Deprecate built-in GraphQL support (#1135)

* Deprecate GraphQLApp

* Add deprecation warning to pytest ignore list

* Tweak deprecation warnings

docs/graphql.md

@@ -1,4 +1,17 @@
 
+!!! Warning
+
+    GraphQL support in Starlette is **deprecated** as of version 0.15 and will
+    be removed in a future release. Please consider using a third-party library
+    to provide GraphQL support. This is usually done by mounting a GraphQL ASGI
+    application. See [#619](https://github.com/encode/starlette/issues/619).
+    Some example libraries are:
+
+    * [Ariadne](https://ariadnegraphql.org/docs/asgi)
+    * [`tartiflette-asgi`](https://tartiflette.github.io/tartiflette-asgi/)
+    * [Strawberry](https://strawberry.rocks/docs/integrations/asgi)
+    * [`starlette-graphene3`](https://github.com/ciscorn/starlette-graphene3)
+
 Starlette includes optional support for GraphQL, using the `graphene` library.
 
 Here's an example of integrating the support into your application.

docs/index.md

@@ -25,7 +25,6 @@ It is production-ready, and gives you the following:
 
 * Seriously impressive performance.
 * WebSocket support.
-* GraphQL support.
 * In-process background tasks.
 * Startup and shutdown events.
 * Test client built on `requests`.
@@ -88,7 +87,6 @@ Starlette does not have any hard dependencies, but the following are optional:
 * [`python-multipart`][python-multipart] - Required if you want to support form parsing, with `request.form()`.
 * [`itsdangerous`][itsdangerous] - Required for `SessionMiddleware` support.
 * [`pyyaml`][pyyaml] - Required for `SchemaGenerator` support.
-* [`graphene`][graphene] - Required for `GraphQLApp` support.
 
 You can install all of these with `pip3 install starlette[full]`.
 

docs/release-notes.md

@@ -1,3 +1,12 @@
+## 0.15.0
+
+Unreleased
+
+### Deprecated
+
+* Built-in GraphQL support via the `GraphQLApp` class has been deprecated and will be removed in a
+  future release. Please see [#619](https://github.com/encode/starlette/issues/619).
+
 ## 0.14.2
 
 February 2, 2021

mkdocs.yml

@@ -36,6 +36,7 @@ markdown_extensions:
   - markdown.extensions.codehilite:
       guess_lang: false
   - mkautodoc
+  - admonition
 
 extra_javascript:
   - 'js/chat.js'

setup.cfg

@@ -29,7 +29,8 @@ filterwarnings=
     error
     # https://github.com/Tinche/aiofiles/issues/81
     ignore: "@coroutine" decorator is deprecated.*:DeprecationWarning
-    # https://github.com/graphql-python/graphene/issues/1055
+    # Deprecated GraphQL (including https://github.com/graphql-python/graphene/issues/1055)
+    ignore: GraphQLApp is deprecated and will be removed in a future release\..*:DeprecationWarning
     ignore: Using or importing the ABCs from 'collections' instead of from 'collections\.abc' is deprecated.*:DeprecationWarning
     ignore: The 'context' alias has been deprecated. Please use 'context_value' instead\.:DeprecationWarning
     ignore: The 'variables' alias has been deprecated. Please use 'variable_values' instead\.:DeprecationWarning

starlette/graphql.py

@@ -1,5 +1,6 @@
 import json
 import typing
+import warnings
 
 from starlette import status
 from starlette.background import BackgroundTasks
@@ -8,6 +9,13 @@
 from starlette.responses import HTMLResponse, JSONResponse, PlainTextResponse, Response
 from starlette.types import Receive, Scope, Send
 
+warnings.warn(
+    "GraphQLApp is deprecated and will be removed in a future release. "
+    "Consider using a third-party GraphQL implementation. "
+    "See https://github.com/encode/starlette/issues/619.",
+    DeprecationWarning,
+)
+
 try:
     import graphene
     from graphql.error import GraphQLError, format_error as format_graphql_error