From: Mike Bayer Date: Fri, 30 Sep 2022 17:07:04 +0000 (-0400) Subject: add autobuild; improve a few session docs X-Git-Tag: rel_1_4_42~15 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=74128a2abdded702ac1ebb700a8a6e554fd57a19;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 (cherry picked from commit abcd088551fda5490ad56c401a8e8260fae0dcfd) --- diff --git a/doc/build/Makefile b/doc/build/Makefile index 09d8b29da1..e9684a2073 100644 --- a/doc/build/Makefile +++ b/doc/build/Makefile @@ -4,6 +4,7 @@ # 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 @@ -14,11 +15,12 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # 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 ' where 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" @@ -45,6 +47,9 @@ html: @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +autobuild: + $(AUTOBUILD) $(ALLSPHINXOPTS) $(BUILDDIR)/html + gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 9c8f01d02e..111adb13b9 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -659,17 +659,28 @@ Glossary `Domain Model (via Wikipedia) `_ 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) `_ - :doc:`orm/session` + :ref:`tutorial_orm_data_manipulation` + + :ref:`session_basics` expire expired diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 2815492dd5..16b2cae5f8 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -314,6 +314,7 @@ via standard methods such as :meth:`_engine.Result.all`, :ref:`migration_20_toplevel` +.. _session_adding: Adding New or Existing Items @@ -343,6 +344,7 @@ The :meth:`~.Session.add` operation **cascades** along the ``save-update`` cascade. For more details see the section :ref:`unitofwork_cascades`. +.. _session_deleting: Deleting -------- diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 96a273a359..4b05381db2 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -2603,13 +2603,28 @@ class Session(_SessionClassMethods): persistent_to_deleted(self, state) def add(self, instance, _warn=True): - """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: @@ -2626,7 +2641,18 @@ class Session(_SessionClassMethods): self._save_or_update_state(state) def add_all(self, instances): - """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()") @@ -2647,7 +2673,22 @@ class Session(_SessionClassMethods): def delete(self, instance): """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: