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

schemathesis/specs/openapi/adapter/responses.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ItemsView, Iterator, Mapping, cast
+
+from schemathesis.core import NOT_SET, NotSet
+from schemathesis.core.compat import RefResolutionError, RefResolver
+from schemathesis.core.errors import InvalidSchema
+from schemathesis.core.jsonschema.bundler import bundle
+from schemathesis.core.jsonschema.types import JsonSchema
+from schemathesis.specs.openapi import types
+from schemathesis.specs.openapi.adapter.protocol import SpecificationAdapter
+from schemathesis.specs.openapi.adapter.references import maybe_resolve
+from schemathesis.specs.openapi.converter import to_json_schema
+from schemathesis.specs.openapi.utils import expand_status_code
+
+if TYPE_CHECKING:
+    from jsonschema.protocols import Validator
+
+
+@dataclass
+class OpenApiResponse:
+    """OpenAPI response definition."""
+
+    status_code: str
+    definition: Mapping[str, Any]
+    resolver: RefResolver
+    scope: str
+    adapter: SpecificationAdapter
+
+    __slots__ = ("status_code", "definition", "resolver", "scope", "adapter", "_schema", "_validator", "_headers")
+
+    def __post_init__(self) -> None:
+        self._schema: JsonSchema | None | NotSet = NOT_SET
+        self._validator: Validator | NotSet = NOT_SET
+        self._headers: OpenApiResponseHeaders | NotSet = NOT_SET
+
+    @property
+    def schema(self) -> JsonSchema | None:
+        """The response body schema extracted from its definition.
+
+        Returns `None` if the response has no schema.
+        """
+        if self._schema is NOT_SET:
+            self._schema = self.adapter.extract_response_schema(
+                self.definition, self.resolver, self.scope, self.adapter.nullable_keyword
+            )
+        assert not isinstance(self._schema, NotSet)
+        return self._schema
+
+    @property
+    def validator(self) -> Validator | None:
+        """JSON Schema validator for this response."""
+        from jsonschema import Draft202012Validator
+
+        schema = self.schema
+        if schema is None:
+            return None
+        if self._validator is NOT_SET:
+            self.adapter.jsonschema_validator_cls.check_schema(schema)
+            self._validator = self.adapter.jsonschema_validator_cls(
+                schema,
+                # Use a recent JSON Schema format checker to get most of formats checked for older drafts as well
+                format_checker=Draft202012Validator.FORMAT_CHECKER,
+                resolver=RefResolver.from_schema(schema),
+            )
+        assert not isinstance(self._validator, NotSet)
+        return self._validator
+
+    @property
+    def headers(self) -> OpenApiResponseHeaders:
+        """A collection of header definitions for this response."""
+        if self._headers is NOT_SET:
+            headers = self.definition.get("headers", {})
+            self._headers = OpenApiResponseHeaders(
+                dict(_iter_resolved_headers(headers, self.resolver, self.scope, self.adapter))
+            )
+        assert not isinstance(self._headers, NotSet)
+        return self._headers
+
+    def iter_examples(self) -> Iterator[tuple[str, object]]:
+        """Iterate over examples of this response."""
+        return self.adapter.iter_response_examples(self.definition, self.status_code)
+
+    def iter_links(self) -> Iterator[tuple[str, Mapping[str, Any]]]:
+        links = self.definition.get(self.adapter.links_keyword)
+        if links is None:
+            return
+        for name, link in links.items():
+            _, link = maybe_resolve(link, self.resolver, self.scope)
+            yield name, link
+
+
+@dataclass
+class OpenApiResponses:
+    """Collection of OpenAPI response definitions."""
+
+    _inner: dict[str, OpenApiResponse]
+    resolver: RefResolver
+    scope: str
+    adapter: SpecificationAdapter
+
+    __slots__ = ("_inner", "resolver", "scope", "adapter")
+
+    @classmethod
+    def from_definition(
+        cls, definition: types.v3.Responses, resolver: RefResolver, scope: str, adapter: SpecificationAdapter
+    ) -> OpenApiResponses:
+        """Build new collection of responses from their raw definition."""
+        # TODO: Add also `v2` type
+        return cls(
+            dict(_iter_resolved_responses(definition=definition, resolver=resolver, scope=scope, adapter=adapter)),
+            resolver=resolver,
+            scope=scope,
+            adapter=adapter,
+        )
+
+    def items(self) -> ItemsView[str, OpenApiResponse]:
+        return self._inner.items()
+
+    def add(self, status_code: str, definition: dict[str, Any]) -> OpenApiResponse:
+        instance = OpenApiResponse(
+            status_code=status_code,
+            definition=definition,
+            resolver=self.resolver,
+            scope=self.scope,
+            adapter=self.adapter,
+        )
+        self._inner[status_code] = instance
+        return instance
+
+    @property
+    def status_codes(self) -> tuple[str, ...]:
+        """All defined status codes."""
+        # Defined as a tuple, so it can be used in a cache key
+        return tuple(self._inner)
+
+    def find_by_status_code(self, status_code: int) -> OpenApiResponse | None:
+        """Find the most specific response definition matching the given HTTP status code."""
+        responses = self._inner
+        # Full match has the highest priority
+        full_match = responses.get(str(status_code))
+        if full_match is not None:
+            return full_match
+        # Then, ones with wildcards
+        keys = sorted(responses, key=lambda k: k.count("X"))
+        for key in keys:
+            if key == "default":
+                continue
+            status_codes = expand_status_code(key)
+            if status_code in status_codes:
+                return responses[key]
+        # The default response has the lowest priority
+        return responses.get("default")
+
+    def iter_examples(self) -> Iterator[tuple[str, object]]:
+        """Iterate over all examples for all responses."""
+        for response in self._inner.values():
+            # Check only 2xx responses
+            if response.status_code.startswith("2"):
+                yield from response.iter_examples()
+
+
+def _iter_resolved_responses(
+    definition: types.v3.Responses, resolver: RefResolver, scope: str, adapter: SpecificationAdapter
+) -> Iterator[tuple[str, OpenApiResponse]]:
+    for key, response in definition.items():
+        status_code = str(key)
+        scope, resolved = maybe_resolve(response, resolver, scope)
+        yield (
+            status_code,
+            OpenApiResponse(
+                status_code=status_code, definition=resolved, resolver=resolver, scope=scope, adapter=adapter
+            ),
+        )
+
+
+def extract_response_schema_v2(
+    response: Mapping[str, Any], resolver: RefResolver, scope: str, nullable_keyword: str
+) -> JsonSchema | None:
+    schema = response.get("schema")
+    if schema is not None:
+        return _prepare_schema(schema, resolver, scope, nullable_keyword)
+    return None
+
+
+def extract_response_schema_v3(
+    response: Mapping[str, Any], resolver: RefResolver, scope: str, nullable_keyword: str
+) -> JsonSchema | None:
+    options = iter(response.get("content", {}).values())
+    media_type = next(options, None)
+    # "schema" is an optional key in the `MediaType` object
+    if media_type and "schema" in media_type:
+        return _prepare_schema(media_type["schema"], resolver, scope, nullable_keyword)
+    return None
+
+
+def _prepare_schema(schema: JsonSchema, resolver: RefResolver, scope: str, nullable_keyword: str) -> JsonSchema:
+    schema = _bundle_in_scope(schema, resolver, scope)
+    # Do not clone the schema, as bundling already does it
+    return to_json_schema(schema, nullable_keyword, is_response_schema=True, update_quantifiers=False, clone=False)
+
+
+def _bundle_in_scope(schema: JsonSchema, resolver: RefResolver, scope: str) -> JsonSchema:
+    resolver.push_scope(scope)
+    try:
+        return bundle(schema, resolver, inline_recursive=False)
+    except RefResolutionError as exc:
+        raise InvalidSchema.from_reference_resolution_error(exc, None, None) from None
+    finally:
+        resolver.pop_scope()
+
+
+@dataclass
+class OpenApiResponseHeaders:
+    """Collection of OpenAPI response header definitions."""
+
+    _inner: dict[str, OpenApiResponseHeader]
+
+    __slots__ = ("_inner",)
+
+    def __bool__(self) -> bool:
+        return bool(self._inner)
+
+    def items(self) -> ItemsView[str, OpenApiResponseHeader]:
+        return self._inner.items()
+
+
+@dataclass
+class OpenApiResponseHeader:
+    """OpenAPI response header definition."""
+
+    name: str
+    definition: Mapping[str, Any]
+    resolver: RefResolver
+    scope: str
+    adapter: SpecificationAdapter
+
+    __slots__ = ("name", "definition", "resolver", "scope", "adapter", "_schema", "_validator")
+
+    def __post_init__(self) -> None:
+        self._schema: JsonSchema | NotSet = NOT_SET
+        self._validator: Validator | NotSet = NOT_SET
+
+    @property
+    def is_required(self) -> bool:
+        return self.definition.get(self.adapter.header_required_keyword, False)
+
+    @property
+    def schema(self) -> JsonSchema:
+        """The header schema extracted from its definition."""
+        if self._schema is NOT_SET:
+            self._schema = self.adapter.extract_header_schema(
+                self.definition, self.resolver, self.scope, self.adapter.nullable_keyword
+            )
+        assert not isinstance(self._schema, NotSet)
+        return self._schema
+
+    @property
+    def validator(self) -> Validator:
+        """JSON Schema validator for this header."""
+        from jsonschema import Draft202012Validator
+
+        schema = self.schema
+        if self._validator is NOT_SET:
+            self.adapter.jsonschema_validator_cls.check_schema(schema)
+            self._validator = self.adapter.jsonschema_validator_cls(
+                schema,
+                # Use a recent JSON Schema format checker to get most of formats checked for older drafts as well
+                format_checker=Draft202012Validator.FORMAT_CHECKER,
+                resolver=RefResolver.from_schema(schema),
+            )
+        assert not isinstance(self._validator, NotSet)
+        return self._validator
+
+
+def _iter_resolved_headers(
+    definition: types.v3.Headers, resolver: RefResolver, scope: str, adapter: SpecificationAdapter
+) -> Iterator[tuple[str, OpenApiResponseHeader]]:
+    for name, header in definition.items():
+        scope, resolved = maybe_resolve(header, resolver, scope)
+        yield (
+            name,
+            OpenApiResponseHeader(name=name, definition=resolved, resolver=resolver, scope=scope, adapter=adapter),
+        )
+
+
+def extract_header_schema_v2(
+    header: Mapping[str, Any], resolver: RefResolver, scope: str, nullable_keyword: str
+) -> JsonSchema:
+    return _prepare_schema(cast(dict, header), resolver, scope, nullable_keyword)
+
+
+def extract_header_schema_v3(
+    header: Mapping[str, Any], resolver: RefResolver, scope: str, nullable_keyword: str
+) -> JsonSchema:
+    schema = header.get("schema", {})
+    return _prepare_schema(schema, resolver, scope, nullable_keyword)
+
+
+def iter_response_examples_v2(response: Mapping[str, Any], status_code: str) -> Iterator[tuple[str, object]]:
+    # In Swagger 2.0, examples are directly in the response under "examples"
+    examples = response.get("examples", {})
+    return iter(examples.items())
+
+
+def iter_response_examples_v3(response: Mapping[str, Any], status_code: str) -> Iterator[tuple[str, object]]:
+    for media_type, definition in response.get("content", {}).items():
+        # Try to get a more descriptive example name from the `$ref` value
+        schema_ref = definition.get("schema", {}).get("$ref")
+        if schema_ref:
+            name = schema_ref.split("/")[-1]
+        else:
+            name = f"{status_code}/{media_type}"
+
+        for examples_container_keyword, example_keyword in (
+            ("examples", "example"),
+            ("x-examples", "x-example"),
+        ):
+            examples = definition.get(examples_container_keyword, {})
+            if isinstance(examples, dict):
+                for example in examples.values():
+                    if "value" in example:
+                        yield name, example["value"]
+            elif isinstance(examples, list):
+                for example in examples:
+                    yield name, example
+            if example_keyword in definition:
+                yield name, definition[example_keyword]

schemathesis/specs/openapi/adapter/security.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Iterator, Mapping
+
+if TYPE_CHECKING:
+    from schemathesis.core.compat import RefResolver
+    from schemathesis.specs.openapi.adapter.protocol import SpecificationAdapter
+
+ORIGINAL_SECURITY_TYPE_KEY = "x-original-securuty-type"
+
+
+@dataclass
+class OpenApiSecurityParameters:
+    """Security parameters for an API operation."""
+
+    _parameters: list[Mapping[str, Any]]
+
+    __slots__ = ("_parameters",)
+
+    @classmethod
+    def from_definition(
+        cls,
+        schema: Mapping[str, Any],
+        operation: Mapping[str, Any],
+        resolver: RefResolver,
+        adapter: SpecificationAdapter,
+    ) -> OpenApiSecurityParameters:
+        return cls(list(adapter.extract_security_parameters(schema, operation, resolver)))
+
+    def iter_parameters(self) -> Iterator[Mapping[str, Any]]:
+        return iter(self._parameters)
+
+
+def extract_security_parameters_v2(
+    schema: Mapping[str, Any], operation: Mapping[str, Any], resolver: RefResolver
+) -> Iterator[Mapping[str, Any]]:
+    """Extract all required security parameters for this operation."""
+    defined = extract_security_definitions_v2(schema, resolver)
+    required = get_security_requirements(schema, operation)
+    optional = has_optional_auth(schema, operation)
+
+    for key in required:
+        if key not in defined:
+            continue
+        definition = defined[key]
+        ty = definition["type"]
+
+        if ty == "apiKey":
+            param = make_api_key_schema(definition, type="string")
+        elif ty == "basic":
+            parameter_schema = make_auth_header_schema(definition)
+            param = make_auth_header(**parameter_schema)
+        else:
+            continue
+
+        param[ORIGINAL_SECURITY_TYPE_KEY] = ty
+
+        if optional:
+            param = {**param, "required": False}
+
+        yield param
+
+
+def extract_security_parameters_v3(
+    schema: Mapping[str, Any],
+    operation: Mapping[str, Any],
+    resolver: RefResolver,
+) -> Iterator[Mapping[str, Any]]:
+    """Extract all required security parameters for this operation."""
+    defined = extract_security_definitions_v3(schema, resolver)
+    required = get_security_requirements(schema, operation)
+    optional = has_optional_auth(schema, operation)
+
+    for key in required:
+        if key not in defined:
+            continue
+        definition = defined[key]
+        ty = definition["type"]
+
+        if ty == "apiKey":
+            param = make_api_key_schema(definition, schema={"type": "string"})
+        elif ty == "http":
+            parameter_schema = make_auth_header_schema(definition)
+            param = make_auth_header(schema=parameter_schema)
+        else:
+            continue
+
+        param[ORIGINAL_SECURITY_TYPE_KEY] = ty
+
+        if optional:
+            param = {**param, "required": False}
+
+        yield param
+
+
+def make_auth_header_schema(definition: dict[str, Any]) -> dict[str, str]:
+    schema = definition.get("scheme", "basic").lower()
+    return {"type": "string", "format": f"_{schema}_auth"}
+
+
+def make_auth_header(**kwargs: Any) -> dict[str, Any]:
+    return {"name": "Authorization", "in": "header", "required": True, **kwargs}
+
+
+def make_api_key_schema(definition: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+    return {"name": definition["name"], "required": True, "in": definition["in"], **kwargs}
+
+
+def get_security_requirements(schema: Mapping[str, Any], operation: Mapping[str, Any]) -> list[str]:
+    requirements = operation.get("security", schema.get("security", []))
+    return [key for requirement in requirements for key in requirement]
+
+
+def has_optional_auth(schema: Mapping[str, Any], operation: Mapping[str, Any]) -> bool:
+    return {} in operation.get("security", schema.get("security", []))
+
+
+def extract_security_definitions_v2(schema: Mapping[str, Any], resolver: RefResolver) -> Mapping[str, Any]:
+    return schema.get("securityDefinitions", {})
+
+
+def extract_security_definitions_v3(schema: Mapping[str, Any], resolver: RefResolver) -> Mapping[str, Any]:
+    """In Open API 3 security definitions are located in ``components`` and may have references inside."""
+    components = schema.get("components", {})
+    security_schemes = components.get("securitySchemes", {})
+    # At this point, the resolution scope could differ from the root scope, that's why we need to restore it
+    # as now we resolve root-level references
+    if len(resolver._scopes_stack) > 1:
+        scope = resolver.resolution_scope
+        resolver.pop_scope()
+    else:
+        scope = None
+    resolve = resolver.resolve
+    try:
+        if "$ref" in security_schemes:
+            return resolve(security_schemes["$ref"])[1]
+        return {key: resolve(value["$ref"])[1] if "$ref" in value else value for key, value in security_schemes.items()}
+    finally:
+        if scope is not None:
+            resolver._scopes_stack.append(scope)

schemathesis/specs/openapi/adapter/v2.py

@@ -0,0 +1,28 @@
+from jsonschema import Draft4Validator
+
+from schemathesis.specs.openapi.adapter import parameters, responses, security
+from schemathesis.specs.openapi.adapter.protocol import (
+    BuildPathParameter,
+    ExtractHeaderSchema,
+    ExtractParameterSchema,
+    ExtractResponseSchema,
+    ExtractSecurityParameters,
+    IterParameters,
+    IterResponseExamples,
+)
+
+nullable_keyword = "x-nullable"
+header_required_keyword = "x-required"
+links_keyword = "x-links"
+example_keyword = "x-example"
+examples_container_keyword = "x-examples"
+
+extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v2
+extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v2
+extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v2
+iter_parameters: IterParameters = parameters.iter_parameters_v2
+build_path_parameter: BuildPathParameter = parameters.build_path_parameter_v2
+iter_response_examples: IterResponseExamples = responses.iter_response_examples_v2
+extract_security_parameters: ExtractSecurityParameters = security.extract_security_parameters_v2
+
+jsonschema_validator_cls = Draft4Validator

schemathesis/specs/openapi/adapter/v3_0.py

@@ -0,0 +1,28 @@
+from jsonschema import Draft4Validator
+
+from schemathesis.specs.openapi.adapter import parameters, responses, security
+from schemathesis.specs.openapi.adapter.protocol import (
+    BuildPathParameter,
+    ExtractHeaderSchema,
+    ExtractParameterSchema,
+    ExtractResponseSchema,
+    ExtractSecurityParameters,
+    IterParameters,
+    IterResponseExamples,
+)
+
+nullable_keyword = "nullable"
+header_required_keyword = "required"
+links_keyword = "links"
+example_keyword = "example"
+examples_container_keyword = "examples"
+
+extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v3
+extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v3
+extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v3
+iter_parameters: IterParameters = parameters.iter_parameters_v3
+build_path_parameter: BuildPathParameter = parameters.build_path_parameter_v3_0
+iter_response_examples: IterResponseExamples = responses.iter_response_examples_v3
+extract_security_parameters: ExtractSecurityParameters = security.extract_security_parameters_v3
+
+jsonschema_validator_cls = Draft4Validator

schemathesis/specs/openapi/adapter/v3_1.py

@@ -0,0 +1,28 @@
+from jsonschema import Draft202012Validator
+
+from schemathesis.specs.openapi.adapter import parameters, responses, security
+from schemathesis.specs.openapi.adapter.protocol import (
+    BuildPathParameter,
+    ExtractHeaderSchema,
+    ExtractParameterSchema,
+    ExtractResponseSchema,
+    ExtractSecurityParameters,
+    IterParameters,
+    IterResponseExamples,
+)
+
+nullable_keyword = "nullable"
+header_required_keyword = "required"
+links_keyword = "links"
+example_keyword = "example"
+examples_container_keyword = "examples"
+
+extract_parameter_schema: ExtractParameterSchema = parameters.extract_parameter_schema_v3
+extract_response_schema: ExtractResponseSchema = responses.extract_response_schema_v3
+extract_header_schema: ExtractHeaderSchema = responses.extract_header_schema_v3
+iter_parameters: IterParameters = parameters.iter_parameters_v3
+build_path_parameter: BuildPathParameter = parameters.build_path_parameter_v3_1
+iter_response_examples: IterResponseExamples = responses.iter_response_examples_v3
+extract_security_parameters: ExtractSecurityParameters = security.extract_security_parameters_v3
+
+jsonschema_validator_cls = Draft202012Validator