schemathesis 4.0.0a11__py3-none-any.whl → 4.0.0b1__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:
-        return self.hooks.register(hook)
+        """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,
@@ -368,13 +421,18 @@ class BaseSchema(Mapping):
         operation: APIOperation,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
         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,35 +452,30 @@ class BaseSchema(Mapping):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        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
 
 
 @dataclass
@@ -441,20 +494,23 @@ class APIOperationMap(Mapping):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        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)
 
@@ -560,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
@@ -607,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:
@@ -620,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,
@@ -641,16 +682,22 @@ class APIOperation(Generic[P]):
 
     def as_strategy(
         self,
-        hooks: HookDispatcher | None = None,
-        auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        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(self)
+            context = HookContext(operation=self)
             for hook in dispatcher.get_all_by_name("before_generate_case"):
                 _strategy = hook(context, _strategy)
             for hook in dispatcher.get_all_by_name("filter_case"):
@@ -666,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
@@ -674,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]:
@@ -709,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
@@ -737,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/scalars.py

@@ -13,10 +13,44 @@ CUSTOM_SCALARS: dict[str, st.SearchStrategy[graphql.ValueNode]] = {}
 
 
 def scalar(name: str, strategy: st.SearchStrategy[graphql.ValueNode]) -> None:
-    """Register a new strategy for generating custom scalars.
+    r"""Register a custom Hypothesis strategy for generating GraphQL scalar values.
+
+    Args:
+        name: Scalar name that matches your GraphQL schema scalar definition
+        strategy: Hypothesis strategy that generates GraphQL AST ValueNode objects
+
+    Example:
+        ```python
+        import schemathesis
+        from hypothesis import strategies as st
+        from schemathesis.graphql import nodes
+
+        # Register email scalar
+        schemathesis.graphql.scalar("Email", st.emails().map(nodes.String))
+
+        # Register positive integer scalar
+        schemathesis.graphql.scalar(
+            "PositiveInt",
+            st.integers(min_value=1).map(nodes.Int)
+        )
+
+        # Register phone number scalar
+        schemathesis.graphql.scalar(
+            "Phone",
+            st.from_regex(r"\+1-\d{3}-\d{3}-\d{4}").map(nodes.String)
+        )
+        ```
+
+    Schema usage:
+        ```graphql
+        scalar Email
+        scalar PositiveInt
+
+        type Query {
+          getUser(email: Email!, rating: PositiveInt!): User
+        }
+        ```
 
-    :param str name: Scalar name. It should correspond the one used in the schema.
-    :param strategy: Hypothesis strategy you'd like to use to generate values for this scalar.
     """
     from hypothesis.strategies import SearchStrategy
 

schemathesis/specs/graphql/schemas.py

@@ -115,6 +115,15 @@ class GraphQLSchema(BaseSchema):
                 return map
         raise KeyError(key)
 
+    def find_operation_by_label(self, label: str) -> APIOperation | None:
+        if label.startswith(("Query.", "Mutation.")):
+            ty, field = label.split(".", maxsplit=1)
+            try:
+                return self[ty][field]
+            except KeyError:
+                return None
+        return None
+
     def on_missing_operation(self, item: str, exc: KeyError) -> NoReturn:
         raw_schema = self.raw_schema["__schema"]
         type_names = [type_def["name"] for type_def in raw_schema.get("types", [])]
@@ -223,7 +232,7 @@ class GraphQLSchema(BaseSchema):
         operation: APIOperation,
         hooks: HookDispatcher | None = None,
         auth_storage: AuthStorage | None = None,
-        generation_mode: GenerationMode = GenerationMode.default(),
+        generation_mode: GenerationMode = GenerationMode.POSITIVE,
         **kwargs: Any,
     ) -> SearchStrategy:
         return graphql_cases(
@@ -244,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,
@@ -255,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,
@@ -321,7 +330,7 @@ def graphql_cases(
     operation: APIOperation,
     hooks: HookDispatcher | None = None,
     auth_storage: auths.AuthStorage | None = None,
-    generation_mode: GenerationMode = GenerationMode.default(),
+    generation_mode: GenerationMode = GenerationMode.POSITIVE,
     path_parameters: NotSet | dict[str, Any] = NOT_SET,
     headers: NotSet | dict[str, Any] = NOT_SET,
     cookies: NotSet | dict[str, Any] = NOT_SET,
@@ -336,7 +345,7 @@ def graphql_cases(
         RootType.QUERY: gql_st.queries,
         RootType.MUTATION: gql_st.mutations,
     }[definition.root_type]
-    hook_context = HookContext(operation)
+    hook_context = HookContext(operation=operation)
     custom_scalars = {**get_extra_scalar_strategies(), **CUSTOM_SCALARS}
     generation = operation.schema.config.generation_for(operation=operation, phase="fuzzing")
     strategy = strategy_factory(
@@ -367,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,