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.

(cherry picked from commit e7b2055866f315a77e1e19a832a5afdae90bfd9f)

diff --git a/doc/build/orm/constructors.rst b/doc/build/orm/constructors.rst
index f03ce3a1a38f7224896071cfd5fb73fff3dee165..50ae218c2fed366143bd7aca0841f1638e22c400 100644 (file)
--- 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 956ef2f6995587f704c20c9bacc6cf7c24ee69b5..3f6c84bf1d2ffc9ae5406345ce4d15201bf62ce1 100644 (file)
--- a/doc/build/orm/loading_objects.rst
+++ b/doc/build/orm/loading_objects.rst
@@ -24,5 +24,4 @@ sections are currently mixed as far as which style they are using.
     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 5d0b6c0d023069c0f4e20bb947071ec9d89c962c..199d92d43155fb35bbb24ff16fdb22fbce9ffff0 100644 (file)
--- a/doc/build/orm/mapping_api.rst
+++ b/doc/build/orm/mapping_api.rst
@@ -34,6 +34,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 1b33aa2e29f0cfb5abadb26219f1ea77b48770c5..84db8cb08700911a34380ff93f34196d5c2f8112 100644 (file)
--- a/doc/build/orm/mapping_styles.rst
+++ b/doc/build/orm/mapping_styles.rst
@@ -290,6 +290,8 @@ method which passes them along to the :func:`_orm.mapper` function.
 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 ed221a964a0c50fc0a31f13df9490e20573187ce..e13ce4bff9cc6c8eabad8cc8d9532ad54c371e3c 100644 (file)
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -3544,6 +3544,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
@@ -3554,8 +3560,6 @@ def reconstructor(fn):
 
     .. seealso::
 
-        :ref:`mapping_constructors`
-
         :meth:`.InstanceEvents.load`
 
     """