Constructors and Object Initialization

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 forthe function that you wish, assign attributes to the instance that are unknownto the ORM, and generally do anything else you would normally do when writinga constructor for a Python class.

The SQLAlchemy ORM does not call init when recreating objects fromdatabase rows. The ORM’s process is somewhat akin to the Python standardlibrary’s pickle module, invoking the low level new method andthen quietly restoring attributes directly on the instance rather than callinginit.

If you need to do some setup on database-loaded instances before they’re readyto use, there is an event hook known as InstanceEvents.load() whichcan achieve this; it is also available via a class-specific decorator calledorm.reconstructor(). When using orm.reconstructor(),the mapper will invoke the decorated method with noarguments every time it loads or reconstructs an instance of theclass. This isuseful for recreating transient properties that are normally assigned ininit:

from sqlalchemy import orm
 
class MyMappedClass(object):
    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 constructoris invoked normally and the data argument is required. When instances areloaded during a Query operation as inquery(MyMappedClass).one(), init_on_load is called.

Any method may be tagged as the orm.reconstructor(), eventhe init method itself. It is invoked after all immediatecolumn-level attributes are loaded as well as after eagerly-loaded scalarrelationships. Eagerly loaded collections may be only partially populatedor 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 thenext flush operation, so the activity within a reconstructor should beconservative.

orm.reconstructor() is a shortcut into a larger systemof “instance level” events, which can be subscribed to using theevent API - see InstanceEvents for the full API descriptionof these events.

sqlalchemy.orm.reconstructor(fn)
Decorate a method as the ‘reconstructor’ hook.

Designates a method as the “reconstructor”, an init-likemethod that will be called by the ORM after the instance has beenloaded from the database or otherwise reconstituted.

The reconstructor will be invoked with no arguments. Scalar(non-collection) database-mapped attributes of the instance willbe available for use within the function. Eagerly-loadedcollections are generally not yet available and will usually onlycontain the first element. ORM state changes made to objects atthis stage will not be recorded for the next flush() operation, sothe activity within a reconstructor should be conservative.