sqlphilosophy 0.1.0__tar.gz

sqlphilosophy-0.1.0/LICENSE

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

sqlphilosophy-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: sqlphilosophy
+Version: 0.1.0
+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
+Project-URL: Homepage, https://github.com/SignalSafeSoftware/sqlphilosophy
+Project-URL: Repository, https://github.com/SignalSafeSoftware/sqlphilosophy
+Project-URL: Documentation, https://github.com/SignalSafeSoftware/sqlphilosophy#readme
+Project-URL: Issues, https://github.com/SignalSafeSoftware/sqlphilosophy/issues
+Project-URL: Changelog, https://github.com/SignalSafeSoftware/sqlphilosophy/blob/main/CHANGELOG.md
+Keywords: sqlalchemy,repository-pattern,repository,orm,database,pagination,audit,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: async
+Requires-Dist: greenlet>=3.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5; 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: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# sqlphilosophy
+
+Portable SQLAlchemy repository kit for typed CRUD, fluent statement building, sort/pagination, and Core SQL helpers — with explicit sync and async session APIs.
+
+| | |
+|---|---|
+| **PyPI** | [`sqlphilosophy`](https://pypi.org/project/sqlphilosophy/) |
+| **GitHub** | [SignalSafeSoftware/sqlphilosophy](https://github.com/SignalSafeSoftware/sqlphilosophy) |
+| **Import** | `sqlphilosophy` (no root reexports — use explicit submodules below) |
+
+Developed in the [DeliveryPlus](https://github.com/SignalSafeSoftware/DeliveryPlus) monorepo under `libs/sqlphilosophy`; this tree is the publishable package source.
+
+## Install
+
+```bash
+pip install sqlphilosophy
+```
+
+Async ORM (`AsyncSession`) also needs greenlet:
+
+```bash
+pip install sqlphilosophy[async]
+```
+
+Requires Python 3.12+ and SQLAlchemy 2.x.
+
+## Package layout
+
+| Module | Contents |
+|--------|----------|
+| `sqlphilosophy.types` | Portable typing aliases (`RowMapping`, `PrimaryKey`, `SqlFilter`, …) |
+| `sqlphilosophy.sql` | Row mapping helpers, partial updates, Core table helpers, filter builders |
+| `sqlphilosophy.sorting` | `ListQuery`, `SortConfig`, `SortSpec`, pagination/sort resolution |
+| `sqlphilosophy.sync` | Sync `BaseRepository`, `StatementQueryBuilder`, `RepositoryFactory` protocol |
+| `sqlphilosophy.aio` | Async `AsyncBaseRepository`, `AsyncStatementQueryBuilder`, `AsyncRepositoryFactory` |
+| `sqlphilosophy.audit` | Optional SQLAlchemy audit listeners and timestamp mixins |
+
+## Sync usage
+
+```python
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sorting import ListQuery, SortConfig, SortSpec
+from sqlphilosophy.sql import partial_update_model, row_int
+from sqlphilosophy.sync.protocols import RepositoryFactory
+from sqlphilosophy.sync.repository import BaseRepository
+from sqlphilosophy.sync.query import SqlAlchemyStatementBuilder
+
+# Without a factory — statement() returns SqlAlchemyStatementBuilder directly
+repo = BaseRepository(User, session)
+rows = repo.statement().where(User.active.is_(True)).mappings().all()
+
+# With a factory — statement() and for_repo() delegate to the factory
+repo = BaseRepository(User, session, factory)
+page = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
+other = repo.for_repo(OrderRepository)
+```
+
+## Async usage
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sqlphilosophy.aio.repository import AsyncBaseRepository
+
+repo = AsyncBaseRepository(User, session)
+rows = await repo.statement().where(User.active.is_(True)).mappings().all()
+```
+
+## Audit mixins
+
+```python
+from sqlphilosophy.audit.context import audit_context
+from sqlphilosophy.audit.listener import configure_audit_listeners
+from sqlphilosophy.audit.model import TimestampModel
+
+configure_audit_listeners()
+
+with audit_context(actor_id=42):
+    session.add(MyModel(name="example"))
+    session.flush()
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+## Releasing
+
+See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

sqlphilosophy-0.1.0/README.md

@@ -0,0 +1,99 @@
+# sqlphilosophy
+
+Portable SQLAlchemy repository kit for typed CRUD, fluent statement building, sort/pagination, and Core SQL helpers — with explicit sync and async session APIs.
+
+| | |
+|---|---|
+| **PyPI** | [`sqlphilosophy`](https://pypi.org/project/sqlphilosophy/) |
+| **GitHub** | [SignalSafeSoftware/sqlphilosophy](https://github.com/SignalSafeSoftware/sqlphilosophy) |
+| **Import** | `sqlphilosophy` (no root reexports — use explicit submodules below) |
+
+Developed in the [DeliveryPlus](https://github.com/SignalSafeSoftware/DeliveryPlus) monorepo under `libs/sqlphilosophy`; this tree is the publishable package source.
+
+## Install
+
+```bash
+pip install sqlphilosophy
+```
+
+Async ORM (`AsyncSession`) also needs greenlet:
+
+```bash
+pip install sqlphilosophy[async]
+```
+
+Requires Python 3.12+ and SQLAlchemy 2.x.
+
+## Package layout
+
+| Module | Contents |
+|--------|----------|
+| `sqlphilosophy.types` | Portable typing aliases (`RowMapping`, `PrimaryKey`, `SqlFilter`, …) |
+| `sqlphilosophy.sql` | Row mapping helpers, partial updates, Core table helpers, filter builders |
+| `sqlphilosophy.sorting` | `ListQuery`, `SortConfig`, `SortSpec`, pagination/sort resolution |
+| `sqlphilosophy.sync` | Sync `BaseRepository`, `StatementQueryBuilder`, `RepositoryFactory` protocol |
+| `sqlphilosophy.aio` | Async `AsyncBaseRepository`, `AsyncStatementQueryBuilder`, `AsyncRepositoryFactory` |
+| `sqlphilosophy.audit` | Optional SQLAlchemy audit listeners and timestamp mixins |
+
+## Sync usage
+
+```python
+from sqlalchemy.orm import Session
+
+from sqlphilosophy.sorting import ListQuery, SortConfig, SortSpec
+from sqlphilosophy.sql import partial_update_model, row_int
+from sqlphilosophy.sync.protocols import RepositoryFactory
+from sqlphilosophy.sync.repository import BaseRepository
+from sqlphilosophy.sync.query import SqlAlchemyStatementBuilder
+
+# Without a factory — statement() returns SqlAlchemyStatementBuilder directly
+repo = BaseRepository(User, session)
+rows = repo.statement().where(User.active.is_(True)).mappings().all()
+
+# With a factory — statement() and for_repo() delegate to the factory
+repo = BaseRepository(User, session, factory)
+page = repo.statement().fetch_page(ListQuery.from_page(page=1, size=20))
+other = repo.for_repo(OrderRepository)
+```
+
+## Async usage
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sqlphilosophy.aio.repository import AsyncBaseRepository
+
+repo = AsyncBaseRepository(User, session)
+rows = await repo.statement().where(User.active.is_(True)).mappings().all()
+```
+
+## Audit mixins
+
+```python
+from sqlphilosophy.audit.context import audit_context
+from sqlphilosophy.audit.listener import configure_audit_listeners
+from sqlphilosophy.audit.model import TimestampModel
+
+configure_audit_listeners()
+
+with audit_context(actor_id=42):
+    session.add(MyModel(name="example"))
+    session.flush()
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+## Releasing
+
+See [RELEASING.md](./RELEASING.md) for GitHub + PyPI trusted publishing.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

sqlphilosophy-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlphilosophy"
+description = "Portable SQLAlchemy repository kit: sync and async CRUD, statement builders, sort/pagination, and SQL helpers."
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Josh Martin", email = "denverprogrammer@gmail.com" }
+]
+keywords = ["sqlalchemy", "repository-pattern", "repository", "orm", "database", "pagination", "audit", "async"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dynamic = ["version"]
+dependencies = [
+    "sqlalchemy>=2.0,<3",
+]
+
+[project.optional-dependencies]
+async = [
+    "greenlet>=3.0",
+]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5",
+    "aiosqlite>=0.20",
+    "greenlet>=3.0",
+    "build>=1.2",
+    "twine>=6.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/SignalSafeSoftware/sqlphilosophy"
+Repository = "https://github.com/SignalSafeSoftware/sqlphilosophy"
+Documentation = "https://github.com/SignalSafeSoftware/sqlphilosophy#readme"
+Issues = "https://github.com/SignalSafeSoftware/sqlphilosophy/issues"
+Changelog = "https://github.com/SignalSafeSoftware/sqlphilosophy/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { file = ["src/sqlphilosophy/VERSION"] }
+
+[tool.setuptools.package-data]
+sqlphilosophy = ["py.typed", "VERSION"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov=sqlphilosophy --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+source = ["sqlphilosophy"]
+branch = false
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_also = [
+    "raise NotImplementedError",
+]

sqlphilosophy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlphilosophy-0.1.0/src/sqlphilosophy/VERSION

@@ -0,0 +1 @@
+0.1.0

sqlphilosophy-0.1.0/src/sqlphilosophy/__init__.py

@@ -0,0 +1,3 @@
+"""SQLAlchemy repository kit — sync/async CRUD, query builders, sort, and SQL helpers."""
+
+__all__: list[str] = []

sqlphilosophy-0.1.0/src/sqlphilosophy/aio/__init__.py

@@ -0,0 +1,3 @@
+"""Async repository subpackage."""
+
+__all__: list[str] = []

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

@@ -0,0 +1,26 @@
+"""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)."""
+        ...