snekql 0.1.0__tar.gz

snekql-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+**/__pycache__
+*.db

snekql-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

snekql-0.1.0/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## GitHub workflow
+
+- Use the `gh` CLI for GitHub interactions: issues, PRs, comments, labels, and repo metadata.
+- Do not hand-edit GitHub URLs or assume issue state; query with `gh issue view/list` when needed.
+- Implementation work should reference the relevant GitHub issue.
+- When starting a new unit of work, first stash any uncommited changes, do a `git fetch`, then create a new branch, based on the latest `origin/main` branch.
+- All work should be done in a branch, and when a unit of work is complete, open a PR against `main`. Only merge the PR if explicitly told to do so.
+- When doing feature/bug-fixing/refactoring or any code-related work, use TDD.
+
+## Testing and validation
+
+- Use `snektest` for tests.
+  - Look up the installed distribution metadata for `snektest` using `importlib.metadata.distribution("snektest").read_text("METADATA").` The README.
+- Use `pyright` for static typing validation.
+- Preferred validation commands:
+
+  ```bash
+  uv run snektest
+  uv run pyright .
+  uv run ruff check .
+  uv run ruff format --check .
+  ```

snekql-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+Initial v1 release candidate.
+
+- Typed table model declarations with pending/fetched lifecycle states.
+- SQLite-first storage declarations and logical codecs.
+- Immutable query builders for single-table select/insert/update/delete.
+- Async SQLite runtime with bounded connection pool and transactions.
+- Deterministic SQLite `STRICT` table creation and schema verification.
+- Public `SnekqlError` exception hierarchy.
+- PEP 561 typing support with `py.typed` and a public facade stub.

snekql-0.1.0/CONTEXT.md

@@ -0,0 +1,41 @@
+# snekql
+
+snekql is a library for declaring relational data contracts and executing typed SQL-shaped operations against a database. It exists to give Python applications an explicit query layer and runtime without becoming an ORM.
+
+## Language
+
+**Query Builder**:
+The layer that declares relational data contracts and builds typed SQL-shaped operations.
+_Avoid_: ORM, repository
+
+**Query Runtime**:
+The layer that executes built queries against a database and manages database-backed execution concerns.
+_Avoid_: ORM session, persistence layer
+
+**Database**:
+An initialized snekql runtime service that owns database connectivity, schema startup work, and transaction entry.
+_Avoid_: Pool, uninitialized database config
+
+**Transaction**:
+A database transaction exposed directly through the library as the unit within which reads and writes are executed.
+_Avoid_: Unit of Work, session
+
+**Table Model**:
+A Python class that declares a table's row contract and serves as an ergonomic front end over the query builder's schema model.
+_Avoid_: Entity, ORM model
+
+**Dialect**:
+The database-specific SQL and schema behavior targeted by compilation and verification.
+_Avoid_: Driver, runtime
+
+**Server Default**:
+A database-supplied column value that is filled in by the database when an insert omits that column.
+_Avoid_: Python default, constructor default
+
+**Pending Model**:
+A model instance constructed by application code before it has been materialized from the database.
+_Avoid_: Draft, unsaved entity
+
+**Fetched Model**:
+A model instance materialized from database query results by the Query Runtime.
+_Avoid_: Loaded, read model, entity

snekql-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: snekql
+Version: 0.1.0
+Summary: Async typed query builder and runtime for SQLite STRICT tables
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: annotated-types>=0.7.0
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# snekql
+
+snekql is a Python async-first query builder and query runtime for SQL.
+It gives applications explicit SQL-shaped operations, typed
+model declarations, runtime validation, startup schema checks, and transaction-
+based execution without becoming an ORM.
+
+## Quick start
+
+```python
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from snekql import (
+    MISSING,
+    CurrentTimestamp,
+    Database,
+    DateTime,
+    Fetched,
+    Integer,
+    Model,
+    Pending,
+    Text,
+    insert,
+    select,
+)
+
+
+class User[S = Pending](Model[S, "User[Fetched]"]):
+    id: User.GenCol[int] = Integer(
+        primary_key=True,
+        auto_increment=True,
+        default=MISSING,
+    )
+    email: User.Col[str] = Text(nullable=False)
+    status: User.Col[str] = Text(nullable=False, default="active")
+    created_at: User.GenCol[datetime] = DateTime(
+        server_default=CurrentTimestamp(),
+        default=MISSING,
+    )
+
+
+async def main() -> None:
+    db = await Database.initialize(
+        database=Path("app.db"),
+        models=[User],
+        schema_policy="strict",
+        pool_size=5,
+        acquire_timeout=30.0,
+    )
+    try:
+        async with db.transaction(timeout=5.0) as tx:
+            await tx.execute(insert(User(email="alice@example.com")))
+            user = await tx.fetch_one(
+                select(User).where(User.email.eq("alice@example.com")),
+            )
+            if user is not None:
+                print(user.email)
+    finally:
+        await db.close()
+```
+
+## Model declaration
+
+Models directly subclass `Model[S, "ModelName[Fetched]"]`. Application-created
+instances are `Pending`; database reads return `Fetched` instances.
+
+```python
+class AuditLog[S = Pending](Model[S, "AuditLog[Fetched]"]):
+    __tablename__ = "audit_log"
+
+    id: AuditLog.GenCol[int] = Integer(
+        primary_key=True,
+        auto_increment=True,
+        default=MISSING,
+    )
+    message: AuditLog.Col[str] = Text(nullable=False)
+    created_at: AuditLog.GenCol[datetime] = DateTime(
+        server_default=CurrentTimestamp(),
+        default=MISSING,
+    )
+```
+
+Rules to remember:
+
+- `Col[T]` is a normal persisted column.
+- `GenCol[T]` is server/generated; pending values may be `MISSING`, fetched
+  values are `T`.
+- If `__tablename__` is omitted, class names become snake_case table names.
+- Models are immutable after construction/materialization.
+- Fetched models are produced by database reads only.
+
+## Storage classes
+
+- `Integer`
+- `Real`
+- `Text`
+- `Blob`
+- `Json` stores `JSON` text.
+- `Boolean` stores `0` / `1` in an `INTEGER` column.
+- `DateTime` stores UTC text as `YYYY-MM-DDTHH:MM:SS.SSSZ`.
+
+`CurrentTimestamp()` is the only v1 server default and is valid only on
+`DateTime` `GenCol` fields.
+
+## Queries
+
+Queries are immutable. Chaining returns new query objects.
+
+```python
+from snekql import delete, insert, select, update
+
+select(User).all()
+select(User.email).where(User.status.eq("active"))
+select(User.email, User.status).where(User.email.like("%@example.com"))
+
+insert(User(email="alice@example.com"))
+
+update(User).set(User.status.to("disabled")).where(
+    User.email.eq("alice@example.com"),
+)
+
+delete(User).where(User.email.eq("retired@example.com"))
+delete(User).all()  # explicit full-table delete
+```
+
+Filtering is explicit: `select`, `update`, and `delete` must choose exactly one
+of `.where(...)` or `.all()` before execution. Predicates use methods such as
+`.eq(...)`, `.ne(...)`, `.is_null()`, `.in_(...)`, `.like(...)`; Python
+comparison operators are not part of the v1 API.
+
+## Runtime
+
+`Database.initialize(...)` is the only public construction path.
+
+```python
+db = await Database.initialize(database=Path("app.db"), models=[User])
+memory_db = await Database.initialize(database=":memory:")
+```
+
+Use transactions for all work:
+
+```python
+async with db.transaction() as tx:
+    rows = await tx.fetch_all(select(User).all())
+    first_email = await tx.fetch_one(select(User.email).all())
+    await tx.execute(update(User).set(User.status.to("inactive")).all())
+```
+
+Runtime methods:
+
+- `fetch_all(select(...))` returns all result rows.
+- `fetch_one(select(...))` returns the first row or `None`.
+- `execute(insert/update/delete)` returns `None`.
+- `close()` is async and idempotent after a successful close.
+
+## Schema startup
+
+When initialized with `models=[...]`, snekql:
+
+1. Preserves model order.
+2. Rejects duplicate resolved table names.
+3. Creates missing `STRICT` tables.
+4. Verifies existing tables by comparing deterministic generated DDL with
+   SQLite metadata.
+5. Treats drift according to `schema_policy`: `"strict"` raises,
+   `"warn"` logs and continues.
+
+## Error model
+
+Every intentional package-originated exception is a `SnekqlError` subclass.
+Use `SnekqlError` to catch all snekql failures, or catch narrower subclasses:
+
+- `ModelDeclarationError`, `ModelValidationError`, `FrozenModelError`
+- `QueryConstructionError`, `QueryCompilationError`
+- `DatabaseClosedError`, `PoolTimeoutError`, `TransactionClosedError`,
+  `ExecutionError`
+- `SchemaVerificationError`
+
+`ExecutionError` preserves `sql` and `params` for debugging.
+
+## Public API
+
+Agent navigation map:
+
+- `snekql/model.py`: model metaclass, table metadata, pending/fetched
+  materialization.
+- `snekql/storage.py`: column descriptors, SQLite storage metadata, value
+  codecs.
+- `snekql/expressions.py`: predicates, ordering, update assignments.
+- `snekql/query.py`: query builders and SQL compilation.
+- `snekql/runtime.py`: `Database`, `Transaction`, execution methods.
+- `snekql/_pool.py`: internal async SQLite connection pool.
+- `snekql/schema.py`: `STRICT` DDL generation and schema verification.
+- `snekql/errors.py`: public exception hierarchy.
+- `tests/test_public_typing.py`: type-checker prototypes for the public API.
+- `PRD.md`: full v1 product contract.
+- `CONTEXT.md`: project language and terminology.