sapling-db 0.1.0__tar.gz

sapling_db-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: sapling-db
+Version: 0.1.0
+Summary: Add your description here
+Author: Justin Chapman
+Author-email: Justin Chapman <commonmodestudio@gmail.com>
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# sapling
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PyPI](https://img.shields.io/pypi/v/sapling-db)](https://pypi.org/project/sapling-db/)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://python.org)
+[![CI](https://github.com/thejchap/sapling/actions/workflows/ci.yml/badge.svg)](https://github.com/thejchap/sapling/actions/workflows/ci.yml)
+
+## installation
+
+```
+pip install sapling-db
+```
+
+## overview
+
+simple, zero-setup persistence for pydantic models
+
+```python
+from pydantic import BaseModel
+from sapling import Database
+
+
+class User(BaseModel):
+    name: str
+    email: str
+
+
+db = Database()
+
+with db.transaction() as txn:
+    user = User(name="alice", email="alice@example.com")
+    doc = txn.put(User, "123", user)
+    txn.fetch(User, "123")
+```
+
+**features:**
+
+- **fully typed** - complete type safety with ide autocomplete and type checking
+- **zero setup** - works out of the box with no configuration
+- **pydantic native** - designed specifically for pydantic models
+- **fastapi ready** - seamless dependency injection for request-scoped transactions
+- **sqlite backed** - solid, battle-tested storage

sapling_db-0.1.0/README.md

@@ -0,0 +1,43 @@
+# sapling
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PyPI](https://img.shields.io/pypi/v/sapling-db)](https://pypi.org/project/sapling-db/)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://python.org)
+[![CI](https://github.com/thejchap/sapling/actions/workflows/ci.yml/badge.svg)](https://github.com/thejchap/sapling/actions/workflows/ci.yml)
+
+## installation
+
+```
+pip install sapling-db
+```
+
+## overview
+
+simple, zero-setup persistence for pydantic models
+
+```python
+from pydantic import BaseModel
+from sapling import Database
+
+
+class User(BaseModel):
+    name: str
+    email: str
+
+
+db = Database()
+
+with db.transaction() as txn:
+    user = User(name="alice", email="alice@example.com")
+    doc = txn.put(User, "123", user)
+    txn.fetch(User, "123")
+```
+
+**features:**
+
+- **fully typed** - complete type safety with ide autocomplete and type checking
+- **zero setup** - works out of the box with no configuration
+- **pydantic native** - designed specifically for pydantic models
+- **fastapi ready** - seamless dependency injection for request-scoped transactions
+- **sqlite backed** - solid, battle-tested storage

sapling_db-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "sapling-db"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Justin Chapman", email = "commonmodestudio@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = ["pydantic>=2.12.5", "pydantic-settings>=2.12.0"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "sapling"
+
+[dependency-groups]
+dev = [
+  "fastapi>=0.125.0",
+  "httpx>=0.28.1",
+  "pre-commit>=4.0.1",
+  "tryke @ git+https://github.com/thejchap/tryke",
+  "ruff>=0.13.0",
+  "ty>=0.0.4",
+]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN201", "PLR2004"]
+"src/sapling/backends/sqlite.py" = ["S608"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # may cause issues with formatter
+  "COM812",
+  # incompatible with D213
+  "D212",
+  # incompatible with D211
+  "D203",
+  # missing docstring
+  "D100",
+  "D101",
+  "D102",
+  "D103",
+  "D104",
+  "D107",
+  # TODOs
+  "FIX002",
+  "FIX003",
+  "TD003",
+  "ERA001",
+  # too many arguments
+  "PLR0913",
+  # causes error
+  "ISC001",
+]
+fixable = ["ALL"]
+
+[tool.ruff.format]
+docstring-code-format = true

sapling_db-0.1.0/src/sapling/__init__.py

@@ -0,0 +1,16 @@
+"""sapling - simple persistence for pydantic models."""
+
+from .backends.memory import MemoryBackend
+from .backends.sqlite import SQLiteBackend
+from .database import Database
+from .document import Document
+from .settings import SaplingSettings, get_sapling_settings
+
+__all__ = [
+    "Database",
+    "Document",
+    "MemoryBackend",
+    "SQLiteBackend",
+    "SaplingSettings",
+    "get_sapling_settings",
+]

sapling_db-0.1.0/src/sapling/backends/__init__.py

@@ -0,0 +1,5 @@
+from .base import Backend
+from .memory import MemoryBackend
+from .sqlite import SQLiteBackend
+
+__all__ = ["Backend", "MemoryBackend", "SQLiteBackend"]

sapling_db-0.1.0/src/sapling/backends/base.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from contextlib import AbstractContextManager
+
+    from pydantic import BaseModel
+
+    from sapling.database import Document
+
+
+class Backend(ABC):
+    """abstract base class for storage backends."""
+
+    @abstractmethod
+    def get[T: BaseModel](
+        self, model_class: type[T], model_id: str
+    ) -> Document[T] | None: ...
+
+    @abstractmethod
+    def put[T: BaseModel](
+        self, model_class: type[T], model_id: str, model: T
+    ) -> Document[T]: ...
+
+    @abstractmethod
+    def fetch[T: BaseModel](
+        self, model_class: type[T], model_id: str
+    ) -> Document[T]: ...
+
+    @abstractmethod
+    def delete(self, model_class: type[BaseModel], model_id: str) -> None: ...
+
+    @abstractmethod
+    def all[T: BaseModel](self, model_class: type[T]) -> list[Document[T]]: ...
+
+    @abstractmethod
+    def get_many[T: BaseModel](
+        self, model_class: type[T], model_ids: list[str]
+    ) -> list[Document[T] | None]: ...
+
+    @abstractmethod
+    def delete_many(
+        self, model_class: type[BaseModel], model_ids: list[str]
+    ) -> None: ...
+
+    @abstractmethod
+    def put_many[T: BaseModel](
+        self, model_class: type[T], models: list[tuple[str, T]]
+    ) -> list[Document[T]]: ...
+
+    @abstractmethod
+    def initialize(self) -> None: ...
+
+    @abstractmethod
+    def transaction(self) -> AbstractContextManager[Self]: ...

sapling_db-0.1.0/src/sapling/backends/memory.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Self
+
+from sapling.backends.base import Backend
+from sapling.document import Document
+from sapling.errors import NotFoundError
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from pydantic import BaseModel
+
+
+class MemoryBackend(Backend):
+    """
+    in-memory storage backend.
+
+    stores documents in python dict, no persistence.
+    useful for testing and development.
+
+    Example:
+        ```python
+        backend = MemoryBackend()
+        db = Database(backend=backend)
+        ```
+
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[tuple[str, str], dict] = {}
+
+    def initialize(self) -> None:
+        pass
+
+    @contextmanager
+    def transaction(self) -> Generator[Self]:
+        yield self
+
+    def get[T: BaseModel](
+        self, model_class: type[T], model_id: str
+    ) -> Document[T] | None:
+        key = (model_class.__name__, model_id)
+        if data := self._store.get(key):
+            model = model_class.model_validate(data["model"])
+            return Document(
+                model=model,
+                model_id=data["model_id"],
+                model_class=data["model_class"],
+            )
+        return None
+
+    def put[T: BaseModel](
+        self, model_class: type[T], model_id: str, model: T
+    ) -> Document[T]:
+        key = (model_class.__name__, model_id)
+        data = {
+            "model_class": model_class.__name__,
+            "model_id": model_id,
+            "model": model.model_dump(),
+        }
+        self._store[key] = data
+        return Document(
+            model=model,
+            model_id=model_id,
+            model_class=model_class.__name__,
+        )
+
+    def fetch[T: BaseModel](self, model_class: type[T], model_id: str) -> Document[T]:
+        if document := self.get(model_class=model_class, model_id=model_id):
+            return document
+        raise NotFoundError
+
+    def delete(self, model_class: type[BaseModel], model_id: str) -> None:
+        key = (model_class.__name__, model_id)
+        self._store.pop(key, None)
+
+    def all[T: BaseModel](self, model_class: type[T]) -> list[Document[T]]:
+        results = []
+        for (stored_class, _), data in self._store.items():
+            if stored_class == model_class.__name__:
+                model = model_class.model_validate(data["model"])
+                results.append(
+                    Document(
+                        model=model,
+                        model_id=data["model_id"],
+                        model_class=data["model_class"],
+                    )
+                )
+        return results
+
+    def get_many[T: BaseModel](
+        self, model_class: type[T], model_ids: list[str]
+    ) -> list[Document[T] | None]:
+        return [self.get(model_class, model_id) for model_id in model_ids]
+
+    def delete_many(self, model_class: type[BaseModel], model_ids: list[str]) -> None:
+        for model_id in model_ids:
+            self.delete(model_class, model_id)
+
+    def put_many[T: BaseModel](
+        self, model_class: type[T], models: list[tuple[str, T]]
+    ) -> list[Document[T]]:
+        return [self.put(model_class, model_id, model) for model_id, model in models]

sapling_db-0.1.0/src/sapling/backends/sqlite.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self, override
+
+from pydantic import BaseModel
+
+from sapling.backends.base import Backend
+from sapling.document import Document
+from sapling.errors import NotFoundError
+from sapling.settings import IsolationLevel, SaplingSettings, get_sapling_settings
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+_CONNECTION_NOT_INITIALIZED = "Connection not initialized"
+
+
+class SQLiteBackend(Backend):
+    """
+    sqlite-based storage backend.
+
+    provides persistent storage using sqlite database.
+    supports both file-based and in-memory modes.
+
+    Args:
+        settings: sapling settings instance. if not provided, uses global settings
+            from environment variables.
+
+    Example:
+        ```python
+        # use global settings from environment
+        backend = SQLiteBackend()
+
+        # use custom settings
+        from sapling import SaplingSettings
+
+        settings = SaplingSettings(
+            sqlite_path="/path/to/db.sqlite",
+            sqlite_timeout=10.0,
+        )
+        backend = SQLiteBackend(settings=settings)
+        ```
+
+    """
+
+    def __init__(self, settings: SaplingSettings | None = None) -> None:
+        settings = settings if settings is not None else get_sapling_settings()
+        self.path: str = settings.sqlite_path
+        self.timeout: float = settings.sqlite_timeout
+        self.detect_types: int = settings.sqlite_detect_types
+        self.isolation_level: IsolationLevel = settings.sqlite_isolation_level
+        self.check_same_thread: bool = settings.sqlite_check_same_thread
+        self.cached_statements: int = settings.sqlite_cached_statements
+        self.uri: bool = settings.sqlite_uri
+        self._conn: sqlite3.Connection | None = None
+        self._initialized: bool = False
+        self._init_lock: threading.Lock = threading.Lock()
+
+    @override
+    def initialize(self) -> None:
+        with self._init_lock:
+            if self._initialized:
+                return
+            if self.path != ":memory:":
+                db_dir = Path(self.path).parent
+                db_dir.mkdir(parents=True, exist_ok=True)
+            self._conn = sqlite3.connect(
+                self.path,
+                timeout=self.timeout,
+                detect_types=self.detect_types,
+                isolation_level=self.isolation_level,
+                check_same_thread=self.check_same_thread,
+                cached_statements=self.cached_statements,
+                uri=self.uri,
+            )
+            self._init_schema()
+            self._initialized = True
+
+    @contextmanager
+    def transaction(self) -> Generator[Self]:
+        if not self._conn:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        with self._conn:
+            yield self
+
+    def _init_schema(self) -> None:
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        self._conn.set_trace_callback(LOGGER.debug)
+        with self._conn:
+            self._conn.execute(
+                """\
+CREATE TABLE IF NOT EXISTS document (
+    model_class VARCHAR,
+    model_id CHARACTER(26),
+    model BLOB,
+    PRIMARY KEY (model_class, model_id)
+);
+""".strip()
+            )
+
+    def _row_to_document[T: BaseModel](
+        self, model_class: type[T], cursor: sqlite3.Cursor, row: tuple[Any]
+    ) -> Document[T]:
+        fields = [column[0] for column in cursor.description]
+        raw = dict(zip(fields, row, strict=False))
+        model = model_class.model_validate_json(raw["model"])
+        return Document(
+            model=model,
+            model_id=raw["model_id"],
+            model_class=raw["model_class"],
+        )
+
+    def get[T: BaseModel](
+        self, model_class: type[T], model_id: str
+    ) -> Document[T] | None:
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        cursor = self._conn.execute(
+            """\
+SELECT
+    model_class,
+    model_id,
+    model
+FROM document
+WHERE
+    model_class = :model_class
+    AND model_id = :model_id
+LIMIT 1
+;
+            """.strip(),
+            {"model_class": model_class.__name__, "model_id": str(model_id)},
+        )
+        row = cursor.fetchone()
+        if row:
+            return self._row_to_document(model_class, cursor, row)
+        return None
+
+    def put[T: BaseModel](
+        self, model_class: type[T], model_id: str, model: T
+    ) -> Document[T]:
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        cursor = self._conn.execute(
+            """\
+INSERT OR REPLACE INTO document VALUES (
+    :model_class,
+    :model_id,
+    :model
+) RETURNING
+    model_class,
+    model_id,
+    model
+;
+            """.strip(),
+            {
+                "model_class": model_class.__name__,
+                "model_id": model_id,
+                "model": model.model_dump_json(),
+            },
+        )
+        row = cursor.fetchone()
+        return self._row_to_document(model_class, cursor, row)
+
+    def fetch[T: BaseModel](self, model_class: type[T], model_id: str) -> Document[T]:
+        if document := self.get(model_class=model_class, model_id=model_id):
+            return document
+        raise NotFoundError
+
+    def delete(self, model_class: type[BaseModel], model_id: str) -> None:
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        self._conn.execute(
+            """\
+DELETE
+FROM document
+WHERE
+    model_class = :model_class
+    AND model_id = :model_id
+;
+            """.strip(),
+            {"model_class": model_class.__name__, "model_id": str(model_id)},
+        )
+
+    def all[T: BaseModel](self, model_class: type[T]) -> list[Document[T]]:
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        cursor = self._conn.execute(
+            """\
+SELECT
+    model_class,
+    model_id,
+    model
+FROM document
+WHERE
+    model_class = :model_class
+;
+            """.strip(),
+            {"model_class": model_class.__name__},
+        )
+        return [
+            self._row_to_document(model_class, cursor, row) for row in cursor.fetchall()
+        ]
+
+    def get_many[T: BaseModel](
+        self, model_class: type[T], model_ids: list[str]
+    ) -> list[Document[T] | None]:
+        if not model_ids:
+            return []
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        placeholders = ",".join("?" * len(model_ids))
+        cursor = self._conn.execute(
+            f"""\
+SELECT
+    model_class,
+    model_id,
+    model
+FROM document
+WHERE
+    model_class = ?
+    AND model_id IN ({placeholders})
+;
+            """.strip(),
+            [model_class.__name__, *model_ids],
+        )
+        results_dict = {
+            row[1]: self._row_to_document(model_class, cursor, row)
+            for row in cursor.fetchall()
+        }
+        return [results_dict.get(model_id) for model_id in model_ids]
+
+    def delete_many(self, model_class: type[BaseModel], model_ids: list[str]) -> None:
+        if not model_ids:
+            return
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        placeholders = ",".join("?" * len(model_ids))
+        self._conn.execute(
+            f"""\
+DELETE
+FROM document
+WHERE
+    model_class = ?
+    AND model_id IN ({placeholders})
+;
+            """.strip(),
+            [model_class.__name__, *model_ids],
+        )
+
+    def put_many[T: BaseModel](
+        self, model_class: type[T], models: list[tuple[str, T]]
+    ) -> list[Document[T]]:
+        if not models:
+            return []
+        if self._conn is None:
+            raise ValueError(_CONNECTION_NOT_INITIALIZED)
+        values_placeholders = ",".join("(?, ?, ?)" * len(models))
+        flat_values = [
+            val
+            for model_id, model in models
+            for val in (model_class.__name__, model_id, model.model_dump_json())
+        ]
+        cursor = self._conn.execute(
+            f"""\
+INSERT OR REPLACE INTO document VALUES {values_placeholders}
+RETURNING model_class, model_id, model
+;
+            """.strip(),
+            flat_values,
+        )
+        return [
+            self._row_to_document(model_class, cursor, row) for row in cursor.fetchall()
+        ]

sapling_db-0.1.0/src/sapling/database.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+from tryke import describe, expect, test
+
+from sapling import MemoryBackend, SQLiteBackend
+from sapling.errors import NotFoundError
+from sapling.settings import SaplingSettings
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterator
+    from contextlib import AbstractContextManager
+    from types import TracebackType
+
+    from sapling.backends.base import Backend
+    from sapling.document import Document
+
+
+class _TransactionWrapper:
+    """
+    Wrapper for backend transactions.
+
+    works as both context managers and generators.
+    """
+
+    def __init__(self, backend_transaction_cm: AbstractContextManager[Backend]) -> None:
+        self._backend_txn_cm: AbstractContextManager[Backend] = backend_transaction_cm
+
+    def __enter__(self) -> Backend:
+        return self._backend_txn_cm.__enter__()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        return self._backend_txn_cm.__exit__(exc_type, exc_value, traceback)
+
+    def __call__(self) -> Iterator[Backend]:
+        return iter(self)
+
+    def __iter__(self) -> Generator[Backend]:
+        with self._backend_txn_cm as txn:
+            yield txn
+
+
+class Database:
+    """
+    main interface for sapling persistence.
+
+    provides crud operations with transaction management.
+
+    Args:
+        backend: storage backend (defaults to SQLiteBackend)
+        initialize: whether to initialize backend immediately
+
+    """
+
+    def __init__(
+        self, backend: Backend | None = None, *, initialize: bool = True
+    ) -> None:
+        self._backend: Backend = backend or SQLiteBackend()
+        if initialize:
+            self._backend.initialize()
+
+    def initialize(self) -> None:
+        """
+        Initialize backend (idempotent - safe to call multiple times).
+
+        use this when `initialize=False` was passed to Database constructor.
+        """
+        self._backend.initialize()
+
+    def transaction(self) -> _TransactionWrapper:
+        """
+        Create transaction context for multiple operations.
+
+        commits on success, rolls back on exception.
+
+        Returns:
+            context manager yielding backend instance
+
+        Example:
+            ```python
+            with db.transaction() as txn:
+                txn.put(User, "1", user1)
+                txn.put(User, "2", user2)
+            ```
+
+        """
+        return _TransactionWrapper(self._backend.transaction())
+
+    def transaction_dependency(self) -> Generator[Backend]:
+        """
+        Fastapi dependency for request-scoped transactions.
+
+        use with Depends() for automatic transaction management.
+
+        Yields:
+            backend instance for crud operations
+
+        Example:
+            ```python
+            @app.post("/users/{user_id}")
+            def create(
+                user_id: str,
+                user: User,
+                txn: Annotated[Backend, Depends(db.transaction_dependency)],
+            ):
+                return txn.put(User, user_id, user)
+            ```
+
+        """
+        with self._backend.transaction() as txn:
+            yield txn
+
+    def get[T: BaseModel](
+        self, model_class: type[T], model_id: str
+    ) -> Document[T] | None:
+        """
+        Retrieve document by id, returns None if not found.
+
+        Args:
+            model_class: pydantic model class
+            model_id: document identifier
+
+        Returns:
+            document if found, None otherwise
+
+        """
+        with self.transaction() as txn:
+            return txn.get(model_class, model_id)
+
+    def put[T: BaseModel](
+        self, model_class: type[T], model_id: str, model: T
+    ) -> Document[T]:
+        """
+        Insert or update document.
+
+        Args:
+            model_class: pydantic model class
+            model_id: document identifier
+            model: pydantic model instance
+
+        Returns:
+            persisted document
+
+        """
+        with self.transaction() as txn:
+            return txn.put(model_class, model_id, model)
+
+    def fetch[T: BaseModel](self, model_class: type[T], model_id: str) -> Document[T]:
+        """
+        Retrieve document by id, raises if not found.
+
+        Args:
+            model_class: pydantic model class
+            model_id: document identifier
+
+        Returns:
+            document
+
+        Raises:
+            NotFoundError: document does not exist
+
+        """
+        with self.transaction() as txn:
+            return txn.fetch(model_class, model_id)
+
+    def delete(self, model_class: type[BaseModel], model_id: str) -> None:
+        """
+        Delete document by id.
+
+        idempotent - no error if document doesn't exist.
+
+        Args:
+            model_class: pydantic model class
+            model_id: document identifier
+
+        """
+        with self.transaction() as txn:
+            return txn.delete(model_class, model_id)
+
+    def all[T: BaseModel](self, model_class: type[T]) -> list[Document[T]]:
+        """
+        Retrieve all documents of given model class.
+
+        Args:
+            model_class: pydantic model class
+
+        Returns:
+            list of documents (empty if none exist)
+
+        """
+        with self.transaction() as txn:
+            return txn.all(model_class)
+
+    def get_many[T: BaseModel](
+        self, model_class: type[T], model_ids: list[str]
+    ) -> list[Document[T] | None]:
+        """
+        Retrieve multiple documents by ids, preserving order.
+
+        Args:
+            model_class: pydantic model class
+            model_ids: list of document identifiers
+
+        Returns:
+            list of documents (None for missing ids)
+
+        """
+        with self.transaction() as txn:
+            return txn.get_many(model_class, model_ids)
+
+    def delete_many(self, model_class: type[BaseModel], model_ids: list[str]) -> None:
+        """
+        Delete multiple documents by ids.
+
+        idempotent - no error if documents don't exist.
+
+        Args:
+            model_class: pydantic model class
+            model_ids: list of document identifiers
+
+        """
+        with self.transaction() as txn:
+            return txn.delete_many(model_class, model_ids)
+
+    def put_many[T: BaseModel](
+        self, model_class: type[T], models: list[tuple[str, T]]
+    ) -> list[Document[T]]:
+        """
+        Insert or update multiple documents.
+
+        Args:
+            model_class: pydantic model class
+            models: list of (model_id, model) tuples
+
+        Returns:
+            list of persisted documents
+
+        """
+        with self.transaction() as txn:
+            return txn.put_many(model_class, models)
+
+
+class _TestModel(BaseModel):
+    hello: str = "world"
+
+
+@test
+def test_basic() -> None:
+    db = Database()
+    hello = _TestModel()
+    with db.transaction() as txn:
+        pk = "hello"
+        record = txn.put(_TestModel, pk, hello)
+        expect(record.model_id).to_equal(pk)
+        maybe_record = txn.get(_TestModel, pk)
+        expect(maybe_record).to_be_truthy()
+        record = txn.fetch(_TestModel, pk)
+        txn.delete(_TestModel, pk)
+        expect(lambda: txn.fetch(_TestModel, pk)).to_raise(NotFoundError)
+
+
+@test
+def test_all_method() -> None:
+    db = Database()
+    with db.transaction() as txn:
+        txn.put(_TestModel, "1", _TestModel(hello="one"))
+        txn.put(_TestModel, "2", _TestModel(hello="two"))
+        txn.put(_TestModel, "3", _TestModel(hello="three"))
+
+        all_hellos = txn.all(_TestModel)
+        expect(all_hellos).to_have_length(3)
+        expect({h.model_id for h in all_hellos}).to_equal({"1", "2", "3"})
+        expect({h.model.hello for h in all_hellos}).to_equal({"one", "two", "three"})
+
+
+@test
+def test_all_empty() -> None:
+    db = Database()
+    with db.transaction() as txn:
+        all_hellos = txn.all(_TestModel)
+        expect(all_hellos).to_equal([])
+
+
+@test
+def test_backend_all_method() -> None:
+    backend = SQLiteBackend()
+    db = Database(backend=backend)
+
+    with db.transaction() as txn:
+        txn.put(_TestModel, "a", _TestModel(hello="alpha"))
+        txn.put(_TestModel, "b", _TestModel(hello="beta"))
+
+        all_docs = txn.all(_TestModel)
+        expect(all_docs).to_have_length(2)
+        expect({d.model_id for d in all_docs}).to_equal({"a", "b"})
+
+
+@test
+def test_memory_backend() -> None:
+    backend = MemoryBackend()
+    db = Database(backend=backend)
+
+    with db.transaction() as txn:
+        txn.put(_TestModel, "test", _TestModel(hello="world"))
+        doc = txn.fetch(_TestModel, "test")
+        expect(doc.model.hello).to_equal("world")
+
+        txn.put(_TestModel, "1", _TestModel(hello="one"))
+        txn.put(_TestModel, "2", _TestModel(hello="two"))
+
+        all_docs = txn.all(_TestModel)
+        expect(all_docs).to_have_length(3)
+        expect({d.model_id for d in all_docs}).to_equal({"test", "1", "2"})
+
+        txn.delete(_TestModel, "test")
+        expect(txn.get(_TestModel, "test")).to_be_none()
+
+        expect(lambda: txn.fetch(_TestModel, "test")).to_raise(NotFoundError)
+
+
+with describe("sqlite"):
+
+    @test
+    def test_sqlite_backend_memory() -> None:
+        backend = SQLiteBackend()
+        db = Database(backend=backend)
+        with db.transaction() as txn:
+            txn.put(_TestModel, "test", _TestModel(hello="world"))
+            doc = txn.fetch(_TestModel, "test")
+            expect(doc.model.hello).to_equal("world")
+
+    @test
+    def test_sqlite_backend_file() -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            db_path = Path(tmp_dir) / "test.db"
+            settings = SaplingSettings(sqlite_path=str(db_path))
+            backend = SQLiteBackend(settings=settings)
+            db = Database(backend=backend)
+
+            with db.transaction() as txn:
+                txn.put(_TestModel, "persistent", _TestModel(hello="saved"))
+
+            settings2 = SaplingSettings(sqlite_path=str(db_path))
+            db2 = Database(backend=SQLiteBackend(settings=settings2))
+            with db2.transaction() as txn:
+                doc = txn.fetch(_TestModel, "persistent")
+                expect(doc.model.hello).to_equal("saved")
+
+
+with describe("initialization"):
+
+    @test
+    def test_deferred_initialization() -> None:
+        backend = SQLiteBackend()
+        db = Database(backend=backend, initialize=False)
+
+        db.initialize()
+
+        with db.transaction() as txn:
+            txn.put(_TestModel, "test", _TestModel(hello="world"))
+            doc = txn.fetch(_TestModel, "test")
+            expect(doc.model.hello).to_equal("world")
+
+    @test
+    def test_idempotent_initialization() -> None:
+        backend = SQLiteBackend()
+        db = Database(backend=backend, initialize=False)
+
+        db.initialize()
+        db.initialize()
+        db.initialize()
+
+        with db.transaction() as txn:
+            txn.put(_TestModel, "test", _TestModel(hello="world"))
+
+    @test
+    def test_uninitialized_error() -> None:
+        backend = SQLiteBackend()
+        db = Database(backend=backend, initialize=False)
+
+        def try_uninitialized() -> None:
+            with db.transaction() as txn:
+                txn.put(_TestModel, "test", _TestModel(hello="world"))
+
+        expect(try_uninitialized).to_raise(ValueError, match="not initialized")

sapling_db-0.1.0/src/sapling/document.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Document[T: BaseModel](BaseModel):
+    """
+    container for persisted pydantic models.
+
+    documents wrap model data with persistence metadata, keeping pydantic
+    models pure (no database-specific fields).
+
+    Attributes:
+        model: the pydantic model instance
+        model_id: unique identifier
+        model_class: fully qualified model class name
+
+    Example:
+        ```python
+        user = User(name="alice", email="alice@example.com")
+        doc = txn.put(User, "user_1", user)
+        reveal_type(doc)  # Document[User]
+        print(document.model.name)  # "alice"
+        ```
+
+    """
+
+    model_config: ConfigDict = ConfigDict(frozen=True)  # pyright: ignore[reportIncompatibleVariableOverride]
+    model: T
+    model_id: str
+    model_class: str

sapling_db-0.1.0/src/sapling/errors.py

@@ -0,0 +1,6 @@
+class SaplingError(Exception):
+    """base exception for all sapling errors."""
+
+
+class NotFoundError(SaplingError):
+    """raised when document not found by fetch operation."""

sapling_db-0.1.0/src/sapling/settings.py

@@ -0,0 +1,53 @@
+from functools import cache
+from typing import ClassVar, Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+type IsolationLevel = Literal["DEFERRED", "IMMEDIATE", "EXCLUSIVE"] | None
+
+
+class SaplingSettings(BaseSettings):
+    """
+    sapling configuration settings.
+
+    all settings can be configured via environment variables with
+    the SAPLING_ prefix (e.g., SAPLING_SQLITE_PATH, SAPLING_SQLITE_TIMEOUT).
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="SAPLING_",
+    )
+    sqlite_path: str = Field(
+        default=":memory:",
+        description='database file path, or ":memory:" for in-memory',
+    )
+    sqlite_timeout: float = Field(
+        default=5.0,
+        description="seconds to wait before raising exception if database is locked",
+    )
+    sqlite_detect_types: int = Field(
+        default=0,
+        description="control type detection for non-native sqlite types",
+    )
+    sqlite_isolation_level: IsolationLevel = Field(
+        default="DEFERRED",
+        description="transaction isolation: DEFERRED, IMMEDIATE, EXCLUSIVE, or None",
+    )
+    sqlite_check_same_thread: bool = Field(
+        default=False,
+        description="if True, only creating thread may use connection",
+    )
+    sqlite_cached_statements: int = Field(
+        default=128,
+        description="number of statements to cache internally",
+    )
+    sqlite_uri: bool = Field(
+        default=False,
+        description="if True, interpret path as URI with query string",
+    )
+
+
+@cache
+def get_sapling_settings() -> SaplingSettings:
+    return SaplingSettings()