pgcommon 0.3.0__tar.gz → 0.3.1__tar.gz

{pgcommon-0.3.0 → pgcommon-0.3.1}/CHANGELOG.md

@@ -11,6 +11,12 @@ public API.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-15
+
+### Security
+
+- `Config` and `ResolvedConfig` no longer print the DSN's password in their `repr` (and so in `str`, tracebacks, debuggers and log lines that format the object): the generated dataclass repr showed the DSN as is. The `dsn` field is now shown through `mask_dsn`; the field value itself is unchanged. Found by platform-eventcommon's review (its `OutboxEnv.pool_config()` hands the `Config` to callers).
+
 ## [0.3.0] - 2026-10-15
 
 Brings the port in line with Go `platform-pgcommon` **v2.0.1**: the Tier 1 metrics below, plus

{pgcommon-0.3.0 → pgcommon-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgcommon
-Version: 0.3.0
+Version: 0.3.1
 Summary: Opinionated async PostgreSQL access layer for platform services — RLS tenancy, retries, and observability by default.
 Project-URL: Homepage, https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
 Project-URL: Repository, https://github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
@@ -32,7 +32,7 @@ The platform's **PostgreSQL access layer for Python services**: an `asyncio` lib
 
 **Repository:** `github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py` (private)
 
-**Package:** `pgcommon` 0.3.0 ([release status](#versioning-and-releases): released 2026-10-15, on [PyPI](https://pypi.org/project/pgcommon/)) · Apache-2.0 · Python ≥ 3.12 (CI runs 3.12, 3.13 and 3.14) · consumed as a dependency, never deployed on its own. It also ships one artefact, the `pgcommon-migrate` CLI, as a container image (`ghcr.io/bcbp-solutions-fzc-llc/platform-pgcommon-py`).
+**Package:** `pgcommon` 0.3.1 ([release status](#versioning-and-releases): released 2026-10-15, on [PyPI](https://pypi.org/project/pgcommon/)) · Apache-2.0 · Python ≥ 3.12 (CI runs 3.12, 3.13 and 3.14) · consumed as a dependency, never deployed on its own. It also ships one artefact, the `pgcommon-migrate` CLI, as a container image (`ghcr.io/bcbp-solutions-fzc-llc/platform-pgcommon-py`).
 
 **Design:** one `src/pgcommon` package — public modules on top of a private `_internal/` layer, with the layer rules enforced by import-linter in CI. See [ARCHITECTURE.md](ARCHITECTURE.md) for design decisions, layer diagrams, and — importantly — how this port's `asyncio`/`contextvars` model differs from the Go original's `context.Context` model. This README is how to **use** it.
 
@@ -2040,8 +2040,8 @@ pgcommon itself is released to PyPI, and services adopt it by bumping their pin;
 Pin an exact version in production ([VERSIONING.md § Consume a release](VERSIONING.md#consume-a-release) has the pin styles):
 
 ```bash
-pip install "pgcommon==0.3.0"            # or "pgcommon[fastapi]==0.3.0" / "pgcommon[structlog]==0.3.0"
-uv add "pgcommon==0.3.0"
+pip install "pgcommon==0.3.1"            # or "pgcommon[fastapi]==0.3.1" / "pgcommon[structlog]==0.3.1"
+uv add "pgcommon==0.3.1"
 ```
 
 The files on PyPI are byte-identical to the GitHub Release's wheel and sdist: the release builds them once and uploads the same files to both.
@@ -2059,7 +2059,7 @@ Two-stage `Dockerfile`. The build stage (`python:3.14-slim` with uv `0.11.32`, b
 Needs [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) ≥ 2.4. A tag-triggered release is signed by `release.yml@refs/tags/<tag>`; a re-run dispatched from `main` by `release.yml@refs/heads/main`, which the regular expression below also accepts.
 
 ```bash
-TAG=v0.3.0   # the release to verify
+TAG=v0.3.1   # the release to verify
 REPO=BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
 IDENTITY="^https://github\.com/${REPO}/\.github/workflows/release\.yml@refs/(tags/${TAG}|heads/main)$"
 
@@ -2208,7 +2208,7 @@ MIGRATIONS_DIR=/migrations
 
 | Consumer | pgcommon pin | Uses |
 |---|---|---|
-| `platform-eventcommon` (Python port of `platform-events`) | `>=0.2.0,<0.3.0` — moving to 0.3.0 needs a coordinated change ([Upgrading from 0.2.0](#upgrading-from-020)) | `Pool` and `run_in_tx` for its outbox, inbox and DLQ stores; `with_guc_set` so message handlers run under RLS; `MigrationDirtyError` for its own schema bookkeeping |
+| `platform-eventcommon` (Python port of `platform-events`) | `>=0.2.0,<0.4.0` on its `main` (its next release, 0.3.0, requires `>=0.3.0,<0.4.0`) | `Pool` and `run_in_tx` for its outbox, inbox and DLQ stores; `with_guc_set` so message handlers run under RLS; `MigrationDirtyError` for its own schema bookkeeping |
 | `platform-interop-tests` (Python probe) | — | Cross-language compatibility with the Go library (CI's `interop` job) |
 | FastAPI platform services | their own | Pool, RLS injection, transactions, error helpers, metrics, `pgcommon.integrations.fastapi` |
 

{pgcommon-0.3.0 → pgcommon-0.3.1}/README.md

@@ -6,7 +6,7 @@ The platform's **PostgreSQL access layer for Python services**: an `asyncio` lib
 
 **Repository:** `github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py` (private)
 
-**Package:** `pgcommon` 0.3.0 ([release status](#versioning-and-releases): released 2026-10-15, on [PyPI](https://pypi.org/project/pgcommon/)) · Apache-2.0 · Python ≥ 3.12 (CI runs 3.12, 3.13 and 3.14) · consumed as a dependency, never deployed on its own. It also ships one artefact, the `pgcommon-migrate` CLI, as a container image (`ghcr.io/bcbp-solutions-fzc-llc/platform-pgcommon-py`).
+**Package:** `pgcommon` 0.3.1 ([release status](#versioning-and-releases): released 2026-10-15, on [PyPI](https://pypi.org/project/pgcommon/)) · Apache-2.0 · Python ≥ 3.12 (CI runs 3.12, 3.13 and 3.14) · consumed as a dependency, never deployed on its own. It also ships one artefact, the `pgcommon-migrate` CLI, as a container image (`ghcr.io/bcbp-solutions-fzc-llc/platform-pgcommon-py`).
 
 **Design:** one `src/pgcommon` package — public modules on top of a private `_internal/` layer, with the layer rules enforced by import-linter in CI. See [ARCHITECTURE.md](ARCHITECTURE.md) for design decisions, layer diagrams, and — importantly — how this port's `asyncio`/`contextvars` model differs from the Go original's `context.Context` model. This README is how to **use** it.
 
@@ -2014,8 +2014,8 @@ pgcommon itself is released to PyPI, and services adopt it by bumping their pin;
 Pin an exact version in production ([VERSIONING.md § Consume a release](VERSIONING.md#consume-a-release) has the pin styles):
 
 ```bash
-pip install "pgcommon==0.3.0"            # or "pgcommon[fastapi]==0.3.0" / "pgcommon[structlog]==0.3.0"
-uv add "pgcommon==0.3.0"
+pip install "pgcommon==0.3.1"            # or "pgcommon[fastapi]==0.3.1" / "pgcommon[structlog]==0.3.1"
+uv add "pgcommon==0.3.1"
 ```
 
 The files on PyPI are byte-identical to the GitHub Release's wheel and sdist: the release builds them once and uploads the same files to both.
@@ -2033,7 +2033,7 @@ Two-stage `Dockerfile`. The build stage (`python:3.14-slim` with uv `0.11.32`, b
 Needs [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) ≥ 2.4. A tag-triggered release is signed by `release.yml@refs/tags/<tag>`; a re-run dispatched from `main` by `release.yml@refs/heads/main`, which the regular expression below also accepts.
 
 ```bash
-TAG=v0.3.0   # the release to verify
+TAG=v0.3.1   # the release to verify
 REPO=BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon-py
 IDENTITY="^https://github\.com/${REPO}/\.github/workflows/release\.yml@refs/(tags/${TAG}|heads/main)$"
 
@@ -2182,7 +2182,7 @@ MIGRATIONS_DIR=/migrations
 
 | Consumer | pgcommon pin | Uses |
 |---|---|---|
-| `platform-eventcommon` (Python port of `platform-events`) | `>=0.2.0,<0.3.0` — moving to 0.3.0 needs a coordinated change ([Upgrading from 0.2.0](#upgrading-from-020)) | `Pool` and `run_in_tx` for its outbox, inbox and DLQ stores; `with_guc_set` so message handlers run under RLS; `MigrationDirtyError` for its own schema bookkeeping |
+| `platform-eventcommon` (Python port of `platform-events`) | `>=0.2.0,<0.4.0` on its `main` (its next release, 0.3.0, requires `>=0.3.0,<0.4.0`) | `Pool` and `run_in_tx` for its outbox, inbox and DLQ stores; `with_guc_set` so message handlers run under RLS; `MigrationDirtyError` for its own schema bookkeeping |
 | `platform-interop-tests` (Python probe) | — | Cross-language compatibility with the Go library (CI's `interop` job) |
 | FastAPI platform services | their own | Pool, RLS injection, transactions, error helpers, metrics, `pgcommon.integrations.fastapi` |
 

{pgcommon-0.3.0 → pgcommon-0.3.1}/VERSIONING.md

@@ -251,9 +251,7 @@ and push the tag.
      image's `provenance.slsa.json` and `sbom.cyclonedx.json` attached.
 
    The cross-language **interop** check gates `push`, exactly as in the Go repo: while it is
-   red, no image, no PyPI upload and no GitHub Release happen. (At the time of writing it fails
-   for `0.3.0` because `platform-eventcommon` pins `pgcommon<0.3.0`; relax that pin, or re-run
-   the release once it is relaxed.)
+   red, no image, no PyPI upload and no GitHub Release happen.
 
 8. **Notify consumers** (Slack/ADR) with upgrade notes if MINOR or MAJOR.
 
@@ -331,6 +329,7 @@ which `release_guard.py` checks).
 
 | pgcommon | Go `platform-pgcommon` parity | Python | asyncpg | Tested in CI |
 |----------|-------------------------------|--------|---------|--------------|
+| `0.3.1` (2026-10-15) | `v2.0.1` | `>=3.12` | `>=0.30,<0.32` | as `0.3.0` (patch: `Config` / `ResolvedConfig` repr masks the DSN password) |
 | `0.3.0` (2026-10-15) | `v2.0.1` | `>=3.12` | `>=0.30,<0.32` | Python 3.12, 3.13, 3.14 on the locked asyncpg (`0.31.0`), plus asyncpg `0.30.0` on 3.12 (`.github/workflows/validate-test.yml`: the `test` job on 3.12, the `python` matrix on 3.13 / 3.14, the `asyncpg-compat` job) |
 | `0.2.0` | not recorded (predates per-release Go tracking) | `>=3.12` | `>=0.29` | Python 3.12, 3.13, 3.14 |
 | `0.1.0` | not recorded (predates per-release Go tracking) | `>=3.12` | `>=0.29` | Python 3.12, 3.13, 3.14 |

{pgcommon-0.3.0 → pgcommon-0.3.1}/docs/lld/platform-lld-pgcommon-py.md

@@ -6,7 +6,7 @@
 |---|---|
 | Document type | Low-Level Design (LLD) |
 | Component | `platform-pgcommon-py`: the `pgcommon` Python package (asyncio PostgreSQL access library) and the `pgcommon-migrate` CLI |
-| Python package | `pgcommon` **0.3.0** (`pyproject.toml`; `requires-python >=3.12`; runtime dependencies `asyncpg>=0.30,<0.32`, `prometheus-client>=0.20`, `opentelemetry-api>=1.24`; extras `fastapi`, `structlog`) |
+| Python package | `pgcommon` **0.3.1** (`pyproject.toml`; `requires-python >=3.12`; runtime dependencies `asyncpg>=0.30,<0.32`, `prometheus-client>=0.20`, `opentelemetry-api>=1.24`; extras `fastapi`, `structlog`) |
 | Go sibling | `platform-pgcommon` **v2.0.1** (`github.com/BCBP-SOLUTIONS-FZC-LLC/platform-pgcommon/v2`). This port tracks it; the deliberate differences are listed in §18.5 and `ARCHITECTURE.md` § Divergences from Go |
 | Library status | **0.3.0 released 2026-10-15** (`CHANGELOG.md` `[0.3.0]`); before it 0.2.0 (2026-07-27). 0.3.0 contains breaking changes (§19.2). `platform-eventcommon` supports it (`pgcommon>=0.2.0,<0.4.0`; §16 A1) and the interop harness checks the pair at `platform-interop-tests` `9bd44ca`. Test suite: 2375 passed, 1 skipped, 100% line + branch coverage (§14) |
 | LLD revision | 1.1 |

{pgcommon-0.3.0 → pgcommon-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pgcommon"
-version = "0.3.0"
+version = "0.3.1"
 description = "Opinionated async PostgreSQL access layer for platform services — RLS tenancy, retries, and observability by default."
 readme = "README.md"
 requires-python = ">=3.12"

{pgcommon-0.3.0 → pgcommon-0.3.1}/src/pgcommon/config.py

@@ -16,6 +16,7 @@ so `?pool_max_conns=20` in the DSN is used unless `Config.max_conns` is set.
 from __future__ import annotations
 
 import configparser
+import dataclasses
 import os
 import re
 from collections.abc import Callable
@@ -31,6 +32,7 @@ from pgcommon._internal.dsn import (
     dsn_settings,
     has_bad_percent_escape,
     is_url_dsn,
+    mask_dsn,
     normalize_dsn,
     redact,
     resolve_connect_timeout,
@@ -117,6 +119,17 @@ def default_min_conns_for(pgbouncer_mode: bool, max_conns: int) -> int:
     return min(DEFAULT_MIN_CONNS, max_conns)
 
 
+def _repr_masking_dsn(obj: object) -> str:
+    """The dataclass repr with `dsn`'s password masked (`mask_dsn`): a `Config` reaches logs,
+    tracebacks and debuggers, and the generated repr printed the DSN as is."""
+    parts = []
+    for f in dataclasses.fields(obj):  # type: ignore[arg-type]
+        value = getattr(obj, f.name)
+        shown = repr(mask_dsn(value)) if f.name == "dsn" and isinstance(value, str) else repr(value)
+        parts.append(f"{f.name}={shown}")
+    return f"{type(obj).__name__}({', '.join(parts)})"
+
+
 @dataclass(slots=True)
 class Config:
     """Pool configuration. `dsn` is the only required field.
@@ -199,6 +212,9 @@ class Config:
     # callback made in the TxEndedInCallbackError, to be resolved by hand.
     prepared_xact_guard: bool = True
 
+    def __repr__(self) -> str:
+        return _repr_masking_dsn(self)
+
     @property
     def resolved_pool_name(self) -> str:
         """`pool_name`, or `"default"` when empty — the value used as the `pool` metric label."""
@@ -278,6 +294,9 @@ class ResolvedConfig:
     saturated_alive_window: timedelta = DEFAULT_SATURATED_ALIVE_WINDOW  # 0: always ping
     prepared_xact_guard: bool = True
 
+    def __repr__(self) -> str:
+        return _repr_masking_dsn(self)
+
 
 def _unset(d: timedelta | None) -> bool:
     return d is None or d == timedelta(0)

{pgcommon-0.3.0 → pgcommon-0.3.1}/tests/unit/test_config.py

@@ -451,3 +451,16 @@ def test_config_from_env_reads_pg_acquire_timeout(
     cfg, warnings = config_from_env()
     assert cfg.acquire_timeout == want
     assert [w.key for w in warnings] == (["PG_ACQUIRE_TIMEOUT"] if warns else [])
+
+
+def test_repr_masks_the_dsn_password() -> None:
+    # The generated dataclass repr printed the DSN as is, so a Config in a log line, a
+    # traceback or a debugger showed the password.
+    from pgcommon.config import Config, resolve
+
+    cfg = Config(dsn="postgres://app:s3cr%40t%2Fpw@db:5432/app?sslmode=require")
+    for shown in (repr(cfg), str(cfg), repr(resolve(cfg))):
+        assert "s3cr" not in shown
+        assert "postgres://app:" in shown
+    keyword = Config(dsn="host=db user=app password='s3cr@t pw' dbname=app")
+    assert "s3cr" not in repr(keyword)

{pgcommon-0.3.0 → pgcommon-0.3.1}/uv.lock

@@ -820,7 +820,7 @@ wheels = [
 
 [[package]]
 name = "pgcommon"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },