Merge branch 'master' into ticket_3100

1 files changed, 94 insertions, 23 deletions

diff --git a/lib/sqlalchemy/ext/declarative/__init__.py b/lib/sqlalchemy/ext/declarative/__init__.py
index 3cbc85c0c..2b611252a 100644
--- a/lib/sqlalchemy/ext/declarative/__init__.py
+++ b/lib/sqlalchemy/ext/declarative/__init__.py
@@ -873,8 +873,7 @@ the method without the need to copy it.
 
 Columns generated by :class:`~.declared_attr` 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
+by ``polymorphic_on`` and ``version_id_col``; the declarative extension
 will resolve them at class construction time::
 
     class MyMixin:
@@ -889,7 +888,6 @@ will resolve them at class construction time::
         id =  Column(Integer, primary_key=True)
 
 
-
 Mixing in Relationships
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -922,6 +920,7 @@ reference a common target class via many-to-one::
         __tablename__ = 'target'
         id = Column(Integer, primary_key=True)
 
+
 Using Advanced Relationship Arguments (e.g. ``primaryjoin``, etc.)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1004,6 +1003,24 @@ requirement so that no reliance on copying is needed::
     class Something(SomethingMixin, Base):
         __tablename__ = "something"
 
+The :func:`.column_property` or other construct may refer
+to other columns from the mixin.  These are copied ahead of time before
+the :class:`.declared_attr` is invoked::
+
+    class SomethingMixin(object):
+        x = Column(Integer)
+
+        y = Column(Integer)
+
+        @declared_attr
+        def x_plus_y(cls):
+            return column_property(cls.x + cls.y)
+
+
+.. versionchanged:: 1.0.0 mixin columns are copied to the final mapped class
+   so that :class:`.declared_attr` methods can access the actual column
+   that will be mapped.
+
 Mixing in Association Proxy and Other Attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1087,19 +1104,20 @@ and ``TypeB`` classes.
 Controlling table inheritance with mixins
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``__tablename__`` attribute in conjunction with the hierarchy of
-classes involved in a declarative mixin scenario controls what type of
-table inheritance, if any,
-is configured by the declarative extension.
+The ``__tablename__`` attribute may be used to provide a function that
+will determine the name of the table used for each class in an inheritance
+hierarchy, as well as whether a class has its own distinct table.
 
-If the ``__tablename__`` is computed by a mixin, you may need to
-control which classes get the computed attribute in order to get the
-type of table inheritance you require.
+This is achieved using the :class:`.declared_attr` indicator in conjunction
+with a method named ``__tablename__()``.   Declarative will always
+invoke :class:`.declared_attr` for the special names
+``__tablename__``, ``__mapper_args__`` and ``__table_args__``
+function **for each mapped class in the hierarchy**.   The function therefore
+needs to expect to receive each class individually and to provide the
+correct answer for each.
 
-For example, if you had a mixin that computes ``__tablename__`` but
-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::
+For example, to create a mixin that gives every class a simple table
+name based on class name::
 
     from sqlalchemy.ext.declarative import declared_attr
 
@@ -1118,15 +1136,10 @@ indicate that the class should not have a table mapped::
         __mapper_args__ = {'polymorphic_identity': 'engineer'}
         primary_language = Column(String(50))
 
-Alternatively, you can make the mixin intelligent enough to only
-return a ``__tablename__`` in the event that no table is already
-mapped in the inheritance hierarchy. To help with this, a
-:func:`~sqlalchemy.ext.declarative.has_inherited_table` helper
-function is provided that returns ``True`` if a parent class already
-has a mapped table.
-
-As an example, here's a mixin that will only allow single table
-inheritance::
+Alternatively, we can modify our ``__tablename__`` function to return
+``None`` for subclasses, using :func:`.has_inherited_table`.  This has
+the effect of those subclasses being mapped with single table inheritance
+agaisnt the parent::
 
     from sqlalchemy.ext.declarative import declared_attr
     from sqlalchemy.ext.declarative import has_inherited_table
@@ -1147,6 +1160,64 @@ inheritance::
         primary_language = Column(String(50))
         __mapper_args__ = {'polymorphic_identity': 'engineer'}
 
+.. _mixin_inheritance_columns:
+
+Mixing in Columns in Inheritance Scenarios
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In constrast to how ``__tablename__`` and other special names are handled when
+used with :class:`.declared_attr`, when we mix in columns and properties (e.g.
+relationships, column properties, etc.), the function is
+invoked for the **base class only** in the hierarchy.  Below, only the
+``Person`` class will receive a column
+called ``id``; the mapping will fail on ``Engineer``, which is not given
+a primary key::
+
+    class HasId(object):
+        @declared_attr
+        def id(cls):
+            return Column('id', Integer, primary_key=True)
+
+    class Person(HasId, Base):
+        __tablename__ = 'person'
+        discriminator = Column('type', String(50))
+        __mapper_args__ = {'polymorphic_on': discriminator}
+
+    class Engineer(Person):
+        __tablename__ = 'engineer'
+        primary_language = Column(String(50))
+        __mapper_args__ = {'polymorphic_identity': 'engineer'}
+
+It is usually the case in joined-table inheritance that we want distinctly
+named columns on each subclass.  However in this case, we may want to have
+an ``id`` column on every table, and have them refer to each other via
+foreign key.  We can achieve this as a mixin by using the
+:attr:`.declared_attr.cascading` modifier, which indicates that the
+function should be invoked **for each class in the hierarchy**, just like
+it does for ``__tablename__``::
+
+    class HasId(object):
+        @declared_attr.cascading
+        def id(cls):
+            if has_inherited_table(cls):
+                return Column('id',
+                              Integer,
+                              ForeignKey('person.id'), primary_key=True)
+            else:
+                return Column('id', Integer, primary_key=True)
+
+    class Person(HasId, Base):
+        __tablename__ = 'person'
+        discriminator = Column('type', String(50))
+        __mapper_args__ = {'polymorphic_on': discriminator}
+
+    class Engineer(Person):
+        __tablename__ = 'engineer'
+        primary_language = Column(String(50))
+        __mapper_args__ = {'polymorphic_identity': 'engineer'}
+
+
+.. versionadded:: 1.0.0 added :attr:`.declared_attr.cascading`.
 
 Combining Table/Mapper Arguments from Multiple Mixins
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~