Deprecate 'graphql/subscription' and move code to 'execution'

Cito · Cito · commit 1d83cfdc06be · 2021-12-23T12:59:16.000+01:00
Replicates graphql/graphql-js@588d096
diff --git a/.coveragerc b/.coveragerc
@@ -8,6 +8,7 @@ omit =
     */cached_property.py
     */character_classes.py
     */is_iterable.py
+    */subscription/__init__.py
 
 [report]
 exclude_lines =
diff --git a/docs/conf.py b/docs/conf.py
@@ -111,7 +111,6 @@
     'language': ['ast', 'directive_locations', 'location',
                  'source', 'token_kind', 'visitor'],
     'pyutils': ['simple_pub_sub', 'frozen_list', 'path'],
-    'subscription': [],
     'type': ['definition', 'directives', 'schema'],
     'utilities': ['find_breaking_changes', 'type_info'],
     'validation': ['rules', 'validation_context']}
@@ -136,9 +135,9 @@
 EnterLeaveVisitor
 FormattedSourceLocation
 asyncio.events.AbstractEventLoop
+graphql.execution.map_async_iterator.MapAsyncIterator
 graphql.language.lexer.EscapeSequence
 graphql.language.visitor.EnterLeaveVisitor
-graphql.subscription.map_async_iterator.MapAsyncIterator
 graphql.type.schema.InterfaceImplementations
 graphql.validation.validation_context.VariableUsage
 graphql.validation.rules.known_argument_names.KnownArgumentNamesOnDirectivesRule
diff --git a/docs/modules/execution.rst b/docs/modules/execution.rst
@@ -22,6 +22,12 @@ Execution
 .. autoclass:: FormattedExecutionResult
    :no-inherited-members:
 
+.. autofunction:: subscribe
+
+.. autofunction:: create_source_event_stream
+
+.. autoclass:: MapAsyncIterator
+
 .. autoclass:: Middleware
 
 .. autoclass:: MiddlewareManager
diff --git a/docs/modules/graphql.rst b/docs/modules/graphql.rst
@@ -27,7 +27,6 @@ Sub-Packages
    execution
    language
    pyutils
-   subscription
    type
    utilities
    validation
diff --git a/docs/modules/subscription.rst b/docs/modules/subscription.rst
diff --git a/docs/usage/other.rst b/docs/usage/other.rst
@@ -1,13 +1,13 @@
 Subscriptions
 -------------
 
-.. currentmodule:: graphql.subscription
+.. currentmodule:: graphql.execution
 
 Sometimes you need to not only query data from a server, but you also want to push data
 from the server to the client. GraphQL-core 3 has you also covered here, because it
 implements the "Subscribe" algorithm described in the GraphQL spec. To execute a GraphQL
 subscription, you must use the :func:`subscribe` method from the
-:mod:`graphql.subscription` module. Instead of a single
+:mod:`graphql.execution` package. Instead of a single
 :class:`~graphql.execution.ExecutionResult`, this function returns an asynchronous
 iterator yielding a stream of those, unless there was an immediate error.
 Of course you will then also need to maintain a persistent channel to the client
diff --git a/src/graphql/__init__.py b/src/graphql/__init__.py
@@ -34,7 +34,6 @@
   - :mod:`graphql.error`: Creating and formatting GraphQL errors.
   - :mod:`graphql.utilities`:
     Common useful computations upon the GraphQL language and type objects.
-  - :mod:`graphql.subscription`: Subscribe to data updates.
 """
 
 # The GraphQL-core 3 and GraphQL.js version info.
@@ -286,14 +285,15 @@
     ExecutionContext,
     ExecutionResult,
     FormattedExecutionResult,
+    # Subscription
+    subscribe,
+    create_source_event_stream,
+    MapAsyncIterator,
     # Middleware
     Middleware,
     MiddlewareManager,
 )
 
-from .subscription import subscribe, create_source_event_stream, MapAsyncIterator
-
-
 # Validate GraphQL queries.
 from .validation import (
     validate,
diff --git a/src/graphql/execution/__init__.py b/src/graphql/execution/__init__.py
@@ -14,19 +14,22 @@
     FormattedExecutionResult,
     Middleware,
 )
-
+from .map_async_iterator import MapAsyncIterator
+from .subscribe import subscribe, create_source_event_stream
 from .middleware import MiddlewareManager
-
 from .values import get_directive_values
 
 __all__ = [
+    "create_source_event_stream",
     "execute",
     "execute_sync",
     "default_field_resolver",
     "default_type_resolver",
+    "subscribe",
     "ExecutionContext",
     "ExecutionResult",
     "FormattedExecutionResult",
+    "MapAsyncIterator",
     "Middleware",
     "MiddlewareManager",
     "get_directive_values",
diff --git a/src/graphql/execution/map_async_iterator.py b/src/graphql/execution/map_async_iterator.py
diff --git a/src/graphql/execution/subscribe.py b/src/graphql/execution/subscribe.py
diff --git a/src/graphql/subscription/__init__.py b/src/graphql/subscription/__init__.py
@@ -2,9 +2,15 @@
 
 The :mod:`graphql.subscription` package is responsible for subscribing to updates
 on specific data.
+
+.. deprecated:: 3.3
+   This package has been deprecated with its exported functions integrated into the
+   :mod:`graphql.execution` package, to better conform with the terminology of the
+   GraphQL specification. For backwards compatibility, the :mod:`graphql.subscription`
+   package currently re-exports the moved functions from the :mod:`graphql.execution`
+   package. In v3.3, the :mod:`graphql.subscription` package will be dropped entirely.
 """
 
-from .subscribe import subscribe, create_source_event_stream
-from .map_async_iterator import MapAsyncIterator
+from ..execution import subscribe, create_source_event_stream, MapAsyncIterator
 
 __all__ = ["subscribe", "create_source_event_stream", "MapAsyncIterator"]
diff --git a/tests/execution/test_map_async_iterator.py b/tests/execution/test_map_async_iterator.py
@@ -3,7 +3,7 @@
 
 from pytest import mark, raises
 
-from graphql.subscription.map_async_iterator import MapAsyncIterator
+from graphql.execution import MapAsyncIterator
 
 
 try:  # pragma: no cover
diff --git a/tests/execution/test_subscribe.py b/tests/execution/test_subscribe.py
@@ -16,7 +16,7 @@
     GraphQLSchema,
     GraphQLString,
 )
-from graphql.subscription import create_source_event_stream, subscribe, MapAsyncIterator
+from graphql.execution import create_source_event_stream, subscribe, MapAsyncIterator
 
 try:
     anext
diff --git a/tests/subscription/__init__.py b/tests/subscription/__init__.py
diff --git a/tests/test_user_registry.py b/tests/test_user_registry.py
@@ -36,7 +36,7 @@
 )
 
 from graphql.pyutils import SimplePubSub, SimplePubSubIterator
-from graphql.subscription.map_async_iterator import MapAsyncIterator
+from graphql.execution.map_async_iterator import MapAsyncIterator
 
 
 class User(NamedTuple):
diff --git a/tests/utilities/test_extend_schema.py b/tests/utilities/test_extend_schema.py
@@ -139,15 +139,15 @@ def extends_objects_by_adding_new_fields():
             extended_schema,
             dedent(
                 '''
-            type SomeObject implements AnotherInterface & SomeInterface {
-              self: SomeObject
-              tree: [SomeObject]!
-              """Old field description."""
-              oldField: String
-              """New field description."""
-              newField(arg: Boolean): String
-            }
-            '''
+                type SomeObject implements AnotherInterface & SomeInterface {
+                  self: SomeObject
+                  tree: [SomeObject]!
+                  """Old field description."""
+                  oldField: String
+                  """New field description."""
+                  newField(arg: Boolean): String
+                }
+                '''
             ),
         )
 
@@ -226,13 +226,13 @@ def extends_enums_by_adding_new_values():
             extended_schema,
             dedent(
                 '''
-            enum SomeEnum {
-              """Old value description."""
-              OLD_VALUE
-              """New value description."""
-              NEW_VALUE
-            }
-            '''
+                enum SomeEnum {
+                  """Old value description."""
+                  OLD_VALUE
+                  """New value description."""
+                  NEW_VALUE
+                }
+                '''
             ),
         )
 
@@ -263,8 +263,8 @@ def extends_unions_by_adding_new_types():
             extended_schema,
             dedent(
                 """
-            union SomeUnion = Foo | Biz | Bar
-            """
+                union SomeUnion = Foo | Biz | Bar
+                """
             ),
         )
 
@@ -318,13 +318,13 @@ def extends_inputs_by_adding_new_fields():
             extended_schema,
             dedent(
                 '''
-            input SomeInput {
-              """Old field description."""
-              oldField: String
-              """New field description."""
-              newField: String
-            }
-            '''
+                input SomeInput {
+                  """Old field description."""
+                  oldField: String
+                  """New field description."""
+                  newField: String
+                }
+                '''
             ),
         )
 
