From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 5 Jul 2015 15:16:26 +0000 (-0400)
Subject: - add a warning suggesting to use the dictionary form of access
X-Git-Tag: rel_0_9_10~3
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a0ba7ce055d38d4c2030d2985d78d8ebf5434416;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a warning suggesting to use the dictionary form of access
if the name of the attribute being accessed is non-specific,
thereby avoiding collisions on names like items, values, keys.
fixes #3475

(cherry picked from commit 6fcc5d4a07e5c409a7d8438582598d0e90562ea0)
---

diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index fb1003d8f4..fc7252ac9b 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -1976,6 +1976,17 @@ class Mapper(_InspectionAttr):
         returned, inclding :attr:`.synonyms`, :attr:`.column_attrs`,
         :attr:`.relationships`, and :attr:`.composites`.
 
+        .. warning::
+
+            the :attr:`.Mapper.relationships` accessor namespace is an
+            instance of :class:`.OrderedProperties`.  This is
+            a dictionary-like object which includes a small number of
+            named methods such as :meth:`.OrderedProperties.items`
+            and :meth:`.OrderedProperties.values`.  When
+            accessing attributes dynamically, favor using the dict-access
+            scheme, e.g. ``mapper.attrs[somename]`` over
+            ``getattr(mapper.attrs, somename)`` to avoid name collisions.
+
         .. seealso::
 
             :attr:`.Mapper.all_orm_descriptors`
@@ -2011,6 +2022,17 @@ class Mapper(_InspectionAttr):
         referring to the collection of mapped properties via
         :attr:`.Mapper.attrs`.
 
+        .. warning::
+
+            the :attr:`.Mapper.relationships` accessor namespace is an
+            instance of :class:`.OrderedProperties`.  This is
+            a dictionary-like object which includes a small number of
+            named methods such as :meth:`.OrderedProperties.items`
+            and :meth:`.OrderedProperties.values`.  When
+            accessing attributes dynamically, favor using the dict-access
+            scheme, e.g. ``mapper.attrs[somename]`` over
+            ``getattr(mapper.attrs, somename)`` to avoid name collisions.
+
         .. versionadded:: 0.8.0
 
         .. seealso::
@@ -2052,6 +2074,17 @@ class Mapper(_InspectionAttr):
         """Return a namespace of all :class:`.RelationshipProperty`
         properties maintained by this :class:`.Mapper`.
 
+        .. warning::
+
+            the :attr:`.Mapper.relationships` accessor namespace is an
+            instance of :class:`.OrderedProperties`.  This is
+            a dictionary-like object which includes a small number of
+            named methods such as :meth:`.OrderedProperties.items`
+            and :meth:`.OrderedProperties.values`.  When
+            accessing attributes dynamically, favor using the dict-access
+            scheme, e.g. ``mapper.attrs[somename]`` over
+            ``getattr(mapper.attrs, somename)`` to avoid name collisions.
+
         .. seealso::
 
             :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty`