voltwire-db-session 0.0.1__tar.gz

voltwire_db_session-0.0.1/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local tool state
+.omc/

voltwire_db_session-0.0.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: voltwire-db-session
+Version: 0.0.1
+Summary: A configurable DB session factory
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: pydantic-settings<3,>=2.3
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: sqlalchemy<3,>=2.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/db-session.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-db-session
+
+A configurable PostgreSQL session factory for Python applications. Wraps SQLAlchemy connection pool setup and pydantic-settings configuration into a single reusable package — install it, point it at your `.env`, and get sessions.
+
+## ORM-agnostic core
+
+`DatabaseSessionFactory`, `RODatabaseSessionFactory`, and `Session` (exported from `voltwire.db.session`) are `Protocol`s, not concrete classes. `TransactionContext` and `DatabaseAutoConfiguration` are written entirely against these interfaces and never import `sqlalchemy` — only `voltwire.db.session.backends.sqlalchemy` does. Today that's the only backend (`SqlAlchemyDatabaseSessionFactory`/`SqlAlchemyRODatabaseSessionFactory`, built via `build_session_factory`/`build_ro_session_factory`), but a future ORM backend only needs to satisfy the same `Protocol`s — no changes required to `TransactionContext`, `DatabaseAutoConfiguration`, or downstream packages like `voltwire-fastapi-db-txs`, which already depend only on the abstraction.
+
+## Installation
+
+```bash
+pip install voltwire-db-session
+# or with Poetry:
+poetry add voltwire-db-session
+```
+
+A PostgreSQL driver is **not** included — install whichever you prefer alongside it:
+
+```bash
+pip install psycopg2-binary   # most common
+pip install psycopg           # psycopg3
+```
+
+## Quickstart
+
+```python
+from voltwire.db.session import DatabaseSettings, build_session_factory
+
+settings = DatabaseSettings()           # reads DB_* vars from .env
+factory = build_session_factory(settings)
+
+session = factory.get_session()
+try:
+    result = session.execute(...)
+    session.commit()
+finally:
+    session.close()
+
+# On app shutdown
+factory.close()
+```
+
+## Configuration
+
+All settings are loaded from environment variables with a `DB_` prefix. By default the library reads from a `.env` file in the working directory.
+
+### Environment variables
+
+| Variable              | Default       | Description                                      |
+|-----------------------|---------------|--------------------------------------------------|
+| `DB_HOST`             | `localhost`   | Primary database host                            |
+| `DB_PORT`             | `5432`        | Database port                                    |
+| `DB_DATABASE`         | `postgres`    | Database name                                    |
+| `DB_USERNAME`         | `postgres`    | Database username                                |
+| `DB_PASSWORD`         | `postgres`    | Database password                                |
+| `DB_SCHEMA_NAME`      | `public`      | PostgreSQL schema (used for `search_path`)       |
+| `DB_DRIVER`           | `psycopg2`    | SQLAlchemy driver name                           |
+| `DB_RO_HOST`          | *(unset)*     | Read-only replica host; falls back to `DB_HOST`  |
+| `DB_POOL_SIZE`        | `10`          | Minimum connections in pool                      |
+| `DB_MAX_POOL_SIZE`    | `20`          | Maximum connections in pool                      |
+| `DB_POOL_TIMEOUT`     | `30`          | Seconds to wait for a connection from pool       |
+| `DB_POOL_RECYCLE`     | `299`         | Recycle connections after this many seconds      |
+| `DB_APPLICATION_NAME` | `app`         | Application name reported to PostgreSQL          |
+
+### Choosing your env file
+
+```python
+# Standard .env (default)
+settings = DatabaseSettings()
+
+# Custom env file — e.g. .env.local, .env.production
+settings = DatabaseSettings.from_env(".env.local")
+
+# No file — reads only from real environment variables
+settings = DatabaseSettings.from_env(None)
+
+# No file, with inline overrides
+settings = DatabaseSettings.from_env(None, host="db.internal", database="myapp")
+```
+
+### Using a different driver
+
+```python
+# psycopg3
+settings = DatabaseSettings.from_env(".env", driver="psycopg")
+
+# or via env var
+# DB_DRIVER=psycopg
+```
+
+The `driver` value is used as the SQLAlchemy URL scheme: `postgresql+{driver}://...`. The corresponding package must be installed in your environment.
+
+## Read-only replica
+
+```python
+from voltwire.db.session import DatabaseSettings, build_ro_session_factory
+
+settings = DatabaseSettings()       # set DB_RO_HOST to point at your replica
+ro_factory = build_ro_session_factory(settings)
+
+session = ro_factory.get_session()  # writes will be rejected by PostgreSQL
+```
+
+If `DB_RO_HOST` is not set, `RODatabaseSessionFactory` falls back to the primary host but still enforces read-only mode at the PostgreSQL level.
+
+## FastAPI example
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from voltwire.db.session import DatabaseSettings, build_session_factory
+
+settings = DatabaseSettings.from_env(".env.local")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.db = build_session_factory(settings)
+    yield
+    app.state.db.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/items")
+def list_items():
+    session = app.state.db.get_session()
+    try:
+        return session.execute(...).all()
+    finally:
+        session.close()
+```
+
+## Logging
+
+The library emits to the `voltwire.db.session` logger namespace using Python's standard `logging` module. To activate debug output:
+
+```python
+import logging
+logging.getLogger("voltwire.db.session").setLevel(logging.DEBUG)
+```
+
+### Routing to loguru
+
+If your app uses [loguru](https://github.com/Delgan/loguru), intercept stdlib logging once at startup:
+
+```python
+import logging
+from loguru import logger
+
+class InterceptHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        logger.opt(depth=6, exception=record.exc_info).log(
+            record.levelname, record.getMessage()
+        )
+
+logging.getLogger("voltwire.db.session").addHandler(InterceptHandler())
+```

voltwire_db_session-0.0.1/README.md

@@ -0,0 +1,158 @@
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/db-session.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-db-session
+
+A configurable PostgreSQL session factory for Python applications. Wraps SQLAlchemy connection pool setup and pydantic-settings configuration into a single reusable package — install it, point it at your `.env`, and get sessions.
+
+## ORM-agnostic core
+
+`DatabaseSessionFactory`, `RODatabaseSessionFactory`, and `Session` (exported from `voltwire.db.session`) are `Protocol`s, not concrete classes. `TransactionContext` and `DatabaseAutoConfiguration` are written entirely against these interfaces and never import `sqlalchemy` — only `voltwire.db.session.backends.sqlalchemy` does. Today that's the only backend (`SqlAlchemyDatabaseSessionFactory`/`SqlAlchemyRODatabaseSessionFactory`, built via `build_session_factory`/`build_ro_session_factory`), but a future ORM backend only needs to satisfy the same `Protocol`s — no changes required to `TransactionContext`, `DatabaseAutoConfiguration`, or downstream packages like `voltwire-fastapi-db-txs`, which already depend only on the abstraction.
+
+## Installation
+
+```bash
+pip install voltwire-db-session
+# or with Poetry:
+poetry add voltwire-db-session
+```
+
+A PostgreSQL driver is **not** included — install whichever you prefer alongside it:
+
+```bash
+pip install psycopg2-binary   # most common
+pip install psycopg           # psycopg3
+```
+
+## Quickstart
+
+```python
+from voltwire.db.session import DatabaseSettings, build_session_factory
+
+settings = DatabaseSettings()           # reads DB_* vars from .env
+factory = build_session_factory(settings)
+
+session = factory.get_session()
+try:
+    result = session.execute(...)
+    session.commit()
+finally:
+    session.close()
+
+# On app shutdown
+factory.close()
+```
+
+## Configuration
+
+All settings are loaded from environment variables with a `DB_` prefix. By default the library reads from a `.env` file in the working directory.
+
+### Environment variables
+
+| Variable              | Default       | Description                                      |
+|-----------------------|---------------|--------------------------------------------------|
+| `DB_HOST`             | `localhost`   | Primary database host                            |
+| `DB_PORT`             | `5432`        | Database port                                    |
+| `DB_DATABASE`         | `postgres`    | Database name                                    |
+| `DB_USERNAME`         | `postgres`    | Database username                                |
+| `DB_PASSWORD`         | `postgres`    | Database password                                |
+| `DB_SCHEMA_NAME`      | `public`      | PostgreSQL schema (used for `search_path`)       |
+| `DB_DRIVER`           | `psycopg2`    | SQLAlchemy driver name                           |
+| `DB_RO_HOST`          | *(unset)*     | Read-only replica host; falls back to `DB_HOST`  |
+| `DB_POOL_SIZE`        | `10`          | Minimum connections in pool                      |
+| `DB_MAX_POOL_SIZE`    | `20`          | Maximum connections in pool                      |
+| `DB_POOL_TIMEOUT`     | `30`          | Seconds to wait for a connection from pool       |
+| `DB_POOL_RECYCLE`     | `299`         | Recycle connections after this many seconds      |
+| `DB_APPLICATION_NAME` | `app`         | Application name reported to PostgreSQL          |
+
+### Choosing your env file
+
+```python
+# Standard .env (default)
+settings = DatabaseSettings()
+
+# Custom env file — e.g. .env.local, .env.production
+settings = DatabaseSettings.from_env(".env.local")
+
+# No file — reads only from real environment variables
+settings = DatabaseSettings.from_env(None)
+
+# No file, with inline overrides
+settings = DatabaseSettings.from_env(None, host="db.internal", database="myapp")
+```
+
+### Using a different driver
+
+```python
+# psycopg3
+settings = DatabaseSettings.from_env(".env", driver="psycopg")
+
+# or via env var
+# DB_DRIVER=psycopg
+```
+
+The `driver` value is used as the SQLAlchemy URL scheme: `postgresql+{driver}://...`. The corresponding package must be installed in your environment.
+
+## Read-only replica
+
+```python
+from voltwire.db.session import DatabaseSettings, build_ro_session_factory
+
+settings = DatabaseSettings()       # set DB_RO_HOST to point at your replica
+ro_factory = build_ro_session_factory(settings)
+
+session = ro_factory.get_session()  # writes will be rejected by PostgreSQL
+```
+
+If `DB_RO_HOST` is not set, `RODatabaseSessionFactory` falls back to the primary host but still enforces read-only mode at the PostgreSQL level.
+
+## FastAPI example
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from voltwire.db.session import DatabaseSettings, build_session_factory
+
+settings = DatabaseSettings.from_env(".env.local")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.db = build_session_factory(settings)
+    yield
+    app.state.db.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/items")
+def list_items():
+    session = app.state.db.get_session()
+    try:
+        return session.execute(...).all()
+    finally:
+        session.close()
+```
+
+## Logging
+
+The library emits to the `voltwire.db.session` logger namespace using Python's standard `logging` module. To activate debug output:
+
+```python
+import logging
+logging.getLogger("voltwire.db.session").setLevel(logging.DEBUG)
+```
+
+### Routing to loguru
+
+If your app uses [loguru](https://github.com/Delgan/loguru), intercept stdlib logging once at startup:
+
+```python
+import logging
+from loguru import logger
+
+class InterceptHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        logger.opt(depth=6, exception=record.exc_info).log(
+            record.levelname, record.getMessage()
+        )
+
+logging.getLogger("voltwire.db.session").addHandler(InterceptHandler())
+```

voltwire_db_session-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "voltwire-db-session"
+version = "0.0.1"
+description = "A configurable DB session factory"
+authors = [{name = "Hermann Steidel", email = "hsteidel.software@gmail.com"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "sqlalchemy>=2.0,<3",
+    "pydantic-settings>=2.3,<3",
+    "pydantic>=2.9,<3",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voltwire"]

voltwire_db_session-0.0.1/src/voltwire/db/session/__init__.py

@@ -0,0 +1,31 @@
+from voltwire.db.session.autoconfiguration import (
+    DatabaseAutoConfiguration,
+    DatabaseAutoConfigurationProperties,
+    auto_configure_database,
+)
+from voltwire.db.session.backends.sqlalchemy import (
+    SqlAlchemyDatabaseSessionFactory,
+    SqlAlchemyRODatabaseSessionFactory,
+    build_ro_session_factory,
+    build_session_factory,
+)
+from voltwire.db.session.interfaces import DatabaseSessionFactory, RODatabaseSessionFactory, Session
+from voltwire.db.session.settings import DatabaseSettings
+from voltwire.db.session.transaction import TransactionContext
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "DatabaseSessionFactory",
+    "RODatabaseSessionFactory",
+    "Session",
+    "SqlAlchemyDatabaseSessionFactory",
+    "SqlAlchemyRODatabaseSessionFactory",
+    "DatabaseSettings",
+    "TransactionContext",
+    "DatabaseAutoConfiguration",
+    "DatabaseAutoConfigurationProperties",
+    "build_session_factory",
+    "build_ro_session_factory",
+    "auto_configure_database",
+]

voltwire_db_session-0.0.1/src/voltwire/db/session/autoconfiguration.py

@@ -0,0 +1,91 @@
+"""
+Database Autoconfiguration
+
+Given ``DatabaseSettings`` (and optional properties for sane defaults), wires up the
+components a consuming app needs for DB session + transaction management, so app
+startup is a single call instead of hand-assembling each piece.
+
+Usage::
+
+    db = auto_configure_database(get_db_settings())
+
+    # if using with di
+    container.register(DatabaseSessionFactory, providers.Object(db.session_factory))
+    container.register(TransactionContext, providers.Object(db.transaction_context))
+
+    # if using fastapi tx middleware
+    app.add_middleware(
+        TransactionMiddleware,
+        transaction_context=db.transaction_context,
+        session_factory=db.session_factory,
+    )
+"""
+
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Generator
+
+from voltwire.db.session.backends.sqlalchemy import build_ro_session_factory, build_session_factory
+from voltwire.db.session.interfaces import DatabaseSessionFactory, RODatabaseSessionFactory, Session
+from voltwire.db.session.settings import DatabaseSettings
+from voltwire.db.session.transaction import TransactionContext
+
+
+@dataclass
+class DatabaseAutoConfigurationProperties:
+    """Optional knobs for ``auto_configure_database``."""
+
+    build_read_replica: bool = False
+    on_start_transaction: Callable[[DatabaseSessionFactory], None] | None = None
+    """
+    Called with the ``DatabaseSessionFactory`` before ``transaction_context()``/
+    ``transaction()`` opens a session for an explicit script/background-task
+    transaction. Not called for sessions opened by FastAPI middleware. Use this for
+    validation that should only run outside the request path — e.g. asserting the
+    factory points at a test database during a pytest run.
+    """
+
+
+@dataclass
+class DatabaseAutoConfiguration:
+    """Wired DB components for a process, given ``DatabaseSettings`` + properties."""
+
+    session_factory: DatabaseSessionFactory
+    transaction_context: TransactionContext
+    ro_session_factory: RODatabaseSessionFactory | None
+
+    @contextmanager
+    def transaction(self) -> Generator[Session, None, None]:
+        """Shorthand for ``self.transaction_context.transaction(self.session_factory)``."""
+        with self.transaction_context.transaction(self.session_factory) as session:
+            yield session
+
+    @contextmanager
+    def read_transaction(self) -> Generator[Session, None, None]:
+        """
+        Shorthand for ``self.transaction_context.read_transaction(self.ro_session_factory)``.
+
+        Raises ``RuntimeError`` if this configuration was built without a read replica
+        (``DatabaseAutoConfigurationProperties.build_read_replica=False``).
+        """
+        if self.ro_session_factory is None:
+            raise RuntimeError(
+                "read_transaction() requires a read replica — "
+                "build with DatabaseAutoConfigurationProperties(build_read_replica=True)"
+            )
+        with self.transaction_context.read_transaction(self.ro_session_factory) as session:
+            yield session
+
+
+def auto_configure_database(
+    settings: DatabaseSettings,
+    properties: DatabaseAutoConfigurationProperties | None = None,
+) -> DatabaseAutoConfiguration:
+    """Build a ``DatabaseAutoConfiguration`` from ``settings``, applying ``properties`` defaults."""
+    properties = properties or DatabaseAutoConfigurationProperties()
+    return DatabaseAutoConfiguration(
+        session_factory=build_session_factory(settings),
+        ro_session_factory=build_ro_session_factory(settings) if properties.build_read_replica else None,
+        transaction_context=TransactionContext(on_start_transaction=properties.on_start_transaction),
+    )