- add cross-linking for passive_deletes / passive_updates

diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index 053369baa7bea305103f9bd4b38fd0dc9e4e8cd5..354cfbca458d9e049aecf3b8178fac5c0d05bb7c 100644 (file)
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -112,7 +112,7 @@ from the database, the ``children`` collection stays empty.
 Using Passive Deletes
 ----------------------
 
-Use ``passive_deletes=True`` to disable child object loading on a DELETE
+Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE
 operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database
 to automatically cascade deletes to child objects::
 
@@ -142,7 +142,7 @@ to automatically cascade deletes to child objects::
     * When using SQLite, foreign key support must be enabled explicitly.
       See :ref:`sqlite_foreign_keys` for details.
 
-When ``passive_deletes`` is applied, the ``children`` relationship will not be
+When :paramref:`~.relationship.passive_deletes` is applied, the ``children`` relationship will not be
 loaded into memory when an instance of ``MyClass`` is marked for deletion. The
 ``cascade="all, delete-orphan"`` *will* take effect for instances of
 ``MyOtherClass`` which are currently present in the session; however for

diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index 67a41c8087df9ec3d8941af1557363908b03baa6..e5534534a289fac01895164d71c65b3a0bd24f3d 100644 (file)
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -221,8 +221,8 @@ There are several possibilities here:
   this feature, the database itself can be made to automatically delete rows in the
   "secondary" table as referencing rows in "child" are deleted.   SQLAlchemy
   can be instructed to forego actively loading in the ``Child.parents``
-  collection in this case using the ``passive_deletes=True`` directive
-  on :func:`.relationship`; see :ref:`passive_deletes` for more details
+  collection in this case using the :paramref:`~.relationship.passive_deletes`
+  directive on :func:`.relationship`; see :ref:`passive_deletes` for more details
   on this.
 
 Note again, these behaviors are *only* relevant to the ``secondary`` option
@@ -1354,13 +1354,13 @@ of sync for any moment.
 
 For databases that don't support this, such as SQLite and
 MySQL without their referential integrity options turned
-on, the ``passive_updates`` flag can
+on, the :paramref:`~.relationship.passive_updates` flag can
 be set to ``False``, most preferably on a one-to-many or
 many-to-many :func:`.relationship`, which instructs
 SQLAlchemy to issue UPDATE statements individually for
 objects referenced in the collection, loading them into
 memory if not already locally present. The
-``passive_updates`` flag can also be ``False`` in
+:paramref:`~.relationship.passive_updates` flag can also be ``False`` in
 conjunction with ON UPDATE CASCADE functionality,
 although in that case the unit of work will be issuing
 extra SELECT and UPDATE statements unnecessarily.
@@ -1385,16 +1385,17 @@ A typical mutable primary key setup might look like::
                     ForeignKey('user.username', onupdate="cascade")
                 )
 
-``passive_updates`` is set to ``True`` by default,
+:paramref:`~.relationship.passive_updates` is set to ``True`` by default,
 indicating that ON UPDATE CASCADE is expected to be in
 place in the usual case for foreign keys that expect
 to have a mutating parent key.
 
-``passive_updates=False`` may be configured on any
+A :paramref:`~.relationship.passive_updates` setting of False may be configured on any
 direction of relationship, i.e. one-to-many, many-to-one,
 and many-to-many, although it is much more effective when
 placed just on the one-to-many or many-to-many side.
-Configuring the ``passive_updates=False`` only on the
+Configuring the :paramref:`~.relationship.passive_updates`
+to False only on the
 many-to-one side will have only a partial effect, as the
 unit of work searches only through the current identity
 map for objects that may be referencing the one with a

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 02dd788777ea686747674ed8835f41689149718a..d5fdbae76e72317768f1ffd2049d089760fff78d 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -555,6 +555,11 @@ def relationship(argument, secondary=None, **kwargs):
        after a flush occurs so this is a very special use-case
        setting.
 
+       .. seealso::
+
+            :ref:`passive_deletes` - Introductory documentation
+            and examples.
+
     :param passive_updates=True:
       Indicates loading and INSERT/UPDATE/DELETE behavior when the
       source of a foreign key value changes (i.e. an "on update"
@@ -581,10 +586,13 @@ def relationship(argument, secondary=None, **kwargs):
       are expected and the database in use doesn't support CASCADE
       (i.e. SQLite, MySQL MyISAM tables).
 
-      Also see the passive_updates flag on ``mapper()``.
+      .. seealso::
+
+            :ref:`passive_updates` - Introductory documentation and
+            examples.
 
-      A future SQLAlchemy release will provide a "detect" feature for
-      this flag.
+            :paramref:`.mapper.passive_updates` - a similar flag which
+            takes effect for joined-table inheritance mappings.
 
     :param post_update:
       this indicates that the relationship should be handled by a
@@ -1061,7 +1069,7 @@ def mapper(class_, local_table=None, *args, **params):
 
            When False, it is assumed that the database does not enforce
            referential integrity and will not be issuing its own CASCADE
-           operation for an update.  The :class:`.Mapper` here will
+           operation for an update.  The unit of work process will
            emit an UPDATE statement for the dependent columns during a
            primary key change.