- fully hyperlink the docstring for make_transient

- establish make_transient and make_transient_to_detached as special-use,
advanced use only functions
- list all conditions under make_transient() under which an attribute
will not be loaded and establish that make_transient() does not attempt
to load all attributes before detaching the object from its
session, fixes #3640

(cherry picked from commit 7eff4e8f3e3999d9eb914647d8776e6e5b7ee88e)

diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst
index c0ecee84b4f72bf8483c736a840e0c5e8552e30a..5f68624f8475aec5eeefc937d5de9e061e047e01 100644 (file)
--- a/doc/build/glossary.rst
+++ b/doc/build/glossary.rst
@@ -129,6 +129,7 @@ Glossary
 
     lazy load
     lazy loads
+    lazy loaded
     lazy loading
         In object relational mapping, a "lazy load" refers to an
         attribute that does not contain its database-side value

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 917d7a8bb6064f78e56126d94227b599f5e56d17..653390d001a0726382541acbc2e7652508a4bba2 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -2457,18 +2457,49 @@ class sessionmaker(_SessionClassMethods):
 
 
 def make_transient(instance):
-    """Make the given instance 'transient'.
+    """Alter the state of the given instance so that it is :term:`transient`.
 
-    This will remove its association with any
-    session and additionally will remove its "identity key",
-    such that it's as though the object were newly constructed,
-    except retaining its values.   It also resets the
-    "deleted" flag on the state if this object
-    had been explicitly deleted by its session.
+    .. note::
 
-    Attributes which were "expired" or deferred at the
-    instance level are reverted to undefined, and
-    will not trigger any loads.
+        :func:`.make_transient` is a special-case function for
+        advanced use cases only.
+
+    The given mapped instance is assumed to be in the :term:`persistent` or
+    :term:`detached` state.   The function will remove its association with any
+    :class:`.Session` as well as its :attr:`.InstanceState.identity`. The
+    effect is that the object will behave as though it were newly constructed,
+    except retaining any attribute / collection values that were loaded at the
+    time of the call.   The :attr:`.InstanceState.deleted` flag is also reset
+    if this object had been deleted as a result of using
+    :meth:`.Session.delete`.
+
+    .. warning::
+
+        :func:`.make_transient` does **not** "unexpire" or otherwise eagerly
+        load ORM-mapped attributes that are not currently loaded at the time
+        the function is called.   This includes attributes which:
+
+        * were expired via :meth:`.Session.expire`
+
+        * were expired as the natural effect of committing a session
+          transaction, e.g. :meth:`.Session.commit`
+
+        * are normally :term:`lazy loaded` but are not currently loaded
+
+        * are "deferred" via :ref:`deferred` and are not yet loaded
+
+        * were not present in the query which loaded this object, such as that
+          which is common in joined table inheritance and other scenarios.
+
+        After :func:`.make_transient` is called, unloaded attributes such
+        as those above will normally resolve to the value ``None`` when
+        accessed, or an empty collection for a collection-oriented attribute.
+        As the object is transient and un-associated with any database
+        identity, it will no longer retrieve these values.
+
+    .. seealso::
+
+        :func:`.make_transient_to_detached`
 
     """
     state = attributes.instance_state(instance)
@@ -2486,7 +2517,12 @@ def make_transient(instance):
 
 
 def make_transient_to_detached(instance):
-    """Make the given transient instance 'detached'.
+    """Make the given transient instance :term:`detached`.
+
+    .. note::
+
+        :func:`.make_transient_to_detached` is a special-case function for
+        advanced use cases only.
 
     All attribute history on the given instance
     will be reset as though the instance were freshly loaded

diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index 19eec2712b74935219d906b5b79d4bb518588f08..04588a6b17594b773a19ec8fdb01320191c5149d 100644 (file)
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -174,7 +174,7 @@ class InstanceState(interfaces._InspectionAttr):
         Returns ``None`` if the object has no primary key identity.
 
         .. note::
-            An object which is transient or pending
+            An object which is :term:`transient` or :term:`pending`
             does **not** have a mapped identity until it is flushed,
             even if its attributes include primary key values.