sqlalchemy-boltons 1.0.1__tar.gz → 2.0.0__tar.gz

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/CHANGELOG.md

@@ -4,6 +4,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-03-11
+
+### Changed
+
+- `sqlite`: Use an unlimited-size QueuePool by default.
+
 ## [1.0.1] - 2025-02-22
 
 ### Changed

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy_boltons
-Version: 1.0.1
+Version: 2.0.0
 Summary: Utilities that should've been inside SQLAlchemy but aren't
 Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
 Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
@@ -71,3 +71,36 @@ with Session() as session:
 with SessionW() as session:
     session.execute(update(...))
 ```
+
+## orm
+
+Somedays you really wish you could write something like:
+
+```python
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Child.parent == Parent1)  # this doesn't work
+)
+```
+
+But it doesn't work. You get an exception. You try various other things but it just won't produce the right subquery.
+You find tons of people online saying you must resign yourself to writing the explicit filtering condition, writing out
+`.where(Child.parent_id == Parent1.id)`. Like a caveman. Why even bother using an ORM at this point? If you're lucky,
+you find yourself reading mail archives from [a decade ago](https://groups.google.com/g/sqlalchemy/c/R-qOlzzVi0o/m/NtFswgJioDIJ)
+with somewhat of a solution, but it's not obvious how to make it work with table
+[aliases](https://docs.sqlalchemy.org/en/20/orm/queryguide/api.html#sqlalchemy.orm.aliased). Despair is setting in.
+
+But lucky you, you can now use this library:
+
+```python
+from sqlalchemy_boltons.orm import RelationshipComparator as Rel
+
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Rel(Child.parent) == Parent1)
+)  #                                  ^^^^            ^
+```
+
+Hope is restored.

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/README.md

@@ -57,3 +57,36 @@ with Session() as session:
 with SessionW() as session:
     session.execute(update(...))
 ```
+
+## orm
+
+Somedays you really wish you could write something like:
+
+```python
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Child.parent == Parent1)  # this doesn't work
+)
+```
+
+But it doesn't work. You get an exception. You try various other things but it just won't produce the right subquery.
+You find tons of people online saying you must resign yourself to writing the explicit filtering condition, writing out
+`.where(Child.parent_id == Parent1.id)`. Like a caveman. Why even bother using an ORM at this point? If you're lucky,
+you find yourself reading mail archives from [a decade ago](https://groups.google.com/g/sqlalchemy/c/R-qOlzzVi0o/m/NtFswgJioDIJ)
+with somewhat of a solution, but it's not obvious how to make it work with table
+[aliases](https://docs.sqlalchemy.org/en/20/orm/queryguide/api.html#sqlalchemy.orm.aliased). Despair is setting in.
+
+But lucky you, you can now use this library:
+
+```python
+from sqlalchemy_boltons.orm import RelationshipComparator as Rel
+
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Rel(Child.parent) == Parent1)
+)  #                                  ^^^^            ^
+```
+
+Hope is restored.

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/pyproject.toml

@@ -3,7 +3,7 @@ line-length = 120
 
 [project]
 name = "sqlalchemy_boltons"
-version = "1.0.1"
+version = "2.0.0"
 description = "Utilities that should've been inside SQLAlchemy but aren't"
 readme = "README.md"
 license = { text = "MIT" }

sqlalchemy_boltons-2.0.0/src/sqlalchemy_boltons/orm.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from sqlalchemy.sql import coercions as _coercions, util as _util
+
+
+class RelationshipComparator:
+    """
+    This wrapper makes it possible to compare a table against a relationship using :func:`join_expr`. This can be used
+    for constructing a subquery that filters using a relationship to a table from the outer query.
+
+    For example::
+
+        import sqlalchemy as sa
+        from sqlalchemy import orm as sao
+        from sqlalchemy_boltons.orm import RelationshipComparator as Rel
+
+        Base = sao.declarative_base()
+
+
+        class Parent(Base):
+            __tablename__ = "parent"
+
+            id = sa.Column(sa.Integer, primary_key=True)
+
+            children = sao.relationship("Child", back_populates="parent")
+
+
+        class Child(Base):
+            __tablename__ = "child"
+
+            id = sa.Column(sa.Integer, primary_key=True)
+            parent_id = sa.Column(sa.ForeignKey("parent.id"), index=True)
+
+            parent = sao.relationship("Parent", back_populates="children")
+
+
+        # We want a query that selects every Parent that has at least one child. We also want to use aliases.
+        P = sao.aliased(Parent)
+        C = sao.aliased(Child)
+
+        # This is the boring old way of doing it, which requires explicitly stating the filtering conditions in terms
+        # of the columns in both tables.
+        q1 = sa.select(P).where(sa.select(C).where(C.parent_id == P.id).exists())
+
+        # Reuse the filtering conditions from the ORM relationship!
+        q2 = sa.select(P).where(sa.select(C).where(Rel(C.parent) == P).exists())
+
+        assert str(q1) == str(q2), "these should produce the same SQL code!"
+
+    Based on this discussion: https://groups.google.com/g/sqlalchemy/c/R-qOlzzVi0o/m/NtFswgJioDIJ
+    """
+
+    def __init__(self, relationship):
+        self._relationship = relationship
+
+    def __eq__(self, other):
+        if other is None:
+            raise TypeError("cannot compare against None")
+        return join_expr(other, self._relationship)
+
+    def __ne__(self, other):
+        return ~(self == other)
+
+
+def join_expr(right, relationship):
+    """
+    Turn an ORM relationship into an expression that you can use for filtering.
+    """
+
+    expr = _coercions.expect(_coercions.roles.ColumnArgumentRole, relationship)
+    if right is not None:
+        right = _coercions.expect(_coercions.roles.FromClauseRole, right)
+        expr = _util.ClauseAdapter(right).traverse(expr)
+    return expr

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/src/sqlalchemy_boltons/sqlite.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import dataclasses as dc
 import functools
 from pathlib import Path
@@ -54,6 +56,16 @@ class SQLAlchemySqliteTransactionFix:
     This class exists because sqlalchemy doesn't automatically fix pysqlite's stupid default behaviour. Additionally,
     we implement support for foreign keys.
 
+    The execution options we look for are as follows:
+
+    - `x_sqlite_begin_mode`: The type of transaction to be started, such as "BEGIN" or
+      "[BEGIN IMMEDIATE](https://www.sqlite.org/lang_transaction.html)" (or
+      "[BEGIN CONCURRENT](https://www.sqlite.org/cgi/src/doc/begin-concurrent/doc/begin_concurrent.md)" someday maybe).
+    - `x_sqlite_foreign_keys`: The [foreign-key enforcement setting](https://www.sqlite.org/foreignkeys.html). Must be
+      `True`, `False`, or `"defer"`.
+    - `x_sqlite_journal_mode`: The [journal mode](https://www.sqlite.org/pragma.html#pragma_journal_mode) such as
+      `"DELETE"` or `"WAL"`. Optional.
+
     https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#serializable-isolation-savepoints-transactional-ddl
     """
 
@@ -188,6 +200,9 @@ def create_engine_sqlite(
     # always default to QueuePool
     if (k := "poolclass") not in create_engine_args:
         create_engine_args[k] = sap.QueuePool
+        if (k := "max_overflow") not in create_engine_args:
+            # for SQLite it doesn't make sense to restrict the number of concurrent (read-only) connections
+            create_engine_args["max_overflow"] = -1
 
     if (v := create_engine_args.get(k := "connect_args")) is None:
         create_engine_args[k] = v = {}

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/src/sqlalchemy_boltons.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy-boltons
-Version: 1.0.1
+Version: 2.0.0
 Summary: Utilities that should've been inside SQLAlchemy but aren't
 Author-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
 Maintainer-email: Eduard Christian Dumitrescu <eduard.c.dumitrescu@gmail.com>
@@ -71,3 +71,36 @@ with Session() as session:
 with SessionW() as session:
     session.execute(update(...))
 ```
+
+## orm
+
+Somedays you really wish you could write something like:
+
+```python
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Child.parent == Parent1)  # this doesn't work
+)
+```
+
+But it doesn't work. You get an exception. You try various other things but it just won't produce the right subquery.
+You find tons of people online saying you must resign yourself to writing the explicit filtering condition, writing out
+`.where(Child.parent_id == Parent1.id)`. Like a caveman. Why even bother using an ORM at this point? If you're lucky,
+you find yourself reading mail archives from [a decade ago](https://groups.google.com/g/sqlalchemy/c/R-qOlzzVi0o/m/NtFswgJioDIJ)
+with somewhat of a solution, but it's not obvious how to make it work with table
+[aliases](https://docs.sqlalchemy.org/en/20/orm/queryguide/api.html#sqlalchemy.orm.aliased). Despair is setting in.
+
+But lucky you, you can now use this library:
+
+```python
+from sqlalchemy_boltons.orm import RelationshipComparator as Rel
+
+# Find every parent that has at least one child.
+Parent1 = aliased(Parent)
+select(Parent1).where(
+    exists().select_from(Child).where(Rel(Child.parent) == Parent1)
+)  #                                  ^^^^            ^
+```
+
+Hope is restored.

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/src/sqlalchemy_boltons.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ doc/conf.py
 doc/index.rst
 doc/make.bat
 src/sqlalchemy_boltons/__init__.py
+src/sqlalchemy_boltons/orm.py
 src/sqlalchemy_boltons/py.typed
 src/sqlalchemy_boltons/sqlite.py
 src/sqlalchemy_boltons.egg-info/PKG-INFO
@@ -19,4 +20,5 @@ src/sqlalchemy_boltons.egg-info/dependency_links.txt
 src/sqlalchemy_boltons.egg-info/top_level.txt
 tests/__init__.py
 tests/conftest.py
+tests/test_orm.py
 tests/test_sqlite.py

sqlalchemy_boltons-2.0.0/tests/test_orm.py

@@ -0,0 +1,83 @@
+import sqlalchemy as sa
+import sqlalchemy.orm as sao
+
+from sqlalchemy_boltons import orm as _orm
+
+import pytest
+
+
+Base = sao.declarative_base()
+
+
+def _make_rel_1(p=None, c=None):
+    p = p or Parent1
+    c = c or Child1
+    return p.id == c.parent_id
+
+
+def _make_rel_2(p=None, c=None):
+    p = p or Parent2
+    c = c or Child2
+    return (p.ix == c.parent_ix) & (p.iy == c.parent_iy)
+
+
+class Parent1(Base):
+    __tablename__ = "parent1"
+
+    id = sa.Column(sa.Integer, primary_key=True)
+
+    children = sao.relationship("Child1", back_populates="parent")
+
+
+class Child1(Base):
+    __tablename__ = "child1"
+
+    id = sa.Column(sa.Integer, primary_key=True)
+    parent_id = sa.Column(sa.ForeignKey("parent1.id"))
+
+    parent = sao.relationship("Parent1", back_populates="children")
+
+
+class Parent2(Base):
+    __tablename__ = "parent2"
+
+    ix = sa.Column(sa.Integer, primary_key=True)
+    iy = sa.Column(sa.String, primary_key=True)
+
+    children = sao.relationship("Child2", back_populates="parent", primaryjoin=_make_rel_2)
+
+
+class Child2(Base):
+    __tablename__ = "child2"
+
+    id = sa.Column(sa.Integer, primary_key=True)
+    parent_ix = sa.Column(sa.ForeignKey("parent2.ix"))
+    parent_iy = sa.Column(sa.ForeignKey("parent2.iy"))
+
+    parent = sao.relationship("Parent2", primaryjoin=_make_rel_2)
+
+
+_cases = {"1": (Parent1, Child1, _make_rel_1), "2": (Parent2, Child2, _make_rel_2)}
+
+
+def assert_same_sql(x, y):
+    assert str(x) == str(y), "expected equivalent SQL"
+
+
+@pytest.mark.parametrize("case", _cases.keys())
+@pytest.mark.parametrize("alias_parent", [False, True])
+@pytest.mark.parametrize("alias_child", [False, True])
+def test_join_expr(case, alias_parent, alias_child):
+    Parent, Child, make_rel = _cases[case]
+
+    P = sao.aliased(Parent) if alias_parent else Parent
+    C = sao.aliased(Child) if alias_child else Child
+
+    assert_same_sql(_orm.join_expr(P, C.parent), make_rel(P, C))
+
+    Rel = _orm.RelationshipComparator
+
+    if alias_parent:
+        assert_same_sql(Rel(C.parent) == P, make_rel(P, C))
+    else:
+        assert_same_sql(_orm.join_expr(None, C.parent), make_rel(P, C))

{sqlalchemy_boltons-1.0.1 → sqlalchemy_boltons-2.0.0}/tests/test_sqlite.py

@@ -54,7 +54,9 @@ def simple_sqlite_engine(tmp_path, database_type):
     else:
         raise AssertionError
 
-    return _sq.create_engine_sqlite(path, journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True})
+    return _sq.create_engine_sqlite(
+        path, journal_mode="WAL", timeout=0.5, create_engine_args={"echo": True, "pool_timeout": 2}
+    )
 
 
 @pytest.mark.parametrize("database_type", ["file", "memory"])
@@ -117,6 +119,12 @@ def test_transaction(simple_sqlite_engine, database_type):
         assert len(s.execute(sa.select(Example)).all()) == 2
         s.commit()
 
+    with contextlib.ExitStack() as exit_stack:
+        # concurrent connection count
+        for i in range(30):
+            exit_stack.enter_context(s := SessionR())
+            assert len(s.execute(sa.select(Example)).all()) == 2
+
 
 @pytest.mark.parametrize("path_type", ["str", "Path"])
 def test_create_engine_path(tmp_path, path_type):