From: Mike Bayer Date: Wed, 20 Jan 2016 20:28:35 +0000 (-0500) Subject: - cross link for concrete helper classes X-Git-Tag: rel_1_1_0b1~84^2~25 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a53bd6f74b4f41fd04c8cde1f8b58bbb766fe18d;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - cross link for concrete helper classes - remove redundant concrete helper docs from declarative docs, two places is enough --- diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst index bf0f2a6e1e..20a51efb22 100644 --- a/doc/build/orm/extensions/declarative/inheritance.rst +++ b/doc/build/orm/extensions/declarative/inheritance.rst @@ -8,6 +8,11 @@ as possible. The ``inherits`` mapper keyword argument is not needed as declarative will determine this from the class itself. The various "polymorphic" keyword arguments are specified using ``__mapper_args__``. +.. seealso:: + + :ref:`inheritance_toplevel` - general introduction to inheritance + mapping with Declarative. + Joined Table Inheritance ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -41,10 +46,6 @@ only the ``engineers.id`` column, give it a different attribute name:: primary_language = Column(String(50)) -.. versionchanged:: 0.7 joined table inheritance favors the subclass - column over that of the superclass, such as querying above - for ``Engineer.id``. Prior to 0.7 this was the reverse. - .. _declarative_single_table: Single Table Inheritance @@ -247,72 +248,13 @@ before the class is built:: __table__ = managers __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True} -.. _declarative_concrete_helpers: - -Using the Concrete Helpers -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Helper classes provides a simpler pattern for concrete inheritance. -With these objects, the ``__declare_first__`` helper is used to configure the -"polymorphic" loader for the mapper after all subclasses have been declared. - -An abstract base can be declared using the -:class:`.AbstractConcreteBase` class:: - - from sqlalchemy.ext.declarative import AbstractConcreteBase - - class Employee(AbstractConcreteBase, Base): - pass - -To have a concrete ``employee`` table, use :class:`.ConcreteBase` instead:: - - from sqlalchemy.ext.declarative import ConcreteBase - - class Employee(ConcreteBase, Base): - __tablename__ = 'employee' - employee_id = Column(Integer, primary_key=True) - name = Column(String(50)) - __mapper_args__ = { - 'polymorphic_identity':'employee', - 'concrete':True} - - -Either ``Employee`` base can be used in the normal fashion:: - - class Manager(Employee): - __tablename__ = 'manager' - employee_id = Column(Integer, primary_key=True) - name = Column(String(50)) - manager_data = Column(String(40)) - __mapper_args__ = { - 'polymorphic_identity':'manager', - 'concrete':True} - - class Engineer(Employee): - __tablename__ = 'engineer' - employee_id = Column(Integer, primary_key=True) - name = Column(String(50)) - engineer_info = Column(String(40)) - __mapper_args__ = {'polymorphic_identity':'engineer', - 'concrete':True} - - -The :class:`.AbstractConcreteBase` class is itself mapped, and can be -used as a target of relationships:: - - class Company(Base): - __tablename__ = 'company' - - id = Column(Integer, primary_key=True) - employees = relationship("Employee", - primaryjoin="Company.id == Employee.company_id") - - -.. versionchanged:: 0.9.3 Support for use of :class:`.AbstractConcreteBase` - as the target of a :func:`.relationship` has been improved. +The helper classes :class:`.AbstractConcreteBase` and :class:`.ConcreteBase` +provide automation for the above system of creating a polymorphic union. +See the documentation for these helpers as well as the main ORM documentation +on concrete inheritance for details. -It can also be queried directly:: +.. seealso:: - for employee in session.query(Employee).filter(Employee.name == 'qbert'): - print(employee) + :ref:`concrete_inheritance` + :ref:`inheritance_concrete_helpers` diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index 6434d7a053..f640973c4a 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -670,6 +670,9 @@ Two critical points should be noted: mapped in an inheritance relationship with ``Employee``, they still **do not include polymorphic loading**. +Concrete Polymorphic Loading ++++++++++++++++++++++++++++++ + To load polymorphically, the :paramref:`.orm.mapper.with_polymorphic` argument is required, along with a selectable indicating how rows should be loaded. Polymorphic loading is most inefficient with concrete inheritance, so if we do seek this style of @@ -767,6 +770,11 @@ them to each class using ``__table__``:: __table__ = manager_table __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True} +.. _inheritance_concrete_helpers: + +Using the Declarative Helper Classes ++++++++++++++++++++++++++++++++++++++ + Another way is to use a special helper class that takes on the fairly complicated task of deferring the production of :class:`.Mapper` objects until all table metadata has been collected, and the polymorphic union to which @@ -870,7 +878,6 @@ can produce this; the mapping would be:: :ref:`declarative_concrete_table` - in the Declarative reference documentation - :ref:`declarative_concrete_helpers` - in the Declarative reference documentation Using Relationships with Inheritance ------------------------------------ diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py index dfc47ce959..5fe427bc22 100644 --- a/lib/sqlalchemy/ext/declarative/api.py +++ b/lib/sqlalchemy/ext/declarative/api.py @@ -397,6 +397,15 @@ class ConcreteBase(object): 'polymorphic_identity':'manager', 'concrete':True} + .. seealso:: + + :class:`.AbstractConcreteBase` + + :ref:`concrete_inheritance` + + :ref:`inheritance_concrete_helpers` + + """ @classmethod @@ -495,6 +504,13 @@ class AbstractConcreteBase(ConcreteBase): have been reworked to support relationships established directly on the abstract base, without any special configurational steps. + .. seealso:: + + :class:`.ConcreteBase` + + :ref:`concrete_inheritance` + + :ref:`inheritance_concrete_helpers` """