Changing Attribute Behavior
Simple Validators
A quick way to add a “validation” routine to an attribute is to use thevalidates()
decorator. An attribute validator can raisean exception, halting the process of mutating the attribute’s value, or canchange the given value into something different. Validators, like allattribute extensions, are only called by normal userland code; they are notissued when the ORM is populating the object:
- from sqlalchemy.orm import validates
- class EmailAddress(Base):
- __tablename__ = 'address'
- id = Column(Integer, primary_key=True)
- email = Column(String)
- @validates('email')
- def validate_email(self, key, address):
- assert '@' in address
- return address
Changed in version 1.0.0: - validators are no longer triggered withinthe flush process when the newly fetched values for primary keycolumns as well as some python- or server-side defaults are fetched.Prior to 1.0, validators may be triggered in those cases as well.
Validators also receive collection append events, when items are added to acollection:
- from sqlalchemy.orm import validates
- class User(Base):
- # ...
- addresses = relationship("Address")
- @validates('addresses')
- def validate_address(self, key, address):
- assert '@' in address.email
- return address
The validation function by default does not get emitted for collectionremove events, as the typical expectation is that a value being discardeddoesn’t require validation. However, validates()
supports receptionof these events by specifying include_removes=True
to the decorator. Whenthis flag is set, the validation function must receive an additional booleanargument which if True
indicates that the operation is a removal:
- from sqlalchemy.orm import validates
- class User(Base):
- # ...
- addresses = relationship("Address")
- @validates('addresses', include_removes=True)
- def validate_address(self, key, address, is_remove):
- if is_remove:
- raise ValueError(
- "not allowed to remove items from the collection")
- else:
- assert '@' in address.email
- return address
The case where mutually dependent validators are linked via a backrefcan also be tailored, using the include_backrefs=False
option; this option,when set to False
, prevents a validation function from emitting if theevent occurs as a result of a backref:
- from sqlalchemy.orm import validates
- class User(Base):
- # ...
- addresses = relationship("Address", backref='user')
- @validates('addresses', include_backrefs=False)
- def validate_address(self, key, address):
- assert '@' in address.email
- return address
Above, if we were to assign to Address.user
as in someaddress.user = some_user
,the validate_address()
function would _not be emitted, even though an appendoccurs to some_user.addresses
- the event is caused by a backref.
Note that the validates()
decorator is a convenience function built ontop of attribute events. An application that requires more control overconfiguration of attribute change behavior can make use of this system,described at AttributeEvents
.
sqlalchemy.orm.
validates
(*names, **kw)- Decorate a method as a ‘validator’ for one or more named properties.
Designates a method as a validator, a method which receives thename of the attribute as well as a value to be assigned, or in thecase of a collection, the value to be added to the collection.The function can then raise validation exceptions to halt theprocess from continuing (where Python’s built-in ValueError
and AssertionError
exceptions are reasonable choices), or canmodify or replace the value before proceeding. The function shouldotherwise return the given value.
Note that a validator for a collection cannot issue a load of thatcollection within the validation routine - this usage raisesan assertion to avoid recursion overflows. This is a reentrantcondition which is not supported.
- Parameters
defaults to True
; if False
, thevalidation function will not emit if the originator is an attributeevent related via a backref. This can be used for bi-directionalvalidates()
usage where only one validator should emit perattribute operation.
New in version 0.9.0.
See also
Simple Validators - usage examples for validates()
Using Custom Datatypes at the Core Level
A non-ORM means of affecting the value of a column in a way that suitsconverting data between how it is represented in Python, vs. how it isrepresented in the database, can be achieved by using a custom datatype that isapplied to the mapped Table
metadata. This is more common in thecase of some style of encoding / decoding that occurs both as data goes to thedatabase and as it is returned; read more about this in the Core documentationat Augmenting Existing Types.
Using Descriptors and Hybrids
A more comprehensive way to produce modified behavior for an attribute is touse descriptors. These are commonly used in Python using the property()
function. The standard SQLAlchemy technique for descriptors is to create aplain descriptor, and to have it read/write from a mapped attribute with adifferent name. Below we illustrate this using Python 2.6-style properties:
- class EmailAddress(Base):
- __tablename__ = 'email_address'
- id = Column(Integer, primary_key=True)
- # name the attribute with an underscore,
- # different from the column name
- _email = Column("email", String)
- # then create an ".email" attribute
- # to get/set "._email"
- @property
- def email(self):
- return self._email
- @email.setter
- def email(self, email):
- self._email = email
The approach above will work, but there’s more we can add. While ourEmailAddress
object will shuttle the value through the email
descriptor and into the _email
mapped attribute, the class levelEmailAddress.email
attribute does not have the usual expression semanticsusable with Query
. To provide these, we instead use thehybrid
extension as follows:
- from sqlalchemy.ext.hybrid import hybrid_property
- class EmailAddress(Base):
- __tablename__ = 'email_address'
- id = Column(Integer, primary_key=True)
- _email = Column("email", String)
- @hybrid_property
- def email(self):
- return self._email
- @email.setter
- def email(self, email):
- self._email = email
The .email
attribute, in addition to providing getter/setter behavior when we have aninstance of EmailAddress
, also provides a SQL expression when used at the class level,that is, from the EmailAddress
class directly:
- from sqlalchemy.orm import Session
- session = Session()
- sqladdress = session.query(EmailAddress).\
- filter(EmailAddress.email == 'address@example.com').\
- one()
SELECT address.email AS address_email, address.id AS address_id FROM address WHERE address.email = ? ('address@example.com',)- address.email = 'otheraddress@example.com'
- sqlsession.commit()
UPDATE address SET email=? WHERE address.id = ? ('otheraddress@example.com', 1) COMMIT
The hybrid_property
also allows us to change the behavior of theattribute, including defining separate behaviors when the attribute isaccessed at the instance level versus at the class/expression level, using thehybrid_property.expression()
modifier. Such as, if we wanted to add ahost name automatically, we might define two sets of string manipulationlogic:
- class EmailAddress(Base):
- __tablename__ = 'email_address'
- id = Column(Integer, primary_key=True)
- _email = Column("email", String)
- @hybrid_property
- def email(self):
- """Return the value of _email up until the last twelve
- characters."""
- return self._email[:-12]
- @email.setter
- def email(self, email):
- """Set the value of _email, tacking on the twelve character
- value @example.com."""
- self._email = email + "@example.com"
- @email.expression
- def email(cls):
- """Produce a SQL expression that represents the value
- of the _email column, minus the last twelve characters."""
- return func.substr(cls._email, 0, func.length(cls._email) - 12)
Above, accessing the email
property of an instance of EmailAddress
will return the value of the _email
attribute, removing or adding thehostname @example.com
from the value. When we query against the email
attribute, a SQL function is rendered which produces the same effect:
- sqladdress = session.query(EmailAddress).filter(EmailAddress.email == 'address').one()
SELECT address.email AS address_email, address.id AS address_id FROM address WHERE substr(address.email, ?, length(address.email) - ?) = ? (0, 12, 'address')
Read more about Hybrids at Hybrid Attributes.
Synonyms
Synonyms are a mapper-level construct that allow any attribute on a classto “mirror” another attribute that is mapped.
In the most basic sense, the synonym is an easy way to make a certainattribute available by an additional name:
- class MyClass(Base):
- __tablename__ = 'my_table'
- id = Column(Integer, primary_key=True)
- job_status = Column(String(50))
- status = synonym("job_status")
The above class MyClass
has two attributes, .job_status
and.status
that will behave as one attribute, both at the expressionlevel:
- >>> print(MyClass.job_status == 'some_status')
- my_table.job_status = :job_status_1
- >>> print(MyClass.status == 'some_status')
- my_table.job_status = :job_status_1
and at the instance level:
- >>> m1 = MyClass(status='x')
- >>> m1.status, m1.job_status
- ('x', 'x')
- >>> m1.job_status = 'y'
- >>> m1.status, m1.job_status
- ('y', 'y')
The synonym()
can be used for any kind of mapped attribute thatsubclasses MapperProperty
, including mapped columns and relationships,as well as synonyms themselves.
Beyond a simple mirror, synonym()
can also be made to referencea user-defined descriptor. We can supply ourstatus
synonym with a @property
:
- class MyClass(Base):
- __tablename__ = 'my_table'
- id = Column(Integer, primary_key=True)
- status = Column(String(50))
- @property
- def job_status(self):
- return "Status: " + self.status
- job_status = synonym("status", descriptor=job_status)
When using Declarative, the above pattern can be expressed more succinctlyusing the synonym_for()
decorator:
- from sqlalchemy.ext.declarative import synonym_for
- class MyClass(Base):
- __tablename__ = 'my_table'
- id = Column(Integer, primary_key=True)
- status = Column(String(50))
- @synonym_for("status")
- @property
- def job_status(self):
- return "Status: " + self.status
While the synonym()
is useful for simple mirroring, the use caseof augmenting attribute behavior with descriptors is better handled in modernusage using the hybrid attribute feature, whichis more oriented towards Python descriptors. Technically, a synonym()
can do everything that a hybrid_property
can do, as it also supportsinjection of custom SQL capabilities, but the hybrid is more straightforwardto use in more complex situations.
sqlalchemy.orm.
synonym
(name, map_column=None, descriptor=None, comparator_factory=None, doc=None, info=None)- Denote an attribute name as a synonym to a mapped property,in that the attribute will mirror the value and expression behaviorof another attribute.
e.g.:
- class MyClass(Base):
- __tablename__ = 'my_table'
- id = Column(Integer, primary_key=True)
- job_status = Column(String(50))
- status = synonym("job_status")
- Parameters
name – the name of the existing mapped property. Thiscan refer to the string name ORM-mapped attributeconfigured on the class, including column-bound attributesand relationships.
descriptor – a Python descriptor that will be usedas a getter (and potentially a setter) when this attribute isaccessed at the instance level.
For classical mappings and mappings againstan existing Table object only. if True
, the synonym()
construct will locate the Column
object upon the mappedtable that would normally be associated with the attribute name ofthis synonym, and produce a new ColumnProperty
that insteadmaps this Column
to the alternate name given as the “name”argument of the synonym; in this way, the usual step of redefiningthe mapping of the Column
to be under a different name isunnecessary. This is usually intended to be used when aColumn
is to be replaced with an attribute that also uses adescriptor, that is, in conjunction with thesynonym.descriptor
parameter:
- my_table = Table(
- "my_table", metadata,
- Column('id', Integer, primary_key=True),
- Column('job_status', String(50))
- )
- class MyClass(object):
- @property
- def _job_status_descriptor(self):
- return "Status: %s" % self._job_status
- mapper(
- MyClass, my_table, properties={
- "job_status": synonym(
- "_job_status", map_column=True,
- descriptor=MyClass._job_status_descriptor)
- }
- )
Above, the attribute named _job_status
is automaticallymapped to the job_status
column:
- >>> j1 = MyClass()
- >>> j1._job_status = "employed"
- >>> j1.job_status
- Status: employed
When using Declarative, in order to provide a descriptor inconjunction with a synonym, use thesqlalchemy.ext.declarative.synonym_for()
helper. However,note that the hybrid properties featureshould usually be preferred, particularly when redefining attributebehavior.
-
Optional data dictionary which will be populated into theInspectionAttr.info
attribute of this object.
New in version 1.0.0.
-
A subclass of PropComparator
that will provide custom comparison behavior at the SQL expressionlevel.
Note
For the use case of providing an attribute which redefines bothPython-level and SQL-expression level behavior of an attribute,please refer to the Hybrid attribute introduced atUsing Descriptors and Hybrids for a more effective technique.
See also
Synonyms - Overview of synonyms
synonym_for()
- a helper oriented towards Declarative
Using Descriptors and Hybrids - The Hybrid Attribute extension provides anupdated approach to augmenting attribute behavior more flexiblythan can be achieved with synonyms.
Operator Customization
The “operators” used by the SQLAlchemy ORM and Core expression languageare fully customizable. For example, the comparison expressionUser.name == 'ed'
makes usage of an operator built into Pythonitself called operator.eq
- the actual SQL construct which SQLAlchemyassociates with such an operator can be modified. Newoperations can be associated with column expressions as well. The operatorswhich take place for column expressions are most directly redefined at thetype level - see thesection Redefining and Creating New Operators for a description.
ORM level functions like column_property()
, relationship()
,and composite()
also provide for operator redefinition at the ORMlevel, by passing a PropComparator
subclass to the comparator_factory
argument of each function. Customization of operators at this level is arare use case. See the documentation at PropComparator
for an overview.