- 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 98de8e20595851f6e683fd9c5845d2be913c2a0a..4d768e8c4a2433d6f41ee60c3198005d8570143b 100644 (file)
--- 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 0c68bcccc9b67e798c697d4685b8eb0ac71deafb..682b83d5f168836bd407b1bf086c3a2dc8cd3bfd 100644 (file)
--- 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 6e4a552c94e8754f71d844059f96e191ab0432ef..8a0312d5a91754bc0f96872e4220f814ec8b43a0 100644 (file)
--- 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)