# You can set these variables from the command line.
SPHINXOPTS = -T -j auto
SPHINXBUILD = sphinx-build
+AUTOBUILD = sphinx-autobuild --port 8080 --watch ../../lib
PAPER =
BUILDDIR = output
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest dist-html site-mako gettext
+.PHONY: help clean html autobuild dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest dist-html site-mako gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
+ @echo " autobuild autobuild and run a webserver"
@echo " gettext to make PO message catalogs"
@echo " dist-html same as html, but places files in /doc"
@echo " dirhtml to make HTML files named index.html in directories"
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+autobuild:
+ $(AUTOBUILD) $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
`Domain Model (via Wikipedia) <https://en.wikipedia.org/wiki/Domain_model>`_
unit of work
- This pattern is where the system transparently keeps
- track of changes to objects and periodically flushes all those
- pending changes out to the database. SQLAlchemy's Session
- implements this pattern fully in a manner similar to that of
- Hibernate.
+ A software architecture where a persistence system such as an object
+ relational mapper maintains a list of changes made to a series of
+ objects, and periodically flushes all those pending changes out to the
+ database.
+
+ SQLAlchemy's :class:`_orm.Session` implements the unit of work pattern,
+ where objects that are added to the :class:`_orm.Session` using methods
+ like :meth:`_orm.Session.add` will then participate in unit-of-work
+ style persistence.
+
+ For a walk-through of what unit of work persistence looks like in
+ SQLAlchemy, start with the section :ref:`tutorial_orm_data_manipulation`
+ in the :ref:`unified_tutorial`. Then for more detail, see
+ :ref:`session_basics` in the general reference documentation.
.. seealso::
`Unit of Work (via Martin Fowler) <https://martinfowler.com/eaaCatalog/unitOfWork.html>`_
- :doc:`orm/session`
+ :ref:`tutorial_orm_data_manipulation`
+
+ :ref:`session_basics`
expire
expired
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:
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()")
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:
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
