sqlakit 0.19.0__tar.gz → 0.21.0__tar.gz

{sqlakit-0.19.0 → sqlakit-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.19.0
+Version: 0.21.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov
@@ -22,13 +22,11 @@ Requires-Dist: sqlalchemy>=2.0.22
 Requires-Dist: typing-extensions>=4.13
 Requires-Dist: sqlalchemy[asyncio]>=2.0.22 ; extra == 'asyncio'
 Requires-Dist: sqlparse>=0.6.0 ; extra == 'debug'
-Requires-Dist: jinja2sql>=0.12.0 ; extra == 'sql'
 Requires-Python: >=3.11
-Project-URL: Repository, https://github.com/antonrh/sqlakit
-Project-URL: Documentation, https://github.com/antonrh/sqlakit
+Project-URL: Repository, https://github.com/sqlakit/sqlakit
+Project-URL: Documentation, https://sqlakit.readthedocs.io/en/stable/
 Provides-Extra: asyncio
 Provides-Extra: debug
-Provides-Extra: sql
 Description-Content-Type: text/markdown
 
 # SQLAKit
@@ -92,11 +90,11 @@ with db.autocommit():  # AUTOCOMMIT, no transaction held open
 
 ## SQL templates
 
-Templates are `Jinja` files, so they can hold anything from a one-line query to
-a report with window functions or a recursive CTE.
-[jinja2sql](https://github.com/antonrh/jinja2sql) turns every `{{ name }}` into
-a bound parameter (`:name__1`), so values never reach the SQL text and there
-is no way to inject anything. Requires the `sqlakit[sql]` extra.
+Templates are SQL files with `:name` parameters, so they hold anything from a
+one-line query to a report with window functions or a recursive CTE, and every
+SQL tool reads them as SQL. Values are bound, so they never reach the SQL
+text. What changes per call, an optional
+condition or a sort order, is a macro such as `tpl.if_set(:team, team = :team)`.
 
 ### From a file
 
@@ -104,7 +102,7 @@ is no way to inject anything. Requires the `sqlakit[sql]` extra.
 -- reports/by_team.sql
 SELECT team, count(*) AS members
 FROM users
-WHERE joined_at > {{ since }}
+WHERE joined_at > :since
 GROUP BY team
 ```
 
@@ -131,13 +129,17 @@ type each row is returned as.
 `SQLAKit` adds the template name to the SQL as a comment, so a slow query log
 shows the source file of each query right away.
 
+`sqlakit check` reads every template the project uses and reports a macro call
+that can't work, before the query runs. See [template
+validation](docs/sql.md#template-validation).
+
 ### From a string
 
 ```python
 db.sql.from_string("SELECT count(*) FROM users").scalars().one()
 ```
 
-The same templating, with no directory to configure.
+The same syntax, with no directory to configure.
 
 ## Query builder
 
@@ -249,16 +251,20 @@ project has `rich`, the output is colored too.
 
 ### The debug server
 
-`sqlakit debugserver` serves a page that fills as the recordings arrive:
+[`sqlakit-debugserver`](https://github.com/sqlakit/sqlakit-debugserver) serves a page that fills as the recordings
+arrive. It is a package of its own:
 
 ```console
-$ sqlakit debugserver
+$ pip install sqlakit-debugserver
+$ sqlakit-debugserver
 
 SQLAKit debug server on http://localhost:5555
 
 Send recordings to it:
 
-  │  with db.recording("GET /users", debugserver=("localhost", 5555)):
+  │  from sqlakit_debugserver import DebugServer
+  │
+  │  with db.recording("GET /users", send_to=DebugServer("localhost", 5555)):
   │      list_users()
 ```
 

{sqlakit-0.19.0 → sqlakit-0.21.0}/README.md

@@ -59,11 +59,11 @@ with db.autocommit():  # AUTOCOMMIT, no transaction held open
 
 ## SQL templates
 
-Templates are `Jinja` files, so they can hold anything from a one-line query to
-a report with window functions or a recursive CTE.
-[jinja2sql](https://github.com/antonrh/jinja2sql) turns every `{{ name }}` into
-a bound parameter (`:name__1`), so values never reach the SQL text and there
-is no way to inject anything. Requires the `sqlakit[sql]` extra.
+Templates are SQL files with `:name` parameters, so they hold anything from a
+one-line query to a report with window functions or a recursive CTE, and every
+SQL tool reads them as SQL. Values are bound, so they never reach the SQL
+text. What changes per call, an optional
+condition or a sort order, is a macro such as `tpl.if_set(:team, team = :team)`.
 
 ### From a file
 
@@ -71,7 +71,7 @@ is no way to inject anything. Requires the `sqlakit[sql]` extra.
 -- reports/by_team.sql
 SELECT team, count(*) AS members
 FROM users
-WHERE joined_at > {{ since }}
+WHERE joined_at > :since
 GROUP BY team
 ```
 
@@ -98,13 +98,17 @@ type each row is returned as.
 `SQLAKit` adds the template name to the SQL as a comment, so a slow query log
 shows the source file of each query right away.
 
+`sqlakit check` reads every template the project uses and reports a macro call
+that can't work, before the query runs. See [template
+validation](docs/sql.md#template-validation).
+
 ### From a string
 
 ```python
 db.sql.from_string("SELECT count(*) FROM users").scalars().one()
 ```
 
-The same templating, with no directory to configure.
+The same syntax, with no directory to configure.
 
 ## Query builder
 
@@ -216,16 +220,20 @@ project has `rich`, the output is colored too.
 
 ### The debug server
 
-`sqlakit debugserver` serves a page that fills as the recordings arrive:
+[`sqlakit-debugserver`](https://github.com/sqlakit/sqlakit-debugserver) serves a page that fills as the recordings
+arrive. It is a package of its own:
 
 ```console
-$ sqlakit debugserver
+$ pip install sqlakit-debugserver
+$ sqlakit-debugserver
 
 SQLAKit debug server on http://localhost:5555
 
 Send recordings to it:
 
-  │  with db.recording("GET /users", debugserver=("localhost", 5555)):
+  │  from sqlakit_debugserver import DebugServer
+  │
+  │  with db.recording("GET /users", send_to=DebugServer("localhost", 5555)):
   │      list_users()
 ```
 

{sqlakit-0.19.0 → sqlakit-0.21.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.19.0"
+version = "0.21.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -42,18 +42,13 @@ sqlakit = "sqlakit._cli:main"
 sqlakit = "sqlakit.pytest_plugin"
 
 [project.urls]
-Repository = "https://github.com/antonrh/sqlakit"
-Documentation = "https://github.com/antonrh/sqlakit"
+Repository = "https://github.com/sqlakit/sqlakit"
+Documentation = "https://sqlakit.readthedocs.io/en/stable/"
 
 [project.optional-dependencies]
 asyncio = ["sqlalchemy[asyncio]>=2.0.22"]
-sql = ["jinja2sql>=0.12.0"]
 debug = ["sqlparse>=0.6.0"]
 
-[build-system]
-requires = ["uv_build>=0.11,<0.13"]
-build-backend = "uv_build"
-
 [tool.uv]
 default-groups = [
     "dev",
@@ -178,12 +173,12 @@ default_item_type = "cmd"
 
 [tool.codespell]
 ignore-words-list = "froms"
-skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver/bun.lock,./sqlakit/debugserver.html"
+skip = "./.venv,./site,./uv.lock,./.git"
 
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.80",
+    "ty>=0.0.84",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
@@ -194,7 +189,6 @@ dev = [
     "httpx>=0.28.1",
     "httpx2>=2.10.0",
     "sqlmodel>=0.0.39",
-    "jinja2sql>=0.12.0",
     "pydantic>=2.13.4",
     "sqlparse>=0.6.0",
     "rich>=15.0.0",
@@ -206,6 +200,7 @@ dev = [
     "flask>=3.1.3",
     "dirty-equals>=0.11",
     "codespell>=2.4.3",
+    "sqruff>=0.40.0",
 ]
 docs = [
     "mkdocs>=1.6.1,<2",
@@ -213,3 +208,7 @@ docs = [
     "mkdocstrings[python]>=1.0.6",
     "ruff>=0.16.6",
 ]
+
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"

{sqlakit-0.19.0 → sqlakit-0.21.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.19.0"
+version = "0.21.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"
@@ -33,24 +33,17 @@ sqlakit = "sqlakit._cli:main"
 sqlakit = "sqlakit.pytest_plugin"
 
 [project.urls]
-Repository = "https://github.com/antonrh/sqlakit"
-Documentation = "https://github.com/antonrh/sqlakit"
+Repository = "https://github.com/sqlakit/sqlakit"
+Documentation = "https://sqlakit.readthedocs.io/en/stable/"
 
 [project.optional-dependencies]
 asyncio = [
     "sqlalchemy[asyncio]>=2.0.22",
 ]
-sql = [
-    "jinja2sql>=0.12.0",
-]
 debug = [
     "sqlparse>=0.6.0",
 ]
 
-[build-system]
-requires = ["uv_build>=0.11,<0.13"]
-build-backend = "uv_build"
-
 [tool.uv.build-backend]
 module-name = "sqlakit"
 module-root = ""
@@ -61,7 +54,7 @@ default-groups = ["dev", "docs"]
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
-    "ty>=0.0.80",
+    "ty>=0.0.84",
     "ruff>=0.16.6",
     "poethepoet>=0.48.0",
     "anyio>=4.14.2",
@@ -72,7 +65,6 @@ dev = [
     "httpx>=0.28.1",
     "httpx2>=2.10.0",
     "sqlmodel>=0.0.39",
-    "jinja2sql>=0.12.0",
     "pydantic>=2.13.4",
     "sqlparse>=0.6.0",
     "rich>=15.0.0",
@@ -84,6 +76,7 @@ dev = [
     "flask>=3.1.3",
     "dirty-equals>=0.11",
     "codespell>=2.4.3",
+    "sqruff>=0.40.0",
 ]
 docs = [
     "mkdocs>=1.6.1,<2",
@@ -101,8 +94,8 @@ filterwarnings = [
 addopts = "-p pytester"
 # The example is a project of its own, run by tests/examples, not collected here.
 norecursedirs = [
-    "examples/testing_plugin",  # a project of its own, run by tests/examples
-    "tests/projects",           # the projects the plugin tests copy
+    "examples/testing_plugin", # a project of its own, run by tests/examples
+    "tests/projects", # the projects the plugin tests copy
     ".*",
     "build",
     "dist",
@@ -137,39 +130,39 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = [
-    "S101",     # tests assert
-    "PLR2004",  # and compare against the values they mean
-    "SLF001",   # they read the internals they are testing
-    "PT012",    # a `raises` block is allowed to set the scene
-    "B018",     # touching an attribute is how a test triggers it
-    "SIM117",   # nested `with` reads better than a long line of them
-    "PLC0415",  # a fixture imports what it is about, where it is about it
-    "DTZ001",   # naive datetimes are fine as fixtures
-    "ARG001",   # a fixture may be requested for its side effect
-    "PT011",    # `raises` without `match` is enough for our own errors
-    "ANN401",   # test helpers take whatever the example hands them
-    "D401",     # test docstrings read as descriptions
-    "N818",     # a test's own exception needs no Error suffix
-    "FBT001",   # parametrised booleans arrive positionally
-    "PLW0108",  # a lambda in a parameter table is deliberate
-    "DTZ005",   # naive datetimes are fine as fixtures
-    "S106",     # the passwords here are fake, and the point of the test
-    "S310",     # the URLs here are the tests' own server
+    "S101", # tests assert
+    "PLR2004", # and compare against the values they mean
+    "SLF001", # they read the internals they are testing
+    "PT012", # a `raises` block is allowed to set the scene
+    "B018", # touching an attribute is how a test triggers it
+    "SIM117", # nested `with` reads better than a long line of them
+    "PLC0415", # a fixture imports what it is about, where it is about it
+    "DTZ001", # naive datetimes are fine as fixtures
+    "ARG001", # a fixture may be requested for its side effect
+    "PT011", # `raises` without `match` is enough for our own errors
+    "ANN401", # test helpers take whatever the example hands them
+    "D401", # test docstrings read as descriptions
+    "N818", # a test's own exception needs no Error suffix
+    "FBT001", # parametrised booleans arrive positionally
+    "PLW0108", # a lambda in a parameter table is deliberate
+    "DTZ005", # naive datetimes are fine as fixtures
+    "S106", # the passwords here are fake, and the point of the test
+    "S310", # the URLs here are the tests' own server
 ]
 "tools/**/*.py" = [
-    "INP001",   # a script, not a package
-    "T201",     # a script that says what it found
+    "INP001", # a script, not a package
+    "T201", # a script that says what it found
 ]
 "examples/**/*.py" = [
-    "INP001",   # examples are read one file at a time, not imported as a package
-    "ARG001",   # FastAPI hands handlers a request they may not use
-    "TC003",    # examples keep their imports where a reader expects them
+    "INP001", # examples are read one file at a time, not imported as a package
+    "ARG001", # FastAPI hands handlers a request they may not use
+    "TC003", # examples keep their imports where a reader expects them
 ]
 "examples/testing_plugin/*.py" = [
-    "S101",     # the example is a test suite, and tests assert
+    "S101", # the example is a test suite, and tests assert
 ]
 "tests/projects/**/*.py" = [
-    "INP001",   # a project the tests copy, not a package of this one
+    "INP001", # a project the tests copy, not a package of this one
 ]
 
 [tool.ty.src]
@@ -211,4 +204,8 @@ default_item_type = "cmd"
 [tool.codespell]
 # `froms` is SQLAlchemy's own word for what a SELECT selects from.
 ignore-words-list = "froms"
-skip = "./.venv,./site,./uv.lock,./.git,./debugserver/node_modules,./debugserver/bun.lock,./sqlakit/debugserver.html"
+skip = "./.venv,./site,./uv.lock,./.git"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.13"]
+build-backend = "uv_build"

{sqlakit-0.19.0 → sqlakit-0.21.0}/sqlakit/__init__.py

@@ -1,6 +1,5 @@
 from ._base import DEFAULT_ENGINE_ARGS, DEFAULT_SESSION_ARGS
 from ._db import Database, RetryingTransaction, Transaction
-from ._debugserver import DebugServer
 from ._discovery import import_models, import_string
 from ._query import (
     CASE_INSENSITIVE_COLLATIONS,
@@ -16,7 +15,6 @@ from ._routing import Router
 from .exceptions import (
     DEFAULT_ALIAS,
     AliasInUseError,
-    AsyncFilterError,
     BulkQueryError,
     ConflictingDatabaseUrlError,
     ConflictingJoinError,
@@ -25,12 +23,17 @@ from .exceptions import (
     DefaultAliasError,
     DetachedInstanceError,
     DuplicateKeyError,
+    InlineValueError,
     InstanceNotFoundError,
     InvalidCursorError,
     InvalidDatabaseConfigError,
     InvalidNullsError,
     InvalidOrderFieldError,
+    InvalidSortStringError,
     KeyLookupError,
+    MacroArgumentError,
+    MacroDefinitionError,
+    MacroSyntaxError,
     MissingConnectionError,
     MissingDatabaseUrlError,
     MissingDefaultDatabaseError,
@@ -40,6 +43,8 @@ from .exceptions import (
     MultipleInstancesFoundError,
     NullCursorValueError,
     PageItemsMismatchError,
+    ParameterPathError,
+    ProjectConfigError,
     RawStatementError,
     RetryNotSupportedError,
     SQLAKitError,
@@ -50,7 +55,9 @@ from .exceptions import (
     UncomparableOrderingError,
     UnknownDatabaseError,
     UnknownFieldError,
+    UnknownIdentifierError,
     UnknownImportPathError,
+    UnknownMacroError,
     UnknownOrderFieldError,
     UnorderedPageError,
     UnregisteredDatabaseError,
@@ -71,7 +78,6 @@ __all__ = [
     "DEFAULT_ENGINE_ARGS",
     "DEFAULT_SESSION_ARGS",
     "AliasInUseError",
-    "AsyncFilterError",
     "BulkQueryError",
     "ConflictingDatabaseUrlError",
     "ConflictingJoinError",
@@ -81,17 +87,21 @@ __all__ = [
     "DatabaseConfig",
     "DatabaseNotConfiguredError",
     "Databases",
-    "DebugServer",
     "DefaultAliasError",
     "DetachedInstanceError",
     "DuplicateKeyError",
     "EngineArgs",
+    "InlineValueError",
     "InstanceNotFoundError",
     "InvalidCursorError",
     "InvalidDatabaseConfigError",
     "InvalidNullsError",
     "InvalidOrderFieldError",
+    "InvalidSortStringError",
     "KeyLookupError",
+    "MacroArgumentError",
+    "MacroDefinitionError",
+    "MacroSyntaxError",
     "MissingConnectionError",
     "MissingDatabaseUrlError",
     "MissingDefaultDatabaseError",
@@ -103,6 +113,8 @@ __all__ = [
     "OrderBy",
     "Page",
     "PageItemsMismatchError",
+    "ParameterPathError",
+    "ProjectConfigError",
     "QueryStats",
     "RawStatementError",
     "Recording",
@@ -122,7 +134,9 @@ __all__ = [
     "UncountedPage",
     "UnknownDatabaseError",
     "UnknownFieldError",
+    "UnknownIdentifierError",
     "UnknownImportPathError",
+    "UnknownMacroError",
     "UnknownOrderFieldError",
     "UnorderedPageError",
     "UnregisteredDatabaseError",

{sqlakit-0.19.0 → sqlakit-0.21.0}/sqlakit/_base.py

@@ -24,7 +24,6 @@ import sqlalchemy as sa
 import sqlalchemy.event
 from typing_extensions import Unpack
 
-from ._debugserver import DebugServer, send_recording
 from ._discovery import import_string
 from ._recording import (
     KEEP,
@@ -358,7 +357,7 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
         stacks: bool = False,
         skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
-        debugserver: DebugServer | tuple[str, int] | None = None,
+        send_to: Callable[[Recording], object] | None = None,
     ) -> Iterator[Recording]:
         """Record the statements of this block, and what they add up to.
 
@@ -373,8 +372,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
 
         ``logger`` writes a summary when the block ends, at a level the numbers
         choose. ``echo`` prints the statements instead, coloured where `rich` is
-        installed. ``debugserver`` sends the recording to a `sqlakit debugserver`
-        listening there, and says nothing when none is. ``stacks`` has every
+        installed. ``send_to`` is called with the recording, to hand it on:
+        `sqlakit_debugserver.DebugServer` is one. ``stacks`` has every
         statement remember the frames that led to it, at the cost of a stack walk
         each time. ``skip_queries_from`` names the files whose statements are none of
         your business: what those run is not recorded at all, which leaves a test's
@@ -403,8 +402,8 @@ class BaseDatabase(Generic[ConnectionT, SessionT]):
                 recording.log(logger)
             if echo:
                 recording.echo()
-            if debugserver is not None:
-                send_recording(recording, debugserver)
+            if send_to is not None:
+                send_to(recording)
 
     @contextmanager
     def assert_queries(
@@ -886,7 +885,7 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
         stacks: bool = False,
         skip_queries_from: Sequence[str | PathLike[str]] = (),
         into: Recording | None = None,
-        debugserver: DebugServer | tuple[str, int] | None = None,
+        send_to: Callable[[Recording], object] | None = None,
         using: str | DatabaseT | Sequence[str | DatabaseT] | None = None,
     ) -> Iterator[Recording]:
         """Record every database this registry has, not the default one alone.
@@ -936,8 +935,8 @@ class _DatabaseRegistryMixin(BaseDatabase[Any, Any], Generic[DatabaseT]):
                     together.log(logger)
                 if echo:
                     together.echo()
-                if debugserver is not None:
-                    send_recording(together, debugserver)
+                if send_to is not None:
+                    send_to(together)
 
     @contextmanager
     def unbound(self) -> Iterator[None]: