diff --git a/docs/aiohttp.md b/docs/aiohttp.md index b301855..3c548ca 100644 --- a/docs/aiohttp.md +++ b/docs/aiohttp.md @@ -30,6 +30,17 @@ if __name__ == '__main__': ``` This will add `/graphql` endpoint to your app (customizable by passing `route_path='/mypath'` to `GraphQLView.attach`) and enable the GraphiQL IDE. +> **CORS** +> +> Use [aiohttp_cors](https://github.com/aio-libs/aiohttp-cors) to allow cross origin requests: +> ```python +> import aiohttp_cors +> +> cors = aiohttp_cors.setup(app) +> for route in list(app.router.routes()): +> cors.add(route) +> ``` + Note: `GraphQLView.attach` is just a convenience function, and the same functionality can be achieved with @@ -47,28 +58,16 @@ gql_view(request) # <-- the instance is callable and expects a `aiohttp.web.Req ### Supported options for GraphQLView - * `schema`: The GraphQL schema object that you want the view to execute when it gets a valid request. Accepts either an object of type `GraphQLSchema` from `graphql-core` or `Schema` from `graphene`. For Graphene v3, passing either `schema: graphene.Schema` or `schema.graphql_schema` is allowed. - * `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 **"2.2.0"**. - * `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/). - * `validation_rules`: A list of graphql validation rules. - * `execution_context_class`: Specifies a custom execution context class. - * `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**. +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `keep_alive` +* `keep_alive_interval` +* `debug` +* `subscription_protocols` +* `connection_init_wait_timeout` +* `multipart_uploads_enabled` ## Contributing See [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/asgi.md b/docs/asgi.md new file mode 100644 index 0000000..c1b6599 --- /dev/null +++ b/docs/asgi.md @@ -0,0 +1,68 @@ +# ASGI-GraphQL + +Adds GraphQL support to any ASGI framework. + +## Installation + +Install the ASGI integration with: + +`pip install graphql-server[asgi]` + +## Usage + +Use the `GraphQL` class from `graphql_server.asgi`. + +```python +from starlette.applications import Starlette +from graphql_server.asgi import GraphQL + +from schema import schema + +app = Starlette() + +graphql_app = GraphQL(schema=schema, graphiql=True) +app.mount("/graphql", graphql_app) +``` + +> **CORS** +> +> Add Starlette's `CORSMiddleware` if you need cross-origin requests: +> ```python +> from starlette.middleware.cors import CORSMiddleware +> app.add_middleware( +> CORSMiddleware, +> allow_origins=["*"], +> allow_methods=["*"], +> allow_headers=["*"], +> ) +> ``` + +This mounts `/graphql` in your ASGI app and enables the GraphiQL IDE. + +### Supported options for GraphQL + +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `keep_alive` +* `keep_alive_interval` +* `debug` +* `subscription_protocols` +* `connection_init_wait_timeout` +* `multipart_uploads_enabled` + + +You can also subclass `GraphQL` and overwrite `get_root_value(self, request)` to have a dynamic root value +per request. + +```python +class UserRootValue(GraphQL): + def get_root_value(self, request): + return request.user + +``` + + +## Contributing +See [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/chalice.md b/docs/chalice.md new file mode 100644 index 0000000..b25c898 --- /dev/null +++ b/docs/chalice.md @@ -0,0 +1,63 @@ +# Chalice-GraphQL + +Adds GraphQL support to your AWS Chalice application. + +## Installation + +Install the Chalice integration with: + +`pip install graphql-server[chalice]` + +## Usage + +Use the `GraphQLView` from `graphql_server.chalice`. + +```python +from chalice import Chalice +from graphql_server.chalice import GraphQLView + +from schema import schema + +app = Chalice(app_name="MyApp") + +@app.route("/graphql", methods=["GET", "POST"]) +def graphql_server(): + view = GraphQLView(schema=schema, graphiql=True) + return view.execute_request(app.current_request) +``` + +> **CORS** +> +> To allow CORS, create a `CORSConfig` and pass it when defining the route: +> ```python +> from chalice import CORSConfig +> +> cors_config = CORSConfig(allow_origin="*") +> @app.route("/graphql", methods=["GET", "POST"], cors=cors_config) +> def graphql_server(): +> view = GraphQLView(schema=schema, graphiql=True) +> return view.execute_request(app.current_request) +> ``` + +This adds a `/graphql` route with GraphiQL enabled. + +### Supported options for GraphQLView + +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` + + +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) diff --git a/docs/channels.md b/docs/channels.md new file mode 100644 index 0000000..895e998 --- /dev/null +++ b/docs/channels.md @@ -0,0 +1,51 @@ +# Channels-GraphQL + +Adds GraphQL over HTTP and WebSockets to Django Channels. + +## Installation + +Install with: + +`pip install graphql-server[channels]` + +## Usage + +Use `GraphQLProtocolTypeRouter` from `graphql_server.channels`. + +```python +from channels.routing import ProtocolTypeRouter +from graphql_server.channels import GraphQLProtocolTypeRouter + +from schema import schema + +application = ProtocolTypeRouter( + { + "": GraphQLProtocolTypeRouter(schema, url_pattern=r"^graphql"), + } +) +``` + +> **CORS** +> +> Use [`django-cors-headers`](https://github.com/adamchainz/django-cors-headers) for cross-origin requests. + +### Supported options for GraphQLProtocolTypeRouter + +* `schema` +* `django_application` +* `url_pattern` +* `http_consumer_class` +* `ws_consumer_class` + + +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) diff --git a/docs/django.md b/docs/django.md new file mode 100644 index 0000000..a572ff8 --- /dev/null +++ b/docs/django.md @@ -0,0 +1,49 @@ +# Django-GraphQL + +Adds GraphQL support to your Django project. + +## Installation + +Install the integration with: + +`pip install graphql-server[django]` + +## Usage + +Use the `GraphQLView` from `graphql_server.django`. + +```python +from django.urls import path +from graphql_server.django import GraphQLView + +from schema import schema + +urlpatterns = [ + path("graphql/", GraphQLView.as_view(schema=schema, graphiql=True)), +] +``` + +> **CORS** +> +> Enable CORS with [`django-cors-headers`](https://github.com/adamchainz/django-cors-headers). + +### Supported options for GraphQLView + +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `multipart_uploads_enabled` + + +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) diff --git a/docs/fastapi.md b/docs/fastapi.md new file mode 100644 index 0000000..0be093c --- /dev/null +++ b/docs/fastapi.md @@ -0,0 +1,77 @@ +# FastAPI-GraphQL + +Adds GraphQL support to your FastAPI application. + +## Installation + +Install with: + +`pip install graphql-server[fastapi]` + +## Usage + +Use the `GraphQLRouter` from `graphql_server.fastapi`. + +```python +from fastapi import FastAPI +from graphql_server.fastapi import GraphQLRouter + +from schema import schema + +app = FastAPI() + +graphql_app = GraphQLRouter(schema=schema, graphiql=True) +app.include_router(graphql_app, prefix="/graphql") +``` + +> **CORS** +> +> Use FastAPI's `CORSMiddleware` to enable cross-origin requests: +> ```python +> from fastapi.middleware.cors import CORSMiddleware +> +> app.add_middleware( +> CORSMiddleware, +> allow_origins=["*"], +> allow_methods=["*"], +> allow_headers=["*"], +> ) +> ``` + +### Supported options for GraphQLRouter + +* `schema` +* `path` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `keep_alive` +* `keep_alive_interval` +* `debug` +* `root_value_getter` +* `context_getter` +* `subscription_protocols` +* `connection_init_wait_timeout` +* `multipart_uploads_enabled` + + +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 + +``` + +You can also subclass `GraphQLRouter` and overwrite `get_root_value(self, request)` to have a dynamic root value per request. + +```python +class UserRootValue(GraphQLRouter): + def get_root_value(self, request): + return request.user +``` + +## Contributing +See [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/flask.md b/docs/flask.md index dfe0aa7..47f90bf 100644 --- a/docs/flask.md +++ b/docs/flask.md @@ -38,29 +38,21 @@ if __name__ == '__main__': ``` This will add `/graphql` endpoint to your app and enable the GraphiQL IDE. +> **CORS** +> +> Install [Flask-CORS](https://flask-cors.readthedocs.io/) and initialize it with your app: +> ```python +> from flask_cors import CORS +> CORS(app) +> ``` ### Supported options for GraphQLView - * `schema`: The GraphQL schema object that you want the view to execute when it gets a valid request. Accepts either an object of type `GraphQLSchema` from `graphql-core` or `Schema` from `graphene`. For Graphene v3, passing either `schema: graphene.Schema` or `schema.graphql_schema` is allowed. - * `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 **"2.2.0"**. - * `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 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/). - * `validation_rules`: A list of graphql validation rules. - * `execution_context_class`: Specifies a custom execution context class. - * `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**. +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `multipart_uploads_enabled` You can also subclass `GraphQLView` and overwrite `get_root_value(self, request)` to have a dynamic root value diff --git a/docs/litestar.md b/docs/litestar.md new file mode 100644 index 0000000..8cfe3ff --- /dev/null +++ b/docs/litestar.md @@ -0,0 +1,73 @@ +# Litestar-GraphQL + +Adds GraphQL support to your Litestar application. + +## Installation + +Install with: + +`pip install graphql-server[litestar]` + +## Usage + +Use `make_graphql_controller` from `graphql_server.litestar`. + +```python +from litestar import Litestar +from graphql_server.litestar import make_graphql_controller + +from schema import schema + +GraphQLController = make_graphql_controller(schema, path="/graphql") + +app = Litestar(route_handlers=[GraphQLController]) +``` + +> **CORS** +> +> To enable CORS you can pass a `CORSConfig` to `Litestar`: +> ```python +> from litestar.config.cors import CORSConfig +> +> cors_config = CORSConfig(allow_origins=["*"]) +> app = Litestar(route_handlers=[GraphQLController], cors_config=cors_config) +> ``` + +### Supported options for GraphQLController + +* `schema` +* `path` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `keep_alive` +* `keep_alive_interval` +* `debug` +* `root_value_getter` +* `context_getter` +* `subscription_protocols` +* `connection_init_wait_timeout` +* `multipart_uploads_enabled` + + +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 + +``` + +You can also subclass `GraphQLController` and overwrite `get_root_value(self, request)` to have a dynamic root value per request. + +```python +class UserRootValue(GraphQLController): + def get_root_value(self, request): + return request.user +``` + + +## Contributing +See [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/docs/quart.md b/docs/quart.md new file mode 100644 index 0000000..fea8c49 --- /dev/null +++ b/docs/quart.md @@ -0,0 +1,62 @@ +# Quart-GraphQL + +Adds GraphQL support to your Quart application. + +## Installation + +Install with: + +`pip install graphql-server[quart]` + +## Usage + +Use the `GraphQLView` from `graphql_server.quart`. + +```python +from quart import Quart +from graphql_server.quart import GraphQLView + +from schema import schema + +app = Quart(__name__) + +app.add_url_rule( + "/graphql", + view_func=GraphQLView.as_view(schema=schema, graphiql=True), +) +``` + +> **CORS** +> +> Use [quart_cors](https://github.com/corydolphin/quart-cors) to enable CORS: +> ```python +> from quart_cors import cors +> +> app = cors(app, allow_origin="*") +> ``` + +### Supported options for GraphQLView + +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `keep_alive` +* `keep_alive_interval` +* `debug` +* `subscription_protocols` +* `connection_init_wait_timeout` +* `multipart_uploads_enabled` + + +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) diff --git a/docs/sanic.md b/docs/sanic.md index 102e38d..fb312c9 100644 --- a/docs/sanic.md +++ b/docs/sanic.md @@ -36,31 +36,23 @@ if __name__ == '__main__': ``` This will add `/graphql` endpoint to your app and enable the GraphiQL IDE. +> **CORS** +> +> Install [sanic-cors](https://github.com/ashleysommer/sanic-cors) and initialize it with your app: +> ```python +> from sanic_cors import CORS +> CORS(app) +> ``` ### Supported options for GraphQLView - * `schema`: The GraphQL schema object that you want the view to execute when it gets a valid request. Accepts either an object of type `GraphQLSchema` from `graphql-core` or `Schema` from `graphene`. For Graphene v3, passing either `schema: graphene.Schema` or `schema.graphql_schema` is allowed. - * `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 **"2.2.0"**. - * `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/). - * `validation_rules`: A list of graphql validation rules. - * `execution_context_class`: Specifies a custom execution context class. - * `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**. +* `schema` +* `graphiql` +* `graphql_ide` +* `allow_queries_via_get` +* `json_encoder` +* `json_dumps_params` +* `multipart_uploads_enabled` You can also subclass `GraphQLView` and overwrite `get_root_value(self, request)` to have a dynamic root value per request. diff --git a/docs/webob.md b/docs/webob.md index 2f88a31..55902fa 100644 --- a/docs/webob.md +++ b/docs/webob.md @@ -35,30 +35,21 @@ if __name__ == '__main__': ``` This will add `/graphql` endpoint to your app and enable the GraphiQL IDE. +### Enabling CORS +> **CORS** +> +> Include [pyramid-cors](https://github.com/Kinto/pyramid-cors) in your Pyramid configuration: +> ```python +> config.include("pyramid_cors") +> ``` -### Supported options for GraphQLView - * `schema`: The GraphQL schema object that you want the view to execute when it gets a valid request. Accepts either an object of type `GraphQLSchema` from `graphql-core` or `Schema` from `graphene`. For Graphene v3, passing either `schema: graphene.Schema` or `schema.graphql_schema` is allowed. - * `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 **"2.2.0"**. - * `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 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/). - * `validation_rules`: A list of graphql validation rules. - * `execution_context_class`: Specifies a custom execution context class. - * `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**. +### Supported options for GraphQLView +* `schema` +* `graphiql` +* `graphql_ide` +* `multipart_uploads_enabled` +* `allow_queries_via_get` ## Contributing See [CONTRIBUTING.md](../CONTRIBUTING.md)