Support using lazy descriptions for GraphQL types (#58)

You can now register additional classes that will be accepted as descriptions.

Author: Cito

README.md

@@ -16,7 +16,7 @@ The current version 3.0.0a2 of GraphQL-core is up-to-date
 with GraphQL.js version 14.4.2.
 
 All parts of the API are covered by an extensive test suite
-of currently 1966 unit tests.
+of currently 1979 unit tests.
 
 
 ## Documentation

docs/modules/pyutils.rst

@@ -10,6 +10,8 @@ PyUtils
 .. autofunction:: cached_property
 .. autofunction:: dedent
 .. autofunction:: did_you_mean
+.. autofunction:: register_description
+.. autofunction:: unregister_description
 .. autoclass:: EventEmitter
    :members:
 .. autoclass:: EventEmitterAsyncIterator

src/graphql/pyutils/__init__.py

@@ -11,6 +11,12 @@
 from .convert_case import camel_to_snake, snake_to_camel
 from .cached_property import cached_property
 from .dedent import dedent
+from .description import (
+    Description,
+    is_description,
+    register_description,
+    unregister_description,
+)
 from .did_you_mean import did_you_mean
 from .event_emitter import EventEmitter, EventEmitterAsyncIterator
 from .identity_func import identity_func
@@ -33,6 +39,10 @@
     "cached_property",
     "dedent",
     "did_you_mean",
+    "Description",
+    "is_description",
+    "register_description",
+    "unregister_description",
     "EventEmitter",
     "EventEmitterAsyncIterator",
     "identity_func",

src/graphql/pyutils/description.py

@@ -0,0 +1,60 @@
+from typing import Any, Tuple, Union
+
+__all__ = [
+    "Description",
+    "is_description",
+    "register_description",
+    "unregister_description",
+]
+
+
+class Description:
+    """Type checker for human readable descriptions.
+
+    By default, only ordinary strings are accepted as descriptions,
+    but you can register() other classes that will also be allowed,
+    e.g. to support lazy string objects that are evaluated only at runtime.
+    If you register(object), any object will be allowed as description.
+    """
+
+    bases: Union[type, Tuple[type, ...]] = str
+
+    @classmethod
+    def isinstance(cls, obj: Any) -> bool:
+        return isinstance(obj, cls.bases)
+
+    @classmethod
+    def register(cls, base: type) -> None:
+        """Register a class that shall be accepted as a description."""
+        if not isinstance(base, type):
+            raise TypeError("Only types can be registered.")
+        if base is object:
+            cls.bases = object
+        elif cls.bases is object:
+            if base is not object:
+                cls.bases = base
+        elif not isinstance(cls.bases, tuple):
+            if base is not cls.bases:
+                cls.bases = (cls.bases, base)
+        elif base not in cls.bases:
+            cls.bases += (base,)
+
+    @classmethod
+    def unregister(cls, base: type) -> None:
+        """Unregister a class that shall no more be accepted as a description."""
+        if not isinstance(base, type):
+            raise TypeError("Only types can be unregistered.")
+        if isinstance(cls.bases, tuple):
+            if base in cls.bases:
+                cls.bases = tuple(b for b in cls.bases if b is not base)
+            if not cls.bases:
+                cls.bases = object
+            elif len(cls.bases) == 1:
+                cls.bases = cls.bases[0]
+        elif cls.bases is base:
+            cls.bases = object
+
+
+is_description = Description.isinstance
+register_description = Description.register
+unregister_description = Description.unregister

src/graphql/type/definition.py

@@ -42,7 +42,14 @@
     UnionTypeExtensionNode,
     ValueNode,
 )
-from ..pyutils import AwaitableOrValue, FrozenList, Path, cached_property, inspect
+from ..pyutils import (
+    AwaitableOrValue,
+    FrozenList,
+    Path,
+    cached_property,
+    inspect,
+    is_description,
+)
 from ..utilities.value_from_ast_untyped import value_from_ast_untyped
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -199,7 +206,7 @@ def __init__(
             raise TypeError("Must provide name.")
         if not isinstance(name, str):
             raise TypeError("The name must be a string.")
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError("The description must be a string.")
         if extensions is not None and (
             not isinstance(extensions, dict)
@@ -471,9 +478,9 @@ def __init__(
                 "Field resolver must be a function if provided, "
                 f" but got: {inspect(resolve)}."
             )
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError("The description must be a string.")
-        if deprecation_reason is not None and not isinstance(deprecation_reason, str):
+        if deprecation_reason is not None and not is_description(deprecation_reason):
             raise TypeError("The deprecation reason must be a string.")
         if extensions is not None and (
             not isinstance(extensions, dict)
@@ -589,7 +596,7 @@ def __init__(
     ) -> None:
         if not is_input_type(type_):
             raise TypeError(f"Argument type must be a GraphQL input type.")
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError("Argument description must be a string.")
         if out_name is not None and not isinstance(out_name, str):
             raise TypeError("Argument out name must be a string.")
@@ -1131,9 +1138,9 @@ def __init__(
         extensions: Dict[str, Any] = None,
         ast_node: EnumValueDefinitionNode = None,
     ) -> None:
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError("The description of the enum value must be a string.")
-        if deprecation_reason is not None and not isinstance(deprecation_reason, str):
+        if deprecation_reason is not None and not is_description(deprecation_reason):
             raise TypeError(
                 "The deprecation reason for the enum value must be a string."
             )
@@ -1320,7 +1327,7 @@ def __init__(
     ) -> None:
         if not is_input_type(type_):
             raise TypeError(f"Input field type must be a GraphQL input type.")
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError("Input field description must be a string.")
         if out_name is not None and not isinstance(out_name, str):
             raise TypeError("Input field out name must be a string.")

src/graphql/type/directives.py

@@ -1,7 +1,7 @@
 from typing import Any, Dict, List, Optional, Sequence, cast
 
 from ..language import ast, DirectiveLocation
-from ..pyutils import inspect, FrozenList
+from ..pyutils import inspect, is_description, FrozenList
 from .definition import GraphQLArgument, GraphQLInputType, GraphQLNonNull, is_input_type
 from .scalars import GraphQLBoolean, GraphQLString
 
@@ -84,7 +84,7 @@ def __init__(
             raise TypeError(f"{name} is_repeatable flag must be True or False.")
         if ast_node and not isinstance(ast_node, ast.DirectiveDefinitionNode):
             raise TypeError(f"{name} AST node must be a DirectiveDefinitionNode.")
-        if description is not None and not isinstance(description, str):
+        if description is not None and not is_description(description):
             raise TypeError(f"{name} description must be a string.")
         if extensions is not None and (
             not isinstance(extensions, dict)