Method contains_eager

lib/sqlalchemy/orm/strategy_options.py:93–161

r"""Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. The option is used in conjunction with an e

(
        self,
        attr: _AttrType,
        alias: Optional[_FromClauseArgument] = None,
        _is_chain: bool = False,
        _propagate_to_loaders: bool = False,
    )

    propagate_to_loaders: bool

    def contains_eager(
        self,
        attr: _AttrType,
        alias: Optional[_FromClauseArgument] = None,
        _is_chain: bool = False,
        _propagate_to_loaders: bool = False,
    ) -> Self:
        r"""Indicate that the given attribute should be eagerly loaded from
        columns stated manually in the query.

        This function is part of the :class:`_orm.Load` interface and supports
        both method-chained and standalone operation.

        The option is used in conjunction with an explicit join that loads
        the desired rows, i.e.::

            sess.query(Order).join(Order.user).options(contains_eager(Order.user))

        The above query would join from the ``Order`` entity to its related
        ``User`` entity, and the returned ``Order`` objects would have the
        ``Order.user`` attribute pre-populated.

        It may also be used for customizing the entries in an eagerly loaded
        collection; queries will normally want to use the
        :ref:`orm_queryguide_populate_existing` execution option assuming the
        primary collection of parent objects may already have been loaded::

            sess.query(User).join(User.addresses).filter(
                Address.email_address.like("%@aol.com")
            ).options(contains_eager(User.addresses)).populate_existing()

        See the section :ref:`contains_eager` for complete usage details.

        .. seealso::

            :ref:`loading_toplevel`

            :ref:`contains_eager`

        """
        if alias is not None:
            if not isinstance(alias, str):
                coerced_alias = coercions.expect(roles.FromClauseRole, alias)
            else:
                util.warn_deprecated(
                    "Passing a string name for the 'alias' argument to "
                    "'contains_eager()` is deprecated, and will not work in a "
                    "future release.  Please use a sqlalchemy.alias() or "
                    "sqlalchemy.orm.aliased() construct.",
                    version="1.4",
                )
                coerced_alias = alias

        elif getattr(attr, "_of_type", None):
            assert isinstance(attr, QueryableAttribute)
            ot: Optional[_InternalEntityType[Any]] = inspect(attr._of_type)
            assert ot is not None
            coerced_alias = ot.selectable