From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 9 Mar 2017 22:38:21 +0000 (-0500)
Subject: - add a note as to why we have this very complicated Annotated
X-Git-Tag: rel_1_1_7~12
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=75ceae6ea6493d44d616df1f21d180b3e7a2e8f5;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a note as to why we have this very complicated Annotated
system

Change-Id: I7d4048b92fcd3a7c7630c43aa9390d983f447c0a
---

diff --git a/lib/sqlalchemy/sql/annotation.py b/lib/sqlalchemy/sql/annotation.py
index 834c93912f..e6f6311c48 100644
--- a/lib/sqlalchemy/sql/annotation.py
+++ b/lib/sqlalchemy/sql/annotation.py
@@ -26,6 +26,13 @@ class Annotated(object):
     reason of keeping its hash value current.  When GC'ed, the
     hash value may be reused, causing conflicts.
 
+    .. note::  The rationale for Annotated producing a brand new class,
+       rather than placing the functionality directly within ClauseElement,
+       is **performance**.  The __hash__() method is absent on plain
+       ClauseElement which leads to significantly reduced function call
+       overhead, as the use of sets and dictionaries against ClauseElement
+       objects is prevalent, but most are not "annotated".
+
     """
 
     def __new__(cls, *args):