postgres-component 0.1.0__py3-none-any.whl

postgres_component/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from postgres_component.component import PostgresComponent
+from postgres_component.migrations import MigrationWiring, create_migration_engine
+
+__all__ = [
+    "MigrationWiring",
+    "PostgresComponent",
+    "create_migration_engine",
+]

postgres_component/_routes.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import APIRouter
+
+
+def build_health_router(get_status: Callable[[], dict[str, Any]]) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/health")
+    async def health() -> dict[str, Any]:
+        return get_status()
+
+    return router

postgres_component/component.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import APIRouter
+from python_components import Component
+from sqlalchemy import URL, make_url, text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from postgres_component._routes import build_health_router
+from postgres_component.migrations import MigrationWiring
+
+
+class PostgresComponent(Component):
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        user: str | None = None,
+        password: str | None = None,
+        database: str | None = None,
+        **engine_kwargs: Any,
+    ) -> None:
+        self.using([])
+        self._url = url or self._build_url(host, port, user, password, database)
+        self._engine_kwargs = engine_kwargs
+        self._engine: AsyncEngine | None = None
+        self._connected = False
+        self._last_error: str | None = None
+        self.session_factory: async_sessionmaker[AsyncSession] | None = None
+
+    @staticmethod
+    def _build_url(
+        host: str | None,
+        port: int | None,
+        user: str | None,
+        password: str | None,
+        database: str | None,
+    ) -> str:
+        if host is None or user is None or database is None:
+            raise TypeError(
+                "PostgresComponent requires either `url` or `host`/`user`/`database`"
+            )
+        return URL.create(
+            "postgresql+asyncpg",
+            username=user,
+            password=password,
+            host=host,
+            port=port or 5432,
+            database=database,
+        ).render_as_string(hide_password=False)
+
+    def _sanitize_error(self, message: str) -> str:
+        password = make_url(self._url).password
+        if password:
+            return message.replace(password, "***")
+        return message
+
+    async def start(self) -> None:
+        if self._engine is not None:
+            await self._engine.dispose()
+        engine = create_async_engine(self._url, **self._engine_kwargs)
+        try:
+            async with engine.connect() as conn:
+                await conn.execute(text("SELECT 1"))
+        except Exception as exc:
+            await engine.dispose()
+            self._last_error = self._sanitize_error(type(exc).__name__)
+            raise
+        self._engine = engine
+        self.session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        self._connected = True
+        self._last_error = None
+
+    async def shutdown(self) -> None:
+        if self._engine is not None:
+            await self._engine.dispose()
+        self._connected = False
+        self.session_factory = None
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        if self.session_factory is None:
+            raise RuntimeError("PostgresComponent.session() called before start()")
+        async with self.session_factory() as session:
+            try:
+                async with session.begin():
+                    yield session
+            except Exception as exc:
+                self._last_error = self._sanitize_error(type(exc).__name__)
+                raise
+
+    def routes(self) -> APIRouter:
+        return build_health_router(self.get_status)
+
+    def get_status(self) -> dict[str, Any]:
+        return {"connected": self._connected, "last_error": self._last_error}
+
+    def migration_wiring(self) -> MigrationWiring:
+        return MigrationWiring(url=self._url, engine_kwargs=dict(self._engine_kwargs))

postgres_component/migrations.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+
+@dataclass(frozen=True)
+class MigrationWiring:
+    url: str
+    engine_kwargs: dict[str, Any]
+
+
+def create_migration_engine(wiring: MigrationWiring) -> AsyncEngine:
+    return create_async_engine(wiring.url, **wiring.engine_kwargs)

postgres_component-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: postgres-component
+Version: 0.1.0
+Summary: Async Postgres connection-lifecycle component for python-components
+Project-URL: Homepage, https://github.com/fabriciooml/postgres-component
+Project-URL: Repository, https://github.com/fabriciooml/postgres-component
+Project-URL: Issues, https://github.com/fabriciooml/postgres-component/issues
+Project-URL: Changelog, https://github.com/fabriciooml/postgres-component/blob/main/CHANGELOG.md
+Author: Fabricio Lima
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,asyncpg,postgres,postgresql,python-components,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+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: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: asyncpg<1,>=0.29
+Requires-Dist: fastapi>=0.115
+Requires-Dist: python-components<0.5,>=0.4.0
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
+Description-Content-Type: text/markdown
+
+# postgres-component
+
+Async Postgres connection-lifecycle component for [python-components](https://github.com/lucassant95/python-components).
+
+## Install
+
+```bash
+uv add postgres-component
+```
+
+## Requirements
+
+- Python >= 3.11
+- A running Postgres server
+
+## Usage
+
+```python
+import asyncio
+
+from python_components import System
+from postgres_component import PostgresComponent
+
+database = PostgresComponent(url="postgresql+asyncpg://user:pass@localhost:5432/mydb")
+
+system = System({"database": database})
+
+async def main():
+    async with system:
+        async with database.session() as session:
+            await session.execute(...)  # commits on success, rolls back on exception
+
+asyncio.run(main())
+```
+
+`PostgresComponent` can also be built from individual kwargs instead of a URL:
+
+```python
+PostgresComponent(host="localhost", port=5432, user="user", password="pass", database="mydb")
+```
+
+`url` takes priority over the kwargs when both are given.
+
+### Health route
+
+```python
+from fastapi_component import create_app
+
+app = create_app(system)  # RouteProvider discovery adds GET /health automatically
+```
+
+### Migrations
+
+`PostgresComponent` never runs migrations itself. `migration_wiring()` hands your
+own Alembic `env.py` the same connection config so it doesn't have to be
+re-derived:
+
+```python
+# alembic/env.py
+from postgres_component import create_migration_engine
+
+engine = create_migration_engine(database.migration_wiring())
+# use `engine` with Alembic's async run_sync() pattern
+```
+
+## Semantics and caveats
+
+- **Fail-fast startup.** `start()` runs an explicit `SELECT 1` before considering itself connected — a dead database makes `start()` raise rather than "starting" successfully and failing later on first query.
+- **Managed Session is a unit of work.** `database.session()` begins a transaction, commits on clean exit, and rolls back on exception — one call is one unit of work. For manual control (long-lived reads, streaming), use the raw `database.session_factory` directly.
+- **Errors propagate raw.** SQLAlchemy exceptions (`OperationalError`, `IntegrityError`, etc.) are never wrapped; `get_status()["last_error"]` is updated as a string for introspection, but the original exception type always reaches the caller.
+- **No ORM, no migrations.** The component owns connection lifecycle only. Models and Alembic setup belong to the consuming app; `migration_wiring()` only removes the boilerplate of re-deriving connection config.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+```
+
+Integration tests spin up a real Postgres instance via [testcontainers](https://testcontainers.com/modules/postgres/). For local development against a persistent instance instead, run `docker compose up -d`.
+
+## License
+
+MIT

postgres_component-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+postgres_component/__init__.py,sha256=rxVd737FJ8JArAJF2f_sz1yy9fOuESwx4PBrMGcbr84,272
+postgres_component/_routes.py,sha256=Hw607vvqEICruIcQ-5wcNWMwKk16wdrOjdbh84loeZs,324
+postgres_component/component.py,sha256=dPFaFf8wARCr8zPzUt0qVdP4GVuSlXOKl8DFPpPzPXs,3672
+postgres_component/migrations.py,sha256=G149lyepn2ZLo7mVUzCaEyjTdZc7spFQrB7BM5rx3-s,396
+postgres_component/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+postgres_component-0.1.0.dist-info/METADATA,sha256=NJY4p4Gbn9UUFodkHxPOGp2WOqktqyeQeDhBXhhJOT0,3905
+postgres_component-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+postgres_component-0.1.0.dist-info/licenses/LICENSE,sha256=B-SYSQHSY79FyOS46ZHL43ywEGFd_VyMLDiBw-9cQYk,1070
+postgres_component-0.1.0.dist-info/RECORD,,

postgres_component-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

postgres_component-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabricio Lima
+
+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.