schemathesis 4.0.0a10__py3-none-any.whl → 4.0.0a12__py3-none-any.whl

schemathesis/graphql/loaders.py

@@ -6,6 +6,7 @@ from os import PathLike
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any, Callable, Dict, NoReturn, TypeVar, cast
 
+from schemathesis.config import SchemathesisConfig
 from schemathesis.core.errors import LoaderError, LoaderErrorKind
 from schemathesis.core.loaders import load_from_url, prepare_request_kwargs, raise_for_status, require_relative_url
 from schemathesis.hooks import HookContext, dispatch
@@ -17,16 +18,52 @@ if TYPE_CHECKING:
     from schemathesis.specs.graphql.schemas import GraphQLSchema
 
 
-def from_asgi(path: str, app: Any, **kwargs: Any) -> GraphQLSchema:
+def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from an ASGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: ASGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the ASGI test client.
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        import schemathesis
+
+        app = FastAPI()
+        schema = schemathesis.graphql.from_asgi("/graphql", app)
+        ```
+
+    """
     require_relative_url(path)
     kwargs.setdefault("json", {"query": get_introspection_query()})
     client = asgi.get_client(app)
     response = load_from_url(client.post, url=path, **kwargs)
     schema = extract_schema_from_response(response, lambda r: r.json())
-    return from_dict(schema=schema).configure(app=app, location=path)
+    return from_dict(schema=schema, config=config).configure(app=app, location=path)
+
+
+def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> GraphQLSchema:
+    """Load GraphQL schema from a WSGI application via introspection.
+
+    Args:
+        path: Relative URL path to the GraphQL endpoint (e.g., "/graphql")
+        app: WSGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the WSGI test client.
 
+    Example:
+        ```python
+        from flask import Flask
+        import schemathesis
 
-def from_wsgi(path: str, app: Any, **kwargs: Any) -> GraphQLSchema:
+        app = Flask(__name__)
+        schema = schemathesis.graphql.from_wsgi("/graphql", app)
+        ```
+
+    """
     require_relative_url(path)
     prepare_request_kwargs(kwargs)
     kwargs.setdefault("json", {"query": get_introspection_query()})
@@ -34,27 +71,97 @@ def from_wsgi(path: str, app: Any, **kwargs: Any) -> GraphQLSchema:
     response = client.post(path=path, **kwargs)
     raise_for_status(response)
     schema = extract_schema_from_response(response, lambda r: r.json)
-    return from_dict(schema=schema).configure(app=app, location=path)
+    return from_dict(schema=schema, config=config).configure(app=app, location=path)
+
+
+def from_url(
+    url: str, *, config: SchemathesisConfig | None = None, wait_for_schema: float | None = None, **kwargs: Any
+) -> GraphQLSchema:
+    """Load GraphQL schema from a URL via introspection query.
+
+    Args:
+        url: Full URL to the GraphQL endpoint
+        config: Custom configuration. If `None`, uses auto-discovered config
+        wait_for_schema: Maximum time in seconds to wait for schema availability
+        **kwargs: Additional parameters passed to `requests.post()` (headers, timeout, auth, etc.).
 
+    Example:
+        ```python
+        import schemathesis
 
-def from_url(url: str, *, wait_for_schema: float | None = None, **kwargs: Any) -> GraphQLSchema:
-    """Load from URL."""
+        # Basic usage
+        schema = schemathesis.graphql.from_url("https://api.example.com/graphql")
+
+        # With authentication and timeout
+        schema = schemathesis.graphql.from_url(
+            "https://api.example.com/graphql",
+            headers={"Authorization": "Bearer token"},
+            timeout=30,
+            wait_for_schema=10.0
+        )
+        ```
+
+    """
     import requests
 
     kwargs.setdefault("json", {"query": get_introspection_query()})
     response = load_from_url(requests.post, url=url, wait_for_schema=wait_for_schema, **kwargs)
     schema = extract_schema_from_response(response, lambda r: r.json())
-    return from_dict(schema).configure(location=url)
+    return from_dict(schema, config=config).configure(location=url)
+
 
+def from_path(
+    path: PathLike | str, *, config: SchemathesisConfig | None = None, encoding: str = "utf-8"
+) -> GraphQLSchema:
+    """Load GraphQL schema from a filesystem path.
 
-def from_path(path: PathLike | str, *, encoding: str = "utf-8") -> GraphQLSchema:
-    """Load from a filesystem path."""
+    Args:
+        path: File path to the GraphQL schema file (.graphql, .gql)
+        config: Custom configuration. If `None`, uses auto-discovered config
+        encoding: Text encoding for reading the file
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Load from GraphQL SDL file
+        schema = schemathesis.graphql.from_path("./schema.graphql")
+        ```
+
+    """
     with open(path, encoding=encoding) as file:
-        return from_file(file=file).configure(location=Path(path).absolute().as_uri())
+        return from_file(file=file, config=config).configure(location=Path(path).absolute().as_uri())
+
+
+def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
+    """Load GraphQL schema from a file-like object or string.
+
+    Args:
+        file: File-like object or raw string containing GraphQL SDL
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
 
+        # From GraphQL SDL string
+        schema_sdl = '''
+            type Query {
+                user(id: ID!): User
+            }
+            type User {
+                id: ID!
+                name: String!
+            }
+        '''
+        schema = schemathesis.graphql.from_file(schema_sdl)
 
-def from_file(file: IO[str] | str) -> GraphQLSchema:
-    """Load from file-like object or string."""
+        # From file object
+        with open("schema.graphql") as f:
+            schema = schemathesis.graphql.from_file(f)
+        ```
+
+    """
     import graphql
 
     if isinstance(file, str):
@@ -78,18 +185,54 @@ def from_file(file: IO[str] | str) -> GraphQLSchema:
                 _on_invalid_schema(exc)
         except json.JSONDecodeError:
             _on_invalid_schema(exc, extras=[entry for entry in str(exc).splitlines() if entry])
-    return from_dict(schema)
+    return from_dict(schema, config=config)
+
+
+def from_dict(schema: dict[str, Any], *, config: SchemathesisConfig | None = None) -> GraphQLSchema:
+    """Load GraphQL schema from a dictionary containing introspection result.
+
+    Args:
+        schema: Dictionary containing GraphQL introspection result or wrapped in 'data' key
+        config: Custom configuration. If `None`, uses auto-discovered config
 
+    Example:
+        ```python
+        import schemathesis
 
-def from_dict(schema: dict[str, Any]) -> GraphQLSchema:
-    """Base loader that others build upon."""
+        # From introspection result
+        introspection = {
+            "__schema": {
+                "types": [...],
+                "queryType": {"name": "Query"},
+                # ... rest of introspection result
+            }
+        }
+        schema = schemathesis.graphql.from_dict(introspection)
+
+        # From GraphQL response format (with 'data' wrapper)
+        response_data = {
+            "data": {
+                "__schema": {
+                    "types": [...],
+                    "queryType": {"name": "Query"}
+                }
+            }
+        }
+        schema = schemathesis.graphql.from_dict(response_data)
+        ```
+
+    """
     from schemathesis.specs.graphql.schemas import GraphQLSchema
 
     if "data" in schema:
         schema = schema["data"]
     hook_context = HookContext()
     dispatch("before_load_schema", hook_context, schema)
-    instance = GraphQLSchema(schema)
+
+    if config is None:
+        config = SchemathesisConfig.discover()
+    project_config = config.projects.get(schema)
+    instance = GraphQLSchema(schema, config=project_config)
     dispatch("after_load_schema", hook_context, instance)
     return instance
 

schemathesis/hooks.py

@@ -37,13 +37,15 @@ class RegisteredHook:
 
 @dataclass
 class HookContext:
-    """A context that is passed to some hook functions.
+    """A context that is passed to some hook functions."""
 
-    :ivar Optional[APIOperation] operation: API operation that is currently being processed.
-                                            Might be absent in some cases.
-    """
+    operation: APIOperation | None
+    """API operation that is currently being processed."""
+
+    __slots__ = ("operation",)
 
-    operation: APIOperation | None = None
+    def __init__(self, *, operation: APIOperation | None = None) -> None:
+        self.operation = operation
 
 
 def to_filterable_hook(dispatcher: HookDispatcher) -> Callable:
@@ -110,48 +112,29 @@ class HookDispatcher:
     _specs: ClassVar[dict[str, RegisteredHook]] = {}
 
     def __post_init__(self) -> None:
-        self.register = to_filterable_hook(self)  # type: ignore[method-assign]
-
-    def register(self, hook: str | Callable) -> Callable:
-        """Register a new hook.
-
-        :param hook: Either a hook function or a string.
-
-        Can be used as a decorator in two forms.
-        Without arguments for registering hooks and autodetecting their names:
-
-        .. code-block:: python
-
-            @schemathesis.hook
-            def before_generate_query(context, strategy):
-                ...
-
-        With a hook name as the first argument:
-
-        .. code-block:: python
+        self.hook = to_filterable_hook(self)  # type: ignore[method-assign]
 
-            @schemathesis.hook("before_generate_query")
-            def hook(context, strategy):
-                ...
-        """
+    def hook(self, hook: str | Callable) -> Callable:
         raise NotImplementedError
 
     def apply(self, hook: Callable, *, name: str | None = None) -> Callable[[Callable], Callable]:
         """Register hook to run only on one test function.
 
-        :param hook: A hook function.
-        :param Optional[str] name: A hook name.
-
-        .. code-block:: python
+        Args:
+            hook: A hook function.
+            name: A hook name.
 
-            def before_generate_query(context, strategy):
+        Example:
+            ```python
+            def filter_query(ctx, value):
                 ...
 
 
-            @schema.hooks.apply(before_generate_query)
+            @schema.hooks.apply(filter_query)
             @schema.parametrize()
             def test_api(case):
                 ...
+            ```
 
         """
         if name is None:
@@ -391,6 +374,50 @@ def after_call(context: HookContext, case: Case, response: Response) -> None:
 GLOBAL_HOOK_DISPATCHER = HookDispatcher(scope=HookScope.GLOBAL)
 dispatch = GLOBAL_HOOK_DISPATCHER.dispatch
 get_all_by_name = GLOBAL_HOOK_DISPATCHER.get_all_by_name
-register = GLOBAL_HOOK_DISPATCHER.register
 unregister = GLOBAL_HOOK_DISPATCHER.unregister
 unregister_all = GLOBAL_HOOK_DISPATCHER.unregister_all
+
+
+def hook(hook: str | Callable) -> Callable:
+    """Register a new hook.
+
+    Args:
+        hook: Either a hook function (autodetecting its name) or a string matching one of the supported hook names.
+
+    Example:
+        Can be used as a decorator in two ways:
+
+        1. Without arguments (auto-detect the hook name from the function name):
+
+            ```python
+            @schemathesis.hook
+            def filter_query(ctx, query):
+                \"\"\"Skip cases where query is None or invalid\"\"\"
+                return query and "user_id" in query
+
+            @schemathesis.hook
+            def before_call(ctx, case):
+                \"\"\"Modify headers before sending each request\"\"\"
+                if case.headers is None:
+                    case.headers = {}
+                case.headers["X-Test-Mode"] = "true"
+                return None
+            ```
+
+        2. With an explicit hook name as the first argument:
+
+            ```python
+            @schemathesis.hook("map_headers")
+            def add_custom_header(ctx, headers):
+                \"\"\"Inject a test header into every request\"\"\"
+                if headers is None:
+                    headers = {}
+                headers["X-Custom"] = "value"
+                return headers
+            ```
+
+    """
+    return GLOBAL_HOOK_DISPATCHER.hook(hook)
+
+
+hook.__dict__ = GLOBAL_HOOK_DISPATCHER.hook.__dict__

schemathesis/openapi/checks.py

@@ -4,8 +4,9 @@ import textwrap
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
+from schemathesis.config import OutputConfig
 from schemathesis.core.failures import Failure, Severity
-from schemathesis.core.output import OutputConfig, truncate_json
+from schemathesis.core.output import truncate_json
 
 if TYPE_CHECKING:
     from jsonschema import ValidationError
@@ -141,11 +142,14 @@ class JsonSchemaError(Failure):
         title: str = "Response violates schema",
         operation: str,
         exc: ValidationError,
-        output_config: OutputConfig | None = None,
+        config: OutputConfig | None = None,
     ) -> JsonSchemaError:
-        output_config = OutputConfig.from_parent(output_config, max_lines=20)
-        schema = textwrap.indent(truncate_json(exc.schema, config=output_config), prefix="    ")
-        value = textwrap.indent(truncate_json(exc.instance, config=output_config), prefix="    ")
+        schema = textwrap.indent(
+            truncate_json(exc.schema, config=config or OutputConfig(), max_lines=20), prefix="    "
+        )
+        value = textwrap.indent(
+            truncate_json(exc.instance, config=config or OutputConfig(), max_lines=20), prefix="    "
+        )
         schema_path = list(exc.absolute_schema_path)
         if len(schema_path) > 1:
             # Exclude the last segment, which is already in the schema
@@ -336,7 +340,7 @@ class IgnoredAuth(Failure):
 class AcceptedNegativeData(Failure):
     """Response with negative data was accepted."""
 
-    __slots__ = ("operation", "message", "status_code", "allowed_statuses", "title", "case_id", "severity")
+    __slots__ = ("operation", "message", "status_code", "expected_statuses", "title", "case_id", "severity")
 
     def __init__(
         self,
@@ -344,14 +348,14 @@ class AcceptedNegativeData(Failure):
         operation: str,
         message: str,
         status_code: int,
-        allowed_statuses: list[str],
+        expected_statuses: list[str],
         title: str = "Accepted negative data",
         case_id: str | None = None,
     ) -> None:
         self.operation = operation
         self.message = message
         self.status_code = status_code
-        self.allowed_statuses = allowed_statuses
+        self.expected_statuses = expected_statuses
         self.title = title
         self.case_id = case_id
         self.severity = Severity.MEDIUM

schemathesis/openapi/generation/filters.py

@@ -1,4 +1,5 @@
 from collections.abc import Mapping
+from typing import Any
 
 from schemathesis.core import NOT_SET
 from schemathesis.core.validation import contains_unicode_surrogate_pair, has_invalid_characters, is_latin_1_encodable
@@ -21,14 +22,15 @@ def is_valid_path(parameters: dict[str, object]) -> bool:
     In this case one variable in the path template will be empty, which will lead to 404 in most of the cases.
     Because of it this case doesn't bring much value and might lead to false positives results of Schemathesis runs.
     """
-    return not any(
-        (
-            value in ("/", "")
-            or contains_unicode_surrogate_pair(value)
-            or isinstance(value, str)
-            and ("/" in value or "}" in value or "{" in value)
-        )
-        for value in parameters.values()
+    return not any(is_invalid_path_parameter(value) for value in parameters.values())
+
+
+def is_invalid_path_parameter(value: Any) -> bool:
+    return (
+        value in ("/", "")
+        or contains_unicode_surrogate_pair(value)
+        or isinstance(value, str)
+        and ("/" in value or "}" in value or "{" in value)
     )
 
 

schemathesis/openapi/loaders.py

@@ -7,6 +7,7 @@ from os import PathLike
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any, Mapping
 
+from schemathesis.config import SchemathesisConfig
 from schemathesis.core import media_types
 from schemathesis.core.deserialization import deserialize_yaml
 from schemathesis.core.errors import LoaderError, LoaderErrorKind
@@ -18,16 +19,52 @@ if TYPE_CHECKING:
     from schemathesis.specs.openapi.schemas import BaseOpenAPISchema
 
 
-def from_asgi(path: str, app: Any, **kwargs: Any) -> BaseOpenAPISchema:
+def from_asgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from an ASGI application.
+
+    Args:
+        path: Relative URL path to the OpenAPI schema endpoint (e.g., "/openapi.json")
+        app: ASGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the ASGI test client
+
+    Example:
+        ```python
+        from fastapi import FastAPI
+        import schemathesis
+
+        app = FastAPI()
+        schema = schemathesis.openapi.from_asgi("/openapi.json", app)
+        ```
+
+    """
     require_relative_url(path)
     client = asgi.get_client(app)
     response = load_from_url(client.get, url=path, **kwargs)
     content_type = detect_content_type(headers=response.headers, path=path)
     schema = load_content(response.text, content_type)
-    return from_dict(schema=schema).configure(app=app, location=path)
+    return from_dict(schema=schema, config=config).configure(app=app, location=path)
+
+
+def from_wsgi(path: str, app: Any, *, config: SchemathesisConfig | None = None, **kwargs: Any) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a WSGI application.
+
+    Args:
+        path: Relative URL path to the OpenAPI schema endpoint (e.g., "/openapi.json")
+        app: WSGI application instance
+        config: Custom configuration. If `None`, uses auto-discovered config
+        **kwargs: Additional request parameters passed to the WSGI test client
+
+    Example:
+        ```python
+        from flask import Flask
+        import schemathesis
 
+        app = Flask(__name__)
+        schema = schemathesis.openapi.from_wsgi("/openapi.json", app)
+        ```
 
-def from_wsgi(path: str, app: Any, **kwargs: Any) -> BaseOpenAPISchema:
+    """
     require_relative_url(path)
     prepare_request_kwargs(kwargs)
     client = wsgi.get_client(app)
@@ -35,29 +72,94 @@ def from_wsgi(path: str, app: Any, **kwargs: Any) -> BaseOpenAPISchema:
     raise_for_status(response)
     content_type = detect_content_type(headers=response.headers, path=path)
     schema = load_content(response.text, content_type)
-    return from_dict(schema=schema).configure(app=app, location=path)
+    return from_dict(schema=schema, config=config).configure(app=app, location=path)
 
 
-def from_url(url: str, *, wait_for_schema: float | None = None, **kwargs: Any) -> BaseOpenAPISchema:
-    """Load from URL."""
+def from_url(
+    url: str, *, config: SchemathesisConfig | None = None, wait_for_schema: float | None = None, **kwargs: Any
+) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a URL.
+
+    Args:
+        url: Full URL to the OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
+        wait_for_schema: Maximum time in seconds to wait for schema availability
+        **kwargs: Additional parameters passed to `requests.get()` (headers, timeout, auth, etc.)
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Basic usage
+        schema = schemathesis.openapi.from_url("https://api.example.com/openapi.json")
+
+        # With authentication and timeout
+        schema = schemathesis.openapi.from_url(
+            "https://api.example.com/openapi.json",
+            headers={"Authorization": "Bearer token"},
+            timeout=30,
+            wait_for_schema=10.0
+        )
+        ```
+
+    """
     import requests
 
     response = load_from_url(requests.get, url=url, wait_for_schema=wait_for_schema, **kwargs)
     content_type = detect_content_type(headers=response.headers, path=url)
     schema = load_content(response.text, content_type)
-    return from_dict(schema=schema).configure(location=url)
+    return from_dict(schema=schema, config=config).configure(location=url)
+
 
+def from_path(
+    path: PathLike | str, *, config: SchemathesisConfig | None = None, encoding: str = "utf-8"
+) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a filesystem path.
 
-def from_path(path: PathLike | str, *, encoding: str = "utf-8") -> BaseOpenAPISchema:
-    """Load from a filesystem path."""
+    Args:
+        path: File path to the OpenAPI schema (supports JSON / YAML)
+        config: Custom configuration. If `None`, uses auto-discovered config
+        encoding: Text encoding for reading the file
+
+    Example:
+        ```python
+        import schemathesis
+
+        # Load from file
+        schema = schemathesis.openapi.from_path("./specs/openapi.yaml")
+
+        # With custom encoding
+        schema = schemathesis.openapi.from_path("./specs/openapi.json", encoding="cp1252")
+        ```
+
+    """
     with open(path, encoding=encoding) as file:
         content_type = detect_content_type(headers=None, path=str(path))
         schema = load_content(file.read(), content_type)
-        return from_dict(schema=schema).configure(location=Path(path).absolute().as_uri())
+        return from_dict(schema=schema, config=config).configure(location=Path(path).absolute().as_uri())
+
+
+def from_file(file: IO[str] | str, *, config: SchemathesisConfig | None = None) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a file-like object or string.
+
+    Args:
+        file: File-like object or raw string containing the OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
+
+    Example:
+        ```python
+        import schemathesis
 
+        # From string
+        schema_content = '{"openapi": "3.0.0", "info": {"title": "API"}}'
+        schema = schemathesis.openapi.from_file(schema_content)
 
-def from_file(file: IO[str] | str) -> BaseOpenAPISchema:
-    """Load from file-like object or string."""
+        # From file object
+        with open("openapi.yaml") as f:
+            schema = schemathesis.openapi.from_file(f)
+        ```
+
+    """
     if isinstance(file, str):
         data = file
     else:
@@ -66,11 +168,30 @@ def from_file(file: IO[str] | str) -> BaseOpenAPISchema:
         schema = json.loads(data)
     except json.JSONDecodeError:
         schema = _load_yaml(data)
-    return from_dict(schema)
+    return from_dict(schema, config=config)
+
+
+def from_dict(schema: dict[str, Any], *, config: SchemathesisConfig | None = None) -> BaseOpenAPISchema:
+    """Load OpenAPI schema from a dictionary.
+
+    Args:
+        schema: Dictionary containing the parsed OpenAPI schema
+        config: Custom configuration. If `None`, uses auto-discovered config
 
+    Example:
+        ```python
+        import schemathesis
 
-def from_dict(schema: dict[str, Any]) -> BaseOpenAPISchema:
-    """Base loader that others build upon."""
+        schema_dict = {
+            "openapi": "3.0.0",
+            "info": {"title": "My API", "version": "1.0.0"},
+            "paths": {"/users": {"get": {"responses": {"200": {"description": "OK"}}}}}
+        }
+
+        schema = schemathesis.openapi.from_dict(schema_dict)
+        ```
+
+    """
     from schemathesis.specs.openapi.schemas import OpenApi30, SwaggerV20
 
     if not isinstance(schema, dict):
@@ -78,8 +199,12 @@ def from_dict(schema: dict[str, Any]) -> BaseOpenAPISchema:
     hook_context = HookContext()
     dispatch("before_load_schema", hook_context, schema)
 
+    if config is None:
+        config = SchemathesisConfig.discover()
+    project_config = config.projects.get(schema)
+
     if "swagger" in schema:
-        instance = SwaggerV20(schema)
+        instance = SwaggerV20(raw_schema=schema, config=project_config)
     elif "openapi" in schema:
         version = schema["openapi"]
         if not OPENAPI_VERSION_RE.match(version):
@@ -87,7 +212,7 @@ def from_dict(schema: dict[str, Any]) -> BaseOpenAPISchema:
                 LoaderErrorKind.OPEN_API_UNSUPPORTED_VERSION,
                 f"The provided schema uses Open API {version}, which is currently not supported.",
             )
-        instance = OpenApi30(schema)
+        instance = OpenApi30(raw_schema=schema, config=project_config)
     else:
         raise LoaderError(
             LoaderErrorKind.OPEN_API_UNSPECIFIED_VERSION,