Add @specifiedBy directive

Replicates graphql/graphql-js@9d4b433

Author: Cito

src/graphql/__init__.py

@@ -70,6 +70,7 @@
     GraphQLIncludeDirective,
     GraphQLSkipDirective,
     GraphQLDeprecatedDirective,
+    GraphQLSpecifiedByDirective,
     # "Enum" of Type Kinds
     TypeKind,
     # Constant Deprecation Reason
@@ -437,6 +438,7 @@
     "GraphQLIncludeDirective",
     "GraphQLSkipDirective",
     "GraphQLDeprecatedDirective",
+    "GraphQLSpecifiedByDirective",
     "TypeKind",
     "DEFAULT_DEPRECATION_REASON",
     "introspection_types",

src/graphql/type/__init__.py

@@ -108,6 +108,7 @@
     GraphQLIncludeDirective,
     GraphQLSkipDirective,
     GraphQLDeprecatedDirective,
+    GraphQLSpecifiedByDirective,
     # Constant Deprecation Reason
     DEFAULT_DEPRECATION_REASON,
 )
@@ -227,6 +228,7 @@
     "GraphQLIncludeDirective",
     "GraphQLSkipDirective",
     "GraphQLDeprecatedDirective",
+    "GraphQLSpecifiedByDirective",
     "DEFAULT_DEPRECATION_REASON",
     "is_specified_scalar_type",
     "specified_scalar_types",

src/graphql/type/definition.py

@@ -318,6 +318,7 @@ def serialize_odd(value):
 
     """
 
+    specified_by_url: Optional[str]
     ast_node: Optional[ScalarTypeDefinitionNode]
     extension_ast_nodes: Optional[FrozenList[ScalarTypeExtensionNode]]
 
@@ -328,6 +329,7 @@ def __init__(
         parse_value: Optional[GraphQLScalarValueParser] = None,
         parse_literal: Optional[GraphQLScalarLiteralParser] = None,
         description: Optional[str] = None,
+        specified_by_url: Optional[str] = None,
         extensions: Optional[Dict[str, Any]] = None,
         ast_node: Optional[ScalarTypeDefinitionNode] = None,
         extension_ast_nodes: Optional[Collection[ScalarTypeExtensionNode]] = None,
@@ -339,6 +341,11 @@ def __init__(
             ast_node=ast_node,
             extension_ast_nodes=extension_ast_nodes,
         )
+        if specified_by_url is not None and not isinstance(specified_by_url, str):
+            raise TypeError(
+                f"{name} must provide 'specified_by_url' as a string,"
+                f" but got: {inspect(specified_by_url)}."
+            )
         if serialize is not None and not callable(serialize):
             raise TypeError(
                 f"{name} must provide 'serialize' as a function."
@@ -369,6 +376,7 @@ def __init__(
             self.parse_value = parse_value  # type: ignore
         if parse_literal is not None:
             self.parse_literal = parse_literal  # type: ignore
+        self.specified_by_url = specified_by_url
 
     def __repr__(self):
         return f"<{self.__class__.__name__} {self.name!r}>"
@@ -417,6 +425,7 @@ def to_kwargs(self) -> Dict[str, Any]:
             if getattr(self.parse_literal, "__func__", None)
             is GraphQLScalarType.parse_literal
             else self.parse_literal,
+            specified_by_url=self.specified_by_url,
         )
 
 

src/graphql/type/directives.py

@@ -14,6 +14,7 @@
     "GraphQLIncludeDirective",
     "GraphQLSkipDirective",
     "GraphQLDeprecatedDirective",
+    "GraphQLSpecifiedByDirective",
     "DirectiveLocation",
     "DEFAULT_DEPRECATION_REASON",
 ]
@@ -196,9 +197,27 @@ def assert_directive(directive: Any) -> GraphQLDirective:
     description="Marks an element of a GraphQL schema as no longer supported.",
 )
 
+# Used to provide a URL for specifying the behaviour of custom scalar definitions:
+GraphQLSpecifiedByDirective = GraphQLDirective(
+    name="specifiedBy",
+    locations=[DirectiveLocation.SCALAR],
+    args={
+        "url": GraphQLArgument(
+            GraphQLNonNull(GraphQLString),
+            description="The URL that specifies the behaviour of this scalar.",
+        )
+    },
+    description="Exposes a URL that specifies the behaviour of this scalar.",
+)
+
 
 specified_directives: FrozenList[GraphQLDirective] = FrozenList(
-    [GraphQLIncludeDirective, GraphQLSkipDirective, GraphQLDeprecatedDirective]
+    [
+        GraphQLIncludeDirective,
+        GraphQLSkipDirective,
+        GraphQLDeprecatedDirective,
+        GraphQLSpecifiedByDirective,
+    ]
 )
 specified_directives.__doc__ = """The full list of specified directives."""
 

src/graphql/type/introspection.py

@@ -199,8 +199,8 @@
     " There are many kinds of types in GraphQL as represented"
     " by the `__TypeKind` enum.\n\nDepending on the kind of a"
     " type, certain fields describe information about that type."
-    " Scalar types provide no information beyond a name and"
-    " description, while Enum types provide their values."
+    " Scalar types provide no information beyond a name, description"
+    " and optional `specifiedByUrl`, while Enum types provide their values."
     " Object and Interface types provide the fields they describe."
     " Abstract types, Union and Interface, provide the Object"
     " types possible at runtime. List and NonNull types compose"
@@ -213,6 +213,9 @@
         "description": GraphQLField(
             GraphQLString, resolve=TypeFieldResolvers.description
         ),
+        "specifiedByUrl": GraphQLField(
+            GraphQLString, resolve=TypeFieldResolvers.specified_by_url
+        ),
         "fields": GraphQLField(
             GraphQLList(GraphQLNonNull(__Field)),
             args={
@@ -278,6 +281,10 @@ def name(type_, _info):
     def description(type_, _info):
         return getattr(type_, "description", None)
 
+    @staticmethod
+    def specified_by_url(type_, _info):
+        return getattr(type_, "specified_by_url", None)
+
     # noinspection PyPep8Naming
     @staticmethod
     def fields(type_, _info, includeDeprecated=False):

src/graphql/utilities/build_ast_schema.py

@@ -10,6 +10,7 @@
     GraphQLIncludeDirective,
     GraphQLSchema,
     GraphQLSkipDirective,
+    GraphQLSpecifiedByDirective,
 )
 from .extend_schema import extend_schema_impl
 
@@ -71,6 +72,8 @@ def build_ast_schema(
         directives.append(GraphQLIncludeDirective)
     if not any(directive.name == "deprecated" for directive in directives):
         directives.append(GraphQLDeprecatedDirective)
+    if not any(directive.name == "specifiedBy" for directive in directives):
+        directives.append(GraphQLSpecifiedByDirective)
 
     return GraphQLSchema(**schema_kwargs)
 

src/graphql/utilities/build_client_schema.py

@@ -115,6 +115,7 @@ def build_scalar_def(scalar_introspection: Dict) -> GraphQLScalarType:
         return GraphQLScalarType(
             name=scalar_introspection["name"],
             description=scalar_introspection.get("description"),
+            specified_by_url=scalar_introspection.get("specifiedByUrl"),
         )
 
     def build_implementations_list(

src/graphql/utilities/extend_schema.py

@@ -32,6 +32,7 @@
     ObjectTypeExtensionNode,
     OperationType,
     ScalarTypeDefinitionNode,
+    ScalarTypeExtensionNode,
     SchemaExtensionNode,
     SchemaDefinitionNode,
     TypeDefinitionNode,
@@ -64,6 +65,7 @@
     GraphQLOutputType,
     GraphQLScalarType,
     GraphQLSchema,
+    GraphQLSpecifiedByDirective,
     GraphQLType,
     GraphQLUnionType,
     assert_schema,
@@ -269,9 +271,14 @@ def extend_scalar_type(type_: GraphQLScalarType) -> GraphQLScalarType:
         kwargs = type_.to_kwargs()
         extensions = type_extensions_map[kwargs["name"]]
 
+        specified_by_url = kwargs["specified_by_url"]
+        for extension_node in extensions:
+            specified_by_url = get_specified_by_url(extension_node) or specified_by_url
+
         return GraphQLScalarType(
             **{
                 **kwargs,
+                "specified_by_url": specified_by_url,
                 "extension_ast_nodes": kwargs["extension_ast_nodes"] + extensions,
             }
         )
@@ -574,6 +581,7 @@ def build_scalar_type(ast_node: ScalarTypeDefinitionNode) -> GraphQLScalarType:
         return GraphQLScalarType(
             name=ast_node.name.value,
             description=ast_node.description.value if ast_node.description else None,
+            specified_by_url=get_specified_by_url(ast_node),
             ast_node=ast_node,
             extension_ast_nodes=extension_nodes,
         )
@@ -673,6 +681,16 @@ def get_deprecation_reason(
     return deprecated["reason"] if deprecated else None
 
 
+def get_specified_by_url(
+    node: Union[ScalarTypeDefinitionNode, ScalarTypeExtensionNode]
+) -> Optional[str]:
+    """Given a scalar node, return the string value for the specifiedByUrl."""
+    from ..execution import get_directive_values
+
+    specified_by_url = get_directive_values(GraphQLSpecifiedByDirective, node)
+    return specified_by_url["url"] if specified_by_url else None
+
+
 def get_description(node: Node) -> Optional[str]:
     """@deprecated: Given an ast node, returns its string description."""
     try:

src/graphql/utilities/get_introspection_query.py

@@ -4,14 +4,19 @@
 
 
 def get_introspection_query(
-    descriptions=True, directive_is_repeatable=False, schema_description=False
+    descriptions=True,
+    specified_by_url=False,
+    directive_is_repeatable=False,
+    schema_description=False,
 ) -> str:
     """Get a query for introspection.
 
-    Optionally, you can exclude descriptions, include repeatability of directives,
-    and specify whether to include the schema description as well.
+    Optionally, you can exclude descriptions, include specification URLs,
+    include repeatability of directives, and specify whether to include
+    the schema description as well.
     """
     maybe_description = "description" if descriptions else ""
+    maybe_specified_by_url = "specifiedByUrl" if specified_by_url else ""
     maybe_directive_is_repeatable = "isRepeatable" if directive_is_repeatable else ""
     maybe_schema_description = maybe_description if schema_description else ""
     return dedent(
@@ -41,6 +46,7 @@ def get_introspection_query(
           kind
           name
           {maybe_description}
+          {maybe_specified_by_url}
           fields(includeDeprecated: true) {{
             name
             {maybe_description}

src/graphql/utilities/introspection_from_schema.py

@@ -14,6 +14,7 @@
 def introspection_from_schema(
     schema: GraphQLSchema,
     descriptions: bool = True,
+    specified_by_url: bool = False,
     directive_is_repeatable: bool = True,
     schema_description: bool = True,
 ) -> IntrospectionSchema:
@@ -27,7 +28,7 @@ def introspection_from_schema(
     """
     document = parse(
         get_introspection_query(
-            descriptions, directive_is_repeatable, schema_description
+            descriptions, specified_by_url, directive_is_repeatable, schema_description
         )
     )