Skip to content

Commit e0fcd01

Browse files
CitoProjectCheshire
Cito
authored and
ProjectCheshire
committed
Improve README and add docstrings (#21)
Separate between official and internal helper functions. Only the official functions are listed in __all__, and the internal ones are moved to the bottom of the file. Also, added a script to create docs from the docstrings. Add Python 3.6 and 3.7 as supported Python versions.
1 parent cfe21f2 commit e0fcd01

12 files changed

+279
-124
lines changed

‎.gitignore

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
*.pyc
2-
.idea
3-
.cache
4-
.tox
2+
*.pyo
3+
54
*.egg
65
*.egg-info
6+
7+
.cache
78
.coverage
8-
/build/
9+
.idea
10+
.mypy_cache
11+
.pytest_cache
12+
.tox
13+
.venv
914

15+
/build/
1016
/dist/
11-
/.mypy_cache
12-
/.pytest_cache

‎.travis.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@ matrix:
1111
- python: '3.5'
1212
env: TOX_ENV=py35
1313
- python: '3.6'
14-
env: TOX_ENV=py36,import-order,flake8,mypy
14+
env: TOX_ENV=py36
15+
- python: '3.7'
16+
env: TOX_ENV=py37,import-order,flake8,mypy
17+
dist: xenial
1518
cache:
1619
directories:
1720
- $HOME/.cache/pip

‎README.md

Lines changed: 34 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,40 @@
1-
# GraphQL-Server
1+
# GraphQL-Server-Core
22

33
[![Build Status](https://travis-ci.org/graphql-python/graphql-server-core.svg?branch=master)](https://travis-ci.org/graphql-python/graphql-server-core) [![Coverage Status](https://coveralls.io/repos/graphql-python/graphql-server-core/badge.svg?branch=master&service=github)](https://coveralls.io/github/graphql-python/graphql-server-core?branch=master) [![PyPI version](https://badge.fury.io/py/graphql-server-core.svg)](https://badge.fury.io/py/graphql-server-core)
44

5-
GraphQL Server core package.
5+
GraphQL-Server-Core is a base library that serves as a helper
6+
for building GraphQL servers or integrations into existing web frameworks using
7+
[GraphQL-Core](https://github.com/graphql-python/graphql-core).
68

7-
## Integrations
9+
## Existing integrations built with GraphQL-Server-Core
810

9-
GraphQL Server powers the following integrations
11+
| Server integration | Package |
12+
|---|---|
13+
| Flask | [flask-graphql](https://github.com/graphql-python/flask-graphql/) |
14+
| Sanic |[sanic-graphql](https://github.com/graphql-python/sanic-graphql/) |
15+
| AIOHTTP | [aiohttp-graphql](https://github.com/graphql-python/aiohttp-graphql) |
16+
| WebOb (Pyramid, TurboGears) | [webob-graphql](https://github.com/graphql-python/webob-graphql/) |
17+
| WSGI | [wsgi-graphql](https://github.com/moritzmhmk/wsgi-graphql) |
18+
| Responder | [responder.ext.graphql](https://github.com/kennethreitz/responder/blob/master/responder/ext/graphql.py) |
1019

11-
| Server integration | Package |
12-
|---------------|-------------------|
13-
| Django | [graphene-django](https://github.com/graphql-python/graphene-django/) |
14-
| Flask | [flask-graphql](https://github.com/graphql-python/flask-graphql/) |
15-
| Sanic | [sanic-graphql](https://github.com/graphql-python/sanic-graphql/) |
16-
| WebOb (Pyramid, Pylons) | [webob-graphql](https://github.com/graphql-python/webob-graphql/) |
20+
## Other integrations using GraphQL-Core or Graphene
21+
22+
| Server integration | Package |
23+
|---|---|
24+
| Django | [graphene-django](https://github.com/graphql-python/graphene-django/) |
25+
26+
## Documentation
27+
28+
The `graphql_server` package provides these three public helper functions:
29+
30+
* `run_http_query`
31+
* `encode_execution_results`
32+
* `laod_json_body`
33+
34+
All functions in the package are annotated with type hints and docstrings,
35+
and you can build HTML documentation from these using `bin/build_docs`.
36+
37+
You can also use one of the existing integrations listed above as
38+
blueprint to build your own integration or GraphQL server implementations.
39+
40+
Please let us know when you have built something new, so we can list it here.

‎README.rst

Lines changed: 46 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,55 @@
1-
GraphQL-Server
2-
==============
1+
GraphQL-Server-Core
2+
===================
33

44
|Build Status| |Coverage Status| |PyPI version|
55

6-
GraphQL Server core package.
6+
GraphQL-Server-Core is a base library that serves as a helper for
7+
building GraphQL servers or integrations into existing web frameworks
8+
using `GraphQL-Core <https://github.com/graphql-python/graphql-core>`__.
79

8-
Integrations
9-
------------
10+
Existing integrations built with GraphQL-Server-Core
11+
----------------------------------------------------
1012

11-
GraphQL Server powers the following integrations
13+
=========================== ==========================================================================================================
14+
Server integration Package
15+
=========================== ==========================================================================================================
16+
Flask `flask-graphql <https://github.com/graphql-python/flask-graphql/>`__
17+
Sanic `sanic-graphql <https://github.com/graphql-python/sanic-graphql/>`__
18+
AIOHTTP `aiohttp-graphql <https://github.com/graphql-python/aiohttp-graphql>`__
19+
WebOb (Pyramid, TurboGears) `webob-graphql <https://github.com/graphql-python/webob-graphql/>`__
20+
WSGI `wsgi-graphql <https://github.com/moritzmhmk/wsgi-graphql>`__
21+
Responder `responder.ext.graphql <https://github.com/kennethreitz/responder/blob/master/responder/ext/graphql.py>`__
22+
=========================== ==========================================================================================================
1223

13-
+---------------------------+----------------------------------------------------------------------------+
14-
| Server integration | Package |
15-
+===========================+============================================================================+
16-
| Django | `graphene-django <https://github.com/graphql-python/graphene-django/>`__ |
17-
+---------------------------+----------------------------------------------------------------------------+
18-
| Flask | `flask-graphql <https://github.com/graphql-python/flask-graphql/>`__ |
19-
+---------------------------+----------------------------------------------------------------------------+
20-
| Sanic | `sanic-graphql <https://github.com/graphql-python/sanic-graphql/>`__ |
21-
+---------------------------+----------------------------------------------------------------------------+
22-
| WebOb (Pyramid, Pylons) | `webob-graphql <https://github.com/graphql-python/webob-graphql/>`__ |
23-
+---------------------------+----------------------------------------------------------------------------+
24+
Other integrations using GraphQL-Core or Graphene
25+
-------------------------------------------------
26+
27+
================== ========================================================================
28+
Server integration Package
29+
================== ========================================================================
30+
Django `graphene-django <https://github.com/graphql-python/graphene-django/>`__
31+
================== ========================================================================
32+
33+
Documentation
34+
-------------
35+
36+
The ``graphql_server`` package provides these three public helper
37+
functions:
38+
39+
- ``run_http_query``
40+
- ``encode_execution_results``
41+
- ``laod_json_body``
42+
43+
All functions in the package are annotated with type hints and
44+
docstrings, and you can build HTML documentation from these using
45+
``bin/build_docs``.
46+
47+
You can also use one of the existing integrations listed above as
48+
blueprint to build your own integration or GraphQL server
49+
implementations.
50+
51+
Please let us know when you have built something new, so we can list it
52+
here.
2453

2554
.. |Build Status| image:: https://travis-ci.org/graphql-python/graphql-server-core.svg?branch=master
2655
:target: https://travis-ci.org/graphql-python/graphql-server-core

‎bin/build_docs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/bash
2+
3+
# the documentation can be created from the docstrings
4+
# with pdoc (https://pdoc3.github.io/pdoc/)
5+
6+
pdoc --html --overwrite --html-dir docs graphql_server

‎bin/convert_documentation

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎bin/convert_readme

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/bash
2+
3+
# the README can be converted from MarkDown to reST
4+
# with pandoc (https://pandoc.org/)
5+
6+
pandoc README.md --from markdown --to rst -s -o README.rst

0 commit comments

Comments
 (0)