Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# orm/strategy_options.py
2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7# mypy: allow-untyped-defs, allow-untyped-calls
9"""
11"""
13from __future__ import annotations
15import typing
16from typing import Any
17from typing import Callable
18from typing import cast
19from typing import Dict
20from typing import Iterable
21from typing import Optional
22from typing import overload
23from typing import Sequence
24from typing import Tuple
25from typing import Type
26from typing import TypeVar
27from typing import Union
29from . import util as orm_util
30from ._typing import insp_is_aliased_class
31from ._typing import insp_is_attribute
32from ._typing import insp_is_mapper
33from ._typing import insp_is_mapper_property
34from .attributes import QueryableAttribute
35from .base import InspectionAttr
36from .interfaces import LoaderOption
37from .path_registry import _DEFAULT_TOKEN
38from .path_registry import _StrPathToken
39from .path_registry import _WILDCARD_TOKEN
40from .path_registry import AbstractEntityRegistry
41from .path_registry import path_is_property
42from .path_registry import PathRegistry
43from .path_registry import TokenRegistry
44from .util import _orm_full_deannotate
45from .util import AliasedInsp
46from .. import exc as sa_exc
47from .. import inspect
48from .. import util
49from ..sql import and_
50from ..sql import cache_key
51from ..sql import coercions
52from ..sql import roles
53from ..sql import traversals
54from ..sql import visitors
55from ..sql.base import _generative
56from ..util.typing import Final
57from ..util.typing import Literal
58from ..util.typing import Self
60_RELATIONSHIP_TOKEN: Final[Literal["relationship"]] = "relationship"
61_COLUMN_TOKEN: Final[Literal["column"]] = "column"
63_FN = TypeVar("_FN", bound="Callable[..., Any]")
65if typing.TYPE_CHECKING:
66 from ._typing import _EntityType
67 from ._typing import _InternalEntityType
68 from .context import _MapperEntity
69 from .context import ORMCompileState
70 from .context import QueryContext
71 from .interfaces import _StrategyKey
72 from .interfaces import MapperProperty
73 from .interfaces import ORMOption
74 from .mapper import Mapper
75 from .path_registry import _PathRepresentation
76 from ..sql._typing import _ColumnExpressionArgument
77 from ..sql._typing import _FromClauseArgument
78 from ..sql.cache_key import _CacheKeyTraversalType
79 from ..sql.cache_key import CacheKey
82_AttrType = Union[Literal["*"], "QueryableAttribute[Any]"]
84_WildcardKeyType = Literal["relationship", "column"]
85_StrategySpec = Dict[str, Any]
86_OptsType = Dict[str, Any]
87_AttrGroupType = Tuple[_AttrType, ...]
90class _AbstractLoad(traversals.GenerativeOnTraversal, LoaderOption):
91 __slots__ = ("propagate_to_loaders",)
93 _is_strategy_option = True
94 propagate_to_loaders: bool
96 def contains_eager(
97 self,
98 attr: _AttrType,
99 alias: Optional[_FromClauseArgument] = None,
100 _is_chain: bool = False,
101 _propagate_to_loaders: bool = False,
102 ) -> Self:
103 r"""Indicate that the given attribute should be eagerly loaded from
104 columns stated manually in the query.
106 This function is part of the :class:`_orm.Load` interface and supports
107 both method-chained and standalone operation.
109 The option is used in conjunction with an explicit join that loads
110 the desired rows, i.e.::
112 sess.query(Order).join(Order.user).options(contains_eager(Order.user))
114 The above query would join from the ``Order`` entity to its related
115 ``User`` entity, and the returned ``Order`` objects would have the
116 ``Order.user`` attribute pre-populated.
118 It may also be used for customizing the entries in an eagerly loaded
119 collection; queries will normally want to use the
120 :ref:`orm_queryguide_populate_existing` execution option assuming the
121 primary collection of parent objects may already have been loaded::
123 sess.query(User).join(User.addresses).filter(
124 Address.email_address.like("%@aol.com")
125 ).options(contains_eager(User.addresses)).populate_existing()
127 See the section :ref:`contains_eager` for complete usage details.
129 .. seealso::
131 :ref:`loading_toplevel`
133 :ref:`contains_eager`
135 """
136 if alias is not None:
137 if not isinstance(alias, str):
138 coerced_alias = coercions.expect(roles.FromClauseRole, alias)
139 else:
140 util.warn_deprecated(
141 "Passing a string name for the 'alias' argument to "
142 "'contains_eager()` is deprecated, and will not work in a "
143 "future release. Please use a sqlalchemy.alias() or "
144 "sqlalchemy.orm.aliased() construct.",
145 version="1.4",
146 )
147 coerced_alias = alias
149 elif getattr(attr, "_of_type", None):
150 assert isinstance(attr, QueryableAttribute)
151 ot: Optional[_InternalEntityType[Any]] = inspect(attr._of_type)
152 assert ot is not None
153 coerced_alias = ot.selectable
154 else:
155 coerced_alias = None
157 cloned = self._set_relationship_strategy(
158 attr,
159 {"lazy": "joined"},
160 propagate_to_loaders=_propagate_to_loaders,
161 opts={"eager_from_alias": coerced_alias},
162 _reconcile_to_other=True if _is_chain else None,
163 )
164 return cloned
166 def load_only(self, *attrs: _AttrType, raiseload: bool = False) -> Self:
167 r"""Indicate that for a particular entity, only the given list
168 of column-based attribute names should be loaded; all others will be
169 deferred.
171 This function is part of the :class:`_orm.Load` interface and supports
172 both method-chained and standalone operation.
174 Example - given a class ``User``, load only the ``name`` and
175 ``fullname`` attributes::
177 session.query(User).options(load_only(User.name, User.fullname))
179 Example - given a relationship ``User.addresses -> Address``, specify
180 subquery loading for the ``User.addresses`` collection, but on each
181 ``Address`` object load only the ``email_address`` attribute::
183 session.query(User).options(
184 subqueryload(User.addresses).load_only(Address.email_address)
185 )
187 For a statement that has multiple entities,
188 the lead entity can be
189 specifically referred to using the :class:`_orm.Load` constructor::
191 stmt = (
192 select(User, Address)
193 .join(User.addresses)
194 .options(
195 Load(User).load_only(User.name, User.fullname),
196 Load(Address).load_only(Address.email_address),
197 )
198 )
200 When used together with the
201 :ref:`populate_existing <orm_queryguide_populate_existing>`
202 execution option only the attributes listed will be refreshed.
204 :param \*attrs: Attributes to be loaded, all others will be deferred.
206 :param raiseload: raise :class:`.InvalidRequestError` rather than
207 lazy loading a value when a deferred attribute is accessed. Used
208 to prevent unwanted SQL from being emitted.
210 .. versionadded:: 2.0
212 .. seealso::
214 :ref:`orm_queryguide_column_deferral` - in the
215 :ref:`queryguide_toplevel`
217 :param \*attrs: Attributes to be loaded, all others will be deferred.
219 :param raiseload: raise :class:`.InvalidRequestError` rather than
220 lazy loading a value when a deferred attribute is accessed. Used
221 to prevent unwanted SQL from being emitted.
223 .. versionadded:: 2.0
225 """
226 cloned = self._set_column_strategy(
227 attrs,
228 {"deferred": False, "instrument": True},
229 )
231 wildcard_strategy = {"deferred": True, "instrument": True}
232 if raiseload:
233 wildcard_strategy["raiseload"] = True
235 cloned = cloned._set_column_strategy(
236 ("*",),
237 wildcard_strategy,
238 )
239 return cloned
241 def joinedload(
242 self,
243 attr: _AttrType,
244 innerjoin: Optional[bool] = None,
245 ) -> Self:
246 """Indicate that the given attribute should be loaded using joined
247 eager loading.
249 This function is part of the :class:`_orm.Load` interface and supports
250 both method-chained and standalone operation.
252 examples::
254 # joined-load the "orders" collection on "User"
255 select(User).options(joinedload(User.orders))
257 # joined-load Order.items and then Item.keywords
258 select(Order).options(joinedload(Order.items).joinedload(Item.keywords))
260 # lazily load Order.items, but when Items are loaded,
261 # joined-load the keywords collection
262 select(Order).options(lazyload(Order.items).joinedload(Item.keywords))
264 :param innerjoin: if ``True``, indicates that the joined eager load
265 should use an inner join instead of the default of left outer join::
267 select(Order).options(joinedload(Order.user, innerjoin=True))
269 In order to chain multiple eager joins together where some may be
270 OUTER and others INNER, right-nested joins are used to link them::
272 select(A).options(
273 joinedload(A.bs, innerjoin=False).joinedload(B.cs, innerjoin=True)
274 )
276 The above query, linking A.bs via "outer" join and B.cs via "inner"
277 join would render the joins as "a LEFT OUTER JOIN (b JOIN c)". When
278 using older versions of SQLite (< 3.7.16), this form of JOIN is
279 translated to use full subqueries as this syntax is otherwise not
280 directly supported.
282 The ``innerjoin`` flag can also be stated with the term ``"unnested"``.
283 This indicates that an INNER JOIN should be used, *unless* the join
284 is linked to a LEFT OUTER JOIN to the left, in which case it
285 will render as LEFT OUTER JOIN. For example, supposing ``A.bs``
286 is an outerjoin::
288 select(A).options(joinedload(A.bs).joinedload(B.cs, innerjoin="unnested"))
290 The above join will render as "a LEFT OUTER JOIN b LEFT OUTER JOIN c",
291 rather than as "a LEFT OUTER JOIN (b JOIN c)".
293 .. note:: The "unnested" flag does **not** affect the JOIN rendered
294 from a many-to-many association table, e.g. a table configured as
295 :paramref:`_orm.relationship.secondary`, to the target table; for
296 correctness of results, these joins are always INNER and are
297 therefore right-nested if linked to an OUTER join.
299 .. note::
301 The joins produced by :func:`_orm.joinedload` are **anonymously
302 aliased**. The criteria by which the join proceeds cannot be
303 modified, nor can the ORM-enabled :class:`_sql.Select` or legacy
304 :class:`_query.Query` refer to these joins in any way, including
305 ordering. See :ref:`zen_of_eager_loading` for further detail.
307 To produce a specific SQL JOIN which is explicitly available, use
308 :meth:`_sql.Select.join` and :meth:`_query.Query.join`. To combine
309 explicit JOINs with eager loading of collections, use
310 :func:`_orm.contains_eager`; see :ref:`contains_eager`.
312 .. seealso::
314 :ref:`loading_toplevel`
316 :ref:`joined_eager_loading`
318 """ # noqa: E501
319 loader = self._set_relationship_strategy(
320 attr,
321 {"lazy": "joined"},
322 opts=(
323 {"innerjoin": innerjoin}
324 if innerjoin is not None
325 else util.EMPTY_DICT
326 ),
327 )
328 return loader
330 def subqueryload(self, attr: _AttrType) -> Self:
331 """Indicate that the given attribute should be loaded using
332 subquery eager loading.
334 This function is part of the :class:`_orm.Load` interface and supports
335 both method-chained and standalone operation.
337 examples::
339 # subquery-load the "orders" collection on "User"
340 select(User).options(subqueryload(User.orders))
342 # subquery-load Order.items and then Item.keywords
343 select(Order).options(
344 subqueryload(Order.items).subqueryload(Item.keywords)
345 )
347 # lazily load Order.items, but when Items are loaded,
348 # subquery-load the keywords collection
349 select(Order).options(lazyload(Order.items).subqueryload(Item.keywords))
351 .. seealso::
353 :ref:`loading_toplevel`
355 :ref:`subquery_eager_loading`
357 """
358 return self._set_relationship_strategy(attr, {"lazy": "subquery"})
360 def selectinload(
361 self,
362 attr: _AttrType,
363 recursion_depth: Optional[int] = None,
364 ) -> Self:
365 """Indicate that the given attribute should be loaded using
366 SELECT IN eager loading.
368 This function is part of the :class:`_orm.Load` interface and supports
369 both method-chained and standalone operation.
371 examples::
373 # selectin-load the "orders" collection on "User"
374 select(User).options(selectinload(User.orders))
376 # selectin-load Order.items and then Item.keywords
377 select(Order).options(
378 selectinload(Order.items).selectinload(Item.keywords)
379 )
381 # lazily load Order.items, but when Items are loaded,
382 # selectin-load the keywords collection
383 select(Order).options(lazyload(Order.items).selectinload(Item.keywords))
385 :param recursion_depth: optional int; when set to a positive integer
386 in conjunction with a self-referential relationship,
387 indicates "selectin" loading will continue that many levels deep
388 automatically until no items are found.
390 .. note:: The :paramref:`_orm.selectinload.recursion_depth` option
391 currently supports only self-referential relationships. There
392 is not yet an option to automatically traverse recursive structures
393 with more than one relationship involved.
395 Additionally, the :paramref:`_orm.selectinload.recursion_depth`
396 parameter is new and experimental and should be treated as "alpha"
397 status for the 2.0 series.
399 .. versionadded:: 2.0 added
400 :paramref:`_orm.selectinload.recursion_depth`
403 .. seealso::
405 :ref:`loading_toplevel`
407 :ref:`selectin_eager_loading`
409 """
410 return self._set_relationship_strategy(
411 attr,
412 {"lazy": "selectin"},
413 opts={"recursion_depth": recursion_depth},
414 )
416 def lazyload(self, attr: _AttrType) -> Self:
417 """Indicate that the given attribute should be loaded using "lazy"
418 loading.
420 This function is part of the :class:`_orm.Load` interface and supports
421 both method-chained and standalone operation.
423 .. seealso::
425 :ref:`loading_toplevel`
427 :ref:`lazy_loading`
429 """
430 return self._set_relationship_strategy(attr, {"lazy": "select"})
432 def immediateload(
433 self,
434 attr: _AttrType,
435 recursion_depth: Optional[int] = None,
436 ) -> Self:
437 """Indicate that the given attribute should be loaded using
438 an immediate load with a per-attribute SELECT statement.
440 The load is achieved using the "lazyloader" strategy and does not
441 fire off any additional eager loaders.
443 The :func:`.immediateload` option is superseded in general
444 by the :func:`.selectinload` option, which performs the same task
445 more efficiently by emitting a SELECT for all loaded objects.
447 This function is part of the :class:`_orm.Load` interface and supports
448 both method-chained and standalone operation.
450 :param recursion_depth: optional int; when set to a positive integer
451 in conjunction with a self-referential relationship,
452 indicates "selectin" loading will continue that many levels deep
453 automatically until no items are found.
455 .. note:: The :paramref:`_orm.immediateload.recursion_depth` option
456 currently supports only self-referential relationships. There
457 is not yet an option to automatically traverse recursive structures
458 with more than one relationship involved.
460 .. warning:: This parameter is new and experimental and should be
461 treated as "alpha" status
463 .. versionadded:: 2.0 added
464 :paramref:`_orm.immediateload.recursion_depth`
467 .. seealso::
469 :ref:`loading_toplevel`
471 :ref:`selectin_eager_loading`
473 """
474 loader = self._set_relationship_strategy(
475 attr,
476 {"lazy": "immediate"},
477 opts={"recursion_depth": recursion_depth},
478 )
479 return loader
481 def noload(self, attr: _AttrType) -> Self:
482 """Indicate that the given relationship attribute should remain
483 unloaded.
485 The relationship attribute will return ``None`` when accessed without
486 producing any loading effect.
488 This function is part of the :class:`_orm.Load` interface and supports
489 both method-chained and standalone operation.
491 :func:`_orm.noload` applies to :func:`_orm.relationship` attributes
492 only.
494 .. legacy:: The :func:`_orm.noload` option is **legacy**. As it
495 forces collections to be empty, which invariably leads to
496 non-intuitive and difficult to predict results. There are no
497 legitimate uses for this option in modern SQLAlchemy.
499 .. seealso::
501 :ref:`loading_toplevel`
503 """
505 return self._set_relationship_strategy(attr, {"lazy": "noload"})
507 def raiseload(self, attr: _AttrType, sql_only: bool = False) -> Self:
508 """Indicate that the given attribute should raise an error if accessed.
510 A relationship attribute configured with :func:`_orm.raiseload` will
511 raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The
512 typical way this is useful is when an application is attempting to
513 ensure that all relationship attributes that are accessed in a
514 particular context would have been already loaded via eager loading.
515 Instead of having to read through SQL logs to ensure lazy loads aren't
516 occurring, this strategy will cause them to raise immediately.
518 :func:`_orm.raiseload` applies to :func:`_orm.relationship` attributes
519 only. In order to apply raise-on-SQL behavior to a column-based
520 attribute, use the :paramref:`.orm.defer.raiseload` parameter on the
521 :func:`.defer` loader option.
523 :param sql_only: if True, raise only if the lazy load would emit SQL,
524 but not if it is only checking the identity map, or determining that
525 the related value should just be None due to missing keys. When False,
526 the strategy will raise for all varieties of relationship loading.
528 This function is part of the :class:`_orm.Load` interface and supports
529 both method-chained and standalone operation.
531 .. seealso::
533 :ref:`loading_toplevel`
535 :ref:`prevent_lazy_with_raiseload`
537 :ref:`orm_queryguide_deferred_raiseload`
539 """
541 return self._set_relationship_strategy(
542 attr, {"lazy": "raise_on_sql" if sql_only else "raise"}
543 )
545 def defaultload(self, attr: _AttrType) -> Self:
546 """Indicate an attribute should load using its predefined loader style.
548 The behavior of this loading option is to not change the current
549 loading style of the attribute, meaning that the previously configured
550 one is used or, if no previous style was selected, the default
551 loading will be used.
553 This method is used to link to other loader options further into
554 a chain of attributes without altering the loader style of the links
555 along the chain. For example, to set joined eager loading for an
556 element of an element::
558 session.query(MyClass).options(
559 defaultload(MyClass.someattribute).joinedload(
560 MyOtherClass.someotherattribute
561 )
562 )
564 :func:`.defaultload` is also useful for setting column-level options on
565 a related class, namely that of :func:`.defer` and :func:`.undefer`::
567 session.scalars(
568 select(MyClass).options(
569 defaultload(MyClass.someattribute)
570 .defer("some_column")
571 .undefer("some_other_column")
572 )
573 )
575 .. seealso::
577 :ref:`orm_queryguide_relationship_sub_options`
579 :meth:`_orm.Load.options`
581 """
582 return self._set_relationship_strategy(attr, None)
584 def defer(self, key: _AttrType, raiseload: bool = False) -> Self:
585 r"""Indicate that the given column-oriented attribute should be
586 deferred, e.g. not loaded until accessed.
588 This function is part of the :class:`_orm.Load` interface and supports
589 both method-chained and standalone operation.
591 e.g.::
593 from sqlalchemy.orm import defer
595 session.query(MyClass).options(
596 defer(MyClass.attribute_one), defer(MyClass.attribute_two)
597 )
599 To specify a deferred load of an attribute on a related class,
600 the path can be specified one token at a time, specifying the loading
601 style for each link along the chain. To leave the loading style
602 for a link unchanged, use :func:`_orm.defaultload`::
604 session.query(MyClass).options(
605 defaultload(MyClass.someattr).defer(RelatedClass.some_column)
606 )
608 Multiple deferral options related to a relationship can be bundled
609 at once using :meth:`_orm.Load.options`::
612 select(MyClass).options(
613 defaultload(MyClass.someattr).options(
614 defer(RelatedClass.some_column),
615 defer(RelatedClass.some_other_column),
616 defer(RelatedClass.another_column),
617 )
618 )
620 :param key: Attribute to be deferred.
622 :param raiseload: raise :class:`.InvalidRequestError` rather than
623 lazy loading a value when the deferred attribute is accessed. Used
624 to prevent unwanted SQL from being emitted.
626 .. versionadded:: 1.4
628 .. seealso::
630 :ref:`orm_queryguide_column_deferral` - in the
631 :ref:`queryguide_toplevel`
633 :func:`_orm.load_only`
635 :func:`_orm.undefer`
637 """
638 strategy = {"deferred": True, "instrument": True}
639 if raiseload:
640 strategy["raiseload"] = True
641 return self._set_column_strategy((key,), strategy)
643 def undefer(self, key: _AttrType) -> Self:
644 r"""Indicate that the given column-oriented attribute should be
645 undeferred, e.g. specified within the SELECT statement of the entity
646 as a whole.
648 The column being undeferred is typically set up on the mapping as a
649 :func:`.deferred` attribute.
651 This function is part of the :class:`_orm.Load` interface and supports
652 both method-chained and standalone operation.
654 Examples::
656 # undefer two columns
657 session.query(MyClass).options(
658 undefer(MyClass.col1), undefer(MyClass.col2)
659 )
661 # undefer all columns specific to a single class using Load + *
662 session.query(MyClass, MyOtherClass).options(Load(MyClass).undefer("*"))
664 # undefer a column on a related object
665 select(MyClass).options(defaultload(MyClass.items).undefer(MyClass.text))
667 :param key: Attribute to be undeferred.
669 .. seealso::
671 :ref:`orm_queryguide_column_deferral` - in the
672 :ref:`queryguide_toplevel`
674 :func:`_orm.defer`
676 :func:`_orm.undefer_group`
678 """ # noqa: E501
679 return self._set_column_strategy(
680 (key,), {"deferred": False, "instrument": True}
681 )
683 def undefer_group(self, name: str) -> Self:
684 """Indicate that columns within the given deferred group name should be
685 undeferred.
687 The columns being undeferred are set up on the mapping as
688 :func:`.deferred` attributes and include a "group" name.
690 E.g::
692 session.query(MyClass).options(undefer_group("large_attrs"))
694 To undefer a group of attributes on a related entity, the path can be
695 spelled out using relationship loader options, such as
696 :func:`_orm.defaultload`::
698 select(MyClass).options(
699 defaultload("someattr").undefer_group("large_attrs")
700 )
702 .. seealso::
704 :ref:`orm_queryguide_column_deferral` - in the
705 :ref:`queryguide_toplevel`
707 :func:`_orm.defer`
709 :func:`_orm.undefer`
711 """
712 return self._set_column_strategy(
713 (_WILDCARD_TOKEN,), None, {f"undefer_group_{name}": True}
714 )
716 def with_expression(
717 self,
718 key: _AttrType,
719 expression: _ColumnExpressionArgument[Any],
720 ) -> Self:
721 r"""Apply an ad-hoc SQL expression to a "deferred expression"
722 attribute.
724 This option is used in conjunction with the
725 :func:`_orm.query_expression` mapper-level construct that indicates an
726 attribute which should be the target of an ad-hoc SQL expression.
728 E.g.::
730 stmt = select(SomeClass).options(
731 with_expression(SomeClass.x_y_expr, SomeClass.x + SomeClass.y)
732 )
734 .. versionadded:: 1.2
736 :param key: Attribute to be populated
738 :param expr: SQL expression to be applied to the attribute.
740 .. seealso::
742 :ref:`orm_queryguide_with_expression` - background and usage
743 examples
745 """
747 expression = _orm_full_deannotate(
748 coercions.expect(roles.LabeledColumnExprRole, expression)
749 )
751 return self._set_column_strategy(
752 (key,), {"query_expression": True}, extra_criteria=(expression,)
753 )
755 def selectin_polymorphic(self, classes: Iterable[Type[Any]]) -> Self:
756 """Indicate an eager load should take place for all attributes
757 specific to a subclass.
759 This uses an additional SELECT with IN against all matched primary
760 key values, and is the per-query analogue to the ``"selectin"``
761 setting on the :paramref:`.mapper.polymorphic_load` parameter.
763 .. versionadded:: 1.2
765 .. seealso::
767 :ref:`polymorphic_selectin`
769 """
770 self = self._set_class_strategy(
771 {"selectinload_polymorphic": True},
772 opts={
773 "entities": tuple(
774 sorted((inspect(cls) for cls in classes), key=id)
775 )
776 },
777 )
778 return self
780 @overload
781 def _coerce_strat(self, strategy: _StrategySpec) -> _StrategyKey: ...
783 @overload
784 def _coerce_strat(self, strategy: Literal[None]) -> None: ...
786 def _coerce_strat(
787 self, strategy: Optional[_StrategySpec]
788 ) -> Optional[_StrategyKey]:
789 if strategy is not None:
790 strategy_key = tuple(sorted(strategy.items()))
791 else:
792 strategy_key = None
793 return strategy_key
795 @_generative
796 def _set_relationship_strategy(
797 self,
798 attr: _AttrType,
799 strategy: Optional[_StrategySpec],
800 propagate_to_loaders: bool = True,
801 opts: Optional[_OptsType] = None,
802 _reconcile_to_other: Optional[bool] = None,
803 ) -> Self:
804 strategy_key = self._coerce_strat(strategy)
806 self._clone_for_bind_strategy(
807 (attr,),
808 strategy_key,
809 _RELATIONSHIP_TOKEN,
810 opts=opts,
811 propagate_to_loaders=propagate_to_loaders,
812 reconcile_to_other=_reconcile_to_other,
813 )
814 return self
816 @_generative
817 def _set_column_strategy(
818 self,
819 attrs: Tuple[_AttrType, ...],
820 strategy: Optional[_StrategySpec],
821 opts: Optional[_OptsType] = None,
822 extra_criteria: Optional[Tuple[Any, ...]] = None,
823 ) -> Self:
824 strategy_key = self._coerce_strat(strategy)
826 self._clone_for_bind_strategy(
827 attrs,
828 strategy_key,
829 _COLUMN_TOKEN,
830 opts=opts,
831 attr_group=attrs,
832 extra_criteria=extra_criteria,
833 )
834 return self
836 @_generative
837 def _set_generic_strategy(
838 self,
839 attrs: Tuple[_AttrType, ...],
840 strategy: _StrategySpec,
841 _reconcile_to_other: Optional[bool] = None,
842 ) -> Self:
843 strategy_key = self._coerce_strat(strategy)
844 self._clone_for_bind_strategy(
845 attrs,
846 strategy_key,
847 None,
848 propagate_to_loaders=True,
849 reconcile_to_other=_reconcile_to_other,
850 )
851 return self
853 @_generative
854 def _set_class_strategy(
855 self, strategy: _StrategySpec, opts: _OptsType
856 ) -> Self:
857 strategy_key = self._coerce_strat(strategy)
859 self._clone_for_bind_strategy(None, strategy_key, None, opts=opts)
860 return self
862 def _apply_to_parent(self, parent: Load) -> None:
863 """apply this :class:`_orm._AbstractLoad` object as a sub-option o
864 a :class:`_orm.Load` object.
866 Implementation is provided by subclasses.
868 """
869 raise NotImplementedError()
871 def options(self, *opts: _AbstractLoad) -> Self:
872 r"""Apply a series of options as sub-options to this
873 :class:`_orm._AbstractLoad` object.
875 Implementation is provided by subclasses.
877 """
878 raise NotImplementedError()
880 def _clone_for_bind_strategy(
881 self,
882 attrs: Optional[Tuple[_AttrType, ...]],
883 strategy: Optional[_StrategyKey],
884 wildcard_key: Optional[_WildcardKeyType],
885 opts: Optional[_OptsType] = None,
886 attr_group: Optional[_AttrGroupType] = None,
887 propagate_to_loaders: bool = True,
888 reconcile_to_other: Optional[bool] = None,
889 extra_criteria: Optional[Tuple[Any, ...]] = None,
890 ) -> Self:
891 raise NotImplementedError()
893 def process_compile_state_replaced_entities(
894 self,
895 compile_state: ORMCompileState,
896 mapper_entities: Sequence[_MapperEntity],
897 ) -> None:
898 if not compile_state.compile_options._enable_eagerloads:
899 return
901 # process is being run here so that the options given are validated
902 # against what the lead entities were, as well as to accommodate
903 # for the entities having been replaced with equivalents
904 self._process(
905 compile_state,
906 mapper_entities,
907 not bool(compile_state.current_path),
908 )
910 def process_compile_state(self, compile_state: ORMCompileState) -> None:
911 if not compile_state.compile_options._enable_eagerloads:
912 return
914 self._process(
915 compile_state,
916 compile_state._lead_mapper_entities,
917 not bool(compile_state.current_path)
918 and not compile_state.compile_options._for_refresh_state,
919 )
921 def _process(
922 self,
923 compile_state: ORMCompileState,
924 mapper_entities: Sequence[_MapperEntity],
925 raiseerr: bool,
926 ) -> None:
927 """implemented by subclasses"""
928 raise NotImplementedError()
930 @classmethod
931 def _chop_path(
932 cls,
933 to_chop: _PathRepresentation,
934 path: PathRegistry,
935 debug: bool = False,
936 ) -> Optional[_PathRepresentation]:
937 i = -1
939 for i, (c_token, p_token) in enumerate(
940 zip(to_chop, path.natural_path)
941 ):
942 if isinstance(c_token, str):
943 if i == 0 and (
944 c_token.endswith(f":{_DEFAULT_TOKEN}")
945 or c_token.endswith(f":{_WILDCARD_TOKEN}")
946 ):
947 return to_chop
948 elif (
949 c_token != f"{_RELATIONSHIP_TOKEN}:{_WILDCARD_TOKEN}"
950 and c_token != p_token.key # type: ignore
951 ):
952 return None
954 if c_token is p_token:
955 continue
956 elif (
957 isinstance(c_token, InspectionAttr)
958 and insp_is_mapper(c_token)
959 and insp_is_mapper(p_token)
960 and c_token.isa(p_token)
961 ):
962 continue
964 else:
965 return None
966 return to_chop[i + 1 :]
969class Load(_AbstractLoad):
970 """Represents loader options which modify the state of a
971 ORM-enabled :class:`_sql.Select` or a legacy :class:`_query.Query` in
972 order to affect how various mapped attributes are loaded.
974 The :class:`_orm.Load` object is in most cases used implicitly behind the
975 scenes when one makes use of a query option like :func:`_orm.joinedload`,
976 :func:`_orm.defer`, or similar. It typically is not instantiated directly
977 except for in some very specific cases.
979 .. seealso::
981 :ref:`orm_queryguide_relationship_per_entity_wildcard` - illustrates an
982 example where direct use of :class:`_orm.Load` may be useful
984 """
986 __slots__ = (
987 "path",
988 "context",
989 "additional_source_entities",
990 )
992 _traverse_internals = [
993 ("path", visitors.ExtendedInternalTraversal.dp_has_cache_key),
994 (
995 "context",
996 visitors.InternalTraversal.dp_has_cache_key_list,
997 ),
998 ("propagate_to_loaders", visitors.InternalTraversal.dp_boolean),
999 (
1000 "additional_source_entities",
1001 visitors.InternalTraversal.dp_has_cache_key_list,
1002 ),
1003 ]
1004 _cache_key_traversal = None
1006 path: PathRegistry
1007 context: Tuple[_LoadElement, ...]
1008 additional_source_entities: Tuple[_InternalEntityType[Any], ...]
1010 def __init__(self, entity: _EntityType[Any]):
1011 insp = cast("Union[Mapper[Any], AliasedInsp[Any]]", inspect(entity))
1012 insp._post_inspect
1014 self.path = insp._path_registry
1015 self.context = ()
1016 self.propagate_to_loaders = False
1017 self.additional_source_entities = ()
1019 def __str__(self) -> str:
1020 return f"Load({self.path[0]})"
1022 @classmethod
1023 def _construct_for_existing_path(
1024 cls, path: AbstractEntityRegistry
1025 ) -> Load:
1026 load = cls.__new__(cls)
1027 load.path = path
1028 load.context = ()
1029 load.propagate_to_loaders = False
1030 load.additional_source_entities = ()
1031 return load
1033 def _adapt_cached_option_to_uncached_option(
1034 self, context: QueryContext, uncached_opt: ORMOption
1035 ) -> ORMOption:
1036 if uncached_opt is self:
1037 return self
1038 return self._adjust_for_extra_criteria(context)
1040 def _prepend_path(self, path: PathRegistry) -> Load:
1041 cloned = self._clone()
1042 cloned.context = tuple(
1043 element._prepend_path(path) for element in self.context
1044 )
1045 return cloned
1047 def _adjust_for_extra_criteria(self, context: QueryContext) -> Load:
1048 """Apply the current bound parameters in a QueryContext to all
1049 occurrences "extra_criteria" stored within this ``Load`` object,
1050 returning a new instance of this ``Load`` object.
1052 """
1054 # avoid generating cache keys for the queries if we don't
1055 # actually have any extra_criteria options, which is the
1056 # common case
1057 for value in self.context:
1058 if value._extra_criteria:
1059 break
1060 else:
1061 return self
1063 replacement_cache_key = context.user_passed_query._generate_cache_key()
1065 if replacement_cache_key is None:
1066 return self
1068 orig_query = context.compile_state.select_statement
1069 orig_cache_key = orig_query._generate_cache_key()
1070 assert orig_cache_key is not None
1072 def process(
1073 opt: _LoadElement,
1074 replacement_cache_key: CacheKey,
1075 orig_cache_key: CacheKey,
1076 ) -> _LoadElement:
1077 cloned_opt = opt._clone()
1079 cloned_opt._extra_criteria = tuple(
1080 replacement_cache_key._apply_params_to_element(
1081 orig_cache_key, crit
1082 )
1083 for crit in cloned_opt._extra_criteria
1084 )
1086 return cloned_opt
1088 cloned = self._clone()
1089 cloned.context = tuple(
1090 (
1091 process(value, replacement_cache_key, orig_cache_key)
1092 if value._extra_criteria
1093 else value
1094 )
1095 for value in self.context
1096 )
1097 return cloned
1099 def _reconcile_query_entities_with_us(self, mapper_entities, raiseerr):
1100 """called at process time to allow adjustment of the root
1101 entity inside of _LoadElement objects.
1103 """
1104 path = self.path
1106 for ent in mapper_entities:
1107 ezero = ent.entity_zero
1108 if ezero and orm_util._entity_corresponds_to(
1109 # technically this can be a token also, but this is
1110 # safe to pass to _entity_corresponds_to()
1111 ezero,
1112 cast("_InternalEntityType[Any]", path[0]),
1113 ):
1114 return ezero
1116 return None
1118 def _process(
1119 self,
1120 compile_state: ORMCompileState,
1121 mapper_entities: Sequence[_MapperEntity],
1122 raiseerr: bool,
1123 ) -> None:
1124 reconciled_lead_entity = self._reconcile_query_entities_with_us(
1125 mapper_entities, raiseerr
1126 )
1128 # if the context has a current path, this is a lazy load
1129 has_current_path = bool(compile_state.compile_options._current_path)
1131 for loader in self.context:
1132 # issue #11292
1133 # historically, propagate_to_loaders was only considered at
1134 # object loading time, whether or not to carry along options
1135 # onto an object's loaded state where it would be used by lazyload.
1136 # however, the defaultload() option needs to propagate in case
1137 # its sub-options propagate_to_loaders, but its sub-options
1138 # that dont propagate should not be applied for lazy loaders.
1139 # so we check again
1140 if has_current_path and not loader.propagate_to_loaders:
1141 continue
1142 loader.process_compile_state(
1143 self,
1144 compile_state,
1145 mapper_entities,
1146 reconciled_lead_entity,
1147 raiseerr,
1148 )
1150 def _apply_to_parent(self, parent: Load) -> None:
1151 """apply this :class:`_orm.Load` object as a sub-option of another
1152 :class:`_orm.Load` object.
1154 This method is used by the :meth:`_orm.Load.options` method.
1156 """
1157 cloned = self._generate()
1159 assert cloned.propagate_to_loaders == self.propagate_to_loaders
1161 if not any(
1162 orm_util._entity_corresponds_to_use_path_impl(
1163 elem, cloned.path.odd_element(0)
1164 )
1165 for elem in (parent.path.odd_element(-1),)
1166 + parent.additional_source_entities
1167 ):
1168 if len(cloned.path) > 1:
1169 attrname = cloned.path[1]
1170 parent_entity = cloned.path[0]
1171 else:
1172 attrname = cloned.path[0]
1173 parent_entity = cloned.path[0]
1174 _raise_for_does_not_link(parent.path, attrname, parent_entity)
1176 cloned.path = PathRegistry.coerce(parent.path[0:-1] + cloned.path[:])
1178 if self.context:
1179 cloned.context = tuple(
1180 value._prepend_path_from(parent) for value in self.context
1181 )
1183 if cloned.context:
1184 parent.context += cloned.context
1185 parent.additional_source_entities += (
1186 cloned.additional_source_entities
1187 )
1189 @_generative
1190 def options(self, *opts: _AbstractLoad) -> Self:
1191 r"""Apply a series of options as sub-options to this
1192 :class:`_orm.Load`
1193 object.
1195 E.g.::
1197 query = session.query(Author)
1198 query = query.options(
1199 joinedload(Author.book).options(
1200 load_only(Book.summary, Book.excerpt),
1201 joinedload(Book.citations).options(joinedload(Citation.author)),
1202 )
1203 )
1205 :param \*opts: A series of loader option objects (ultimately
1206 :class:`_orm.Load` objects) which should be applied to the path
1207 specified by this :class:`_orm.Load` object.
1209 .. versionadded:: 1.3.6
1211 .. seealso::
1213 :func:`.defaultload`
1215 :ref:`orm_queryguide_relationship_sub_options`
1217 """
1218 for opt in opts:
1219 try:
1220 opt._apply_to_parent(self)
1221 except AttributeError as ae:
1222 if not isinstance(opt, _AbstractLoad):
1223 raise sa_exc.ArgumentError(
1224 f"Loader option {opt} is not compatible with the "
1225 "Load.options() method."
1226 ) from ae
1227 else:
1228 raise
1229 return self
1231 def _clone_for_bind_strategy(
1232 self,
1233 attrs: Optional[Tuple[_AttrType, ...]],
1234 strategy: Optional[_StrategyKey],
1235 wildcard_key: Optional[_WildcardKeyType],
1236 opts: Optional[_OptsType] = None,
1237 attr_group: Optional[_AttrGroupType] = None,
1238 propagate_to_loaders: bool = True,
1239 reconcile_to_other: Optional[bool] = None,
1240 extra_criteria: Optional[Tuple[Any, ...]] = None,
1241 ) -> Self:
1242 # for individual strategy that needs to propagate, set the whole
1243 # Load container to also propagate, so that it shows up in
1244 # InstanceState.load_options
1245 if propagate_to_loaders:
1246 self.propagate_to_loaders = True
1248 if self.path.is_token:
1249 raise sa_exc.ArgumentError(
1250 "Wildcard token cannot be followed by another entity"
1251 )
1253 elif path_is_property(self.path):
1254 # re-use the lookup which will raise a nicely formatted
1255 # LoaderStrategyException
1256 if strategy:
1257 self.path.prop._strategy_lookup(self.path.prop, strategy[0])
1258 else:
1259 raise sa_exc.ArgumentError(
1260 f"Mapped attribute '{self.path.prop}' does not "
1261 "refer to a mapped entity"
1262 )
1264 if attrs is None:
1265 load_element = _ClassStrategyLoad.create(
1266 self.path,
1267 None,
1268 strategy,
1269 wildcard_key,
1270 opts,
1271 propagate_to_loaders,
1272 attr_group=attr_group,
1273 reconcile_to_other=reconcile_to_other,
1274 extra_criteria=extra_criteria,
1275 )
1276 if load_element:
1277 self.context += (load_element,)
1278 assert opts is not None
1279 self.additional_source_entities += cast(
1280 "Tuple[_InternalEntityType[Any]]", opts["entities"]
1281 )
1283 else:
1284 for attr in attrs:
1285 if isinstance(attr, str):
1286 load_element = _TokenStrategyLoad.create(
1287 self.path,
1288 attr,
1289 strategy,
1290 wildcard_key,
1291 opts,
1292 propagate_to_loaders,
1293 attr_group=attr_group,
1294 reconcile_to_other=reconcile_to_other,
1295 extra_criteria=extra_criteria,
1296 )
1297 else:
1298 load_element = _AttributeStrategyLoad.create(
1299 self.path,
1300 attr,
1301 strategy,
1302 wildcard_key,
1303 opts,
1304 propagate_to_loaders,
1305 attr_group=attr_group,
1306 reconcile_to_other=reconcile_to_other,
1307 extra_criteria=extra_criteria,
1308 )
1310 if load_element:
1311 # for relationship options, update self.path on this Load
1312 # object with the latest path.
1313 if wildcard_key is _RELATIONSHIP_TOKEN:
1314 self.path = load_element.path
1315 self.context += (load_element,)
1317 # this seems to be effective for selectinloader,
1318 # giving the extra match to one more level deep.
1319 # but does not work for immediateloader, which still
1320 # must add additional options at load time
1321 if load_element.local_opts.get("recursion_depth", False):
1322 r1 = load_element._recurse()
1323 self.context += (r1,)
1325 return self
1327 def __getstate__(self):
1328 d = self._shallow_to_dict()
1329 d["path"] = self.path.serialize()
1330 return d
1332 def __setstate__(self, state):
1333 state["path"] = PathRegistry.deserialize(state["path"])
1334 self._shallow_from_dict(state)
1337class _WildcardLoad(_AbstractLoad):
1338 """represent a standalone '*' load operation"""
1340 __slots__ = ("strategy", "path", "local_opts")
1342 _traverse_internals = [
1343 ("strategy", visitors.ExtendedInternalTraversal.dp_plain_obj),
1344 ("path", visitors.ExtendedInternalTraversal.dp_plain_obj),
1345 (
1346 "local_opts",
1347 visitors.ExtendedInternalTraversal.dp_string_multi_dict,
1348 ),
1349 ]
1350 cache_key_traversal: _CacheKeyTraversalType = None
1352 strategy: Optional[Tuple[Any, ...]]
1353 local_opts: _OptsType
1354 path: Union[Tuple[()], Tuple[str]]
1355 propagate_to_loaders = False
1357 def __init__(self) -> None:
1358 self.path = ()
1359 self.strategy = None
1360 self.local_opts = util.EMPTY_DICT
1362 def _clone_for_bind_strategy(
1363 self,
1364 attrs,
1365 strategy,
1366 wildcard_key,
1367 opts=None,
1368 attr_group=None,
1369 propagate_to_loaders=True,
1370 reconcile_to_other=None,
1371 extra_criteria=None,
1372 ):
1373 assert attrs is not None
1374 attr = attrs[0]
1375 assert (
1376 wildcard_key
1377 and isinstance(attr, str)
1378 and attr in (_WILDCARD_TOKEN, _DEFAULT_TOKEN)
1379 )
1381 attr = f"{wildcard_key}:{attr}"
1383 self.strategy = strategy
1384 self.path = (attr,)
1385 if opts:
1386 self.local_opts = util.immutabledict(opts)
1388 assert extra_criteria is None
1390 def options(self, *opts: _AbstractLoad) -> Self:
1391 raise NotImplementedError("Star option does not support sub-options")
1393 def _apply_to_parent(self, parent: Load) -> None:
1394 """apply this :class:`_orm._WildcardLoad` object as a sub-option of
1395 a :class:`_orm.Load` object.
1397 This method is used by the :meth:`_orm.Load.options` method. Note
1398 that :class:`_orm.WildcardLoad` itself can't have sub-options, but
1399 it may be used as the sub-option of a :class:`_orm.Load` object.
1401 """
1402 assert self.path
1403 attr = self.path[0]
1404 if attr.endswith(_DEFAULT_TOKEN):
1405 attr = f"{attr.split(':')[0]}:{_WILDCARD_TOKEN}"
1407 effective_path = cast(AbstractEntityRegistry, parent.path).token(attr)
1409 assert effective_path.is_token
1411 loader = _TokenStrategyLoad.create(
1412 effective_path,
1413 None,
1414 self.strategy,
1415 None,
1416 self.local_opts,
1417 self.propagate_to_loaders,
1418 )
1420 parent.context += (loader,)
1422 def _process(self, compile_state, mapper_entities, raiseerr):
1423 is_refresh = compile_state.compile_options._for_refresh_state
1425 if is_refresh and not self.propagate_to_loaders:
1426 return
1428 entities = [ent.entity_zero for ent in mapper_entities]
1429 current_path = compile_state.current_path
1431 start_path: _PathRepresentation = self.path
1433 if current_path:
1434 # TODO: no cases in test suite where we actually get
1435 # None back here
1436 new_path = self._chop_path(start_path, current_path)
1437 if new_path is None:
1438 return
1440 # chop_path does not actually "chop" a wildcard token path,
1441 # just returns it
1442 assert new_path == start_path
1444 # start_path is a single-token tuple
1445 assert start_path and len(start_path) == 1
1447 token = start_path[0]
1448 assert isinstance(token, str)
1449 entity = self._find_entity_basestring(entities, token, raiseerr)
1451 if not entity:
1452 return
1454 path_element = entity
1456 # transfer our entity-less state into a Load() object
1457 # with a real entity path. Start with the lead entity
1458 # we just located, then go through the rest of our path
1459 # tokens and populate into the Load().
1461 assert isinstance(token, str)
1462 loader = _TokenStrategyLoad.create(
1463 path_element._path_registry,
1464 token,
1465 self.strategy,
1466 None,
1467 self.local_opts,
1468 self.propagate_to_loaders,
1469 raiseerr=raiseerr,
1470 )
1471 if not loader:
1472 return
1474 assert loader.path.is_token
1476 # don't pass a reconciled lead entity here
1477 loader.process_compile_state(
1478 self, compile_state, mapper_entities, None, raiseerr
1479 )
1481 return loader
1483 def _find_entity_basestring(
1484 self,
1485 entities: Iterable[_InternalEntityType[Any]],
1486 token: str,
1487 raiseerr: bool,
1488 ) -> Optional[_InternalEntityType[Any]]:
1489 if token.endswith(f":{_WILDCARD_TOKEN}"):
1490 if len(list(entities)) != 1:
1491 if raiseerr:
1492 raise sa_exc.ArgumentError(
1493 "Can't apply wildcard ('*') or load_only() "
1494 f"loader option to multiple entities "
1495 f"{', '.join(str(ent) for ent in entities)}. Specify "
1496 "loader options for each entity individually, such as "
1497 f"""{
1498 ", ".join(
1499 f"Load({ent}).some_option('*')"
1500 for ent in entities
1501 )
1502 }."""
1503 )
1504 elif token.endswith(_DEFAULT_TOKEN):
1505 raiseerr = False
1507 for ent in entities:
1508 # return only the first _MapperEntity when searching
1509 # based on string prop name. Ideally object
1510 # attributes are used to specify more exactly.
1511 return ent
1512 else:
1513 if raiseerr:
1514 raise sa_exc.ArgumentError(
1515 "Query has only expression-based entities - "
1516 f'can\'t find property named "{token}".'
1517 )
1518 else:
1519 return None
1521 def __getstate__(self) -> Dict[str, Any]:
1522 d = self._shallow_to_dict()
1523 return d
1525 def __setstate__(self, state: Dict[str, Any]) -> None:
1526 self._shallow_from_dict(state)
1529class _LoadElement(
1530 cache_key.HasCacheKey, traversals.HasShallowCopy, visitors.Traversible
1531):
1532 """represents strategy information to select for a LoaderStrategy
1533 and pass options to it.
1535 :class:`._LoadElement` objects provide the inner datastructure
1536 stored by a :class:`_orm.Load` object and are also the object passed
1537 to methods like :meth:`.LoaderStrategy.setup_query`.
1539 .. versionadded:: 2.0
1541 """
1543 __slots__ = (
1544 "path",
1545 "strategy",
1546 "propagate_to_loaders",
1547 "local_opts",
1548 "_extra_criteria",
1549 "_reconcile_to_other",
1550 )
1551 __visit_name__ = "load_element"
1553 _traverse_internals = [
1554 ("path", visitors.ExtendedInternalTraversal.dp_has_cache_key),
1555 ("strategy", visitors.ExtendedInternalTraversal.dp_plain_obj),
1556 (
1557 "local_opts",
1558 visitors.ExtendedInternalTraversal.dp_string_multi_dict,
1559 ),
1560 ("_extra_criteria", visitors.InternalTraversal.dp_clauseelement_list),
1561 ("propagate_to_loaders", visitors.InternalTraversal.dp_plain_obj),
1562 ("_reconcile_to_other", visitors.InternalTraversal.dp_plain_obj),
1563 ]
1564 _cache_key_traversal = None
1566 _extra_criteria: Tuple[Any, ...]
1568 _reconcile_to_other: Optional[bool]
1569 strategy: Optional[_StrategyKey]
1570 path: PathRegistry
1571 propagate_to_loaders: bool
1573 local_opts: util.immutabledict[str, Any]
1575 is_token_strategy: bool
1576 is_class_strategy: bool
1578 def __hash__(self) -> int:
1579 return id(self)
1581 def __eq__(self, other):
1582 return traversals.compare(self, other)
1584 @property
1585 def is_opts_only(self) -> bool:
1586 return bool(self.local_opts and self.strategy is None)
1588 def _clone(self, **kw: Any) -> _LoadElement:
1589 cls = self.__class__
1590 s = cls.__new__(cls)
1592 self._shallow_copy_to(s)
1593 return s
1595 def _update_opts(self, **kw: Any) -> _LoadElement:
1596 new = self._clone()
1597 new.local_opts = new.local_opts.union(kw)
1598 return new
1600 def __getstate__(self) -> Dict[str, Any]:
1601 d = self._shallow_to_dict()
1602 d["path"] = self.path.serialize()
1603 return d
1605 def __setstate__(self, state: Dict[str, Any]) -> None:
1606 state["path"] = PathRegistry.deserialize(state["path"])
1607 self._shallow_from_dict(state)
1609 def _raise_for_no_match(self, parent_loader, mapper_entities):
1610 path = parent_loader.path
1612 found_entities = False
1613 for ent in mapper_entities:
1614 ezero = ent.entity_zero
1615 if ezero:
1616 found_entities = True
1617 break
1619 if not found_entities:
1620 raise sa_exc.ArgumentError(
1621 "Query has only expression-based entities; "
1622 f"attribute loader options for {path[0]} can't "
1623 "be applied here."
1624 )
1625 else:
1626 raise sa_exc.ArgumentError(
1627 f"Mapped class {path[0]} does not apply to any of the "
1628 f"root entities in this query, e.g. "
1629 f"""{
1630 ", ".join(
1631 str(x.entity_zero)
1632 for x in mapper_entities if x.entity_zero
1633 )}. Please """
1634 "specify the full path "
1635 "from one of the root entities to the target "
1636 "attribute. "
1637 )
1639 def _adjust_effective_path_for_current_path(
1640 self, effective_path: PathRegistry, current_path: PathRegistry
1641 ) -> Optional[PathRegistry]:
1642 """receives the 'current_path' entry from an :class:`.ORMCompileState`
1643 instance, which is set during lazy loads and secondary loader strategy
1644 loads, and adjusts the given path to be relative to the
1645 current_path.
1647 E.g. given a loader path and current path:
1649 .. sourcecode:: text
1651 lp: User -> orders -> Order -> items -> Item -> keywords -> Keyword
1653 cp: User -> orders -> Order -> items
1655 The adjusted path would be:
1657 .. sourcecode:: text
1659 Item -> keywords -> Keyword
1662 """
1663 chopped_start_path = Load._chop_path(
1664 effective_path.natural_path, current_path
1665 )
1666 if not chopped_start_path:
1667 return None
1669 tokens_removed_from_start_path = len(effective_path) - len(
1670 chopped_start_path
1671 )
1673 loader_lead_path_element = self.path[tokens_removed_from_start_path]
1675 effective_path = PathRegistry.coerce(
1676 (loader_lead_path_element,) + chopped_start_path[1:]
1677 )
1679 return effective_path
1681 def _init_path(
1682 self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria
1683 ):
1684 """Apply ORM attributes and/or wildcard to an existing path, producing
1685 a new path.
1687 This method is used within the :meth:`.create` method to initialize
1688 a :class:`._LoadElement` object.
1690 """
1691 raise NotImplementedError()
1693 def _prepare_for_compile_state(
1694 self,
1695 parent_loader,
1696 compile_state,
1697 mapper_entities,
1698 reconciled_lead_entity,
1699 raiseerr,
1700 ):
1701 """implemented by subclasses."""
1702 raise NotImplementedError()
1704 def process_compile_state(
1705 self,
1706 parent_loader,
1707 compile_state,
1708 mapper_entities,
1709 reconciled_lead_entity,
1710 raiseerr,
1711 ):
1712 """populate ORMCompileState.attributes with loader state for this
1713 _LoadElement.
1715 """
1716 keys = self._prepare_for_compile_state(
1717 parent_loader,
1718 compile_state,
1719 mapper_entities,
1720 reconciled_lead_entity,
1721 raiseerr,
1722 )
1723 for key in keys:
1724 if key in compile_state.attributes:
1725 compile_state.attributes[key] = _LoadElement._reconcile(
1726 self, compile_state.attributes[key]
1727 )
1728 else:
1729 compile_state.attributes[key] = self
1731 @classmethod
1732 def create(
1733 cls,
1734 path: PathRegistry,
1735 attr: Union[_AttrType, _StrPathToken, None],
1736 strategy: Optional[_StrategyKey],
1737 wildcard_key: Optional[_WildcardKeyType],
1738 local_opts: Optional[_OptsType],
1739 propagate_to_loaders: bool,
1740 raiseerr: bool = True,
1741 attr_group: Optional[_AttrGroupType] = None,
1742 reconcile_to_other: Optional[bool] = None,
1743 extra_criteria: Optional[Tuple[Any, ...]] = None,
1744 ) -> _LoadElement:
1745 """Create a new :class:`._LoadElement` object."""
1747 opt = cls.__new__(cls)
1748 opt.path = path
1749 opt.strategy = strategy
1750 opt.propagate_to_loaders = propagate_to_loaders
1751 opt.local_opts = (
1752 util.immutabledict(local_opts) if local_opts else util.EMPTY_DICT
1753 )
1754 opt._extra_criteria = ()
1756 if reconcile_to_other is not None:
1757 opt._reconcile_to_other = reconcile_to_other
1758 elif strategy is None and not local_opts:
1759 opt._reconcile_to_other = True
1760 else:
1761 opt._reconcile_to_other = None
1763 path = opt._init_path(
1764 path, attr, wildcard_key, attr_group, raiseerr, extra_criteria
1765 )
1767 if not path:
1768 return None # type: ignore
1770 assert opt.is_token_strategy == path.is_token
1772 opt.path = path
1773 return opt
1775 def __init__(self) -> None:
1776 raise NotImplementedError()
1778 def _recurse(self) -> _LoadElement:
1779 cloned = self._clone()
1780 cloned.path = PathRegistry.coerce(self.path[:] + self.path[-2:])
1782 return cloned
1784 def _prepend_path_from(self, parent: Load) -> _LoadElement:
1785 """adjust the path of this :class:`._LoadElement` to be
1786 a subpath of that of the given parent :class:`_orm.Load` object's
1787 path.
1789 This is used by the :meth:`_orm.Load._apply_to_parent` method,
1790 which is in turn part of the :meth:`_orm.Load.options` method.
1792 """
1794 if not any(
1795 orm_util._entity_corresponds_to_use_path_impl(
1796 elem,
1797 self.path.odd_element(0),
1798 )
1799 for elem in (parent.path.odd_element(-1),)
1800 + parent.additional_source_entities
1801 ):
1802 raise sa_exc.ArgumentError(
1803 f'Attribute "{self.path[1]}" does not link '
1804 f'from element "{parent.path[-1]}".'
1805 )
1807 return self._prepend_path(parent.path)
1809 def _prepend_path(self, path: PathRegistry) -> _LoadElement:
1810 cloned = self._clone()
1812 assert cloned.strategy == self.strategy
1813 assert cloned.local_opts == self.local_opts
1814 assert cloned.is_class_strategy == self.is_class_strategy
1816 cloned.path = PathRegistry.coerce(path[0:-1] + cloned.path[:])
1818 return cloned
1820 @staticmethod
1821 def _reconcile(
1822 replacement: _LoadElement, existing: _LoadElement
1823 ) -> _LoadElement:
1824 """define behavior for when two Load objects are to be put into
1825 the context.attributes under the same key.
1827 :param replacement: ``_LoadElement`` that seeks to replace the
1828 existing one
1830 :param existing: ``_LoadElement`` that is already present.
1832 """
1833 # mapper inheritance loading requires fine-grained "block other
1834 # options" / "allow these options to be overridden" behaviors
1835 # see test_poly_loading.py
1837 if replacement._reconcile_to_other:
1838 return existing
1839 elif replacement._reconcile_to_other is False:
1840 return replacement
1841 elif existing._reconcile_to_other:
1842 return replacement
1843 elif existing._reconcile_to_other is False:
1844 return existing
1846 if existing is replacement:
1847 return replacement
1848 elif (
1849 existing.strategy == replacement.strategy
1850 and existing.local_opts == replacement.local_opts
1851 ):
1852 return replacement
1853 elif replacement.is_opts_only:
1854 existing = existing._clone()
1855 existing.local_opts = existing.local_opts.union(
1856 replacement.local_opts
1857 )
1858 existing._extra_criteria += replacement._extra_criteria
1859 return existing
1860 elif existing.is_opts_only:
1861 replacement = replacement._clone()
1862 replacement.local_opts = replacement.local_opts.union(
1863 existing.local_opts
1864 )
1865 replacement._extra_criteria += existing._extra_criteria
1866 return replacement
1867 elif replacement.path.is_token:
1868 # use 'last one wins' logic for wildcard options. this is also
1869 # kind of inconsistent vs. options that are specific paths which
1870 # will raise as below
1871 return replacement
1873 raise sa_exc.InvalidRequestError(
1874 f"Loader strategies for {replacement.path} conflict"
1875 )
1878class _AttributeStrategyLoad(_LoadElement):
1879 """Loader strategies against specific relationship or column paths.
1881 e.g.::
1883 joinedload(User.addresses)
1884 defer(Order.name)
1885 selectinload(User.orders).lazyload(Order.items)
1887 """
1889 __slots__ = ("_of_type", "_path_with_polymorphic_path")
1891 __visit_name__ = "attribute_strategy_load_element"
1893 _traverse_internals = _LoadElement._traverse_internals + [
1894 ("_of_type", visitors.ExtendedInternalTraversal.dp_multi),
1895 (
1896 "_path_with_polymorphic_path",
1897 visitors.ExtendedInternalTraversal.dp_has_cache_key,
1898 ),
1899 ]
1901 _of_type: Union[Mapper[Any], AliasedInsp[Any], None]
1902 _path_with_polymorphic_path: Optional[PathRegistry]
1904 is_class_strategy = False
1905 is_token_strategy = False
1907 def _init_path(
1908 self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria
1909 ):
1910 assert attr is not None
1911 self._of_type = None
1912 self._path_with_polymorphic_path = None
1913 insp, _, prop = _parse_attr_argument(attr)
1915 if insp.is_property:
1916 # direct property can be sent from internal strategy logic
1917 # that sets up specific loaders, such as
1918 # emit_lazyload->_lazyload_reverse
1919 # prop = found_property = attr
1920 prop = attr
1921 path = path[prop]
1923 if path.has_entity:
1924 path = path.entity_path
1925 return path
1927 elif not insp.is_attribute:
1928 # should not reach here;
1929 assert False
1931 # here we assume we have user-passed InstrumentedAttribute
1932 if not orm_util._entity_corresponds_to_use_path_impl(
1933 path[-1], attr.parent
1934 ):
1935 if raiseerr:
1936 if attr_group and attr is not attr_group[0]:
1937 raise sa_exc.ArgumentError(
1938 "Can't apply wildcard ('*') or load_only() "
1939 "loader option to multiple entities in the "
1940 "same option. Use separate options per entity."
1941 )
1942 else:
1943 _raise_for_does_not_link(path, str(attr), attr.parent)
1944 else:
1945 return None
1947 # note the essential logic of this attribute was very different in
1948 # 1.4, where there were caching failures in e.g.
1949 # test_relationship_criteria.py::RelationshipCriteriaTest::
1950 # test_selectinload_nested_criteria[True] if an existing
1951 # "_extra_criteria" on a Load object were replaced with that coming
1952 # from an attribute. This appears to have been an artifact of how
1953 # _UnboundLoad / Load interacted together, which was opaque and
1954 # poorly defined.
1955 if extra_criteria:
1956 assert not attr._extra_criteria
1957 self._extra_criteria = extra_criteria
1958 else:
1959 self._extra_criteria = attr._extra_criteria
1961 if getattr(attr, "_of_type", None):
1962 ac = attr._of_type
1963 ext_info = inspect(ac)
1964 self._of_type = ext_info
1966 self._path_with_polymorphic_path = path.entity_path[prop]
1968 path = path[prop][ext_info]
1970 else:
1971 path = path[prop]
1973 if path.has_entity:
1974 path = path.entity_path
1976 return path
1978 def _generate_extra_criteria(self, context):
1979 """Apply the current bound parameters in a QueryContext to the
1980 immediate "extra_criteria" stored with this Load object.
1982 Load objects are typically pulled from the cached version of
1983 the statement from a QueryContext. The statement currently being
1984 executed will have new values (and keys) for bound parameters in the
1985 extra criteria which need to be applied by loader strategies when
1986 they handle this criteria for a result set.
1988 """
1990 assert (
1991 self._extra_criteria
1992 ), "this should only be called if _extra_criteria is present"
1994 orig_query = context.compile_state.select_statement
1995 current_query = context.query
1997 # NOTE: while it seems like we should not do the "apply" operation
1998 # here if orig_query is current_query, skipping it in the "optimized"
1999 # case causes the query to be different from a cache key perspective,
2000 # because we are creating a copy of the criteria which is no longer
2001 # the same identity of the _extra_criteria in the loader option
2002 # itself. cache key logic produces a different key for
2003 # (A, copy_of_A) vs. (A, A), because in the latter case it shortens
2004 # the second part of the key to just indicate on identity.
2006 # if orig_query is current_query:
2007 # not cached yet. just do the and_()
2008 # return and_(*self._extra_criteria)
2010 k1 = orig_query._generate_cache_key()
2011 k2 = current_query._generate_cache_key()
2013 return k2._apply_params_to_element(k1, and_(*self._extra_criteria))
2015 def _set_of_type_info(self, context, current_path):
2016 assert self._path_with_polymorphic_path
2018 pwpi = self._of_type
2019 assert pwpi
2020 if not pwpi.is_aliased_class:
2021 pwpi = inspect(
2022 orm_util.AliasedInsp._with_polymorphic_factory(
2023 pwpi.mapper.base_mapper,
2024 (pwpi.mapper,),
2025 aliased=True,
2026 _use_mapper_path=True,
2027 )
2028 )
2029 start_path = self._path_with_polymorphic_path
2030 if current_path:
2031 new_path = self._adjust_effective_path_for_current_path(
2032 start_path, current_path
2033 )
2034 if new_path is None:
2035 return
2036 start_path = new_path
2038 key = ("path_with_polymorphic", start_path.natural_path)
2039 if key in context:
2040 existing_aliased_insp = context[key]
2041 this_aliased_insp = pwpi
2042 new_aliased_insp = existing_aliased_insp._merge_with(
2043 this_aliased_insp
2044 )
2045 context[key] = new_aliased_insp
2046 else:
2047 context[key] = pwpi
2049 def _prepare_for_compile_state(
2050 self,
2051 parent_loader,
2052 compile_state,
2053 mapper_entities,
2054 reconciled_lead_entity,
2055 raiseerr,
2056 ):
2057 # _AttributeStrategyLoad
2059 current_path = compile_state.current_path
2060 is_refresh = compile_state.compile_options._for_refresh_state
2061 assert not self.path.is_token
2063 if is_refresh and not self.propagate_to_loaders:
2064 return []
2066 if self._of_type:
2067 # apply additional with_polymorphic alias that may have been
2068 # generated. this has to happen even if this is a defaultload
2069 self._set_of_type_info(compile_state.attributes, current_path)
2071 # omit setting loader attributes for a "defaultload" type of option
2072 if not self.strategy and not self.local_opts:
2073 return []
2075 if raiseerr and not reconciled_lead_entity:
2076 self._raise_for_no_match(parent_loader, mapper_entities)
2078 if self.path.has_entity:
2079 effective_path = self.path.parent
2080 else:
2081 effective_path = self.path
2083 if current_path:
2084 assert effective_path is not None
2085 effective_path = self._adjust_effective_path_for_current_path(
2086 effective_path, current_path
2087 )
2088 if effective_path is None:
2089 return []
2091 return [("loader", cast(PathRegistry, effective_path).natural_path)]
2093 def __getstate__(self):
2094 d = super().__getstate__()
2096 # can't pickle this. See
2097 # test_pickled.py -> test_lazyload_extra_criteria_not_supported
2098 # where we should be emitting a warning for the usual case where this
2099 # would be non-None
2100 d["_extra_criteria"] = ()
2102 if self._path_with_polymorphic_path:
2103 d["_path_with_polymorphic_path"] = (
2104 self._path_with_polymorphic_path.serialize()
2105 )
2107 if self._of_type:
2108 if self._of_type.is_aliased_class:
2109 d["_of_type"] = None
2110 elif self._of_type.is_mapper:
2111 d["_of_type"] = self._of_type.class_
2112 else:
2113 assert False, "unexpected object for _of_type"
2115 return d
2117 def __setstate__(self, state):
2118 super().__setstate__(state)
2120 if state.get("_path_with_polymorphic_path", None):
2121 self._path_with_polymorphic_path = PathRegistry.deserialize(
2122 state["_path_with_polymorphic_path"]
2123 )
2124 else:
2125 self._path_with_polymorphic_path = None
2127 if state.get("_of_type", None):
2128 self._of_type = inspect(state["_of_type"])
2129 else:
2130 self._of_type = None
2133class _TokenStrategyLoad(_LoadElement):
2134 """Loader strategies against wildcard attributes
2136 e.g.::
2138 raiseload("*")
2139 Load(User).lazyload("*")
2140 defer("*")
2141 load_only(User.name, User.email) # will create a defer('*')
2142 joinedload(User.addresses).raiseload("*")
2144 """
2146 __visit_name__ = "token_strategy_load_element"
2148 inherit_cache = True
2149 is_class_strategy = False
2150 is_token_strategy = True
2152 def _init_path(
2153 self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria
2154 ):
2155 # assert isinstance(attr, str) or attr is None
2156 if attr is not None:
2157 default_token = attr.endswith(_DEFAULT_TOKEN)
2158 if attr.endswith(_WILDCARD_TOKEN) or default_token:
2159 if wildcard_key:
2160 attr = f"{wildcard_key}:{attr}"
2162 path = path.token(attr)
2163 return path
2164 else:
2165 raise sa_exc.ArgumentError(
2166 "Strings are not accepted for attribute names in loader "
2167 "options; please use class-bound attributes directly."
2168 )
2169 return path
2171 def _prepare_for_compile_state(
2172 self,
2173 parent_loader,
2174 compile_state,
2175 mapper_entities,
2176 reconciled_lead_entity,
2177 raiseerr,
2178 ):
2179 # _TokenStrategyLoad
2181 current_path = compile_state.current_path
2182 is_refresh = compile_state.compile_options._for_refresh_state
2184 assert self.path.is_token
2186 if is_refresh and not self.propagate_to_loaders:
2187 return []
2189 # omit setting attributes for a "defaultload" type of option
2190 if not self.strategy and not self.local_opts:
2191 return []
2193 effective_path = self.path
2194 if reconciled_lead_entity:
2195 effective_path = PathRegistry.coerce(
2196 (reconciled_lead_entity,) + effective_path.path[1:]
2197 )
2199 if current_path:
2200 new_effective_path = self._adjust_effective_path_for_current_path(
2201 effective_path, current_path
2202 )
2203 if new_effective_path is None:
2204 return []
2205 effective_path = new_effective_path
2207 # for a wildcard token, expand out the path we set
2208 # to encompass everything from the query entity on
2209 # forward. not clear if this is necessary when current_path
2210 # is set.
2212 return [
2213 ("loader", natural_path)
2214 for natural_path in (
2215 cast(
2216 TokenRegistry, effective_path
2217 )._generate_natural_for_superclasses()
2218 )
2219 ]
2222class _ClassStrategyLoad(_LoadElement):
2223 """Loader strategies that deals with a class as a target, not
2224 an attribute path
2226 e.g.::
2228 q = s.query(Person).options(
2229 selectin_polymorphic(Person, [Engineer, Manager])
2230 )
2232 """
2234 inherit_cache = True
2235 is_class_strategy = True
2236 is_token_strategy = False
2238 __visit_name__ = "class_strategy_load_element"
2240 def _init_path(
2241 self, path, attr, wildcard_key, attr_group, raiseerr, extra_criteria
2242 ):
2243 return path
2245 def _prepare_for_compile_state(
2246 self,
2247 parent_loader,
2248 compile_state,
2249 mapper_entities,
2250 reconciled_lead_entity,
2251 raiseerr,
2252 ):
2253 # _ClassStrategyLoad
2255 current_path = compile_state.current_path
2256 is_refresh = compile_state.compile_options._for_refresh_state
2258 if is_refresh and not self.propagate_to_loaders:
2259 return []
2261 # omit setting attributes for a "defaultload" type of option
2262 if not self.strategy and not self.local_opts:
2263 return []
2265 effective_path = self.path
2267 if current_path:
2268 new_effective_path = self._adjust_effective_path_for_current_path(
2269 effective_path, current_path
2270 )
2271 if new_effective_path is None:
2272 return []
2273 effective_path = new_effective_path
2275 return [("loader", effective_path.natural_path)]
2278def _generate_from_keys(
2279 meth: Callable[..., _AbstractLoad],
2280 keys: Tuple[_AttrType, ...],
2281 chained: bool,
2282 kw: Any,
2283) -> _AbstractLoad:
2284 lead_element: Optional[_AbstractLoad] = None
2286 attr: Any
2287 for is_default, _keys in (True, keys[0:-1]), (False, keys[-1:]):
2288 for attr in _keys:
2289 if isinstance(attr, str):
2290 if attr.startswith("." + _WILDCARD_TOKEN):
2291 util.warn_deprecated(
2292 "The undocumented `.{WILDCARD}` format is "
2293 "deprecated "
2294 "and will be removed in a future version as "
2295 "it is "
2296 "believed to be unused. "
2297 "If you have been using this functionality, "
2298 "please "
2299 "comment on Issue #4390 on the SQLAlchemy project "
2300 "tracker.",
2301 version="1.4",
2302 )
2303 attr = attr[1:]
2305 if attr == _WILDCARD_TOKEN:
2306 if is_default:
2307 raise sa_exc.ArgumentError(
2308 "Wildcard token cannot be followed by "
2309 "another entity",
2310 )
2312 if lead_element is None:
2313 lead_element = _WildcardLoad()
2315 lead_element = meth(lead_element, _DEFAULT_TOKEN, **kw)
2317 else:
2318 raise sa_exc.ArgumentError(
2319 "Strings are not accepted for attribute names in "
2320 "loader options; please use class-bound "
2321 "attributes directly.",
2322 )
2323 else:
2324 if lead_element is None:
2325 _, lead_entity, _ = _parse_attr_argument(attr)
2326 lead_element = Load(lead_entity)
2328 if is_default:
2329 if not chained:
2330 lead_element = lead_element.defaultload(attr)
2331 else:
2332 lead_element = meth(
2333 lead_element, attr, _is_chain=True, **kw
2334 )
2335 else:
2336 lead_element = meth(lead_element, attr, **kw)
2338 assert lead_element
2339 return lead_element
2342def _parse_attr_argument(
2343 attr: _AttrType,
2344) -> Tuple[InspectionAttr, _InternalEntityType[Any], MapperProperty[Any]]:
2345 """parse an attribute or wildcard argument to produce an
2346 :class:`._AbstractLoad` instance.
2348 This is used by the standalone loader strategy functions like
2349 ``joinedload()``, ``defer()``, etc. to produce :class:`_orm.Load` or
2350 :class:`._WildcardLoad` objects.
2352 """
2353 try:
2354 # TODO: need to figure out this None thing being returned by
2355 # inspect(), it should not have None as an option in most cases
2356 # if at all
2357 insp: InspectionAttr = inspect(attr) # type: ignore
2358 except sa_exc.NoInspectionAvailable as err:
2359 raise sa_exc.ArgumentError(
2360 "expected ORM mapped attribute for loader strategy argument"
2361 ) from err
2363 lead_entity: _InternalEntityType[Any]
2365 if insp_is_mapper_property(insp):
2366 lead_entity = insp.parent
2367 prop = insp
2368 elif insp_is_attribute(insp):
2369 lead_entity = insp.parent
2370 prop = insp.prop
2371 else:
2372 raise sa_exc.ArgumentError(
2373 "expected ORM mapped attribute for loader strategy argument"
2374 )
2376 return insp, lead_entity, prop
2379def loader_unbound_fn(fn: _FN) -> _FN:
2380 """decorator that applies docstrings between standalone loader functions
2381 and the loader methods on :class:`._AbstractLoad`.
2383 """
2384 bound_fn = getattr(_AbstractLoad, fn.__name__)
2385 fn_doc = bound_fn.__doc__
2386 bound_fn.__doc__ = f"""Produce a new :class:`_orm.Load` object with the
2387:func:`_orm.{fn.__name__}` option applied.
2389See :func:`_orm.{fn.__name__}` for usage examples.
2391"""
2393 fn.__doc__ = fn_doc
2394 return fn
2397# standalone functions follow. docstrings are filled in
2398# by the ``@loader_unbound_fn`` decorator.
2401@loader_unbound_fn
2402def contains_eager(*keys: _AttrType, **kw: Any) -> _AbstractLoad:
2403 return _generate_from_keys(Load.contains_eager, keys, True, kw)
2406@loader_unbound_fn
2407def load_only(*attrs: _AttrType, raiseload: bool = False) -> _AbstractLoad:
2408 # TODO: attrs against different classes. we likely have to
2409 # add some extra state to Load of some kind
2410 _, lead_element, _ = _parse_attr_argument(attrs[0])
2411 return Load(lead_element).load_only(*attrs, raiseload=raiseload)
2414@loader_unbound_fn
2415def joinedload(*keys: _AttrType, **kw: Any) -> _AbstractLoad:
2416 return _generate_from_keys(Load.joinedload, keys, False, kw)
2419@loader_unbound_fn
2420def subqueryload(*keys: _AttrType) -> _AbstractLoad:
2421 return _generate_from_keys(Load.subqueryload, keys, False, {})
2424@loader_unbound_fn
2425def selectinload(
2426 *keys: _AttrType, recursion_depth: Optional[int] = None
2427) -> _AbstractLoad:
2428 return _generate_from_keys(
2429 Load.selectinload, keys, False, {"recursion_depth": recursion_depth}
2430 )
2433@loader_unbound_fn
2434def lazyload(*keys: _AttrType) -> _AbstractLoad:
2435 return _generate_from_keys(Load.lazyload, keys, False, {})
2438@loader_unbound_fn
2439def immediateload(
2440 *keys: _AttrType, recursion_depth: Optional[int] = None
2441) -> _AbstractLoad:
2442 return _generate_from_keys(
2443 Load.immediateload, keys, False, {"recursion_depth": recursion_depth}
2444 )
2447@loader_unbound_fn
2448def noload(*keys: _AttrType) -> _AbstractLoad:
2449 return _generate_from_keys(Load.noload, keys, False, {})
2452@loader_unbound_fn
2453def raiseload(*keys: _AttrType, **kw: Any) -> _AbstractLoad:
2454 return _generate_from_keys(Load.raiseload, keys, False, kw)
2457@loader_unbound_fn
2458def defaultload(*keys: _AttrType) -> _AbstractLoad:
2459 return _generate_from_keys(Load.defaultload, keys, False, {})
2462@loader_unbound_fn
2463def defer(
2464 key: _AttrType, *addl_attrs: _AttrType, raiseload: bool = False
2465) -> _AbstractLoad:
2466 if addl_attrs:
2467 util.warn_deprecated(
2468 "The *addl_attrs on orm.defer is deprecated. Please use "
2469 "method chaining in conjunction with defaultload() to "
2470 "indicate a path.",
2471 version="1.3",
2472 )
2474 if raiseload:
2475 kw = {"raiseload": raiseload}
2476 else:
2477 kw = {}
2479 return _generate_from_keys(Load.defer, (key,) + addl_attrs, False, kw)
2482@loader_unbound_fn
2483def undefer(key: _AttrType, *addl_attrs: _AttrType) -> _AbstractLoad:
2484 if addl_attrs:
2485 util.warn_deprecated(
2486 "The *addl_attrs on orm.undefer is deprecated. Please use "
2487 "method chaining in conjunction with defaultload() to "
2488 "indicate a path.",
2489 version="1.3",
2490 )
2491 return _generate_from_keys(Load.undefer, (key,) + addl_attrs, False, {})
2494@loader_unbound_fn
2495def undefer_group(name: str) -> _AbstractLoad:
2496 element = _WildcardLoad()
2497 return element.undefer_group(name)
2500@loader_unbound_fn
2501def with_expression(
2502 key: _AttrType, expression: _ColumnExpressionArgument[Any]
2503) -> _AbstractLoad:
2504 return _generate_from_keys(
2505 Load.with_expression, (key,), False, {"expression": expression}
2506 )
2509@loader_unbound_fn
2510def selectin_polymorphic(
2511 base_cls: _EntityType[Any], classes: Iterable[Type[Any]]
2512) -> _AbstractLoad:
2513 ul = Load(base_cls)
2514 return ul.selectin_polymorphic(classes)
2517def _raise_for_does_not_link(path, attrname, parent_entity):
2518 if len(path) > 1:
2519 path_is_of_type = path[-1].entity is not path[-2].mapper.class_
2520 if insp_is_aliased_class(parent_entity):
2521 parent_entity_str = str(parent_entity)
2522 else:
2523 parent_entity_str = parent_entity.class_.__name__
2525 raise sa_exc.ArgumentError(
2526 f'ORM mapped entity or attribute "{attrname}" does not '
2527 f'link from relationship "{path[-2]}%s".%s'
2528 % (
2529 f".of_type({path[-1]})" if path_is_of_type else "",
2530 (
2531 " Did you mean to use "
2532 f'"{path[-2]}'
2533 f'.of_type({parent_entity_str})" or "loadopt.options('
2534 f"selectin_polymorphic({path[-2].mapper.class_.__name__}, "
2535 f'[{parent_entity_str}]), ...)" ?'
2536 if not path_is_of_type
2537 and not path[-1].is_aliased_class
2538 and orm_util._entity_corresponds_to(
2539 path.entity, inspect(parent_entity).mapper
2540 )
2541 else ""
2542 ),
2543 )
2544 )
2545 else:
2546 raise sa_exc.ArgumentError(
2547 f'ORM mapped attribute "{attrname}" does not '
2548 f'link mapped class "{path[-1]}"'
2549 )