From: Mike Bayer Date: Fri, 30 Sep 2022 18:53:31 +0000 (-0400) Subject: run proxy doc generation for updated session methods X-Git-Tag: rel_2_0_0b1~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fe617840447db8061c7cd39ace559f898a9cf0bd;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 60b77f3ea6..b38574dc8e 100644 --- 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 abe97653ae..e3ba86c5a2 100644 --- 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