- re-document synonyms and remove warnings about "superseded"; synonyms

are still useful, just include notes that for more complex descriptor operations,
hybrids are probably preferable

1 files changed, 50 insertions, 33 deletions

diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py
index daf125ea2..1156a140e 100644
--- a/lib/sqlalchemy/orm/descriptor_props.py
+++ b/lib/sqlalchemy/orm/descriptor_props.py
@@ -488,40 +488,57 @@ class SynonymProperty(DescriptorProperty):
     def __init__(self, name, map_column=None,
                             descriptor=None, comparator_factory=None,
                             doc=None):
-        """Denote an attribute name as a synonym to a mapped property.
+        """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.
 
-        .. versionchanged:: 0.7
-            :func:`.synonym` is superseded by the :mod:`~sqlalchemy.ext.hybrid`
-            extension.  See  the documentation for hybrids
-            at :ref:`hybrids_toplevel`.
-
-        Used with the ``properties`` dictionary sent to
-        :func:`~sqlalchemy.orm.mapper`::
-
-            class MyClass(object):
-                def _get_status(self):
-                    return self._status
-                def _set_status(self, value):
-                    self._status = value
-                status = property(_get_status, _set_status)
-
-            mapper(MyClass, sometable, properties={
-                "status":synonym("_status", map_column=True)
-            })
-
-        Above, the ``status`` attribute of MyClass will produce
-        expression behavior against the table column named ``status``,
-        using the Python attribute ``_status`` on the mapped class
-        to represent the underlying value.
-
-        :param name: the name of the existing mapped property, which can be
-          any other ``MapperProperty`` including column-based properties and
-          relationships.
-
-        :param map_column: if ``True``, an additional ``ColumnProperty`` is created
-          on the mapper automatically, using the synonym's name as the keyname of
-          the property, and the keyname of this ``synonym()`` as the name of the
-          column to map.
+        :param name: the name of the existing mapped property.  This
+          can refer to the string name of any :class:`.MapperProperty`
+          configured on the class, including column-bound attributes
+          and relationships.
+
+        :param descriptor: a Python :term:`descriptor` that will be used
+          as a getter (and potentially a setter) when this attribute is
+          accessed at the instance level.
+
+        :param map_column: if ``True``, the :func:`.synonym` construct will
+          locate the existing named :class:`.MapperProperty` based on the
+          attribute name of this :func:`.synonym`, and assign it to a new
+          attribute linked to the name of this :func:`.synonym`.
+          That is, given a mapping like::
+
+                class MyClass(Base):
+                    __tablename__ = 'my_table'
+
+                    id = Column(Integer, primary_key=True)
+                    job_status = Column(String(50))
+
+                    job_status = synonym("_job_status", map_column=True)
+
+          The above class ``MyClass`` will now have the ``job_status``
+          :class:`.Column` object mapped to the attribute named ``_job_status``,
+          and the attribute named ``job_status`` will refer to the synonym
+          itself.  This feature is typically used in conjunction with the
+          ``descriptor`` argument in order to link a user-defined descriptor
+          as a "wrapper" for an existing column.
+
+        :param comparator_factory: A subclass of :class:`.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
+            :ref:`mapper_hybrids` for a more effective technique.
+
+        .. seealso::
+
+            :ref:`synonyms` - examples of functionality.
+
+            :ref:`mapper_hybrids` - Hybrids provide a better approach for
+            more complicated attribute-wrapping schemes than synonyms.
 
         """