Add ColumnProperty.Comparator.expressions

Added an accessor :attr:`.ColumnProperty.Comparator.expressions` which
provides access to the group of columns mapped under a multi-column
:class:`.ColumnProperty` attribute.

Fixes: #5262
Change-Id: I44cf53ff0e6cf76a0c90eee4638ca96da3df8088

2 files changed, 24 insertions, 0 deletions

diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst
index d0e7c1ce4..e9f1b431e 100644
--- a/doc/build/orm/internals.rst
+++ b/doc/build/orm/internals.rst
@@ -21,6 +21,17 @@ sections, are listed here.
 .. autoclass:: sqlalchemy.orm.properties.ColumnProperty
     :members:
 
+    .. attribute:: Comparator.expressions
+
+         The full sequence of columns referenced by this
+         attribute, adjusted for any aliasing in progress.
+
+         .. versionadded:: 1.3.17
+
+         .. seealso::
+
+            :ref:`maptojoin` - usage example
+
 .. autoclass:: sqlalchemy.orm.descriptor_props.CompositeProperty
     :members:
 
diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst
index 01a615ae2..81679dd01 100644
--- a/doc/build/orm/nonstandard_mappings.rst
+++ b/doc/build/orm/nonstandard_mappings.rst
@@ -68,6 +68,19 @@ The natural primary key of the above mapping is the composite of
 is represented from an ``AddressUser`` object as
 ``(AddressUser.id, AddressUser.address_id)``.
 
+When referring to the ``AddressUser.id`` column, most SQL expressions will
+make use of only the first column in the list of columns mapped, as the
+two columns are synonymous.  However, for the special use case such as
+a GROUP BY expression where both columns must be referenced at the same
+time while making use of the proper context, that is, accommodating for
+aliases and similar, the accessor :attr:`.ColumnProperty.Comparator.expressions`
+may be used::
+
+    q = session.query(AddressUser).group_by(*AddressUser.id.expressions)
+
+.. versionadded:: 1.3.17 Added the
+   :attr:`.ColumnProperty.Comparator.expressions` accessor.
+
 
 .. note::