add autobuild; improve a few session docs

this is from the writeonly patch, some doc edits became
more general so will backport these to 1.4.

Change-Id: I19231e4bcfa33a0742c8995b6059c9a9488b1a6f

1 files changed, 48 insertions, 7 deletions

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 779860896..ce7caa3ee 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -3023,13 +3023,28 @@ class Session(_SessionClassMethods, EventTarget):
                 persistent_to_deleted(self, state)
 
     def add(self, instance: object, _warn: bool = True) -> None:
-        """Place an object in the ``Session``.
+        """Place an object into this :class:`_orm.Session`.
 
-        Its state will be persisted to the database on the next flush
-        operation.
+        Objects that are in the :term:`transient` state when passed to the
+        :meth:`_orm.Session.add` method will move to the
+        :term:`pending` state, until the next flush, at which point they
+        will move to the :term:`persistent` state.
 
-        Repeated calls to ``add()`` will be ignored. The opposite of ``add()``
-        is ``expunge()``.
+        Objects that are in the :term:`detached` state when passed to the
+        :meth:`_orm.Session.add` method will move to the :term:`persistent`
+        state directly.
+
+        If the transaction used by the :class:`_orm.Session` is rolled back,
+        objects which were transient when they were passed to
+        :meth:`_orm.Session.add` will be moved back to the
+        :term:`transient` state, and will no longer be present within this
+        :class:`_orm.Session`.
+
+        .. seealso::
+
+            :meth:`_orm.Session.add_all`
+
+            :ref:`session_adding` - at :ref:`session_basics`
 
         """
         if _warn and self._warn_on_events:
@@ -3043,7 +3058,18 @@ class Session(_SessionClassMethods, EventTarget):
         self._save_or_update_state(state)
 
     def add_all(self, instances: Iterable[object]) -> None:
-        """Add the given collection of instances to this ``Session``."""
+        """Add the given collection of instances to this :class:`_orm.Session`.
+
+        See the documentation for :meth:`_orm.Session.add` for a general
+        behavioral description.
+
+        .. seealso::
+
+            :meth:`_orm.Session.add`
+
+            :ref:`session_adding` - at :ref:`session_basics`
+
+        """
 
         if self._warn_on_events:
             self._flush_warning("Session.add_all()")
@@ -3064,7 +3090,22 @@ class Session(_SessionClassMethods, EventTarget):
     def delete(self, instance: object) -> None:
         """Mark an instance as deleted.
 
-        The database delete operation occurs upon ``flush()``.
+        The object is assumed to be either :term:`persistent` or
+        :term:`detached` when passed; after the method is called, the
+        object will remain in the :term:`persistent` state until the next
+        flush proceeds.  During this time, the object will also be a member
+        of the :attr:`_orm.Session.deleted` collection.
+
+        When the next flush proceeds, the object will move to the
+        :term:`deleted` state, indicating a ``DELETE`` statement was emitted
+        for its row within the current transaction.   When the transaction
+        is successfully committed,
+        the deleted object is moved to the :term:`detached` state and is
+        no longer present within this :class:`_orm.Session`.
+
+        .. seealso::
+
+            :ref:`session_deleting` - at :ref:`session_basics`
 
         """
         if self._warn_on_events: