involve-benchling 0.1.0a1__py3-none-any.whl

involve_benchling/__init__.py

@@ -0,0 +1,49 @@
+"""involve-benchling: the toolkit the official Benchling SDK doesn't give you.
+
+A thin, composable layer over ``benchling_v3_sdk`` -- it never hides the
+SDK. Pillars:
+
+- :mod:`involve_benchling.cache` -- tiered, pickle-free response caching.
+- :mod:`involve_benchling.resolve` -- generic name->object resolution with
+  typed errors, over any V3 resource.
+- :mod:`involve_benchling.dataframes` -- pandas adapters (optional extra).
+- :mod:`involve_benchling.testing` -- pytest fixtures and resource cleanup.
+- :mod:`involve_benchling.tools` -- cross-resource workflows (roadmap).
+
+Quick start::
+
+    from involve_benchling import BenchlingConfig, connect, resolve
+
+    config = BenchlingConfig.from_env()
+    benchling = connect(config)
+    plasmid = resolve.get_by_name(benchling.custom_entity, "pEX-001")
+"""
+
+from . import resolve
+from .cache import BenchlingCache, CachePolicy
+from .core import BenchlingConfig, connect, connect_async
+from .errors import (
+    AmbiguousError,
+    CacheError,
+    ConfigError,
+    InvolveBenchlingError,
+    NotFoundError,
+    ReadOnlyViolationError,
+)
+from .version import __version__
+
+__all__ = [
+    "AmbiguousError",
+    "BenchlingCache",
+    "BenchlingConfig",
+    "CacheError",
+    "CachePolicy",
+    "ConfigError",
+    "InvolveBenchlingError",
+    "NotFoundError",
+    "ReadOnlyViolationError",
+    "__version__",
+    "connect",
+    "connect_async",
+    "resolve",
+]

involve_benchling/cache/__init__.py

@@ -0,0 +1,160 @@
+"""Caching for Benchling API responses.
+
+The official SDK does no caching; reference data (schemas, dropdowns,
+registries, users) rarely changes but is fetched constantly. A
+:class:`BenchlingCache` turns those ~500ms calls into sub-millisecond
+lookups.
+
+Values round-trip through JSON (never pickle). Benchling SDK models are
+Pydantic models and are serialised losslessly. A cached model is rebuilt
+only from a ``benchling_v3_sdk`` class or the ``model`` passed to
+:meth:`BenchlingCache.get_or_fetch`, so a tampered cache file cannot make
+the cache import arbitrary modules::
+
+    from involve_benchling.cache import BenchlingCache
+    from benchling_v3_sdk.types.custom_entity import CustomEntity
+
+    cache = BenchlingCache.from_policy(policy, namespace=config.base_url)
+
+    entities = cache.get_or_fetch(
+        "entities:by-schema:ts_abc123",
+        category="entity",
+        model=CustomEntity,
+        fetch=lambda: list(benchling.custom_entity.list(schema_eq="ts_abc123")),
+    )
+
+    # after a write:
+    cache.invalidate("entities:")
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from .backends import MISSING, CacheBackend, DiskBackend, MemoryBackend, TieredBackend
+from .policy import DEFAULT_TTLS, CachePolicy
+
+__all__ = [
+    "DEFAULT_TTLS",
+    "MISSING",
+    "BenchlingCache",
+    "CacheBackend",
+    "CachePolicy",
+    "DiskBackend",
+    "MemoryBackend",
+    "TieredBackend",
+]
+
+M = TypeVar("M", bound=BaseModel)
+
+
+def _encode(value: Any) -> Any:
+    """Encode a value (possibly a Pydantic model or list of them) to JSON-safe form."""
+    if isinstance(value, BaseModel):
+        return {"__model__": _model_ref(type(value)), "data": value.model_dump_json()}
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return {"__list__": [_encode(item) for item in value]}
+    return {"__json__": value}
+
+
+def _decode(doc: Any, model: type[BaseModel] | None = None) -> Any:
+    if not isinstance(doc, dict):
+        return doc
+    if "__model__" in doc:
+        ref = doc["__model__"]
+        model_cls = model if model and ref == _model_ref(model) else _import_model(ref)
+        return model_cls.model_validate_json(doc["data"])
+    if "__list__" in doc:
+        return [_decode(item, model) for item in doc["__list__"]]
+    return doc.get("__json__")
+
+
+def _model_ref(cls: type[BaseModel]) -> str:
+    return f"{cls.__module__}:{cls.__qualname__}"
+
+
+#: Packages whose models the cache imports by name when rehydrating.
+_TRUSTED_MODEL_PACKAGES = ("benchling_v3_sdk",)
+
+
+def _import_model(ref: str) -> type[BaseModel]:
+    module_name, _, qualname = ref.partition(":")
+    if module_name.partition(".")[0] not in _TRUSTED_MODEL_PACKAGES:
+        raise TypeError(f"{ref} is not a Benchling SDK model; pass it as model=")
+    obj: Any = importlib.import_module(module_name)
+    for part in qualname.split("."):
+        obj = getattr(obj, part)
+    if not (isinstance(obj, type) and issubclass(obj, BaseModel)):
+        raise TypeError(f"{ref} is not a Pydantic model")
+    return obj
+
+
+class BenchlingCache:
+    """High-level cache facade with stats and model-aware serialisation."""
+
+    def __init__(self, backend: CacheBackend, policy: CachePolicy | None = None) -> None:
+        self._backend = backend
+        self._policy = policy or CachePolicy()
+        self.hits = 0
+        self.misses = 0
+
+    @classmethod
+    def from_policy(cls, policy: CachePolicy, *, namespace: str = "") -> BenchlingCache:
+        """Build the standard tiered cache described by ``policy``.
+
+        ``namespace`` (typically the tenant base URL) isolates cache
+        directories between tenants.
+        """
+        memory = MemoryBackend(policy.max_memory_entries)
+        if policy.directory is None:
+            return cls(memory, policy)
+        subdir = hashlib.sha256(namespace.encode()).hexdigest()[:12] if namespace else "default"
+        disk = DiskBackend(policy.directory / subdir)
+        return cls(TieredBackend(memory, disk), policy)
+
+    @property
+    def hit_rate(self) -> float:
+        total = self.hits + self.misses
+        return self.hits / total if total else 0.0
+
+    def get_or_fetch(
+        self,
+        key: str,
+        *,
+        fetch: Callable[[], Any],
+        category: str = "",
+        ttl: float | None = None,
+        model: type[BaseModel] | None = None,
+    ) -> Any:
+        """Return the cached value for ``key``, calling ``fetch`` on a miss.
+
+        ``ttl`` overrides the policy TTL for ``category``. ``model`` names a
+        Pydantic class outside ``benchling_v3_sdk`` that the cached value may
+        hold; SDK models need no ``model``. An entry that cannot be decoded
+        counts as a miss.
+        """
+        if not self._policy.enabled:
+            return fetch()
+        doc = self._backend.get(key)
+        if doc is not MISSING:
+            try:
+                value = _decode(doc, model)
+            except (ImportError, AttributeError, TypeError, ValueError):
+                pass
+            else:
+                self.hits += 1
+                return value
+        self.misses += 1
+        value = fetch()
+        resolved_ttl = ttl if ttl is not None else self._policy.ttl_for(category)
+        self._backend.set(key, _encode(value), resolved_ttl)
+        return value
+
+    def invalidate(self, prefix: str = "") -> int:
+        """Drop every entry whose key starts with ``prefix``. Returns the count."""
+        return self._backend.invalidate(prefix)

involve_benchling/cache/backends.py

@@ -0,0 +1,164 @@
+"""Cache backends.
+
+Values are stored as JSON documents, never pickle. Pydantic models from
+the Benchling SDK are serialised with ``model_dump_json`` and rehydrated
+with ``model_validate_json``.
+
+The disk tier creates its directory and files readable only by the current
+user, because cached responses can hold sensitive tenant data.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import tempfile
+import time
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+class _Missing:
+    def __repr__(self) -> str:  # pragma: no cover
+        return "<MISSING>"
+
+
+#: Sentinel returned by :meth:`CacheBackend.get` on a miss.
+MISSING: Any = _Missing()
+
+
+@runtime_checkable
+class CacheBackend(Protocol):
+    """Minimal interface a cache backend must implement.
+
+    Values are JSON-serialisable documents (dict/list/str/num/bool/None).
+    """
+
+    def get(self, key: str) -> Any: ...
+
+    def set(self, key: str, value: Any, ttl: float) -> None: ...
+
+    def invalidate(self, prefix: str = "") -> int: ...
+
+
+class MemoryBackend:
+    """In-process LRU cache with per-entry TTL."""
+
+    def __init__(self, max_entries: int = 1024) -> None:
+        self._max = max_entries
+        self._data: OrderedDict[str, tuple[float, Any]] = OrderedDict()
+
+    def get(self, key: str) -> Any:
+        entry = self._data.get(key)
+        if entry is None:
+            return MISSING
+        expires_at, value = entry
+        if time.monotonic() >= expires_at:
+            del self._data[key]
+            return MISSING
+        self._data.move_to_end(key)
+        return value
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        self._data[key] = (time.monotonic() + ttl, value)
+        self._data.move_to_end(key)
+        while len(self._data) > self._max:
+            self._data.popitem(last=False)
+
+    def invalidate(self, prefix: str = "") -> int:
+        keys = [k for k in self._data if k.startswith(prefix)]
+        for k in keys:
+            del self._data[k]
+        return len(keys)
+
+
+class DiskBackend:
+    """Persistent cache: one JSON file per key, shared across processes.
+
+    Writes are atomic (write to a unique temp file, then rename). Corrupt or
+    unreadable entries are treated as misses, never as errors. The directory
+    holds a ``.gitignore`` so a cache inside a repository is never committed.
+    """
+
+    def __init__(self, directory: Path) -> None:
+        self._dir = directory
+        self._index_dir = directory / "entries"
+        self._index_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        gitignore = directory / ".gitignore"
+        if not gitignore.exists():
+            with contextlib.suppress(OSError):
+                gitignore.write_text("*\n")
+
+    def _path(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode()).hexdigest()[:40]
+        return self._index_dir / f"{digest}.json"
+
+    def get(self, key: str) -> Any:
+        path = self._path(key)
+        try:
+            doc = json.loads(path.read_text())
+        except (OSError, ValueError):
+            return MISSING
+        if doc.get("key") != key or time.time() >= doc.get("expires_at", 0):
+            return MISSING
+        return doc.get("value")
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        path = self._path(key)
+        doc = {"key": key, "expires_at": time.time() + ttl, "value": value}
+        try:
+            # mkstemp creates the file with mode 0600.
+            fd, tmp_name = tempfile.mkstemp(dir=self._index_dir, suffix=".tmp")
+        except OSError:
+            return
+        tmp = Path(tmp_name)
+        try:
+            with os.fdopen(fd, "w") as f:
+                f.write(json.dumps(doc))
+            tmp.replace(path)
+        except OSError:
+            # Cache failures must never break the caller.
+            tmp.unlink(missing_ok=True)
+
+    def invalidate(self, prefix: str = "") -> int:
+        count = 0
+        for path in self._index_dir.glob("*.json"):
+            try:
+                doc = json.loads(path.read_text())
+            except (OSError, ValueError):
+                path.unlink(missing_ok=True)
+                continue
+            if doc.get("key", "").startswith(prefix):
+                path.unlink(missing_ok=True)
+                count += 1
+        return count
+
+
+class TieredBackend:
+    """Memory tier in front of a persistent tier."""
+
+    def __init__(self, memory: MemoryBackend, disk: DiskBackend) -> None:
+        self._memory = memory
+        self._disk = disk
+
+    def get(self, key: str) -> Any:
+        value = self._memory.get(key)
+        if value is not MISSING:
+            return value
+        value = self._disk.get(key)
+        if value is not MISSING:
+            # Re-warm the memory tier; TTL is enforced by the disk doc,
+            # so a short memory TTL keeps the tiers close.
+            self._memory.set(key, value, ttl=60)
+        return value
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        self._memory.set(key, value, ttl)
+        self._disk.set(key, value, ttl)
+
+    def invalidate(self, prefix: str = "") -> int:
+        self._memory.invalidate(prefix)
+        return self._disk.invalidate(prefix)

involve_benchling/cache/policy.py

@@ -0,0 +1,39 @@
+"""Cache policy: what to cache, where, and for how long."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: Default TTLs (seconds) per category. Categories are free-form strings;
+#: these defaults reflect how often each kind of Benchling data changes.
+DEFAULT_TTLS: dict[str, float] = {
+    "schema": 24 * 3600,
+    "registry": 12 * 3600,
+    "dropdown": 12 * 3600,
+    "folder": 12 * 3600,
+    "project": 12 * 3600,
+    "user": 12 * 3600,
+    "entity": 3600,
+}
+
+
+@dataclass(frozen=True)
+class CachePolicy:
+    """Configuration for :class:`~involve_benchling.cache.BenchlingCache`."""
+
+    enabled: bool = True
+    #: Directory for the persistent tier. ``None`` disables the disk tier.
+    directory: Path | None = Path(".benchling-cache")
+    #: Maximum entries held in the in-memory LRU tier.
+    max_memory_entries: int = 1024
+    #: TTL (seconds) used when a category has no specific TTL.
+    default_ttl: float = 3600
+    #: Per-category TTL overrides, merged over :data:`DEFAULT_TTLS`.
+    ttls: dict[str, float] = field(default_factory=dict)
+
+    def ttl_for(self, category: str) -> float:
+        """Resolve the TTL for a category."""
+        if category in self.ttls:
+            return self.ttls[category]
+        return DEFAULT_TTLS.get(category, self.default_ttl)

involve_benchling/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core: configuration and SDK client construction."""
+
+from .client import connect, connect_async
+from .config import BenchlingConfig
+
+__all__ = ["BenchlingConfig", "connect", "connect_async"]

involve_benchling/core/client.py

@@ -0,0 +1,78 @@
+"""Thin construction helpers over the official ``benchling_v3_sdk``.
+
+involve-benchling never hides the SDK: :func:`connect` returns the plain
+``benchling_v3_sdk.Benchling`` client, and every helper in this library
+accepts SDK clients and resources directly.
+
+When ``config.read_only`` is set, the client is built on an ``httpx``
+transport that blocks every request that could change tenant data (see
+:mod:`~involve_benchling.core.readonly`).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..errors import ConfigError
+from .config import BenchlingConfig
+from .readonly import read_only_async_http_client, read_only_http_client
+
+if TYPE_CHECKING:
+    from benchling_v3_sdk import AsyncBenchling, Benchling
+
+#: Request timeout (seconds) for read-only clients, matching the SDK default.
+_DEFAULT_TIMEOUT = 60.0
+
+
+def _client_kwargs(config: BenchlingConfig) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {"base_url": config.base_url}
+    if config.early_access:
+        kwargs["early_access"] = "true"
+    if config.api_key:
+        kwargs["api_key"] = config.api_key
+    else:
+        kwargs["client_id"] = config.oauth_client_id
+        kwargs["client_secret"] = config.oauth_client_secret
+    return kwargs
+
+
+def _read_only_http_kwargs(extra: dict[str, Any]) -> dict[str, Any]:
+    if "httpx_client" in extra:
+        raise ConfigError(
+            "A read-only config builds its own httpx client; do not pass httpx_client."
+        )
+    return {
+        "timeout": extra.get("timeout") or _DEFAULT_TIMEOUT,
+        "follow_redirects": extra.get("follow_redirects", True),
+    }
+
+
+def connect(config: BenchlingConfig, **extra: Any) -> Benchling:
+    """Create a synchronous ``benchling_v3_sdk.Benchling`` client.
+
+    Extra keyword arguments (``timeout``, ``max_retries``, ``httpx_client``,
+    ...) are forwarded to the SDK constructor.
+
+    Raises:
+        ConfigError: ``config.read_only`` is set and ``httpx_client`` was passed.
+    """
+    from benchling_v3_sdk import Benchling
+
+    if config.read_only:
+        http = _read_only_http_kwargs(extra)
+        extra["httpx_client"] = read_only_http_client(config.base_url, **http)
+    return Benchling(**_client_kwargs(config), **extra)
+
+
+def connect_async(config: BenchlingConfig, **extra: Any) -> AsyncBenchling:
+    """Create an asynchronous ``benchling_v3_sdk.AsyncBenchling`` client.
+
+    Raises:
+        ConfigError: ``config.read_only`` is set and ``httpx_client`` was passed.
+    """
+    from benchling_v3_sdk import AsyncBenchling
+
+    if config.read_only:
+        http = _read_only_http_kwargs(extra)
+        extra["httpx_client"] = read_only_async_http_client(config.base_url, **http)
+    return AsyncBenchling(**_client_kwargs(config), **extra)

involve_benchling/core/config.py

@@ -0,0 +1,80 @@
+"""Immutable configuration for connecting to Benchling."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from ..cache.policy import CachePolicy
+from ..errors import ConfigError
+
+_ENV_PREFIX = "BENCHLING_"
+
+
+def _env_flag(name: str) -> bool:
+    return os.getenv(f"{_ENV_PREFIX}{name}", "").lower() in ("1", "true", "yes")
+
+
+@dataclass(frozen=True)
+class BenchlingConfig:
+    """Connection settings for a Benchling tenant.
+
+    Authenticate with either an API key or OAuth client credentials.
+    All fields are immutable; use :meth:`with_options` to derive variants.
+    """
+
+    base_url: str
+    api_key: str | None = None
+    oauth_client_id: str | None = None
+    oauth_client_secret: str | None = None
+    early_access: bool = False
+    registry_name: str | None = None
+    #: Clients built from this config send only reads (see :mod:`~involve_benchling.core.readonly`).
+    read_only: bool = False
+    cache: CachePolicy = field(default_factory=CachePolicy)
+
+    def __post_init__(self) -> None:
+        if not self.base_url:
+            raise ConfigError("base_url is required (e.g. https://yourtenant.benchling.com)")
+        has_key = bool(self.api_key)
+        has_oauth = bool(self.oauth_client_id and self.oauth_client_secret)
+        if not has_key and not has_oauth:
+            raise ConfigError(
+                "Provide api_key or oauth_client_id + oauth_client_secret "
+                f"(or set {_ENV_PREFIX}API_KEY / {_ENV_PREFIX}OAUTH_CLIENT_ID "
+                f"and {_ENV_PREFIX}OAUTH_CLIENT_SECRET)."
+            )
+        if has_key and has_oauth:
+            raise ConfigError("Provide api_key or OAuth credentials, not both.")
+
+    @property
+    def auth_method(self) -> str:
+        """``"api_key"`` or ``"oauth"``."""
+        return "api_key" if self.api_key else "oauth"
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> BenchlingConfig:
+        """Build a config from ``BENCHLING_*`` environment variables.
+
+        Recognised variables: ``BENCHLING_BASE_URL``, ``BENCHLING_API_KEY``,
+        ``BENCHLING_OAUTH_CLIENT_ID``, ``BENCHLING_OAUTH_CLIENT_SECRET``,
+        ``BENCHLING_EARLY_ACCESS``, ``BENCHLING_REGISTRY_NAME``,
+        ``BENCHLING_READ_ONLY``.
+        Keyword arguments override environment values.
+        """
+        env: dict[str, Any] = {
+            "base_url": os.getenv(f"{_ENV_PREFIX}BASE_URL", ""),
+            "api_key": os.getenv(f"{_ENV_PREFIX}API_KEY") or None,
+            "oauth_client_id": os.getenv(f"{_ENV_PREFIX}OAUTH_CLIENT_ID") or None,
+            "oauth_client_secret": os.getenv(f"{_ENV_PREFIX}OAUTH_CLIENT_SECRET") or None,
+            "early_access": _env_flag("EARLY_ACCESS"),
+            "registry_name": os.getenv(f"{_ENV_PREFIX}REGISTRY_NAME") or None,
+            "read_only": _env_flag("READ_ONLY"),
+        }
+        env.update(overrides)
+        return cls(**env)
+
+    def with_options(self, **changes: Any) -> BenchlingConfig:
+        """Return a copy of this config with the given fields replaced."""
+        return replace(self, **changes)

involve_benchling/core/readonly.py

@@ -0,0 +1,106 @@
+"""Read-only enforcement at the HTTP transport.
+
+A read-only client sends only ``GET``, ``HEAD`` and ``OPTIONS`` requests,
+plus ``POST`` to a short list of endpoints that read without changing
+tenant data (:data:`READ_POSTS`):
+
+- ``/oauth/token`` issues a credential.
+- ``/api/v3/search`` runs a search query.
+
+Any other request raises :class:`~involve_benchling.errors.ReadOnlyViolationError`
+before it leaves the process.
+
+The check sits below every SDK method, so it covers raw-response calls and
+methods added in future SDK releases without a list of write verbs to
+maintain. Build read-only clients with ``BenchlingConfig(read_only=True)``
+and :func:`~involve_benchling.connect`; use these helpers directly only when
+constructing an ``httpx`` client yourself.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ..errors import ReadOnlyViolationError
+
+__all__ = [
+    "READ_POSTS",
+    "SAFE_METHODS",
+    "AsyncReadOnlyTransport",
+    "ReadOnlyTransport",
+    "read_only_async_http_client",
+    "read_only_http_client",
+    "token_url",
+]
+
+#: HTTP methods a read-only client may send to any URL.
+SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+#: Paths, relative to the tenant base URL, that accept a read-only ``POST``.
+READ_POSTS: tuple[str, ...] = ("oauth/token", "api/v3/search")
+
+
+def _url(base_url: str, path: str) -> httpx.URL:
+    return httpx.URL(f"{base_url.rstrip('/')}/{path}")
+
+
+def token_url(base_url: str) -> httpx.URL:
+    """The OAuth token endpoint the SDK posts to for ``base_url``."""
+    return _url(base_url, "oauth/token")
+
+
+def _check(request: httpx.Request, read_posts: frozenset[httpx.URL]) -> None:
+    if request.method in SAFE_METHODS:
+        return
+    url = request.url.copy_with(query=None, fragment=None)
+    if request.method == "POST" and url in read_posts:
+        return
+    raise ReadOnlyViolationError(request.method, str(url))
+
+
+def _read_posts(base_url: str) -> frozenset[httpx.URL]:
+    return frozenset(_url(base_url, path) for path in READ_POSTS)
+
+
+class ReadOnlyTransport(httpx.BaseTransport):
+    """Sync transport that rejects every request a read-only client must not send."""
+
+    def __init__(self, base_url: str, inner: httpx.BaseTransport | None = None) -> None:
+        self._read_posts = _read_posts(base_url)
+        self._inner = inner or httpx.HTTPTransport()
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        _check(request, self._read_posts)
+        return self._inner.handle_request(request)
+
+    def close(self) -> None:
+        self._inner.close()
+
+
+class AsyncReadOnlyTransport(httpx.AsyncBaseTransport):
+    """Async counterpart of :class:`ReadOnlyTransport`."""
+
+    def __init__(self, base_url: str, inner: httpx.AsyncBaseTransport | None = None) -> None:
+        self._read_posts = _read_posts(base_url)
+        self._inner = inner or httpx.AsyncHTTPTransport()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        _check(request, self._read_posts)
+        return await self._inner.handle_async_request(request)
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+def read_only_http_client(base_url: str, **kwargs: Any) -> httpx.Client:
+    """An ``httpx.Client`` whose transport enforces read-only access."""
+    kwargs.setdefault("follow_redirects", True)
+    return httpx.Client(transport=ReadOnlyTransport(base_url), **kwargs)
+
+
+def read_only_async_http_client(base_url: str, **kwargs: Any) -> httpx.AsyncClient:
+    """An ``httpx.AsyncClient`` whose transport enforces read-only access."""
+    kwargs.setdefault("follow_redirects", True)
+    return httpx.AsyncClient(transport=AsyncReadOnlyTransport(base_url), **kwargs)