Include column_property composition examples

Add cross-linking between column_property() and ColumnProperty

Add section to describe using .expression

remove inherited-members from ColumnProperty to greatly
decrease verbosity

Fixes: #5179
Change-Id: Ic477b16350dbf551100b31d14ff3ba8ba8221a43

1 files changed, 27 insertions, 1 deletions

diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 7eabce80b..6ad8606e3 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -58,7 +58,7 @@ class ColumnProperty(StrategizedProperty):
     )
 
     def __init__(self, *columns, **kwargs):
-        r"""Provide a column-level property for use with a Mapper.
+        r"""Provide a column-level property for use with a mapping.
 
         Column-based properties can normally be applied to the mapper's
         ``properties`` dictionary using the :class:`.Column` element directly.
@@ -66,6 +66,9 @@ class ColumnProperty(StrategizedProperty):
         the mapper's selectable; examples include SQL expressions, functions,
         and scalar SELECT queries.
 
+        The :func:`.orm.column_property` function returns an instance of
+        :class:`.ColumnProperty`.
+
         Columns that aren't present in the mapper's selectable won't be
         persisted by the mapper and are effectively "read-only" attributes.
 
@@ -128,6 +131,14 @@ class ColumnProperty(StrategizedProperty):
 
                 :ref:`deferred_raiseload`
 
+        .. seealso::
+
+            :ref:`column_property_options` - to map columns while including
+            mapping options
+
+            :ref:`mapper_column_property_sql_expressions` - to map SQL
+            expressions
+
         """
         super(ColumnProperty, self).__init__()
         self._orig_columns = [
@@ -206,6 +217,21 @@ class ColumnProperty(StrategizedProperty):
     def expression(self):
         """Return the primary column or expression for this ColumnProperty.
 
+        E.g.::
+
+
+            class File(Base):
+                # ...
+
+                name = Column(String(64))
+                extension = Column(String(8))
+                filename = column_property(name + '.' + extension)
+                path = column_property('C:/' + filename.expression)
+
+        .. seealso::
+
+            :ref:`mapper_column_property_sql_expressions_composed`
+
         """
         return self.columns[0]