Mike Bayer avatar Mike Bayer committed e92d070

- remove all the fanfare from dynamic_loader() and de-emphasize it in
the docs for [ticket:2080]. Not deprecating for now.

Comments (0)

Files changed (3)

doc/build/orm/collections.rst

 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:
 .. sourcecode:: python+sql
 
     mapper(User, users_table, properties={
-        'posts': dynamic_loader(Post)
+        'posts': relationship(Post, lazy="dynamic")
     })
 
     jack = session.query(User).get(id)
 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
 
 
 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
 ~~~~~~~~~~~~~~~

doc/build/orm/relationships.rst

 
 .. autofunction:: relation
 
+.. autofunction:: dynamic_loader
 
+

lib/sqlalchemy/orm/__init__.py

 
     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.
 
 
 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)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.