From 3b8bcbcac66d814d15ec44c86c30d9c48ec40c27 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 7 Sep 2022 19:00:31 -0400 Subject: [PATCH] add docs for session.get() also use the term "primary key" a bit more Change-Id: Ib654b30a9d06a2aeed019b4754db920afe05d774 References: https://twitter.com/encthenet/status/1567644850471989248 (cherry picked from commit cc72081b0c32dbd089fb9601747f448b65414640) --- doc/build/orm/session_basics.rst | 31 ++++++++++++++++++-- doc/build/tutorial/orm_data_manipulation.rst | 4 +-- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index b747246c04..2815492dd5 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -500,6 +500,29 @@ so that the overall nesting pattern of so-called "subtransactions" is consistently maintained. The FAQ section :ref:`faq_session_rollback` contains a more detailed description of this behavior. +.. _session_get: + +Get by Primary Key +------------------ + +As the :class:`_orm.Session` makes use of an :term:`identity map` which refers +to current in-memory objects by primary key, the :meth:`_orm.Session.get` +method is provided as a means of locating objects by primary key, first +looking within the current identity map and then querying the database +for non present values. Such as, to locate a ``User`` entity with primary key +identity ``(5, )``:: + + my_user = session.get(User, 5) + +The :meth:`_orm.Session.get` also includes calling forms for composite primary +key values, which may be passed as tuples or dictionaries, as well as +additional parameters which allow for specific loader and execution options. +See :meth:`_orm.Session.get` for the complete parameter list. + +.. seealso:: + + :meth:`_orm.Session.get` + .. _session_expiring: Expiring / Refreshing @@ -552,9 +575,11 @@ ways to refresh its contents with new data from the current transaction: .. -* **the populate_existing() method** - this method is actually on the - :class:`_orm.Query` object as :meth:`_orm.Query.populate_existing` - and indicates that it should return objects that are unconditionally +* **the populate_existing() method or execution option** - This is now + an execution option documented at :ref:`orm_queryguide_populate_existing`; in + legacy form it's found on the :class:`_orm.Query` object as the + :meth:`_orm.Query.populate_existing` method. This operation in either form + indicates that objects being returned from a query should be unconditionally re-populated from their contents in the database:: u2 = session.query(User).populate_existing().filter(id=5).first() diff --git a/doc/build/tutorial/orm_data_manipulation.rst b/doc/build/tutorial/orm_data_manipulation.rst index ca955d0237..b0b67f53c4 100644 --- a/doc/build/tutorial/orm_data_manipulation.rst +++ b/doc/build/tutorial/orm_data_manipulation.rst @@ -173,8 +173,8 @@ the ``id`` attribute:: INSERT many rows at once while still being able to retrieve the primary key values. -Identity Map -^^^^^^^^^^^^ +Getting Objects by Primary Key from the Identity Map +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The primary key identity of the objects are significant to the :class:`_orm.Session`, as the objects are now linked to this identity in memory using a feature -- 2.47.2