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

system

Change-Id: I7d4048b92fcd3a7c7630c43aa9390d983f447c0a

1 files changed, 7 insertions, 0 deletions

diff --git a/lib/sqlalchemy/sql/annotation.py b/lib/sqlalchemy/sql/annotation.py
index 834c93912..e6f6311c4 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):