pytest-graphql 0.1.0a1__py3-none-any.whl

pytest_graphql/__init__.py

@@ -0,0 +1,62 @@
+"""Schema-aware GraphQL test client with an optional pytest plugin.
+
+The public API is re-exported from this module. Per C9, only names a user
+constructs, catches, annotates or calls belong in ``__all__``; a name lands
+here in the milestone that implements it, and the rest of the documented
+surface arrives with the milestones that still owe it. ``__version__`` is the
+single source of the distribution version, and the release workflow checks
+it against the tag.
+
+Importing this module imports no pytest (C41). The pytest layer lives under
+``pytest_graphql.plugin`` and nothing here reaches into it.
+"""
+
+from __future__ import annotations
+
+from pytest_graphql._core.auth import Auth, BearerAuth, HeaderAuth
+from pytest_graphql._core.client import (
+    ClientConfig,
+    GraphQLClient,
+    build_client,
+)
+from pytest_graphql._core.diagnostics import DiagnosticSnapshot, RequestInfo
+from pytest_graphql._core.errors import (
+    DiagnosticRenderError,
+    GraphQLFieldError,
+    ResponseShapeError,
+)
+from pytest_graphql._core.middleware import BaseMiddleware, Middleware
+from pytest_graphql._core.response import GraphQLResponse, Node, NodeList
+from pytest_graphql._core.schema.source import SchemaSource
+from pytest_graphql._core.selection.model import AUTO, Field, Selection
+from pytest_graphql._core.selection.policy import CyclePolicy, SelectionPolicy
+from pytest_graphql._core.transport.base import Transport
+
+__all__ = [
+    "AUTO",
+    "Auth",
+    "BaseMiddleware",
+    "BearerAuth",
+    "ClientConfig",
+    "CyclePolicy",
+    "DiagnosticRenderError",
+    "DiagnosticSnapshot",
+    "Field",
+    "GraphQLClient",
+    "GraphQLFieldError",
+    "GraphQLResponse",
+    "HeaderAuth",
+    "Middleware",
+    "Node",
+    "NodeList",
+    "RequestInfo",
+    "ResponseShapeError",
+    "SchemaSource",
+    "Selection",
+    "SelectionPolicy",
+    "Transport",
+    "__version__",
+    "build_client",
+]
+
+__version__ = "0.1.0a1"

pytest_graphql/_core/__init__.py

@@ -0,0 +1,7 @@
+"""Private implementation package.
+
+Nothing here is public API, and nothing here may import pytest. The purity check
+in ``scripts/check_core_purity.py`` enforces the second rule in CI.
+"""
+
+from __future__ import annotations

pytest_graphql/_core/auth.py

@@ -0,0 +1,89 @@
+"""The ``Auth`` protocol and the two implementations that ship (B5).
+
+``Auth.apply`` is called once per request, so a token that has to be refreshed
+is refreshed inside ``apply`` and needs no extra machinery. It sits fourth in
+the C4 header precedence chain: above ``ClientConfig.headers`` and the
+``gql_headers`` fixture, below ``with_headers()`` and a per-call ``headers=``.
+
+``apply`` receives the live ``RequestInfo`` (C2), because an implementation
+genuinely needs the real values to sign or refresh a request. The leak
+boundary is rendering, not the object, so nothing here may render one: this
+module produces a new ``RequestInfo`` and never text.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+from pytest_graphql._core.diagnostics import RequestInfo
+from pytest_graphql._core.headers import merge_headers
+
+
+@runtime_checkable
+class Auth(Protocol):
+    """One request identity (B5)."""
+
+    def apply(self, request: RequestInfo) -> RequestInfo: ...
+
+
+def with_headers(request: RequestInfo, headers: Mapping[str, str]) -> RequestInfo:
+    """``request`` with ``headers`` merged over its own, under the C4 rule.
+
+    The one place an ``Auth`` implementation in this package rewrites a
+    request, so the case-insensitive replacement rule is applied once rather
+    than at each implementation.
+    """
+    return dataclasses.replace(request, headers=merge_headers(request.headers, headers))
+
+
+class BearerAuth:
+    """``Authorization: Bearer <token>`` (B5).
+
+    The token is held as given. It reaches no representation: ``RequestInfo``
+    renders only its redacted snapshot, and ``authorization`` is in the
+    default ``redact_headers`` set, so the rendered form is a placeholder and
+    the value enters the C16 secret set for the free-form-text scrub.
+    """
+
+    __slots__ = ("token",)
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def apply(self, request: RequestInfo) -> RequestInfo:
+        return with_headers(request, {"Authorization": f"Bearer {self.token}"})
+
+    def __repr__(self) -> str:
+        return "BearerAuth(token=<redacted>)"
+
+
+class HeaderAuth:
+    """A fixed set of identity headers (B5).
+
+    B5 writes the constructor as ``HeaderAuth(**headers)``. A keyword cannot
+    spell a name containing a hyphen, and almost every real identity header
+    does, so an optional positional mapping is accepted as well, exactly as
+    B21 does for ``with_headers()`` and for the same reason:
+    ``HeaderAuth({"X-Api-Key": "v"}, Authorization="Bearer x")``.
+    """
+
+    __slots__ = ("headers",)
+
+    def __init__(
+        self, headers: Mapping[str, str] | None = None, /, **named: str
+    ) -> None:
+        self.headers = merge_headers(headers, named)
+
+    def apply(self, request: RequestInfo) -> RequestInfo:
+        return with_headers(request, self.headers)
+
+    def __repr__(self) -> str:
+        names = ", ".join(sorted(self.headers))
+        return f"HeaderAuth(names=[{names}], values=<redacted>)"
+
+
+def as_(auth: Auth | str) -> Auth:
+    """Resolve the documented shorthand: a bare string is a bearer token."""
+    return BearerAuth(auth) if isinstance(auth, str) else auth