sqlakit 0.14.0__tar.gz → 0.16.0__tar.gz

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

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

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

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

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

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

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

@@ -24,9 +24,14 @@ from sqlalchemy.ext.compiler import compiles
 from sqlalchemy.orm import (
     InstrumentedAttribute,
     contains_eager,
+    defer,
     joinedload,
+    load_only,
     selectinload,
     subqueryload,
+    undefer,
+    undefer_group,
+    with_expression,
 )
 from sqlalchemy.orm.exc import MultipleResultsFound, NoResultFound
 from sqlalchemy.sql import operators
@@ -112,6 +117,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,28 +486,49 @@ 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."""
         self._reject_statement("where")
         return self.with_select(self._select.where(*criteria))
 
-    def filter_by(self, **values: Any) -> Self:  # noqa: ANN401
-        """Narrow the rows by equality, as `Select.filter_by` does."""
+    def filter_by(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        **fields: Any,  # noqa: ANN401
+    ) -> Self:
+        """Narrow the rows by equality, as `Select.filter_by` does.
+
+        ```python
+        db.query(User).filter_by(team="red")
+        db.query(User).filter_by(request.query_params)
+        ```
+
+        The fields are keywords, a mapping, or both, as `create()` takes them.
+        """
         self._reject_statement("filter_by")
-        return self.with_select(self._select.filter_by(**values))
+        return self.with_select(self._select.filter_by(**merged(values, fields)))
 
     def join(
         self,
@@ -636,6 +677,67 @@ class BaseQuery(Generic[ModelT]):
         """Read a relationship from a join this query already makes."""
         return self.options(_chain(contains_eager, keys))
 
+    def load_only(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Load these columns of the row, and defer the rest.
+
+        ```python
+        db.query(User).load_only(User.id, User.name).all()
+        ```
+
+        The rows are still instances: a column left out is read from the
+        database when something touches it, one statement per instance, which
+        is the cost this trades the narrower row for. `only_columns` is the
+        other one: it gives the instances up and reads values.
+        """
+        return self.options(load_only(*columns))
+
+    def defer(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Leave these columns out of the row until something reads them.
+
+        ```python
+        db.query(Post).defer(Post.body).all()
+        ```
+
+        For the wide column of a table read for everything else.
+        """
+        return self.options(*(defer(column) for column in columns))
+
+    def undefer(self, *columns: Any) -> Self:  # noqa: ANN401
+        """Load these columns with the row, though the model defers them.
+
+        ```python
+        db.query(Post).undefer(Post.body).all()
+        ```
+
+        The other side of `mapped_column(deferred=True)`, for the read that
+        wants the column after all.
+        """
+        return self.options(*(undefer(column) for column in columns))
+
+    def undefer_group(self, name: str) -> Self:
+        """Load the columns a model defers under this group name.
+
+        ```python
+        db.query(Post).undefer_group("body").all()
+        ```
+
+        The group is the one `mapped_column(deferred_group="body")` names, for
+        the columns a read wants together or not at all.
+        """
+        return self.options(undefer_group(name))
+
+    def with_expression(self, key: Any, expression: Any) -> Self:  # noqa: ANN401
+        """Give a `query_expression()` attribute its value for this read.
+
+        ```python
+        db.query(Post).with_expression(Post.comments, _comment_count()).all()
+        ```
+
+        The attribute holds what this statement selects into it, so a count or
+        a window function arrives on the instance rather than beside it.
+        """
+        return self.options(with_expression(key, expression))
+
     def with_for_update(
         self,
         *,

{sqlakit-0.14.0 → sqlakit-0.16.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.16.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.16.0}/sqlakit/orm.py

@@ -29,6 +29,7 @@ from ._query import (
     BaseQuery,
     CursorPage,
     Page,
+    merged,
     one_row,
     one_row_or_none,
     orderable,
@@ -326,6 +327,10 @@ class Query(BaseQuery[ModelT]):
         ```python
         names = User.query.where(User.is_active).only_columns(User.name).all()
         ```
+
+        One column arrives as values and several as tuples, and neither is an
+        instance. `load_only` is the other one: the rows stay instances, and
+        the columns it leaves out are read when something touches them.
         """
         return ColumnQuery(
             self.model,
@@ -334,19 +339,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 +381,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 +399,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.16.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.