repositron 0.0.1__tar.gz

repositron-0.0.1/LICENSE

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

repositron-0.0.1/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: repositron
+Version: 0.0.1
+Summary: A typed, generic repository base for SQLAlchemy 2.0. Full CRUD with no per-table boilerplate.
+Keywords: sqlalchemy,repository,orm,crud,typed,generic
+Author: Felipe Adeildo
+Author-email: Felipe Adeildo <contato@felipeadeildo.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: sqlalchemy>=2.0.51
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/felipeadeildo/repositron
+Project-URL: Repository, https://github.com/felipeadeildo/repositron
+Project-URL: Issues, https://github.com/felipeadeildo/repositron/issues
+Description-Content-Type: text/markdown
+
+# repositron
+
+A typed, generic repository base for SQLAlchemy 2.0. Declare a model (and
+optionally a DTO and write payloads), inherit one generic class, and get
+`get` / `first` / `list` / `list_paginated` / `count` / `exists` / `create` /
+`update` / `delete` with no per-table boilerplate.
+
+Every method is fully typed off the generic parameters, so your editor knows
+that `repo.list()` returns `list[UserDTO]` and `repo.get(id)` takes an `int`
+(or a `uuid.UUID`, your choice).
+
+```python
+class UserRepository(Repository[User, UserDTO, UserCreate, UserUpdate]):
+    field_mapping = {"full_name": "name"}
+
+repo.list(is_active=True, order_by=User.created_at.desc())  # -> list[UserDTO]
+repo.update(1, UserUpdate(name="Ada"))                      # only name; others untouched
+```
+
+## Install
+
+```bash
+uv add repositron        # or: pip install repositron
+```
+
+Requires Python 3.13+ and `sqlalchemy>=2.0`. That is the only dependency; the
+dataclass path pulls in nothing else.
+
+## The before / after
+
+Every SQLAlchemy project rewrites the same layer: a class per table wrapping
+`session.query(...)`, the same `get` / `list` / `count`, the same pagination
+math, the same "turn the ORM row into something light to return". It is
+mechanical and easy to get subtly wrong.
+
+### Before: hand-written, per table
+
+```python
+class UserRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def get(self, id: int) -> UserDTO | None:
+        row = self.session.query(User).filter(User.id == id).first()
+        if row is None:
+            return None
+        return UserDTO(id=row.id, name=row.full_name, email=row.email)
+
+    def list(self, *, is_active: bool | None = None) -> list[UserDTO]:
+        query = self.session.query(User)
+        if is_active is not None:
+            query = query.filter(User.is_active == is_active)
+        return [
+            UserDTO(id=r.id, name=r.full_name, email=r.email)
+            for r in query.order_by(User.created_at.desc()).all()
+        ]
+
+    def list_paginated(self, offset: int, limit: int = 20) -> tuple[list[UserDTO], int]:
+        query = self.session.query(User).order_by(User.created_at.desc())
+        total = query.order_by(None).count()
+        rows = query.offset(offset).limit(limit).all()
+        return [UserDTO(id=r.id, name=r.full_name, email=r.email) for r in rows], total
+
+    def count(self, *, is_active: bool | None = None) -> int:
+        query = self.session.query(User.id)
+        if is_active is not None:
+            query = query.filter(User.is_active == is_active)
+        return query.count()
+
+    def create(self, full_name: str, email: str) -> int:
+        user = User(full_name=full_name, email=email)
+        self.session.add(user)
+        self.session.flush()
+        return user.id
+
+    def update(self, id: int, *, full_name: str | None = None, email: str | None = None) -> bool:
+        user = self.session.query(User).filter(User.id == id).first()
+        if user is None:
+            return False
+        if full_name is not None:     # but how do you set a column to NULL on purpose?
+            user.full_name = full_name
+        if email is not None:
+            user.email = email
+        self.session.flush()
+        return True
+
+    # ...and delete, and first, and the same again for the next ten tables.
+```
+
+### After: declare it once
+
+```python
+from dataclasses import dataclass
+from repositron import Repository, UNSET, UnsetType
+
+
+@dataclass(frozen=True, slots=True)
+class UserDTO:                 # light, detached, serializes straight to JSON
+    id: int
+    name: str                  # renamed from the model column `full_name`
+    email: str
+
+
+@dataclass
+class UserCreate:
+    full_name: str
+    email: str
+
+
+@dataclass
+class UserUpdate:
+    full_name: str | UnsetType = UNSET     # absent = leave alone; None = SET NULL
+    email: str | UnsetType = UNSET
+
+
+class UserRepository(Repository[User, UserDTO, UserCreate, UserUpdate]):
+    field_mapping = {"full_name": "name"}
+```
+
+That is the whole repository. Every method above comes for free, typed against
+`UserDTO`:
+
+```python
+repo = UserRepository(session)
+
+repo.get(1)                                          # -> UserDTO | None
+repo.list(is_active=True, order_by=User.created_at.desc())
+repo.list_paginated(0, 20, order_by=User.created_at.desc())  # -> PaginatedResult[UserDTO]
+repo.count(is_active=True)
+repo.create(UserCreate(full_name="Ada Lovelace", email="ada@example.com"))  # -> int (new id)
+repo.update(1, UserUpdate(full_name="Ada L."))       # email left untouched
+repo.delete(1)
+```
+
+## The sugar
+
+### Two ways to filter, in one call
+
+Equality is keyed by attribute name. Anything else is a plain SQLAlchemy
+expression. They combine.
+
+```python
+repo.list(
+    is_active=True,                      # equality
+    extra_filters=[User.age > 18],       # any expression: >, IN, LIKE, OR, ...
+    order_by=[User.created_at.desc(), User.id],
+)
+# WHERE is_active = true AND age > 18 ORDER BY created_at DESC, id
+```
+
+A filter value of `None` means `IS NULL`; `UNSET` skips the filter entirely, so
+you can pass through optional query params without branching.
+
+### Partial updates that can actually write NULL
+
+`UNSET` and `None` are different on purpose. `UNSET` says "don't touch this
+column"; `None` says "set it to NULL". The hand-written `if x is not None`
+pattern can't express the second one.
+
+```python
+repo.update(1, UserUpdate(full_name="Ada"))     # email stays whatever it was
+repo.update(1, UserUpdate(email=None))          # email IS NULL now
+```
+
+### Column projection: load only what you need
+
+Index the repo with a narrow DTO and it selects only those columns, returning
+that shape, for the duration of the call. The injected repository is untouched.
+
+```python
+@dataclass(frozen=True, slots=True)
+class UserIdEmail:
+    id: int
+    email: str
+
+repo[UserIdEmail].list(is_active=True)   # SELECT id, email -> list[UserIdEmail]
+repo[UserIdEmail].first(id=5)
+```
+
+### Pagination is ordered, or it raises
+
+Pagination over an unstable order silently drops and repeats rows across pages,
+so `list_paginated` requires `order_by`. Forgetting it is a `ValueError`, not a
+heisenbug in production.
+
+```python
+repo.list_paginated(0, 20)                                 # ValueError
+repo.list_paginated(0, 20, order_by=User.id)               # PaginatedResult(items=[...], total=...)
+```
+
+## Three shapes of DTO
+
+The DTO is an optimization, not a mandate. Pick the one that fits, and pay only
+for what you use.
+
+### 1. Dataclass DTO (the recommendation)
+
+Lightest, detached from the session, and FastAPI serializes it natively, so the
+same object is your repository return value and your `response_model`. No third
+hand-written schema.
+
+```python
+@app.get("/users")
+def list_users(repo: Annotated[UserRepository, Depends(get_repo)]) -> list[UserDTO]:
+    return repo.list(order_by=User.created_at.desc())
+```
+
+### 2. No DTO at all (model as DTO)
+
+Leave the DTO parameter off and the repository returns the model itself. No
+hydration, no dict round-trip. Set the id type when your keys aren't `int`:
+
+```python
+import uuid
+from repositron import Repository
+
+class AccountRepository(Repository[Account, Account, AccountCreate, AccountUpdate, uuid.UUID]):
+    pass
+
+repo.get(uuid.uuid4())        # -> Account | None, typed on UUID
+repo.list(status="active")    # -> list[Account]
+```
+
+### 3. Pydantic DTO
+
+If you already have a Pydantic response schema, it is the DTO. repositron
+detects Pydantic and hydrates through `model_validate`.
+
+```python
+class UserOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    name: str
+
+class UserRepository(Repository[User, UserOut]): ...
+repo.list()   # -> list[UserOut], ready for HTTP
+```
+
+## Public API
+
+```python
+from repositron import (
+    Repository,            # full CRUD generic base
+    ReadOnlyRepository,    # read-only generic base
+    PaginatedResult,       # {items, total} container
+    UNSET, UnsetType,      # partial-update sentinel
+)
+```
+
+Type parameters: `Repository[ModelT, DTOT=ModelT, CreateT, UpdateT, IdT=int]`.
+`ModelT` is required; everything else has a default, so
+`Repository[Account]` is a valid read/write repository returning `Account` on
+`int` keys.
+
+| Class attribute | Purpose                                       | Default |
+| --------------- | --------------------------------------------- | ------- |
+| `field_mapping` | `{model_field: dto_field}` for renamed fields | `{}`    |
+| `pk_column`     | primary-key column name                       | `"id"`  |
+
+## Design notes
+
+- The session is the caller's. The repository never opens, commits, or closes
+  it; writes `flush`, so transaction boundaries stay in the app.
+- One source of truth per field name: declare a rename once in `field_mapping`
+  and it applies to both hydration and projection.
+- Ordering is never implicit. `list` / `first` default to unordered; pagination
+  refuses to run without an order.
+- `UNSET` is one canonical singleton, compared by identity. There is no
+  per-project override.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

repositron-0.0.1/README.md

@@ -0,0 +1,273 @@
+# repositron
+
+A typed, generic repository base for SQLAlchemy 2.0. Declare a model (and
+optionally a DTO and write payloads), inherit one generic class, and get
+`get` / `first` / `list` / `list_paginated` / `count` / `exists` / `create` /
+`update` / `delete` with no per-table boilerplate.
+
+Every method is fully typed off the generic parameters, so your editor knows
+that `repo.list()` returns `list[UserDTO]` and `repo.get(id)` takes an `int`
+(or a `uuid.UUID`, your choice).
+
+```python
+class UserRepository(Repository[User, UserDTO, UserCreate, UserUpdate]):
+    field_mapping = {"full_name": "name"}
+
+repo.list(is_active=True, order_by=User.created_at.desc())  # -> list[UserDTO]
+repo.update(1, UserUpdate(name="Ada"))                      # only name; others untouched
+```
+
+## Install
+
+```bash
+uv add repositron        # or: pip install repositron
+```
+
+Requires Python 3.13+ and `sqlalchemy>=2.0`. That is the only dependency; the
+dataclass path pulls in nothing else.
+
+## The before / after
+
+Every SQLAlchemy project rewrites the same layer: a class per table wrapping
+`session.query(...)`, the same `get` / `list` / `count`, the same pagination
+math, the same "turn the ORM row into something light to return". It is
+mechanical and easy to get subtly wrong.
+
+### Before: hand-written, per table
+
+```python
+class UserRepository:
+    def __init__(self, session: Session) -> None:
+        self.session = session
+
+    def get(self, id: int) -> UserDTO | None:
+        row = self.session.query(User).filter(User.id == id).first()
+        if row is None:
+            return None
+        return UserDTO(id=row.id, name=row.full_name, email=row.email)
+
+    def list(self, *, is_active: bool | None = None) -> list[UserDTO]:
+        query = self.session.query(User)
+        if is_active is not None:
+            query = query.filter(User.is_active == is_active)
+        return [
+            UserDTO(id=r.id, name=r.full_name, email=r.email)
+            for r in query.order_by(User.created_at.desc()).all()
+        ]
+
+    def list_paginated(self, offset: int, limit: int = 20) -> tuple[list[UserDTO], int]:
+        query = self.session.query(User).order_by(User.created_at.desc())
+        total = query.order_by(None).count()
+        rows = query.offset(offset).limit(limit).all()
+        return [UserDTO(id=r.id, name=r.full_name, email=r.email) for r in rows], total
+
+    def count(self, *, is_active: bool | None = None) -> int:
+        query = self.session.query(User.id)
+        if is_active is not None:
+            query = query.filter(User.is_active == is_active)
+        return query.count()
+
+    def create(self, full_name: str, email: str) -> int:
+        user = User(full_name=full_name, email=email)
+        self.session.add(user)
+        self.session.flush()
+        return user.id
+
+    def update(self, id: int, *, full_name: str | None = None, email: str | None = None) -> bool:
+        user = self.session.query(User).filter(User.id == id).first()
+        if user is None:
+            return False
+        if full_name is not None:     # but how do you set a column to NULL on purpose?
+            user.full_name = full_name
+        if email is not None:
+            user.email = email
+        self.session.flush()
+        return True
+
+    # ...and delete, and first, and the same again for the next ten tables.
+```
+
+### After: declare it once
+
+```python
+from dataclasses import dataclass
+from repositron import Repository, UNSET, UnsetType
+
+
+@dataclass(frozen=True, slots=True)
+class UserDTO:                 # light, detached, serializes straight to JSON
+    id: int
+    name: str                  # renamed from the model column `full_name`
+    email: str
+
+
+@dataclass
+class UserCreate:
+    full_name: str
+    email: str
+
+
+@dataclass
+class UserUpdate:
+    full_name: str | UnsetType = UNSET     # absent = leave alone; None = SET NULL
+    email: str | UnsetType = UNSET
+
+
+class UserRepository(Repository[User, UserDTO, UserCreate, UserUpdate]):
+    field_mapping = {"full_name": "name"}
+```
+
+That is the whole repository. Every method above comes for free, typed against
+`UserDTO`:
+
+```python
+repo = UserRepository(session)
+
+repo.get(1)                                          # -> UserDTO | None
+repo.list(is_active=True, order_by=User.created_at.desc())
+repo.list_paginated(0, 20, order_by=User.created_at.desc())  # -> PaginatedResult[UserDTO]
+repo.count(is_active=True)
+repo.create(UserCreate(full_name="Ada Lovelace", email="ada@example.com"))  # -> int (new id)
+repo.update(1, UserUpdate(full_name="Ada L."))       # email left untouched
+repo.delete(1)
+```
+
+## The sugar
+
+### Two ways to filter, in one call
+
+Equality is keyed by attribute name. Anything else is a plain SQLAlchemy
+expression. They combine.
+
+```python
+repo.list(
+    is_active=True,                      # equality
+    extra_filters=[User.age > 18],       # any expression: >, IN, LIKE, OR, ...
+    order_by=[User.created_at.desc(), User.id],
+)
+# WHERE is_active = true AND age > 18 ORDER BY created_at DESC, id
+```
+
+A filter value of `None` means `IS NULL`; `UNSET` skips the filter entirely, so
+you can pass through optional query params without branching.
+
+### Partial updates that can actually write NULL
+
+`UNSET` and `None` are different on purpose. `UNSET` says "don't touch this
+column"; `None` says "set it to NULL". The hand-written `if x is not None`
+pattern can't express the second one.
+
+```python
+repo.update(1, UserUpdate(full_name="Ada"))     # email stays whatever it was
+repo.update(1, UserUpdate(email=None))          # email IS NULL now
+```
+
+### Column projection: load only what you need
+
+Index the repo with a narrow DTO and it selects only those columns, returning
+that shape, for the duration of the call. The injected repository is untouched.
+
+```python
+@dataclass(frozen=True, slots=True)
+class UserIdEmail:
+    id: int
+    email: str
+
+repo[UserIdEmail].list(is_active=True)   # SELECT id, email -> list[UserIdEmail]
+repo[UserIdEmail].first(id=5)
+```
+
+### Pagination is ordered, or it raises
+
+Pagination over an unstable order silently drops and repeats rows across pages,
+so `list_paginated` requires `order_by`. Forgetting it is a `ValueError`, not a
+heisenbug in production.
+
+```python
+repo.list_paginated(0, 20)                                 # ValueError
+repo.list_paginated(0, 20, order_by=User.id)               # PaginatedResult(items=[...], total=...)
+```
+
+## Three shapes of DTO
+
+The DTO is an optimization, not a mandate. Pick the one that fits, and pay only
+for what you use.
+
+### 1. Dataclass DTO (the recommendation)
+
+Lightest, detached from the session, and FastAPI serializes it natively, so the
+same object is your repository return value and your `response_model`. No third
+hand-written schema.
+
+```python
+@app.get("/users")
+def list_users(repo: Annotated[UserRepository, Depends(get_repo)]) -> list[UserDTO]:
+    return repo.list(order_by=User.created_at.desc())
+```
+
+### 2. No DTO at all (model as DTO)
+
+Leave the DTO parameter off and the repository returns the model itself. No
+hydration, no dict round-trip. Set the id type when your keys aren't `int`:
+
+```python
+import uuid
+from repositron import Repository
+
+class AccountRepository(Repository[Account, Account, AccountCreate, AccountUpdate, uuid.UUID]):
+    pass
+
+repo.get(uuid.uuid4())        # -> Account | None, typed on UUID
+repo.list(status="active")    # -> list[Account]
+```
+
+### 3. Pydantic DTO
+
+If you already have a Pydantic response schema, it is the DTO. repositron
+detects Pydantic and hydrates through `model_validate`.
+
+```python
+class UserOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    name: str
+
+class UserRepository(Repository[User, UserOut]): ...
+repo.list()   # -> list[UserOut], ready for HTTP
+```
+
+## Public API
+
+```python
+from repositron import (
+    Repository,            # full CRUD generic base
+    ReadOnlyRepository,    # read-only generic base
+    PaginatedResult,       # {items, total} container
+    UNSET, UnsetType,      # partial-update sentinel
+)
+```
+
+Type parameters: `Repository[ModelT, DTOT=ModelT, CreateT, UpdateT, IdT=int]`.
+`ModelT` is required; everything else has a default, so
+`Repository[Account]` is a valid read/write repository returning `Account` on
+`int` keys.
+
+| Class attribute | Purpose                                       | Default |
+| --------------- | --------------------------------------------- | ------- |
+| `field_mapping` | `{model_field: dto_field}` for renamed fields | `{}`    |
+| `pk_column`     | primary-key column name                       | `"id"`  |
+
+## Design notes
+
+- The session is the caller's. The repository never opens, commits, or closes
+  it; writes `flush`, so transaction boundaries stay in the app.
+- One source of truth per field name: declare a rename once in `field_mapping`
+  and it applies to both hydration and projection.
+- Ordering is never implicit. `list` / `first` default to unordered; pagination
+  refuses to run without an order.
+- `UNSET` is one canonical singleton, compared by identity. There is no
+  per-project override.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

repositron-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "repositron"
+version = "0.0.1"
+description = "A typed, generic repository base for SQLAlchemy 2.0. Full CRUD with no per-table boilerplate."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Felipe Adeildo", email = "contato@felipeadeildo.com" }
+]
+requires-python = ">=3.13"
+keywords = ["sqlalchemy", "repository", "orm", "crud", "typed", "generic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "sqlalchemy>=2.0.51",
+]
+
+[project.urls]
+Homepage = "https://github.com/felipeadeildo/repositron"
+Repository = "https://github.com/felipeadeildo/repositron"
+Issues = "https://github.com/felipeadeildo/repositron/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.22,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "prek>=0.4.5",
+    "ruff>=0.15.18",
+    "ty>=0.0.51",
+    "zensical>=0.0.45",
+]

repositron-0.0.1/src/repositron/__init__.py

@@ -0,0 +1,17 @@
+"""repositron: a typed, generic SQLAlchemy 2.0 repository base.
+
+Declare a Model (and optionally a DTO and write payloads), inherit one generic
+base, and get a typed repository with filtering, ordering, pagination, column
+projection, and model-to-DTO hydration, without per-table CRUD boilerplate.
+
+    from repositron import Repository, UNSET, UnsetType
+
+    class TargetRepository(Repository[Target, TargetDTO, TargetCreate, TargetUpdate]):
+        field_mapping = {"mention_rank": "rank"}
+"""
+
+from repositron.base import PaginatedResult
+from repositron.sentinel import UNSET, UnsetType
+from repositron.sql import ReadOnlyRepository, Repository
+
+__all__ = ["UNSET", "PaginatedResult", "ReadOnlyRepository", "Repository", "UnsetType"]

repositron-0.0.1/src/repositron/base.py

@@ -0,0 +1,130 @@
+"""Backend-agnostic repository contracts and the pagination container.
+
+These declare what a repository offers, independent of any database. The
+SQLAlchemy implementation that a project actually inherits from lives in
+`repositron.sql`. Import `Repository` from the package root, not from here.
+"""
+
+import datetime
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+
+from sqlalchemy.sql.elements import ColumnElement
+
+from repositron.sentinel import UnsetType
+
+_list = list  # the list() method below shadows the builtin in class scope
+
+# Equality-filter value: UNSET skips the filter, None filters by IS NULL.
+type FilterValue = (
+    str
+    | int
+    | float
+    | bool
+    | datetime.datetime
+    | datetime.date
+    | Enum
+    | None
+    | UnsetType
+)
+
+# order_by value: a column, a list of columns, or None for no ordering.
+type OrderBy = ColumnElement | _list[ColumnElement] | None
+
+
+@dataclass(frozen=True, slots=True)
+class PaginatedResult[DTOT]:
+    """One page of results plus the count the query would return unpaginated."""
+
+    items: list[DTOT]
+    total: int
+    """Total matching rows ignoring offset/limit; for computing page counts."""
+
+
+class ReadOnlyRepositoryABC[ModelT, DTOT = ModelT, IdT = int](ABC):
+    """Read-only side of the repository contract (get, first, list, count, exists).
+
+    Backends implement this; consumers inherit the concrete `ReadOnlyRepository`
+    from `repositron.sql` instead.
+    """
+
+    @abstractmethod
+    def get(self, id: IdT) -> DTOT | None:
+        """Get a single record by primary key, or None if absent."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def first(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> DTOT | None:
+        """Get the first record matching the filters, or None."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def list(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> _list[DTOT]:
+        """List records matching the filters."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_paginated(
+        self,
+        offset: int,
+        limit: int = 20,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> PaginatedResult[DTOT]:
+        """List records with pagination. `order_by` is required."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def count(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        **filters: FilterValue,
+    ) -> int:
+        """Count records matching the filters."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def exists(self, id: IdT) -> bool:
+        """Check whether a record with this primary key exists."""
+        raise NotImplementedError
+
+
+class CRUDRepositoryABC[
+    ModelT,
+    DTOT = ModelT,
+    CreateT = object,
+    UpdateT = object,
+    IdT = int,
+](ReadOnlyRepositoryABC[ModelT, DTOT, IdT]):
+    """Adds create/update/delete to the read-only contract."""
+
+    @abstractmethod
+    def create(self, payload: CreateT) -> IdT:
+        """Create a record from a dataclass payload. Returns the new primary key."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def update(self, id: IdT, payload: UpdateT) -> bool:
+        """Partial-update a record; UNSET fields are skipped. False if not found."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, id: IdT) -> bool:
+        """Delete a record by primary key. False if not found."""
+        raise NotImplementedError

repositron-0.0.1/src/repositron/sentinel.py

@@ -0,0 +1,33 @@
+"""The partial-update sentinel.
+
+One canonical singleton, compared by identity. A field equal to `UNSET` on an
+update payload is skipped (left untouched); `None` is a real value (SET NULL).
+"""
+
+from typing import Final
+
+
+class UnsetType:
+    """Type of the `UNSET` sentinel; instances compare equal only by identity.
+
+    Annotate an optional update field as `int | UnsetType = UNSET` so it can be
+    distinguished from an explicit `None`.
+    """
+
+    _instance: "UnsetType | None" = None
+
+    def __new__(cls) -> "UnsetType":
+        # ponytail: enforce the singleton so identity comparison is always safe,
+        # even if someone calls UnsetType() directly.
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET: Final[UnsetType] = UnsetType()

repositron-0.0.1/src/repositron/sql.py

@@ -0,0 +1,433 @@
+"""Concrete SQLAlchemy repositories: `ReadOnlyRepository` and `Repository`.
+
+The working classes a project inherits from. They implement the contracts in
+`repositron.base` over a SQLAlchemy `Session`, adding model-to-DTO hydration,
+column projection via `repo[DTO]`, and the equality/expression filter split.
+"""
+
+import copy
+from dataclasses import fields, is_dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, ClassVar, cast, get_args, get_origin
+
+from sqlalchemy.orm import Query, Session
+from sqlalchemy.sql.elements import ColumnElement
+
+from repositron.base import (
+    CRUDRepositoryABC,
+    FilterValue,
+    OrderBy,
+    PaginatedResult,
+    ReadOnlyRepositoryABC,
+)
+from repositron.sentinel import UnsetType
+
+if TYPE_CHECKING:
+    from _typeshed import DataclassInstance
+
+_list = list  # avoids shadowing by the list() method in class scope
+
+
+class ReadOnlyRepository[ModelT, DTOT = ModelT, IdT = int](
+    ReadOnlyRepositoryABC[ModelT, DTOT, IdT]
+):
+    """Typed read access to one table, parameterized by model, DTO, and id type.
+
+    Reads return the DTO `DTOT` (defaults to `ModelT`, i.e. the model itself with
+    no hydration). The instance holds no per-call state, so a single repository is
+    safe to share and inject.
+
+    Two filtering mechanisms combine in one call:
+
+    - `**filters`: equality only (`column == value`), keyed by model attribute
+      name, e.g. `name="Ale"`. `UNSET` skips that filter; `None` filters by
+      `IS NULL`.
+    - `extra_filters`: arbitrary SQLAlchemy expressions for what equality can't
+      express, like `age > 18`, `IN`, `LIKE`, `OR`. So
+      `list(name="Ale", extra_filters=[Model.age > 18])` is
+      `WHERE name = 'Ale' AND age > 18`.
+
+    The return type is resolved `repo[X]` (call site) > `DTOT` (class default) >
+    `ModelT` (fallback); see `__getitem__`.
+    """
+
+    field_mapping: ClassVar[dict[str, str]] = {}
+    """Renamed fields as `{model_field: dto_field}`, applied both when hydrating and when resolving projection columns."""  # noqa: E501
+    pk_column: ClassVar[str] = "id"
+    """Primary-key column name; override for models keyed elsewhere (e.g. `"url_hash"`)."""
+
+    def __init__(self, session: Session) -> None:
+        """
+        Args:
+            session: Caller-owned session. The repository never opens, commits, or
+                closes it; writes `flush` only.
+        """
+        self.session = session
+        self._active_dto: type | None = None
+        """DTO bound via `__getitem__` (call-site override); None uses the class default."""
+
+    @classmethod
+    def _extract_type_arg(cls, index: int) -> type | None:
+        """Extract a generic type argument from `__orig_bases__`, or None if absent.
+
+        Scans for the base parameterized off `ReadOnlyRepository` and
+        returns its argument at `index`. Robust to multiple inheritance (mixins
+        are skipped) and to base position in the MRO. Returns None when the
+        argument was omitted (e.g. DTOT left to its default) so callers can fall
+        back rather than crash.
+        """
+        for base in getattr(cls, "__orig_bases__", ()):
+            origin = get_origin(base) or base
+            if isinstance(origin, type) and issubclass(origin, ReadOnlyRepository):
+                args = get_args(base)
+                if len(args) > index:
+                    arg = args[index]
+                    # A still-unbound TypeVar (default not supplied) is not a real type.
+                    return arg if isinstance(arg, type) else None
+                return None
+        raise TypeError(
+            f"Cannot infer type arguments for {cls.__name__}. Inherit passing the generic "
+            f"parameters, e.g. class MyRepo(Repository[Model, DTO, Create, Update])."
+        )
+
+    @cached_property
+    def model_class(self) -> type[ModelT]:
+        """SQLAlchemy model class, inferred from the `ModelT` generic parameter."""
+        model = self._extract_type_arg(0)
+        if model is None:
+            raise TypeError(
+                f"{type(self).__name__} must be parameterized with a model class."
+            )
+        return cast("type[ModelT]", model)
+
+    @cached_property
+    def dto_class(self) -> type[DTOT]:
+        """DTO class: the `DTOT` generic if supplied, else `ModelT` (model-as-DTO)."""
+        dto = self._extract_type_arg(1)
+        return cast("type[DTOT]", dto if dto is not None else self.model_class)
+
+    @property
+    def _dto(self) -> type:
+        """Active DTO: the call-site override (`repo[X]`) if set, else the class default."""
+        return self._active_dto if self._active_dto is not None else self.dto_class
+
+    def __getitem__[S](self, dto: type[S]) -> "ReadOnlyRepository[ModelT, S, IdT]":
+        """Return a lightweight clone bound to `dto` for this call.
+
+        The clone shares this repository's session and diverges only in its active
+        DTO, so the injected instance stays untouched and thread-safe. A narrow
+        dataclass DTO triggers column projection (loads only its fields).
+
+        Example:
+            repo[TargetIdOrg].list(is_active=True)  # SELECT id, organization_id
+        """
+        clone = copy.copy(self)
+        clone._active_dto = dto
+        return cast("ReadOnlyRepository[ModelT, S, IdT]", clone)
+
+    @property
+    def _pk_col(self) -> ColumnElement:
+        """The primary-key column element, configurable via `pk_column`."""
+        col = getattr(self.model_class, self.pk_column, None)
+        if col is None:
+            raise AttributeError(
+                f"{self.model_class.__name__} has no column '{self.pk_column}'"
+            )
+        return col  # type: ignore[return-value]
+
+    def _project_columns(self, dto: type) -> _list[ColumnElement]:
+        """Resolve a dataclass DTO's fields to model columns (in field order), honoring field_mapping."""  # noqa: E501
+        reverse = {v: k for k, v in self.field_mapping.items()}
+        names = [f.name for f in fields(cast("type[DataclassInstance]", dto))]
+        if not names:
+            raise ValueError(f"DTO {dto.__name__} has no fields")
+        columns: _list[ColumnElement] = []
+        for name in names:
+            model_field = reverse.get(name, name)
+            col = getattr(self.model_class, model_field, None)
+            if col is None:
+                raise AttributeError(
+                    f"DTO {dto.__name__}: field '{name}' maps to no column on "
+                    f"{self.model_class.__name__} (model_field='{model_field}')"
+                )
+            columns.append(col)
+        return columns
+
+    def _project(
+        self,
+        dto: type,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None,
+        order_by: OrderBy,
+        **filters: FilterValue,
+    ) -> Query:
+        """Build the column-projection query for a dataclass `dto` (rows in field order)."""
+        return self._select(
+            *self._project_columns(dto),
+            extra_filters=extra_filters,
+            order_by=order_by,
+            **filters,
+        )
+
+    def _hydrate(self, model: ModelT) -> DTOT:
+        """Convert a model instance to the active DTO.
+
+        When the DTO is the model class the instance is returned unchanged. A
+        Pydantic DTO goes through `model_validate`, a dataclass DTO is built by
+        field name; both honor `field_mapping` for renames. Override for a DTO
+        the automatic path can't construct.
+        """
+        dto = self._dto
+        if dto is self.model_class:
+            return cast("DTOT", model)
+
+        try:
+            # ponytail: duck-type on model_validate instead of importing pydantic, so it
+            # stays a genuinely optional extra. from_attributes reads off the model; aliases rename.
+            validate = getattr(dto, "model_validate", None)
+            if validate is not None:
+                return cast("DTOT", validate(model))
+
+            model_dict = {
+                k: v for k, v in model.__dict__.items() if not k.startswith("_")
+            }
+            if is_dataclass(dto):
+                reverse = {v: k for k, v in self.field_mapping.items()}
+                kwargs = {
+                    f.name: model_dict[reverse.get(f.name, f.name)]
+                    for f in fields(dto)
+                    if reverse.get(f.name, f.name) in model_dict
+                }
+                return cast("DTOT", dto(**kwargs))
+            return cast("DTOT", dto(**model_dict))
+        except (AttributeError, TypeError, IndexError) as e:
+            raise NotImplementedError(
+                f"Cannot automatically convert {type(model).__name__} to {dto.__name__}. "
+                f"Override _hydrate() in your repository subclass. Error: {e}"
+            ) from e
+
+    def _apply_filters(
+        self,
+        query: Query,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        **filters: FilterValue,
+    ) -> Query:
+        """Apply equality `**filters` and arbitrary `extra_filters` (see class docstring).
+
+        Raises:
+            ValueError: if a `**filters` key is not a model attribute.
+        """
+        for key, value in filters.items():
+            if isinstance(value, UnsetType):
+                continue
+            if not hasattr(self.model_class, key):
+                raise ValueError(
+                    f"{self.model_class.__name__} has no attribute '{key}'"
+                )
+            query = query.filter(getattr(self.model_class, key) == value)
+        if extra_filters:
+            query = query.filter(*extra_filters)
+        return query
+
+    def _apply_order(self, query: Query, order_by: OrderBy = None) -> Query:
+        """Apply `order_by` to a query; `None` leaves it unordered."""
+        if order_by is None:
+            return query
+        if isinstance(order_by, list):
+            return query.order_by(*order_by)
+        return query.order_by(order_by)
+
+    def _select(
+        self,
+        *columns: ColumnElement,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> Query:
+        """Build a query (over `columns`, or the whole model if none) with filters and order applied."""  # noqa: E501
+        target = (
+            self.session.query(*columns)
+            if columns
+            else self.session.query(self.model_class)
+        )
+        target = self._apply_filters(target, extra_filters=extra_filters, **filters)
+        return self._apply_order(target, order_by=order_by)
+
+    def _projecting(self) -> type | None:
+        """The active DTO if it warrants column projection (a non-model dataclass), else None."""
+        dto = self._dto
+        if dto is self.model_class:
+            return None
+        return dto if is_dataclass(dto) else None
+
+    def get(self, id: IdT) -> DTOT | None:
+        """Fetch one record by primary key, hydrated to the active DTO."""
+        model = self.session.query(self.model_class).filter(self._pk_col == id).first()
+        if model is None:
+            return None
+        return self._hydrate(model)
+
+    def first(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> DTOT | None:
+        """Fetch the first matching record, hydrated to the active DTO, or None."""
+        dto = self._projecting()
+        if dto is not None:
+            row = self._project(
+                dto, extra_filters=extra_filters, order_by=order_by, **filters
+            ).first()
+            return cast("DTOT", dto(*row)) if row is not None else None
+        model = self._select(
+            extra_filters=extra_filters, order_by=order_by, **filters
+        ).first()
+        if model is None:
+            return None
+        return self._hydrate(model)
+
+    def list(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> _list[DTOT]:
+        """List records matching the filters, each hydrated to the active DTO."""
+        dto = self._projecting()
+        if dto is not None:
+            rows = self._project(
+                dto, extra_filters=extra_filters, order_by=order_by, **filters
+            ).all()
+            # Rows come back in the DTO's field order (see _project_columns); build positionally.
+            return cast("_list[DTOT]", [dto(*row) for row in rows])
+        models = self._select(
+            extra_filters=extra_filters, order_by=order_by, **filters
+        ).all()
+        return [self._hydrate(m) for m in models]
+
+    def list_paginated(
+        self,
+        offset: int,
+        limit: int = 20,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        order_by: OrderBy = None,
+        **filters: FilterValue,
+    ) -> PaginatedResult[DTOT]:
+        """Return a page of records plus the unpaginated total.
+
+        Args:
+            order_by: Required. Pagination over an unstable order silently drops
+                and repeats rows across pages, so a None order is rejected.
+
+        Raises:
+            ValueError: If `order_by` is None.
+        """
+        if order_by is None:
+            raise ValueError(
+                "list_paginated requires order_by: pagination is unstable without a stable order"
+            )
+        dto = self._projecting()
+        if dto is not None:
+            query = self._project(
+                dto, extra_filters=extra_filters, order_by=order_by, **filters
+            )
+            total = query.order_by(None).count()
+            rows = query.offset(offset).limit(limit).all()
+            items = cast("_list[DTOT]", [dto(*row) for row in rows])
+            return PaginatedResult(items=items, total=total)
+        query = self._select(extra_filters=extra_filters, order_by=order_by, **filters)
+        total = query.order_by(None).count()
+        models = query.offset(offset).limit(limit).all()
+        return PaginatedResult(items=[self._hydrate(m) for m in models], total=total)
+
+    def count(
+        self,
+        *,
+        extra_filters: _list[ColumnElement[bool]] | None = None,
+        **filters: FilterValue,
+    ) -> int:
+        """Count records matching the filters."""
+        query = self.session.query(self._pk_col)
+        query = self._apply_filters(query, extra_filters=extra_filters, **filters)
+        return query.count()
+
+    def exists(self, id: IdT) -> bool:
+        """Check whether a record with this primary key exists."""
+        return (
+            self.session.query(self._pk_col).filter(self._pk_col == id).first()
+            is not None
+        )
+
+
+class Repository[ModelT, DTOT = ModelT, CreateT = object, UpdateT = object, IdT = int](
+    ReadOnlyRepository[ModelT, DTOT, IdT],
+    CRUDRepositoryABC[ModelT, DTOT, CreateT, UpdateT, IdT],
+):
+    """Read access plus `create`/`update`/`delete` from dataclass payloads.
+
+    Writes `flush` so the caller still owns the transaction boundary (no
+    `commit`). `CreateT`/`UpdateT` are the payload dataclasses; `UNSET` fields are
+    skipped on write.
+
+    Example:
+        class TargetRepository(
+            Repository[Target, TargetDTO, TargetCreate, TargetUpdate]
+        ):
+            field_mapping = {"mention_rank": "rank"}
+    """
+
+    def create(self, payload: CreateT) -> IdT:
+        """Insert a record from a dataclass payload and flush.
+
+        UNSET fields are omitted, so the column or model default applies.
+
+        Returns:
+            The new primary-key value, read back after the flush.
+        """
+        kwargs = {
+            f.name: getattr(payload, f.name)
+            for f in fields(cast("DataclassInstance", payload))
+            if hasattr(self.model_class, f.name)
+            and not isinstance(getattr(payload, f.name), UnsetType)
+        }
+        model = self.model_class(**kwargs)  # type: ignore[call-arg]
+        self.session.add(model)
+        self.session.flush()
+        return getattr(model, self.pk_column)
+
+    def update(self, id: IdT, payload: UpdateT) -> bool:
+        """Apply a partial update from a dataclass payload and flush.
+
+        UNSET fields are left untouched; `None` is written as a real value
+        (SET NULL).
+
+        Returns:
+            True on success, False if no record has that primary key.
+        """
+        model = self.session.query(self.model_class).filter(self._pk_col == id).first()
+        if model is None:
+            return False
+        for f in fields(cast("DataclassInstance", payload)):
+            value = getattr(payload, f.name)
+            if not isinstance(value, UnsetType) and hasattr(model, f.name):
+                setattr(model, f.name, value)
+        self.session.flush()
+        return True
+
+    def delete(self, id: IdT) -> bool:
+        """Delete a record by primary key and flush.
+
+        Returns:
+            True on success, False if no record has that primary key.
+        """
+        model = self.session.query(self.model_class).filter(self._pk_col == id).first()
+        if model is None:
+            return False
+        self.session.delete(model)
+        self.session.flush()
+        return True