diff options
Diffstat (limited to 'lib/sqlalchemy/orm/strategy_options.py')
| -rw-r--r-- | lib/sqlalchemy/orm/strategy_options.py | 109 |
1 files changed, 59 insertions, 50 deletions
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index 6475f79de..2fd628d0b 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -34,26 +34,29 @@ from ..sql.traversals import HasCacheKey class Load(HasCacheKey, Generative, MapperOption): """Represents loader options which modify the state of a - :class:`.Query` in order to affect how various mapped attributes are + :class:`_query.Query` in order to affect how various mapped attributes are loaded. - The :class:`.Load` object is in most cases used implicitly behind the - scenes when one makes use of a query option like :func:`.joinedload`, - :func:`.defer`, or similar. However, the :class:`.Load` object + The :class:`_orm.Load` object is in most cases used implicitly behind the + scenes when one makes use of a query option like :func:`_orm.joinedload`, + :func:`.defer`, or similar. However, the :class:`_orm.Load` object can also be used directly, and in some cases can be useful. - To use :class:`.Load` directly, instantiate it with the target mapped + To use :class:`_orm.Load` directly, instantiate it with the target mapped class as the argument. This style of usage is - useful when dealing with a :class:`.Query` that has multiple entities:: + useful when dealing with a :class:`_query.Query` + that has multiple entities:: myopt = Load(MyClass).joinedload("widgets") - The above ``myopt`` can now be used with :meth:`.Query.options`, where it + The above ``myopt`` can now be used with :meth:`_query.Query.options`, + where it will only take effect for the ``MyClass`` entity:: session.query(MyClass, MyOtherClass).options(myopt) - One case where :class:`.Load` is useful as public API is when specifying + One case where :class:`_orm.Load` + is useful as public API is when specifying "wildcard" options that only take effect for a certain class:: session.query(Order).options(Load(Order).lazyload('*')) @@ -363,7 +366,8 @@ class Load(HasCacheKey, Generative, MapperOption): @_generative def options(self, *opts): - r"""Apply a series of options as sub-options to this :class:`.Load` + r"""Apply a series of options as sub-options to this + :class:`_orm.Load` object. E.g.:: @@ -379,8 +383,8 @@ class Load(HasCacheKey, Generative, MapperOption): ) :param \*opts: A series of loader option objects (ultimately - :class:`.Load` objects) which should be applied to the path - specified by this :class:`.Load` object. + :class:`_orm.Load` objects) which should be applied to the path + specified by this :class:`_orm.Load` object. .. versionadded:: 1.3.6 @@ -555,8 +559,8 @@ class Load(HasCacheKey, Generative, MapperOption): class _UnboundLoad(Load): """Represent a loader option that isn't tied to a root entity. - The loader option will produce an entity-linked :class:`.Load` - object when it is passed :meth:`.Query.options`. + The loader option will produce an entity-linked :class:`_orm.Load` + object when it is passed :meth:`_query.Query.options`. This provides compatibility with the traditional system of freestanding options, e.g. ``joinedload('x.y.z')``. @@ -981,7 +985,7 @@ class loader_option(object): def _add_unbound_fn(self, fn): self._unbound_fn = fn fn_doc = self.fn.__doc__ - self.fn.__doc__ = """Produce a new :class:`.Load` object with the + self.fn.__doc__ = """Produce a new :class:`_orm.Load` object with the :func:`_orm.%(name)s` option applied. See :func:`_orm.%(name)s` for usage examples. @@ -1029,7 +1033,7 @@ def contains_eager(loadopt, attr, alias=None): r"""Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. - This function is part of the :class:`.Load` interface and supports + 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 @@ -1123,7 +1127,7 @@ def load_only(loadopt, *attrs): of column-based attribute names should be loaded; all others will be deferred. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Example - given a class ``User``, load only the ``name`` and ``fullname`` @@ -1139,8 +1143,9 @@ def load_only(loadopt, *attrs): subqueryload("addresses").load_only("email_address") ) - For a :class:`.Query` that has multiple entities, the lead entity can be - specifically referred to using the :class:`.Load` constructor:: + For a :class:`_query.Query` that has multiple entities, + the lead entity can be + specifically referred to using the :class:`_orm.Load` constructor:: session.query(User, Address).join(User.addresses).options( Load(User).load_only("name", "fullname"), @@ -1170,7 +1175,7 @@ def joinedload(loadopt, attr, innerjoin=None): """Indicate that the given attribute should be loaded using joined eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1221,7 +1226,7 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: The "unnested" flag does **not** affect the JOIN rendered from a many-to-many association table, e.g. a table configured - as :paramref:`.relationship.secondary`, to the target table; for + as :paramref:`_orm.relationship.secondary`, to the target table; for correctness of results, these joins are always INNER and are therefore right-nested if linked to an OUTER join. @@ -1233,15 +1238,17 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: - The joins produced by :func:`.orm.joinedload` are **anonymously + The joins produced by :func:`_orm.joinedload` are **anonymously aliased**. The criteria by which the join proceeds cannot be - modified, nor can the :class:`.Query` refer to these joins in any way, + modified, nor can the :class:`_query.Query` + refer to these joins in any way, including ordering. See :ref:`zen_of_eager_loading` for further detail. To produce a specific SQL JOIN which is explicitly available, use - :meth:`.Query.join`. To combine explicit JOINs with eager loading - of collections, use :func:`.orm.contains_eager`; see + :meth:`_query.Query.join`. + To combine explicit JOINs with eager loading + of collections, use :func:`_orm.contains_eager`; see :ref:`contains_eager`. .. seealso:: @@ -1267,7 +1274,7 @@ def subqueryload(loadopt, attr): """Indicate that the given attribute should be loaded using subquery eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1305,7 +1312,7 @@ def selectinload(loadopt, attr): """Indicate that the given attribute should be loaded using SELECT IN eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1344,7 +1351,7 @@ def lazyload(loadopt, attr): """Indicate that the given attribute should be loaded using "lazy" loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1371,7 +1378,7 @@ def immediateload(loadopt, attr): by the :func:`.selectinload` option, which performs the same task more efficiently by emitting a SELECT for all loaded objects. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1394,11 +1401,11 @@ def immediateload(*keys): def noload(loadopt, attr): """Indicate that the given relationship attribute should remain unloaded. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. - :func:`.orm.noload` applies to :func:`.relationship` attributes; for - column-based attributes, see :func:`.orm.defer`. + :func:`_orm.noload` applies to :func:`_orm.relationship` attributes; for + column-based attributes, see :func:`_orm.defer`. .. seealso:: @@ -1418,7 +1425,7 @@ def noload(*keys): def raiseload(loadopt, attr, sql_only=False): """Indicate that the given attribute should raise an error if accessed. - A relationship attribute configured with :func:`.orm.raiseload` will + A relationship attribute configured with :func:`_orm.raiseload` will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The typical way this is useful is when an application is attempting to ensure that all relationship attributes that are accessed in a particular context @@ -1426,7 +1433,8 @@ def raiseload(loadopt, attr, sql_only=False): to read through SQL logs to ensure lazy loads aren't occurring, this strategy will cause them to raise immediately. - :func:`.orm.raiseload` applies to :func:`.relationship` attributes only. + :func:`_orm.raiseload` applies to :func:`_orm.relationship` + attributes only. In order to apply raise-on-SQL behavior to a column-based attribute, use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer` loader option. @@ -1436,7 +1444,7 @@ def raiseload(loadopt, attr, sql_only=False): related value should just be None due to missing keys. When False, the strategy will raise for all varieties of relationship loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. @@ -1487,7 +1495,7 @@ def defaultload(loadopt, attr): .. seealso:: - :meth:`.Load.options` - allows for complex hierarchical + :meth:`_orm.Load.options` - allows for complex hierarchical loader option structures with less verbosity than with individual :func:`.defaultload` directives. @@ -1509,7 +1517,7 @@ def defer(loadopt, key, raiseload=False): r"""Indicate that the given column-oriented attribute should be deferred, e.g. not loaded until accessed. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. e.g.:: @@ -1527,12 +1535,13 @@ def defer(loadopt, key, raiseload=False): To specify a deferred load of an attribute on a related class, the path can be specified one token at a time, specifying the loading style for each link along the chain. To leave the loading style - for a link unchanged, use :func:`.orm.defaultload`:: + for a link unchanged, use :func:`_orm.defaultload`:: session.query(MyClass).options(defaultload("someattr").defer("some_column")) - A :class:`.Load` object that is present on a certain path can have - :meth:`.Load.defer` called multiple times, each will operate on the same + A :class:`_orm.Load` object that is present on a certain path can have + :meth:`_orm.Load.defer` called multiple times, + each will operate on the same parent entity:: @@ -1559,7 +1568,7 @@ def defer(loadopt, key, raiseload=False): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.defer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.defer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1569,7 +1578,7 @@ def defer(loadopt, key, raiseload=False): :ref:`deferred` - :func:`.orm.undefer` + :func:`_orm.undefer` """ strategy = {"deferred": True, "instrument": True} @@ -1600,7 +1609,7 @@ def undefer(loadopt, key): The column being undeferred is typically set up on the mapping as a :func:`.deferred` attribute. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Examples:: @@ -1622,7 +1631,7 @@ def undefer(loadopt, key): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.undefer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.undefer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1631,9 +1640,9 @@ def undefer(loadopt, key): :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer_group` + :func:`_orm.undefer_group` """ return loadopt.set_column_strategy( @@ -1669,21 +1678,21 @@ def undefer_group(loadopt, name): To undefer a group of attributes on a related entity, the path can be spelled out using relationship loader options, such as - :func:`.orm.defaultload`:: + :func:`_orm.defaultload`:: session.query(MyClass).options( defaultload("someattr").undefer_group("large_attrs")) - .. versionchanged:: 0.9.0 :func:`.orm.undefer_group` is now specific to a + .. versionchanged:: 0.9.0 :func:`_orm.undefer_group` is now specific to a particular entity load path. .. seealso:: :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer` + :func:`_orm.undefer` """ return loadopt.set_column_strategy( @@ -1700,7 +1709,7 @@ def undefer_group(name): def with_expression(loadopt, key, expression): r"""Apply an ad-hoc SQL expression to a "deferred expression" attribute. - This option is used in conjunction with the :func:`.orm.query_expression` + This option is used in conjunction with the :func:`_orm.query_expression` mapper-level construct that indicates an attribute which should be the target of an ad-hoc SQL expression. |