SQLAlchemy 2.0 Documentation
SQLAlchemy ORM
- ORM Quick Start
- ORM Mapped Class Configuration
- ORM Mapped Class Overview
- Mapping Classes with Declarative
- Integration with dataclasses and attrs
- SQL Expressions as Mapped Attributes
- Changing Attribute Behavior¶
- Composite Column Types
- Mapping Class Inheritance Hierarchies
- Non-Traditional Mappings
- Configuring a Version Counter
- Class Mapping API
- Mapping SQL Expressions
- Relationship Configuration
- ORM Querying Guide
- Using the Session
- Events and Internals
- ORM Extensions
- ORM Examples
Project Versions
- Previous: SQL Expressions as Mapped Attributes
- Next: Composite Column Types
- Up: Home
- On this page:
Changing Attribute Behavior¶
This section will discuss features and techniques used to modify the
behavior of ORM mapped attributes, including those mapped with
mapped_column()
, relationship()
, and others.
Simple Validators¶
A quick way to add a “validation” routine to an attribute is to use the
validates()
decorator. An attribute validator can raise
an exception, halting the process of mutating the attribute’s value, or can
change the given value into something different. Validators, like all
attribute extensions, are only called by normal userland code; they are not
issued when the ORM is populating the object:
from sqlalchemy.orm import validates
class EmailAddress(Base):
__tablename__ = "address"
id = mapped_column(Integer, primary_key=True)
email = mapped_column(String)
@validates("email")
def validate_email(self, key, address):
if "@" not in address:
raise ValueError("failed simple email validation")
return address
Validators also receive collection append events, when items are added to a collection:
from sqlalchemy.orm import validates
class User(Base):
# ...
addresses = relationship("Address")
@validates("addresses")
def validate_address(self, key, address):
if "@" not in address.email:
raise ValueError("failed simplified email validation")
return address
The validation function by default does not get emitted for collection
remove events, as the typical expectation is that a value being discarded
doesn’t require validation. However, validates()
supports reception
of these events by specifying include_removes=True
to the decorator. When
this flag is set, the validation function must receive an additional boolean
argument 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:
if "@" not in address.email:
raise ValueError("failed simplified email validation")
return address
The case where mutually dependent validators are linked via a backref
can also be tailored, using the include_backrefs=False
option; this option,
when set to False
, prevents a validation function from emitting if the
event 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):
if "@" not in address:
raise ValueError("failed simplified email validation")
return address
Above, if we were to assign to Address.user
as in some_address.user = some_user
,
the validate_address()
function would not be emitted, even though an append
occurs to some_user.addresses
- the event is caused by a backref.
Note that the validates()
decorator is a convenience function built on
top of attribute events. An application that requires more control over
configuration of attribute change behavior can make use of this system,
described at AttributeEvents
.
Object Name | Description |
---|---|
validates(*names, [include_removes, include_backrefs]) |
Decorate a method as a ‘validator’ for one or more named properties. |
- function sqlalchemy.orm.validates(*names: str, include_removes: bool = False, include_backrefs: bool = True) → Callable[[_Fn], _Fn]¶
Decorate a method as a ‘validator’ for one or more named properties.
Designates a method as a validator, a method which receives the name of the attribute as well as a value to be assigned, or in the case of a collection, the value to be added to the collection. The function can then raise validation exceptions to halt the process from continuing (where Python’s built-in
ValueError
andAssertionError
exceptions are reasonable choices), or can modify or replace the value before proceeding. The function should otherwise return the given value.Note that a validator for a collection cannot issue a load of that collection within the validation routine - this usage raises an assertion to avoid recursion overflows. This is a reentrant condition which is not supported.
- Parameters:
*names¶ – list of attribute names to be validated.
include_removes¶ – if True, “remove” events will be sent as well - the validation function must accept an additional argument “is_remove” which will be a boolean.
include_backrefs¶ –
defaults to
True
; ifFalse
, the validation function will not emit if the originator is an attribute event related via a backref. This can be used for bi-directionalvalidates()
usage where only one validator should emit per attribute operation.Changed in version 2.0.16: This paramter inadvertently defaulted to
False
for releases 2.0.0 through 2.0.15. Its correct default ofTrue
is restored in 2.0.16.
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 suits
converting data between how it is represented in Python, vs. how it is
represented in the database, can be achieved by using a custom datatype that is
applied to the mapped Table
metadata. This is more common in the
case of some style of encoding / decoding that occurs both as data goes to the
database and as it is returned; read more about this in the Core documentation
at Augmenting Existing Types.
Using Descriptors and Hybrids¶
A more comprehensive way to produce modified behavior for an attribute is to
use descriptors. These are commonly used in Python using the property()
function. The standard SQLAlchemy technique for descriptors is to create a
plain descriptor, and to have it read/write from a mapped attribute with a
different name. Below we illustrate this using Python 2.6-style properties:
class EmailAddress(Base):
__tablename__ = "email_address"
id = mapped_column(Integer, primary_key=True)
# name the attribute with an underscore,
# different from the column name
_email = mapped_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 our
EmailAddress
object will shuttle the value through the email
descriptor and into the _email
mapped attribute, the class level
EmailAddress.email
attribute does not have the usual expression semantics
usable with Select
. To provide these, we instead use the
hybrid
extension as follows:
from sqlalchemy.ext.hybrid import hybrid_property
class EmailAddress(Base):
__tablename__ = "email_address"
id = mapped_column(Integer, primary_key=True)
_email = mapped_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 an
instance 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
from sqlalchemy import select
session = Session()
address = session.scalars(
select(EmailAddress).where(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"
session.commit()
UPDATE address SET email=? WHERE address.id = ?
('otheraddress@example.com', 1)
COMMIT
The hybrid_property
also allows us to change the behavior of the
attribute, including defining separate behaviors when the attribute is
accessed at the instance level versus at the class/expression level, using the
hybrid_property.expression()
modifier. Such as, if we wanted to add a
host name automatically, we might define two sets of string manipulation
logic:
class EmailAddress(Base):
__tablename__ = "email_address"
id = mapped_column(Integer, primary_key=True)
_email = mapped_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 the
hostname @example.com
from the value. When we query against the email
attribute, a SQL function is rendered which produces the same effect:
address = session.scalars(
select(EmailAddress).where(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 class to “mirror” another attribute that is mapped.
In the most basic sense, the synonym is an easy way to make a certain attribute available by an additional name:
from sqlalchemy.orm import synonym
class MyClass(Base):
__tablename__ = "my_table"
id = mapped_column(Integer, primary_key=True)
job_status = mapped_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 expression
level:
>>> 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 that
subclasses MapperProperty
, including mapped columns and relationships,
as well as synonyms themselves.
Beyond a simple mirror, synonym()
can also be made to reference
a user-defined descriptor. We can supply our
status
synonym with a @property
:
class MyClass(Base):
__tablename__ = "my_table"
id = mapped_column(Integer, primary_key=True)
status = mapped_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 succinctly
using the synonym_for()
decorator:
from sqlalchemy.ext.declarative import synonym_for
class MyClass(Base):
__tablename__ = "my_table"
id = mapped_column(Integer, primary_key=True)
status = mapped_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 case
of augmenting attribute behavior with descriptors is better handled in modern
usage using the hybrid attribute feature, which
is more oriented towards Python descriptors. Technically, a synonym()
can do everything that a hybrid_property
can do, as it also supports
injection of custom SQL capabilities, but the hybrid is more straightforward
to use in more complex situations.
Object Name | Description |
---|---|
synonym(name, *, [map_column, descriptor, comparator_factory, init, repr, default, default_factory, compare, kw_only, hash, info, doc]) |
Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of another attribute. |
- function sqlalchemy.orm.synonym(name: str, *, map_column: bool | None = None, descriptor: Any | None = None, comparator_factory: Type[PropComparator[_T]] | None = None, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: _NoArg | _T = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG, info: _InfoType | None = None, doc: str | None = None) → Synonym[Any]¶
Denote an attribute name as a synonym to a mapped property, in that the attribute will mirror the value and expression behavior of 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. This can refer to the string name ORM-mapped attribute configured on the class, including column-bound attributes and relationships.
descriptor¶ – a Python descriptor that will be used as a getter (and potentially a setter) when this attribute is accessed at the instance level.
map_column¶ –
For classical mappings and mappings against an existing Table object only. if
True
, thesynonym()
construct will locate theColumn
object upon the mapped table that would normally be associated with the attribute name of this synonym, and produce a newColumnProperty
that instead maps thisColumn
to the alternate name given as the “name” argument of the synonym; in this way, the usual step of redefining the mapping of theColumn
to be under a different name is unnecessary. This is usually intended to be used when aColumn
is to be replaced with an attribute that also uses a descriptor, 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: @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 automatically mapped to thejob_status
column:>>> j1 = MyClass() >>> j1._job_status = "employed" >>> j1.job_status Status: employed
When using Declarative, in order to provide a descriptor in conjunction with a synonym, use the
sqlalchemy.ext.declarative.synonym_for()
helper. However, note that the hybrid properties feature should usually be preferred, particularly when redefining attribute behavior.info¶ – Optional data dictionary which will be populated into the
InspectionAttr.info
attribute of this object.comparator_factory¶ –
A subclass of
PropComparator
that will provide custom comparison behavior at the SQL expression level.Note
For the use case of providing an attribute which redefines both Python-level and SQL-expression level behavior of an attribute, please refer to the Hybrid attribute introduced at Using Descriptors and Hybrids for a more effective technique.
See also
Synonyms - Overview of synonyms
synonym_for()
- a helper oriented towards DeclarativeUsing Descriptors and Hybrids - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than can be achieved with synonyms.
Operator Customization¶
The “operators” used by the SQLAlchemy ORM and Core expression language
are fully customizable. For example, the comparison expression
User.name == 'ed'
makes usage of an operator built into Python
itself called operator.eq
- the actual SQL construct which SQLAlchemy
associates with such an operator can be modified. New
operations can be associated with column expressions as well. The operators
which take place for column expressions are most directly redefined at the
type level - see the
section Redefining and Creating New Operators for a description.
ORM level functions like column_property()
, relationship()
,
and composite()
also provide for operator redefinition at the ORM
level, by passing a PropComparator
subclass to the comparator_factory
argument of each function. Customization of operators at this level is a
rare use case. See the documentation at PropComparator
for an overview.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Thu 12 Dec 2024 05:39:06 PM EST