schemathesis 4.0.0a12__py3-none-any.whl → 4.0.1__py3-none-any.whl

schemathesis/schemas.py

@@ -40,8 +40,11 @@ from .filters import (
 from .hooks import GLOBAL_HOOK_DISPATCHER, HookContext, HookDispatcher, HookScope, dispatch, to_filterable_hook
 
 if TYPE_CHECKING:
+    import httpx
+    import requests
     from hypothesis.strategies import SearchStrategy
-    from typing_extensions import Self
+    from requests.structures import CaseInsensitiveDict
+    from werkzeug.test import TestResponse
 
     from schemathesis.core import Specification
     from schemathesis.generation.stateful.state_machine import APIStateMachine
@@ -136,7 +139,25 @@ class BaseSchema(Mapping):
         operation_id: FilterValue | None = None,
         operation_id_regex: RegexValue | None = None,
     ) -> BaseSchema:
-        """Include only operations that match the given filters."""
+        """Return a new schema containing only operations matching the specified criteria.
+
+        Args:
+            func: Custom filter function that accepts operation context.
+            name: Operation name(s) to include.
+            name_regex: Regex pattern for operation names.
+            method: HTTP method(s) to include.
+            method_regex: Regex pattern for HTTP methods.
+            path: API path(s) to include.
+            path_regex: Regex pattern for API paths.
+            tag: OpenAPI tag(s) to include.
+            tag_regex: Regex pattern for OpenAPI tags.
+            operation_id: Operation ID(s) to include.
+            operation_id_regex: Regex pattern for operation IDs.
+
+        Returns:
+            New schema instance with applied include filters.
+
+        """
         filter_set = self.filter_set.clone()
         filter_set.include(
             func,
@@ -169,7 +190,26 @@ class BaseSchema(Mapping):
         operation_id_regex: RegexValue | None = None,
         deprecated: bool = False,
     ) -> BaseSchema:
-        """Include only operations that match the given filters."""
+        """Return a new schema excluding operations matching the specified criteria.
+
+        Args:
+            func: Custom filter function that accepts operation context.
+            name: Operation name(s) to exclude.
+            name_regex: Regex pattern for operation names.
+            method: HTTP method(s) to exclude.
+            method_regex: Regex pattern for HTTP methods.
+            path: API path(s) to exclude.
+            path_regex: Regex pattern for API paths.
+            tag: OpenAPI tag(s) to exclude.
+            tag_regex: Regex pattern for OpenAPI tags.
+            operation_id: Operation ID(s) to exclude.
+            operation_id_regex: Regex pattern for operation IDs.
+            deprecated: Whether to exclude deprecated operations.
+
+        Returns:
+            New schema instance with applied exclude filters.
+
+        """
         filter_set = self.filter_set.clone()
         if deprecated:
             if func is None:
@@ -211,10 +251,15 @@ class BaseSchema(Mapping):
         return self.statistic.operations.total
 
     def hook(self, hook: str | Callable) -> Callable:
+        """Register a hook function for this schema only.
+
+        Args:
+            hook: Hook name string or hook function to register.
+
+        """
         return self.hooks.hook(hook)
 
     def get_full_path(self, path: str) -> str:
-        """Compute full path for the given path."""
         return get_full_path(self.base_path, path)
 
     @property
@@ -258,19 +303,27 @@ class BaseSchema(Mapping):
         raise NotImplementedError
 
     def get_strategies_from_examples(self, operation: APIOperation, **kwargs: Any) -> list[SearchStrategy[Case]]:
-        """Get examples from the API operation."""
         raise NotImplementedError
 
     def get_security_requirements(self, operation: APIOperation) -> list[str]:
-        """Get applied security requirements for the given API operation."""
         raise NotImplementedError
 
     def get_parameter_serializer(self, operation: APIOperation, location: str) -> Callable | None:
-        """Get a function that serializes parameters for the given location."""
         raise NotImplementedError
 
     def parametrize(self) -> Callable:
-        """Mark a test function as a parametrized one."""
+        """Return a decorator that marks a test function for `pytest` parametrization.
+
+        The decorated test function will be parametrized with test cases generated
+        from the schema's API operations.
+
+        Returns:
+            Decorator function for test parametrization.
+
+        Raises:
+            IncorrectUsage: If applied to the same function multiple times.
+
+        """
 
         def wrapper(func: Callable) -> Callable:
             from schemathesis.pytest.plugin import SchemaHandleMark
@@ -293,7 +346,13 @@ class BaseSchema(Mapping):
         return wrapper
 
     def given(self, *args: GivenInput, **kwargs: GivenInput) -> Callable:
-        """Proxy Hypothesis strategies to ``hypothesis.given``."""
+        """Proxy to Hypothesis's `given` decorator for adding custom strategies.
+
+        Args:
+            *args: Positional arguments passed to `hypothesis.given`.
+            **kwargs: Keyword arguments passed to `hypothesis.given`.
+
+        """
         return given_proxy(*args, **kwargs)
 
     def clone(
@@ -320,7 +379,6 @@ class BaseSchema(Mapping):
         )
 
     def get_local_hook_dispatcher(self) -> HookDispatcher | None:
-        """Get a HookDispatcher instance bound to the test if present."""
         # It might be not present when it is used without pytest via `APIOperation.as_strategy()`
         if self.test_function is not None:
             # Might be missing it in case of `LazySchema` usage
@@ -328,7 +386,6 @@ class BaseSchema(Mapping):
         return None
 
     def dispatch_hook(self, name: str, context: HookContext, *args: Any, **kwargs: Any) -> None:
-        """Dispatch a hook via all available dispatchers."""
         dispatch(name, context, *args, **kwargs)
         self.hooks.dispatch(name, context, *args, **kwargs)
         local_dispatcher = self.get_local_hook_dispatcher()
@@ -338,10 +395,6 @@ class BaseSchema(Mapping):
     def prepare_multipart(
         self, form_data: dict[str, Any], operation: APIOperation
     ) -> tuple[list | None, dict[str, Any] | None]:
-        """Split content of `form_data` into files & data.
-
-        Forms may contain file fields, that we should send via `files` argument in `requests`.
-        """
         raise NotImplementedError
 
     def get_request_payload_content_types(self, operation: APIOperation) -> list[str]:
@@ -354,7 +407,7 @@ class BaseSchema(Mapping):
         method: str | None = None,
         path: str | None = None,
         path_parameters: dict[str, Any] | None = None,
-        headers: dict[str, Any] | None = None,
+        headers: dict[str, Any] | CaseInsensitiveDict | None = None,
         cookies: dict[str, Any] | None = None,
         query: dict[str, Any] | None = None,
         body: list | dict[str, Any] | str | int | float | bool | bytes | NotSet = NOT_SET,
@@ -374,7 +427,12 @@ class BaseSchema(Mapping):
         raise NotImplementedError
 
     def as_state_machine(self) -> type[APIStateMachine]:
-        """Create a state machine class."""
+        """Create a state machine class for stateful testing of linked API operations.
+
+        Returns:
+            APIStateMachine subclass configured for this schema.
+
+        """
         raise NotImplementedError
 
     def get_links(self, operation: APIOperation) -> dict[str, dict[str, Any]]:
@@ -394,36 +452,28 @@ class BaseSchema(Mapping):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
         generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
-        """Build a strategy for generating test cases for all defined API operations."""
+        """Create a Hypothesis strategy that generates test cases for all schema operations.
+
+        Use with `@given` in non-Schemathesis tests.
+
+        Args:
+            generation_mode: Whether to generate positive or negative test data.
+            **kwargs: Additional keywords for each strategy.
+
+        Returns:
+            Combined Hypothesis strategy for all valid operations in the schema.
+
+        """
         _strategies = [
-            operation.ok().as_strategy(
-                hooks=hooks,
-                auth_storage=auth_storage,
-                generation_mode=generation_mode,
-                **kwargs,
-            )
+            operation.ok().as_strategy(generation_mode=generation_mode, **kwargs)
             for operation in self.get_all_operations()
             if isinstance(operation, Ok)
         ]
         return strategies.combine(_strategies)
 
-    def configure(
-        self,
-        *,
-        location: str | None | NotSet = NOT_SET,
-        app: Any | NotSet = NOT_SET,
-    ) -> Self:
-        if not isinstance(location, NotSet):
-            self.location = location
-        if not isinstance(app, NotSet):
-            self.app = app
-        return self
-
     def find_operation_by_label(self, label: str) -> APIOperation | None:
         raise NotImplementedError
 
@@ -444,20 +494,23 @@ class APIOperationMap(Mapping):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
         generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
-        """Build a strategy for generating test cases for all API operations defined in this subset."""
+        """Create a Hypothesis strategy that generates test cases for all schema operations in this subset.
+
+        Use with `@given` in non-Schemathesis tests.
+
+        Args:
+            generation_mode: Whether to generate positive or negative test data.
+            **kwargs: Additional keywords for each strategy.
+
+        Returns:
+            Combined Hypothesis strategy for all valid operations in the schema.
+
+        """
         _strategies = [
-            operation.as_strategy(
-                hooks=hooks,
-                auth_storage=auth_storage,
-                generation_mode=generation_mode,
-                **kwargs,
-            )
-            for operation in self._data.values()
+            operation.as_strategy(generation_mode=generation_mode, **kwargs) for operation in self._data.values()
         ]
         return strategies.combine(_strategies)
 
@@ -563,16 +616,7 @@ class OperationDefinition(Generic[D]):
 
 @dataclass(eq=False)
 class APIOperation(Generic[P]):
-    """A single operation defined in an API.
-
-    You can get one via a ``schema`` instance.
-
-    .. code-block:: python
-
-        # Get the POST /items operation
-        operation = schema["/items"]["POST"]
-
-    """
+    """An API operation (e.g., `GET /users`)."""
 
     # `path` does not contain `basePath`
     # Example <scheme>://<host>/<basePath>/users - "/users" is path
@@ -610,7 +654,6 @@ class APIOperation(Generic[P]):
         return self.schema.get_tags(self)
 
     def iter_parameters(self) -> Iterator[P]:
-        """Iterate over all operation's parameters."""
         return chain(self.path_parameters, self.headers, self.cookies, self.query)
 
     def _lookup_container(self, location: str) -> ParameterSet[P] | PayloadAlternatives[P] | None:
@@ -623,11 +666,6 @@ class APIOperation(Generic[P]):
         }.get(location)
 
     def add_parameter(self, parameter: P) -> None:
-        """Add a new processed parameter to an API operation.
-
-        :param parameter: A parameter that will be used with this operation.
-        :rtype: None
-        """
         # If the parameter has a typo, then by default, there will be an error from `jsonschema` earlier.
         # But if the user wants to skip schema validation, we choose to ignore a malformed parameter.
         # In this case, we still might generate some tests for an API operation, but without this parameter,
@@ -644,13 +682,19 @@ class APIOperation(Generic[P]):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
         generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy[Case]:
-        """Turn this API operation into a Hypothesis strategy."""
-        strategy = self.schema.get_case_strategy(self, hooks, auth_storage, generation_mode, **kwargs)
+        """Create a Hypothesis strategy that generates test cases for this API operation.
+
+        Use with `@given` in non-Schemathesis tests.
+
+        Args:
+            generation_mode: Whether to generate positive or negative test data.
+            **kwargs: Extra arguments to the underlying strategy function.
+
+        """
+        strategy = self.schema.get_case_strategy(self, generation_mode=generation_mode, **kwargs)
 
         def _apply_hooks(dispatcher: HookDispatcher, _strategy: SearchStrategy[Case]) -> SearchStrategy[Case]:
             context = HookContext(operation=self)
@@ -669,6 +713,7 @@ class APIOperation(Generic[P]):
 
         strategy = _apply_hooks(GLOBAL_HOOK_DISPATCHER, strategy)
         strategy = _apply_hooks(self.schema.hooks, strategy)
+        hooks = kwargs.get("hooks")
         if hooks is not None:
             strategy = _apply_hooks(hooks, strategy)
         return strategy
@@ -677,15 +722,9 @@ class APIOperation(Generic[P]):
         return self.schema.get_security_requirements(self)
 
     def get_strategies_from_examples(self, **kwargs: Any) -> list[SearchStrategy[Case]]:
-        """Get examples from the API operation."""
         return self.schema.get_strategies_from_examples(self, **kwargs)
 
     def get_parameter_serializer(self, location: str) -> Callable | None:
-        """Get a function that serializes parameters for the given location.
-
-        It handles serializing data into various `collectionFormat` options and similar.
-        Note that payload is handled by this function - it is handled by serializers.
-        """
         return self.schema.get_parameter_serializer(self, location)
 
     def prepare_multipart(self, form_data: dict[str, Any]) -> tuple[list | None, dict[str, Any] | None]:
@@ -712,27 +751,37 @@ class APIOperation(Generic[P]):
         *,
         method: str | None = None,
         path_parameters: dict[str, Any] | None = None,
-        headers: dict[str, Any] | None = None,
+        headers: dict[str, Any] | CaseInsensitiveDict | None = None,
         cookies: dict[str, Any] | None = None,
         query: dict[str, Any] | None = None,
         body: list | dict[str, Any] | str | int | float | bool | bytes | NotSet = NOT_SET,
         media_type: str | None = None,
-        meta: CaseMetadata | None = None,
+        _meta: CaseMetadata | None = None,
     ) -> Case:
-        """Create a new example for this API operation.
+        """Create a test case with specific data instead of generated values.
+
+        Args:
+            method: Override HTTP method.
+            path_parameters: Override path variables.
+            headers: Override HTTP headers.
+            cookies: Override cookies.
+            query: Override query parameters.
+            body: Override request body.
+            media_type: Override media type.
 
-        The main use case is constructing Case instances completely manually, without data generation.
         """
+        from requests.structures import CaseInsensitiveDict
+
         return self.schema.make_case(
             operation=self,
             method=method,
-            path_parameters=path_parameters,
-            headers=headers,
-            cookies=cookies,
-            query=query,
+            path_parameters=path_parameters or {},
+            headers=CaseInsensitiveDict() if headers is None else CaseInsensitiveDict(headers),
+            cookies=cookies or {},
+            query=query or {},
             body=body,
             media_type=media_type,
-            meta=meta,
+            meta=_meta,
         )
 
     @property
@@ -740,15 +789,30 @@ class APIOperation(Generic[P]):
         path = self.path.replace("~", "~0").replace("/", "~1")
         return f"#/paths/{path}/{self.method}"
 
-    def validate_response(self, response: Response) -> bool | None:
-        """Validate API response for conformance.
+    def validate_response(self, response: Response | httpx.Response | requests.Response | TestResponse) -> bool | None:
+        """Validate a response against the API schema.
+
+        Args:
+            response: The HTTP response to validate. Can be a `requests.Response`,
+                `httpx.Response`, `werkzeug.test.TestResponse`, or `schemathesis.Response`.
+
+        Raises:
+            FailureGroup: If the response does not conform to the schema.
 
-        :raises FailureGroup: If the response does not conform to the API schema.
         """
-        return self.schema.validate_response(self, response)
+        return self.schema.validate_response(self, Response.from_any(response))
+
+    def is_valid_response(self, response: Response | httpx.Response | requests.Response | TestResponse) -> bool:
+        """Check if the provided response is valid against the API schema.
 
-    def is_response_valid(self, response: Response) -> bool:
-        """Validate API response for conformance."""
+        Args:
+            response: The HTTP response to validate. Can be a `requests.Response`,
+                `httpx.Response`, `werkzeug.test.TestResponse`, or `schemathesis.Response`.
+
+        Returns:
+            `True` if response is valid, `False` otherwise.
+
+        """
         try:
             self.validate_response(response)
             return True

schemathesis/specs/graphql/schemas.py

@@ -253,7 +253,7 @@ class GraphQLSchema(BaseSchema):
         method: str | None = None,
         path: str | None = None,
         path_parameters: dict[str, Any] | None = None,
-        headers: dict[str, Any] | None = None,
+        headers: dict[str, Any] | CaseInsensitiveDict | None = None,
         cookies: dict[str, Any] | None = None,
         query: dict[str, Any] | None = None,
         body: list | dict[str, Any] | str | int | float | bool | bytes | NotSet = NOT_SET,
@@ -264,10 +264,10 @@ class GraphQLSchema(BaseSchema):
             operation=operation,
             method=method or operation.method.upper(),
             path=path or operation.path,
-            path_parameters=path_parameters,
-            headers=CaseInsensitiveDict(headers) if headers is not None else headers,
-            cookies=cookies,
-            query=query,
+            path_parameters=path_parameters or {},
+            headers=CaseInsensitiveDict() if headers is None else CaseInsensitiveDict(headers),
+            cookies=cookies or {},
+            query=query or {},
             body=body,
             media_type=media_type or "application/json",
             meta=meta,
@@ -376,7 +376,7 @@ def graphql_cases(
         cookies=cookies_,
         query=query_,
         body=body,
-        meta=CaseMetadata(
+        _meta=CaseMetadata(
             generation=GenerationInfo(
                 time=time.monotonic() - start,
                 mode=generation_mode,

schemathesis/specs/openapi/_hypothesis.py

@@ -7,9 +7,11 @@ from typing import Any, Callable, Dict, Iterable, Optional, Union, cast
 from urllib.parse import quote_plus
 from weakref import WeakKeyDictionary
 
+import jsonschema.protocols
 from hypothesis import event, note, reject
 from hypothesis import strategies as st
 from hypothesis_jsonschema import from_schema
+from requests.structures import CaseInsensitiveDict
 
 from schemathesis.config import GenerationConfig
 from schemathesis.core import NOT_SET, NotSet, media_types
@@ -42,7 +44,9 @@ from .parameters import OpenAPIBody, OpenAPIParameter, parameters_to_json_schema
 from .utils import is_header_location
 
 SLASH = "/"
-StrategyFactory = Callable[[Dict[str, Any], str, str, Optional[str], GenerationConfig], st.SearchStrategy]
+StrategyFactory = Callable[
+    [Dict[str, Any], str, str, Optional[str], GenerationConfig, type[jsonschema.protocols.Validator]], st.SearchStrategy
+]
 
 
 @st.composite  # type: ignore
@@ -154,12 +158,12 @@ def openapi_cases(
 
     instance = operation.Case(
         media_type=media_type,
-        path_parameters=path_parameters_.value,
-        headers=headers_.value,
-        cookies=cookies_.value,
-        query=query_.value,
+        path_parameters=path_parameters_.value or {},
+        headers=headers_.value or CaseInsensitiveDict(),
+        cookies=cookies_.value or {},
+        query=query_.value or {},
         body=body_.value,
-        meta=CaseMetadata(
+        _meta=CaseMetadata(
             generation=GenerationInfo(
                 time=time.monotonic() - start,
                 mode=generation_mode,
@@ -195,6 +199,8 @@ def _get_body_strategy(
     operation: APIOperation,
     generation_config: GenerationConfig,
 ) -> st.SearchStrategy:
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
     if parameter.media_type in MEDIA_TYPES:
         return MEDIA_TYPES[parameter.media_type]
     # The cache key relies on object ids, which means that the parameter should not be mutated
@@ -203,7 +209,10 @@ def _get_body_strategy(
         return _BODY_STRATEGIES_CACHE[parameter][strategy_factory]
     schema = parameter.as_json_schema(operation)
     schema = operation.schema.prepare_schema(schema)
-    strategy = strategy_factory(schema, operation.label, "body", parameter.media_type, generation_config)
+    assert isinstance(operation.schema, BaseOpenAPISchema)
+    strategy = strategy_factory(
+        schema, operation.label, "body", parameter.media_type, generation_config, operation.schema.validator_cls
+    )
     if not parameter.is_required:
         strategy |= st.just(NOT_SET)
     _BODY_STRATEGIES_CACHE.setdefault(parameter, {})[strategy_factory] = strategy
@@ -337,6 +346,8 @@ def get_parameters_strategy(
     exclude: Iterable[str] = (),
 ) -> st.SearchStrategy:
     """Create a new strategy for the case's component from the API operation parameters."""
+    from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
+
     parameters = getattr(operation, LOCATION_TO_CONTAINER[location])
     if parameters:
         # The cache key relies on object ids, which means that the parameter should not be mutated
@@ -344,17 +355,28 @@ def get_parameters_strategy(
         if operation in _PARAMETER_STRATEGIES_CACHE and nested_cache_key in _PARAMETER_STRATEGIES_CACHE[operation]:
             return _PARAMETER_STRATEGIES_CACHE[operation][nested_cache_key]
         schema = get_schema_for_location(operation, location, parameters)
-        for name in exclude:
-            # Values from `exclude` are not necessarily valid for the schema - they come from user-defined examples
-            # that may be invalid
-            schema["properties"].pop(name, None)
-            with suppress(ValueError):
-                schema["required"].remove(name)
+        if location == "header" and exclude:
+            # Remove excluded headers case-insensitively
+            exclude_lower = {name.lower() for name in exclude}
+            schema["properties"] = {
+                key: value for key, value in schema["properties"].items() if key.lower() not in exclude_lower
+            }
+            if "required" in schema:
+                schema["required"] = [key for key in schema["required"] if key.lower() not in exclude_lower]
+        elif exclude:
+            # Non-header locations: remove by exact name
+            for name in exclude:
+                schema["properties"].pop(name, None)
+                with suppress(ValueError):
+                    schema["required"].remove(name)
         if not schema["properties"] and strategy_factory is make_negative_strategy:
             # Nothing to negate - all properties were excluded
             strategy = st.none()
         else:
-            strategy = strategy_factory(schema, operation.label, location, None, generation_config)
+            assert isinstance(operation.schema, BaseOpenAPISchema)
+            strategy = strategy_factory(
+                schema, operation.label, location, None, generation_config, operation.schema.validator_cls
+            )
             serialize = operation.get_parameter_serializer(location)
             if serialize is not None:
                 strategy = strategy.map(serialize)
@@ -418,6 +440,7 @@ def make_positive_strategy(
     location: str,
     media_type: str | None,
     generation_config: GenerationConfig,
+    validator_cls: type[jsonschema.protocols.Validator],
     custom_formats: dict[str, st.SearchStrategy] | None = None,
 ) -> st.SearchStrategy:
     """Strategy for generating values that fit the schema."""
@@ -448,6 +471,7 @@ def make_negative_strategy(
     location: str,
     media_type: str | None,
     generation_config: GenerationConfig,
+    validator_cls: type[jsonschema.protocols.Validator],
     custom_formats: dict[str, st.SearchStrategy] | None = None,
 ) -> st.SearchStrategy:
     custom_formats = _build_custom_formats(custom_formats, generation_config)
@@ -458,6 +482,7 @@ def make_negative_strategy(
         media_type=media_type,
         custom_formats=custom_formats,
         generation_config=generation_config,
+        validator_cls=validator_cls,
     )