synonym does not create the proxying behavior unless the flag 'proxy=True' is set up

4 files changed, 23 insertions, 6 deletions

diff --git a/doc/build/content/adv_datamapping.txt b/doc/build/content/adv_datamapping.txt
index 5b16c9072..e46387c16 100644
--- a/doc/build/content/adv_datamapping.txt
+++ b/doc/build/content/adv_datamapping.txt
@@ -84,7 +84,7 @@ A common request is the ability to create custom class properties that override
        '_email': mytable.c.email
     })
 
-It is also possible to use the `select_by` and `get_by` functions on `Query` using the original property name, by establishing a `synonym`:
+It is also possible to route the the `select_by` and `get_by` functions on `Query` using the new property name, by establishing a `synonym`:
 
     {python}
     mapper(MyClass, mytable, proeprties = {
@@ -99,6 +99,20 @@ It is also possible to use the `select_by` and `get_by` functions on `Query` usi
     # now you can select_by(email)
     result = session.query(MyClass).select_by(email='john@smith.com')
 
+Synonym can be established with the flag "proxy=True", to create a class-level proxy to the actual property:
+
+    {python}
+    mapper(MyClass, mytable, proeprties = {
+        '_email': mytable.c.email
+        'email' : synonym('_email', proxy=True)
+    })
+
+    x = MyClass()
+    x.email = 'john@doe.com'
+    
+    >>> x._email
+    'john@doe.com'
+    
 The `synonym` keyword is currently an [Alpha Feature][alpha_api].
 
 #### Custom List Classes {@name=customlist}
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index d2d8bd532..2d9a4e845 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -45,9 +45,9 @@ def mapper(class_, table=None, *args, **params):
     """return a new Mapper object."""
     return Mapper(class_, table, *args, **params)
 
-def synonym(name):
+def synonym(name, proxy=False):
     """set up 'name' as a synonym to another MapperProperty."""
-    return properties.SynonymProperty(name)
+    return properties.SynonymProperty(name, proxy=proxy)
     
 def clear_mappers():
     """remove all mappers that have been created thus far.  when new mappers are 
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index d409352e4..768b51959 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -21,13 +21,16 @@ from interfaces import *
 
 
 class SynonymProperty(MapperProperty):
-    def __init__(self, name):
+    def __init__(self, name, proxy=False):
         self.name = name
+        self.proxy = proxy
     def setup(self, querycontext, **kwargs):
         pass
     def execute(self, selectcontext, instance, row, identitykey, isnew):
         pass
     def do_init(self):
+        if not self.proxy:
+            return
         class SynonymProp(object):
             def __set__(s, obj, value):
                 setattr(obj, self.name, value)
diff --git a/test/orm/mapper.py b/test/orm/mapper.py
index 9b6717010..6a26c8b4b 100644
--- a/test/orm/mapper.py
+++ b/test/orm/mapper.py
@@ -354,8 +354,8 @@ class MapperTest(MapperSuperTest):
         sess = create_session()
         mapper(User, users, properties = dict(
             addresses = relation(mapper(Address, addresses), lazy = True),
-            uname = synonym('user_name'),
-            adlist = synonym('addresses')
+            uname = synonym('user_name', proxy=True),
+            adlist = synonym('addresses', proxy=True)
         ))
         
         u = sess.query(User).get_by(uname='jack')