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

(cherry picked from commit 292f5bec1cbfcaa9d16af8fe4149c7191f194f11)

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index fd8f9d53b461e35f8c379399a02c63af03efde01..154e9d1185d71941c7fc5441f8ec57c3bf7c9f25 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -597,6 +597,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