run proxy doc generation for updated session methods

Change-Id: I0e86d78c2b56e8a1c85d5848b42a9eb4081bacfd

diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
index 60b77f3ea63ea90304acd0a63449b36db112e691..b38574dc8e80ad496dcfd39387427a304bf55b96 100644 (file)
--- a/lib/sqlalchemy/ext/asyncio/session.py
+++ b/lib/sqlalchemy/ext/asyncio/session.py
@@ -893,18 +893,33 @@ class AsyncSession(ReversibleProxy[Session]):
         return self._proxied.__iter__()
 
     def add(self, instance: object, _warn: bool = True) -> None:
-        r"""Place an object in the ``Session``.
+        r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
 
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_asyncio.AsyncSession` class.
 
-        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`
 
 
         """  # noqa: E501
@@ -912,13 +927,23 @@ class AsyncSession(ReversibleProxy[Session]):
         return self._proxied.add(instance, _warn=_warn)
 
     def add_all(self, instances: Iterable[object]) -> None:
-        r"""Add the given collection of instances to this ``Session``.
+        r"""Add the given collection of instances to this :class:`_orm.Session`.
 
         .. container:: class_bases
 
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_asyncio.AsyncSession` class.
 
+        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`
+
+
         """  # noqa: E501
 
         return self._proxied.add_all(instances)

diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index abe97653ae4bfabd125c3573a6968fb1f97aa125..e3ba86c5a29faff625557b947404ab2a098438e5 100644 (file)
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -327,18 +327,33 @@ class scoped_session(Generic[_S]):
         return self._proxied.__iter__()
 
     def add(self, instance: object, _warn: bool = True) -> None:
-        r"""Place an object in the ``Session``.
+        r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
 
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_orm.scoping.scoped_session` class.
 
-        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`
 
 
         """  # noqa: E501
@@ -346,13 +361,23 @@ class scoped_session(Generic[_S]):
         return self._proxied.add(instance, _warn=_warn)
 
     def add_all(self, instances: Iterable[object]) -> None:
-        r"""Add the given collection of instances to this ``Session``.
+        r"""Add the given collection of instances to this :class:`_orm.Session`.
 
         .. container:: class_bases
 
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_orm.scoping.scoped_session` class.
 
+        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`
+
+
         """  # noqa: E501
 
         return self._proxied.add_all(instances)
@@ -567,7 +592,22 @@ class scoped_session(Generic[_S]):
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_orm.scoping.scoped_session` class.
 
-        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`
 
 
         """  # noqa: E501