schemathesis 4.1.4__py3-none-any.whl → 4.2.1__py3-none-any.whl

schemathesis/core/adapter.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar
+
+from schemathesis.core.parameters import ParameterLocation
+
+T = TypeVar("T", covariant=True)
+
+
+class ResponsesContainer(Protocol[T]):
+    def find_by_status_code(self, status_code: int) -> T | None: ...  # pragma: no cover
+    def add(self, status_code: str, definition: dict[str, Any]) -> T: ...  # pragma: no cover
+
+
+class OperationParameter(Protocol):
+    """API parameter at a specific location (query, header, body, etc.)."""
+
+    definition: Any
+    """Raw parameter definition from the API spec."""
+
+    @property
+    def location(self) -> ParameterLocation:
+        """Location: "query", "header", "body", etc."""
+        ...  # pragma: no cover
+
+    @property
+    def name(self) -> str:
+        """Parameter name."""
+        ...  # pragma: no cover
+
+    @property
+    def is_required(self) -> bool:
+        """True if required."""
+        ...  # pragma: no cover

schemathesis/core/errors.py

@@ -17,6 +17,7 @@ if TYPE_CHECKING:
 
     from schemathesis.config import OutputConfig
     from schemathesis.core.compat import RefResolutionError
+    from schemathesis.core.jsonschema import BundleError
 
 
 SCHEMA_ERROR_SUGGESTION = "Ensure that the definition complies with the OpenAPI specification"
@@ -26,11 +27,6 @@ SERIALIZATION_NOT_POSSIBLE_MESSAGE = f"No supported serializers for media types:
 SERIALIZATION_FOR_TYPE_IS_NOT_POSSIBLE_MESSAGE = (
     f"Cannot serialize to '{{}}' (unsupported media type)\n{SERIALIZERS_SUGGESTION_MESSAGE}"
 )
-RECURSIVE_REFERENCE_ERROR_MESSAGE = (
-    "Currently, Schemathesis can't generate data for this operation due to "
-    "recursive references in the operation definition. See more information in "
-    "this issue - https://github.com/schemathesis/schemathesis/issues/947"
-)
 
 
 class SchemathesisError(Exception):
@@ -50,6 +46,14 @@ class InvalidSchema(SchemathesisError):
         self.path = path
         self.method = method
 
+    @classmethod
+    def from_bundle_error(cls, error: BundleError, location: str, name: str | None = None) -> InvalidSchema:
+        if location == "body":
+            message = f"Can not generate data for {location}! {error}"
+        else:
+            message = f"Can not generate data for {location} parameter `{name}`! {error}"
+        return InvalidSchema(message)
+
     @classmethod
     def from_jsonschema_error(
         cls, error: ValidationError | JsonSchemaError, path: str | None, method: str | None, config: OutputConfig
@@ -283,6 +287,26 @@ class UnboundPrefix(SerializationError):
         super().__init__(UNBOUND_PREFIX_MESSAGE_TEMPLATE.format(prefix=prefix))
 
 
+class UnresolvableReference(SchemathesisError):
+    """A reference cannot be resolved."""
+
+    def __init__(self, reference: str) -> None:
+        self.reference = reference
+
+    def __str__(self) -> str:
+        return f"Reference `{self.reference}` cannot be resolved"
+
+
+class InfiniteRecursiveReference(SchemathesisError):
+    """Required recursive reference creates a cycle."""
+
+    def __init__(self, reference: str) -> None:
+        self.reference = reference
+
+    def __str__(self) -> str:
+        return f"Required reference `{self.reference}` creates a cycle"
+
+
 class SerializationNotPossible(SerializationError):
     """Not possible to serialize data to specified media type(s).
 

schemathesis/core/jsonschema/__init__.py

@@ -0,0 +1,13 @@
+from .bundler import BUNDLE_STORAGE_KEY, REFERENCE_TO_BUNDLE_PREFIX, BundleError, Bundler, bundle
+from .keywords import ALL_KEYWORDS
+from .types import get_type
+
+__all__ = [
+    "ALL_KEYWORDS",
+    "bundle",
+    "Bundler",
+    "BundleError",
+    "REFERENCE_TO_BUNDLE_PREFIX",
+    "BUNDLE_STORAGE_KEY",
+    "get_type",
+]

schemathesis/core/jsonschema/bundler.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from schemathesis.core.errors import InfiniteRecursiveReference
+from schemathesis.core.jsonschema.references import sanitize
+from schemathesis.core.jsonschema.types import JsonSchema, to_json_type_name
+from schemathesis.core.transforms import deepclone
+
+if TYPE_CHECKING:
+    from schemathesis.core.compat import RefResolver
+
+
+BUNDLE_STORAGE_KEY = "x-bundled"
+REFERENCE_TO_BUNDLE_PREFIX = f"#/{BUNDLE_STORAGE_KEY}"
+
+
+class BundleError(Exception):
+    def __init__(self, reference: str, value: Any) -> None:
+        self.reference = reference
+        self.value = value
+
+    def __str__(self) -> str:
+        return f"Cannot bundle `{self.reference}`: expected JSON Schema (object or boolean), got {to_json_type_name(self.value)}"
+
+
+class Bundler:
+    """Bundler tracks schema ids stored in a bundle."""
+
+    counter: int
+
+    __slots__ = ("counter",)
+
+    def __init__(self) -> None:
+        self.counter = 0
+
+    def bundle(self, schema: JsonSchema, resolver: RefResolver, *, inline_recursive: bool) -> JsonSchema:
+        """Bundle a JSON Schema by embedding all references."""
+        # Inlining recursive reference is required (for now) for data generation, but is unsound for data validation
+        if not isinstance(schema, dict):
+            return schema
+
+        # Track visited URIs and their local definition names
+        visited: set[str] = set()
+        uri_to_def_name: dict[str, str] = {}
+        defs = {}
+
+        has_recursive_references = False
+        resolve = resolver.resolve
+        visit = visited.add
+
+        def get_def_name(uri: str) -> str:
+            """Generate or retrieve the local definition name for a URI."""
+            name = uri_to_def_name.get(uri)
+            if name is None:
+                self.counter += 1
+                name = f"schema{self.counter}"
+                uri_to_def_name[uri] = name
+            return name
+
+        def bundle_recursive(current: JsonSchema | list[JsonSchema]) -> JsonSchema | list[JsonSchema]:
+            """Recursively process and bundle references in the current schema."""
+            # Local lookup is cheaper and it matters for large schemas.
+            # It works because this recursive call goes to every nested value
+            nonlocal has_recursive_references
+            _bundle_recursive = bundle_recursive
+            if isinstance(current, dict):
+                reference = current.get("$ref")
+                if isinstance(reference, str) and not reference.startswith(REFERENCE_TO_BUNDLE_PREFIX):
+                    resolved_uri, resolved_schema = resolve(reference)
+
+                    if not isinstance(resolved_schema, (dict, bool)):
+                        raise BundleError(reference, resolved_schema)
+                    def_name = get_def_name(resolved_uri)
+
+                    is_recursive_reference = resolved_uri in resolver._scopes_stack
+                    has_recursive_references |= is_recursive_reference
+                    if inline_recursive and is_recursive_reference:
+                        # This is a recursive reference! As of Sep 2025, `hypothesis-jsonschema` does not support
+                        # recursive references and Schemathesis has to remove them if possible.
+                        #
+                        # Cutting them of immediately would limit the quality of generated data, since it would have
+                        # just a single level of recursion. Currently, the only way to generate recursive data is to
+                        # inline definitions directly, which can lead to schema size explosion.
+                        #
+                        # To balance it, Schemathesis inlines one level, that avoids exponential blowup of O(B ^ L)
+                        # in worst case, where B is branching factor (number of recursive references per schema), and
+                        # L is the number of levels. Even quadratic growth can be unacceptable for large schemas.
+                        #
+                        # In the future, it **should** be handled by `hypothesis-jsonschema` instead.
+                        cloned = deepclone(resolved_schema)
+                        remaining_references = sanitize(cloned)
+                        if remaining_references:
+                            # This schema is either infinitely recursive or the sanitization logic misses it, in any
+                            # event, we git up here
+                            raise InfiniteRecursiveReference(reference)
+
+                        result = {key: _bundle_recursive(value) for key, value in current.items() if key != "$ref"}
+                        # Recursive references need `$ref` to be in them, which is only possible with `dict`
+                        assert isinstance(cloned, dict)
+                        result.update(cloned)
+                        return result
+                    elif resolved_uri not in visited:
+                        # Bundle only new schemas
+                        visit(resolved_uri)
+
+                        # Recursively bundle the embedded schema too!
+                        resolver.push_scope(resolved_uri)
+                        try:
+                            bundled_resolved = _bundle_recursive(resolved_schema)
+                        finally:
+                            resolver.pop_scope()
+
+                        defs[def_name] = bundled_resolved
+
+                        return {
+                            key: f"{REFERENCE_TO_BUNDLE_PREFIX}/{def_name}"
+                            if key == "$ref"
+                            else _bundle_recursive(value)
+                            if isinstance(value, (dict, list))
+                            else value
+                            for key, value in current.items()
+                        }
+                    else:
+                        # Already visited - just update $ref
+                        return {
+                            key: f"{REFERENCE_TO_BUNDLE_PREFIX}/{def_name}"
+                            if key == "$ref"
+                            else _bundle_recursive(value)
+                            if isinstance(value, (dict, list))
+                            else value
+                            for key, value in current.items()
+                        }
+                return {
+                    key: _bundle_recursive(value) if isinstance(value, (dict, list)) else value
+                    for key, value in current.items()
+                }
+            elif isinstance(current, list):
+                return [_bundle_recursive(item) if isinstance(item, (dict, list)) else item for item in current]  # type: ignore[misc]
+            # `isinstance` guards won't let it happen
+            # Otherwise is present to make type checker happy
+            return current  # pragma: no cover
+
+        bundled = bundle_recursive(schema)
+
+        assert isinstance(bundled, dict)
+
+        # Inlining such a schema is only possible if recursive references were inlined
+        if (inline_recursive or not has_recursive_references) and "$ref" in bundled and len(defs) == 1:
+            result = {key: value for key, value in bundled.items() if key != "$ref"}
+            for value in defs.values():
+                if isinstance(value, dict):
+                    result.update(value)
+            return result
+
+        if defs:
+            bundled[BUNDLE_STORAGE_KEY] = defs
+        return bundled
+
+
+def bundle(schema: JsonSchema, resolver: RefResolver, *, inline_recursive: bool) -> JsonSchema:
+    """Bundle a JSON Schema by embedding all references."""
+    return Bundler().bundle(schema, resolver, inline_recursive=inline_recursive)

schemathesis/{specs/openapi/constants.py → core/jsonschema/keywords.py}

@@ -1,11 +1,3 @@
-LOCATION_TO_CONTAINER = {
-    "path": "path_parameters",
-    "query": "query",
-    "header": "headers",
-    "cookie": "cookies",
-    "body": "body",
-}
-
 ALL_KEYWORDS = {
     "additionalItems",
     "additionalProperties",

schemathesis/core/jsonschema/references.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from schemathesis.core.jsonschema.keywords import ALL_KEYWORDS
+from schemathesis.core.jsonschema.types import JsonSchema, JsonSchemaObject, get_type
+
+
+def sanitize(schema: JsonSchema) -> set[str]:
+    """Remove optional parts of the schema that contain references.
+
+    It covers only the most popular cases, as removing all optional parts is complicated.
+    We might fall back to filtering out invalid cases in the future.
+    """
+    if isinstance(schema, bool):
+        return set()
+
+    stack = [schema]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, dict):
+            # Optional properties
+            if "properties" in current:
+                properties = current["properties"]
+                required = current.get("required", [])
+                for name, value in list(properties.items()):
+                    if isinstance(value, dict):
+                        if name not in required and _has_references(value):
+                            del properties[name]
+                        elif _find_single_reference_combinators(value):
+                            properties.pop(name, None)
+                        else:
+                            stack.append(value)
+
+            # Optional items
+            if "items" in current:
+                _sanitize_items(current)
+            # Not required additional properties
+            if "additionalProperties" in current:
+                _sanitize_additional_properties(current)
+            for k in _find_single_reference_combinators(current):
+                del current[k]
+
+    remaining: set[str] = set()
+    _collect_all_references(schema, remaining)
+    return remaining
+
+
+def _collect_all_references(schema: JsonSchema | list[JsonSchema], remaining: set[str]) -> None:
+    """Recursively collect all $ref present in the schema."""
+    if isinstance(schema, dict):
+        reference = schema.get("$ref")
+        if isinstance(reference, str):
+            remaining.add(reference)
+        for value in schema.values():
+            _collect_all_references(value, remaining)
+    elif isinstance(schema, list):
+        for item in schema:
+            _collect_all_references(item, remaining)
+
+
+def _has_references_in_items(items: list[JsonSchema]) -> bool:
+    return any("$ref" in item for item in items if isinstance(item, dict))
+
+
+def _has_references(schema: JsonSchemaObject) -> bool:
+    if "$ref" in schema:
+        return True
+    items = schema.get("items")
+    return (isinstance(items, dict) and "$ref" in items) or isinstance(items, list) and _has_references_in_items(items)
+
+
+def _is_optional_schema(schema: JsonSchema) -> bool:
+    # Whether this schema could be dropped from a list of schemas
+    if isinstance(schema, bool):
+        return True
+    type_ = get_type(schema)
+    if type_ == ["object"]:
+        # Empty object is valid for this schema -> could be dropped
+        return schema.get("required", []) == [] and schema.get("minProperties", 0) == 0
+    # Has at least one keyword -> should not be removed
+    return not any(k in ALL_KEYWORDS for k in schema)
+
+
+def _find_single_reference_combinators(schema: JsonSchemaObject) -> list[str]:
+    # Schema example:
+    # {
+    #     "type": "object",
+    #     "properties": {
+    #         "parent": {
+    #             "allOf": [{"$ref": "#/components/schemas/User"}]
+    #         }
+    #     }
+    # }
+    found = []
+    for keyword in ("allOf", "oneOf", "anyOf"):
+        combinator = schema.get(keyword)
+        if combinator is not None:
+            optionals = [subschema for subschema in combinator if not _is_optional_schema(subschema)]
+            # NOTE: The first schema is not bool, hence it is safe to pass it to `_has_references`
+            if len(optionals) == 1 and _has_references(optionals[0]):
+                found.append(keyword)
+    return found
+
+
+def _sanitize_items(schema: JsonSchemaObject) -> None:
+    items = schema["items"]
+    min_items = schema.get("minItems", 0)
+    if not min_items:
+        if isinstance(items, dict) and ("$ref" in items or _find_single_reference_combinators(items)):
+            _convert_to_empty_array(schema)
+        if isinstance(items, list) and _has_references_in_items(items):
+            _convert_to_empty_array(schema)
+
+
+def _convert_to_empty_array(schema: JsonSchemaObject) -> None:
+    del schema["items"]
+    schema["maxItems"] = 0
+
+
+def _sanitize_additional_properties(schema: JsonSchemaObject) -> None:
+    additional_properties = schema["additionalProperties"]
+    if isinstance(additional_properties, dict) and "$ref" in additional_properties:
+        schema["additionalProperties"] = False

schemathesis/core/jsonschema/types.py

@@ -0,0 +1,41 @@
+from typing import Any, Union
+
+JsonSchemaObject = dict[str, Any]
+JsonSchema = Union[JsonSchemaObject, bool]
+
+ANY_TYPE = ["null", "boolean", "number", "string", "array", "object"]
+ALL_TYPES = ["null", "boolean", "integer", "number", "string", "array", "object"]
+
+
+def get_type(schema: JsonSchema, *, _check_type: bool = False) -> list[str]:
+    if isinstance(schema, bool):
+        return ANY_TYPE
+    ty = schema.get("type", ANY_TYPE)
+    if isinstance(ty, str):
+        if _check_type and ty not in ALL_TYPES:
+            raise AssertionError(f"Unknown type: `{ty}`. Should be one of {', '.join(ALL_TYPES)}")
+        return [ty]
+    if ty is ANY_TYPE:
+        return list(ty)
+    return [t for t in ALL_TYPES if t in ty]
+
+
+def _get_type(schema: JsonSchema) -> list[str]:
+    # Special version to patch `hypothesis-jsonschema`
+    return get_type(schema, _check_type=True)
+
+
+def to_json_type_name(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "boolean"
+    if isinstance(v, dict):
+        return "object"
+    if isinstance(v, list):
+        return "array"
+    if isinstance(v, (int, float)):
+        return "number"
+    if isinstance(v, str):
+        return "string"
+    return type(v).__name__

schemathesis/core/media_types.py

@@ -1,10 +1,12 @@
+from __future__ import annotations
+
 from functools import lru_cache
-from typing import Generator, Tuple
+from typing import Generator
 
 from schemathesis.core.errors import MalformedMediaType
 
 
-def _parseparam(s: str) -> Generator[str, None, None]:
+def _parseparam(s: str) -> Generator[str]:
     while s[:1] == ";":
         s = s[1:]
         end = s.find(";")
@@ -17,7 +19,7 @@ def _parseparam(s: str) -> Generator[str, None, None]:
         s = s[end:]
 
 
-def _parse_header(line: str) -> Tuple[str, dict]:
+def _parse_header(line: str) -> tuple[str, dict]:
     parts = _parseparam(";" + line)
     key = parts.__next__()
     pdict = {}
@@ -34,7 +36,7 @@ def _parse_header(line: str) -> Tuple[str, dict]:
 
 
 @lru_cache
-def parse(media_type: str) -> Tuple[str, str]:
+def parse(media_type: str) -> tuple[str, str]:
     """Parse Content Type and return main type and subtype."""
     try:
         media_type, _ = _parse_header(media_type)

schemathesis/core/parameters.py

@@ -0,0 +1,37 @@
+from enum import Enum
+
+LOCATION_TO_CONTAINER = {
+    "path": "path_parameters",
+    "query": "query",
+    "header": "headers",
+    "cookie": "cookies",
+    "body": "body",
+}
+
+
+class ParameterLocation(str, Enum):
+    """API parameter location."""
+
+    QUERY = "query"
+    HEADER = "header"
+    PATH = "path"
+    COOKIE = "cookie"
+    BODY = "body"
+    UNKNOWN = None
+
+    @property
+    def container_name(self) -> str:
+        return {
+            "path": "path_parameters",
+            "query": "query",
+            "header": "headers",
+            "cookie": "cookies",
+            "body": "body",
+        }[self]
+
+    @property
+    def is_in_header(self) -> bool:
+        return self in HEADER_LOCATIONS
+
+
+HEADER_LOCATIONS = frozenset([ParameterLocation.HEADER, ParameterLocation.COOKIE])

schemathesis/core/transforms.py

@@ -1,6 +1,20 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, List, Mapping, Union, overload
+from typing import Any, Callable, Dict, List, Mapping, TypeVar, Union, overload
+
+T = TypeVar("T")
+
+
+@overload
+def deepclone(value: dict) -> dict: ...  # pragma: no cover
+
+
+@overload
+def deepclone(value: list) -> list: ...  # pragma: no cover
+
+
+@overload
+def deepclone(value: T) -> T: ...  # pragma: no cover
 
 
 def deepclone(value: Any) -> Any:
@@ -11,7 +25,16 @@ def deepclone(value: Any) -> Any:
     if isinstance(value, dict):
         return {
             k1: (
-                {k2: deepclone(v2) for k2, v2 in v1.items()}
+                {
+                    k2: (
+                        {k3: deepclone(v3) for k3, v3 in v2.items()}
+                        if isinstance(v2, dict)
+                        else [deepclone(v3) for v3 in v2]
+                        if isinstance(v2, list)
+                        else v2
+                    )
+                    for k2, v2 in v1.items()
+                }
                 if isinstance(v1, dict)
                 else [deepclone(v2) for v2 in v1]
                 if isinstance(v1, list)

schemathesis/core/validation.py

@@ -1,6 +1,8 @@
 import re
 from urllib.parse import urlparse
 
+from schemathesis.core.errors import InvalidSchema
+
 # Adapted from http.client._is_illegal_header_value
 INVALID_HEADER_RE = re.compile(r"\n(?![ \t])|\r(?![ \t\n])")
 
@@ -29,6 +31,23 @@ def is_latin_1_encodable(value: object) -> bool:
         return False
 
 
+def check_header_name(name: str) -> None:
+    from requests.exceptions import InvalidHeader
+    from requests.utils import check_header_validity
+
+    if not name:
+        raise InvalidSchema("Header name should not be empty")
+    if not name.isascii():
+        # `urllib3` encodes header names to ASCII
+        raise InvalidSchema(f"Header name should be ASCII: {name}")
+    try:
+        check_header_validity((name, ""))
+    except InvalidHeader as exc:
+        raise InvalidSchema(str(exc)) from None
+    if bool(INVALID_HEADER_RE.search(name)):
+        raise InvalidSchema(f"Invalid header name: {name}")
+
+
 SURROGATE_PAIR_RE = re.compile(r"[\ud800-\udfff]")
 _contains_surrogate_pair = SURROGATE_PAIR_RE.search
 

schemathesis/engine/context.py

@@ -95,7 +95,7 @@ class EngineContext:
             # Generate links from collected Location headers
             inferencer = LinkInferencer.from_schema(self.schema)
             for operation, entries in self.observations.location_headers.items():
-                injected += inferencer.inject_links(operation.definition.raw, entries)
+                injected += inferencer.inject_links(operation.responses, entries)
 
         return injected