diff options
Diffstat (limited to 'lib/sqlalchemy')
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 55 |
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: |