Mike Bayer avatar Mike Bayer committed e73e6d9

some doc stuff

Comments (0)

Files changed (4)

doc/build/content/mappers.txt

 
 Versions of SQLAlchemy previous to 0.5 included another mapper flag called "entity_name", as of version 0.5.0 this feature has been removed (it never worked very well).
 
+#### Performing Initialization When an Object Is Loaded {@name=onreconstitute}
+
+While a mapped object's `__init__()` method works as always during object construction, it's not called when instances of the object are re-created from the database.  This is so that the `__init__()` method can be constructed in any desired way without SQLA requiring any sort of behavior, and also so that an object can control the way it's initialized when constructed new versus reconstituted.
+
+To support the common use case of instance management which occurs during load, SQLA 0.5 supports this most easily using the `@on_reconstitute` decorator, which is a shortcut to the `MapperExtension.on_reconstitute` method:
+
+    {python}
+    from sqlalchemy.orm.attributes import on_reconstitute
+    
+    class MyMappedClass(object):
+        def __init__(self, data):
+            self.data = data
+            self.description = "The data is: " + data
+            
+        @on_reconstitute
+        def init_on_load(self):
+            self.description = "The data is: " + self.data
+
+Above, when `MyMappedClass` is constructed, `__init__()` is called with the requirement that the `data` argument is passed, but when loaded during a `Query` operation, `init_on_load()` is called instead.   This method is called after the object's row has been loaded, so scalar attributes will be present, such as above where the `self.data` is available.  Eagerly-loaded collections are generally not available at this stage and will usually only contain the first element.   Any state changes to objects at this stage will not be recorded for the next flush() operation, so the activity within a reconstitute hook should be conservative.
+
+The non-declarative form of `@on_reconsitute` is to use the `on_reconstitute` method of `MapperExtension`, the ORM's mapper-level extension API which is described in the next section.
+
 #### Extending Mapper {@name=extending}
 
 Mappers can have functionality augmented or replaced at many points in its execution via the usage of the MapperExtension class.  This class is just a series of "hooks" where various functionality takes place.  An application can make its own MapperExtension objects, overriding only the methods it needs.  Methods that are not overridden return the special value `sqlalchemy.orm.EXT_CONTINUE` to allow processing to continue to the next MapperExtension or simply proceed normally if there are no more extensions.

doc/build/gen_docstrings.py

         make_doc(obj=expression,include_all_classes=True),
         make_doc(obj=types),
         make_doc(obj=orm),
+        make_doc(obj=orm.attributes),
         make_doc(obj=orm.collections, classes=[orm.collections.collection,
                                                orm.collections.MappedCollection,
                                                orm.collections.CollectionAdapter]),

lib/sqlalchemy/ext/declarative.py

 
     constructor
       Defaults to declarative._declarative_constructor, an __init__
-      implementation that assigns **kwargs for declared fields and relations
+      implementation that assigns \**kwargs for declared fields and relations
       to an instance.  If `None` is supplied, no __init__ will be installed
       and construction will fall back to cls.__init__ with normal Python
       semantics.

lib/sqlalchemy/orm/attributes.py

 #
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
+"""
+
+Defines SQLAlchemy's system of class instrumentation.
+
+This module is usually not visible to user applications, but forms
+a large part of the ORM's interactivity.  The primary "public"
+function is the ``on_reconstitute`` decorator which is described in
+the main mapper documentation.
+
+SQLA's instrumentation system is completely customizable, in which
+case an understanding of the general mechanics of this module is helpful.
+An example of full customization is in /examples/custom_attributes.
+
+"""
 
 import operator
 from operator import attrgetter, itemgetter
 
     def __init__(self, impl, comparator=None, parententity=None):
         """Construct an InstrumentedAttribute.
-        comparator
-          a sql.Comparator to which class-level compare/math events will be sent
+        
+          comparator
+            a sql.Comparator to which class-level compare/math events will be sent
         """
 
         self.impl = impl
     def __init__(self, class_, key, callable_, class_manager, trackparent=False, extension=None, compare_function=None, **kwargs):
         """Construct an AttributeImpl.
 
-        class_
+        \class_
           the class to be instrumented.
 
         key
           string name of the attribute
 
-        callable_
+        \callable_
           optional function which generates a callable based on a parent
           instance, which produces the "default" values for a scalar or
           collection attribute when it's first accessed, if not present
         fired.
 
         The callable overrides the class level callable set in the
-        ``InstrumentedAttribute` constructor.
+        ``InstrumentedAttribute`` constructor.
 
         """
         if callable_ is None:
         """Set a value on the given InstanceState.
 
         `initiator` is the ``InstrumentedAttribute`` that initiated the
-        ``set()` operation and is used to control the depth of a circular
+        ``set()`` operation and is used to control the depth of a circular
         setter operation.
+        
         """
-
         if initiator is self:
             return
 
         """Set a value on the given object.
 
         `initiator` is the ``InstrumentedAttribute`` that initiated the
-        ``set()` operation and is used to control the depth of a circular
+        ``set()`` operation and is used to control the depth of a circular
         setter operation.
         """
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.