- add a note clarifying query.with_labels(), fixes #3506

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 8b3df08e762ad58d6d634f84d0378558568a93ab..e9b4e19820324cde2f0b76b28ada189a9b2afe8e 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -608,6 +608,16 @@ class Query(object):
         When the `Query` actually issues SQL to load rows, it always
         uses column labeling.
 
+        .. note:: The :meth:`.Query.with_labels` method *only* applies
+           the output of :attr:`.Query.statement`, and *not* to any of
+           the result-row invoking systems of :class:`.Query` itself, e.g.
+           :meth:`.Query.first`, :meth:`.Query.all`, etc.   To execute
+           a query using :meth:`.Query.with_labels`, invoke the
+           :attr:`.Query.statement` using :meth:`.Session.execute`::
+
+                result = session.execute(query.with_labels().statement)
+
+
         """
         self._with_labels = True