sqlphilosophy 0.1.4__tar.gz → 0.1.8__tar.gz

{sqlphilosophy-0.1.4/src/sqlphilosophy.egg-info → sqlphilosophy-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlphilosophy
-Version: 0.1.4
+Version: 0.1.8
 Summary: Portable SQLAlchemy repository kit: sync and async CRUD, statement builders, sort/pagination, and SQL helpers.
 Author-email: Josh Martin <denverprogrammer@gmail.com>
 License-Expression: MIT
@@ -111,6 +111,43 @@ with SessionLocal() as session:
 
 **Async:** swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
 
+## Strongly typed repositories (factory pattern)
+
+Domain repositories subclass `BaseRepository[Model, RepositoryFactory]` (or `AsyncBaseRepository` for async) and add typed query helpers. A session-scoped factory implements `RepositoryFactory` to cache repositories and wire `statement()` / `for_repo()` across repos on the same session.
+
+```python
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sync.protocols import RepositoryFactory
+from sqlphilosophy.sync.repository import BaseRepository
+
+
+class UserRepository(BaseRepository[User, RepositoryFactory]):
+    def __init__(self, session: Session, factory: RepositoryFactory) -> None:
+        super().__init__(User, session, factory)
+
+    def get_by_username(self, username: str) -> User | None:
+        return self.first(username=username)
+
+    def get_by_email(self, email: str) -> User | None:
+        return self.first(email=email)
+
+    def get_active_by_email(self, email: str) -> User | None:
+        return (
+            self.statement()
+            .where(User.email == email, User.is_active.is_(True))
+            .scalars()
+            .first()
+        )
+```
+
+Full runnable examples with models, a multi-repo factory, and cross-repository usage:
+
+- Sync: [`examples/typed_repository_sync.py`](./examples/typed_repository_sync.py)
+- Async: [`examples/typed_repository_async.py`](./examples/typed_repository_async.py)
+
+For async, swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
+
 ## Package layout
 
 | Module | Contents |

{sqlphilosophy-0.1.4 → sqlphilosophy-0.1.8}/README.md

@@ -72,6 +72,43 @@ with SessionLocal() as session:
 
 **Async:** swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
 
+## Strongly typed repositories (factory pattern)
+
+Domain repositories subclass `BaseRepository[Model, RepositoryFactory]` (or `AsyncBaseRepository` for async) and add typed query helpers. A session-scoped factory implements `RepositoryFactory` to cache repositories and wire `statement()` / `for_repo()` across repos on the same session.
+
+```python
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sync.protocols import RepositoryFactory
+from sqlphilosophy.sync.repository import BaseRepository
+
+
+class UserRepository(BaseRepository[User, RepositoryFactory]):
+    def __init__(self, session: Session, factory: RepositoryFactory) -> None:
+        super().__init__(User, session, factory)
+
+    def get_by_username(self, username: str) -> User | None:
+        return self.first(username=username)
+
+    def get_by_email(self, email: str) -> User | None:
+        return self.first(email=email)
+
+    def get_active_by_email(self, email: str) -> User | None:
+        return (
+            self.statement()
+            .where(User.email == email, User.is_active.is_(True))
+            .scalars()
+            .first()
+        )
+```
+
+Full runnable examples with models, a multi-repo factory, and cross-repository usage:
+
+- Sync: [`examples/typed_repository_sync.py`](./examples/typed_repository_sync.py)
+- Async: [`examples/typed_repository_async.py`](./examples/typed_repository_async.py)
+
+For async, swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
+
 ## Package layout
 
 | Module | Contents |

sqlphilosophy-0.1.8/src/sqlphilosophy/VERSION

@@ -0,0 +1 @@
+0.1.8

sqlphilosophy-0.1.8/src/sqlphilosophy/aio/protocols.py

@@ -0,0 +1,122 @@
+"""Portable async repository factory and repository protocols (no Phobos or app imports)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from typing import Optional
+from typing import TYPE_CHECKING
+from typing import Protocol
+from typing import TypeVar
+
+if TYPE_CHECKING:
+    from sqlphilosophy.aio.repository import AsyncBaseRepository
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+
+from sqlphilosophy.aio.query import AsyncStatementQueryBuilder
+from sqlphilosophy.types import IdList
+from sqlphilosophy.types import PrimaryKey
+from sqlphilosophy.types import RowMapping
+from sqlphilosophy.types import RowValue
+from sqlphilosophy.types import SqlFilter
+
+T = TypeVar("T", bound=DeclarativeBase)
+R = TypeVar("R", bound="AsyncBaseRepository[Any, Any]")
+
+
+class AsyncBaseRepositoryProtocol[T: DeclarativeBase, U: Optional[AsyncRepositoryFactory]](
+    Protocol,
+):
+    """Generic read/write surface shared by sqlphilosophy ``AsyncBaseRepository[T]``."""
+
+    model: type[T]
+    _session: AsyncSession
+    _factory: Optional[U]
+
+    async def get(self, obj_id: PrimaryKey, load_relations: Any = None) -> T: ...
+
+    async def get_by_id(self, obj_id: PrimaryKey, load_relations: Any = None) -> T | None: ...
+
+    async def get_many(
+        self, ids: Sequence[PrimaryKey], load_relations: Any = None
+    ) -> Sequence[T]: ...
+
+    async def first(self, load_relations: Any = None, **filters: RowValue) -> T | None: ...
+
+    async def filter(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+        **filters: RowValue,
+    ) -> Sequence[T]: ...
+
+    async def get_all(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+    ) -> Sequence[T]: ...
+
+    async def count(self, **filters: RowValue) -> int: ...
+
+    async def exists(self, obj_id: PrimaryKey) -> bool: ...
+
+    async def exists_where(self, **filters: RowValue) -> bool: ...
+
+    def statement(self) -> AsyncStatementQueryBuilder[T]: ...
+
+    async def create(self, **fields: object) -> T: ...
+
+    async def add(self, obj: T) -> T: ...
+
+    async def get_or_create(
+        self, *, defaults: RowMapping | None = None, **lookup: RowValue
+    ) -> tuple[T, bool]: ...
+
+    async def remove(self, obj_id: PrimaryKey) -> bool: ...
+
+    async def delete_many(self, ids: IdList) -> int: ...
+
+    async def delete_where(
+        self, *, criteria: Sequence[SqlFilter], params: RowMapping | None = None
+    ) -> int: ...
+
+    async def update_partial(
+        self,
+        obj_id: PrimaryKey,
+        fields: RowMapping,
+        writable: frozenset[str],
+        *,
+        touch_updated_on: bool = False,
+    ) -> int: ...
+
+    async def update_where(
+        self,
+        *,
+        criteria: Sequence[SqlFilter],
+        values: RowMapping,
+        params: RowMapping | None = None,
+    ) -> int: ...
+
+
+class AsyncRepositoryFactory(Protocol):
+    """Session-scoped factory for async statement builders and entity repositories."""
+
+    def create_statement(self, model: type[T]) -> AsyncStatementQueryBuilder[T]:
+        """Return a fluent async read builder for ``model``."""
+        ...
+
+    def get_repository(self, repo_class: type[R]) -> R:
+        """Return a cached typed entity repository."""
+        ...
+
+    def repository(
+        self, model: type[T]
+    ) -> AsyncBaseRepositoryProtocol[T, Optional[AsyncRepositoryFactory]]:
+        """Return generic CRUD helpers for ``model`` (``AsyncBaseRepository`` in Phobos)."""
+        ...

{sqlphilosophy-0.1.4 → sqlphilosophy-0.1.8}/src/sqlphilosophy/aio/repository.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 from typing import cast
+from typing import Optional
 from sqlalchemy import delete
 from sqlalchemy import func
 from sqlalchemy import inspect as sa_inspect
@@ -31,7 +32,7 @@ from sqlphilosophy.types import cursor_rowcount
 LoadRelations = Sequence[LoaderOption]
 
 
-class AsyncBaseRepository[T: DeclarativeBase]:
+class AsyncBaseRepository[T: DeclarativeBase, U: Optional[AsyncRepositoryFactory]]:
     """Async session-scoped CRUD helpers for a single mapped model."""
 
     def __init__(
@@ -41,7 +42,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         factory: AsyncRepositoryFactory | None = None,
     ) -> None:
         self.model = model
-        self.session = session
+        self._session = session
         self._factory = factory
         pk_cols = self.inspect_model(model).primary_key
         if len(pk_cols) != 1:
@@ -59,7 +60,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
 
     async def list_table_names(self) -> frozenset[str]:
         """Return visible table names on the session connection."""
-        connection = await self.session.connection()
+        connection = await self._session.connection()
 
         def _names(sync_conn: object) -> frozenset[str]:
             insp = sa_inspect(sync_conn)
@@ -79,7 +80,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         return stmt
 
     async def _scalar_result(self, stmt: Any, *, unique: bool = False) -> Any:
-        result = await self.session.scalars(stmt)
+        result = await self._session.scalars(stmt)
         if unique:
             return result.unique()
         return result
@@ -88,19 +89,19 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         self, stmt: Any, params: RowMapping | None = None
     ) -> list[RowMapping]:
         """Execute ``stmt`` and return all rows as mappings."""
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         mapped = result.mappings()
         rows = mapped.all() if hasattr(mapped, "all") else mapped
         return rows_mapping(rows)
 
     async def scalar_count(self, stmt: SqlSelect, params: SqlBindParams | None = None) -> int:
         """Execute a scalar count/select statement and return ``int``."""
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         return int(result.scalar_one())
 
     async def iter_mappings(self, stmt: SqlSelect, params: SqlBindParams | None = None):
         """Yield each result row as a plain ``dict``."""
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         for row in result.mappings():
             yield dict(row)
 
@@ -108,7 +109,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         self, stmt: SqlSelect, params: SqlBindParams | None = None
     ) -> RowMapping | None:
         """Execute ``stmt`` and return the first row as a mapping, or ``None``."""
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         row = result.mappings().first()
         return dict(row) if row is not None else None
 
@@ -116,7 +117,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         self, stmt: SqlSelect, params: SqlBindParams | None = None
     ) -> RowMapping:
         """Execute ``stmt`` and return exactly one row as a mapping."""
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         return dict(result.mappings().one())
 
     async def fetch_mappings_page(
@@ -159,7 +160,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         """Fetch a single record by primary key with optional eager loading."""
         stmt = select(self.model).where(self._pk_column == obj_id)
         stmt = self._apply_load_relations(stmt, load_relations)
-        result = await self.session.scalars(stmt)
+        result = await self._session.scalars(stmt)
         return result.first()
 
     async def exists(self, obj_id: PrimaryKey) -> bool:
@@ -175,7 +176,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         stmt = select(func.count()).select_from(self.model)
         if filters:
             stmt = stmt.filter_by(**filters)
-        result = await self.session.scalar(stmt)
+        result = await self._session.scalar(stmt)
         return int(result or 0)
 
     async def first(
@@ -184,7 +185,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         """Return the first row matching filters, with optional eager loading."""
         stmt = select(self.model).filter_by(**filters).limit(1)
         stmt = self._apply_load_relations(stmt, load_relations)
-        result = await self.session.scalars(stmt)
+        result = await self._session.scalars(stmt)
         return result.first()
 
     async def get(self, obj_id: PrimaryKey, load_relations: LoadRelations | None = None) -> T:
@@ -258,7 +259,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
             stmt = stmt.join(target_model)  # pragma: no cover
         if filter_expressions:
             stmt = stmt.where(*filter_expressions)
-        result = await self.session.execute(stmt)
+        result = await self._session.execute(stmt)
         return cast(Sequence[tuple[T, Any]], result.all())
 
     async def create(self, **fields: object) -> T:
@@ -280,8 +281,8 @@ class AsyncBaseRepository[T: DeclarativeBase]:
 
     async def add(self, obj: T) -> T:
         """Stage a new instance; caller commits in the orchestration layer."""
-        self.session.add(obj)
-        await self.session.flush()
+        self._session.add(obj)
+        await self._session.flush()
         return obj
 
     async def update_partial(
@@ -297,12 +298,12 @@ class AsyncBaseRepository[T: DeclarativeBase]:
             audit_updates = {k: v for k, v in fields.items() if k in writable}
             if not audit_updates:
                 return 0
-            row = await self.session.get(self.model, obj_id)
+            row = await self._session.get(self.model, obj_id)
             if row is None:
                 return 0
             for key, value in audit_updates.items():
                 setattr(row, key, value)
-            await self.session.flush()
+            await self._session.flush()
             return 1
         core_updates: RowMapping = {k: v for k, v in fields.items() if k in writable}
         if not core_updates:
@@ -314,7 +315,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
             )
         pk_col = self._pk_column
         stmt = update(self.model).where(pk_col == obj_id).values(**core_updates)
-        result = await self.session.execute(stmt)
+        result = await self._session.execute(stmt)
         return cursor_rowcount(result)
 
     async def update_where(
@@ -328,7 +329,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         if not values:
             return 0
         stmt = update(self.model).where(*criteria).values(**values)
-        result = await self.session.execute(stmt, params or {})
+        result = await self._session.execute(stmt, params or {})
         return cursor_rowcount(result)
 
     async def delete_where(
@@ -351,7 +352,7 @@ class AsyncBaseRepository[T: DeclarativeBase]:
     async def remove(self, obj_id: PrimaryKey) -> bool:
         """Delete a record by primary key."""
         statement = delete(self.model).where(self._pk_column == obj_id)
-        result = await self.session.execute(statement)
+        result = await self._session.execute(statement)
         return cursor_rowcount(result) > 0
 
     async def delete_many(self, ids: IdList) -> int:
@@ -359,12 +360,12 @@ class AsyncBaseRepository[T: DeclarativeBase]:
         if not ids:
             return 0
         stmt = delete(self.model).where(self._pk_column.in_(ids))
-        result = await self.session.execute(stmt)
+        result = await self._session.execute(stmt)
         return cursor_rowcount(result)
 
     async def delete_all(self) -> int:
         """Delete every row for this model. Dev/ops only — prefer ``delete_where`` in app code."""
-        result = await self.session.execute(delete(self.model))
+        result = await self._session.execute(delete(self.model))
         return cursor_rowcount(result)
 
     async def batched_purge_ids(
@@ -389,17 +390,19 @@ class AsyncBaseRepository[T: DeclarativeBase]:
             if not ids:
                 break
             total += await self.delete_many(ids)
-            await self.session.commit()
+            await self._session.commit()
         return total
 
     def statement(self) -> AsyncStatementQueryBuilder[T]:
         """Return a fluent statement builder for reads on this model (default read path)."""
         if self._factory is not None:
             return self._factory.create_statement(self.model)
-        return AsyncSqlAlchemyStatementBuilder(self.session, self.model)
+        return AsyncSqlAlchemyStatementBuilder(self._session, self.model)
 
-    def for_repo[R](self, repo_class: type[R]) -> R:
+    def for_repo[R: AsyncBaseRepository[Any, Any]](
+        self, repo_class: type[R]
+    ) -> R:
         """Return a typed entity repository sharing this session and factory."""
         if self._factory is None:
             raise RuntimeError("for_repo() requires an AsyncRepositoryFactory")
-        return self._factory.get_repository(repo_class)
+        return cast(R, self._factory.get_repository(repo_class))

{sqlphilosophy-0.1.4 → sqlphilosophy-0.1.8}/src/sqlphilosophy/sql.py

@@ -49,20 +49,10 @@ def sql_table(table_name: str, *column_names: str) -> SqlTable:
 
 def get_column_value(entity: object) -> ApiObject:
     """Return mapped column values for an ORM entity instance."""
-    instance_state = sa_inspect(entity, raiseerr=False)
-    if instance_state is not None and hasattr(instance_state, "mapper"):
-        mapper = instance_state.mapper
-    else:
-        from sqlphilosophy.sync.repository import BaseRepository
-
-        try:
-            insp = BaseRepository.inspect_model(type(entity))
-        except Exception as exc:
-            raise TypeError(f"{type(entity)!r} is not a mapped SQLAlchemy entity") from exc
-        if not hasattr(insp, "mapper"):
-            raise TypeError(f"{type(entity)!r} is not a mapped SQLAlchemy entity")
-        mapper = insp.mapper
-    return {attr.key: getattr(entity, attr.key) for attr in mapper.column_attrs}
+    insp = sa_inspect(type(entity), raiseerr=False)
+    if insp is None:
+        raise TypeError(f"{type(entity)!r} is not a mapped SQLAlchemy entity")
+    return {attr.key: getattr(entity, attr.key) for attr in insp.mapper.column_attrs}
 
 
 def row_mapping(row: object) -> RowMapping:

sqlphilosophy-0.1.8/src/sqlphilosophy/sync/protocols.py

@@ -0,0 +1,120 @@
+"""Portable repository factory and repository protocols (no Phobos or app imports)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from typing import Optional
+from typing import TYPE_CHECKING
+from typing import Protocol
+from typing import TypeVar
+
+if TYPE_CHECKING:
+    from sqlphilosophy.sync.repository import BaseRepository
+
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sync.query import StatementQueryBuilder
+from sqlphilosophy.types import IdList
+from sqlphilosophy.types import PrimaryKey
+from sqlphilosophy.types import RowMapping
+from sqlphilosophy.types import RowValue
+from sqlphilosophy.types import SqlFilter
+
+T = TypeVar("T", bound=DeclarativeBase)
+R = TypeVar("R", bound="BaseRepository[Any, Any]")
+
+
+class BaseRepositoryProtocol[T: DeclarativeBase, U: Optional[RepositoryFactory]](Protocol):
+    """Generic read/write surface shared by sqlphilosophy ``BaseRepository[T]``."""
+
+    model: type[T]
+    _session: Session
+    _factory: Optional[U]
+
+    def get(self, obj_id: PrimaryKey, load_relations: Any = None) -> T: ...
+
+    def get_by_id(self, obj_id: PrimaryKey, load_relations: Any = None) -> T | None: ...
+
+    def get_many(
+        self, ids: Sequence[PrimaryKey], load_relations: Any = None
+    ) -> Sequence[T]: ...
+
+    def first(self, load_relations: Any = None, **filters: RowValue) -> T | None: ...
+
+    def filter(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+        **filters: RowValue,
+    ) -> Sequence[T]: ...
+
+    def get_all(
+        self,
+        *,
+        page: int = 1,
+        limit: int | None = None,
+        load_relations: Any = None,
+    ) -> Sequence[T]: ...
+
+    def count(self, **filters: RowValue) -> int: ...
+
+    def exists(self, obj_id: PrimaryKey) -> bool: ...
+
+    def exists_where(self, **filters: RowValue) -> bool: ...
+
+    def statement(self) -> StatementQueryBuilder[T]: ...
+
+    def create(self, **fields: object) -> T: ...
+
+    def add(self, obj: T) -> T: ...
+
+    def get_or_create(
+        self, *, defaults: RowMapping | None = None, **lookup: RowValue
+    ) -> tuple[T, bool]: ...
+
+    def remove(self, obj_id: PrimaryKey) -> bool: ...
+
+    def delete_many(self, ids: IdList) -> int: ...
+
+    def delete_where(
+        self, *, criteria: Sequence[SqlFilter], params: RowMapping | None = None
+    ) -> int: ...
+
+    def update_partial(
+        self,
+        obj_id: PrimaryKey,
+        fields: RowMapping,
+        writable: frozenset[str],
+        *,
+        touch_updated_on: bool = False,
+    ) -> int: ...
+
+    def update_where(
+        self,
+        *,
+        criteria: Sequence[SqlFilter],
+        values: RowMapping,
+        params: RowMapping | None = None,
+    ) -> int: ...
+
+
+class RepositoryFactory(Protocol):
+    """Session-scoped factory for statement builders and entity repositories."""
+
+    def create_statement(self, model: type[T]) -> StatementQueryBuilder[T]:
+        """Return a fluent read builder for ``model``."""
+        ...
+
+    def get_repository(self, repo_class: type[R]) -> R:
+        """Return a cached typed entity repository."""
+        ...
+
+    def repository(
+        self, model: type[T]
+    ) -> BaseRepositoryProtocol[T, Optional[RepositoryFactory]]:
+        """Return generic CRUD helpers for ``model`` (``BaseRepository`` in Phobos)."""
+        ...

{sqlphilosophy-0.1.4 → sqlphilosophy-0.1.8}/src/sqlphilosophy/sync/repository.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 from typing import cast
+from typing import Optional
 from sqlalchemy import delete
 from sqlalchemy import func
 from sqlalchemy import inspect as sa_inspect
@@ -14,6 +15,7 @@ from sqlalchemy.orm import Session
 from sqlalchemy.orm.interfaces import LoaderOption
 from sqlphilosophy.sorting import ListQuery
 from sqlphilosophy.sorting import SortConfig
+from sqlphilosophy.sql import apply_mappings_page
 from sqlphilosophy.sql import delete_by_ids_model
 from sqlphilosophy.sql import partial_update_model
 from sqlphilosophy.sql import rows_mapping
@@ -32,7 +34,7 @@ from sqlphilosophy.types import cursor_rowcount
 LoadRelations = Sequence[LoaderOption]
 
 
-class BaseRepository[T: DeclarativeBase]:
+class BaseRepository[T: DeclarativeBase, U: Optional[RepositoryFactory]]:
     """Session-scoped CRUD helpers for a single mapped model."""
 
     def __init__(
@@ -42,7 +44,7 @@ class BaseRepository[T: DeclarativeBase]:
         factory: RepositoryFactory | None = None,
     ) -> None:
         self.model = model
-        self.session = session
+        self._session = session
         self._factory = factory
         pk_cols = self.inspect_model(model).primary_key
         if len(pk_cols) != 1:
@@ -60,7 +62,7 @@ class BaseRepository[T: DeclarativeBase]:
 
     def list_table_names(self) -> frozenset[str]:
         """Return visible table names on the session connection."""
-        return frozenset(sa_inspect(self.session.connection()).get_table_names())
+        return frozenset(sa_inspect(self._session.connection()).get_table_names())
 
     def has_table(self, table_name: str) -> bool:
         """True when ``table_name`` exists on the session connection."""
@@ -73,36 +75,36 @@ class BaseRepository[T: DeclarativeBase]:
 
     def _scalar_result(self, stmt: Any, *, unique: bool = False) -> Any:
         if unique:
-            return self.session.scalars(stmt).unique()
-        return self.session.scalars(stmt)
+            return self._session.scalars(stmt).unique()
+        return self._session.scalars(stmt)
 
     def fetch_statement_mappings(
         self, stmt: Any, params: RowMapping | None = None
     ) -> list[RowMapping]:
         """Execute ``stmt`` and return all rows as mappings."""
-        mapped = self.session.execute(stmt, params or {}).mappings()
+        mapped = self._session.execute(stmt, params or {}).mappings()
         rows = mapped.all() if hasattr(mapped, "all") else mapped
         return rows_mapping(rows)
 
     def scalar_count(self, stmt: SqlSelect, params: SqlBindParams | None = None) -> int:
         """Execute a scalar count/select statement and return ``int``."""
-        return int(self.session.execute(stmt, params or {}).scalar_one())
+        return int(self._session.execute(stmt, params or {}).scalar_one())
 
     def iter_mappings(self, stmt: SqlSelect, params: SqlBindParams | None = None):
         """Yield each result row as a plain ``dict``."""
-        for row in self.session.execute(stmt, params or {}).mappings():
+        for row in self._session.execute(stmt, params or {}).mappings():
             yield dict(row)
 
     def fetch_mapping_first(
         self, stmt: SqlSelect, params: SqlBindParams | None = None
     ) -> RowMapping | None:
         """Execute ``stmt`` and return the first row as a mapping, or ``None``."""
-        row = self.session.execute(stmt, params or {}).mappings().first()
+        row = self._session.execute(stmt, params or {}).mappings().first()
         return dict(row) if row is not None else None
 
     def fetch_mapping_one(self, stmt: SqlSelect, params: SqlBindParams | None = None) -> RowMapping:
         """Execute ``stmt`` and return exactly one row as a mapping."""
-        return dict(self.session.execute(stmt, params or {}).mappings().one())
+        return dict(self._session.execute(stmt, params or {}).mappings().one())
 
     def fetch_mappings_page(
         self,
@@ -113,11 +115,13 @@ class BaseRepository[T: DeclarativeBase]:
         params: RowMapping | None = None,
     ) -> list[RowMapping]:
         """Execute ``stmt`` with limit/offset; return normalized row mappings."""
-        if limit < 0:
-            raise ValueError("limit must be >= 0")
-        if offset < 0:
-            raise ValueError("offset must be >= 0")
-        return self.fetch_statement_mappings(stmt.limit(limit).offset(offset), params)
+        return apply_mappings_page(
+            self._session,
+            stmt,
+            limit=limit,
+            offset=offset,
+            params=params,
+        )
 
     def fetch_sorted_mappings(
         self,
@@ -143,7 +147,7 @@ class BaseRepository[T: DeclarativeBase]:
         """Fetch a single record by primary key with optional eager loading."""
         stmt = select(self.model).where(self._pk_column == obj_id)
         stmt = self._apply_load_relations(stmt, load_relations)
-        return self.session.scalar(stmt)
+        return self._session.scalar(stmt)
 
     def exists(self, obj_id: PrimaryKey) -> bool:
         """True when a row exists for the primary key."""
@@ -158,13 +162,13 @@ class BaseRepository[T: DeclarativeBase]:
         stmt = select(func.count()).select_from(self.model)
         if filters:
             stmt = stmt.filter_by(**filters)
-        return int(self.session.scalar(stmt) or 0)
+        return int(self._session.scalar(stmt) or 0)
 
     def first(self, load_relations: LoadRelations | None = None, **filters: RowValue) -> T | None:
         """Return the first row matching filters, with optional eager loading."""
         stmt = select(self.model).filter_by(**filters).limit(1)
         stmt = self._apply_load_relations(stmt, load_relations)
-        return self.session.scalar(stmt)
+        return self._session.scalar(stmt)
 
     def get(self, obj_id: PrimaryKey, load_relations: LoadRelations | None = None) -> T:
         """Fetch a single record by primary key; raise if missing."""
@@ -234,7 +238,7 @@ class BaseRepository[T: DeclarativeBase]:
             stmt = stmt.join(target_model)  # pragma: no cover
         if filter_expressions:
             stmt = stmt.where(*filter_expressions)
-        return cast(Sequence[tuple[T, Any]], self.session.execute(stmt).all())
+        return cast(Sequence[tuple[T, Any]], self._session.execute(stmt).all())
 
     def create(self, **fields: object) -> T:
         """Construct, stage, and flush a new instance."""
@@ -255,8 +259,8 @@ class BaseRepository[T: DeclarativeBase]:
 
     def add(self, obj: T) -> T:
         """Stage a new instance; caller commits in the orchestration layer."""
-        self.session.add(obj)
-        self.session.flush()
+        self._session.add(obj)
+        self._session.flush()
         return obj
 
     def update_partial(
@@ -269,7 +273,7 @@ class BaseRepository[T: DeclarativeBase]:
     ) -> int:
         """Apply a partial update; returns affected row count (0 if none)."""
         return partial_update_model(
-            self.session,
+            self._session,
             self.model,
             obj_id,
             fields,
@@ -288,7 +292,7 @@ class BaseRepository[T: DeclarativeBase]:
         if not values:
             return 0
         stmt = update(self.model).where(*criteria).values(**values)
-        result = self.session.execute(stmt, params or {})
+        result = self._session.execute(stmt, params or {})
         return cursor_rowcount(result)
 
     def delete_where(
@@ -311,16 +315,16 @@ class BaseRepository[T: DeclarativeBase]:
     def remove(self, obj_id: PrimaryKey) -> bool:
         """Delete a record by primary key."""
         statement = delete(self.model).where(self._pk_column == obj_id)
-        result = self.session.execute(statement)
+        result = self._session.execute(statement)
         return cursor_rowcount(result) > 0
 
     def delete_many(self, ids: IdList) -> int:
         """Delete multiple records by primary key."""
-        return delete_by_ids_model(self.session, self.model, list(ids))
+        return delete_by_ids_model(self._session, self.model, list(ids))
 
     def delete_all(self) -> int:
         """Delete every row for this model. Dev/ops only — prefer ``delete_where`` in app code."""
-        result = self.session.execute(delete(self.model))
+        result = self._session.execute(delete(self.model))
         return cursor_rowcount(result)
 
     def batched_purge_ids(
@@ -345,17 +349,19 @@ class BaseRepository[T: DeclarativeBase]:
             if not ids:
                 break
             total += self.delete_many(ids)
-            self.session.commit()
+            self._session.commit()
         return total
 
     def statement(self) -> StatementQueryBuilder[T]:
         """Return a fluent statement builder for reads on this model (default read path)."""
         if self._factory is not None:
             return self._factory.create_statement(self.model)
-        return SqlAlchemyStatementBuilder(self.session, self.model)
+        return SqlAlchemyStatementBuilder(self._session, self.model)
 
-    def for_repo[R](self, repo_class: type[R]) -> R:
+    def for_repo[R: BaseRepository[Any, Any]](
+        self, repo_class: type[R]
+    ) -> R:
         """Return a typed entity repository sharing this session and factory."""
         if self._factory is None:
             raise RuntimeError("for_repo() requires a RepositoryFactory")
-        return self._factory.get_repository(repo_class)
+        return cast(R, self._factory.get_repository(repo_class))

{sqlphilosophy-0.1.4 → sqlphilosophy-0.1.8/src/sqlphilosophy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlphilosophy
-Version: 0.1.4
+Version: 0.1.8
 Summary: Portable SQLAlchemy repository kit: sync and async CRUD, statement builders, sort/pagination, and SQL helpers.
 Author-email: Josh Martin <denverprogrammer@gmail.com>
 License-Expression: MIT
@@ -111,6 +111,43 @@ with SessionLocal() as session:
 
 **Async:** swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
 
+## Strongly typed repositories (factory pattern)
+
+Domain repositories subclass `BaseRepository[Model, RepositoryFactory]` (or `AsyncBaseRepository` for async) and add typed query helpers. A session-scoped factory implements `RepositoryFactory` to cache repositories and wire `statement()` / `for_repo()` across repos on the same session.
+
+```python
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sync.protocols import RepositoryFactory
+from sqlphilosophy.sync.repository import BaseRepository
+
+
+class UserRepository(BaseRepository[User, RepositoryFactory]):
+    def __init__(self, session: Session, factory: RepositoryFactory) -> None:
+        super().__init__(User, session, factory)
+
+    def get_by_username(self, username: str) -> User | None:
+        return self.first(username=username)
+
+    def get_by_email(self, email: str) -> User | None:
+        return self.first(email=email)
+
+    def get_active_by_email(self, email: str) -> User | None:
+        return (
+            self.statement()
+            .where(User.email == email, User.is_active.is_(True))
+            .scalars()
+            .first()
+        )
+```
+
+Full runnable examples with models, a multi-repo factory, and cross-repository usage:
+
+- Sync: [`examples/typed_repository_sync.py`](./examples/typed_repository_sync.py)
+- Async: [`examples/typed_repository_async.py`](./examples/typed_repository_async.py)
+
+For async, swap `Session` → `AsyncSession`, `BaseRepository` → `AsyncBaseRepository` from `sqlphilosophy.aio.repository`, and `await` repository methods.
+
 ## Package layout
 
 | Module | Contents |

sqlphilosophy-0.1.4/src/sqlphilosophy/VERSION

@@ -1 +0,0 @@
-0.1.4

sqlphilosophy-0.1.4/src/sqlphilosophy/aio/protocols.py

@@ -1,26 +0,0 @@
-"""Portable async repository factory protocol (no Phobos or app imports)."""
-
-from __future__ import annotations
-from typing import Protocol
-from typing import TypeVar
-from sqlalchemy.orm import DeclarativeBase
-from sqlphilosophy.aio.query import AsyncStatementQueryBuilder
-
-T = TypeVar("T", bound=DeclarativeBase)
-R = TypeVar("R")
-
-
-class AsyncRepositoryFactory(Protocol):
-    """Session-scoped factory for async statement builders and entity repositories."""
-
-    def create_statement(self, model: type[T]) -> AsyncStatementQueryBuilder[T]:
-        """Return a fluent async read builder for ``model``."""
-        ...
-
-    def get_repository(self, repo_class: type[R]) -> R:
-        """Return a cached typed entity repository."""
-        ...
-
-    def repository(self, model: type[T]) -> object:
-        """Return generic CRUD helpers for ``model`` (``AsyncBaseRepository`` in Phobos)."""
-        ...

sqlphilosophy-0.1.4/src/sqlphilosophy/sync/protocols.py

@@ -1,26 +0,0 @@
-"""Portable repository factory protocol (no Phobos or app imports)."""
-
-from __future__ import annotations
-from typing import Protocol
-from typing import TypeVar
-from sqlalchemy.orm import DeclarativeBase
-from sqlphilosophy.sync.query import StatementQueryBuilder
-
-T = TypeVar("T", bound=DeclarativeBase)
-R = TypeVar("R")
-
-
-class RepositoryFactory(Protocol):
-    """Session-scoped factory for statement builders and entity repositories."""
-
-    def create_statement(self, model: type[T]) -> StatementQueryBuilder[T]:
-        """Return a fluent read builder for ``model``."""
-        ...
-
-    def get_repository(self, repo_class: type[R]) -> R:
-        """Return a cached typed entity repository."""
-        ...
-
-    def repository(self, model: type[T]) -> object:
-        """Return generic CRUD helpers for ``model`` (``BaseRepository`` in Phobos)."""
-        ...