connpool 1.0.2__py3-none-any.whl

connpool/__init__.py

@@ -0,0 +1,46 @@
+"""connpool - a generic connection pool for Python (sync + asyncio), standard library only.
+
+Layers (each only depends on the ones above it):
+
+    core           errors, clocks, connection bookkeeping
+    resilience     circuit breaker, retry/backoff
+    policy         PoolConfig + the pure retirement rules
+    factories      ConnectionFactory: the seam users implement to pool anything
+    observability  listeners + stats
+    pools          ConnectionPool, AsyncConnectionPool, PoolRegistry
+
+This module is the *public API facade*: everything users need can be imported straight
+from ``connpool`` so that internal modules can move without breaking anyone.
+"""
+from connpool.core import (
+    CircuitOpenError, Clock, CloseReason, ConnectionCreateError, InvalidReleaseError,
+    ManualClock, PoolClosedError, PoolConfigError, PoolError, PoolExhaustedError,
+    PoolTimeoutError, PooledConnection, SystemClock,
+)
+from connpool.factories import (
+    AsyncCallableFactory, AsyncConnectionFactory, CallableFactory, ConnectionFactory,
+)
+from connpool.observability import PoolListener, PoolStats
+from connpool.policy import IdleStrategy, PoolConfig
+from connpool.pools import AsyncConnectionPool, AsyncPoolRegistry, ConnectionPool, PoolRegistry
+from connpool.resilience import (
+    NO_RETRY, BreakerConfig, BreakerState, CircuitBreaker, RetryPolicy,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # pools
+    "AsyncConnectionPool", "AsyncPoolRegistry", "ConnectionPool", "PoolRegistry",
+    # configuration
+    "BreakerConfig", "IdleStrategy", "NO_RETRY", "PoolConfig", "RetryPolicy",
+    # what you implement
+    "AsyncCallableFactory", "AsyncConnectionFactory", "CallableFactory", "ConnectionFactory",
+    # observability
+    "BreakerState", "CloseReason", "PoolListener", "PoolStats", "PooledConnection",
+    # errors
+    "CircuitOpenError", "ConnectionCreateError", "InvalidReleaseError", "PoolClosedError",
+    "PoolConfigError", "PoolError", "PoolExhaustedError", "PoolTimeoutError",
+    # standalone building blocks / testing
+    "CircuitBreaker", "Clock", "ManualClock", "SystemClock",
+]

connpool/core/__init__.py

@@ -0,0 +1,14 @@
+"""Foundation layer: errors, clocks, connection bookkeeping, timeout helpers.
+Depends on nothing else in connpool."""
+from connpool.core.clock import Clock, ManualClock, SystemClock
+from connpool.core.connection import CloseReason, PooledConnection
+from connpool.core.errors import (
+    CircuitOpenError, ConnectionCreateError, InvalidReleaseError, PoolClosedError,
+    PoolConfigError, PoolError, PoolExhaustedError, PoolTimeoutError,
+)
+
+__all__ = [
+    "CircuitOpenError", "Clock", "CloseReason", "ConnectionCreateError", "InvalidReleaseError",
+    "ManualClock", "PoolClosedError", "PoolConfigError", "PoolError", "PoolExhaustedError",
+    "PoolTimeoutError", "PooledConnection", "SystemClock",
+]

connpool/core/clock.py

@@ -0,0 +1,45 @@
+"""Time source abstraction so every time-dependent rule is deterministic in tests."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Protocol
+
+
+class Clock(Protocol):
+    def monotonic(self) -> float: ...
+    def sleep(self, seconds: float) -> None: ...
+    async def async_sleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    """Real time. The default."""
+
+    def monotonic(self) -> float:
+        return time.monotonic()
+
+    def sleep(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+    async def async_sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+
+class ManualClock:
+    """Fake clock for tests: time moves only when you say so; sleeping just advances it."""
+
+    def __init__(self, start: float = 1000.0) -> None:
+        self._now = start
+
+    def monotonic(self) -> float:
+        return self._now
+
+    def advance(self, seconds: float) -> None:
+        self._now += seconds
+
+    def sleep(self, seconds: float) -> None:
+        self._now += seconds
+
+    async def async_sleep(self, seconds: float) -> None:
+        self._now += seconds
+        await asyncio.sleep(0)

connpool/core/connection.py

@@ -0,0 +1,62 @@
+"""Bookkeeping wrapper around a raw connection."""
+from __future__ import annotations
+
+import enum
+import itertools
+from dataclasses import dataclass, field
+from typing import Generic, Optional, TypeVar
+
+T = TypeVar("T")
+_ids = itertools.count(1)
+
+
+class CloseReason(str, enum.Enum):
+    """Why a connection left the pool."""
+
+    EXPIRED = "expired"            # max_lifetime reached (rotation)
+    MAX_USES = "max_uses"          # max_uses reached (rotation)
+    IDLE = "idle"                  # sat idle longer than max_idle_time
+    UNHEALTHY = "unhealthy"        # failed validation
+    ERROR = "error"                # caller's block raised and the connection is suspect
+    RESET_FAILED = "reset_failed"  # factory.reset() raised on release
+    DISCARDED = "discarded"        # caller asked for it
+    POOL_CLOSED = "pool_closed"
+
+
+@dataclass(eq=False)
+class PooledConnection(Generic[T]):
+    """A raw connection plus the metadata the pool needs to manage it."""
+
+    raw: T
+    created_at: float
+    expires_at: Optional[float] = None
+    last_returned_at: Optional[float] = None
+    checked_out_at: Optional[float] = None
+    use_count: int = 0
+    leak_reported: bool = False
+    id: int = field(default_factory=lambda: next(_ids))
+
+    def __post_init__(self) -> None:
+        if self.last_returned_at is None:
+            self.last_returned_at = self.created_at
+
+    def age(self, now: float) -> float:
+        return now - self.created_at
+
+    def idle_time(self, now: float) -> float:
+        return now - (self.last_returned_at or self.created_at)
+
+    def hold_time(self, now: float) -> float:
+        return 0.0 if self.checked_out_at is None else now - self.checked_out_at
+
+    def mark_checked_out(self, now: float) -> None:
+        self.checked_out_at = now
+        self.use_count += 1
+        self.leak_reported = False
+
+    def mark_returned(self, now: float) -> None:
+        self.checked_out_at = None
+        self.last_returned_at = now
+
+    def __repr__(self) -> str:
+        return f"<PooledConnection #{self.id} uses={self.use_count}>"

connpool/core/errors.py

@@ -0,0 +1,41 @@
+"""Exception hierarchy. Catch ``PoolError`` to handle anything the pool raises."""
+from __future__ import annotations
+
+
+class PoolError(Exception):
+    """Base class for every error raised by connpool."""
+
+
+class PoolConfigError(PoolError, ValueError):
+    """Invalid pool / breaker / retry configuration."""
+
+
+class PoolClosedError(PoolError):
+    """The pool has been closed; no more connections can be acquired."""
+
+
+class PoolTimeoutError(PoolError, TimeoutError):
+    """No connection became available before the acquire deadline."""
+
+
+class PoolExhaustedError(PoolError):
+    """The pool is full and the waiter queue is at ``max_waiters``; shedding load."""
+
+
+class ConnectionCreateError(PoolError):
+    """The factory failed to create a connection (after all retries).
+
+    The original exception is available as ``__cause__``.
+    """
+
+
+class CircuitOpenError(PoolError):
+    """The circuit breaker is rejecting calls to protect a failing backend."""
+
+    def __init__(self, retry_after: float) -> None:
+        super().__init__(f"circuit breaker is open; retry in ~{retry_after:.1f}s")
+        self.retry_after = retry_after
+
+
+class InvalidReleaseError(PoolError):
+    """Released an object that is not checked out from this pool (double release?)."""

connpool/core/timeouts.py

@@ -0,0 +1,25 @@
+"""Tiny shared helpers (internal)."""
+from __future__ import annotations
+
+import enum
+from typing import Optional, Union
+
+
+class _Unset(enum.Enum):
+    UNSET = "unset"
+
+
+UNSET = _Unset.UNSET
+"""Sentinel: "use the configured default" (``None`` already means "wait forever")."""
+
+Timeout = Union[float, None, _Unset]
+
+
+def compute_deadline(timeout: Timeout, default: Optional[float], now: float) -> Optional[float]:
+    if isinstance(timeout, _Unset):
+        timeout = default
+    return None if timeout is None else now + timeout
+
+
+def remaining(deadline: Optional[float], now: float) -> Optional[float]:
+    return None if deadline is None else deadline - now

connpool/factories/__init__.py

@@ -0,0 +1,6 @@
+"""The seam to the outside world: what users implement to pool *any* kind of connection.
+Has no dependency on the rest of connpool."""
+from connpool.factories.async_factory import AsyncCallableFactory, AsyncConnectionFactory
+from connpool.factories.sync_factory import CallableFactory, ConnectionFactory
+
+__all__ = ["AsyncCallableFactory", "AsyncConnectionFactory", "CallableFactory", "ConnectionFactory"]

connpool/factories/async_factory.py

@@ -0,0 +1,68 @@
+"""Asynchronous factory contract: async twin of ``sync_factory``."""
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Awaitable, Callable, Generic, Optional, TypeVar, Union, cast
+
+T = TypeVar("T")
+
+
+async def _maybe_await(value: Union[Any, Awaitable[Any]]) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class AsyncConnectionFactory(ABC, Generic[T]):
+    """Async twin of ``ConnectionFactory``."""
+
+    @abstractmethod
+    async def create(self) -> T: ...
+
+    async def validate(self, conn: T) -> bool:
+        return True
+
+    async def reset(self, conn: T) -> None:
+        return None
+
+    async def close(self, conn: T) -> None:
+        closer = getattr(conn, "close", None)
+        if callable(closer):
+            await _maybe_await(closer())
+
+    def is_fatal_error(self, exc: BaseException) -> bool:
+        return False
+
+
+class AsyncCallableFactory(AsyncConnectionFactory[T]):
+    """Callables may be sync or async - both work."""
+
+    def __init__(
+        self,
+        create: Callable[[], Any],
+        *,
+        close: Optional[Callable[[T], Any]] = None,
+        validate: Optional[Callable[[T], Any]] = None,
+        reset: Optional[Callable[[T], Any]] = None,
+        is_fatal_error: Optional[Callable[[BaseException], bool]] = None,
+    ) -> None:
+        self._create, self._close, self._validate = create, close, validate
+        self._reset, self._is_fatal = reset, is_fatal_error
+
+    async def create(self) -> T:
+        return cast(T, await _maybe_await(self._create()))
+
+    async def validate(self, conn: T) -> bool:
+        return True if self._validate is None else bool(await _maybe_await(self._validate(conn)))
+
+    async def reset(self, conn: T) -> None:
+        if self._reset:
+            await _maybe_await(self._reset(conn))
+
+    async def close(self, conn: T) -> None:
+        if self._close:
+            await _maybe_await(self._close(conn))
+        else:
+            await super().close(conn)
+
+    def is_fatal_error(self, exc: BaseException) -> bool:
+        return bool(self._is_fatal and self._is_fatal(exc))

connpool/factories/sync_factory.py

@@ -0,0 +1,72 @@
+"""Synchronous factory contract: the ONE seam between the pool and the outside world.
+
+To pool *anything* (DB driver, HTTP session, SSH client, socket, gRPC channel...)
+implement ``ConnectionFactory`` - or just pass callables via ``CallableFactory``.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable, Generic, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+class ConnectionFactory(ABC, Generic[T]):
+    """Override ``create``; override the rest only when the default isn't right."""
+
+    @abstractmethod
+    def create(self) -> T:
+        """Open a new connection. Should enforce its own connect timeout."""
+
+    def validate(self, conn: T) -> bool:
+        """Cheap liveness check (e.g. ``SELECT 1``). Return False/raise = dead."""
+        return True
+
+    def reset(self, conn: T) -> None:
+        """Called on release to scrub session state (e.g. ``rollback()``)."""
+
+    def close(self, conn: T) -> None:
+        """Dispose of a connection. Default: call ``conn.close()`` if present."""
+        closer = getattr(conn, "close", None)
+        if callable(closer):
+            closer()
+
+    def is_fatal_error(self, exc: BaseException) -> bool:
+        """True if ``exc`` (raised by user code using the connection) proves the
+        connection is broken, so it is discarded without further checks."""
+        return False
+
+
+class CallableFactory(ConnectionFactory[T]):
+    """Build a factory from plain functions."""
+
+    def __init__(
+        self,
+        create: Callable[[], T],
+        *,
+        close: Optional[Callable[[T], None]] = None,
+        validate: Optional[Callable[[T], bool]] = None,
+        reset: Optional[Callable[[T], None]] = None,
+        is_fatal_error: Optional[Callable[[BaseException], bool]] = None,
+    ) -> None:
+        self._create, self._close, self._validate = create, close, validate
+        self._reset, self._is_fatal = reset, is_fatal_error
+
+    def create(self) -> T:
+        return self._create()
+
+    def validate(self, conn: T) -> bool:
+        return True if self._validate is None else bool(self._validate(conn))
+
+    def reset(self, conn: T) -> None:
+        if self._reset:
+            self._reset(conn)
+
+    def close(self, conn: T) -> None:
+        if self._close:
+            self._close(conn)
+        else:
+            super().close(conn)
+
+    def is_fatal_error(self, exc: BaseException) -> bool:
+        return bool(self._is_fatal and self._is_fatal(exc))

connpool/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Listener hooks and built-in metrics. Depends on ``core`` and ``resilience``."""
+from connpool.observability.events import PoolListener
+from connpool.observability.stats import PoolStats
+
+__all__ = ["PoolListener", "PoolStats"]

connpool/observability/events.py

@@ -0,0 +1,36 @@
+"""Observability hooks. Subclass ``PoolListener`` and override what you care about
+(metrics, tracing, logging). Hooks run synchronously on the calling thread/task, outside
+the pool's lock, so keep them fast. Exceptions raised by listeners are logged and
+swallowed - a broken metrics exporter must never break the pool."""
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable, List
+
+from connpool.resilience.breaker import BreakerState
+from connpool.core.connection import CloseReason, PooledConnection
+
+log = logging.getLogger("connpool")
+
+
+class PoolListener:
+    def on_connection_created(self, conn: PooledConnection[Any], duration: float) -> None: ...
+    def on_connection_closed(self, conn: PooledConnection[Any], reason: CloseReason) -> None: ...
+    def on_create_failed(self, error: BaseException) -> None: ...
+    def on_acquired(self, conn: PooledConnection[Any], wait_time: float) -> None: ...
+    def on_released(self, conn: PooledConnection[Any], hold_time: float) -> None: ...
+    def on_acquire_timeout(self, waited: float) -> None: ...
+    def on_connection_leak(self, conn: PooledConnection[Any], held_for: float) -> None: ...
+    def on_breaker_state_change(self, old: BreakerState, new: BreakerState) -> None: ...
+
+
+class ListenerGroup:
+    def __init__(self, listeners: Iterable[PoolListener]) -> None:
+        self._listeners: List[PoolListener] = list(listeners)
+
+    def dispatch(self, hook: str, *args: object) -> None:
+        for listener in self._listeners:
+            try:
+                getattr(listener, hook)(*args)
+            except Exception:  # noqa: BLE001 - listeners must never break the pool
+                log.exception("pool listener %r failed in %s", listener, hook)

connpool/observability/stats.py

@@ -0,0 +1,118 @@
+"""Built-in metrics: a listener that counts events, plus an immutable snapshot."""
+from __future__ import annotations
+
+import threading
+from collections import Counter, deque
+from dataclasses import dataclass, field
+from typing import Any, Deque, Dict, List, Optional
+
+from connpool.core.connection import CloseReason, PooledConnection
+from connpool.observability.events import PoolListener
+
+ACQUIRE_WAIT_WINDOW = 1024
+"""How many recent acquire-wait / create-latency samples to keep. ``avg`` and all percentiles
+are computed over this same window (bounded memory), so they always describe the same
+population."""
+
+
+def percentile(sorted_values: List[float], q: float) -> float:
+    """Linear-interpolated percentile of an already-sorted list. ``q`` in [0, 1]."""
+    if not sorted_values:
+        return 0.0
+    k = (len(sorted_values) - 1) * q
+    lo = int(k)
+    hi = min(lo + 1, len(sorted_values) - 1)
+    return sorted_values[lo] + (sorted_values[hi] - sorted_values[lo]) * (k - lo)
+
+
+@dataclass(frozen=True)
+class PoolStats:
+    name: str
+    max_size: int
+    size: int            # idle + in use + being created
+    idle: int            # available for checkout right now
+    in_use: int          # checked out: held by a caller, OR briefly reserved by a background
+                         # idle health check (validate_idle) while it pings them off-lock
+    waiting: int         # callers currently blocked in acquire()
+    created: int
+    create_failures: int
+    acquired: int
+    released: int
+    timeouts: int
+    closed: int
+    leaks: int = 0       # borrowed connections flagged as possibly leaked
+    closed_by_reason: Dict[str, int] = field(default_factory=dict)
+    # acquire-wait aggregates, all over the last ACQUIRE_WAIT_WINDOW samples
+    avg_acquire_wait: float = 0.0
+    p50_acquire_wait: float = 0.0
+    p95_acquire_wait: float = 0.0
+    p99_acquire_wait: float = 0.0
+    # create-latency aggregates (factory.create() duration), same window
+    avg_create_latency: float = 0.0
+    p50_create_latency: float = 0.0
+    p95_create_latency: float = 0.0
+    p99_create_latency: float = 0.0
+    breaker_state: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return dict(self.__dict__)
+
+
+class StatsCollector(PoolListener):
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._n: Counter[str] = Counter()
+        self._by_reason: Counter[str] = Counter()
+        self._waits: Deque[float] = deque(maxlen=ACQUIRE_WAIT_WINDOW)
+        self._creates: Deque[float] = deque(maxlen=ACQUIRE_WAIT_WINDOW)
+
+    def _inc(self, key: str) -> None:
+        with self._lock:
+            self._n[key] += 1
+
+    def on_connection_created(self, conn: PooledConnection[Any], duration: float) -> None:
+        with self._lock:
+            self._n["created"] += 1
+            self._creates.append(duration)
+
+    def on_create_failed(self, error: BaseException) -> None:
+        self._inc("create_failures")
+
+    def on_connection_closed(self, conn: PooledConnection[Any], reason: CloseReason) -> None:
+        with self._lock:
+            self._n["closed"] += 1
+            self._by_reason[reason.value] += 1
+
+    def on_acquired(self, conn: PooledConnection[Any], wait_time: float) -> None:
+        with self._lock:
+            self._n["acquired"] += 1
+            self._waits.append(wait_time)
+
+    def on_released(self, conn: PooledConnection[Any], hold_time: float) -> None:
+        self._inc("released")
+
+    def on_acquire_timeout(self, waited: float) -> None:
+        self._inc("timeouts")
+
+    def on_connection_leak(self, conn: PooledConnection[Any], held_for: float) -> None:
+        self._inc("leaks")
+
+    def snapshot(self, **gauges: Any) -> PoolStats:
+        with self._lock:
+            n = self._n
+            waits = sorted(self._waits)
+            creates = sorted(self._creates)
+            return PoolStats(
+                created=n["created"], create_failures=n["create_failures"], acquired=n["acquired"],
+                released=n["released"], timeouts=n["timeouts"], closed=n["closed"],
+                leaks=n["leaks"], closed_by_reason=dict(self._by_reason),
+                avg_acquire_wait=(sum(waits) / len(waits)) if waits else 0.0,
+                p50_acquire_wait=percentile(waits, 0.50),
+                p95_acquire_wait=percentile(waits, 0.95),
+                p99_acquire_wait=percentile(waits, 0.99),
+                avg_create_latency=(sum(creates) / len(creates)) if creates else 0.0,
+                p50_create_latency=percentile(creates, 0.50),
+                p95_create_latency=percentile(creates, 0.95),
+                p99_create_latency=percentile(creates, 0.99),
+                **gauges,
+            )

connpool/policy/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration and the pure rules that decide when a connection must retire.
+Depends on ``core`` and ``resilience``."""
+from connpool.policy.config import IdleStrategy, PoolConfig
+
+__all__ = ["IdleStrategy", "PoolConfig"]

connpool/policy/config.py

@@ -0,0 +1,72 @@
+"""Pool configuration: one immutable, validated object."""
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field, replace
+from typing import Any, Optional
+
+from connpool.resilience.breaker import BreakerConfig
+from connpool.core.errors import PoolConfigError
+from connpool.resilience.retry import RetryPolicy
+
+
+class IdleStrategy(str, enum.Enum):
+    LIFO = "lifo"  # reuse the hottest connection; cold ones age out and get evicted
+    FIFO = "fifo"  # reuse the oldest idle connection; spreads load / rotates evenly
+
+
+@dataclass(frozen=True)
+class PoolConfig:
+    # --- sizing ---
+    min_size: int = 0                       # kept warm by open() and the maintenance pass
+    max_size: int = 10                      # hard cap (idle + in use + being created)
+
+    # --- timeouts (seconds; None = no limit) ---
+    acquire_timeout: Optional[float] = 30.0   # default wait in acquire()
+    create_timeout: Optional[float] = 10.0    # enforced by AsyncConnectionPool only; sync
+                                              # factories must enforce their own connect timeout
+    max_waiters: Optional[int] = None         # backpressure: cap callers blocked in acquire()
+                                              # (None = unlimited; 0 = never wait when full)
+
+    # --- rotation / recycling ---
+    max_lifetime: Optional[float] = 1800.0  # retire connections after this age
+    lifetime_jitter: float = 0.1            # shave up to 10% off each lifetime so a
+                                            # whole pool never expires at the same instant
+    max_idle_time: Optional[float] = 600.0  # evict idle connections (down to min_size)
+    max_uses: Optional[int] = None          # retire after N checkouts
+    idle_strategy: IdleStrategy = IdleStrategy.LIFO
+
+    # --- health ---
+    validate_after_idle: Optional[float] = 30.0  # validate on checkout if idle >= this
+                                                 # (0 = always, None = never)
+    maintenance_interval: Optional[float] = 30.0  # background sweep period (None = off)
+    leak_detection_timeout: Optional[float] = None  # warn when a borrowed connection is held
+                                                    # longer than this (None = off); needs open()
+    validate_idle: bool = False             # validate idle connections during the maintenance
+                                            # sweep and evict dead ones (needs open(); adds I/O)
+
+    # --- resilience ---
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    breaker: Optional[BreakerConfig] = field(default_factory=BreakerConfig)  # None = off
+
+    def __post_init__(self) -> None:
+        def need(ok: bool, msg: str) -> None:
+            if not ok:
+                raise PoolConfigError(msg)
+
+        need(self.max_size >= 1, "max_size must be >= 1")
+        need(0 <= self.min_size <= self.max_size, "min_size must be within [0, max_size]")
+        need(self.acquire_timeout is None or self.acquire_timeout >= 0, "acquire_timeout must be >= 0")
+        for name in ("create_timeout", "max_lifetime", "max_idle_time", "maintenance_interval",
+                     "leak_detection_timeout"):
+            value = getattr(self, name)
+            need(value is None or value > 0, f"{name} must be > 0 or None")
+        need(self.validate_after_idle is None or self.validate_after_idle >= 0,
+             "validate_after_idle must be >= 0 or None")
+        need(0.0 <= self.lifetime_jitter <= 1.0, "lifetime_jitter must be within [0, 1]")
+        need(self.max_uses is None or self.max_uses >= 1, "max_uses must be >= 1 or None")
+        need(self.max_waiters is None or self.max_waiters >= 0, "max_waiters must be >= 0 or None")
+
+    def replace(self, **changes: Any) -> "PoolConfig":
+        """Return a modified copy (the config itself is immutable)."""
+        return replace(self, **changes)