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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy_boltons
-Version: 1.1.0
+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.1.0 → 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.1.0 → sqlalchemy_boltons-2.0.0}/pyproject.toml

@@ -3,7 +3,7 @@ line-length = 120
 
 [project]
 name = "sqlalchemy_boltons"
-version = "1.1.0"
+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.1.0 → 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

{sqlalchemy_boltons-1.1.0 → 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.1.0
+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.1.0 → 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))