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 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 02e8e1daa4c7b544012efe291e266e79febe358d..f8f19cc609ffbd5073f931367d717791e8cb4f3c 100644 (file)
--- 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 830239d2e122cd9214daee657161b17abf7ac615..c60b51749cec5a1e324a2cb1999868c85ad6f67f 100644 (file)
--- 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 d60b6824b7f5db54fb054402146e5f06c3720eba..2edc74d6ab5eef6a185d3e39dd0b7fd86e570040 100644 (file)
--- 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 61c9820292b0d42d332b45a9d2e8d1ae388606f2..b4aee545ee918fa992546284fefdfb8c0703179d 100644 (file)
--- 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`
 
     """