basst 0.1.0__tar.gz

basst-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.3
+Name: basst
+Version: 0.1.0
+Summary: Fluent HTTP API testing library with Pydantic model binding
+Author: Gitznik
+Author-email: Gitznik <dev@robswebhub.net>
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Hypex (working name)
+
+Pydantic-first HTTP testing client for Python. Fluent request builder, one-step model binding, native Python assertions.
+
+## Install
+
+```bash
+pip install hypex
+```
+
+## Quick Start
+
+```python
+from hypex import Client, matchers
+from pydantic import BaseModel
+
+
+class Address(BaseModel):
+    city: str
+    zip: str
+
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+    age: int | None
+    roles: list[str]
+    address: Address
+
+
+api = Client("https://api.example.com")
+
+user = (
+    api.get(f"/users/{user_id}")
+    .header("X-Token", "secret")
+    .expect()
+    .status(200)
+    .header("content-type", matchers.contains("json"))
+    .model(User)
+)
+
+assert user.name == "Ada"
+assert "@" in user.email
+assert "admin" in user.roles
+assert user.address.city == "Paris"
+```
+
+## Request Building
+
+```python
+api = Client(
+    "https://api.example.com",
+    headers={"X-Token": "secret"},
+    auth=("user", "pass"),
+    timeout=5.0,
+)
+
+# Builder methods are chainable
+resp = (
+    api.post("/users")
+    .json({"name": "Ada", "email": "ada@example.com"})
+    .header("X-Request-Id", "abc123")
+    .timeout(10.0)
+    .expect()
+)
+
+user = resp.status(201).model(User)
+assert user.name == "Ada"
+```
+
+## Collections
+
+```python
+users = (
+    api.get("/users")
+    .query(page=1, limit=10)
+    .expect()
+    .status(200)
+    .model_list(User)
+)
+
+assert len(users) > 0
+assert users[0].name == "Ada"
+```
+
+## Response Assertions
+
+Assertion methods are chainable and raise on failure:
+
+```python
+from hypex import matchers
+
+resp = api.get(f"/users/{user_id}").expect()
+
+# Chain status and header assertions, then bind model
+user = (
+    resp
+    .status(200)
+    .header("content-type", matchers.contains("json"))
+    .header("x-request-id")  # no matcher — just asserts the header exists
+    .model(User)
+)
+```
+
+## Matchers
+
+The `matchers` module provides built-in assertion functions for header values:
+
+```python
+from hypex import matchers
+
+matchers.equals("application/json")
+matchers.contains("json")
+matchers.starts_with("application/")
+matchers.ends_with("+json")
+matchers.matches(r"^application/(json|.+\+json)$")  # regex
+```
+
+A matcher is any callable `(str) -> None` that raises `AssertionError` on failure.
+Write your own for reusable, domain-specific checks:
+
+```python
+import uuid
+
+def is_uuid(value: str) -> None:
+    try:
+        uuid.UUID(value)
+    except ValueError:
+        raise AssertionError(f"Expected UUID, got: {value}")
+
+resp.header("x-request-id", is_uuid)
+```
+
+## Raw Response Access
+
+Accessor methods return values for use in plain Python:
+
+```python
+resp = api.get("/health").expect()
+
+# Raw values
+code = resp.status_code
+content_type = resp.get_header("content-type")
+all_headers = resp.get_headers()
+data = resp.json()
+text = resp.text
+```
+
+## Content-Type Validation
+
+Model binding validates the response content-type before parsing. By default,
+`application/json` and any `+json` suffix are accepted.
+
+```python
+# Default: accepts application/json, application/problem+json,
+# application/vnd.api+json, etc.
+user = resp.model(User)
+
+# Prefix match: assert it's specifically application/problem+json
+problem = resp.model(ProblemDetail, content_type="problem")
+
+# Exact match: full MIME type
+data = resp.model(MyModel, content_type="application/vnd.api+json")
+
+# Skip content-type validation entirely
+data = resp.model(MyModel, content_type=None)
+```
+
+## Async
+
+```python
+from hypex import AsyncClient
+
+aapi = AsyncClient("https://api.example.com")
+
+# await at .expect() — everything after is synchronous
+resp = await aapi.get(f"/users/{user_id}").expect()
+user = resp.status(200).model(User)
+assert user.name == "Ada"
+```
+
+## Context Managers
+
+```python
+# Sync
+with Client("https://api.example.com") as api:
+    user = api.get(f"/users/{user_id}").expect().status(200).model(User)
+
+# Async
+async with AsyncClient("https://api.example.com") as api:
+    resp = await api.get(f"/users/{user_id}").expect()
+    user = resp.status(200).model(User)
+```
+
+## Error Messages
+
+When things fail, hypex provides context about the request and response:
+
+```
+hypex.StatusError: Expected status 200, got 404
+  GET https://api.example.com/users/999
+  Response body: {"detail": "Not found"}
+
+hypex.HeaderError: Header "x-cache" expected to equal "HIT", got "MISS"
+  GET https://api.example.com/users/1
+
+hypex.ContentTypeError: Expected JSON-compatible content-type, got text/html
+  GET https://api.example.com/users/1
+  Response body: <html>...
+
+hypex.ModelError: Failed to validate response as User
+  GET https://api.example.com/users/1
+  Response body: {"id": "not-an-int", "name": "Ada", ...}
+  Validation errors:
+    id: Input should be a valid integer [type=int_parsing]
+```
+
+## Design Principles
+
+- Pydantic models are the primary response surface.
+- `model()` and `model_list()` return real model instances, not proxies.
+- Use native Python assertions on model fields.
+- No custom assertion DSL, no JSONPath, no string selectors.
+- The async boundary is only at `.expect()` — everything after is synchronous.
+- Client is reusable — each verb call creates a fresh request builder.

basst-0.1.0/README.md

@@ -0,0 +1,226 @@
+# Hypex (working name)
+
+Pydantic-first HTTP testing client for Python. Fluent request builder, one-step model binding, native Python assertions.
+
+## Install
+
+```bash
+pip install hypex
+```
+
+## Quick Start
+
+```python
+from hypex import Client, matchers
+from pydantic import BaseModel
+
+
+class Address(BaseModel):
+    city: str
+    zip: str
+
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+    age: int | None
+    roles: list[str]
+    address: Address
+
+
+api = Client("https://api.example.com")
+
+user = (
+    api.get(f"/users/{user_id}")
+    .header("X-Token", "secret")
+    .expect()
+    .status(200)
+    .header("content-type", matchers.contains("json"))
+    .model(User)
+)
+
+assert user.name == "Ada"
+assert "@" in user.email
+assert "admin" in user.roles
+assert user.address.city == "Paris"
+```
+
+## Request Building
+
+```python
+api = Client(
+    "https://api.example.com",
+    headers={"X-Token": "secret"},
+    auth=("user", "pass"),
+    timeout=5.0,
+)
+
+# Builder methods are chainable
+resp = (
+    api.post("/users")
+    .json({"name": "Ada", "email": "ada@example.com"})
+    .header("X-Request-Id", "abc123")
+    .timeout(10.0)
+    .expect()
+)
+
+user = resp.status(201).model(User)
+assert user.name == "Ada"
+```
+
+## Collections
+
+```python
+users = (
+    api.get("/users")
+    .query(page=1, limit=10)
+    .expect()
+    .status(200)
+    .model_list(User)
+)
+
+assert len(users) > 0
+assert users[0].name == "Ada"
+```
+
+## Response Assertions
+
+Assertion methods are chainable and raise on failure:
+
+```python
+from hypex import matchers
+
+resp = api.get(f"/users/{user_id}").expect()
+
+# Chain status and header assertions, then bind model
+user = (
+    resp
+    .status(200)
+    .header("content-type", matchers.contains("json"))
+    .header("x-request-id")  # no matcher — just asserts the header exists
+    .model(User)
+)
+```
+
+## Matchers
+
+The `matchers` module provides built-in assertion functions for header values:
+
+```python
+from hypex import matchers
+
+matchers.equals("application/json")
+matchers.contains("json")
+matchers.starts_with("application/")
+matchers.ends_with("+json")
+matchers.matches(r"^application/(json|.+\+json)$")  # regex
+```
+
+A matcher is any callable `(str) -> None` that raises `AssertionError` on failure.
+Write your own for reusable, domain-specific checks:
+
+```python
+import uuid
+
+def is_uuid(value: str) -> None:
+    try:
+        uuid.UUID(value)
+    except ValueError:
+        raise AssertionError(f"Expected UUID, got: {value}")
+
+resp.header("x-request-id", is_uuid)
+```
+
+## Raw Response Access
+
+Accessor methods return values for use in plain Python:
+
+```python
+resp = api.get("/health").expect()
+
+# Raw values
+code = resp.status_code
+content_type = resp.get_header("content-type")
+all_headers = resp.get_headers()
+data = resp.json()
+text = resp.text
+```
+
+## Content-Type Validation
+
+Model binding validates the response content-type before parsing. By default,
+`application/json` and any `+json` suffix are accepted.
+
+```python
+# Default: accepts application/json, application/problem+json,
+# application/vnd.api+json, etc.
+user = resp.model(User)
+
+# Prefix match: assert it's specifically application/problem+json
+problem = resp.model(ProblemDetail, content_type="problem")
+
+# Exact match: full MIME type
+data = resp.model(MyModel, content_type="application/vnd.api+json")
+
+# Skip content-type validation entirely
+data = resp.model(MyModel, content_type=None)
+```
+
+## Async
+
+```python
+from hypex import AsyncClient
+
+aapi = AsyncClient("https://api.example.com")
+
+# await at .expect() — everything after is synchronous
+resp = await aapi.get(f"/users/{user_id}").expect()
+user = resp.status(200).model(User)
+assert user.name == "Ada"
+```
+
+## Context Managers
+
+```python
+# Sync
+with Client("https://api.example.com") as api:
+    user = api.get(f"/users/{user_id}").expect().status(200).model(User)
+
+# Async
+async with AsyncClient("https://api.example.com") as api:
+    resp = await api.get(f"/users/{user_id}").expect()
+    user = resp.status(200).model(User)
+```
+
+## Error Messages
+
+When things fail, hypex provides context about the request and response:
+
+```
+hypex.StatusError: Expected status 200, got 404
+  GET https://api.example.com/users/999
+  Response body: {"detail": "Not found"}
+
+hypex.HeaderError: Header "x-cache" expected to equal "HIT", got "MISS"
+  GET https://api.example.com/users/1
+
+hypex.ContentTypeError: Expected JSON-compatible content-type, got text/html
+  GET https://api.example.com/users/1
+  Response body: <html>...
+
+hypex.ModelError: Failed to validate response as User
+  GET https://api.example.com/users/1
+  Response body: {"id": "not-an-int", "name": "Ada", ...}
+  Validation errors:
+    id: Input should be a valid integer [type=int_parsing]
+```
+
+## Design Principles
+
+- Pydantic models are the primary response surface.
+- `model()` and `model_list()` return real model instances, not proxies.
+- Use native Python assertions on model fields.
+- No custom assertion DSL, no JSONPath, no string selectors.
+- The async boundary is only at `.expect()` — everything after is synchronous.
+- Client is reusable — each verb call creates a fresh request builder.

basst-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "basst"
+version = "0.1.0"
+description = "Fluent HTTP API testing library with Pydantic model binding"
+readme = "README.md"
+authors = [{ name = "Gitznik", email = "dev@robswebhub.net" }]
+requires-python = ">=3.13"
+dependencies = ["httpx", "pydantic"]
+
+[dependency-groups]
+dev = ["pytest", "pytest-asyncio", "respx", "pyright"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

basst-0.1.0/src/basst/_sentinel.py

@@ -0,0 +1,14 @@
+"""Sentinel value to distinguish 'not provided' from ``None``."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class _Unset(Enum):
+    """Sentinel to distinguish 'not set' from ``None``."""
+
+    token = 0
+
+
+_UNSET = _Unset.token

basst-0.1.0/src/basst/builder.py

@@ -0,0 +1,226 @@
+"""Request builder for constructing and firing HTTP requests."""
+
+from __future__ import annotations
+
+from enum import Enum, StrEnum
+from typing import Any, Self
+
+import httpx
+
+from basst._sentinel import _Unset, _UNSET
+from basst.response import Response
+
+HeaderTypes = httpx.Headers | dict[str, str] | list[tuple[str, str]]
+"""Type alias for accepted header input formats.
+
+Mirrors httpx's internal ``HeaderTypes``. Accepts ``httpx.Headers``,
+a ``dict[str, str]``, or a ``list[tuple[str, str]]`` (for multi-value
+headers).
+"""
+
+
+class Method(StrEnum):
+    """HTTP methods supported by the request builder.
+
+    Inherits from ``str`` so values pass directly to httpx without
+    conversion.
+    """
+
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    HEAD = "HEAD"
+    OPTIONS = "OPTIONS"
+
+
+class RequestBuilder:
+    """Fluent builder for a single HTTP request.
+
+    Created by Client verb methods. All builder methods return ``self``
+    for chaining. Call :meth:`expect` to fire the request and get a
+    :class:`~basst.response.Response`.
+
+    The builder only tracks per-request overrides. The underlying
+    ``httpx.Client`` holds base configuration (base_url, headers, auth,
+    timeout) and httpx merges them automatically.
+
+    Args:
+        client: The httpx.Client to send the request through.
+        method: The HTTP method.
+        path: The URL path (relative to the client's base_url).
+    """
+
+    def __init__(
+        self,
+        *,
+        client: httpx.Client,
+        method: Method,
+        path: str,
+    ) -> None:
+        self._client = client
+        self._method = method
+        self._path = path
+        self._headers = httpx.Headers()
+        self._params: dict[str, str | int | float | bool] = {}
+        self._cookies: dict[str, str] = {}
+        self._json: Any = None
+        self._data: dict[str, Any] | None = None
+        self._auth: tuple[str, str] | httpx.Auth | None | _Unset = _UNSET
+        self._timeout: float | None | _Unset = _UNSET
+
+    # -- Builder methods (all return self for chaining) --
+
+    def header(self, name: str, value: str) -> Self:
+        """Add a single header to the request.
+
+        Args:
+            name: Header name (case-insensitive).
+            value: Header value.
+
+        Returns:
+            self, for chaining.
+        """
+        self._headers[name] = value
+        return self
+
+    def headers(self, headers: HeaderTypes) -> Self:
+        """Add multiple headers to the request.
+
+        Args:
+            headers: Headers as ``httpx.Headers``, a ``dict``, or a
+                list of ``(name, value)`` tuples (for multi-value
+                headers).
+
+        Returns:
+            self, for chaining.
+        """
+        self._headers.update(headers)
+        return self
+
+    def query(self, **params: str | int | float | bool) -> Self:
+        """Add query parameters to the request URL.
+
+        Args:
+            **params: Query parameter names and values.
+
+        Returns:
+            self, for chaining.
+        """
+        self._params.update(params)
+        return self
+
+    def cookie(self, name: str, value: str) -> Self:
+        """Add a cookie to the request.
+
+        Cookies are sent via the ``Cookie`` header.
+
+        Args:
+            name: Cookie name.
+            value: Cookie value.
+
+        Returns:
+            self, for chaining.
+        """
+        self._cookies[name] = value
+        return self
+
+    def json(self, data: Any) -> Self:
+        """Set the JSON request body.
+
+        Args:
+            data: Any JSON-serialisable value. Must not be ``None``
+                (use a different body method or omit the call instead).
+
+        Returns:
+            self, for chaining.
+        """
+        self._json = data
+        return self
+
+    def data(self, data: dict[str, Any]) -> Self:
+        """Set form-encoded request body.
+
+        Args:
+            data: Form field names and values.
+
+        Returns:
+            self, for chaining.
+        """
+        self._data = data
+        return self
+
+    def auth(self, auth: tuple[str, str] | httpx.Auth | None) -> Self:
+        """Set authentication for this request.
+
+        Overrides any client-level auth. Pass ``None`` to explicitly
+        disable authentication for this request.
+
+        Args:
+            auth: A ``(username, password)`` tuple, an ``httpx.Auth``
+                instance, or ``None`` to disable.
+
+        Returns:
+            self, for chaining.
+        """
+        self._auth = auth
+        return self
+
+    def timeout(self, seconds: float | None) -> Self:
+        """Set timeout for this request.
+
+        Overrides any client-level timeout. Pass ``None`` to disable
+        the timeout entirely (wait forever).
+
+        Args:
+            seconds: Timeout in seconds, or ``None`` to disable.
+
+        Returns:
+            self, for chaining.
+        """
+        self._timeout = seconds
+        return self
+
+    # -- Terminal method --
+
+    def expect(self) -> Response:
+        """Fire the HTTP request and return a Response.
+
+        Passes only the builder's accumulated overrides to
+        ``httpx.Client.request()``. httpx merges them with any
+        client-level defaults (base_url, headers, auth, timeout).
+
+        Returns:
+            A :class:`~basst.response.Response` wrapping the
+            httpx response.
+        """
+        kwargs: dict[str, Any] = {}
+
+        # Merge cookies into headers (per-request cookies= is deprecated
+        # in httpx 0.28+).
+        if self._cookies:
+            cookie_str = "; ".join(
+                f"{name}={value}" for name, value in self._cookies.items()
+            )
+            self._headers["cookie"] = cookie_str
+
+        if self._headers:
+            kwargs["headers"] = self._headers
+        if self._params:
+            kwargs["params"] = self._params
+        if self._json is not None:
+            kwargs["json"] = self._json
+        if self._data is not None:
+            kwargs["data"] = self._data
+        if self._auth is not _UNSET:
+            kwargs["auth"] = self._auth
+        if self._timeout is not _UNSET:
+            kwargs["timeout"] = self._timeout
+
+        raw_response = self._client.request(
+            self._method,
+            self._path,
+            **kwargs,
+        )
+        return Response(raw_response)

basst-0.1.0/src/basst/errors.py

@@ -0,0 +1,146 @@
+"""Error classes for basst."""
+
+
+def _truncate(body: str, max_len: int = 200) -> str:
+    """Truncate a body string, appending '...' if it exceeds max_len."""
+    if len(body) <= max_len:
+        return body
+    return body[:max_len] + "..."
+
+
+class BasstError(Exception):
+    """Base error for all basst errors."""
+
+
+class StatusError(BasstError):
+    """Raised when the response status code does not match the expected value."""
+
+    def __init__(
+        self,
+        *,
+        expected: int,
+        actual: int,
+        method: str,
+        url: str,
+        body: str,
+    ) -> None:
+        self.expected = expected
+        self.actual = actual
+        self.method = method
+        self.url = url
+        self.body = body
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"Expected status {self.expected}, got {self.actual}\n"
+            f"  {self.method} {self.url}\n"
+            f"  Response body: {_truncate(self.body)}"
+        )
+
+
+class HeaderError(BasstError):
+    """Raised when a header assertion fails."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        method: str,
+        url: str,
+        message: str | None = None,
+    ) -> None:
+        self.name = name
+        self.method = method
+        self.url = url
+        self.message = message
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        if self.message is None:
+            headline = f'Header "{self.name}" not found'
+        else:
+            headline = f'Header "{self.name}" {self.message}'
+        return f"{headline}\n  {self.method} {self.url}"
+
+
+class ContentTypeError(BasstError):
+    """Raised when the response content-type does not match the expected value."""
+
+    def __init__(
+        self,
+        *,
+        expected: str,
+        actual: str,
+        method: str,
+        url: str,
+        body: str,
+    ) -> None:
+        self.expected = expected
+        self.actual = actual
+        self.method = method
+        self.url = url
+        self.body = body
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"Expected content-type {self.expected}, got {self.actual}\n"
+            f"  {self.method} {self.url}\n"
+            f"  Response body: {_truncate(self.body)}"
+        )
+
+
+class ModelError(BasstError):
+    """Raised when pydantic model validation fails."""
+
+    def __init__(
+        self,
+        *,
+        model_name: str,
+        errors: str,
+        method: str,
+        url: str,
+        body: str,
+    ) -> None:
+        self.model_name = model_name
+        self.errors = errors
+        self.method = method
+        self.url = url
+        self.body = body
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"Failed to validate response as {self.model_name}\n"
+            f"  {self.method} {self.url}\n"
+            f"  Validation errors:\n"
+            f"    {self.errors}\n"
+            f"  Response body: {_truncate(self.body)}"
+        )
+
+
+class JsonError(BasstError):
+    """Raised when the response body cannot be parsed as JSON."""
+
+    def __init__(
+        self,
+        *,
+        method: str,
+        url: str,
+        body: str,
+        detail: str,
+    ) -> None:
+        self.method = method
+        self.url = url
+        self.body = body
+        self.detail = detail
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        return (
+            f"Failed to parse response body as JSON\n"
+            f"  {self.method} {self.url}\n"
+            f"  Parse error: {self.detail}\n"
+            f"  Response body: {_truncate(self.body)}"
+        )

basst-0.1.0/src/basst/matchers.py

@@ -0,0 +1,109 @@
+"""Matchers for header value assertions.
+
+Matchers are callables with the signature ``(str) -> None``. They raise
+``AssertionError`` on failure and return ``None`` on success.
+"""
+
+import re
+from collections.abc import Callable
+
+Matcher = Callable[[str], None]
+"""A callable that validates a string value.
+
+Takes a single string argument and returns ``None`` on success.
+Raises ``AssertionError`` with a descriptive message on failure.
+"""
+
+
+def equals(expected: str) -> Matcher:
+    """Create a matcher that asserts exact string equality.
+
+    Args:
+        expected: The expected string value.
+
+    Returns:
+        A matcher that raises ``AssertionError`` if the value does not
+        equal ``expected``.
+    """
+
+    def _check(value: str) -> None:
+        if value != expected:
+            raise AssertionError(f'expected "{value}" to equal "{expected}"')
+
+    return _check
+
+
+def contains(substring: str) -> Matcher:
+    """Create a matcher that asserts a substring is present.
+
+    Args:
+        substring: The substring to search for.
+
+    Returns:
+        A matcher that raises ``AssertionError`` if ``substring`` is
+        not found in the value.
+    """
+
+    def _check(value: str) -> None:
+        if substring not in value:
+            raise AssertionError(f'expected "{value}" to contain "{substring}"')
+
+    return _check
+
+
+def starts_with(prefix: str) -> Matcher:
+    """Create a matcher that asserts a string prefix.
+
+    Args:
+        prefix: The expected prefix.
+
+    Returns:
+        A matcher that raises ``AssertionError`` if the value does not
+        start with ``prefix``.
+    """
+
+    def _check(value: str) -> None:
+        if not value.startswith(prefix):
+            raise AssertionError(f'expected "{value}" to start with "{prefix}"')
+
+    return _check
+
+
+def ends_with(suffix: str) -> Matcher:
+    """Create a matcher that asserts a string suffix.
+
+    Args:
+        suffix: The expected suffix.
+
+    Returns:
+        A matcher that raises ``AssertionError`` if the value does not
+        end with ``suffix``.
+    """
+
+    def _check(value: str) -> None:
+        if not value.endswith(suffix):
+            raise AssertionError(f'expected "{value}" to end with "{suffix}"')
+
+    return _check
+
+
+def matches(pattern: str) -> Matcher:
+    """Create a matcher that asserts a regex pattern match.
+
+    Uses ``re.search``, so the pattern can match anywhere in the value.
+    Anchor with ``^`` and ``$`` for a full match.
+
+    Args:
+        pattern: A regular expression pattern.
+
+    Returns:
+        A matcher that raises ``AssertionError`` if the pattern is not
+        found in the value.
+    """
+    compiled = re.compile(pattern)
+
+    def _check(value: str) -> None:
+        if not compiled.search(value):
+            raise AssertionError(f'expected "{value}" to match pattern "{pattern}"')
+
+    return _check

basst-0.1.0/src/basst/response.py

@@ -0,0 +1,321 @@
+"""Response wrapper with accessor methods and assertions."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from basst._sentinel import _Unset, _UNSET
+from basst.errors import (
+    ContentTypeError,
+    HeaderError,
+    JsonError,
+    ModelError,
+    StatusError,
+)
+from basst.matchers import Matcher
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class Response:
+    """Wraps an httpx.Response with accessor methods and assertions.
+
+    Assertion methods are chainable (return self) and raise on failure.
+    Accessor methods return values.
+
+    Args:
+        response: The underlying httpx.Response to wrap.
+    """
+
+    def __init__(self, response: httpx.Response) -> None:
+        self._response = response
+
+    @property
+    def _method(self) -> str:
+        """HTTP method from the original request."""
+        return self._response.request.method
+
+    @property
+    def _url(self) -> str:
+        """URL from the original request."""
+        return str(self._response.request.url)
+
+    # -- Assertion methods (chainable) --
+
+    def status(self, code: int) -> Response:
+        """Assert that the response status code matches the expected value.
+
+        Args:
+            code: The expected HTTP status code.
+
+        Returns:
+            self, for chaining.
+
+        Raises:
+            StatusError: If the actual status code does not match.
+        """
+        if self._response.status_code != code:
+            raise StatusError(
+                expected=code,
+                actual=self._response.status_code,
+                method=self._method,
+                url=self._url,
+                body=self.text,
+            )
+        return self
+
+    def header(self, name: str, matcher: Matcher | None = None) -> Response:
+        """Assert that a response header exists and optionally matches a value.
+
+        When called with just a name, asserts the header is present. When a
+        matcher is also provided, asserts the header exists **and** the matcher
+        passes against the header value.
+
+        Args:
+            name: The header name (case-insensitive).
+            matcher: Optional matcher to validate the header value.
+
+        Returns:
+            self, for chaining.
+
+        Raises:
+            HeaderError: If the header is missing or the matcher fails.
+        """
+        value = self._response.headers.get(name)
+        if value is None:
+            raise HeaderError(
+                name=name,
+                method=self._method,
+                url=self._url,
+            )
+        if matcher is None:
+            return self
+        try:
+            matcher(value)
+        except AssertionError as exc:
+            raise HeaderError(
+                name=name,
+                method=self._method,
+                url=self._url,
+                message=str(exc),
+            ) from None
+        return self
+
+    # -- Model binding --
+
+    def model(
+        self, model_type: type[T], *, content_type: str | None | _Unset = _UNSET
+    ) -> T:
+        """Validate the response body against a Pydantic model.
+
+        Validates the response content-type, parses the JSON body, and
+        returns a model instance. Content-type parameters in the response
+        (e.g. ``charset=utf-8``) are always ignored during comparison.
+
+        Args:
+            model_type: The Pydantic model class to validate against.
+            content_type: Controls content-type validation. Must not
+                contain parameters (no ``;``). Not provided (default):
+                accepts ``application/json`` or any ``+json`` suffix.
+                ``None``: skips validation. Contains ``/``: exact media
+                type match. Otherwise: treated as a prefix matching
+                ``application/{value}+json``.
+
+        Returns:
+            An instance of ``model_type``.
+
+        Raises:
+            ValueError: If ``content_type`` contains parameters.
+            ContentTypeError: If the response content-type does not match.
+            ModelError: If the response body fails Pydantic validation.
+        """
+        self._validate_content_type(content_type)
+        data = self.json()
+        try:
+            return model_type.model_validate(data)
+        except ValidationError as exc:
+            raise ModelError(
+                model_name=model_type.__name__,
+                errors=str(exc),
+                method=self._method,
+                url=self._url,
+                body=self.text,
+            ) from None
+
+    def model_list(
+        self, model_type: type[T], *, content_type: str | None | _Unset = _UNSET
+    ) -> list[T]:
+        """Validate the response body as a list of Pydantic models.
+
+        Validates the response content-type, parses the JSON body as a
+        list, and returns a list of model instances. Content-type
+        parameters in the response (e.g. ``charset=utf-8``) are always
+        ignored during comparison.
+
+        Args:
+            model_type: The Pydantic model class for each list element.
+            content_type: Controls content-type validation. Same rules as
+                :meth:`model`.
+
+        Returns:
+            A list of ``model_type`` instances.
+
+        Raises:
+            ValueError: If ``content_type`` contains parameters.
+            ContentTypeError: If the response content-type does not match.
+            ModelError: If any element fails Pydantic validation.
+        """
+        self._validate_content_type(content_type)
+        data = self.json()
+        try:
+            # NOTE: mypy and ty flag list[model_type] as an invalid type
+            # expression because model_type is a variable, not a static type.
+            # Pyright accepts it because TypeAdapter is designed for runtime
+            # type expressions. We use pyright as our type checker.
+            adapter = TypeAdapter(list[model_type])
+            return adapter.validate_python(data)
+        except ValidationError as exc:
+            raise ModelError(
+                model_name=model_type.__name__,
+                errors=str(exc),
+                method=self._method,
+                url=self._url,
+                body=self.text,
+            ) from None
+
+    def _validate_content_type(self, content_type: str | None | _Unset) -> None:
+        """Validate the response content-type header.
+
+        Content-type parameters (e.g. ``charset=utf-8``) in the response
+        are always stripped before comparison — only the media type is
+        matched. Passing a ``content_type`` string that itself contains
+        parameters (a ``;``) is not supported and raises ``ValueError``.
+
+        Args:
+            content_type: The expected content-type constraint. See
+                :meth:`model` for the full rules.
+
+        Raises:
+            ValueError: If ``content_type`` contains a ``;`` (parameters).
+            ContentTypeError: If the response content-type does not match.
+        """
+        if content_type is None:
+            return
+
+        if isinstance(content_type, str) and ";" in content_type:
+            raise ValueError(
+                f"content_type must not contain parameters (got {content_type!r}). "
+                "Response content-type parameters (e.g. charset) are always "
+                "ignored during comparison."
+            )
+
+        raw_ct = self._response.headers.get("content-type", "")
+        # Strip parameters (e.g. "; charset=utf-8") and normalise case.
+        media_type = raw_ct.split(";")[0].strip().lower()
+
+        if content_type is _UNSET:
+            if media_type != "application/json" and not media_type.endswith("+json"):
+                raise ContentTypeError(
+                    expected="application/json or *+json",
+                    actual=raw_ct,
+                    method=self._method,
+                    url=self._url,
+                    body=self.text,
+                )
+            return
+
+        if "/" in content_type:
+            # Exact match.
+            if media_type != content_type.lower():
+                raise ContentTypeError(
+                    expected=content_type,
+                    actual=raw_ct,
+                    method=self._method,
+                    url=self._url,
+                    body=self.text,
+                )
+        else:
+            # Prefix mode: matches application/{value}+json.
+            expected_media = f"application/{content_type.lower()}+json"
+            if media_type != expected_media:
+                raise ContentTypeError(
+                    expected=expected_media,
+                    actual=raw_ct,
+                    method=self._method,
+                    url=self._url,
+                    body=self.text,
+                )
+
+    # -- Accessor methods --
+
+    @property
+    def status_code(self) -> int:
+        """The raw HTTP status code."""
+        return self._response.status_code
+
+    def get_header(self, name: str) -> str:
+        """Return the value of a response header.
+
+        Args:
+            name: The header name (case-insensitive).
+
+        Returns:
+            The header value as a string.
+
+        Raises:
+            HeaderError: If the header is not present in the response.
+        """
+        try:
+            return self._response.headers[name]
+        except KeyError:
+            raise HeaderError(
+                name=name,
+                method=self._method,
+                url=self._url,
+            ) from None
+
+    def get_headers(self) -> httpx.Headers:
+        """Return all response headers.
+
+        Returns:
+            The response headers as an ``httpx.Headers`` object. Supports
+            dict-like access for single-value lookups and ``.multi_items()``
+            or ``.get_list(name)`` for multi-value headers.
+        """
+        return self._response.headers
+
+    def json(self) -> Any:
+        """Parse the response body as JSON.
+
+        Returns:
+            The parsed JSON value.
+
+        Raises:
+            JsonError: If the response body is not valid JSON.
+        """
+        try:
+            return self._response.json()
+        except Exception as exc:
+            raise JsonError(
+                method=self._method,
+                url=self._url,
+                body=self.text,
+                detail=str(exc),
+            ) from None
+
+    @property
+    def raw(self) -> httpx.Response:
+        """The underlying httpx.Response object.
+
+        Use this as an escape hatch when you need access to httpx features
+        that basst does not wrap directly.
+        """
+        return self._response
+
+    @property
+    def text(self) -> str:
+        """The raw response body as a string."""
+        return self._response.text