From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 3 Aug 2015 21:46:34 +0000 (-0400)
Subject: - add a note clarifying query.with_labels(), fixes #3506
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3d4edfa51b4383906ed90e018c685c127f2fea9c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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 fd8f9d53b4..154e9d1185 100644
--- 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