sqlakit 0.14.0__tar.gz → 0.15.0__tar.gz

{sqlakit-0.14.0 → sqlakit-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlakit
-Version: 0.14.0
+Version: 0.15.0
 Summary: A toolkit for SQLAlchemy applications.
 Keywords: sqlalchemy,database,orm,sql,asyncio
 Author: Anton Ruhlov

{sqlakit-0.14.0 → sqlakit-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.14.0"
+version = "0.15.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.14.0 → sqlakit-0.15.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlakit"
-version = "0.14.0"
+version = "0.15.0"
 description = "A toolkit for SQLAlchemy applications."
 readme = "README.md"
 license = "MIT"

{sqlakit-0.14.0 → sqlakit-0.15.0}/sqlakit/_query.py

@@ -112,6 +112,21 @@ RowT = TypeVar("RowT")
 RowT_co = TypeVar("RowT_co", covariant=True)
 
 
+def merged(
+    mapping: Mapping[str, Any] | None, keywords: Mapping[str, Any]
+) -> Mapping[str, Any]:
+    """Return the values a call was given, however they were passed.
+
+    A caller handed a mapping passes it as it is, and the keywords beside it
+    win, so one value can be replaced without copying the mapping.
+    """
+    if not mapping:
+        return keywords
+    if not keywords:
+        return mapping
+    return {**mapping, **keywords}
+
+
 class CaseInsensitive(sa.ColumnElement[Any]):
     """A column compared without regard to case, however the dialect does it.
 
@@ -466,18 +481,26 @@ class BaseQuery(Generic[ModelT]):
         )
         return query
 
-    def from_sql(self, template: str, /, **context: Any) -> Self:  # noqa: ANN401
+    def from_sql(
+        self,
+        template: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> Self:
         """Take the rows of a SQL template, mapped onto the model.
 
         ```python
         User.query.from_sql("users/active.sql", team="red").all()
+        User.query.from_sql("users/active.sql", context=filters).all()
         ```
 
         Read from the database this query runs on, and rendered for its dialect. As
         with `from_statement`, nothing can be added afterwards and
         ``__query_filter__`` is not applied.
         """
-        return self.from_statement(self.db.sql.from_file(template, **context).statement)
+        rows = self.db.sql.from_file(template, context, **values)
+        return self.from_statement(rows.statement)
 
     def where(self, *criteria: _ColumnExpressionArgument[bool]) -> Self:
         """Narrow the rows, as `Select.where` does."""

{sqlakit-0.14.0 → sqlakit-0.15.0}/sqlakit/asyncio/orm.py

@@ -28,6 +28,7 @@ from sqlakit._query import (
     BaseQuery,
     CursorPage,
     Page,
+    merged,
     one_row,
     one_row_or_none,
     orderable,
@@ -344,19 +345,28 @@ class Query(BaseQuery[ModelT]):
             scalar=len(columns) == 1,
         )
 
-    async def create(self, **values: Any) -> ModelT:  # noqa: ANN401
+    async def create(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> ModelT:
         """Write a new row, and return it as an instance.
 
         ```python
         user = await User.query.create(name="ada", team="red")
+        user = await User.query.create(payload.model_dump())
         ```
 
+        The fields are keywords, a mapping, or both, where a keyword replaces
+        the value of that name.
+
         The row goes through the session, so defaults, relationships and the identity
         map behave as they do for a model that saves itself. What it adds is a write
         that needs no model layer: `Query(User, db).create(...)` works on any mapped
         class.
         """
-        instance = self.model(**values)
+        instance = self.model(**merged(values, fields))
         self.db.session.add(instance)
         await self._persist()
         return instance
@@ -377,9 +387,17 @@ class Query(BaseQuery[ModelT]):
         await self._persist()
         return len(rows)
 
-    async def update(self, values: Mapping[str, Any]) -> int:
+    async def update(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> int:
         """Write these values to every matching row, and return how many.
 
+        A mapping, keywords, or both: `update({"team": "green"})` and
+        `update(team="green")` write the same statement.
+
         One statement, so the session's objects are updated from the database
         rather than in memory. Only the narrowing carries over.
 
@@ -387,7 +405,9 @@ class Query(BaseQuery[ModelT]):
             BulkQueryError: if the query carries anything a statement drops.
 
         """
-        result = await self.db.session.execute(self._update_statement(values))
+        result = await self.db.session.execute(
+            self._update_statement(merged(values, fields))
+        )
         await self._persist()
         return cast("CursorResult[Any]", result).rowcount
 

{sqlakit-0.14.0 → sqlakit-0.15.0}/sqlakit/asyncio/sql.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any, TypeVar, cast
 import sqlalchemy as sa
 from typing_extensions import Unpack
 
+from sqlakit._query import merged
 from sqlakit._sql import (
     BaseSQLQuery,
     Filter,
@@ -14,7 +15,7 @@ from sqlakit._sql import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Sequence
+    from collections.abc import AsyncIterator, Mapping, Sequence
 
     from sqlalchemy.engine import Result, ScalarResult
     from sqlalchemy.ext.asyncio import AsyncConnection
@@ -50,27 +51,48 @@ class SQL:
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.db!r})"
 
-    def __call__(self, template: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+    def __call__(
+        self,
+        template: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of a template. Short for `from_file`.
 
         ```python
         await db.sql("users/active.sql", team="red").all()
         ```
         """
-        return self.from_file(template, **context)
-
-    def from_file(self, template: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+        return self.from_file(template, context, **values)
+
+    def from_file(
+        self,
+        template: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of a template kept under the database's ``templates=``.
 
         ```python
         await db.sql.from_file("users/active.sql", team="red").all()
+        await db.sql.from_file("users/active.sql", context=filters).all()
         ```
 
-        The keyword arguments are the template's context.
+        The keyword arguments are the template's context, and ``context`` takes
+        the same values as a mapping, for values a caller was handed rather than
+        wrote. A value named `context` lives in that mapping.
         """
-        return SQLQuery(self.db, template, context)
-
-    def from_string(self, source: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+        return SQLQuery(self.db, template, merged(context, values))
+
+    def from_string(
+        self,
+        source: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of SQL written out here rather than kept in a file.
 
         ```python
@@ -79,11 +101,12 @@ class SQL:
         )
         ```
 
-        Values are named in `{{ }}` and passed by keyword, as in a template. A
-        `:name` or a `?` binds nothing here, and rendering says so rather than
-        reaching the driver. It needs no ``templates=``.
+        Values are named in `{{ }}` and passed by keyword, or as the ``context``
+        mapping, as in a template. A `:name` or a `?` binds nothing here, and
+        rendering says so rather than reaching the driver. It needs no
+        ``templates=``.
         """
-        return SQLQuery(self.db, source, context, inline=True)
+        return SQLQuery(self.db, source, merged(context, values), inline=True)
 
     def from_statement(self, statement: Executable) -> SQLQuery:
         """Read the rows of a statement built with SQLAlchemy.

{sqlakit-0.14.0 → sqlakit-0.15.0}/sqlakit/orm.py

@@ -29,6 +29,7 @@ from ._query import (
     BaseQuery,
     CursorPage,
     Page,
+    merged,
     one_row,
     one_row_or_none,
     orderable,
@@ -334,19 +335,28 @@ class Query(BaseQuery[ModelT]):
             scalar=len(columns) == 1,
         )
 
-    def create(self, **values: Any) -> ModelT:  # noqa: ANN401
+    def create(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> ModelT:
         """Write a new row, and return it as an instance.
 
         ```python
         user = User.query.create(name="ada", team="red")
+        user = User.query.create(payload.model_dump())
         ```
 
+        The fields are keywords, a mapping, or both, where a keyword replaces
+        the value of that name.
+
         The row goes through the session, so defaults, relationships and the identity
         map behave as they do for a model that saves itself. What it adds is a write
         that needs no model layer: `Query(User, db).create(...)` works on any mapped
         class.
         """
-        instance = self.model(**values)
+        instance = self.model(**merged(values, fields))
         self.db.session.add(instance)
         self._persist()
         return instance
@@ -367,9 +377,17 @@ class Query(BaseQuery[ModelT]):
         self._persist()
         return len(rows)
 
-    def update(self, values: Mapping[str, Any]) -> int:
+    def update(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> int:
         """Write these values to every matching row, and return how many.
 
+        A mapping, keywords, or both: `update({"team": "green"})` and
+        `update(team="green")` write the same statement.
+
         One statement, so the session's objects are updated from the database
         rather than in memory. Only the narrowing carries over.
 
@@ -377,7 +395,7 @@ class Query(BaseQuery[ModelT]):
             BulkQueryError: if the query carries anything a statement drops.
 
         """
-        result = self.db.session.execute(self._update_statement(values))
+        result = self.db.session.execute(self._update_statement(merged(values, fields)))
         self._persist()
         return cast("CursorResult[Any]", result).rowcount
 

{sqlakit-0.14.0 → sqlakit-0.15.0}/sqlakit/sql.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Any, TypeVar, cast
 import sqlalchemy as sa
 from typing_extensions import Unpack
 
+from ._query import merged
 from ._sql import (
     BaseSQLQuery,
     Filter,
@@ -14,7 +15,7 @@ from ._sql import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Iterator, Mapping, Sequence
 
     from sqlalchemy.engine import Result, ScalarResult
     from sqlalchemy.sql import Executable
@@ -48,38 +49,60 @@ class SQL:
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.db!r})"
 
-    def __call__(self, template: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+    def __call__(
+        self,
+        template: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of a template. Short for `from_file`.
 
         ```python
         db.sql("users/active.sql", team="red").all()
         ```
         """
-        return self.from_file(template, **context)
-
-    def from_file(self, template: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+        return self.from_file(template, context, **values)
+
+    def from_file(
+        self,
+        template: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of a template kept under the database's ``templates=``.
 
         ```python
         db.sql.from_file("users/active.sql", team="red").all()
+        db.sql.from_file("users/active.sql", context=filters).all()
         ```
 
-        The keyword arguments are the template's context.
+        The keyword arguments are the template's context, and ``context`` takes
+        the same values as a mapping, for values a caller was handed rather than
+        wrote. A value named `context` lives in that mapping.
         """
-        return SQLQuery(self.db, template, context)
-
-    def from_string(self, source: str, /, **context: Any) -> SQLQuery:  # noqa: ANN401
+        return SQLQuery(self.db, template, merged(context, values))
+
+    def from_string(
+        self,
+        source: str,
+        /,
+        context: Mapping[str, Any] | None = None,
+        **values: Any,  # noqa: ANN401
+    ) -> SQLQuery:
         """Read the rows of SQL written out here rather than kept in a file.
 
         ```python
         db.sql.from_string("SELECT id FROM users WHERE team = {{ team }}", team="red")
         ```
 
-        Values are named in `{{ }}` and passed by keyword, as in a template. A
-        `:name` or a `?` binds nothing here, and rendering says so rather than
-        reaching the driver. It needs no ``templates=``.
+        Values are named in `{{ }}` and passed by keyword, or as the ``context``
+        mapping, as in a template. A `:name` or a `?` binds nothing here, and
+        rendering says so rather than reaching the driver. It needs no
+        ``templates=``.
         """
-        return SQLQuery(self.db, source, context, inline=True)
+        return SQLQuery(self.db, source, merged(context, values), inline=True)
 
     def from_statement(self, statement: Executable) -> SQLQuery:
         """Read the rows of a statement built with SQLAlchemy.