From 8250a4248fceaa3f4fbaebea3ff6a7f626299659 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 24 Jan 2018 18:03:04 -0500 Subject: Rework synonym, synonym_for documentation The map_column example was incorrect, and overall the purpose of this parameter as well as that of synonym_for was not explained; examples added along with more encouragement to use hybrids. Change-Id: I20bd286f541f798daa81fa598c0f31db1f5aa6ed --- lib/sqlalchemy/ext/declarative/api.py | 37 ++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) (limited to 'lib/sqlalchemy/ext/declarative/api.py') 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 ` 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): -- cgit v1.2.1