diff --git a/docs/usage/extension.rst b/docs/usage/extension.rst index bfe41c20..4d6c49b3 100644 --- a/docs/usage/extension.rst +++ b/docs/usage/extension.rst @@ -17,7 +17,7 @@ follows:: """)) Note that this function expects the extensions as an AST, which we can get using the -:func:`graphql.language.parse` function. Also note that the `extend_schema` function +:func:`graphql.language.parse` function. Also note that the :func:`~graphql.extend_schema` function does not alter the original schema, but returns a new schema object. We also need to attach a resolver function to the new field:: diff --git a/src/graphql/execution/execute.py b/src/graphql/execution/execute.py index 80ade47e..001a88ac 100644 --- a/src/graphql/execution/execute.py +++ b/src/graphql/execution/execute.py @@ -97,8 +97,8 @@ class ExecutionResult(NamedTuple): """The result of GraphQL execution. - - `data` is the result of a successful execution of the query. - - `errors` is included when any errors occurred as a non-empty list. + - ``data`` is the result of a successful execution of the query. + - ``errors`` is included when any errors occurred as a non-empty list. """ data: Optional[Dict[str, Any]] @@ -678,7 +678,8 @@ def complete_value( inner type on each item in the list. If the field type is a Scalar or Enum, ensures the completed value is a legal - value of the type by calling the `serialize` method of GraphQL type definition. + value of the type by calling the ``serialize`` method of GraphQL type + definition. If the field is an abstract type, determine the runtime type of the value and then complete based on that type. @@ -948,7 +949,7 @@ def collect_subfields( """Collect subfields. A cached collection of relevant subfields with regard to the return type is - kept in the execution context as `_subfields_cache`. This ensures the + kept in the execution context as ``_subfields_cache``. This ensures the subfields are not repeatedly calculated, which saves overhead when resolving lists of values. """ @@ -1065,9 +1066,9 @@ def get_field_def( """Get field definition. This method looks up the field on the given type definition. It has special casing - for the two introspection fields, `__schema` and `__typename`. `__typename` is + for the two introspection fields, ``__schema`` and ``__typename``. ``__typename`` is special because it can always be queried as a field, even in situations where no - other fields are allowed, like on a Union. `__schema` could get automatically + other fields are allowed, like on a Union. ``__schema`` could get automatically added to the query type, but that would require mutating type definitions, which would cause issues. @@ -1098,7 +1099,7 @@ def invalid_return_type_error( def get_typename(value: Any) -> Optional[str]: - """Get the `__typename` property of the given value.""" + """Get the ``__typename`` property of the given value.""" if isinstance(value, dict): return value.get("__typename") # need to de-mangle the attribute assumed to be "private" in Python @@ -1117,11 +1118,12 @@ def default_type_resolver( If a resolve_type function is not given, then a default resolve behavior is used which attempts two strategies: - First, See if the provided value has a `__typename` field defined, if so, use that + First, See if the provided value has a ``__typename`` field defined, if so, use that value as name of the resolved type. - Otherwise, test each possible type for the abstract type by calling `is_type_of` - for the object being coerced, returning the first type that matches. + Otherwise, test each possible type for the abstract type by calling + :meth:`~graphql.type.GraphQLObjectType.is_type_of` for the object + being coerced, returning the first type that matches. """ # First, look for `__typename`. type_name = get_typename(value) diff --git a/src/graphql/execution/middleware.py b/src/graphql/execution/middleware.py index d1070372..452b9910 100644 --- a/src/graphql/execution/middleware.py +++ b/src/graphql/execution/middleware.py @@ -13,7 +13,7 @@ class MiddlewareManager: This class helps to wrap resolver functions with the provided middleware functions and/or objects. The functions take the next middleware function as first argument. - If middleware is provided as an object, it must provide a method `resolve` that is + If middleware is provided as an object, it must provide a method ``resolve`` that is used as the middleware function. Note that since resolvers return "AwaitableOrValue"s, all middleware functions diff --git a/src/graphql/graphql.py b/src/graphql/graphql.py index d9924580..5b13a55e 100644 --- a/src/graphql/graphql.py +++ b/src/graphql/graphql.py @@ -65,7 +65,8 @@ async def graphql( :arg type_resolver: A type resolver function to use when none is provided by the schema. If not provided, the default type resolver is used (which looks for a - `__typename` field or alternatively calls the `is_type_of` method). + ``__typename`` field or alternatively calls the + :meth:`~graphql.type.GraphQLObjectType.is_type_of` method). :arg middleware: The middleware to wrap the resolvers with :arg execution_context_class: diff --git a/src/graphql/language/parser.py b/src/graphql/language/parser.py index 3f3dbc96..b3ef846c 100644 --- a/src/graphql/language/parser.py +++ b/src/graphql/language/parser.py @@ -77,14 +77,16 @@ def parse( Throws GraphQLError if a syntax error is encountered. By default, the parser creates AST nodes that know the location in the source that - they correspond to. The `no_location` option disables that behavior for performance - or testing. + they correspond to. The ``no_location`` option disables that behavior for + performance or testing. Experimental features: - If `experimental_fragment_variables` is set to True, the parser will understand - and parse variable definitions contained in a fragment definition. They'll be - represented in the `variable_definitions` field of the `FragmentDefinitionNode`. + If ``experimental_fragment_variables`` is set to ``True``, the parser will + understand and parse variable definitions contained in a fragment definition. + They'll be represented in the + :attr:`~graphql.language.FragmentDefinitionNode.variable_definitions` field + of the :class:`~graphql.language.FragmentDefinitionNode`. The syntax is identical to normal, query-defined variables. For example:: @@ -110,7 +112,8 @@ def parse_value( This is useful within tools that operate upon GraphQL Values directly and in isolation of complete GraphQL documents. - Consider providing the results to the utility function: `value_from_ast()`. + Consider providing the results to the utility function: + :func:`~graphql.value_from_ast`. """ parser = Parser( source, @@ -133,7 +136,8 @@ def parse_type( This is useful within tools that operate upon GraphQL Types directly and in isolation of complete GraphQL documents. - Consider providing the results to the utility function: `type_from_ast()`. + Consider providing the results to the utility function: + :func:`~graphql.value_from_ast`. """ parser = Parser( source, @@ -390,7 +394,7 @@ def parse_fragment_definition(self) -> FragmentDefinitionNode: ) def parse_fragment_name(self) -> NameNode: - """FragmentName: Name but not `on`""" + """FragmentName: Name but not ``on``""" if self._lexer.token.value == "on": raise self.unexpected() return self.parse_name() @@ -1042,9 +1046,10 @@ def any( ) -> List[T]: """Fetch any matching nodes, possibly none. - Returns a possibly empty list of parse nodes, determined by the `parse_fn`. - This list begins with a lex token of `open_kind` and ends with a lex token of - `close_kind`. Advances the parser to the next lex token after the closing token. + Returns a possibly empty list of parse nodes, determined by the ``parse_fn``. + This list begins with a lex token of ``open_kind`` and ends with a lex token of + ``close_kind``. Advances the parser to the next lex token after the closing + token. """ self.expect_token(open_kind) nodes: List[T] = [] @@ -1058,10 +1063,11 @@ def optional_many( ) -> List[T]: """Fetch matching nodes, maybe none. - Returns a list of parse nodes, determined by the `parse_fn`. It can be empty + Returns a list of parse nodes, determined by the ``parse_fn``. It can be empty only if the open token is missing, otherwise it will always return a non-empty - list that begins with a lex token of `open_kind` and ends with a lex token of - `close_kind`. Advances the parser to the next lex token after the closing token. + list that begins with a lex token of ``open_kind`` and ends with a lex token of + ``close_kind``. Advances the parser to the next lex token after the closing + token. """ if self.expect_optional_token(open_kind): nodes = [parse_fn()] @@ -1076,9 +1082,10 @@ def many( ) -> List[T]: """Fetch matching nodes, at least one. - Returns a non-empty list of parse nodes, determined by the `parse_fn`. - This list begins with a lex token of `open_kind` and ends with a lex token of - `close_kind`. Advances the parser to the next lex token after the closing token. + Returns a non-empty list of parse nodes, determined by the ``parse_fn``. + This list begins with a lex token of ``open_kind`` and ends with a lex token of + ``close_kind``. Advances the parser to the next lex token after the closing + token. """ self.expect_token(open_kind) nodes = [parse_fn()] diff --git a/src/graphql/language/source.py b/src/graphql/language/source.py index 1614ad7e..0561f574 100644 --- a/src/graphql/language/source.py +++ b/src/graphql/language/source.py @@ -18,10 +18,10 @@ def __init__( """Initialize source input. - `name` and `location_offset` are optional. They are useful for clients who + ``name`` and ``location_offset`` are optional. They are useful for clients who store GraphQL documents in source files; for example, if the GraphQL input starts at line 40 in a file named Foo.graphql, it might be useful for name - to be "Foo.graphql" and location to be `(40, 0)`. + to be "Foo.graphql" and location to be ``(40, 0)``. line and column in location_offset are 1-indexed """ diff --git a/src/graphql/language/visitor.py b/src/graphql/language/visitor.py index 977d8a61..4a3653b8 100644 --- a/src/graphql/language/visitor.py +++ b/src/graphql/language/visitor.py @@ -142,14 +142,14 @@ def enter(self, node, key, parent, path, ancestors): :arg parent: the parent immediately above this node, which may be an Array. :arg path: The key path to get to this node from the root node. :arg ancestors: All nodes and Arrays visited before reaching parent - of this node. These correspond to array indices in `path`. + of this node. These correspond to array indices in ``path``. Note: ancestors includes arrays which contain the parent of visited node. You can also define node kind specific methods by suffixing them with an underscore - followed by the kind of the node to be visited. For instance, to visit `field` - nodes, you would defined the methods `enter_field()` and/or `leave_field()`, with - the same signature as above. If no kind specific method has been defined for a given - node, the generic method is called. + followed by the kind of the node to be visited. For instance, to visit ``field`` + nodes, you would defined the methods ``enter_field()`` and/or ``leave_field()``, + with the same signature as above. If no kind specific method has been defined + for a given node, the generic method is called. """ # Provide special return values as attributes @@ -200,18 +200,18 @@ class Stack(NamedTuple): def visit(root: Node, visitor: Visitor, visitor_keys=None) -> Any: """Visit each node in an AST. - `visit()` will walk through an AST using a depth first traversal, calling the + :func:`~.visit` will walk through an AST using a depth first traversal, calling the visitor's enter methods at each node in the traversal, and calling the leave methods after visiting that node and all of its child nodes. By returning different values from the enter and leave methods, the behavior of the visitor can be altered, including skipping over a sub-tree of the AST (by returning False), editing the AST by returning a value or None to remove the value, or to stop - the whole traversal by returning `BREAK`. + the whole traversal by returning :data:`~.BREAK`. - When using `visit()` to edit an AST, the original AST will not be modified, and a - new version of the AST with the changes applied will be returned from the visit - function. + When using :func:`~.visit` to edit an AST, the original AST will not be modified, + and a new version of the AST with the changes applied will be returned from the + visit function. To customize the node attributes to be used for traversal, you can provide a dictionary visitor_keys mapping node kinds to node attributes. diff --git a/src/graphql/subscription/subscribe.py b/src/graphql/subscription/subscribe.py index 2e5d948a..58446cf2 100644 --- a/src/graphql/subscription/subscribe.py +++ b/src/graphql/subscription/subscribe.py @@ -51,7 +51,7 @@ async def subscribe( If the source stream could not be created due to faulty subscription resolver logic or underlying systems, the coroutine object will yield a single ExecutionResult - containing `errors` and no `data`. + containing ``errors`` and no ``data``. If the operation succeeded, the coroutine will yield an AsyncIterator, which yields a stream of ExecutionResults representing the response stream. @@ -75,11 +75,11 @@ async def map_source_to_response(payload) -> ExecutionResult: """Map source to response. For each payload yielded from a subscription, map it over the normal GraphQL - `execute` function, with `payload` as the `root_value`. This implements the - "MapSourceToResponseEvent" algorithm described in the GraphQL specification. - The `execute` function provides the "ExecuteSubscriptionEvent" algorithm, - as it is nearly identical to the "ExecuteQuery" algorithm, for which `execute` - is also used. + :func:`~graphql.execute` function, with ``payload`` as the ``root_value``. + This implements the "MapSourceToResponseEvent" algorithm described in the + GraphQL specification. The :func:`~graphql.execute` function provides the + "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the + "ExecuteQuery" algorithm, for which :func:`~graphql.execute` is also used. """ result = execute( schema, diff --git a/src/graphql/type/definition.py b/src/graphql/type/definition.py index 14268b69..7b7c0e1c 100644 --- a/src/graphql/type/definition.py +++ b/src/graphql/type/definition.py @@ -306,7 +306,7 @@ class GraphQLScalarType(GraphQLNamedType): and are defined with a name and a series of functions used to parse input from ast or variables and to ensure validity. - If a type's serialize function does not return a value (i.e. it returns `None`), + If a type's serialize function does not return a value (i.e. it returns ``None``), then no error will be included in the response. Example:: @@ -1245,7 +1245,7 @@ class GraphQLInputObjectType(GraphQLNamedType): An input object defines a structured collection of fields which may be supplied to a field argument. - Using `NonNull` will ensure that a value must be provided by the query. + Using ``NonNull`` will ensure that a value must be provided by the query. Example:: @@ -1261,7 +1261,7 @@ class GeoPoint(GraphQLInputObjectType): } The outbound values will be Python dictionaries by default, but you can have them - converted to other types by specifying an `out_type` function or class. + converted to other types by specifying an ``out_type`` function or class. """ ast_node: Optional[InputObjectTypeDefinitionNode] diff --git a/src/graphql/type/schema.py b/src/graphql/type/schema.py index 9b1bfc08..d9faf6f6 100644 --- a/src/graphql/type/schema.py +++ b/src/graphql/type/schema.py @@ -78,8 +78,8 @@ class GraphQLSchema: # you want them to be included in the final schema. types=[human_type, droid_type]) - Note: If a list of `directives` is provided to GraphQLSchema, that will be the - exact list of directives represented and allowed. If `directives` is not provided, + Note: If a list of ``directives`` is provided to GraphQLSchema, that will be the + exact list of directives represented and allowed. If ``directives`` is not provided, then a default set of the specified directives (e.g. @include and @skip) will be used. If you wish to provide *additional* directives to these specified directives, you must explicitly declare them. Example:: @@ -119,7 +119,7 @@ def __init__( """Initialize GraphQL schema. If this schema was built from a source known to be valid, then it may be marked - with `assume_valid` to avoid an additional type system validation. + with ``assume_valid`` to avoid an additional type system validation. """ self._validation_errors = [] if assume_valid else None diff --git a/src/graphql/utilities/build_ast_schema.py b/src/graphql/utilities/build_ast_schema.py index eab8959a..ca100c0c 100644 --- a/src/graphql/utilities/build_ast_schema.py +++ b/src/graphql/utilities/build_ast_schema.py @@ -36,9 +36,9 @@ def build_ast_schema( resolve methods, so execution will use default resolvers. When building a schema from a GraphQL service's introspection result, it might - be safe to assume the schema is valid. Set `assume_valid` to True to assume the - produced schema is valid. Set `assume_valid_sdl` to True to assume it is already - a valid SDL document. + be safe to assume the schema is valid. Set ``assume_valid`` to ``True`` to assume + the produced schema is valid. Set ``assume_valid_sdl`` to ``True`` to assume it is + already a valid SDL document. """ if not isinstance(document_ast, DocumentNode): raise TypeError("Must provide valid Document AST.") diff --git a/src/graphql/utilities/extend_schema.py b/src/graphql/utilities/extend_schema.py index 2c4cbdb1..f6ffb470 100644 --- a/src/graphql/utilities/extend_schema.py +++ b/src/graphql/utilities/extend_schema.py @@ -108,8 +108,9 @@ def extend_schema( copy. The original schema remains unaltered. When extending a schema with a known valid extension, it might be safe to assume the - schema is valid. Set `assume_valid` to true to assume the produced schema is valid. - Set `assume_valid_sdl` to True to assume it is already a valid SDL document. + schema is valid. Set ``assume_valid`` to ``True`` to assume the produced schema is + valid. Set ``assume_valid_sdl`` to ``True`` to assume it is already a valid SDL + document. """ assert_schema(schema) diff --git a/src/graphql/utilities/type_from_ast.py b/src/graphql/utilities/type_from_ast.py index a2c5d033..da43aba8 100644 --- a/src/graphql/utilities/type_from_ast.py +++ b/src/graphql/utilities/type_from_ast.py @@ -44,7 +44,7 @@ def type_from_ast(schema, type_node): Given a Schema and an AST node describing a type, return a GraphQLType definition which applies to that type. For example, if provided the parsed AST node for - `[User]`, a GraphQLList instance will be returned, containing the type called + ``[User]``, a GraphQLList instance will be returned, containing the type called "User" found in the schema. If a type called "User" is not found in the schema, then None will be returned. """ diff --git a/src/graphql/utilities/type_info.py b/src/graphql/utilities/type_info.py index 2fcbaa38..9b7bb17d 100644 --- a/src/graphql/utilities/type_info.py +++ b/src/graphql/utilities/type_info.py @@ -56,7 +56,8 @@ class TypeInfo: TypeInfo is a utility class which, given a GraphQL schema, can keep track of the current field and type definitions at any point in a GraphQL document AST during - a recursive descent by calling `enter(node)` and `leave(node)`. + a recursive descent by calling :meth:`enter(node) <.TypeInfo.enter>` and + :meth:`leave(node) <.TypeInfo.leave>`. """ def __init__( @@ -262,9 +263,9 @@ def get_field_def( ) -> Optional[GraphQLField]: """Get field definition. - Not exactly the same as the executor's definition of `get_field_def()`, in this - statically evaluated environment we do not always have an Object type, and need - to handle Interface and Union types. + Not exactly the same as the executor's definition of + :func:`graphql.execution.get_field_def`, in this statically evaluated environment + we do not always have an Object type, and need to handle Interface and Union types. """ name = field_node.name.value if name == "__schema" and schema.query_type is parent_type: diff --git a/src/graphql/utilities/value_from_ast.py b/src/graphql/utilities/value_from_ast.py index 7bb08845..62a506c8 100644 --- a/src/graphql/utilities/value_from_ast.py +++ b/src/graphql/utilities/value_from_ast.py @@ -33,7 +33,7 @@ def value_from_ast( A GraphQL type must be provided, which will be used to interpret different GraphQL Value literals. - Returns `Undefined` when the value could not be validly coerced according + Returns ``Undefined`` when the value could not be validly coerced according to the provided type. =================== ============== ================ @@ -143,7 +143,7 @@ def value_from_ast( def is_missing_variable( value_node: ValueNode, variables: Optional[Dict[str, Any]] = None ) -> bool: - """Check if `value_node` is a variable not defined in the `variables` dict.""" + """Check if ``value_node`` is a variable not defined in the ``variables`` dict.""" return isinstance(value_node, VariableNode) and ( not variables or variables.get(value_node.name.value, Undefined) is Undefined ) diff --git a/src/graphql/utilities/value_from_ast_untyped.py b/src/graphql/utilities/value_from_ast_untyped.py index cf245707..3d38e797 100644 --- a/src/graphql/utilities/value_from_ast_untyped.py +++ b/src/graphql/utilities/value_from_ast_untyped.py @@ -12,8 +12,8 @@ def value_from_ast_untyped( ) -> Any: """Produce a Python value given a GraphQL Value AST. - Unlike `value_from_ast()`, no type is provided. The resulting Python value will - reflect the provided GraphQL value AST. + Unlike :func:`~graphql.value_from_ast`, no type is provided. + The resulting Python value will reflect the provided GraphQL value AST. =================== ============== ================ GraphQL Value JSON Value Python Value diff --git a/src/graphql/validation/rules/fields_on_correct_type.py b/src/graphql/validation/rules/fields_on_correct_type.py index fdac446f..c784eae6 100644 --- a/src/graphql/validation/rules/fields_on_correct_type.py +++ b/src/graphql/validation/rules/fields_on_correct_type.py @@ -24,7 +24,7 @@ class FieldsOnCorrectTypeRule(ValidationRule): """Fields on correct type A GraphQL document is only valid if all fields selected are defined by the parent - type, or are an allowed meta field such as `__typename`. + type, or are an allowed meta field such as ``__typename``. """ def enter_field(self, node: FieldNode, *_args): diff --git a/src/graphql/validation/rules/known_directives.py b/src/graphql/validation/rules/known_directives.py index dd080c0c..3998847d 100644 --- a/src/graphql/validation/rules/known_directives.py +++ b/src/graphql/validation/rules/known_directives.py @@ -17,7 +17,7 @@ class KnownDirectivesRule(ASTValidationRule): """Known directives - A GraphQL document is only valid if all `@directives` are known by the schema and + A GraphQL document is only valid if all ``@directives`` are known by the schema and legally positioned. """ diff --git a/src/graphql/validation/rules/known_fragment_names.py b/src/graphql/validation/rules/known_fragment_names.py index 095e70ae..49929106 100644 --- a/src/graphql/validation/rules/known_fragment_names.py +++ b/src/graphql/validation/rules/known_fragment_names.py @@ -8,7 +8,7 @@ class KnownFragmentNamesRule(ValidationRule): """Known fragment names - A GraphQL document is only valid if all `...Fragment` fragment spreads refer to + A GraphQL document is only valid if all ``...Fragment`` fragment spreads refer to fragments defined in the same document. """ diff --git a/src/graphql/validation/rules/overlapping_fields_can_be_merged.py b/src/graphql/validation/rules/overlapping_fields_can_be_merged.py index 4f2219e3..b5a5da54 100644 --- a/src/graphql/validation/rules/overlapping_fields_can_be_merged.py +++ b/src/graphql/validation/rules/overlapping_fields_can_be_merged.py @@ -466,10 +466,10 @@ def collect_conflicts_between( ) -> None: """Collect all Conflicts between two collections of fields. - This is similar to, but different from the `collectConflictsWithin` function above. - This check assumes that `collectConflictsWithin` has already been called on each - provided collection of fields. This is true because this validator traverses each - individual selection set. + This is similar to, but different from the :func:`~.collect_conflicts_within` + function above. This check assumes that :func:`~.collect_conflicts_within` has + already been called on each provided collection of fields. This is true because + this validator traverses each individual selection set. """ # A field map is a keyed collection, where each key represents a response name and # the value at that key is a list of all fields which provide that response name.