Defining Expression Behavior Distinct from Attribute Behavior¶

In the previous section, our usage of the & and | bitwise operators within the Interval.contains and Interval.intersects methods was fortunate, considering our functions operated on two boolean values to return a new one. In many cases, the construction of an in-Python function and a SQLAlchemy SQL expression have enough differences that two separate Python expressions should be defined. The hybrid decorator defines a modifier hybrid_property.expression() for this purpose. As an example we’ll define the radius of the interval, which requires the usage of the absolute value function:

fromsqlalchemyimport ColumnElement
fromsqlalchemyimport Float
fromsqlalchemyimport func
fromsqlalchemyimport type_coerce
classInterval(Base):
 # ...
 @hybrid_property
 defradius(self) -> float:
 return abs(self.length) / 2
 @radius.inplace.expression
 @classmethod
 def_radius_expression(cls) -> ColumnElement[float]:
 return type_coerce(func.abs(cls.length) / 2, Float)

In the above example, the hybrid_property first assigned to the name Interval.radius is amended by a subsequent method called Interval._radius_expression, using the decorator @radius.inplace.expression, which chains together two modifiers hybrid_property.inplace and hybrid_property.expression. The use of hybrid_property.inplace indicates that the hybrid_property.expression() modifier should mutate the existing hybrid object at Interval.radius in place, without creating a new object. Notes on this modifier and its rationale are discussed in the next section Using inplace to create pep-484 compliant hybrid properties. The use of @classmethod is optional, and is strictly to give typing tools a hint that cls in this case is expected to be the Interval class, and not an instance of Interval.

With Interval.radius now including an expression element, the SQL function ABS() is returned when accessing Interval.radius at the class level:

>>> fromsqlalchemyimport select
>>> print(select(Interval).filter(Interval.radius > 5))
SELECTinterval.id,interval.start,interval."end"
FROMinterval
WHEREabs(interval."end"-interval.start)/:abs_1>:param_1

Using inplace to create pep-484 compliant hybrid properties¶

In the previous section, a hybrid_property decorator is illustrated which includes two separate method-level functions being decorated, both to produce a single object attribute referenced as Interval.radius. There are actually several different modifiers we can use for hybrid_property including hybrid_property.expression(), hybrid_property.setter() and hybrid_property.update_expression().

SQLAlchemy’s hybrid_property decorator intends that adding on these methods may be done in the identical manner as Python’s built-in @property decorator, where idiomatic use is to continue to redefine the attribute repeatedly, using the same attribute name each time, as in the example below that illustrates the use of hybrid_property.setter() and hybrid_property.expression() for the Interval.radius descriptor:

# correct use, however is not accepted by pep-484 tooling
classInterval(Base):
 # ...
 @hybrid_property
 defradius(self):
 return abs(self.length) / 2
 @radius.setter
 defradius(self, value):
 self.length = value * 2
 @radius.expression
 defradius(cls):
 return type_coerce(func.abs(cls.length) / 2, Float)

Above, there are three Interval.radius methods, but as each are decorated, first by the hybrid_property decorator and then by the @radius name itself, the end effect is that Interval.radius is a single attribute with three different functions contained within it. This style of use is taken from Python’s documented use of @property. It is important to note that the way both @property as well as hybrid_property work, a copy of the descriptor is made each time. That is, each call to @radius.expression, @radius.setter etc. make a new object entirely. This allows the attribute to be re-defined in subclasses without issue (see Reusing Hybrid Properties across Subclasses later in this section for how this is used).

However, the above approach is not compatible with typing tools such as mypy and pyright. Python’s own @property decorator does not have this limitation only because these tools hardcode the behavior of @property, meaning this syntax is not available to SQLAlchemy under PEP 484 compliance.

In order to produce a reasonable syntax while remaining typing compliant, the hybrid_property.inplace decorator allows the same decorator to be reused with different method names, while still producing a single decorator under one name:

# correct use which is also accepted by pep-484 tooling
classInterval(Base):
 # ...
 @hybrid_property
 defradius(self) -> float:
 return abs(self.length) / 2
 @radius.inplace.setter
 def_radius_setter(self, value: float) -> None:
 # for example only
 self.length = value * 2
 @radius.inplace.expression
 @classmethod
 def_radius_expression(cls) -> ColumnElement[float]:
 return type_coerce(func.abs(cls.length) / 2, Float)

Using hybrid_property.inplace further qualifies the use of the decorator that a new copy should not be made, thereby maintaining the Interval.radius name while allowing additional methods Interval._radius_setter and Interval._radius_expression to be differently named.

Defining Setters¶

The hybrid_property.setter() modifier allows the construction of a custom setter method, that can modify values on the object:

classInterval(Base):
 # ...
 @hybrid_property
 deflength(self) -> int:
 return self.end - self.start
 @length.inplace.setter
 def_length_setter(self, value: int) -> None:
 self.end = self.start + value

The length(self, value) method is now called upon set:

>>> i1 = Interval(5, 10)
>>> i1.length
5
>>> i1.length = 12
>>> i1.end
17

Supporting ORM Bulk INSERT and UPDATE¶

Hybrids have support for use in ORM Bulk INSERT/UPDATE operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. There are two distinct hooks that may be used supply a hybrid value within a DML operation:

1. The hybrid_property.update_expression() hook indicates a method that can provide one or more expressions to render in the SET clause of an UPDATE or INSERT statement, in response to when a hybrid attribute is referenced directly in the UpdateBase.values() method; i.e. the use shown in ORM UPDATE and DELETE with Custom WHERE Criteria and ORM Bulk Insert with Per Row SQL Expressions

2. The hybrid_property.bulk_dml() hook indicates a method that can intercept individual parameter dictionaries sent to Session.execute(), i.e. the use shown at ORM Bulk INSERT Statements as well as ORM Bulk UPDATE by Primary Key.

fromsqlalchemyimport from_dml_column
classProduct(Base):
 __tablename__ = "product"
 id: Mapped[int] = mapped_column(primary_key=True)
 price: Mapped[float]
 tax_rate: Mapped[float]
 @hybrid_property
 deftotal_price(self) -> float:
 return self.price * (1 + self.tax_rate)
 @total_price.inplace.update_expression
 @classmethod
 def_total_price_update_expression(
 cls, value: Any
 ) -> List[Tuple[Any, Any]]:
 return [(cls.price, value / (1 + from_dml_column(cls.tax_rate)))]

>>> fromsqlalchemyimport update
>>> print(
... update(Product).values(
... {Product.tax_rate: 0.08, Product.total_price: 125.00}
... )
... )
UPDATEproductSETtax_rate=:tax_rate,price=(:total_price/(:tax_rate+:param_1))

>>> fromsqlalchemyimport update
>>> print(update(Product).values({Product.total_price: 125.00}))
UPDATEproductSETprice=(:total_price/(tax_rate+:param_1))

fromtypingimport MutableMapping
classProduct(Base):
 __tablename__ = "product"
 id: Mapped[int] = mapped_column(primary_key=True)
 price: Mapped[float]
 tax_rate: Mapped[float]
 @hybrid_property
 deftotal_price(self) -> float:
 return self.price * (1 + self.tax_rate)
 @total_price.inplace.bulk_dml
 @classmethod
 def_total_price_bulk_dml(
 cls, mapping: MutableMapping[str, Any], value: float
 ) -> None:
 mapping["price"] = value / (1 + mapping["tax_rate"])

# Bulk INSERT
session.execute(
 insert(Product),
 [
 {"tax_rate": 0.08, "total_price": 125.00},
 {"tax_rate": 0.05, "total_price": 110.00},
 ],
)

Working with Relationships¶

There’s no essential difference when creating hybrids that work with related objects as opposed to column-based data. The need for distinct expressions tends to be greater. The two variants we’ll illustrate are the "join-dependent" hybrid, and the "correlated subquery" hybrid.

from__future__import annotations
fromdecimalimport Decimal
fromtypingimport cast
fromtypingimport List
fromtypingimport Optional
fromsqlalchemyimport ForeignKey
fromsqlalchemyimport Numeric
fromsqlalchemyimport String
fromsqlalchemyimport SQLColumnExpression
fromsqlalchemy.ext.hybridimport hybrid_property
fromsqlalchemy.ormimport DeclarativeBase
fromsqlalchemy.ormimport Mapped
fromsqlalchemy.ormimport mapped_column
fromsqlalchemy.ormimport relationship
classBase(DeclarativeBase):
 pass
classSavingsAccount(Base):
 __tablename__ = "account"
 id: Mapped[int] = mapped_column(primary_key=True)
 user_id: Mapped[int] = mapped_column(ForeignKey("user.id"))
 balance: Mapped[Decimal] = mapped_column(Numeric(15, 5))
 owner: Mapped[User] = relationship(back_populates="accounts")
classUser(Base):
 __tablename__ = "user"
 id: Mapped[int] = mapped_column(primary_key=True)
 name: Mapped[str] = mapped_column(String(100))
 accounts: Mapped[List[SavingsAccount]] = relationship(
 back_populates="owner", lazy="selectin"
 )
 @hybrid_property
 defbalance(self) -> Optional[Decimal]:
 if self.accounts:
 return self.accounts[0].balance
 else:
 return None
 @balance.inplace.setter
 def_balance_setter(self, value: Optional[Decimal]) -> None:
 assert value is not None
 if not self.accounts:
 account = SavingsAccount(owner=self)
 else:
 account = self.accounts[0]
 account.balance = value
 @balance.inplace.expression
 @classmethod
 def_balance_expression(cls) -> SQLColumnExpression[Optional[Decimal]]:
 return cast(
 "SQLColumnExpression[Optional[Decimal]]",
 SavingsAccount.balance,
 )

>>> fromsqlalchemyimport select
>>> print(
... select(User, User.balance)
... .join(User.accounts)
... .filter(User.balance > 5000)
... )
SELECT"user".idASuser_id,"user".nameASuser_name,
account.balanceASaccount_balance
FROM"user"JOINaccountON"user".id=account.user_id
WHEREaccount.balance>:balance_1

>>> fromsqlalchemyimport select
>>> fromsqlalchemyimport or_
>>> print(
... select(User, User.balance)
... .outerjoin(User.accounts)
... .filter(or_(User.balance < 5000, User.balance == None))
... )
SELECT"user".idASuser_id,"user".nameASuser_name,
account.balanceASaccount_balance
FROM"user"LEFTOUTERJOINaccountON"user".id=account.user_id
WHEREaccount.balance<:balance_1ORaccount.balanceISNULL

from__future__import annotations
fromdecimalimport Decimal
fromtypingimport List
fromsqlalchemyimport ForeignKey
fromsqlalchemyimport func
fromsqlalchemyimport Numeric
fromsqlalchemyimport select
fromsqlalchemyimport SQLColumnExpression
fromsqlalchemyimport String
fromsqlalchemy.ext.hybridimport hybrid_property
fromsqlalchemy.ormimport DeclarativeBase
fromsqlalchemy.ormimport Mapped
fromsqlalchemy.ormimport mapped_column
fromsqlalchemy.ormimport relationship
classBase(DeclarativeBase):
 pass
classSavingsAccount(Base):
 __tablename__ = "account"
 id: Mapped[int] = mapped_column(primary_key=True)
 user_id: Mapped[int] = mapped_column(ForeignKey("user.id"))
 balance: Mapped[Decimal] = mapped_column(Numeric(15, 5))
 owner: Mapped[User] = relationship(back_populates="accounts")
classUser(Base):
 __tablename__ = "user"
 id: Mapped[int] = mapped_column(primary_key=True)
 name: Mapped[str] = mapped_column(String(100))
 accounts: Mapped[List[SavingsAccount]] = relationship(
 back_populates="owner", lazy="selectin"
 )
 @hybrid_property
 defbalance(self) -> Decimal:
 return sum(
 (acc.balance for acc in self.accounts), start=Decimal("0")
 )
 @balance.inplace.expression
 @classmethod
 def_balance_expression(cls) -> SQLColumnExpression[Decimal]:
 return (
 select(func.sum(SavingsAccount.balance))
 .where(SavingsAccount.user_id == cls.id)
 .label("total_balance")
 )

>>> fromsqlalchemyimport select
>>> print(select(User).filter(User.balance > 400))
SELECT"user".id,"user".name
FROM"user"
WHERE(
SELECTsum(account.balance)ASsum_1FROMaccount
WHEREaccount.user_id="user".id
)>:param_1

Building Custom Comparators¶

The hybrid property also includes a helper that allows construction of custom comparators. A comparator object allows one to customize the behavior of each SQLAlchemy expression operator individually. They are useful when creating custom types that have some highly idiosyncratic behavior on the SQL side.

The example class below allows case-insensitive comparisons on the attribute named word_insensitive:

from__future__import annotations
fromtypingimport Any
fromsqlalchemyimport ColumnElement
fromsqlalchemyimport func
fromsqlalchemy.ext.hybridimport Comparator
fromsqlalchemy.ext.hybridimport hybrid_property
fromsqlalchemy.ormimport DeclarativeBase
fromsqlalchemy.ormimport Mapped
fromsqlalchemy.ormimport mapped_column
classBase(DeclarativeBase):
 pass
classCaseInsensitiveComparator(Comparator[str]):
 def__eq__(self, other: Any) -> ColumnElement[bool]: # type: ignore[override] # noqa: E501
 return func.lower(self.__clause_element__()) == func.lower(other)
classSearchWord(Base):
 __tablename__ = "searchword"
 id: Mapped[int] = mapped_column(primary_key=True)
 word: Mapped[str]
 @hybrid_property
 defword_insensitive(self) -> str:
 return self.word.lower()
 @word_insensitive.inplace.comparator
 @classmethod
 def_word_insensitive_comparator(cls) -> CaseInsensitiveComparator:
 return CaseInsensitiveComparator(cls.word)

Above, SQL expressions against word_insensitive will apply the LOWER() SQL function to both sides:

>>> fromsqlalchemyimport select
>>> print(select(SearchWord).filter_by(word_insensitive="Trucks"))
SELECTsearchword.id,searchword.word
FROMsearchword
WHERElower(searchword.word)=lower(:lower_1)

The CaseInsensitiveComparator above implements part of the ColumnOperators interface. A "coercion" operation like lowercasing can be applied to all comparison operations (i.e. eq, lt, gt, etc.) using Operators.operate():

classCaseInsensitiveComparator(Comparator):
 defoperate(self, op, other, **kwargs):
 return op(
 func.lower(self.__clause_element__()),
 func.lower(other),
 **kwargs,
 )

Reusing Hybrid Properties across Subclasses¶

A hybrid can be referred to from a superclass, to allow modifying methods like hybrid_property.getter(), hybrid_property.setter() to be used to redefine those methods on a subclass. This is similar to how the standard Python @property object works:

classFirstNameOnly(Base):
 # ...
 first_name: Mapped[str]
 @hybrid_property
 defname(self) -> str:
 return self.first_name
 @name.inplace.setter
 def_name_setter(self, value: str) -> None:
 self.first_name = value
classFirstNameLastName(FirstNameOnly):
 # ...
 last_name: Mapped[str]
 # 'inplace' is not used here; calling getter creates a copy
 # of FirstNameOnly.name that is local to FirstNameLastName
 @FirstNameOnly.name.getter
 defname(self) -> str:
 return self.first_name + " " + self.last_name
 @name.inplace.setter
 def_name_setter(self, value: str) -> None:
 self.first_name, self.last_name = value.split(" ", 1)

Above, the FirstNameLastName class refers to the hybrid from FirstNameOnly.name to repurpose its getter and setter for the subclass.

When overriding hybrid_property.expression() and hybrid_property.comparator() alone as the first reference to the superclass, these names conflict with the same-named accessors on the class- level QueryableAttribute object returned at the class level. To override these methods when referring directly to the parent class descriptor, add the special qualifier hybrid_property.overrides, which will de- reference the instrumented attribute back to the hybrid object:

classFirstNameLastName(FirstNameOnly):
 # ...
 last_name: Mapped[str]
 @FirstNameOnly.name.overrides.expression
 @classmethod
 defname(cls):
 return func.concat(cls.first_name, " ", cls.last_name)

Hybrid Value Objects¶

In the example shown previously at Building Custom Comparators, if we were to compare the word_insensitive attribute of a SearchWord instance to a plain Python string, the plain Python string would not be coerced to lower case - the CaseInsensitiveComparator we built, being returned by @word_insensitive.comparator, only applies to the SQL side.

A more comprehensive form of the custom comparator is to construct a Hybrid Value Object. This technique applies the target value or expression to a value object which is then returned by the accessor in all cases. The value object allows control of all operations upon the value as well as how compared values are treated, both on the SQL expression side as well as the Python value side. Replacing the previous CaseInsensitiveComparator class with a new CaseInsensitiveWord class:

fromsqlalchemyimport func
fromsqlalchemy.ext.hybridimport Comparator
classCaseInsensitiveWord(Comparator):
 "Hybrid value representing a lower case representation of a word."
 def__init__(self, word):
 if isinstance(word, str):
 self.word = word.lower()
 else:
 self.word = func.lower(word)
 defoperate(self, op, other, **kwargs):
 if not isinstance(other, CaseInsensitiveWord):
 other = CaseInsensitiveWord(other)
 return op(self.word, other.word, **kwargs)
 def__clause_element__(self):
 return self.word
 def__str__(self):
 return self.word
 key = "word"
 "Label to apply to Query tuple results"

Above, the CaseInsensitiveWord object represents self.word, which may be a SQL function, or may be a Python native string. The hybrid value object should implement __clause_element__(), which allows the object to be coerced into a SQL-capable value when used in SQL expression constructs, as well as Python comparison methods such as __eq__(), which is accomplished in the above example by subclassing Comparator and overriding the operate() method.

With __clause_element__() provided, our SearchWord class can now deliver the CaseInsensitiveWord object unconditionally from a single hybrid method, returning an object that behaves appropriately in both value-based and SQL contexts:

classSearchWord(Base):
 __tablename__ = "searchword"
 id: Mapped[int] = mapped_column(primary_key=True)
 word: Mapped[str]
 @hybrid_property
 defword_insensitive(self) -> CaseInsensitiveWord:
 return CaseInsensitiveWord(self.word)

The class-level version of CaseInsensitiveWord will work in SQL constructs:

>>> print(select(SearchWord).filter(SearchWord.word_insensitive == "Trucks"))
SELECTsearchword.idASsearchword_id,searchword.wordASsearchword_word
FROMsearchword
WHERElower(searchword.word)=:lower_1

By also subclassing Comparator and providing an implementation for operate(), the word_insensitive attribute also has case-insensitive comparison behavior universally, including SQL expression and Python expression (note the Python value is converted to lower case on the Python side here):

>>> fromsqlalchemy.ormimport aliased
>>> sw1 = aliased(SearchWord)
>>> sw2 = aliased(SearchWord)
>>> print(
... select(sw1.word_insensitive, sw2.word_insensitive).filter(
... sw1.word_insensitive > sw2.word_insensitive
... )
... )
SELECTlower(searchword_1.word)ASlower_1,
lower(searchword_2.word)ASlower_2
FROMsearchwordASsearchword_1,searchwordASsearchword_2
WHERElower(searchword_1.word)>lower(searchword_2.word)

Python only expression:

>>> ws1 = SearchWord(word="SomeWord")
>>> ws1.word_insensitive == "sOmEwOrD"
True
>>> ws1.word_insensitive == "XOmEwOrX"
False
>>> print(ws1.word_insensitive)
someword

The Hybrid Value pattern is very useful for any kind of value that may have multiple representations, such as timestamps, time deltas, units of measurement, currencies and encrypted passwords.

fromdataclassesimport dataclass
fromsqlalchemyimport tuple_
fromsqlalchemy.ext.hybridimport Comparator
fromsqlalchemyimport SQLColumnExpression
@dataclass(eq=False)
classPoint(Comparator):
 x: int | SQLColumnExpression[int]
 y: int | SQLColumnExpression[int]
 defoperate(self, op, other, **kwargs):
 return op(self.x, other.x) & op(self.y, other.y)
 def__clause_element__(self):
 return tuple_(self.x, self.y)

fromsqlalchemy.ormimport DeclarativeBase, Mapped
fromsqlalchemy.ormimport mapped_column
fromsqlalchemy.ext.hybridimport hybrid_property
classBase(DeclarativeBase):
 pass
classVertex(Base):
 __tablename__ = "vertices"
 id: Mapped[int] = mapped_column(primary_key=True)
 x1: Mapped[int]
 y1: Mapped[int]
 x2: Mapped[int]
 y2: Mapped[int]
 @hybrid_property
 defstart(self) -> Point:
 return Point(self.x1, self.y1)
 @start.inplace.setter
 def_set_start(self, value: Point) -> None:
 self.x1 = value.x
 self.y1 = value.y
 @hybrid_property
 defend(self) -> Point:
 return Point(self.x2, self.y2)
 @end.inplace.setter
 def_set_end(self, value: Point) -> None:
 self.x2 = value.x
 self.y2 = value.y
 def__repr__(self) -> str:
 return f"Vertex(start={self.start}, end={self.end})"

>>> v1 = Vertex(start=Point(3, 4), end=Point(15, 10))
>>> v1.end == Point(15, 10)
True
>>> stmt = (
...  select(Vertex)
...  .where(Vertex.start == Point(3, 4))
...  .where(Vertex.end < Point(7, 8))
... )
>>> print(stmt)
SELECT vertices.id, vertices.x1, vertices.y1, vertices.x2, vertices.y2
FROM vertices
WHERE vertices.x1 = :x1_1 AND vertices.y1 = :y1_1 AND vertices.x2 < :x2_1 AND vertices.y2 < :y2_1

classLocation(Base):
 __tablename__ = "location"
 id: Mapped[int] = mapped_column(primary_key=True)
 x: Mapped[int]
 y: Mapped[int]
 @hybrid_property
 defcoordinates(self) -> Point:
 return Point(self.x, self.y)
 @coordinates.inplace.update_expression
 @classmethod
 def_coordinates_update_expression(
 cls, value: Any
 ) -> List[Tuple[Any, Any]]:
 assert isinstance(value, Point)
 return [(cls.x, value.x), (cls.y, value.y)]

>>> fromsqlalchemyimport update
>>> print(
... update(Location)
... .where(Location.id == 5)
... .values({Location.coordinates: Point(25, 17)})
... )
UPDATElocationSETx=:x,y=:yWHERElocation.id=:id_1

fromtypingimport MutableMapping
classLocation(Base):
 # ... (same as above)
 @coordinates.inplace.bulk_dml
 @classmethod
 def_coordinates_bulk_dml(
 cls, mapping: MutableMapping[str, Any], value: Point
 ) -> None:
 mapping["x"] = value.x
 mapping["y"] = value.y

# Bulk INSERT
session.execute(
 insert(Location),
 [
 {"id": 1, "coordinates": Point(10, 20)},
 {"id": 2, "coordinates": Point(30, 40)},
 ],
)
# Bulk UPDATE
session.execute(
 update(Location),
 [
 {"id": 1, "coordinates": Point(15, 25)},
 {"id": 2, "coordinates": Point(35, 45)},
 ],
)

API Reference¶

classsqlalchemy.ext.hybrid.hybrid_method¶

inherits from sqlalchemy.orm.base.InspectionAttrInfo, typing.Generic

A decorator which allows definition of a Python object method with both instance-level and class-level behavior.

Member Name	Description
__init__()	Create a new hybrid_method.
expression()	Provide a modifying decorator that defines a SQL-expression producing method.
extension_type	The extension type, if any. Defaults to NotExtension.NOT_EXTENSION
is_attribute	True if this object is a Python descriptor.

method sqlalchemy.ext.hybrid.hybrid_method. __init__(func:Callable[[Concatenate[Any,_P]],_R], expr:Callable[[Concatenate[Any,_P]],SQLCoreOperations[_R]]|None=None)¶

Create a new hybrid_method.

Usage is typically via decorator:

fromsqlalchemy.ext.hybridimport hybrid_method
classSomeClass:
 @hybrid_method
 defvalue(self, x, y):
 return self._value + x + y
 @value.expression
 @classmethod
 defvalue(cls, x, y):
 return func.some_function(cls._value, x, y)

method sqlalchemy.ext.hybrid.hybrid_method. expression(expr:Callable[[Concatenate[Any,_P]],SQLCoreOperations[_R]]) → hybrid_method [_P,_R]¶

Provide a modifying decorator that defines a SQL-expression producing method.

attribute sqlalchemy.ext.hybrid.hybrid_method. extension_type:InspectionAttrExtensionType ='HYBRID_METHOD'¶

The extension type, if any. Defaults to NotExtension.NOT_EXTENSION

See also

HybridExtensionType

AssociationProxyExtensionType

propertyinplace:Self¶

Return the inplace mutator for this hybrid_method.

The hybrid_method class already performs "in place" mutation when the hybrid_method.expression() decorator is called, so this attribute returns Self.

Added in version 2.0.4.

See also

Using inplace to create pep-484 compliant hybrid properties

attribute sqlalchemy.ext.hybrid.hybrid_method. is_attribute=True¶

True if this object is a Python descriptor.

This can refer to one of many types. Usually a QueryableAttribute which handles attributes events on behalf of a MapperProperty. But can also be an extension type such as AssociationProxy or hybrid_property. The InspectionAttr.extension_type will refer to a constant identifying the specific subtype.

See also

Mapper.all_orm_descriptors

classsqlalchemy.ext.hybrid.hybrid_property¶

inherits from sqlalchemy.orm.base.InspectionAttrInfo, sqlalchemy.orm.base.ORMDescriptor

A decorator which allows definition of a Python descriptor with both instance-level and class-level behavior.

Member Name	Description
__init__()	Create a new hybrid_property.
bulk_dml()	Define a setter for bulk dml.
comparator()	Provide a modifying decorator that defines a custom comparator producing method.
deleter()	Provide a modifying decorator that defines a deletion method.
expression()	Provide a modifying decorator that defines a SQL-expression producing method.
extension_type	The extension type, if any. Defaults to NotExtension.NOT_EXTENSION
getter()	Provide a modifying decorator that defines a getter method.
is_attribute	True if this object is a Python descriptor.
setter()	Provide a modifying decorator that defines a setter method.
update_expression()	Provide a modifying decorator that defines an UPDATE tuple producing method.

method sqlalchemy.ext.hybrid.hybrid_property. __init__(fget:_HybridGetterType[_T], fset:_HybridSetterType[_T]|None=None, fdel:_HybridDeleterType[_T]|None=None, expr:_HybridExprCallableType[_T]|None=None, custom_comparator:Comparator [_T]|None=None, update_expr:_HybridUpdaterType[_T]|None=None, bulk_dml_setter:_HybridBulkDMLType[_T]|None=None)¶

Create a new hybrid_property.

Usage is typically via decorator:

fromsqlalchemy.ext.hybridimport hybrid_property
classSomeClass:
 @hybrid_property
 defvalue(self):
 return self._value
 @value.setter
 defvalue(self, value):
 self._value = value

method sqlalchemy.ext.hybrid.hybrid_property. bulk_dml(meth:_HybridBulkDMLType[_T]) → hybrid_property [_T]¶

Define a setter for bulk dml.

Added in version 2.1.

method sqlalchemy.ext.hybrid.hybrid_property. comparator(comparator:_HybridComparatorCallableType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines a custom comparator producing method.

The return value of the decorated method should be an instance of Comparator.

Note

The hybrid_property.comparator() decorator replaces the use of the hybrid_property.expression() decorator. They cannot be used together.

When a hybrid is invoked at the class level, the Comparator object given here is wrapped inside of a specialized QueryableAttribute, which is the same kind of object used by the ORM to represent other mapped attributes. The reason for this is so that other class-level attributes such as docstrings and a reference to the hybrid itself may be maintained within the structure that’s returned, without any modifications to the original comparator object passed in.

Note

When referring to a hybrid property from an owning class (e.g. SomeClass.some_hybrid), an instance of QueryableAttribute is returned, representing the expression or comparator object as this hybrid object. However, that object itself has accessors called expression and comparator; so when attempting to override these decorators on a subclass, it may be necessary to qualify it using the hybrid_property.overrides modifier first. See that modifier for details.

method sqlalchemy.ext.hybrid.hybrid_property. deleter(fdel:_HybridDeleterType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines a deletion method.

method sqlalchemy.ext.hybrid.hybrid_property. expression(expr:_HybridExprCallableType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines a SQL-expression producing method.

When a hybrid is invoked at the class level, the SQL expression given here is wrapped inside of a specialized QueryableAttribute, which is the same kind of object used by the ORM to represent other mapped attributes. The reason for this is so that other class-level attributes such as docstrings and a reference to the hybrid itself may be maintained within the structure that’s returned, without any modifications to the original SQL expression passed in.

Note

When referring to a hybrid property from an owning class (e.g. SomeClass.some_hybrid), an instance of QueryableAttribute is returned, representing the expression or comparator object as well as this hybrid object. However, that object itself has accessors called expression and comparator; so when attempting to override these decorators on a subclass, it may be necessary to qualify it using the hybrid_property.overrides modifier first. See that modifier for details.

See also

Defining Expression Behavior Distinct from Attribute Behavior

attribute sqlalchemy.ext.hybrid.hybrid_property. extension_type:InspectionAttrExtensionType ='HYBRID_PROPERTY'¶

The extension type, if any. Defaults to NotExtension.NOT_EXTENSION

See also

HybridExtensionType

AssociationProxyExtensionType

method sqlalchemy.ext.hybrid.hybrid_property. getter(fget:_HybridGetterType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines a getter method.

propertyinplace:_InPlace[_T]¶

Return the inplace mutator for this hybrid_property.

This is to allow in-place mutation of the hybrid, allowing the first hybrid method of a certain name to be reused in order to add more methods without having to name those methods the same, e.g.:

classInterval(Base):
 # ...
 @hybrid_property
 defradius(self) -> float:
 return abs(self.length) / 2
 @radius.inplace.setter
 def_radius_setter(self, value: float) -> None:
 self.length = value * 2
 @radius.inplace.expression
 def_radius_expression(cls) -> ColumnElement[float]:
 return type_coerce(func.abs(cls.length) / 2, Float)

Added in version 2.0.4.

See also

Using inplace to create pep-484 compliant hybrid properties

attribute sqlalchemy.ext.hybrid.hybrid_property. is_attribute=True¶

True if this object is a Python descriptor.

This can refer to one of many types. Usually a QueryableAttribute which handles attributes events on behalf of a MapperProperty. But can also be an extension type such as AssociationProxy or hybrid_property. The InspectionAttr.extension_type will refer to a constant identifying the specific subtype.

See also

Mapper.all_orm_descriptors

propertyoverrides:Self¶

Prefix for a method that is overriding an existing attribute.

The hybrid_property.overrides accessor just returns this hybrid object, which when called at the class level from a parent class, will de-reference the "instrumented attribute" normally returned at this level, and allow modifying decorators like hybrid_property.expression() and hybrid_property.comparator() to be used without conflicting with the same-named attributes normally present on the QueryableAttribute:

classSuperClass:
 # ...
 @hybrid_property
 deffoobar(self):
 return self._foobar
classSubClass(SuperClass):
 # ...
 @SuperClass.foobar.overrides.expression
 deffoobar(cls):
 return func.subfoobar(self._foobar)

See also

Reusing Hybrid Properties across Subclasses

method sqlalchemy.ext.hybrid.hybrid_property. setter(fset:_HybridSetterType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines a setter method.

method sqlalchemy.ext.hybrid.hybrid_property. update_expression(meth:_HybridUpdaterType[_T]) → hybrid_property [_T]¶

Provide a modifying decorator that defines an UPDATE tuple producing method.

The method accepts a single value, which is the value to be rendered into the SET clause of an UPDATE statement. The method should then process this value into individual column expressions that fit into the ultimate SET clause, and return them as a sequence of 2-tuples. Each tuple contains a column expression as the key and a value to be rendered.

E.g.:

classPerson(Base):
 # ...
 first_name = Column(String)
 last_name = Column(String)
 @hybrid_property
 deffullname(self):
 return first_name + " " + last_name
 @fullname.update_expression
 deffullname(cls, value):
 fname, lname = value.split(" ", 1)
 return [(cls.first_name, fname), (cls.last_name, lname)]

classsqlalchemy.ext.hybrid.Comparator¶

inherits from sqlalchemy.orm.PropComparator

A helper class that allows easy construction of custom PropComparator classes for usage with hybrids.

classsqlalchemy.ext.hybrid.HybridExtensionType¶

inherits from sqlalchemy.orm.base.InspectionAttrExtensionType

Member Name	Description
HYBRID_METHOD	Symbol indicating an InspectionAttr that’s of type hybrid_method.
HYBRID_PROPERTY

attribute sqlalchemy.ext.hybrid.HybridExtensionType. HYBRID_METHOD='HYBRID_METHOD'¶

Symbol indicating an InspectionAttr that’s of type hybrid_method.

Is assigned to the InspectionAttr.extension_type attribute.

See also

Mapper.all_orm_attributes

attribute sqlalchemy.ext.hybrid.HybridExtensionType. HYBRID_PROPERTY='HYBRID_PROPERTY'¶

Symbol indicating an InspectionAttr that’s

of type hybrid_method.

Is assigned to the InspectionAttr.extension_type attribute.

See also

Mapper.all_orm_attributes