- @classproperty 's official name/location for usage

with declarative is sqlalchemy.ext.declarative.mapperproperty.
Same thing, but moving there since it is more of a
"marker" that's specific to declararative,
not just an attribute technique.  [ticket:1915]

1 files changed, 85 insertions, 36 deletions

diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index 0b471ee1f..be1cb75ec 100755
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -589,13 +589,13 @@ keys, as a :class:`ForeignKey` itself contains references to columns
 which can't be properly recreated at this level.  For columns that 
 have foreign keys, as well as for the variety of mapper-level constructs
 that require destination-explicit context, the
-:func:`~sqlalchemy.util.classproperty` decorator is provided so that
+:func:`~.mapperproperty` decorator is provided so that
 patterns common to many classes can be defined as callables::
 
-    from sqlalchemy.util import classproperty
+    from sqlalchemy.ext.declarative import mapperproperty
     
     class ReferenceAddressMixin(object):
-        @classproperty
+        @mapperproperty
         def address_id(cls):
             return Column(Integer, ForeignKey('address.id'))
             
@@ -608,14 +608,14 @@ point at which the ``User`` class is constructed, and the declarative
 extension can use the resulting :class:`Column` object as returned by
 the method without the need to copy it.
 
-Columns generated by :func:`~sqlalchemy.util.classproperty` can also be
+Columns generated by :func:`~.mapperproperty` can also be
 referenced by ``__mapper_args__`` to a limited degree, currently 
 by ``polymorphic_on`` and ``version_id_col``, by specifying the 
 classdecorator itself into the dictionary - the declarative extension
 will resolve them at class construction time::
 
     class MyMixin:
-        @classproperty
+        @mapperproperty
         def type_(cls):
             return Column(String(50))
 
@@ -625,26 +625,23 @@ will resolve them at class construction time::
         __tablename__='test'
         id =  Column(Integer, primary_key=True)
     
-.. note:: The usage of :func:`~sqlalchemy.util.classproperty` with mixin 
-   columns is a new feature as of SQLAlchemy 0.6.2.
-
 Mixing in Relationships
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Relationships created by :func:`~sqlalchemy.orm.relationship` are provided
 with declarative mixin classes exclusively using the
-:func:`~sqlalchemy.util.classproperty` approach, eliminating any ambiguity
+:func:`.mapperproperty` approach, eliminating any ambiguity
 which could arise when copying a relationship and its possibly column-bound
 contents. Below is an example which combines a foreign key column and a
 relationship so that two classes ``Foo`` and ``Bar`` can both be configured to
 reference a common target class via many-to-one::
 
     class RefTargetMixin(object):
-        @classproperty
+        @mapperproperty
         def target_id(cls):
             return Column('target_id', ForeignKey('target.id'))
     
-        @classproperty
+        @mapperproperty
         def target(cls):
             return relationship("Target")
     
@@ -667,20 +664,16 @@ To reference the mixin class in these expressions, use the given ``cls``
 to get it's name::
 
     class RefTargetMixin(object):
-        @classproperty
+        @mapperproperty
         def target_id(cls):
             return Column('target_id', ForeignKey('target.id'))
         
-        @classproperty
+        @mapperproperty
         def target(cls):
             return relationship("Target",
                 primaryjoin="Target.id==%s.target_id" % cls.__name__
             )
 
-.. note:: The usage of :func:`~sqlalchemy.util.classproperty` with mixin 
-   relationships is a new feature as of SQLAlchemy 0.6.2.
-
-
 Mixing in deferred(), column_property(), etc.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -688,21 +681,18 @@ Like :func:`~sqlalchemy.orm.relationship`, all
 :class:`~sqlalchemy.orm.interfaces.MapperProperty` subclasses such as
 :func:`~sqlalchemy.orm.deferred`, :func:`~sqlalchemy.orm.column_property`,
 etc. ultimately involve references to columns, and therefore, when 
-used with declarative mixins, have the :func:`~sqlalchemy.util.classproperty` 
+used with declarative mixins, have the :func:`.mapperproperty` 
 requirement so that no reliance on copying is needed::
 
     class SomethingMixin(object):
 
-        @classproperty
+        @mapperproperty
         def dprop(cls):
             return deferred(Column(Integer))
 
     class Something(Base, SomethingMixin):
         __tablename__ = "something"
 
-.. note:: The usage of :func:`~sqlalchemy.util.classproperty` with mixin 
-   mapper properties is a new feature as of SQLAlchemy 0.6.2.
-
 
 Controlling table inheritance with mixins
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -721,10 +711,10 @@ where you wanted to use that mixin in a single table inheritance
 hierarchy, you can explicitly specify ``__tablename__`` as ``None`` to
 indicate that the class should not have a table mapped::
 
-    from sqlalchemy.util import classproperty
+    from sqlalchemy.ext.declarative import mapperproperty
 
     class Tablename:
-        @classproperty
+        @mapperproperty
         def __tablename__(cls):
             return cls.__name__.lower()
 
@@ -748,11 +738,11 @@ has a mapped table.
 As an example, here's a mixin that will only allow single table
 inheritance::
 
-    from sqlalchemy.util import classproperty
+    from sqlalchemy.ext.declarative import mapperproperty
     from sqlalchemy.ext.declarative import has_inherited_table
 
     class Tablename:
-        @classproperty
+        @mapperproperty
         def __tablename__(cls):
             if has_inherited_table(cls):
                 return None
@@ -772,11 +762,11 @@ table inheritance, you would need a slightly different mixin and use
 it on any joined table child classes in addition to their parent
 classes::
 
-    from sqlalchemy.util import classproperty
+    from sqlalchemy.ext.declarative import mapperproperty
     from sqlalchemy.ext.declarative import has_inherited_table
 
     class Tablename:
-        @classproperty
+        @mapperproperty
         def __tablename__(cls):
             if (has_inherited_table(cls) and
                 Tablename not in cls.__bases__):
@@ -806,11 +796,11 @@ In the case of ``__table_args__`` or ``__mapper_args__``
 specified with declarative mixins, you may want to combine
 some parameters from several mixins with those you wish to
 define on the class iteself. The
-:func:`~sqlalchemy.util.classproperty` decorator can be used
+:func:`.mapperproperty` decorator can be used
 here to create user-defined collation routines that pull
 from multiple collections::
 
-    from sqlalchemy.util import classproperty
+    from sqlalchemy.ext.declarative import mapperproperty
 
     class MySQLSettings:
         __table_args__ = {'mysql_engine':'InnoDB'}             
@@ -821,7 +811,7 @@ from multiple collections::
     class MyModel(Base,MySQLSettings,MyOtherMixin):
         __tablename__='my_model'
 
-        @classproperty
+        @mapperproperty
         def __table_args__(self):
             args = dict()
             args.update(MySQLSettings.__table_args__)
@@ -907,6 +897,8 @@ def _as_declarative(cls, classname, dict_):
     tablename = None
     parent_columns = ()
     
+    declarative_props = (mapperproperty, util.classproperty)
+    
     for base in cls.__mro__:
         class_mapped = _is_mapped_class(base)
         if class_mapped:
@@ -916,19 +908,19 @@ def _as_declarative(cls, classname, dict_):
             if name == '__mapper_args__':
                 if not mapper_args and (
                                         not class_mapped or 
-                                        isinstance(obj, util.classproperty)
+                                        isinstance(obj, declarative_props)
                                     ):
                     mapper_args = cls.__mapper_args__
             elif name == '__tablename__':
                 if not tablename and (
                                         not class_mapped or 
-                                        isinstance(obj, util.classproperty)
+                                        isinstance(obj, declarative_props)
                                     ):
                     tablename = cls.__tablename__
             elif name == '__table_args__':
                 if not table_args and (
                                         not class_mapped or 
-                                        isinstance(obj, util.classproperty)
+                                        isinstance(obj, declarative_props)
                                     ):
                     table_args = cls.__table_args__
                     if base is not cls:
@@ -959,7 +951,7 @@ def _as_declarative(cls, classname, dict_):
                         "column_property(), relationship(), etc.) must "
                         "be declared as @classproperty callables "
                         "on declarative mixin classes.")
-                elif isinstance(obj, util.classproperty):
+                elif isinstance(obj, declarative_props):
                     dict_[name] = ret = \
                             column_copies[obj] = getattr(cls, name)
                     if isinstance(ret, (Column, MapperProperty)) and \
@@ -984,7 +976,7 @@ def _as_declarative(cls, classname, dict_):
 
     for k in dict_:
         value = dict_[k]
-        if isinstance(value, util.classproperty):
+        if isinstance(value, declarative_props):
             value = getattr(cls, k)
             
         if (isinstance(value, tuple) and len(value) == 1 and
@@ -1273,6 +1265,63 @@ def comparable_using(comparator_factory):
         return comparable_property(comparator_factory, fn)
     return decorate
 
+class mapperproperty(property):
+    """Mark a class-level method as representing the definition of
+    a mapped property or special declarative member name.
+
+    .. note:: @mapperproperty is available as 
+      sqlalchemy.util.classproperty for SQLAlchemy versions
+      0.6.2, 0.6.3, 0.6.4.
+      
+    @mapperproperty turns the attribute into a scalar-like
+    property that can be invoked from the uninstantiated class.
+    Declarative treats attributes specifically marked with 
+    @mapperproperty as returning a construct that is specific
+    to mapping or declarative table configuration.  The name
+    of the attribute is that of what the non-dynamic version
+    of the attribute would be.
+    
+    @mapperproperty is more often than not applicable to mixins,
+    to define relationships that are to be applied to different
+    implementors of the class::
+    
+        class ProvidesUser(object):
+            "A mixin that adds a 'user' relationship to classes."
+            
+            @mapperproperty
+            def user(self):
+                return relationship("User")
+    
+    It also can be applied to mapped classes, such as to provide
+    a "polymorphic" scheme for inheritance::
+        
+        class Employee(Base):
+            id = Column(Integer, primary_key=True)
+            type = Column(String(50), nullable=False)
+            
+            @mapperproperty
+            def __tablename__(cls):
+                return cls.__name__.lower()
+            
+            @mapperproperty
+            def __mapper_args__(cls):
+                if cls.__name__ == 'Employee':
+                    return {
+                            "polymorphic_on":cls.type, 
+                            "polymorphic_identity":"Employee"
+                    }
+                else:
+                    return {"polymorphic_identity":cls.__name__}
+    
+    """
+    
+    def __init__(self, fget, *arg, **kw):
+        super(mapperproperty, self).__init__(fget, *arg, **kw)
+        self.__doc__ = fget.__doc__
+        
+    def __get__(desc, self, cls):
+        return desc.fget(cls)
+
 def _declarative_constructor(self, **kwargs):
     """A simple constructor that allows initialization from kwargs.