From a0ba7ce055d38d4c2030d2985d78d8ebf5434416 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 5 Jul 2015 11:16:26 -0400
Subject: [PATCH] - 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)
---
 lib/sqlalchemy/orm/mapper.py | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

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`
-- 
2.47.3