Method with_parent

lib/sqlalchemy/orm/query.py:1251–1318

Add filtering criterion that relates the given instance to a child object or collection, using its attribute state as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate the clause, t

(
        self,
        instance: object,
        property: Optional[  # noqa: A002
            attributes.QueryableAttribute[Any]
        ] = None,
        from_entity: Optional[_ExternalEntityType[Any]] = None,
    )

    )
    @util.preload_module("sqlalchemy.orm.relationships")
    def with_parent(
        self,
        instance: object,
        property: Optional[  # noqa: A002
            attributes.QueryableAttribute[Any]
        ] = None,
        from_entity: Optional[_ExternalEntityType[Any]] = None,
    ) -> Self:
        """Add filtering criterion that relates the given instance
        to a child object or collection, using its attribute state
        as well as an established :func:`_orm.relationship()`
        configuration.

        The method uses the :func:`.with_parent` function to generate
        the clause, the result of which is passed to
        :meth:`_query.Query.filter`.

        Parameters are the same as :func:`.with_parent`, with the exception
        that the given property can be None, in which case a search is
        performed against this :class:`_query.Query` object's target mapper.

        :param instance:
          An instance which has some :func:`_orm.relationship`.

        :param property:
          Class bound attribute which indicates
          what relationship from the instance should be used to reconcile the
          parent/child relationship.

        :param from_entity:
          Entity in which to consider as the left side.  This defaults to the
          "zero" entity of the :class:`_query.Query` itself.

        """
        relationships = util.preloaded.orm_relationships

        if from_entity:
            entity_zero = inspect(from_entity)
        else:
            entity_zero = _legacy_filter_by_entity_zero(self)
        if property is None:
            # TODO: deprecate, property has to be supplied
            mapper = object_mapper(instance)

            for prop in mapper.iterate_properties:
                if (
                    isinstance(prop, relationships.RelationshipProperty)
                    and prop.mapper is entity_zero.mapper  # type: ignore
                ):
                    property = prop  # type: ignore  # noqa: A001
                    break
            else:
                raise sa_exc.InvalidRequestError(
                    "Could not locate a property which relates instances "
                    "of class '%s' to instances of class '%s'"
                    % (
                        entity_zero.mapper.class_.__name__,  # type: ignore
                        instance.__class__.__name__,