From: Mike Bayer Date: Fri, 19 Aug 2022 15:12:41 +0000 (-0400) Subject: remove narrative "reconstructor" document X-Git-Tag: rel_2_0_0b1~101 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e7b2055866f315a77e1e19a832a5afdae90bfd9f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git remove narrative "reconstructor" document this event hook is not commonly used and this page does not fit into the current narrative very well. We should possibly write a new paragraph regarding how instances load at some point though the best place to put it is not clear. --- diff --git a/doc/build/orm/constructors.rst b/doc/build/orm/constructors.rst index f03ce3a1a3..50ae218c2f 100644 --- a/doc/build/orm/constructors.rst +++ b/doc/build/orm/constructors.rst @@ -1,3 +1,5 @@ +:orphan: + .. currentmodule:: sqlalchemy.orm .. _mapping_constructors: @@ -5,59 +7,6 @@ Constructors and Object Initialization ====================================== -Mapping imposes no restrictions or requirements on the constructor -(``__init__``) method for the class. You are free to require any arguments for -the function that you wish, assign attributes to the instance that are unknown -to the ORM, and generally do anything else you would normally do when writing -a constructor for a Python class. - -The SQLAlchemy ORM does not call ``__init__`` when recreating objects from -database rows. The ORM's process is somewhat akin to the Python standard -library's ``pickle`` module, invoking the low level ``__new__`` method and -then quietly restoring attributes directly on the instance rather than calling -``__init__``. - -If you need to do some setup on database-loaded instances before they're ready -to use, there is an event hook known as :meth:`.InstanceEvents.load` which -can achieve this; it is also available via a class-specific decorator called -:func:`_orm.reconstructor`. When using :func:`_orm.reconstructor`, -the mapper will invoke a single decorated method with no -arguments every time it loads or reconstructs an instance of the -class. This is -useful for recreating transient properties that are normally assigned in -``__init__``:: - - from sqlalchemy import orm - - - class MyMappedClass: - def __init__(self, data): - self.data = data - # we need stuff on all instances, but not in the database. - self.stuff = [] - - @orm.reconstructor - def init_on_load(self): - self.stuff = [] - -Above, when ``obj = MyMappedClass()`` is executed, the ``__init__`` constructor -is invoked normally and the ``data`` argument is required. When instances are -loaded during a :class:`~sqlalchemy.orm.query.Query` operation as in -``query(MyMappedClass).one()``, ``init_on_load`` is called. - -Any method may be tagged as the :func:`_orm.reconstructor`, even -the ``__init__`` method itself, but only one method may be tagged as such. It is invoked after all immediate -column-level attributes are loaded as well as after eagerly-loaded scalar -relationships. Eagerly loaded collections may be only partially populated -or not populated at all, depending on the kind of eager loading used. - -ORM state changes made to objects at this stage will not be recorded for the -next flush operation, so the activity within a reconstructor should be -conservative. - -:func:`_orm.reconstructor` is a shortcut into a larger system -of "instance level" events, which can be subscribed to using the -event API - see :class:`.InstanceEvents` for the full API description -of these events. +This document has been removed. See :ref:`orm_mapped_class_behavior` +as well as :meth:`_orm.InstanceEvents.load` for what was covered here. -.. autofunction:: reconstructor diff --git a/doc/build/orm/loading_objects.rst b/doc/build/orm/loading_objects.rst index 02e8e1daa4..f8f19cc609 100644 --- a/doc/build/orm/loading_objects.rst +++ b/doc/build/orm/loading_objects.rst @@ -17,5 +17,4 @@ For an introduction to querying with the SQLAlchemy ORM, start with the loading_columns loading_relationships inheritance_loading - constructors query diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst index 830239d2e1..c60b51749c 100644 --- a/doc/build/orm/mapping_api.rst +++ b/doc/build/orm/mapping_api.rst @@ -129,6 +129,8 @@ Class Mapping API .. autofunction:: polymorphic_union +.. autofunction:: reconstructor + .. autoclass:: Mapper :members: diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index d60b6824b7..2edc74d6ab 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -311,6 +311,8 @@ method which passes them along to the :class:`_orm.Mapper` class. The full range of parameters accepted are documented at :class:`_orm.Mapper`. +.. _orm_mapped_class_behavior: + Mapped Class Behavior ===================== diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 61c9820292..b4aee545ee 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -3818,6 +3818,12 @@ def reconstructor(fn): method that will be called by the ORM after the instance has been loaded from the database or otherwise reconstituted. + .. tip:: + + The :func:`_orm.reconstructor` decorator makes use of the + :meth:`_orm.InstanceEvents.load` event hook, which can be + used directly. + The reconstructor will be invoked with no arguments. Scalar (non-collection) database-mapped attributes of the instance will be available for use within the function. Eagerly-loaded @@ -3828,8 +3834,6 @@ def reconstructor(fn): .. seealso:: - :ref:`mapping_constructors` - :meth:`.InstanceEvents.load` """