From: Mike Bayer Date: Sun, 20 Mar 2011 18:54:35 +0000 (-0400) Subject: - remove all the fanfare from dynamic_loader() and de-emphasize it in X-Git-Tag: rel_0_7b3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b6423d26280cac2ff74ab1450ce5549789ffa61e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - remove all the fanfare from dynamic_loader() and de-emphasize it in the docs for [ticket:2080]. Not deprecating for now. --- diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index 98de8e2059..4d768e8c4a 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -30,8 +30,8 @@ loading of child items both at load time as well as deletion time. Dynamic Relationship Loaders ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The most useful by far is the :func:`~sqlalchemy.orm.dynamic_loader` -relationship. This is a variant of :func:`~sqlalchemy.orm.relationship` which +A key feature to enable management of a large collection is the so-called "dynamic" +relationship. This is an optional form of :func:`~sqlalchemy.orm.relationship` which returns a :class:`~sqlalchemy.orm.query.Query` object in place of a collection when accessed. :func:`~sqlalchemy.orm.query.Query.filter` criterion may be applied as well as limits and offsets, either explicitly or via array slices: @@ -39,7 +39,7 @@ applied as well as limits and offsets, either explicitly or via array slices: .. sourcecode:: python+sql mapper(User, users_table, properties={ - 'posts': dynamic_loader(Post) + 'posts': relationship(Post, lazy="dynamic") }) jack = session.query(User).get(id) @@ -65,7 +65,8 @@ enabled on the :class:`.Session` in use, this will occur automatically each time the collection is about to emit a query. -To place a dynamic relationship on a backref, use ``lazy='dynamic'``: +To place a dynamic relationship on a backref, use the :func:`~.orm.backref` +function in conjunction with ``lazy='dynamic'``: .. sourcecode:: python+sql @@ -75,7 +76,9 @@ To place a dynamic relationship on a backref, use ``lazy='dynamic'``: Note that eager/lazy loading options cannot be used in conjunction dynamic relationships at this time. -.. autofunction:: dynamic_loader +.. note:: The :func:`~.orm.dynamic_loader` function is essentially the same + as :func:`~.orm.relationship` with the ``lazy='dynamic'`` argument specified. + Setting Noload ~~~~~~~~~~~~~~~ diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index 0c68bcccc9..682b83d5f1 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -791,4 +791,6 @@ Relationships API .. autofunction:: relation +.. autofunction:: dynamic_loader + diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 6e4a552c94..8a0312d5a9 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -531,51 +531,31 @@ def relation(*arg, **kw): return relationship(*arg, **kw) -def dynamic_loader(argument, secondary=None, primaryjoin=None, - secondaryjoin=None, foreign_keys=None, backref=None, - post_update=False, cascade=False, remote_side=None, - enable_typechecks=True, passive_deletes=False, doc=None, - order_by=None, comparator_factory=None, query_class=None): +def dynamic_loader(argument, **kw): """Construct a dynamically-loading mapper property. - This property is similar to :func:`relationship`, except read - operations return an active :class:`.Query` object which reads from - the database when accessed. Items may be appended to the - attribute via ``append()``, or removed via ``remove()``; changes - will be persisted to the database during a :meth:`Sesion.flush`. - However, no other Python list or collection mutation operations - are available. + This is essentially the same as + using the ``lazy='dynamic'`` argument with :func:`relationship`:: - A subset of arguments available to :func:`relationship` are available - here. + dynamic_loader(SomeClass) + + # vs. + + relationship(SomeClass, lazy="dynamic") - :param argument: - a class or :class:`.Mapper` instance, representing the target of - the relationship. + A :func:`relationship` that is "dynamic" features the behavior + that read operations return an active :class:`.Query` object which + reads from the database when accessed. Items may be appended to the + attribute via ``append()``, or removed via ``remove()``; changes will be + persisted to the database during a :meth:`Sesion.flush`. However, no other + Python list or collection mutation operations are available. - :param secondary: - for a many-to-many relationship, specifies the intermediary - table. The *secondary* keyword argument should generally only - be used for a table that is not otherwise expressed in any class - mapping. In particular, using the Association Object Pattern is - generally mutually exclusive with the use of the *secondary* - keyword argument. - - :param query_class: - Optional, a custom Query subclass to be used as the basis for - dynamic collection. + All arguments accepted by :func:`relationship` are + accepted here, other than ``lazy`` which is fixed at ``dynamic``. """ - from sqlalchemy.orm.dynamic import DynaLoader - - return RelationshipProperty( - argument, secondary=secondary, primaryjoin=primaryjoin, - secondaryjoin=secondaryjoin, foreign_keys=foreign_keys, - backref=backref, - post_update=post_update, cascade=cascade, remote_side=remote_side, - enable_typechecks=enable_typechecks, passive_deletes=passive_deletes, - order_by=order_by, comparator_factory=comparator_factory,doc=doc, - strategy_class=DynaLoader, query_class=query_class) + kw['lazy'] = 'dynamic' + return relationship(argument, **kw) def column_property(*args, **kwargs): """Provide a column-level property for use with a Mapper. @@ -678,11 +658,13 @@ def composite(class_, *cols, **kwargs): def backref(name, **kwargs): - """Create a back reference with explicit arguments, which are the same + """Create a back reference with explicit keyword arguments, which are the same arguments one can send to :func:`relationship`. - Used with the `backref` keyword argument to :func:`relationship` in - place of a string argument. + Used with the ``backref`` keyword argument to :func:`relationship` in + place of a string argument, e.g.:: + + 'items':relationship(SomeItem, backref=backref('parent', lazy='subquery')) """ return (name, kwargs)