bitemporalorm 0.1.0__tar.gz

bitemporalorm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,146 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Lint — ruff (format + lint) + mypy
+  # ---------------------------------------------------------------------------
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dev dependencies
+        run: uv sync --group dev
+
+      - name: ruff format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: ruff lint
+        run: uv run ruff check src/ tests/
+
+      - name: mypy
+        run: uv run mypy src/bitemporalorm/
+
+  # ---------------------------------------------------------------------------
+  # Test
+  # ---------------------------------------------------------------------------
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  # ---------------------------------------------------------------------------
+  # Build docs — only on main push
+  # ---------------------------------------------------------------------------
+  docs:
+    name: Build & deploy docs
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install mkdocs-material
+
+      - run: mkdocs gh-deploy --force
+
+  # ---------------------------------------------------------------------------
+  # Build package — wheel + sdist
+  # ---------------------------------------------------------------------------
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ---------------------------------------------------------------------------
+  # Publish to PyPI — only on version tags (v*)
+  #
+  # Uses OIDC Trusted Publishing (no API token needed).
+  # One-time setup on PyPI:
+  #   1. Go to https://pypi.org/manage/account/publishing/
+  #   2. Add a new publisher:
+  #        Owner:      kalyansahoo
+  #        Repository: bitemporalorm
+  #        Workflow:   ci.yml
+  #        Environment: pypi
+  # ---------------------------------------------------------------------------
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bitemporalorm-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

bitemporalorm-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: bitemporalorm
+Version: 0.1.0
+Summary: Bitemporal data storage ORM for PostgreSQL with Polars DataFrames
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: connectorx>=0.3
+Requires-Dist: polars>=1.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlglot>=25.0
+Requires-Dist: typer>=0.12

bitemporalorm-0.1.0/docs/api/connection.md

@@ -0,0 +1,195 @@
+# Connection
+
+## `ConnectionConfig`
+
+```python
+from bitemporalorm import ConnectionConfig
+```
+
+Holds connection parameters for both the async write path (asyncpg) and the bulk read path (connectorx).
+
+```python
+@dataclass
+class ConnectionConfig:
+    host:     str = "localhost"
+    port:     int = 5432
+    database: str = "postgres"
+    user:     str = "postgres"
+    password: str = ""
+```
+
+### Derived properties
+
+| Property | Format | Used by |
+|---|---|---|
+| `asyncpg_dsn` | `postgresql://user:pass@host:port/db` | `AsyncPool` |
+| `connectorx_uri` | `postgresql://user:pass@host:port/db` | `DBExecutor.read_as_dataframe()` |
+| `psycopg2_dsn` | `host=... port=... dbname=... user=... password=...` | CLI / sync helpers |
+
+```python
+config = ConnectionConfig(
+    host="localhost",
+    port=5432,
+    database="mydb",
+    user="postgres",
+    password="secret",
+)
+
+print(config.asyncpg_dsn)
+# postgresql://postgres:secret@localhost:5432/mydb
+```
+
+---
+
+## `AsyncPool`
+
+```python
+from bitemporalorm.connection.pool import AsyncPool
+```
+
+Thin wrapper around an asyncpg connection pool.
+
+### Constructor
+
+```python
+AsyncPool(config: ConnectionConfig)
+```
+
+### Methods
+
+| Method | Description |
+|---|---|
+| `await connect()` | Open the connection pool |
+| `await disconnect()` | Close the connection pool |
+| `await execute(sql, *args)` | Execute a statement, discard result |
+| `await fetch(sql, *args)` | Fetch all rows as a list of `asyncpg.Record` |
+| `await fetchrow(sql, *args)` | Fetch one row (or `None`) |
+| `await fetchval(sql, *args)` | Fetch the first column of the first row |
+| `await execute_ddl(sql)` | Execute a DDL statement (no parameters) |
+
+```python
+pool = AsyncPool(config)
+await pool.connect()
+
+rows = await pool.fetch("SELECT id FROM business_entity WHERE id = $1", 42)
+await pool.execute("DELETE FROM business_entity WHERE id = $1", 42)
+
+await pool.disconnect()
+```
+
+### Context manager
+
+```python
+async with AsyncPool(config) as pool:
+    rows = await pool.fetch("SELECT id FROM business_entity")
+```
+
+---
+
+## `DBExecutor`
+
+```python
+from bitemporalorm import DBExecutor
+```
+
+High-level executor that handles both writes (asyncpg) and bulk reads (connectorx). All `Entity.save()` and `Entity.filter()` calls are delegated to a `DBExecutor`.
+
+### Constructor
+
+```python
+DBExecutor(pool: AsyncPool)
+```
+
+### Methods
+
+#### `save_entity(entity_cls, df)`
+
+```python
+async def save_entity(
+    entity_cls: type[Entity],
+    df: pl.DataFrame,
+) -> pl.DataFrame
+```
+
+Persists a DataFrame of bitemporal events. Delegates to the internal save pipeline:
+
+1. Allocate `entity_id` for rows without one.
+2. Insert audit rows for each field column present in `df`.
+3. Run the split-and-reinsert materialized update for each field.
+
+Returns `df` with `entity_id` populated.
+
+#### `read_as_dataframe(sql)`
+
+```python
+def read_as_dataframe(sql: str) -> pl.DataFrame
+```
+
+Executes `sql` via connectorx and returns a Polars DataFrame. Used by `Entity.filter()`.
+
+!!! note
+    This is a synchronous method. connectorx manages its own thread pool internally.
+
+---
+
+## Global executor registry
+
+Executors are registered globally by alias so that `Entity.save()` and `Entity.filter()` can resolve the correct executor without being passed one explicitly.
+
+```python
+from bitemporalorm import register_executor, get_executor
+```
+
+### `register_executor(executor, alias="default")`
+
+```python
+def register_executor(executor: DBExecutor, alias: str = "default") -> None
+```
+
+Register `executor` under `alias`. The alias `"default"` is used unless overridden.
+
+### `get_executor(alias="default")`
+
+```python
+def get_executor(alias: str = "default") -> DBExecutor
+```
+
+Retrieve a registered executor. Raises `KeyError` if `alias` is not registered.
+
+---
+
+## Typical setup
+
+```python
+import asyncio
+from bitemporalorm import ConnectionConfig, DBExecutor, register_executor
+from bitemporalorm.connection.pool import AsyncPool
+
+async def startup():
+    config = ConnectionConfig(
+        host="localhost",
+        database="mydb",
+        user="postgres",
+        password="secret",
+    )
+    pool = AsyncPool(config)
+    await pool.connect()
+
+    executor = DBExecutor(pool)
+    register_executor(executor)          # registered as "default"
+
+async def shutdown():
+    get_executor().pool.disconnect()
+```
+
+After `register_executor()`, all `Entity.save()` and `Entity.filter()` calls will use the default executor automatically.
+
+### Multiple databases
+
+```python
+register_executor(executor_a, alias="primary")
+register_executor(executor_b, alias="replica")
+
+# Entity.filter() uses "default" unless you override it at the Entity level
+register_executor(executor_a)   # also register as default
+```

bitemporalorm-0.1.0/docs/api/entity.md

@@ -0,0 +1,156 @@
+# Entity
+
+## class `Entity`
+
+Base class for all bitemporal entities. Subclass it and declare fields as type annotations.
+
+```python
+from bitemporalorm import Entity, ManyToOneField, OneToOneField, OneToManyField
+
+class BusinessEntity(Entity):
+    city:         ManyToOneField[str]
+    phone_number: OneToOneField[str]
+    director:     OneToManyField[str]
+```
+
+---
+
+### `Entity.save()` — persist events
+
+```python
+@classmethod
+async def save(cls, df: pl.DataFrame) -> pl.DataFrame
+```
+
+Persists a DataFrame of bitemporal events. For each row, inserts into the audit table and updates the materialized table. Returns the DataFrame with `entity_id` populated.
+
+**Required columns**
+
+| Column | Type | Description |
+|---|---|---|
+| `as_of_start` | `datetime` | Start of the valid-time range |
+
+**Optional columns**
+
+| Column | Type | Default | Description |
+|---|---|---|---|
+| `as_of_end` | `datetime` | `infinity` | End of the valid-time range (exclusive) |
+| `entity_id` | `int` | `None` | Entity to update. Absent = insert new entity. |
+| `parent_entity_id` | `int` | — | For child entities: ID of the parent entity instance |
+| `<field_name>` | varies | — | Any declared field. Only fields present in df are saved. |
+
+**Returns** — `pl.DataFrame` with `entity_id` populated for all rows.
+
+```python
+# Insert (entity_id absent → auto-assigned)
+df = await BusinessEntity.save(pl.DataFrame({
+    "as_of_start":  [datetime(2020, 1, 1, tzinfo=timezone.utc)],
+    "city":         ["London"],
+    "phone_number": ["+44123456789"],
+    "director":     ["Alice Smith"],
+}))
+entity_id = df["entity_id"][0]
+
+# Update (provide entity_id)
+await BusinessEntity.save(pl.DataFrame({
+    "entity_id":   [entity_id],
+    "as_of_start": [datetime(2023, 1, 1, tzinfo=timezone.utc)],
+    "city":        ["Manchester"],
+}))
+
+# Bounded range (e.g. temporary change)
+await BusinessEntity.save(pl.DataFrame({
+    "entity_id":   [entity_id],
+    "as_of_start": [datetime(2021, 1, 1, tzinfo=timezone.utc)],
+    "as_of_end":   [datetime(2022, 1, 1, tzinfo=timezone.utc)],
+    "city":        ["Bristol"],
+}))
+```
+
+---
+
+### `Entity.filter()` — point-in-time query
+
+```python
+@classmethod
+async def filter(cls, as_of: datetime, *exprs: pl.Expr) -> pl.DataFrame
+```
+
+Returns a Polars DataFrame with the state of all entities at `as_of`.
+
+**Parameters**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `as_of` | `datetime` | Point-in-time to query. Required. |
+| `*exprs` | `pl.Expr` | Additional Polars filter expressions (AND-combined) |
+
+**Returns** — `pl.DataFrame` with columns `entity_id` + one column per declared field (own + inherited for child entities).
+
+For `OneToManyField`: one row per `(entity, value)` combination (exploded).
+
+```python
+# All entities as of a date
+df = await BusinessEntity.filter(
+    as_of=datetime(2022, 6, 1, tzinfo=timezone.utc),
+)
+
+# With Polars expression filters
+df = await BusinessEntity.filter(
+    as_of=datetime(2022, 6, 1, tzinfo=timezone.utc),
+    pl.col("city") == "London",
+    pl.col("director").is_not_null(),
+)
+```
+
+---
+
+## class `EntityOptions`
+
+Attached to every `Entity` subclass as `cls._meta`. Do not instantiate directly.
+
+### Attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `table_name` | `str` | Database table name |
+| `fields` | `dict[str, FieldSpec]` | Own fields only (not inherited) |
+| `parent_entity` | `type[Entity] \| None` | Direct parent entity class |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `all_fields()` | `dict[str, FieldSpec]` | Own fields + all inherited fields (flattened) |
+| `hierarchy()` | `list[type[Entity]]` | `[parent, grandparent, ...]` walking up the chain |
+
+```python
+RegionalOffice._meta.table_name    # "regional_office"
+RegionalOffice._meta.fields        # {"branch_code": ..., "head_count": ...}
+RegionalOffice._meta.all_fields()  # {"city": ..., "phone_number": ..., "director": ...,
+                                   #  "branch_code": ..., "head_count": ...}
+RegionalOffice._meta.parent_entity # BusinessEntity
+RegionalOffice._meta.hierarchy()   # [BusinessEntity]
+```
+
+---
+
+## class `EntityRegistry`
+
+Global singleton registry. Available as `bitemporalorm.registry`.
+
+| Method | Description |
+|---|---|
+| `register(entity)` | Register a class (called automatically by `EntityMeta`) |
+| `get(name: str)` | Look up by class name. Raises `LookupError` if not found. |
+| `all()` | Return all registered classes |
+| `clear()` | Remove all registrations (useful in tests) |
+| `snapshot()` | Return a copy of the current registry dict |
+| `restore(snap)` | Restore registry from a snapshot |
+
+```python
+from bitemporalorm import registry
+
+registry.get("BusinessEntity")   # → BusinessEntity class
+registry.all()                   # → [BusinessEntity, RegionalOffice, ...]
+```

bitemporalorm-0.1.0/docs/api/fields.md

@@ -0,0 +1,128 @@
+# Fields
+
+## `ManyToOneField`
+
+```python
+from bitemporalorm import ManyToOneField
+```
+
+Many entities can share the same value; each entity has one value at any given time.
+
+```python
+class BusinessEntity(Entity):
+    city: ManyToOneField[str]
+    score: ManyToOneField[int]
+```
+
+- Exclusion constraint: **enforced** — no two rows for the same entity with overlapping `as_of`
+- Relationship type: `"many_to_one"`
+
+---
+
+## `OneToOneField`
+
+```python
+from bitemporalorm import OneToOneField
+```
+
+Exactly one value per entity at any given time; semantically stricter than `ManyToOneField`.
+
+```python
+class BusinessEntity(Entity):
+    phone_number: OneToOneField[str]
+    registration_number: OneToOneField[str]
+```
+
+- Exclusion constraint: **enforced**
+- Relationship type: `"one_to_one"`
+
+---
+
+## `OneToManyField`
+
+```python
+from bitemporalorm import OneToManyField
+```
+
+Multiple values per entity at the same time. Query results are exploded (one row per value).
+
+```python
+class BusinessEntity(Entity):
+    director: OneToManyField[str]
+    tag: OneToManyField[str]
+```
+
+- Exclusion constraint: **not enforced** — multiple simultaneous values allowed
+- Relationship type: `"one_to_many"`
+
+---
+
+## Annotation syntax
+
+### Class-getitem (recommended)
+
+```python
+city: ManyToOneField[str]            # primitive
+country: ManyToOneField["Country"]   # entity reference (string forward ref)
+```
+
+### Direct instantiation
+
+```python
+city: ManyToOneField = ManyToOneField(str)
+```
+
+---
+
+## Type argument mapping
+
+| Python type | SQL column type |
+|---|---|
+| `str` | `TEXT` |
+| `int` | `BIGINT` |
+| `float` | `DOUBLE PRECISION` |
+| `datetime.datetime` | `TIMESTAMPTZ` |
+| `"EntityName"` (string) | `BIGINT` (FK to entity table) |
+| `EntityClass` (direct ref) | `BIGINT` (FK to entity table) |
+
+---
+
+## `FieldType` enum
+
+```python
+from bitemporalorm import FieldType
+```
+
+| Member | SQL type |
+|---|---|
+| `FieldType.TEXT` | `TEXT` |
+| `FieldType.INT` | `BIGINT` |
+| `FieldType.FLOAT` | `DOUBLE PRECISION` |
+| `FieldType.DATETIME` | `TIMESTAMPTZ` |
+| `FieldType.ENTITY_REF` | `BIGINT` |
+
+---
+
+## class `FieldSpec`
+
+Resolved field metadata attached to `EntityOptions.fields`. Read-only.
+
+```python
+fspec = BusinessEntity._meta.fields["city"]
+
+fspec.name          # "city"
+fspec.relationship  # RelationshipType.MANY_TO_ONE
+fspec.sql_type      # FieldType.TEXT
+fspec.sql_type_str  # "TEXT"
+fspec.entity_ref    # None  (or "Country" for entity-reference fields)
+```
+
+### Attributes
+
+| Attribute | Type | Description |
+|---|---|---|
+| `name` | `str` | Field name (matches annotation key) |
+| `relationship` | `RelationshipType` | `MANY_TO_ONE`, `ONE_TO_ONE`, or `ONE_TO_MANY` |
+| `sql_type` | `FieldType` | SQL column type enum |
+| `sql_type_str` | `str` | SQL type string (e.g. `"TEXT"`) |
+| `entity_ref` | `str \| None` | Referenced entity class name, or `None` |