From: Mike Bayer Date: Tue, 19 Apr 2022 03:12:31 +0000 (-0400) Subject: update ORM join doc X-Git-Tag: rel_2_0_0b1~342 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=13a8552053c21a9fa7ff6f992ed49ee92cca73e4;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git update ORM join doc forgot to remove string support for the ON clause here. will backport a deprecation message to 1.4. Change-Id: If90e2bff929cce4dc8a6e9bd3ad818b8f8e514a6 --- diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py index ee6d561452..7690c05dec 100644 --- a/lib/sqlalchemy/orm/_orm_constructors.py +++ b/lib/sqlalchemy/orm/_orm_constructors.py @@ -2243,30 +2243,31 @@ def join( left and right selectables may be not only core selectable objects such as :class:`_schema.Table`, but also mapped classes or :class:`.AliasedClass` instances. The "on" clause can - be a SQL expression, or an attribute or string name + be a SQL expression or an ORM mapped attribute referencing a configured :func:`_orm.relationship`. :func:`_orm.join` is not commonly needed in modern usage, as its functionality is encapsulated within that of the - :meth:`_query.Query.join` method, which features a + :meth:`_sql.Select.join` and :meth:`_query.Query.join` + methods. which feature a significant amount of automation beyond :func:`_orm.join` - by itself. Explicit usage of :func:`_orm.join` - with :class:`_query.Query` involves usage of the - :meth:`_query.Query.select_from` method, as in:: + by itself. Explicit use of :func:`_orm.join` + with ORM-enabled SELECT statements involves use of the + :meth:`_sql.Select.select_from` method, as in:: from sqlalchemy.orm import join - session.query(User).\ + stmt = select(User).\ select_from(join(User, Address, User.addresses)).\ filter(Address.email_address=='foo@bar.com') In modern SQLAlchemy the above join can be written more succinctly as:: - session.query(User).\ + stmt = select(User).\ join(User.addresses).\ filter(Address.email_address=='foo@bar.com') - See :meth:`_query.Query.join` for information on modern usage + See :ref:`orm_queryguide_joins` for information on modern usage of ORM level joins. .. deprecated:: 0.8