diff options
Diffstat (limited to 'lib/sqlalchemy/ext/declarative/api.py')
| -rw-r--r-- | lib/sqlalchemy/ext/declarative/api.py | 37 |
1 files changed, 26 insertions, 11 deletions
diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py index 5f9ffac2b..77a03bc4a 100644 --- a/lib/sqlalchemy/ext/declarative/api.py +++ b/lib/sqlalchemy/ext/declarative/api.py @@ -69,21 +69,36 @@ class DeclarativeMeta(type): def synonym_for(name, map_column=False): - """Decorator, make a Python @property a query synonym for a column. + """Decorator that produces an :func:`.orm.synonym` attribute in conjunction + with a Python descriptor. - A decorator version of :func:`~sqlalchemy.orm.synonym`. The function being - decorated is the 'descriptor', otherwise passes its arguments through to - synonym():: + The function being decorated is passed to :func:`.orm.synonym` as the + :paramref:`.orm.synonym.descriptor` parameter:: - @synonym_for('col') - @property - def prop(self): - return 'special sauce' + class MyClass(Base): + __tablename__ = 'my_table' + + id = Column(Integer, primary_key=True) + _job_status = Column("job_status", String(50)) + + @synonym_for("job_status") + @property + def job_status(self): + return "Status: %s" % self._job_status + + The :ref:`hybrid properties <mapper_hybrids>` feature of SQLAlchemy + is typically preferred instead of synonyms, which is a more legacy + feature. + + .. seealso:: + + :ref:`synonyms` - Overview of synonyms - The regular ``synonym()`` is also usable directly in a declarative setting - and may be convenient for read/write properties:: + :func:`.orm.synonym` - the mapper-level function - prop = synonym('col', descriptor=property(_read_prop, _write_prop)) + :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an + updated approach to augmenting attribute behavior more flexibly than + can be achieved with synonyms. """ def decorate(fn): |