chrono-temporal 0.1.0__tar.gz

chrono_temporal-0.1.0/LICENSE

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

chrono_temporal-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include chrono_temporal *.py

chrono_temporal-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: chrono-temporal
+Version: 0.1.0
+Summary: Time-travel queries for any data entity. Query what your data looked like at any point in history.
+Author-email: Daniel <daniel@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Daniel7303/chrono-temporal-api-framework
+Project-URL: Repository, https://github.com/Daniel7303/chrono-temporal-api-framework
+Project-URL: Issues, https://github.com/Daniel7303/chrono-temporal-api-framework/issues
+Keywords: temporal,time-travel,database,audit,history,fastapi,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == "fastapi"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Dynamic: license-file

chrono_temporal-0.1.0/chrono_temporal/__init__.py

@@ -0,0 +1,22 @@
+"""
+Chrono Temporal — Time-travel queries for any data entity.
+
+Usage:
+    from chrono_temporal import TemporalService, TemporalRecord, TemporalRecordCreate
+"""
+
+from chrono_temporal.service import TemporalService
+from chrono_temporal.models import TemporalRecord
+from chrono_temporal.schemas import TemporalRecordCreate, TemporalRecordRead
+from chrono_temporal.base import ChronoBase, get_engine, get_session
+
+__version__ = "0.1.0"
+__all__ = [
+    "TemporalService",
+    "TemporalRecord",
+    "TemporalRecordCreate",
+    "TemporalRecordRead",
+    "ChronoBase",
+    "get_engine",
+    "get_session",
+]

chrono_temporal-0.1.0/chrono_temporal/base.py

@@ -0,0 +1,61 @@
+"""
+Database engine and session utilities for Chrono Temporal.
+"""
+from typing import AsyncGenerator
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    create_async_engine,
+    async_sessionmaker,
+    AsyncEngine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+
+class ChronoBase(DeclarativeBase):
+    """Base class for all Chrono Temporal models."""
+    pass
+
+
+def get_engine(database_url: str, echo: bool = False, **kwargs) -> AsyncEngine:
+    """
+    Create an async SQLAlchemy engine.
+
+    Args:
+        database_url: PostgreSQL connection string (must use asyncpg driver)
+                      e.g. postgresql+asyncpg://user:pass@localhost/dbname
+        echo: Log SQL statements (default False)
+        **kwargs: Additional engine options
+
+    Returns:
+        AsyncEngine instance
+    """
+    return create_async_engine(
+        database_url,
+        echo=echo,
+        pool_pre_ping=True,
+        **kwargs,
+    )
+
+
+def get_session(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    """
+    Create an async session factory.
+
+    Args:
+        engine: AsyncEngine instance from get_engine()
+
+    Returns:
+        async_sessionmaker configured for the given engine
+    """
+    return async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+
+
+async def create_tables(engine: AsyncEngine) -> None:
+    """Create all Chrono Temporal tables in the database."""
+    from chrono_temporal.models import TemporalRecord  # noqa
+    async with engine.begin() as conn:
+        await conn.run_sync(ChronoBase.metadata.create_all)

chrono_temporal-0.1.0/chrono_temporal/models.py

@@ -0,0 +1,34 @@
+from sqlalchemy import Column, Integer, String, DateTime, JSON, Text, func
+from chrono_temporal.base import ChronoBase
+
+
+class TemporalRecord(ChronoBase):
+    """
+    Core temporal record model.
+
+    Stores any entity with valid_from/valid_to time bounds,
+    enabling time-travel queries across the full history of any entity.
+
+    Columns:
+        entity_type: Category of entity e.g. "user", "order", "product"
+        entity_id:   Unique identifier within the entity type
+        valid_from:  When this version of the entity became true
+        valid_to:    When this version expired (NULL = still valid)
+        created_at:  When this record was inserted (transaction time)
+        data:        JSON payload — any fields you want to track
+        notes:       Optional human-readable description of the change
+    """
+    __tablename__ = "temporal_records"
+
+    id = Column(Integer, primary_key=True, index=True)
+    entity_type = Column(String(100), nullable=False, index=True)
+    entity_id = Column(String(255), nullable=False, index=True)
+
+    valid_from = Column(DateTime(timezone=True), nullable=False)
+    valid_to = Column(DateTime(timezone=True), nullable=True)
+
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    data = Column(JSON, nullable=False)
+    notes = Column(Text, nullable=True)

chrono_temporal-0.1.0/chrono_temporal/schemas.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Optional, Any
+
+
+class TemporalRecordCreate(BaseModel):
+    """Schema for creating a new temporal record."""
+    entity_type: str
+    entity_id: str
+    valid_from: datetime
+    valid_to: Optional[datetime] = None
+    data: dict[str, Any]
+    notes: Optional[str] = None
+
+
+class TemporalRecordRead(BaseModel):
+    """Schema for reading a temporal record."""
+    id: int
+    entity_type: str
+    entity_id: str
+    valid_from: datetime
+    valid_to: Optional[datetime] = None
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+    data: dict[str, Any]
+    notes: Optional[str] = None
+
+    class Config:
+        from_attributes = True
+
+
+class TemporalDiff(BaseModel):
+    """Result of a diff between two points in time."""
+    entity_type: str
+    entity_id: str
+    from_dt: str
+    to_dt: str
+    changed: dict[str, Any]
+    added: dict[str, Any]
+    removed: dict[str, Any]
+    unchanged: list[str]
+    has_changes: bool

chrono_temporal-0.1.0/chrono_temporal/service.py

@@ -0,0 +1,171 @@
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, and_, or_
+from datetime import datetime, timezone
+from typing import Optional
+from chrono_temporal.models import TemporalRecord
+from chrono_temporal.schemas import TemporalRecordCreate
+
+
+class TemporalService:
+    """
+    Core service for time-travel queries on any entity.
+
+    Usage:
+        engine = get_engine("postgresql+asyncpg://user:pass@localhost/db")
+        session_factory = get_session(engine)
+
+        async with session_factory() as session:
+            svc = TemporalService(session)
+            record = await svc.create(TemporalRecordCreate(...))
+    """
+
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def create(self, payload: TemporalRecordCreate) -> TemporalRecord:
+        """Create a new temporal record."""
+        record = TemporalRecord(**payload.model_dump())
+        self.db.add(record)
+        await self.db.flush()
+        await self.db.refresh(record)
+        return record
+
+    async def get_by_id(self, record_id: int) -> Optional[TemporalRecord]:
+        """Get a record by its primary key."""
+        result = await self.db.execute(
+            select(TemporalRecord).where(TemporalRecord.id == record_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_current(self, entity_type: str, entity_id: str) -> list[TemporalRecord]:
+        """Get records valid right now."""
+        now = datetime.now(timezone.utc)
+        result = await self.db.execute(
+            select(TemporalRecord).where(
+                and_(
+                    TemporalRecord.entity_type == entity_type,
+                    TemporalRecord.entity_id == entity_id,
+                    TemporalRecord.valid_from <= now,
+                    or_(
+                        TemporalRecord.valid_to.is_(None),
+                        TemporalRecord.valid_to > now,
+                    ),
+                )
+            ).order_by(TemporalRecord.valid_from.desc())
+        )
+        return result.scalars().all()
+
+    async def get_at_point_in_time(
+        self, entity_type: str, entity_id: str, as_of: datetime
+    ) -> list[TemporalRecord]:
+        """
+        Time-travel query — get entity state at a specific point in time.
+
+        Example:
+            records = await svc.get_at_point_in_time("user", "user_001", datetime(2024, 3, 1))
+        """
+        result = await self.db.execute(
+            select(TemporalRecord).where(
+                and_(
+                    TemporalRecord.entity_type == entity_type,
+                    TemporalRecord.entity_id == entity_id,
+                    TemporalRecord.valid_from <= as_of,
+                    or_(
+                        TemporalRecord.valid_to.is_(None),
+                        TemporalRecord.valid_to > as_of,
+                    ),
+                )
+            ).order_by(TemporalRecord.valid_from.desc())
+        )
+        return result.scalars().all()
+
+    async def get_history(self, entity_type: str, entity_id: str) -> list[TemporalRecord]:
+        """Get full timeline of changes for an entity."""
+        result = await self.db.execute(
+            select(TemporalRecord).where(
+                and_(
+                    TemporalRecord.entity_type == entity_type,
+                    TemporalRecord.entity_id == entity_id,
+                )
+            ).order_by(TemporalRecord.valid_from.asc())
+        )
+        return result.scalars().all()
+
+    async def get_diff(
+        self, entity_type: str, entity_id: str, from_dt: datetime, to_dt: datetime
+    ) -> dict:
+        """
+        Diff an entity's state between two points in time.
+
+        Returns what fields changed, were added, or were removed.
+
+        Example:
+            diff = await svc.get_diff("user", "user_001", datetime(2024, 1, 1), datetime(2025, 1, 1))
+            # diff["changed"] = {"plan": {"from": "free", "to": "pro"}}
+        """
+        async def get_snapshot(at: datetime):
+            result = await self.db.execute(
+                select(TemporalRecord).where(
+                    and_(
+                        TemporalRecord.entity_type == entity_type,
+                        TemporalRecord.entity_id == entity_id,
+                        TemporalRecord.valid_from <= at,
+                        or_(
+                            TemporalRecord.valid_to.is_(None),
+                            TemporalRecord.valid_to > at,
+                        ),
+                    )
+                ).order_by(TemporalRecord.valid_from.desc())
+            )
+            records = result.scalars().all()
+            return records[0].data if records else None
+
+        from_data = await get_snapshot(from_dt)
+        to_data = await get_snapshot(to_dt)
+
+        if from_data is None and to_data is None:
+            return {"error": "No records found for this entity at either point in time"}
+        if from_data is None:
+            return {"error": f"No records found at {from_dt}", "to": to_data}
+        if to_data is None:
+            return {"error": f"No records found at {to_dt}", "from": from_data}
+
+        all_keys = set(from_data.keys()) | set(to_data.keys())
+        changed, unchanged, added, removed = {}, [], {}, {}
+
+        for key in all_keys:
+            if key not in from_data:
+                added[key] = to_data[key]
+            elif key not in to_data:
+                removed[key] = from_data[key]
+            elif from_data[key] != to_data[key]:
+                changed[key] = {"from": from_data[key], "to": to_data[key]}
+            else:
+                unchanged.append(key)
+
+        return {
+            "entity_type": entity_type,
+            "entity_id": entity_id,
+            "from": str(from_dt),
+            "to": str(to_dt),
+            "changed": changed,
+            "added": added,
+            "removed": removed,
+            "unchanged": unchanged,
+            "has_changes": bool(changed or added or removed),
+        }
+
+    async def close_record(
+        self, record_id: int, closed_at: Optional[datetime] = None
+    ) -> Optional[TemporalRecord]:
+        """
+        Close a record by setting its valid_to date.
+        Use this when a new version of the entity becomes valid.
+        """
+        record = await self.get_by_id(record_id)
+        if not record:
+            return None
+        record.valid_to = closed_at or datetime.now(timezone.utc)
+        await self.db.flush()
+        await self.db.refresh(record)
+        return record

chrono_temporal-0.1.0/chrono_temporal.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: chrono-temporal
+Version: 0.1.0
+Summary: Time-travel queries for any data entity. Query what your data looked like at any point in history.
+Author-email: Daniel <daniel@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Daniel7303/chrono-temporal-api-framework
+Project-URL: Repository, https://github.com/Daniel7303/chrono-temporal-api-framework
+Project-URL: Issues, https://github.com/Daniel7303/chrono-temporal-api-framework/issues
+Keywords: temporal,time-travel,database,audit,history,fastapi,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == "fastapi"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Dynamic: license-file

chrono_temporal-0.1.0/chrono_temporal.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+pyproject.toml
+chrono_temporal/__init__.py
+chrono_temporal/base.py
+chrono_temporal/models.py
+chrono_temporal/schemas.py
+chrono_temporal/service.py
+chrono_temporal.egg-info/PKG-INFO
+chrono_temporal.egg-info/SOURCES.txt
+chrono_temporal.egg-info/dependency_links.txt
+chrono_temporal.egg-info/requires.txt
+chrono_temporal.egg-info/top_level.txt

chrono_temporal-0.1.0/chrono_temporal.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chrono_temporal-0.1.0/chrono_temporal.egg-info/requires.txt

@@ -0,0 +1,12 @@
+sqlalchemy>=2.0.0
+asyncpg>=0.29.0
+pydantic>=2.0.0
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+httpx>=0.27.0
+
+[fastapi]
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0

chrono_temporal-0.1.0/chrono_temporal.egg-info/top_level.txt

@@ -0,0 +1 @@
+chrono_temporal

chrono_temporal-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chrono-temporal"
+version = "0.1.0"
+description = "Time-travel queries for any data entity. Query what your data looked like at any point in history."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Daniel", email = "daniel@example.com" }
+]
+keywords = ["temporal", "time-travel", "database", "audit", "history", "fastapi", "sqlalchemy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: FastAPI",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "sqlalchemy>=2.0.0",
+    "asyncpg>=0.29.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.29.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Daniel7303/chrono-temporal-api-framework"
+Repository = "https://github.com/Daniel7303/chrono-temporal-api-framework"
+Issues = "https://github.com/Daniel7303/chrono-temporal-api-framework/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["chrono_temporal*"]

chrono_temporal-0.1.0/setup.cfg

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