connpool 1.0.2__tar.gz

connpool-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Ilyushin (Jeffeek)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connpool-1.0.2/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: connpool
+Version: 1.0.2
+Summary: Generic connection pool for Python (sync + asyncio), standard library only
+Author: Mikhail Ilyushin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Jeffeek/poolyglot/python
+Project-URL: Repository, https://github.com/Jeffeek/poolyglot
+Project-URL: Issues, https://github.com/Jeffeek/poolyglot/issues
+Keywords: connection pool,pool,asyncio,database,resource,circuit breaker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# connpool
+
+A generic connection pool for Python 3.11+ — sync (threads) and `asyncio`. **Standard library only**
+(no third-party runtime dependencies). It pools *anything*: DB drivers, HTTP sessions, SSH clients, sockets…
+because the pool knows nothing about connections except what a small `ConnectionFactory` tells it.
+
+```python
+from connpool import ConnectionPool, PoolConfig
+
+pool = ConnectionPool.from_callables(make_conn, validate=is_alive, config=PoolConfig(max_size=20))
+with pool:                                  # optional: warm-up + background sweeper
+    with pool.connection() as conn:         # acquire -> use -> release (errors handled)
+        conn.do_something()
+```
+
+## Project layout
+
+```
+src/connpool/                 the library (imports: standard library only)
+  core/            errors, clocks, PooledConnection/CloseReason, timeout helpers
+  resilience/      breaker.py (circuit breaker), retry.py (backoff policy)
+  policy/          config.py (PoolConfig), lifecycle.py (pure "when must a connection retire?" rules)
+  factories/       sync_factory.py, async_factory.py  <- what YOU implement to pool anything
+  observability/   events.py (PoolListener), stats.py (metrics)
+  pools/           sync_pool.py, async_pool.py, registry.py (pool-per-key)
+tests/             mirrors src/ (unittest, no dependencies)
+  support/         fake factories and helpers
+examples/          client code - NOT part of the library
+  database/        generic DB-API factory (any driver), sqlite3 demo (runnable), psycopg demo
+  http_client/  ssh/  async_usage/
+```
+
+Dependency direction is strictly downward (a layer only imports from layers listed above it):
+`core → resilience → policy → factories/observability → pools`. The top-level `connpool/__init__.py` is a
+facade re-exporting the public API, so `from connpool import ConnectionPool` keeps working even if internal
+modules move.
+
+## What you get
+
+| Concern | How it works |
+|---|---|
+| Sizing | `min_size` kept warm, `max_size` is a *hard* cap (slot reserved before create) |
+| Timeouts | `acquire_timeout` (per-call override), `create_timeout` (async), retries never sleep past the deadline |
+| Rotation | `max_lifetime` (with jitter), `max_uses`, `max_idle_time`, `LIFO`/`FIFO` reuse |
+| Health | validate on checkout if idle ≥ `validate_after_idle`; `reset()` on release; after an exception: fatal → discard, otherwise re-validate; optional `validate_idle` pings idle connections in the background sweep and reaps dead ones |
+| Retries | exponential backoff + jitter, `retry_on` filter |
+| Circuit breaker | closed → open → half-open, probe limits, state-change events; open = fail fast. Counts **one failure per logical creation** (a whole retry sequence), not per attempt. A create failure *or* a `create_timeout` (slow backend) counts; an acquire-timeout or cancellation mid-create does not |
+| Backpressure | `max_waiters` caps the blocked-caller queue; excess callers fail fast with `PoolExhaustedError` |
+| Leak detection | `leak_detection_timeout` warns (via log + `on_connection_leak`) when a borrowed connection is held too long; warn-only, never force-reclaimed |
+| Observability | `PoolListener` hooks + `pool.stats()` snapshot (counters, **avg + p50/p95/p99** for both acquire-wait and create-latency over a recent window) |
+| Shutdown | idempotent `close()`, wakes blocked callers, in-use connections close on release; `close(timeout=)` drains gracefully; a `ResourceWarning` fires if a pool is GC'd un-closed |
+| Cancellation | asyncio cancellation never leaks a slot |
+| Many backends | `PoolRegistry` / `AsyncPoolRegistry` = one lazily-created pool per key (host, tenant, DB) |
+
+## Writing a factory
+
+```python
+class MyFactory(ConnectionFactory[MyConn]):
+    def create(self):            return MyConn.connect(...)        # enforce your own connect timeout
+    def validate(self, c):       return c.ping()                    # cheap liveness check
+    def reset(self, c):          c.rollback()                       # scrub session state on release
+    def close(self, c):          c.close()                          # default: calls c.close()
+    def is_fatal_error(self, e): return isinstance(e, ConnectionError)
+```
+Async: subclass `AsyncConnectionFactory`, or pass sync/async callables to `AsyncConnectionPool.from_callables`.
+`examples/database/dbapi_factory.py` shows one factory that covers every PEP 249 database driver.
+
+## Configuration (`PoolConfig`)
+
+| Field | Default | Meaning |
+|---|---|---|
+| `min_size` / `max_size` | 0 / 10 | warm connections / hard cap |
+| `acquire_timeout` | 30 | seconds to wait (`None` = forever, `0` = don't wait) |
+| `max_waiters` | None | backpressure: cap callers blocked in `acquire()` (excess → `PoolExhaustedError`; `None` = unlimited, `0` = never wait when full) |
+| `create_timeout` | 10 | async only; sync factories enforce their own |
+| `max_lifetime` / `lifetime_jitter` | 1800 / 0.1 | retire after age, shaved by up to 10% |
+| `max_idle_time` | 600 | evict idle connections (never below `min_size`) |
+| `max_uses` | None | retire after N checkouts |
+| `idle_strategy` | LIFO | `FIFO` spreads load evenly |
+| `validate_after_idle` | 30 | validate on checkout if idle this long (0 = always, None = never) |
+| `validate_idle` | False | also validate idle connections during the background sweep and reap dead ones (needs `open()`; adds I/O) |
+| `maintenance_interval` | 30 | background sweep period (None = off) |
+| `leak_detection_timeout` | None | warn when a borrowed connection is held longer than this (needs `open()`; checked once per `maintenance_interval` sweep; None = off) |
+| `retry` | 3 attempts, 0.1s base, ×2, 5s cap | `RetryPolicy` (`NO_RETRY` disables) |
+| `breaker` | 5 failures / 30s recovery | `BreakerConfig` (`None` disables); `failure_threshold` counts failed *creations*, not retry attempts |
+
+## Install, test, run examples
+
+```
+pip install -e .                                  # or: export PYTHONPATH=src
+pip install -e ".[dev]"                           # + coverage/pytest/mypy
+python -m unittest discover -s tests -t .         # 142 tests, ~2s
+./run_tests.sh                                     # same, with a compact coverage report (gate: 100%)
+mypy                                               # strict type check (config in pyproject.toml)
+python examples/database/sqlite_demo.py
+```
+(`pytest` works too if installed; configuration is in `pyproject.toml`.)
+Examples importing `paramiko` or `psycopg` need those packages; the library never does.
+
+## Limits / extension points
+
+* The breaker guards connection *creation*. To also trip on request failures wrap calls with `CircuitBreaker.call()`.
+* The breaker counts consecutive failed creations (one per logical acquire, retries included). A real backend failure or a `create_timeout` firing (the backend is too slow to connect — a genuine fault) both count; an acquire-timeout (caller impatience) or cancellation mid-create does not. A rate-based window is a drop-in replacement of one class.
+* Leak detection is **warn-only** by design — the pool never yanks a connection a caller may still be using. It also only runs while the pool is `open()` (the maintenance sweep drives it), so registry pools need an explicit `open()`, and a warning can lag the real leak by up to one `maintenance_interval`.
+* **Not fork-safe.** A pool `open()`ed before `os.fork()` (e.g. a pre-forking server like gunicorn with `preload`, or `multiprocessing`) shares live connections/file descriptors with the children — close the pool before forking and create a fresh one per process (`max_size` is per-process).
+* Pool size is fixed at construction (`PoolConfig` is immutable); there is no runtime resize. Use a new pool, or a `PoolRegistry` keyed by profile, if you need different caps at runtime.
+* Wake-up order of blocked threads is not strictly FIFO.
+* Sync `create()` can't be interrupted by the pool; give your client a connect timeout.
+* Listener hooks are synchronous; push heavy work to a queue.
+* A factory's `create()` must return a **distinct** object each call; returning a shared/singleton connection is rejected with `ConnectionCreateError` (the pool tracks borrow state by object identity).
+* `acquire_wait` percentiles are estimated over the last 1024 samples (bounded memory), not the full history.
+* With `validate_idle` on, idle connections being pinged by the background sweep are briefly reserved and count as `in_use` (not `idle`) in `stats()` for the duration of that check — they are genuinely unavailable while validated, not borrowed by a caller.
+
+## Considered, not implemented
+
+These are deliberate scope decisions, not oversights. For most, something already in the
+library covers the real need; adding them would make the pool heavier for every user to serve
+a minority. Listed here so the trade-off is explicit and the upgrade path is known.
+
+| Feature | How it would be implemented | Why not (and what covers it today) |
+|---|---|---|
+| **Runtime resize** | Make `max_size`/`min_size` mutable behind the lock; on grow, raise the cap and `notify_all` waiters; on shrink, mark excess idle connections for disposal and let in-use ones close on release (never force-closed). | Erodes the immutable-`PoolConfig` invariant (predictability is a feature); shrink is fiddly. Use a fresh pool or a `PoolRegistry` keyed by profile — and `min_size`↔`max_size` already flexes with load. |
+| **Adaptive sizing** | A control loop that tunes `max_size` from live metrics (saturation, acquire latency), with hysteresis to avoid oscillation. | Genuinely hard to do well and easy to make worse than static. `min_size` + `max_size` + idle eviction is already a simple, deterministic adaptive scheme (grow to max under load, shrink to min when quiet). |
+| **Priority acquisition** | Replace the single `Condition` with a priority heap of per-waiter futures; `release()` hands the connection to the highest-priority waiter; timeouts/cancellation remove waiters from the heap. | Ordering ≠ isolation, and it complicates the hot path. Prefer **separate pools** (a `PoolRegistry` acts as bulkheads): give batch its own small pool and interactive its own. |
+| **Create-rate limiting** | A token-bucket / min-interval gate in the create path, checked after reserving a slot and bounded by `acquire_timeout`. | Connection storms are already bounded by `max_size` (caps concurrent creates) and the circuit breaker (halts storms after failures). Add only if a backend imposes a literal connect/sec quota — this is the cheapest of these to add if ever needed. |
+| **Lease handles (use-after-release protection)** | Return a proxy wrapping the raw connection, forwarding attribute access and invalidating itself on release. | A Python proxy is bypassable (the underlying object is always reachable), so it is a guardrail, not a guarantee, and it taxes every call. The context manager + identity tracking already give deterministic release and detect double/foreign release. |
+| **Broken-connection quarantine** | Move suspect connections to a side store with a reason/timestamp and a debug API, instead of closing them. | Quarantine's only real value is forensic; in steady state you *want* broken connections closed — hoarding dead file descriptors is a resource leak by design (HikariCP/asyncpg discard too). Use the `on_connection_closed(conn, reason)` hook to snapshot metadata at close time if you need diagnostics. |

connpool-1.0.2/README.md

@@ -0,0 +1,127 @@
+# connpool
+
+A generic connection pool for Python 3.11+ — sync (threads) and `asyncio`. **Standard library only**
+(no third-party runtime dependencies). It pools *anything*: DB drivers, HTTP sessions, SSH clients, sockets…
+because the pool knows nothing about connections except what a small `ConnectionFactory` tells it.
+
+```python
+from connpool import ConnectionPool, PoolConfig
+
+pool = ConnectionPool.from_callables(make_conn, validate=is_alive, config=PoolConfig(max_size=20))
+with pool:                                  # optional: warm-up + background sweeper
+    with pool.connection() as conn:         # acquire -> use -> release (errors handled)
+        conn.do_something()
+```
+
+## Project layout
+
+```
+src/connpool/                 the library (imports: standard library only)
+  core/            errors, clocks, PooledConnection/CloseReason, timeout helpers
+  resilience/      breaker.py (circuit breaker), retry.py (backoff policy)
+  policy/          config.py (PoolConfig), lifecycle.py (pure "when must a connection retire?" rules)
+  factories/       sync_factory.py, async_factory.py  <- what YOU implement to pool anything
+  observability/   events.py (PoolListener), stats.py (metrics)
+  pools/           sync_pool.py, async_pool.py, registry.py (pool-per-key)
+tests/             mirrors src/ (unittest, no dependencies)
+  support/         fake factories and helpers
+examples/          client code - NOT part of the library
+  database/        generic DB-API factory (any driver), sqlite3 demo (runnable), psycopg demo
+  http_client/  ssh/  async_usage/
+```
+
+Dependency direction is strictly downward (a layer only imports from layers listed above it):
+`core → resilience → policy → factories/observability → pools`. The top-level `connpool/__init__.py` is a
+facade re-exporting the public API, so `from connpool import ConnectionPool` keeps working even if internal
+modules move.
+
+## What you get
+
+| Concern | How it works |
+|---|---|
+| Sizing | `min_size` kept warm, `max_size` is a *hard* cap (slot reserved before create) |
+| Timeouts | `acquire_timeout` (per-call override), `create_timeout` (async), retries never sleep past the deadline |
+| Rotation | `max_lifetime` (with jitter), `max_uses`, `max_idle_time`, `LIFO`/`FIFO` reuse |
+| Health | validate on checkout if idle ≥ `validate_after_idle`; `reset()` on release; after an exception: fatal → discard, otherwise re-validate; optional `validate_idle` pings idle connections in the background sweep and reaps dead ones |
+| Retries | exponential backoff + jitter, `retry_on` filter |
+| Circuit breaker | closed → open → half-open, probe limits, state-change events; open = fail fast. Counts **one failure per logical creation** (a whole retry sequence), not per attempt. A create failure *or* a `create_timeout` (slow backend) counts; an acquire-timeout or cancellation mid-create does not |
+| Backpressure | `max_waiters` caps the blocked-caller queue; excess callers fail fast with `PoolExhaustedError` |
+| Leak detection | `leak_detection_timeout` warns (via log + `on_connection_leak`) when a borrowed connection is held too long; warn-only, never force-reclaimed |
+| Observability | `PoolListener` hooks + `pool.stats()` snapshot (counters, **avg + p50/p95/p99** for both acquire-wait and create-latency over a recent window) |
+| Shutdown | idempotent `close()`, wakes blocked callers, in-use connections close on release; `close(timeout=)` drains gracefully; a `ResourceWarning` fires if a pool is GC'd un-closed |
+| Cancellation | asyncio cancellation never leaks a slot |
+| Many backends | `PoolRegistry` / `AsyncPoolRegistry` = one lazily-created pool per key (host, tenant, DB) |
+
+## Writing a factory
+
+```python
+class MyFactory(ConnectionFactory[MyConn]):
+    def create(self):            return MyConn.connect(...)        # enforce your own connect timeout
+    def validate(self, c):       return c.ping()                    # cheap liveness check
+    def reset(self, c):          c.rollback()                       # scrub session state on release
+    def close(self, c):          c.close()                          # default: calls c.close()
+    def is_fatal_error(self, e): return isinstance(e, ConnectionError)
+```
+Async: subclass `AsyncConnectionFactory`, or pass sync/async callables to `AsyncConnectionPool.from_callables`.
+`examples/database/dbapi_factory.py` shows one factory that covers every PEP 249 database driver.
+
+## Configuration (`PoolConfig`)
+
+| Field | Default | Meaning |
+|---|---|---|
+| `min_size` / `max_size` | 0 / 10 | warm connections / hard cap |
+| `acquire_timeout` | 30 | seconds to wait (`None` = forever, `0` = don't wait) |
+| `max_waiters` | None | backpressure: cap callers blocked in `acquire()` (excess → `PoolExhaustedError`; `None` = unlimited, `0` = never wait when full) |
+| `create_timeout` | 10 | async only; sync factories enforce their own |
+| `max_lifetime` / `lifetime_jitter` | 1800 / 0.1 | retire after age, shaved by up to 10% |
+| `max_idle_time` | 600 | evict idle connections (never below `min_size`) |
+| `max_uses` | None | retire after N checkouts |
+| `idle_strategy` | LIFO | `FIFO` spreads load evenly |
+| `validate_after_idle` | 30 | validate on checkout if idle this long (0 = always, None = never) |
+| `validate_idle` | False | also validate idle connections during the background sweep and reap dead ones (needs `open()`; adds I/O) |
+| `maintenance_interval` | 30 | background sweep period (None = off) |
+| `leak_detection_timeout` | None | warn when a borrowed connection is held longer than this (needs `open()`; checked once per `maintenance_interval` sweep; None = off) |
+| `retry` | 3 attempts, 0.1s base, ×2, 5s cap | `RetryPolicy` (`NO_RETRY` disables) |
+| `breaker` | 5 failures / 30s recovery | `BreakerConfig` (`None` disables); `failure_threshold` counts failed *creations*, not retry attempts |
+
+## Install, test, run examples
+
+```
+pip install -e .                                  # or: export PYTHONPATH=src
+pip install -e ".[dev]"                           # + coverage/pytest/mypy
+python -m unittest discover -s tests -t .         # 142 tests, ~2s
+./run_tests.sh                                     # same, with a compact coverage report (gate: 100%)
+mypy                                               # strict type check (config in pyproject.toml)
+python examples/database/sqlite_demo.py
+```
+(`pytest` works too if installed; configuration is in `pyproject.toml`.)
+Examples importing `paramiko` or `psycopg` need those packages; the library never does.
+
+## Limits / extension points
+
+* The breaker guards connection *creation*. To also trip on request failures wrap calls with `CircuitBreaker.call()`.
+* The breaker counts consecutive failed creations (one per logical acquire, retries included). A real backend failure or a `create_timeout` firing (the backend is too slow to connect — a genuine fault) both count; an acquire-timeout (caller impatience) or cancellation mid-create does not. A rate-based window is a drop-in replacement of one class.
+* Leak detection is **warn-only** by design — the pool never yanks a connection a caller may still be using. It also only runs while the pool is `open()` (the maintenance sweep drives it), so registry pools need an explicit `open()`, and a warning can lag the real leak by up to one `maintenance_interval`.
+* **Not fork-safe.** A pool `open()`ed before `os.fork()` (e.g. a pre-forking server like gunicorn with `preload`, or `multiprocessing`) shares live connections/file descriptors with the children — close the pool before forking and create a fresh one per process (`max_size` is per-process).
+* Pool size is fixed at construction (`PoolConfig` is immutable); there is no runtime resize. Use a new pool, or a `PoolRegistry` keyed by profile, if you need different caps at runtime.
+* Wake-up order of blocked threads is not strictly FIFO.
+* Sync `create()` can't be interrupted by the pool; give your client a connect timeout.
+* Listener hooks are synchronous; push heavy work to a queue.
+* A factory's `create()` must return a **distinct** object each call; returning a shared/singleton connection is rejected with `ConnectionCreateError` (the pool tracks borrow state by object identity).
+* `acquire_wait` percentiles are estimated over the last 1024 samples (bounded memory), not the full history.
+* With `validate_idle` on, idle connections being pinged by the background sweep are briefly reserved and count as `in_use` (not `idle`) in `stats()` for the duration of that check — they are genuinely unavailable while validated, not borrowed by a caller.
+
+## Considered, not implemented
+
+These are deliberate scope decisions, not oversights. For most, something already in the
+library covers the real need; adding them would make the pool heavier for every user to serve
+a minority. Listed here so the trade-off is explicit and the upgrade path is known.
+
+| Feature | How it would be implemented | Why not (and what covers it today) |
+|---|---|---|
+| **Runtime resize** | Make `max_size`/`min_size` mutable behind the lock; on grow, raise the cap and `notify_all` waiters; on shrink, mark excess idle connections for disposal and let in-use ones close on release (never force-closed). | Erodes the immutable-`PoolConfig` invariant (predictability is a feature); shrink is fiddly. Use a fresh pool or a `PoolRegistry` keyed by profile — and `min_size`↔`max_size` already flexes with load. |
+| **Adaptive sizing** | A control loop that tunes `max_size` from live metrics (saturation, acquire latency), with hysteresis to avoid oscillation. | Genuinely hard to do well and easy to make worse than static. `min_size` + `max_size` + idle eviction is already a simple, deterministic adaptive scheme (grow to max under load, shrink to min when quiet). |
+| **Priority acquisition** | Replace the single `Condition` with a priority heap of per-waiter futures; `release()` hands the connection to the highest-priority waiter; timeouts/cancellation remove waiters from the heap. | Ordering ≠ isolation, and it complicates the hot path. Prefer **separate pools** (a `PoolRegistry` acts as bulkheads): give batch its own small pool and interactive its own. |
+| **Create-rate limiting** | A token-bucket / min-interval gate in the create path, checked after reserving a slot and bounded by `acquire_timeout`. | Connection storms are already bounded by `max_size` (caps concurrent creates) and the circuit breaker (halts storms after failures). Add only if a backend imposes a literal connect/sec quota — this is the cheapest of these to add if ever needed. |
+| **Lease handles (use-after-release protection)** | Return a proxy wrapping the raw connection, forwarding attribute access and invalidating itself on release. | A Python proxy is bypassable (the underlying object is always reachable), so it is a guardrail, not a guarantee, and it taxes every call. The context manager + identity tracking already give deterministic release and detect double/foreign release. |
+| **Broken-connection quarantine** | Move suspect connections to a side store with a reason/timestamp and a debug API, instead of closing them. | Quarantine's only real value is forensic; in steady state you *want* broken connections closed — hoarding dead file descriptors is a resource leak by design (HikariCP/asyncpg discard too). Use the `on_connection_closed(conn, reason)` hook to snapshot metadata at close time if you need diagnostics. |

connpool-1.0.2/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=77"]          # >=77 for the SPDX `license` string form (PEP 639)
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "connpool"
+version = "1.0.2"
+description = "Generic connection pool for Python (sync + asyncio), standard library only"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mikhail Ilyushin" }]
+keywords = ["connection pool", "pool", "asyncio", "database", "resource", "circuit breaker"]
+dependencies = []                      # runtime: standard library only
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Jeffeek/poolyglot/python"
+Repository = "https://github.com/Jeffeek/poolyglot"
+Issues = "https://github.com/Jeffeek/poolyglot/issues"
+
+[project.optional-dependencies]
+# Dev tooling only - the library itself stays dependency-free.
+#   pip install -e ".[dev]"
+dev = [
+    "coverage>=7",                     # used by run_tests.sh
+    "pytest>=8",                       # optional: `pytest` also works (see [tool.pytest.ini_options])
+    "mypy>=1.8",                       # static type checking (the package ships py.typed)
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+connpool = ["py.typed"]
+
+[tool.pytest.ini_options]              # optional: `pytest` also works if you prefer it
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src"]
+
+[tool.coverage.report]
+precision = 1
+show_missing = true
+# The library targets 100% line coverage; CI fails below it.
+fail_under = 100
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]

connpool-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

connpool-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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"]