sqlalchemy.ext.declarative.declared_attr

Mark a class-level method as representing the definition of a mapped property or Declarative directive. :class:`_orm.declared_attr` is typically applied as a decorator to a class level method, turning the attribute into a scalar-like property that can be invoked from the uninstantiated class. The Declarative mapping process looks for these :class:`_orm.declared_attr` callables as it scans classes, and assumes any attribute marked with :class:`_orm.declared_attr` will be a callable that will produce an object specific to the Declarative mapping or table configuration. :class:`_orm.declared_attr` is usually applicable to :ref:`mixins <orm_mixins_toplevel>`, to define relationships that are to be applied to different implementors of the class. It may also be used to define dynamically generated column expressions and other Declarative attributes. Example:: class ProvidesUserMixin: "A mixin that adds a 'user' relationship to classes." user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id")) @declared_attr def user(cls) -> Mapped["User"]: return relationship("User") When used with Declarative directives such as ``__tablename__``, the :meth:`_orm.declared_attr.directive` modifier may be used which indicates to :pep:`484` typing tools that the given method is not dealing with :class:`_orm.Mapped` attributes:: class CreateTableName: @declared_attr.directive def __tablename__(cls) -> str: return cls.__name__.lower() :class:`_orm.declared_attr` can also be applied directly to mapped classes, to allow for attributes that dynamically configure themselves on subclasses when using mapped inheritance schemes. Below illustrates :class:`_orm.declared_attr` to create a dynamic scheme for generating the :paramref:`_orm.Mapper.polymorphic_identity` parameter for subclasses:: class Employee(Base): __tablename__ = 'employee' id: Mapped[int] = mapped_column(primary_key=True) type: Mapped[str] = mapped_column(String(50)) @declared_attr.directive def __mapper_args__(cls) -> Dict[str, Any]: if cls.__name__ == 'Employee': return { "polymorphic_on":cls.type, "polymorphic_identity":"Employee" } else: return {"polymorphic_identity":cls.__name__} class Engineer(Employee): pass :class:`_orm.declared_attr` supports decorating functions that are explicitly decorated with ``@classmethod``. This is never necessary from a runtime perspective, however may be needed in order to support :pep:`484` typing tools that don't otherwise recognize the decorated function as having class-level behaviors for the ``cls`` parameter:: class SomethingMixin: x: Mapped[int] y: Mapped[int] @declared_attr @classmethod def x_plus_y(cls) -> Mapped[int]: return column_property(cls.x + cls.y) .. versionadded:: 2.0 - :class:`_orm.declared_attr` can accommodate a function decorated with ``@classmethod`` to help with :pep:`484` integration where needed. .. seealso:: :ref:`orm_mixins_toplevel` - Declarative Mixin documentation with background on use patterns for :class:`_orm.declared_attr`.