Docs about integration with each framework (#54)

Co-authored-by: Jonathan Kim <[email protected]>

Author: KingDarBoja

MANIFEST.in

@@ -7,6 +7,8 @@ include CONTRIBUTING.md
 include codecov.yml
 include tox.ini
 
+recursive-include docs *.md
+
 graft tests
 prune bin
 

README.md

@@ -1,21 +1,25 @@
-# GraphQL-Server-Core
+# GraphQL-Server
 
 [![PyPI version](https://badge.fury.io/py/graphql-server-core.svg)](https://badge.fury.io/py/graphql-server-core)
 [![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://codecov.io/gh/graphql-python/graphql-server-core/branch/master/graph/badge.svg)](https://codecov.io/gh/graphql-python/graphql-server-core)
 
-GraphQL-Server-Core is a base library that serves as a helper
+GraphQL-Server is a base library that serves as a helper
 for building GraphQL servers or integrations into existing web frameworks using
 [GraphQL-Core](https://github.com/graphql-python/graphql-core).
 
-## Existing integrations built with GraphQL-Server-Core
+## Integrations built with GraphQL-Server
 
-| Server integration | Package |
+| Server integration | Docs |
 |---|---|
-| Flask | [flask-graphql](https://github.com/graphql-python/flask-graphql/) |
-| Sanic |[sanic-graphql](https://github.com/graphql-python/sanic-graphql/) |
-| AIOHTTP | [aiohttp-graphql](https://github.com/graphql-python/aiohttp-graphql) |
-| WebOb (Pyramid, TurboGears) |  [webob-graphql](https://github.com/graphql-python/webob-graphql/) |
+| Flask | [flask](docs/flask.md) |
+| Sanic |[sanic](docs/sanic.md) |
+| AIOHTTP | [aiohttp](docs/aiohttp.md) |
+| WebOb (Pyramid, TurboGears) | [webob](docs/webob.md) |
+
+## Other integrations built with GraphQL-Server
+
+| Server integration | Package |
 | WSGI | [wsgi-graphql](https://github.com/moritzmhmk/wsgi-graphql) |
 | Responder | [responder.ext.graphql](https://github.com/kennethreitz/responder/blob/master/responder/ext/graphql.py) |
 

docs/aiohttp.md

@@ -0,0 +1,73 @@
+# aiohttp-Graphql
+
+Adds GraphQL support to your aiohttp application.
+
+## Installation
+
+To install the integration with aiohttp, run the below command on your terminal.
+
+`pip install graphql-server-core[aiohttp]`
+
+## Usage
+
+Use the `GraphQLView` view from `graphql_server.aiohttp`
+
+```python
+from aiohttp import web
+from graphql_server.aiohttp import GraphQLView
+
+from schema import schema
+
+app = web.Application()
+
+GraphQLView.attach(app, schema=schema, graphiql=True)
+
+# Optional, for adding batch query support (used in Apollo-Client)
+GraphQLView.attach(app, schema=schema, batch=True, route_path="/graphql/batch")
+
+if __name__ == '__main__':
+    web.run_app(app)
+```
+
+This will add `/graphql` endpoint to your app (customizable by passing `route_path='/mypath'` to `GraphQLView.attach`) and enable the GraphiQL IDE.
+
+Note: `GraphQLView.attach` is just a convenience function, and the same functionality can be achieved with
+
+```python
+gql_view = GraphQLView(schema=schema, graphiql=True)
+app.router.add_route('*', '/graphql', gql_view, name='graphql')
+```
+
+It's worth noting that the the "view function" of `GraphQLView` is contained in `GraphQLView.__call__`. So, when you create an instance, that instance is callable with the request object as the sole positional argument. To illustrate:
+
+```python
+gql_view = GraphQLView(schema=Schema, **kwargs)
+gql_view(request)  # <-- the instance is callable and expects a `aiohttp.web.Request` object.
+```
+
+### Supported options for GraphQLView
+
+ * `schema`: The `GraphQLSchema` object that you want the view to execute when it gets a valid request.
+ * `context`: A value to pass as the `context_value` to graphql `execute` function. By default is set to `dict` with request object at key `request`.
+ * `root_value`: The `root_value` you want to provide to graphql `execute`.
+ * `pretty`: Whether or not you want the response to be pretty printed JSON.
+ * `graphiql`: If `True`, may present [GraphiQL](https://github.com/graphql/graphiql) when loaded directly from a browser (a useful tool for debugging and exploration).
+ * `graphiql_version`: The graphiql version to load. Defaults to **"1.0.3"**.
+ * `graphiql_template`: Inject a Jinja template string to customize GraphiQL.
+ * `graphiql_html_title`: The graphiql title to display. Defaults to **"GraphiQL"**.
+ * `jinja_env`: Sets jinja environment to be used to process GraphiQL template. If Jinja’s async mode is enabled (by `enable_async=True`), uses 
+`Template.render_async` instead of `Template.render`. If environment is not set, fallbacks to simple regex-based renderer.
+ * `batch`: Set the GraphQL view as batch (for using in [Apollo-Client](http://dev.apollodata.com/core/network.html#query-batching) or [ReactRelayNetworkLayer](https://github.com/nodkz/react-relay-network-layer))
+ * `middleware`: A list of graphql [middlewares](http://docs.graphene-python.org/en/latest/execution/middleware/).
+ * `max_age`: Sets the response header Access-Control-Max-Age for preflight requests.
+ * `encode`: the encoder to use for responses (sensibly defaults to `graphql_server.json_encode`).
+ * `format_error`: the error formatter to use for responses (sensibly defaults to `graphql_server.default_format_error`.
+ * `enable_async`: whether `async` mode will be enabled.
+ * `subscriptions`: The GraphiQL socket endpoint for using subscriptions in graphql-ws.
+ * `headers`: An optional GraphQL string to use as the initial displayed request headers, if not provided, the stored headers will be used.
+ * `default_query`: An optional GraphQL string to use when no query is provided and no stored query exists from a previous session. If not provided, GraphiQL will use its own default query.
+* `header_editor_enabled`: An optional boolean which enables the header editor when true. Defaults to **false**.
+* `should_persist_headers`:  An optional boolean which enables to persist headers to storage when true. Defaults to **false**.
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md)

docs/flask.md

@@ -0,0 +1,81 @@
+# Flask-GraphQL
+
+Adds GraphQL support to your Flask application.
+
+## Installation
+
+To install the integration with Flask, run the below command on your terminal.
+
+`pip install graphql-server-core[flask]`
+
+## Usage
+
+Use the `GraphQLView` view from `graphql_server.flask`.
+
+```python
+from flask import Flask
+from graphql_server.flask import GraphQLView
+
+from schema import schema
+
+app = Flask(__name__)
+
+app.add_url_rule('/graphql', view_func=GraphQLView.as_view(
+    'graphql',
+    schema=schema,
+    graphiql=True,
+))
+
+# Optional, for adding batch query support (used in Apollo-Client)
+app.add_url_rule('/graphql/batch', view_func=GraphQLView.as_view(
+    'graphql',
+    schema=schema,
+    batch=True
+))
+
+if __name__ == '__main__':
+    app.run()
+```
+
+This will add `/graphql` endpoint to your app and enable the GraphiQL IDE.
+
+### Special Note for Graphene v3
+
+If you are using the `Schema` type of [Graphene](https://github.com/graphql-python/graphene) library, be sure to use the `graphql_schema` attribute to pass as schema on the `GraphQLView` view. Otherwise, the `GraphQLSchema` from `graphql-core` is the way to go.
+
+More info at [Graphene v3 release notes](https://github.com/graphql-python/graphene/wiki/v3-release-notes#graphene-schema-no-longer-subclasses-graphqlschema-type) and [GraphQL-core 3 usage](https://github.com/graphql-python/graphql-core#usage).
+
+
+### Supported options for GraphQLView
+
+ * `schema`: The `GraphQLSchema` object that you want the view to execute when it gets a valid request.
+ * `context`: A value to pass as the `context_value` to graphql `execute` function. By default is set to `dict` with request object at key `request`.
+ * `root_value`: The `root_value` you want to provide to graphql `execute`.
+ * `pretty`: Whether or not you want the response to be pretty printed JSON.
+ * `graphiql`: If `True`, may present [GraphiQL](https://github.com/graphql/graphiql) when loaded directly from a browser (a useful tool for debugging and exploration).
+ * `graphiql_version`: The graphiql version to load. Defaults to **"1.0.3"**.
+ * `graphiql_template`: Inject a Jinja template string to customize GraphiQL.
+ * `graphiql_html_title`: The graphiql title to display. Defaults to **"GraphiQL"**.
+ * `batch`: Set the GraphQL view as batch (for using in [Apollo-Client](http://dev.apollodata.com/core/network.html#query-batching) or [ReactRelayNetworkLayer](https://github.com/nodkz/react-relay-network-layer))
+ * `middleware`: A list of graphql [middlewares](http://docs.graphene-python.org/en/latest/execution/middleware/).
+ * `encode`: the encoder to use for responses (sensibly defaults to `graphql_server.json_encode`).
+ * `format_error`: the error formatter to use for responses (sensibly defaults to `graphql_server.default_format_error`.
+ * `subscriptions`: The GraphiQL socket endpoint for using subscriptions in graphql-ws.
+ * `headers`: An optional GraphQL string to use as the initial displayed request headers, if not provided, the stored headers will be used.
+ * `default_query`: An optional GraphQL string to use when no query is provided and no stored query exists from a previous session. If not provided, GraphiQL will use its own default query.
+* `header_editor_enabled`: An optional boolean which enables the header editor when true. Defaults to **false**.
+* `should_persist_headers`:  An optional boolean which enables to persist headers to storage when true. Defaults to **false**.
+
+
+You can also subclass `GraphQLView` and overwrite `get_root_value(self, request)` to have a dynamic root value
+per request.
+
+```python
+class UserRootValue(GraphQLView):
+    def get_root_value(self, request):
+        return request.user
+
+```
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md)

docs/sanic.md

@@ -0,0 +1,74 @@
+# Sanic-GraphQL
+
+Adds GraphQL support to your Sanic application.
+
+## Installation
+
+To install the integration with Sanic, run the below command on your terminal.
+
+`pip install graphql-server-core[sanic]`
+
+## Usage
+
+Use the `GraphQLView` view from `graphql_server.sanic`
+
+```python
+from graphql_server.sanic import GraphQLView
+from sanic import Sanic
+
+from schema import schema
+
+app = Sanic(name="Sanic Graphql App")
+
+app.add_route(
+    GraphQLView.as_view(schema=schema, graphiql=True),
+    '/graphql'
+)
+
+# Optional, for adding batch query support (used in Apollo-Client)
+app.add_route(
+    GraphQLView.as_view(schema=schema, batch=True),
+    '/graphql/batch'
+)
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=8000)
+```
+
+This will add `/graphql` endpoint to your app and enable the GraphiQL IDE.
+
+### Supported options for GraphQLView
+
+ * `schema`: The `GraphQLSchema` object that you want the view to execute when it gets a valid request.
+ * `context`: A value to pass as the `context_value` to graphql `execute` function. By default is set to `dict` with request object at key `request`.
+ * `root_value`: The `root_value` you want to provide to graphql `execute`.
+ * `pretty`: Whether or not you want the response to be pretty printed JSON.
+ * `graphiql`: If `True`, may present [GraphiQL](https://github.com/graphql/graphiql) when loaded directly from a browser (a useful tool for debugging and exploration).
+ * `graphiql_version`: The graphiql version to load. Defaults to **"1.0.3"**.
+ * `graphiql_template`: Inject a Jinja template string to customize GraphiQL.
+ * `graphiql_html_title`: The graphiql title to display. Defaults to **"GraphiQL"**.
+ * `jinja_env`: Sets jinja environment to be used to process GraphiQL template. If Jinja’s async mode is enabled (by `enable_async=True`), uses 
+`Template.render_async` instead of `Template.render`. If environment is not set, fallbacks to simple regex-based renderer.
+ * `batch`: Set the GraphQL view as batch (for using in [Apollo-Client](http://dev.apollodata.com/core/network.html#query-batching) or [ReactRelayNetworkLayer](https://github.com/nodkz/react-relay-network-layer))
+ * `middleware`: A list of graphql [middlewares](http://docs.graphene-python.org/en/latest/execution/middleware/).
+ * `max_age`: Sets the response header Access-Control-Max-Age for preflight requests.
+ * `encode`: the encoder to use for responses (sensibly defaults to `graphql_server.json_encode`).
+ * `format_error`: the error formatter to use for responses (sensibly defaults to `graphql_server.default_format_error`.
+ * `enable_async`: whether `async` mode will be enabled.
+ * `subscriptions`: The GraphiQL socket endpoint for using subscriptions in graphql-ws.
+ * `headers`: An optional GraphQL string to use as the initial displayed request headers, if not provided, the stored headers will be used.
+ * `default_query`: An optional GraphQL string to use when no query is provided and no stored query exists from a previous session. If not provided, GraphiQL will use its own default query.
+* `header_editor_enabled`: An optional boolean which enables the header editor when true. Defaults to **false**.
+* `should_persist_headers`:  An optional boolean which enables to persist headers to storage when true. Defaults to **false**.
+
+
+You can also subclass `GraphQLView` and overwrite `get_root_value(self, request)` to have a dynamic root value per request.
+
+```python
+class UserRootValue(GraphQLView):
+    def get_root_value(self, request):
+        return request.user
+```
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md)

docs/webob.md

@@ -0,0 +1,61 @@
+# WebOb-GraphQL
+
+Adds GraphQL support to your WebOb (Pyramid, Pylons, ...) application.
+
+## Installation
+
+To install the integration with WebOb, run the below command on your terminal.
+
+`pip install graphql-server-core[webob]`
+
+## Usage
+
+Use the `GraphQLView` view from `graphql_server.webob`
+
+### Pyramid
+
+```python
+from wsgiref.simple_server import make_server
+from pyramid.config import Configurator
+
+from graphql_server.webob import GraphQLView
+
+from schema import schema
+
+def graphql_view(request):
+    return GraphQLView(request=request, schema=schema, graphiql=True).dispatch_request(request)
+
+if __name__ == '__main__':
+    with Configurator() as config:
+        config.add_route('graphql', '/graphql')
+        config.add_view(graphql_view, route_name='graphql')
+        app = config.make_wsgi_app()
+    server = make_server('0.0.0.0', 6543, app)
+    server.serve_forever()
+```
+
+This will add `/graphql` endpoint to your app and enable the GraphiQL IDE.
+
+### Supported options for GraphQLView
+
+ * `schema`: The `GraphQLSchema` object that you want the view to execute when it gets a valid request.
+ * `context`: A value to pass as the `context_value` to graphql `execute` function. By default is set to `dict` with request object at key `request`.
+ * `root_value`: The `root_value` you want to provide to graphql `execute`.
+ * `pretty`: Whether or not you want the response to be pretty printed JSON.
+ * `graphiql`: If `True`, may present [GraphiQL](https://github.com/graphql/graphiql) when loaded directly from a browser (a useful tool for debugging and exploration).
+ * `graphiql_version`: The graphiql version to load. Defaults to **"1.0.3"**.
+ * `graphiql_template`: Inject a Jinja template string to customize GraphiQL.
+ * `graphiql_html_title`: The graphiql title to display. Defaults to **"GraphiQL"**.
+ * `batch`: Set the GraphQL view as batch (for using in [Apollo-Client](http://dev.apollodata.com/core/network.html#query-batching) or [ReactRelayNetworkLayer](https://github.com/nodkz/react-relay-network-layer))
+ * `middleware`: A list of graphql [middlewares](http://docs.graphene-python.org/en/latest/execution/middleware/).
+ * `encode`: the encoder to use for responses (sensibly defaults to `graphql_server.json_encode`).
+ * `format_error`: the error formatter to use for responses (sensibly defaults to `graphql_server.default_format_error`.
+ * `enable_async`: whether `async` mode will be enabled.
+ * `subscriptions`: The GraphiQL socket endpoint for using subscriptions in graphql-ws.
+ * `headers`: An optional GraphQL string to use as the initial displayed request headers, if not provided, the stored headers will be used.
+ * `default_query`: An optional GraphQL string to use when no query is provided and no stored query exists from a previous session. If not provided, GraphiQL will use its own default query.
+* `header_editor_enabled`: An optional boolean which enables the header editor when true. Defaults to **false**.
+* `should_persist_headers`:  An optional boolean which enables to persist headers to storage when true. Defaults to **false**.
+
+## Contributing
+See [CONTRIBUTING.md](../CONTRIBUTING.md)

graphql_server/flask/graphqlview.py

@@ -37,6 +37,9 @@ class GraphQLView(View):
 
     methods = ["GET", "POST", "PUT", "DELETE"]
 
+    format_error = staticmethod(format_error_default)
+    encode = staticmethod(json_encode)
+
     def __init__(self, **kwargs):
         super(GraphQLView, self).__init__()
         for key, value in kwargs.items():
@@ -57,9 +60,6 @@ def get_context_value(self):
     def get_middleware(self):
         return self.middleware
 
-    format_error = staticmethod(format_error_default)
-    encode = staticmethod(json_encode)
-
     def dispatch_request(self):
         try:
             request_method = request.method.lower()

graphql_server/sanic/graphqlview.py

@@ -44,6 +44,9 @@ class GraphQLView(HTTPMethodView):
 
     methods = ["GET", "POST", "PUT", "DELETE"]
 
+    format_error = staticmethod(format_error_default)
+    encode = staticmethod(json_encode)
+
     def __init__(self, **kwargs):
         super(GraphQLView, self).__init__()
         for key, value in kwargs.items():
@@ -70,9 +73,6 @@ def get_context(self, request):
     def get_middleware(self):
         return self.middleware
 
-    format_error = staticmethod(format_error_default)
-    encode = staticmethod(json_encode)
-
     async def dispatch_request(self, request, *args, **kwargs):
         try:
             request_method = request.method.lower()

graphql_server/webob/graphqlview.py

@@ -40,6 +40,9 @@ class GraphQLView:
     headers = None
     charset = "UTF-8"
 
+    format_error = staticmethod(format_error_default)
+    encode = staticmethod(json_encode)
+
     def __init__(self, **kwargs):
         super(GraphQLView, self).__init__()
         for key, value in kwargs.items():
@@ -66,9 +69,6 @@ def get_context(self, request):
     def get_middleware(self):
         return self.middleware
 
-    format_error = staticmethod(format_error_default)
-    encode = staticmethod(json_encode)
-
     def dispatch_request(self, request):
         try:
             request_method = request.method.lower()