graphql-core 3.2.12__tar.gz → 3.2.14__tar.gz

{graphql_core-3.2.12 → graphql_core-3.2.14}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.2.12
+current_version = 3.2.14
 commit = False
 tag = False
 

graphql_core-3.2.14/.flake8

@@ -0,0 +1,13 @@
+[flake8]
+ignore = E203,E704,W503,D105,D107,D203,D213,D400,D403,D415,D401
+docstring-convention = all
+per-file-ignores =
+    src/graphql/language/ast.py: D101
+    src/graphql/utilities/extend_schema.py: D102
+    src/graphql/utilities/get_introspection_query.py: D101
+    src/graphql/utilities/type_info.py: D102
+    src/graphql/validation/rules/*: D102
+    src/graphql/validation/validation_context.py: D102
+    tests/*: D100,D101,D102,D103
+exclude = .git,.mypy_cache,.pytest_cache,.tox,.venv,__pycache__,build,dist,docs
+max-line-length = 88

{graphql_core-3.2.12 → graphql_core-3.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphql-core
-Version: 3.2.12
+Version: 3.2.14
 Summary: GraphQL implementation for Python, a port of GraphQL.js, the JavaScript reference implementation for GraphQL.
 Home-page: https://github.com/graphql-python/graphql-core
 Author: Christoph Zwerschke
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Python: >=3.7,<4
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -50,7 +51,7 @@ a query language for APIs created by Facebook.
 ![Lint Status](https://github.com/graphql-python/graphql-core/actions/workflows/lint.yml/badge.svg)
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
-The current version 3.2.12 of GraphQL-core is up-to-date with GraphQL.js version 16.14.2.
+The current version 3.2.14 of GraphQL-core is up-to-date with GraphQL.js version 16.15.0.
 
 An extensive test suite with over 2500 unit tests and 100% coverage comprises a
 replication of the complete test suite of GraphQL.js, making sure this port is

{graphql_core-3.2.12 → graphql_core-3.2.14}/README.md

@@ -10,7 +10,7 @@ a query language for APIs created by Facebook.
 ![Lint Status](https://github.com/graphql-python/graphql-core/actions/workflows/lint.yml/badge.svg)
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
-The current version 3.2.12 of GraphQL-core is up-to-date with GraphQL.js version 16.14.2.
+The current version 3.2.14 of GraphQL-core is up-to-date with GraphQL.js version 16.15.0.
 
 An extensive test suite with over 2500 unit tests and 100% coverage comprises a
 replication of the complete test suite of GraphQL.js, making sure this port is

{graphql_core-3.2.12 → graphql_core-3.2.14}/docs/conf.py

@@ -61,7 +61,7 @@ author = "Christoph Zwerschke"
 # The short X.Y version.
 # version = '3.2'
 # The full version, including alpha/beta/rc tags.
-version = release = "3.2.12"
+version = release = "3.2.14"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

{graphql_core-3.2.12 → graphql_core-3.2.14}/docs/modules/execution.rst

@@ -32,6 +32,8 @@ Execution
 
 .. autoclass:: MiddlewareManager
 
+.. autofunction:: get_argument_values
+
 .. autofunction:: get_directive_values
 
 .. autofunction:: get_variable_values

{graphql_core-3.2.12 → graphql_core-3.2.14}/docs/modules/type.rst

@@ -13,6 +13,7 @@ Definition
 Predicates
 ^^^^^^^^^^
 
+.. autofunction:: is_abstract_type
 .. autofunction:: is_composite_type
 .. autofunction:: is_enum_type
 .. autofunction:: is_input_object_type
@@ -25,6 +26,8 @@ Predicates
 .. autofunction:: is_nullable_type
 .. autofunction:: is_object_type
 .. autofunction:: is_output_type
+.. autofunction:: is_required_argument
+.. autofunction:: is_required_input_field
 .. autofunction:: is_scalar_type
 .. autofunction:: is_type
 .. autofunction:: is_union_type
@@ -116,6 +119,11 @@ Predicates
 .. autofunction:: is_directive
 .. autofunction:: is_specified_directive
 
+Assertions
+^^^^^^^^^^
+
+.. autofunction:: assert_directive
+
 Definitions
 ^^^^^^^^^^^
 
@@ -123,6 +131,8 @@ Definitions
 .. autoclass:: GraphQLIncludeDirective
 .. autoclass:: GraphQLSkipDirective
 .. autoclass:: GraphQLDeprecatedDirective
+.. autoclass:: GraphQLSpecifiedByDirective
+.. autoclass:: GraphQLOneOfDirective
 
 .. data:: specified_directives
 
@@ -172,6 +182,10 @@ Definitions
 .. autoclass:: GraphQLInt
 .. autoclass:: GraphQLString
 
+.. data:: specified_scalar_types
+
+   A mapping containing all scalar types from the GraphQL specification
+
 .. data:: GRAPHQL_MAX_INT
 
    Maximum possible Int value as per GraphQL Spec (32-bit signed integer)
@@ -189,6 +203,11 @@ Predicates
 
 .. autofunction:: is_schema
 
+Assertions
+^^^^^^^^^^
+
+.. autofunction:: assert_schema
+
 Definitions
 ^^^^^^^^^^^
 

{graphql_core-3.2.12 → graphql_core-3.2.14}/docs/modules/validation.rst

@@ -33,6 +33,11 @@ Rules
 
    A tuple with all validation rules defined by the GraphQL specification
 
+.. data:: recommended_rules
+
+   A tuple with validation rules that are not part of the GraphQL specification,
+   but recommended to be used, like limiting the depth of introspection queries
+
 **Spec Section: "Executable Definitions"**
 
 .. autoclass:: ExecutableDefinitionsRule
@@ -151,3 +156,8 @@ Rules
 .. autoclass:: UniqueArgumentDefinitionNamesRule
 .. autoclass:: UniqueDirectiveNamesRule
 .. autoclass:: PossibleTypeExtensionsRule
+
+**Custom validation rules (not part of the specification)**
+
+.. autoclass:: NoDeprecatedCustomRule
+.. autoclass:: NoSchemaIntrospectionCustomRule

{graphql_core-3.2.12 → graphql_core-3.2.14}/pyproject.toml

@@ -1,9 +1,9 @@
 [tool.poetry]
 name = "graphql-core"
-version = "3.2.12"
+version = "3.2.14"
 description = """
-GraphQL-core is a Python port of GraphQL.js,\
- the JavaScript reference implementation for GraphQL."""
+GraphQL-core is a Python port of GraphQL.js, \
+the JavaScript reference implementation for GraphQL."""
 license = "MIT"
 authors = [
     "Christoph Zwerschke <cito@online.de>"
@@ -26,6 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
 ]
 packages = [
     { include = "graphql", from = "src" },
@@ -54,7 +55,8 @@ typing-extensions = [
 
 [tool.black]
 target-version = [
-    'py37', 'py38', 'py39', 'py310', 'py311', 'py312', 'py313', 'py314'
+    'py37', 'py38', 'py39', 'py310', 'py311', 'py312', 'py313', 'py314',
+    'py315'
 ]
 
 [tool.pyright]

{graphql_core-3.2.12 → graphql_core-3.2.14}/setup.cfg

@@ -1,5 +1,5 @@
 [bdist_wheel]
-python-tag = py3
+python_tag = py3
 
 [aliases]
 test = pytest

{graphql_core-3.2.12 → graphql_core-3.2.14}/setup.py

@@ -1,3 +1,5 @@
+"""Setup script for GraphQL-core."""
+
 from re import search
 
 from setuptools import find_packages, setup
@@ -35,6 +37,7 @@ setup(
         "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3.14",
+        "Programming Language :: Python :: 3.15",
     ],
     install_requires=[
         "typing-extensions>=4.7,<5; python_version < '3.10'",

{graphql_core-3.2.12 → graphql_core-3.2.14}/src/graphql/error/__init__.py

@@ -2,6 +2,8 @@
 
 The :mod:`graphql.error` package is responsible for creating and formatting GraphQL
 errors.
+
+These exports are also available from the root :mod:`graphql` package.
 """
 
 from .graphql_error import (

{graphql_core-3.2.12 → graphql_core-3.2.14}/src/graphql/error/graphql_error.py

@@ -1,4 +1,5 @@
-from sys import exc_info
+"""GraphQL Error"""
+
 from typing import Any, Collection, Dict, List, Optional, Union, TYPE_CHECKING
 
 try:
@@ -39,22 +40,40 @@ GraphQLFormattedErrorExtensions = Dict[str, Any]
 
 
 class GraphQLFormattedError(TypedDict, total=False):
-    """Formatted GraphQL error"""
+    """Formatted GraphQL error
+
+    See: https://spec.graphql.org/draft/#sec-Errors
+    """
 
-    # A short, human-readable summary of the problem that **SHOULD NOT** change
-    # from occurrence to occurrence of the problem, except for purposes of localization.
     message: str
-    # If an error can be associated to a particular point in the requested
-    # GraphQL document, it should contain a list of locations.
+    """A short, human-readable summary of the problem.
+
+    The message **SHOULD NOT** change from occurrence to occurrence of the problem,
+    except for purposes of localization.
+    """
+
     locations: List["FormattedSourceLocation"]
-    # If an error can be associated to a particular field in the GraphQL result,
-    # it _must_ contain an entry with the key `path` that details the path of
-    # the response field which experienced the error. This allows clients to
-    # identify whether a null result is intentional or caused by a runtime error.
+    """Locations in the requested GraphQL document.
+
+    If an error can be associated to a particular point in the requested GraphQL
+    document, it should contain a list of locations.
+    """
+
     path: List[Union[str, int]]
-    # Reserved for implementors to extend the protocol however they see fit,
-    # and hence there are no additional restrictions on its contents.
+    """Path of the response field which experienced the error.
+
+    If an error can be associated to a particular field in the GraphQL result, it
+    *must* contain an entry with the key ``path`` that details the path of the response
+    field which experienced the error. This allows clients to identify whether a null
+    result is intentional or caused by a runtime error.
+    """
+
     extensions: GraphQLFormattedErrorExtensions
+    """Custom extensions.
+
+    Reserved for implementors to extend the protocol however they see fit, and hence
+    there are no additional restrictions on its contents.
+    """
 
 
 class GraphQLError(Exception):
@@ -64,6 +83,72 @@ class GraphQLError(Exception):
     phases of performing a GraphQL operation. In addition to a message, it also includes
     information about the locations in a GraphQL document and/or execution result that
     correspond to the Error.
+
+    :param message: Human-readable error message.
+    :param nodes: AST node or nodes associated with this error.
+    :param source: Source document used to derive error locations.
+    :param positions: Character offsets in the source document associated with this
+        error.
+    :param path: Response path where this error occurred during execution.
+    :param original_error: Original error that caused this GraphQLError, if one
+        exists.
+    :param extensions: Extension fields to include in the formatted error.
+
+    Create an error from AST nodes and response metadata:
+
+    >>> from graphql import GraphQLError, parse
+    >>> document = parse('{ greeting }')
+    >>> field_node = document.definitions[0].selection_set.selections[0]
+    >>> error = GraphQLError(
+    ...     'Cannot query this field.',
+    ...     nodes=field_node,
+    ...     path=['greeting'],
+    ...     extensions={'code': 'FORBIDDEN'},
+    ... )
+    >>> error.message
+    'Cannot query this field.'
+    >>> error.locations
+    [SourceLocation(line=1, column=3)]
+    >>> error.path
+    ['greeting']
+    >>> error.extensions
+    {'code': 'FORBIDDEN'}
+
+    This variant derives locations from source positions and preserves the original
+    error:
+
+    >>> from graphql import Source
+    >>> source = Source('{ greeting }')
+    >>> original_error = RuntimeError('Database unavailable.')
+    >>> error = GraphQLError(
+    ...     'Resolver failed.',
+    ...     source=source,
+    ...     positions=[2],
+    ...     path=['greeting'],
+    ...     original_error=original_error,
+    ... )
+    >>> error.locations
+    [SourceLocation(line=1, column=3)]
+    >>> error.path
+    ['greeting']
+    >>> error.original_error is original_error
+    True
+
+    All arguments can also be passed positionally:
+
+    >>> error = GraphQLError(
+    ...     'Resolver failed.',
+    ...     None,
+    ...     source,
+    ...     [2],
+    ...     ['greeting'],
+    ...     original_error,
+    ...     {'code': 'INTERNAL'},
+    ... )
+    >>> error.locations
+    [SourceLocation(line=1, column=3)]
+    >>> error.extensions
+    {'code': 'INTERNAL'}
     """
 
     message: str
@@ -81,7 +166,7 @@ class GraphQLError(Exception):
     """
 
     path: Optional[List[Union[str, int]]]
-    """
+    """Response path
 
     A list of field names and array indexes describing the JSON-path into the execution
     response which corresponds to this error.
@@ -107,7 +192,7 @@ class GraphQLError(Exception):
     """
 
     original_error: Optional[Exception]
-    """The original error thrown from a field resolver during execution"""
+    """Original error that caused this GraphQLError, if one exists"""
 
     extensions: Optional[GraphQLErrorExtensions]
     """Extension fields to add to the formatted error"""
@@ -160,13 +245,18 @@ class GraphQLError(Exception):
         if not positions and node_locations:
             positions = [loc.start for loc in node_locations]
         self.positions = positions or None
-        if positions and source:
-            locations: Optional[List["SourceLocation"]] = [
-                source.get_location(pos) for pos in positions
-            ]
+        source_positions = (
+            [(source, pos) for pos in positions]
+            if positions and source
+            else [(loc.source, loc.start) for loc in node_locations]
+        )
+        if source_positions:
+            # Lazy import to avoid a cyclic dependency between error and language
+            from ..language.location import get_locations
+
+            self.locations = get_locations(source_positions)
         else:
-            locations = [loc.source.get_location(loc.start) for loc in node_locations]
-        self.locations = locations or None
+            self.locations = None
 
         if original_error:
             self.__traceback__ = original_error.__traceback__
@@ -179,10 +269,23 @@ class GraphQLError(Exception):
                 if isinstance(original_extensions, dict):
                     extensions = original_extensions
         self.extensions = extensions or {}
-        if not self.__traceback__:
-            self.__traceback__ = exc_info()[2]
 
     def __str__(self) -> str:
+        """Get this error as a human-readable message with source locations.
+
+        >>> from graphql import GraphQLError, Source
+        >>> error = GraphQLError(
+        ...     'Cannot query field "name".',
+        ...     source=Source('{ name }'),
+        ...     positions=[2],
+        ... )
+        >>> print(error)
+        Cannot query field "name".
+        <BLANKLINE>
+        GraphQL request:1:3
+        1 | { name }
+          |   ^
+        """
         # Lazy import to avoid a cyclic dependency between error and language
         from ..language.print_location import print_location, print_source_location
 
@@ -237,6 +340,16 @@ class GraphQLError(Exception):
 
         Given a GraphQLError, format it according to the rules described by the
         "Response Format, Errors" section of the GraphQL Specification.
+
+        >>> from graphql import GraphQLError
+        >>> error = GraphQLError(
+        ...     'Resolver failed.',
+        ...     path=['viewer', 'name'],
+        ...     extensions={'code': 'INTERNAL'},
+        ... )
+        >>> error.formatted
+        {'message': 'Resolver failed.', 'path': ['viewer', 'name'],
+         'extensions': {'code': 'INTERNAL'}}
         """
         formatted: GraphQLFormattedError = {
             "message": self.message or "An unknown error occurred.",
@@ -257,6 +370,14 @@ def print_error(error: GraphQLError) -> str:
     This deprecated helper is retained for backwards compatibility; call ``str(error)``
     instead because ``print_error`` will be removed in v3.3.
 
+    :param error: The error to format.
+    :returns: The printed string representation.
+
+    >>> from graphql import GraphQLError
+    >>> from graphql.error.graphql_error import print_error
+    >>> print_error(GraphQLError('Example error'))
+    'Example error'
+
     .. deprecated:: 3.2
        Please use ``str(error)`` instead. Will be removed in v3.3.
     """
@@ -273,6 +394,14 @@ def format_error(error: GraphQLError) -> GraphQLFormattedError:
     retained for backwards compatibility; use ``error.formatted`` instead because
     ``format_error`` will be removed in v3.3.
 
+    :param error: The error to format.
+    :returns: The JSON-serializable formatted error.
+
+    >>> from graphql import GraphQLError
+    >>> from graphql.error.graphql_error import format_error
+    >>> format_error(GraphQLError('Example error'))
+    {'message': 'Example error'}
+
     .. deprecated:: 3.2
        Please use ``error.formatted`` instead. Will be removed in v3.3.
     """

{graphql_core-3.2.12 → graphql_core-3.2.14}/src/graphql/error/located_error.py

@@ -1,3 +1,5 @@
+"""Located GraphQL Error"""
+
 from typing import TYPE_CHECKING, Collection, Optional, Union
 
 from ..pyutils import inspect
@@ -19,6 +21,22 @@ def located_error(
     Given an arbitrary Exception, presumably thrown while attempting to execute a
     GraphQL operation, produce a new GraphQLError aware of the location in the document
     responsible for the original Exception.
+
+    :param original_error: The original error value to wrap.
+    :param nodes: The AST nodes associated with the error.
+    :param path: The response path associated with the error.
+    :returns: The GraphQL error.
+
+    >>> from graphql import located_error, parse
+    >>> document = parse('{ viewer { name } }')
+    >>> field_node = document.definitions[0].selection_set.selections[0]
+    >>> error = located_error(RuntimeError('Resolver failed'), [field_node], ['viewer'])
+    >>> error.message
+    'Resolver failed'
+    >>> error.locations
+    [SourceLocation(line=1, column=3)]
+    >>> error.path
+    ['viewer']
     """
     # Sometimes a non-error is thrown, wrap it as a TypeError to ensure consistency.
     if not isinstance(original_error, Exception):

graphql_core-3.2.14/src/graphql/error/syntax_error.py

@@ -0,0 +1,38 @@
+"""GraphQL Syntax Error"""
+
+from typing import TYPE_CHECKING
+
+from .graphql_error import GraphQLError
+
+if TYPE_CHECKING:
+    from ..language.source import Source  # noqa: F401
+
+__all__ = ["GraphQLSyntaxError"]
+
+
+class GraphQLSyntaxError(GraphQLError):
+    """A GraphQLError representing a syntax error.
+
+    Contains useful descriptive information about the syntax error's position in the
+    source.
+
+    :param source: The GraphQL source containing the syntax error.
+    :param position: Character offset where the syntax error was encountered.
+    :param description: Human-readable description of the syntax error.
+
+    >>> from graphql import GraphQLSyntaxError, Source
+    >>> error = GraphQLSyntaxError(Source('query {'), 7, 'Expected Name')
+    >>> error.message
+    'Syntax Error: Expected Name'
+    >>> error.locations
+    [SourceLocation(line=1, column=8)]
+    """
+
+    description: str
+    """Human-readable description of the syntax error."""
+
+    def __init__(self, source: "Source", position: int, description: str) -> None:
+        super().__init__(
+            f"Syntax Error: {description}", source=source, positions=[position]
+        )
+        self.description = description

{graphql_core-3.2.12 → graphql_core-3.2.14}/src/graphql/execution/__init__.py

@@ -2,6 +2,8 @@
 
 The :mod:`graphql.execution` package is responsible for the execution phase of
 fulfilling a GraphQL request.
+
+These exports are also available from the root :mod:`graphql` package.
 """
 
 from .execute import (

{graphql_core-3.2.12 → graphql_core-3.2.14}/src/graphql/execution/collect_fields.py

@@ -1,4 +1,6 @@
-from typing import Any, Dict, List, Set, Union, cast
+"""Collect fields"""
+
+from typing import Any, Callable, Dict, List, Optional, Set, Union, cast
 
 from ..language import (
     FieldNode,
@@ -27,6 +29,7 @@ def collect_fields(
     variable_values: Dict[str, Any],
     runtime_type: GraphQLObjectType,
     selection_set: SelectionSetNode,
+    on_selection_set: Optional[Callable[[SelectionSetNode], None]] = None,
 ) -> Dict[str, List[FieldNode]]:
     """Collect fields.
 
@@ -37,10 +40,19 @@ def collect_fields(
     object type returned by that field.
 
     For internal use only.
+
+    :meta private:
     """
     fields: Dict[str, List[FieldNode]] = {}
     collect_fields_impl(
-        schema, fragments, variable_values, runtime_type, selection_set, fields, set()
+        schema,
+        fragments,
+        variable_values,
+        runtime_type,
+        selection_set,
+        fields,
+        set(),
+        on_selection_set,
     )
     return fields
 
@@ -62,6 +74,8 @@ def collect_sub_fields(
     object type returned by that field.
 
     For internal use only.
+
+    :meta private:
     """
     sub_field_nodes: Dict[str, List[FieldNode]] = {}
     visited_fragment_names: Set[str] = set()
@@ -87,8 +101,14 @@ def collect_fields_impl(
     selection_set: SelectionSetNode,
     fields: Dict[str, List[FieldNode]],
     visited_fragment_names: Set[str],
+    on_selection_set: Optional[Callable[[SelectionSetNode], None]] = None,
 ) -> None:
-    """Collect fields (internal implementation)."""
+    """Collect fields (internal implementation).
+
+    :meta private:
+    """
+    if on_selection_set:
+        on_selection_set(selection_set)
     for selection in selection_set.selections:
         if isinstance(selection, FieldNode):
             if not should_include_node(variable_values, selection):
@@ -108,6 +128,7 @@ def collect_fields_impl(
                 selection.selection_set,
                 fields,
                 visited_fragment_names,
+                on_selection_set,
             )
         elif isinstance(selection, FragmentSpreadNode):  # pragma: no cover else
             frag_name = selection.name.value
@@ -129,6 +150,7 @@ def collect_fields_impl(
                 fragment.selection_set,
                 fields,
                 visited_fragment_names,
+                on_selection_set,
             )
 
 
@@ -138,8 +160,10 @@ def should_include_node(
 ) -> bool:
     """Check if node should be included
 
-    Determines if a field should be included based on the @include and @skip
-    directives, where @skip has higher precedence than @include.
+    Determines if a field should be included based on the ``@include`` and ``@skip``
+    directives, where ``@skip`` has higher precedence than ``@include``.
+
+    :meta private:
     """
     skip = get_directive_values(GraphQLSkipDirective, node, variable_values)
     if skip and skip["if"]:
@@ -157,7 +181,10 @@ def does_fragment_condition_match(
     fragment: Union[FragmentDefinitionNode, InlineFragmentNode],
     type_: GraphQLObjectType,
 ) -> bool:
-    """Determine if a fragment is applicable to the given type."""
+    """Determine if a fragment is applicable to the given type.
+
+    :meta private:
+    """
     type_condition_node = fragment.type_condition
     if not type_condition_node:
         return True
@@ -170,5 +197,8 @@ def does_fragment_condition_match(
 
 
 def get_field_entry_key(node: FieldNode) -> str:
-    """Implements the logic to compute the key of a given field's entry"""
+    """Implement the logic to compute the key of a given field's entry.
+
+    :meta private:
+    """
     return node.alias.value if node.alias else node.name.value