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

schemathesis/specs/openapi/stateful/dependencies/models.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import difflib
+import enum
+from dataclasses import asdict, dataclass
+from typing import Any, Iterator, Mapping
+
+from typing_extensions import TypeAlias
+
+from schemathesis.core.parameters import ParameterLocation
+from schemathesis.core.transforms import encode_pointer
+
+
+@dataclass
+class DependencyGraph:
+    """Graph of API operations and their resource dependencies."""
+
+    operations: OperationMap
+    resources: ResourceMap
+
+    __slots__ = ("operations", "resources")
+
+    def serialize(self) -> dict[str, Any]:
+        serialized = asdict(self)
+
+        for operation in serialized["operations"].values():
+            del operation["method"]
+            del operation["path"]
+            for input in operation["inputs"]:
+                input["resource"] = input["resource"]["name"]
+            for output in operation["outputs"]:
+                output["resource"] = output["resource"]["name"]
+
+        for resource in serialized["resources"].values():
+            del resource["name"]
+            del resource["source"]
+
+        return serialized
+
+    def iter_links(self) -> Iterator[ResponseLinks]:
+        """Generate OpenAPI Links connecting producer and consumer operations.
+
+        Creates links from operations that produce resources to operations that
+        consume them. For example: `POST /users` (creates `User`) -> `GET /users/{id}`
+        (needs `User.id` parameter).
+        """
+        # Connect each producer output to matching consumer inputs
+        for producer in self.operations.values():
+            producer_path = encode_pointer(producer.path)
+            for output_slot in producer.outputs:
+                for consumer in self.operations.values():
+                    # Skip self-references
+                    if producer is consumer:
+                        continue
+
+                    consumer_path = encode_pointer(consumer.path)
+                    links: dict[str, LinkDefinition] = {}
+                    for input_slot in consumer.inputs:
+                        if input_slot.resource is output_slot.resource:
+                            body_pointer = build_response_body_pointer(
+                                output_slot.pointer, input_slot.resource_field, output_slot.cardinality
+                            )
+                            link_name = f"{consumer.method.capitalize()}{input_slot.resource.name}"
+                            links[link_name] = LinkDefinition(
+                                operation_ref=f"#/paths/{consumer_path}/{consumer.method}",
+                                parameters={
+                                    # Data is extracted from response body
+                                    f"{input_slot.parameter_location.value}.{input_slot.parameter_name}": f"$response.body#{body_pointer}",
+                                },
+                            )
+                    if links:
+                        yield ResponseLinks(
+                            producer_operation_ref=f"#/paths/{producer_path}/{producer.method}",
+                            status_code=output_slot.status_code,
+                            links=links,
+                        )
+
+    def assert_fieldless_resources(self, key: str, known: dict[str, frozenset[str]]) -> None:  # pragma: no cover
+        """Verify all resources have at least one field."""
+        # Fieldless resources usually indicate failed schema extraction, which can be caused by a bug
+        known_fieldless = known.get(key, frozenset())
+
+        for name, resource in self.resources.items():
+            if not resource.fields and name not in known_fieldless:
+                raise AssertionError(f"Resource {name} has no fields")
+
+    def assert_incorrect_field_mappings(self, key: str, known: dict[str, frozenset[str]]) -> None:
+        """Verify all input slots reference valid fields in their resources."""
+        known_mismatches = known.get(key, frozenset())
+
+        for operation in self.operations.values():
+            for input in operation.inputs:
+                # Skip unreliable definition sources
+                if input.resource.source < DefinitionSource.SCHEMA_WITH_PROPERTIES:
+                    continue
+                resource = self.resources[input.resource.name]
+                if (
+                    input.resource_field not in resource.fields and resource.name not in known_mismatches
+                ):  # pragma: no cover
+                    message = (
+                        f"Operation '{operation.method.upper()} {operation.path}': "
+                        f"InputSlot references field '{input.resource_field}' "
+                        f"not found in resource '{resource.name}'"
+                    )
+                    matches = difflib.get_close_matches(input.resource_field, resource.fields, n=1, cutoff=0.6)
+                    if matches:
+                        message += f". Closest field - `{matches[0]}`"
+                    elif resource.fields:
+                        message += f". Available fields - {', '.join(resource.fields)}"
+                    else:
+                        message += ". Resource has no fields"
+                    raise AssertionError(message)
+
+
+def build_response_body_pointer(pointer: str, field: str, cardinality: Cardinality) -> str:
+    if not pointer.endswith("/"):
+        pointer += "/"
+    if cardinality == Cardinality.MANY:
+        # For arrays, reference first element: /data → /data/0
+        pointer += "0/"
+    pointer += encode_pointer(field)
+    return pointer
+
+
+@dataclass
+class LinkDefinition:
+    """OpenAPI Link Object definition.
+
+    Represents a single link from a producer operation's response to a
+    consumer operation's input parameter.
+    """
+
+    operation_ref: str
+    """Reference to target operation (e.g., '#/paths/~1users~1{id}/get')"""
+
+    parameters: dict[str, str]
+    """Parameter mappings (e.g., {'path.id': '$response.body#/id'})"""
+
+    __slots__ = ("operation_ref", "parameters")
+
+    def to_openapi(self) -> dict[str, Any]:
+        """Convert to OpenAPI Links format."""
+        return {
+            "operationRef": self.operation_ref,
+            "parameters": self.parameters,
+        }
+
+
+@dataclass
+class ResponseLinks:
+    """Collection of OpenAPI Links for a producer operation's response.
+
+    Represents all links from a single response (e.g., POST /users -> 201)
+    to consumer operations that can use the produced resource.
+
+    Example:
+        POST /users -> 201 might have links to:
+        - GET /users/{id}
+        - PATCH /users/{id}
+        - DELETE /users/{id}
+
+    """
+
+    producer_operation_ref: str
+    """Reference to producer operation (e.g., '#/paths/~1users/post')"""
+
+    status_code: str
+    """Response status code (e.g., '201', '200', 'default')"""
+
+    links: dict[str, LinkDefinition]
+    """Named links (e.g., {'GetUserById': LinkDefinition(...)})"""
+
+    __slots__ = ("producer_operation_ref", "status_code", "links")
+
+    def to_openapi(self) -> dict[str, Any]:
+        """Convert to OpenAPI response links format."""
+        return {name: link_def.to_openapi() for name, link_def in self.links.items()}
+
+
+class Cardinality(str, enum.Enum):
+    """Whether there is one or many resources in a slot."""
+
+    ONE = "ONE"
+    MANY = "MANY"
+
+
+@dataclass
+class OperationNode:
+    """An API operation with its input/output dependencies."""
+
+    method: str
+    path: str
+    # What this operation NEEDS
+    inputs: list[InputSlot]
+    # What this operation PRODUCES
+    outputs: list[OutputSlot]
+
+    __slots__ = ("method", "path", "inputs", "outputs")
+
+
+@dataclass
+class InputSlot:
+    """A required input for an operation."""
+
+    # Which resource is needed
+    resource: ResourceDefinition
+    # Which field from that resource (e.g., "id")
+    resource_field: str
+    # Where it goes in the request (e.g., "userId")
+    parameter_name: str
+    parameter_location: ParameterLocation
+
+    __slots__ = ("resource", "resource_field", "parameter_name", "parameter_location")
+
+
+@dataclass
+class OutputSlot:
+    """Describes how to extract a resource from an operation's response."""
+
+    # Which resource type
+    resource: ResourceDefinition
+    # Where in response body (JSON pointer)
+    pointer: str
+    # Is this a single resource or an array?
+    cardinality: Cardinality
+    # HTTP status code
+    status_code: str
+
+    __slots__ = ("resource", "pointer", "cardinality", "status_code")
+
+
+@dataclass
+class ResourceDefinition:
+    """A minimal description of a resource structure."""
+
+    name: str
+    # A sorted list of resource fields
+    fields: list[str]
+    # How this resource was created
+    source: DefinitionSource
+
+    __slots__ = ("name", "fields", "source")
+
+    @classmethod
+    def without_properties(cls, name: str) -> ResourceDefinition:
+        return cls(name=name, fields=[], source=DefinitionSource.SCHEMA_WITHOUT_PROPERTIES)
+
+    @classmethod
+    def inferred_from_parameter(cls, name: str, parameter_name: str) -> ResourceDefinition:
+        return cls(name=name, fields=[parameter_name], source=DefinitionSource.PARAMETER_INFERENCE)
+
+
+class DefinitionSource(enum.IntEnum):
+    """Quality level of resource information.
+
+    Lower values are less reliable and should be replaced by higher values.
+    Same values should be merged (union of fields).
+    """
+
+    # From spec but no structural information
+    SCHEMA_WITHOUT_PROPERTIES = 0
+    # Guessed from parameter names (not in spec)
+    PARAMETER_INFERENCE = 1
+    # From spec with actual field definitions
+    SCHEMA_WITH_PROPERTIES = 2
+
+
+OperationMap: TypeAlias = dict[str, OperationNode]
+ResourceMap: TypeAlias = dict[str, ResourceDefinition]
+CanonicalizationCache: TypeAlias = dict[str, Mapping[str, Any]]

schemathesis/specs/openapi/stateful/dependencies/naming.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+
+def from_parameter(parameter: str, path: str) -> str | None:
+    # TODO: support other naming patterns
+    # Named like "userId" -> look for "User" resource
+    if parameter.endswith("Id"):
+        return to_pascal_case(parameter[:-2])
+    # Named like "user_id" -> look for "User" resource
+    elif parameter.endswith("_id"):
+        return to_pascal_case(parameter[:-3])
+    # Just "id" -> infer from path context
+    elif parameter == "id":
+        return from_path(path)
+    return None
+
+
+def from_path(path: str) -> str | None:
+    segments = [s for s in path.split("/") if s and "{" not in s]
+
+    if not segments:
+        # API Root
+        return None
+
+    singular = to_singular(segments[-1])
+    return to_pascal_case(singular)
+
+
+def to_singular(word: str) -> str:
+    if word.endswith("ies"):
+        return word[:-3] + "y"
+    if word.endswith("sses"):
+        return word[:-2]
+    if word.endswith(("ses", "xes", "zes", "ches", "shes")):
+        return word[:-2]
+    if word.endswith("s"):
+        return word[:-1]
+    return word
+
+
+def to_plural(word: str) -> str:
+    # party -> parties (inverse of ies -> y)
+    if word.endswith("y"):
+        return word[:-1] + "ies"
+    # class -> classes
+    if word.endswith("ss"):
+        return word + "es"
+    # words that normally take -es: box -> boxes
+    if word.endswith(("s", "x", "z", "ch", "sh")):
+        return word + "es"
+    # just add 's' (car -> cars)
+    return word + "s"
+
+
+def to_pascal_case(text: str) -> str:
+    parts = text.replace("-", "_").split("_")
+    return "".join(word.capitalize() for word in parts if word)
+
+
+def to_snake_case(text: str) -> str:
+    text = text.replace("-", "_")
+    # Insert underscores before uppercase letters
+    result = []
+    for i, char in enumerate(text):
+        # Add underscore before uppercase (except at start)
+        if i > 0 and char.isupper():
+            result.append("_")
+        result.append(char.lower())
+    return "".join(result)
+
+
+def find_matching_field(*, parameter: str, resource: str, fields: list[str]) -> str | None:
+    """Find which resource field matches the parameter name."""
+    if not fields:
+        return None
+
+    # Exact match
+    if parameter in fields:
+        return parameter
+
+    # Normalize for fuzzy matching
+    parameter_normalized = _normalize_for_matching(parameter)
+    resource_normalized = _normalize_for_matching(resource)
+
+    # Normalized exact match
+    # `brandId` -> `Brand.BrandId`
+    for field in fields:
+        if _normalize_for_matching(field) == parameter_normalized:
+            return field
+
+    # Extract parameter components
+    parameter_prefix, param_suffix = _split_parameter_name(parameter)
+    parameter_prefix_normalized = _normalize_for_matching(parameter_prefix)
+
+    # Parameter has resource prefix, field might not
+    # Example: `channelId` - `Channel.id`
+    if parameter_prefix and parameter_prefix_normalized == resource_normalized:
+        suffix_normalized = _normalize_for_matching(param_suffix)
+
+        for field in fields:
+            field_normalized = _normalize_for_matching(field)
+            if field_normalized == suffix_normalized:
+                return field
+
+    # Parameter has no prefix, field might have resource prefix
+    # Example: `id` - `Channel.channelId`
+    if not parameter_prefix and param_suffix:
+        expected_field_normalized = resource_normalized + _normalize_for_matching(param_suffix)
+
+        for field in fields:
+            field_normalized = _normalize_for_matching(field)
+            if field_normalized == expected_field_normalized:
+                return field
+
+    return None
+
+
+def _normalize_for_matching(text: str) -> str:
+    """Normalize text for case-insensitive, separator-insensitive matching.
+
+    Examples:
+        "channelId" -> "channelid"
+        "channel_id" -> "channelid"
+        "ChannelId" -> "channelid"
+        "Channel" -> "channel"
+
+    """
+    return text.lower().replace("_", "").replace("-", "")
+
+
+def _split_parameter_name(param_name: str) -> tuple[str, str]:
+    """Split parameter into (prefix, suffix) components.
+
+    Examples:
+        "channelId" -> ("channel", "Id")
+        "userId" -> ("user", "Id")
+        "user_id" -> ("user", "_id")
+        "id" -> ("", "id")
+        "channel_id" -> ("channel", "_id")
+
+    """
+    if param_name.endswith("Id") and len(param_name) > 2:
+        return (param_name[:-2], "Id")
+
+    if param_name.endswith("_id") and len(param_name) > 3:
+        return (param_name[:-3], "_id")
+
+    return ("", param_name)
+
+
+def strip_affixes(name: str, prefixes: list[str], suffixes: list[str]) -> str:
+    """Remove common prefixes and suffixes from a name (case-insensitive)."""
+    result = name.strip()
+    name_lower = result.lower()
+
+    # Remove one matching prefix
+    for prefix in prefixes:
+        if name_lower.startswith(prefix):
+            result = result[len(prefix) :]
+            break
+
+    # Remove one matching suffix
+    for suffix in suffixes:
+        if name_lower.endswith(suffix):
+            result = result[: -len(suffix)]
+            break
+
+    return result.strip()

schemathesis/specs/openapi/stateful/dependencies/outputs.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from schemathesis.specs.openapi.stateful.dependencies.models import CanonicalizationCache, OutputSlot, ResourceMap
+from schemathesis.specs.openapi.stateful.dependencies.resources import extract_resources_from_responses
+
+if TYPE_CHECKING:
+    from schemathesis.core.compat import RefResolver
+    from schemathesis.specs.openapi.schemas import APIOperation
+
+
+def extract_outputs(
+    *,
+    operation: APIOperation,
+    resources: ResourceMap,
+    updated_resources: set[str],
+    resolver: RefResolver,
+    canonicalization_cache: CanonicalizationCache,
+) -> Iterator[OutputSlot]:
+    """Extract resources from API operation's responses."""
+    for response, extracted in extract_resources_from_responses(
+        operation=operation,
+        resources=resources,
+        updated_resources=updated_resources,
+        resolver=resolver,
+        canonicalization_cache=canonicalization_cache,
+    ):
+        yield OutputSlot(
+            resource=extracted.resource,
+            pointer=extracted.pointer,
+            cardinality=extracted.cardinality,
+            status_code=response.status_code,
+        )