sqlphilosophy 0.3.0__tar.gz → 0.3.4__tar.gz

{sqlphilosophy-0.3.0/src/sqlphilosophy.egg-info → sqlphilosophy-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlphilosophy
-Version: 0.3.0
+Version: 0.3.4
 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
@@ -20,7 +20,7 @@ Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: servicephilosophy>=0.1.0
+Requires-Dist: servicephilosophy<0.2,>=0.1.2
 Requires-Dist: sqlalchemy<3,>=2.0
 Provides-Extra: async
 Requires-Dist: greenlet>=3.0; extra == "async"
@@ -30,7 +30,7 @@ Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: pytest-cov>=6; extra == "dev"
 Requires-Dist: aiosqlite>=0.20; extra == "dev"
 Requires-Dist: greenlet>=3.0; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: build<2,>=1.6.1; extra == "dev"
 Requires-Dist: twine>=5; extra == "dev"
 Requires-Dist: ruff>=0.15; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
@@ -40,6 +40,8 @@ Dynamic: license-file
 
 # sqlphilosophy
 
+Current source and planned customer-subdomain impact: [current-state summary](docs/current-state-summary.md).
+
 Portable SQLAlchemy repository kit: sync and async CRUD, fluent statement builders, sort/pagination, Core SQL helpers, and optional audit listeners.
 
 | | |
@@ -180,3 +182,21 @@ See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing. See [CH
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Expression lookups and scope overrides (0.3+)
+
+Both repository bases provide `find_entity(criteria=..., lock=False)`, `find_row(criteria=..., columns=..., lock=False)` and `count_scoped(criteria=...)`. Criteria must not be empty; projected lookups also require columns. Entity lookups return a mapped object, projected lookups return RowMapping, and absence returns None. These methods never commit.
+
+Override `apply_scope(statement)` for additional predicates on these helpers. It runs after projection initialization, because `select_columns`/`select_entity` reset the builder's SELECT. This hook does not implicitly scope existing CRUD helpers or arbitrary builder calls: keep ownership checks in named application repository methods. Existing `first`, `get_by_id`, `count` and statement APIs remain available and unchanged.
+
+Published 0.3.3 provides these lookup APIs. The 0.3.4 source prepares compatible
+strict-decoder, documentation and build-metadata fixes. Use a named application
+repository method to own each model-specific projection, ordering and policy;
+compose its query with `statement()` or these lookup helpers instead of
+scattering `select()` calls through controllers/services. Core SQL helpers remain
+available for explicit SQL boundaries; a repository does not supply authorization.
+
+The supported dependency range remains SQLAlchemy 2.x. DeliveryPlus native's
+2.0.49 constraint and RuleAtlas's separate 2.1.5 minimum are host decisions;
+upgrading this package does not silently change either host lock. Coordinated
+candidate verification exercises both SQLAlchemy versions before release.

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/README.md

@@ -1,5 +1,7 @@
 # sqlphilosophy
 
+Current source and planned customer-subdomain impact: [current-state summary](docs/current-state-summary.md).
+
 Portable SQLAlchemy repository kit: sync and async CRUD, fluent statement builders, sort/pagination, Core SQL helpers, and optional audit listeners.
 
 | | |
@@ -140,3 +142,21 @@ See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing. See [CH
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Expression lookups and scope overrides (0.3+)
+
+Both repository bases provide `find_entity(criteria=..., lock=False)`, `find_row(criteria=..., columns=..., lock=False)` and `count_scoped(criteria=...)`. Criteria must not be empty; projected lookups also require columns. Entity lookups return a mapped object, projected lookups return RowMapping, and absence returns None. These methods never commit.
+
+Override `apply_scope(statement)` for additional predicates on these helpers. It runs after projection initialization, because `select_columns`/`select_entity` reset the builder's SELECT. This hook does not implicitly scope existing CRUD helpers or arbitrary builder calls: keep ownership checks in named application repository methods. Existing `first`, `get_by_id`, `count` and statement APIs remain available and unchanged.
+
+Published 0.3.3 provides these lookup APIs. The 0.3.4 source prepares compatible
+strict-decoder, documentation and build-metadata fixes. Use a named application
+repository method to own each model-specific projection, ordering and policy;
+compose its query with `statement()` or these lookup helpers instead of
+scattering `select()` calls through controllers/services. Core SQL helpers remain
+available for explicit SQL boundaries; a repository does not supply authorization.
+
+The supported dependency range remains SQLAlchemy 2.x. DeliveryPlus native's
+2.0.49 constraint and RuleAtlas's separate 2.1.5 minimum are host decisions;
+upgrading this package does not silently change either host lock. Coordinated
+candidate verification exercises both SQLAlchemy versions before release.

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+requires = ["setuptools>=84.2.1,<85", "wheel>=0.46,<1"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -24,7 +24,7 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
-    "servicephilosophy>=0.1.0",
+    "servicephilosophy>=0.1.2,<0.2",
     "sqlalchemy>=2.0,<3",
 ]
 
@@ -38,7 +38,7 @@ dev = [
     "pytest-cov>=6",
     "aiosqlite>=0.20",
     "greenlet>=3.0",
-    "build>=1.2",
+    "build>=1.6.1,<2",
     "twine>=5",
     "ruff>=0.15",
     "mypy>=1.11",
@@ -81,7 +81,6 @@ exclude_also = [
 
 [tool.mypy]
 python_version = "3.12"
-plugins = ["sqlalchemy.ext.mypy.plugin"]
 warn_unused_ignores = true
 
 [tool.ruff]

sqlphilosophy-0.3.4/src/sqlphilosophy/VERSION

@@ -0,0 +1 @@
+0.3.4

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy/_repository_shared.py

@@ -8,6 +8,7 @@ from typing import Any, Literal, cast
 
 from sqlalchemy import func
 from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.sql import SQLColumnExpression
 
 from sqlphilosophy.audit.model import AuditMixin
 from sqlphilosophy.types import PrimaryKey, RowMapping, RowValue, SqlFilter
@@ -112,3 +113,13 @@ def criteria_delete_allowed(criteria: Sequence[SqlFilter]) -> bool:
 def bulk_update_allowed(values: RowMapping) -> bool:
     """True when ``update_where`` has values to apply."""
     return bool(values)
+
+
+def require_lookup_inputs(
+    criteria: Sequence[SqlFilter], columns: Sequence[SQLColumnExpression[object]] | None = None
+) -> None:
+    """Reject accidental unscoped or empty-projection expression lookups."""
+    if not criteria:
+        raise ValueError("lookup criteria must not be empty")
+    if columns is not None and not columns:
+        raise ValueError("lookup projection must not be empty")

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy/aio/repository.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import Any, cast
+from typing import Any, SupportsInt, cast
 
 from servicephilosophy import ServiceRepository
 from sqlalchemy import delete, func, select, update
@@ -11,6 +11,7 @@ from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase
 from sqlalchemy.orm.interfaces import LoaderOption
+from sqlalchemy.sql import SQLColumnExpression
 
 from sqlphilosophy._repository_shared import (
     bulk_update_allowed,
@@ -19,6 +20,7 @@ from sqlphilosophy._repository_shared import (
     lookup_not_found_message,
     plan_partial_update,
     require_batch_size,
+    require_lookup_inputs,
     require_mappings_page_limits,
     require_page_and_limit,
     require_single_column_primary_key,
@@ -55,6 +57,11 @@ class AsyncBaseRepository[T: DeclarativeBase, U: AsyncRepositoryFactory](Service
         self._session = session
         self._pk_column = require_single_column_primary_key(model, self.inspect_model(model))
 
+    @property
+    def session(self) -> AsyncSession:
+        """Caller-owned session; exposed for composition ownership checks."""
+        return self._session
+
     @classmethod
     def inspect_model(cls, model: type[DeclarativeBase]) -> Any:
         """Return SQLAlchemy ORM mapper inspection for ``model``."""
@@ -101,7 +108,7 @@ class AsyncBaseRepository[T: DeclarativeBase, U: AsyncRepositoryFactory](Service
     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 {})
-        return int(result.scalar_one())
+        return int(cast("SupportsInt", result.scalar_one()))
 
     async def iter_mappings(self, stmt: SqlSelect, params: SqlBindParams | None = None):
         """Yield each result row as a plain ``dict``."""
@@ -308,20 +315,20 @@ class AsyncBaseRepository[T: DeclarativeBase, U: AsyncRepositoryFactory](Service
         *,
         criteria: Sequence[SqlFilter],
         values: RowMapping,
-        params: SqlBindParams | None = None,
+        params: RowMapping | None = None,
     ) -> int:
         """Bulk UPDATE rows matching ``criteria``; returns affected row count."""
         if not bulk_update_allowed(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, dict(params) if params is not None else {})
         return cursor_rowcount(result)
 
     async def delete_where(
         self,
         *,
         criteria: Sequence[SqlFilter],
-        params: SqlBindParams | None = None,
+        params: RowMapping | None = None,
     ) -> int:
         """Delete rows matching ``criteria`` via PK lookup + ``delete_many``."""
         if not criteria_delete_allowed(criteria):
@@ -329,7 +336,7 @@ class AsyncBaseRepository[T: DeclarativeBase, U: AsyncRepositoryFactory](Service
         pk_key = self._pk_column.key
         builder = self.statement().select_columns(self._pk_column).where(*criteria)
         if params:
-            builder = builder.with_params(params)
+            builder = builder.with_params(dict(params))
         rows = await builder.mappings().all()
         ids = extract_primary_keys(rows, pk_key)
         return await self.delete_many(ids)
@@ -374,6 +381,34 @@ class AsyncBaseRepository[T: DeclarativeBase, U: AsyncRepositoryFactory](Service
             await self._session.commit()
         return total
 
+    def apply_scope(self, statement: AsyncStatementQueryBuilder[T]) -> AsyncStatementQueryBuilder[T]:
+        """Host override hook, invoked after projection initialization."""
+        return statement
+
+    async def find_entity(self, *, criteria: Sequence[SqlFilter], lock: bool = False) -> T | None:
+        require_lookup_inputs(criteria)
+        query = self.apply_scope(self.statement()).where(*criteria)
+        if lock:
+            query = query.with_for_update()
+        return await query.scalars().first()
+
+    async def find_row(
+        self,
+        *,
+        criteria: Sequence[SqlFilter],
+        columns: Sequence[SQLColumnExpression[object]],
+        lock: bool = False,
+    ) -> RowMapping | None:
+        require_lookup_inputs(criteria, columns)
+        query = self.apply_scope(self.statement().select_columns(*columns)).where(*criteria)
+        if lock:
+            query = query.with_for_update()
+        return await query.mappings().first()
+
+    async def count_scoped(self, *, criteria: Sequence[SqlFilter]) -> int:
+        require_lookup_inputs(criteria)
+        return await self.apply_scope(self.statement().select_entity()).where(*criteria).count()
+
     def statement(self) -> AsyncStatementQueryBuilder[T]:
         """Return a fluent statement builder for reads on this model (default read path)."""
         factory = self.maybe_factory

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy/strict.py

@@ -6,7 +6,7 @@ from collections.abc import Callable, Mapping
 from datetime import date, datetime
 from enum import Enum
 from math import isfinite
-from typing import TypeGuard
+from typing import TypeGuard, cast
 from uuid import UUID
 
 from sqlphilosophy.types import JSONValue
@@ -99,9 +99,21 @@ def strict_row_enum[EnumT: Enum](row: Row, key: str, enum_type: type[EnumT]) ->
     raise _type_error(key, enum_type.__name__, value)
 
 
+def _plain_list(value: object) -> list[object] | None:
+    if type(value) is not list:
+        return None
+    # Exact built-in type proof preserves identity without inspecting __class__.
+    return cast(list[object], value)
+
+
+def _is_str_list(value: object) -> TypeGuard[list[str]]:
+    items = _plain_list(value)
+    return items is not None and all(type(item) is str for item in items)
+
+
 def strict_row_str_list(row: Row, key: str) -> list[str]:
     value = _required(row, key)
-    if type(value) is not list or not all(type(item) is str for item in value):
+    if not _is_str_list(value):
         raise _type_error(key, "list[str]", value)
     return value
 
@@ -111,8 +123,9 @@ def is_strict_json_value(value: object) -> TypeGuard[JSONValue]:
         return True
     if type(value) is float:
         return isfinite(value)
-    if type(value) is list:
-        return all(is_strict_json_value(item) for item in value)
+    items = _plain_list(value)
+    if items is not None:
+        return all(is_strict_json_value(item) for item in items)
     if type(value) is dict:
         return all(type(key) is str and is_strict_json_value(item) for key, item in value.items())
     return False

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy/sync/repository.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import Any, cast
+from typing import Any, SupportsInt, cast
 
 from servicephilosophy import ServiceRepository
 from sqlalchemy import delete, func, select, update
 from sqlalchemy import inspect as sa_inspect
 from sqlalchemy.orm import DeclarativeBase, Session
 from sqlalchemy.orm.interfaces import LoaderOption
+from sqlalchemy.sql import SQLColumnExpression
 
 from sqlphilosophy._repository_shared import (
     bulk_update_allowed,
@@ -17,6 +18,7 @@ from sqlphilosophy._repository_shared import (
     extract_primary_keys,
     lookup_not_found_message,
     require_batch_size,
+    require_lookup_inputs,
     require_page_and_limit,
     require_single_column_primary_key,
 )
@@ -52,6 +54,11 @@ class BaseRepository[T: DeclarativeBase, U: RepositoryFactory](ServiceRepository
         self._session = session
         self._pk_column = require_single_column_primary_key(model, self.inspect_model(model))
 
+    @property
+    def session(self) -> Session:
+        """Caller-owned session; exposed for composition ownership checks."""
+        return self._session
+
     @classmethod
     def inspect_model(cls, model: type[DeclarativeBase]) -> Any:
         """Return SQLAlchemy ORM mapper inspection for ``model``."""
@@ -87,7 +94,7 @@ class BaseRepository[T: DeclarativeBase, U: RepositoryFactory](ServiceRepository
 
     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(cast("SupportsInt", 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``."""
@@ -274,20 +281,20 @@ class BaseRepository[T: DeclarativeBase, U: RepositoryFactory](ServiceRepository
         *,
         criteria: Sequence[SqlFilter],
         values: RowMapping,
-        params: SqlBindParams | None = None,
+        params: RowMapping | None = None,
     ) -> int:
         """Bulk UPDATE rows matching ``criteria``; returns affected row count."""
         if not bulk_update_allowed(values):
             return 0
         stmt = update(self.model).where(*criteria).values(**values)
-        result = self._session.execute(stmt, params or {})
+        result = self._session.execute(stmt, dict(params) if params is not None else {})
         return cursor_rowcount(result)
 
     def delete_where(
         self,
         *,
         criteria: Sequence[SqlFilter],
-        params: SqlBindParams | None = None,
+        params: RowMapping | None = None,
     ) -> int:
         """Delete rows matching ``criteria`` via PK lookup + ``delete_many``."""
         if not criteria_delete_allowed(criteria):
@@ -295,7 +302,7 @@ class BaseRepository[T: DeclarativeBase, U: RepositoryFactory](ServiceRepository
         pk_key = self._pk_column.key
         builder = self.statement().select_columns(self._pk_column).where(*criteria)
         if params:
-            builder = builder.with_params(params)
+            builder = builder.with_params(dict(params))
         rows = builder.mappings().all()
         ids = extract_primary_keys(rows, pk_key)
         return self.delete_many(ids)
@@ -334,6 +341,34 @@ class BaseRepository[T: DeclarativeBase, U: RepositoryFactory](ServiceRepository
             self._session.commit()
         return total
 
+    def apply_scope(self, statement: StatementQueryBuilder[T]) -> StatementQueryBuilder[T]:
+        """Host override hook, invoked after projection initialization."""
+        return statement
+
+    def find_entity(self, *, criteria: Sequence[SqlFilter], lock: bool = False) -> T | None:
+        require_lookup_inputs(criteria)
+        query = self.apply_scope(self.statement()).where(*criteria)
+        if lock:
+            query = query.with_for_update()
+        return query.scalars().first()
+
+    def find_row(
+        self,
+        *,
+        criteria: Sequence[SqlFilter],
+        columns: Sequence[SQLColumnExpression[object]],
+        lock: bool = False,
+    ) -> RowMapping | None:
+        require_lookup_inputs(criteria, columns)
+        query = self.apply_scope(self.statement().select_columns(*columns)).where(*criteria)
+        if lock:
+            query = query.with_for_update()
+        return query.mappings().first()
+
+    def count_scoped(self, *, criteria: Sequence[SqlFilter]) -> int:
+        require_lookup_inputs(criteria)
+        return self.apply_scope(self.statement().select_entity()).where(*criteria).count()
+
     def statement(self) -> StatementQueryBuilder[T]:
         """Return a fluent statement builder for reads on this model (default read path)."""
         factory = self.maybe_factory

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy/types.py

@@ -65,4 +65,4 @@ type OrmModel = type[DeclarativeBase]
 
 def cursor_rowcount(result: Result[Any]) -> int:
     """Return affected row count from a DML ``execute`` result."""
-    return int(cast(CursorResult[Any], result).rowcount or 0)
+    return int(cast("CursorResult[Any]", result).rowcount or 0)

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4/src/sqlphilosophy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlphilosophy
-Version: 0.3.0
+Version: 0.3.4
 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
@@ -20,7 +20,7 @@ Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: servicephilosophy>=0.1.0
+Requires-Dist: servicephilosophy<0.2,>=0.1.2
 Requires-Dist: sqlalchemy<3,>=2.0
 Provides-Extra: async
 Requires-Dist: greenlet>=3.0; extra == "async"
@@ -30,7 +30,7 @@ Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: pytest-cov>=6; extra == "dev"
 Requires-Dist: aiosqlite>=0.20; extra == "dev"
 Requires-Dist: greenlet>=3.0; extra == "dev"
-Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: build<2,>=1.6.1; extra == "dev"
 Requires-Dist: twine>=5; extra == "dev"
 Requires-Dist: ruff>=0.15; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
@@ -40,6 +40,8 @@ Dynamic: license-file
 
 # sqlphilosophy
 
+Current source and planned customer-subdomain impact: [current-state summary](docs/current-state-summary.md).
+
 Portable SQLAlchemy repository kit: sync and async CRUD, fluent statement builders, sort/pagination, Core SQL helpers, and optional audit listeners.
 
 | | |
@@ -180,3 +182,21 @@ See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing. See [CH
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## Expression lookups and scope overrides (0.3+)
+
+Both repository bases provide `find_entity(criteria=..., lock=False)`, `find_row(criteria=..., columns=..., lock=False)` and `count_scoped(criteria=...)`. Criteria must not be empty; projected lookups also require columns. Entity lookups return a mapped object, projected lookups return RowMapping, and absence returns None. These methods never commit.
+
+Override `apply_scope(statement)` for additional predicates on these helpers. It runs after projection initialization, because `select_columns`/`select_entity` reset the builder's SELECT. This hook does not implicitly scope existing CRUD helpers or arbitrary builder calls: keep ownership checks in named application repository methods. Existing `first`, `get_by_id`, `count` and statement APIs remain available and unchanged.
+
+Published 0.3.3 provides these lookup APIs. The 0.3.4 source prepares compatible
+strict-decoder, documentation and build-metadata fixes. Use a named application
+repository method to own each model-specific projection, ordering and policy;
+compose its query with `statement()` or these lookup helpers instead of
+scattering `select()` calls through controllers/services. Core SQL helpers remain
+available for explicit SQL boundaries; a repository does not supply authorization.
+
+The supported dependency range remains SQLAlchemy 2.x. DeliveryPlus native's
+2.0.49 constraint and RuleAtlas's separate 2.1.5 minimum are host decisions;
+upgrading this package does not silently change either host lock. Coordinated
+candidate verification exercises both SQLAlchemy versions before release.

{sqlphilosophy-0.3.0 → sqlphilosophy-0.3.4}/src/sqlphilosophy.egg-info/requires.txt

@@ -1,4 +1,4 @@
-servicephilosophy>=0.1.0
+servicephilosophy<0.2,>=0.1.2
 sqlalchemy<3,>=2.0
 
 [async]
@@ -10,7 +10,7 @@ pytest-asyncio>=0.24
 pytest-cov>=6
 aiosqlite>=0.20
 greenlet>=3.0
-build>=1.2
+build<2,>=1.6.1
 twine>=5
 ruff>=0.15
 mypy>=1.11

sqlphilosophy-0.3.0/src/sqlphilosophy/VERSION

@@ -1 +0,0 @@
-0.3.0