diff options
| -rw-r--r-- | CHANGES | 19 | ||||
| -rw-r--r-- | doc/build/mappers.rst | 2 | ||||
| -rw-r--r-- | doc/build/reference/orm/utilities.rst | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/declarative.py | 263 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/util.py | 2 | ||||
| -rw-r--r-- | test/ext/declarative.py | 521 |
6 files changed, 651 insertions, 158 deletions
@@ -41,6 +41,25 @@ CHANGES - Index now accepts column-oriented InstrumentedAttributes (i.e. column-based mapped class attributes) as column arguments. [ticket:1214] + +- declarative + - Can now specify Column objects on subclasses which have no + table of their own (i.e. use single table inheritance). + The columns will be appended to the base table, but only + mapped by the subclass. + + - For both joined and single inheriting subclasses, the subclass + will only map those columns which are already mapped on the + superclass and those explicit on the subclass. Other + columns that are present on the `Table` will be excluded + from the mapping by default, which can be disabled + by passing a blank `exclude_properties` collection to the + `__mapper_args__`. This is so that single-inheriting + classes which define their own columns are the only classes + to map those columns. The effect is actually a more organized + mapping than you'd normally get with explicit `mapper()` + calls unless you set up the `exclude_properties` arguments + explicitly. - mysql - Added the missing keywords from MySQL 4.1 so they get escaped diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst index f67b056af..07b89da60 100644 --- a/doc/build/mappers.rst +++ b/doc/build/mappers.rst @@ -583,6 +583,8 @@ Single table inheritance is where the attributes of the base class as well as al Note that the mappers for the derived classes Manager and Engineer omit the specification of their associated table, as it is inherited from the employee_mapper. Omitting the table specification for derived mappers in single-table inheritance is required. +.. _concrete_inheritance: + Concrete Table Inheritance ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/build/reference/orm/utilities.rst b/doc/build/reference/orm/utilities.rst index 2ddd1064a..c1dff6f09 100644 --- a/doc/build/reference/orm/utilities.rst +++ b/doc/build/reference/orm/utilities.rst @@ -2,5 +2,5 @@ Utilities ========= .. automodule:: sqlalchemy.orm.util - :members: identity_key, Validator, with_parent + :members: identity_key, Validator, with_parent, polymorphic_union :undoc-members: diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py index 1b5dee975..a5cb6e9d2 100644 --- a/lib/sqlalchemy/ext/declarative.py +++ b/lib/sqlalchemy/ext/declarative.py @@ -3,8 +3,8 @@ Synopsis ======== -SQLAlchemy object-relational configuration involves the usage of Table, -mapper(), and class objects to define the three areas of configuration. +SQLAlchemy object-relational configuration involves the usage of :class:`~sqlalchemy.schema.Table`, +:func:`~sqlalchemy.orm.mapper`, and class objects to define the three areas of configuration. ``declarative`` moves these three types of configuration underneath the individual mapped class. Regular SQLAlchemy schema and ORM constructs are used in most cases:: @@ -18,9 +18,9 @@ cases:: id = Column(Integer, primary_key=True) name = Column(String(50)) -Above, the ``declarative_base`` callable produces a new base class from which +Above, the :func:`declarative_base` callable produces a new base class from which all mapped classes inherit from. When the class definition is completed, a -new ``Table`` and ``mapper()`` have been generated, accessible via the +new :class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.orm.mapper` have been generated, accessible via the ``__table__`` and ``__mapper__`` attributes on the ``SomeClass`` class. Defining Attributes @@ -60,28 +60,28 @@ string-configured :class:`~sqlalchemy.schema.ForeignKey` references can be resol Association of Metadata and Engine ================================== -The ``declarative_base`` base class contains a ``MetaData`` object where newly -defined ``Table`` objects are collected. This is accessed via the -``metadata`` class level accessor, so to create tables we can say:: +The :func:`declarative_base` base class contains a :class:`~sqlalchemy.schema.MetaData` object where newly +defined :class:`~sqlalchemy.schema.Table` objects are collected. This is accessed via the +:class:`~sqlalchemy.schema.MetaData` class level accessor, so to create tables we can say:: engine = create_engine('sqlite://') Base.metadata.create_all(engine) -The ``Engine`` created above may also be directly associated with the +The :class:`~sqlalchemy.engine.base.Engine` created above may also be directly associated with the declarative base class using the ``bind`` keyword argument, where it will be -associated with the underlying ``MetaData`` object and allow SQL operations +associated with the underlying :class:`~sqlalchemy.schema.MetaData` object and allow SQL operations involving that metadata and its tables to make use of that engine automatically:: Base = declarative_base(bind=create_engine('sqlite://')) -Or, as ``MetaData`` allows, at any time using the ``bind`` attribute:: +Or, as :class:`~sqlalchemy.schema.MetaData` allows, at any time using the ``bind`` attribute:: Base.metadata.bind = create_engine('sqlite://') -The ``declarative_base`` can also receive a pre-created ``MetaData`` object, +The :func:`declarative_base` can also receive a pre-created :class:`~sqlalchemy.schema.MetaData` object, which allows a declarative setup to be associated with an already existing -traditional collection of ``Table`` objects:: +traditional collection of :class:`~sqlalchemy.schema.Table` objects:: mymetadata = MetaData() Base = declarative_base(metadata=mymetadata) @@ -90,7 +90,7 @@ Configuring Relations ===================== Relations to other classes are done in the usual way, with the added feature -that the class specified to ``relation()`` may be a string name. The "class +that the class specified to :func:`~sqlalchemy.orm.relation()` may be a string name. The "class registry" associated with ``Base`` is used at mapper compilation time to resolve the name into the actual class object, which is expected to have been defined once the mapper configuration is used:: @@ -120,13 +120,13 @@ where we define a primary join condition on the ``Address`` class using them:: user_id = Column(Integer, ForeignKey('users.id')) user = relation(User, primaryjoin=user_id == User.id) -In addition to the main argument for ``relation``, other arguments +In addition to the main argument for :func:`~sqlalchemy.orm.relation`, other arguments which depend upon the columns present on an as-yet undefined class may also be specified as strings. These strings are evaluated as Python expressions. The full namespace available within this evaluation includes all classes mapped for this declarative base, as well as the contents of the ``sqlalchemy`` package, including -expression functions like ``desc`` and ``func``:: +expression functions like :func:`~sqlalchemy.sql.expression.desc` and :attr:`~sqlalchemy.sql.expression.func`:: class User(Base): # .... @@ -139,11 +139,32 @@ class after the fact:: User.addresses = relation(Address, primaryjoin=Address.user_id == User.id) +Configuring Many-to-Many Relations +================================== + +There's nothing special about many-to-many with declarative. The ``secondary`` +argument to :func:`~sqlalchemy.orm.relation` still requires a :class:`~sqlalchemy.schema.Table` object, not a declarative class. +The :class:`~sqlalchemy.schema.Table` should share the same :class:`~sqlalchemy.schema.MetaData` object used by the declarative base:: + + keywords = Table('keywords', Base.metadata, + Column('author_id', Integer, ForeignKey('authors.id')), + Column('keyword_id', Integer, ForeignKey('keywords.id')) + ) + + class Author(Base): + __tablename__ = 'authors' + id = Column(Integer, primary_key=True) + keywords = relation("Keyword", secondary=keywords) + +You should generally **not** map a class and also specify its table in a many-to-many +relation, since the ORM may issue duplicate INSERT and DELETE statements. + + Defining Synonyms ================= Synonyms are introduced in :ref:`synonyms`. To define a getter/setter which -proxies to an underlying attribute, use ``synonym`` with the +proxies to an underlying attribute, use :func:`~sqlalchemy.orm.synonym` with the ``descriptor`` argument:: class MyClass(Base): @@ -193,8 +214,8 @@ ORM function:: Table Configuration =================== -As an alternative to ``__tablename__``, a direct ``Table`` construct may be -used. The ``Column`` objects, which in this case require their names, will be +As an alternative to ``__tablename__``, a direct :class:`~sqlalchemy.schema.Table` construct may be +used. The :class:`~sqlalchemy.schema.Column` objects, which in this case require their names, will be added to the mapping just like a regular mapping to a table:: class MyClass(Base): @@ -220,14 +241,34 @@ or a dictionary-containing tuple in the form Mapper Configuration ==================== -Mapper arguments are specified using the ``__mapper_args__`` class variable. -Note that the column objects declared on the class are immediately usable, as -in this joined-table inheritance example:: +Mapper arguments are specified using the ``__mapper_args__`` class variable, +which is a dictionary that accepts the same names as the :class:`~sqlalchemy.orm.mapper` +function accepts as keywords:: + + class Widget(Base): + __tablename__ = 'widgets' + id = Column(Integer, primary_key=True) + + __mapper_args__ = {'extension': MyWidgetExtension()} + +Inheritance Configuration +========================= + +Declarative supports all three forms of inheritance as intuitively +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__``. + +Joined Table Inheritance +~~~~~~~~~~~~~~~~~~~~~~~~ + +Joined table inheritance is defined as a subclass that defines its own +table:: class Person(Base): __tablename__ = 'people' id = Column(Integer, primary_key=True) - discriminator = Column(String(50)) + discriminator = Column('type', String(50)) __mapper_args__ = {'polymorphic_on': discriminator} class Engineer(Person): @@ -236,11 +277,105 @@ in this joined-table inheritance example:: id = Column(Integer, ForeignKey('people.id'), primary_key=True) primary_language = Column(String(50)) -For single-table inheritance, the ``__tablename__`` and ``__table__`` class -variables are optional on a class when the class inherits from another mapped -class. +Note that above, the ``Engineer.id`` attribute, since it shares the same +attribute name as the ``Person.id`` attribute, will in fact represent the ``people.id`` +and ``engineers.id`` columns together, and will render inside a query as ``"people.id"``. +To provide the ``Engineer`` class with an attribute that represents only the +``engineers.id`` column, give it a different attribute name:: + + class Engineer(Person): + __tablename__ = 'engineers' + __mapper_args__ = {'polymorphic_identity': 'engineer'} + engineer_id = Column('id', Integer, ForeignKey('people.id'), primary_key=True) + primary_language = Column(String(50)) + +Single Table Inheritance +~~~~~~~~~~~~~~~~~~~~~~~~ + +Single table inheritance is defined as a subclass that does not have its +own table; you just leave out the ``__table__`` and ``__tablename__`` attributes:: + + class Person(Base): + __tablename__ = 'people' + id = Column(Integer, primary_key=True) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on': discriminator} + + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity': 'engineer'} + primary_language = Column(String(50)) + +When the above mappers are configured, the ``Person`` class is mapped to the ``people`` +table *before* the ``primary_language`` column is defined, and this column will not be included +in its own mapping. When ``Engineer`` then defines the ``primary_language`` +column, the column is added to the ``people`` table so that it is included in the mapping +for ``Engineer`` and is also part of the table's full set of columns. +Columns which are not mapped to ``Person`` are also excluded from any other +single or joined inheriting classes using the ``exclude_properties`` mapper argument. +Below, ``Manager`` will have all the attributes of ``Person`` and ``Manager`` but *not* +the ``primary_language`` attribute of ``Engineer``:: -As a convenience feature, the ``declarative_base()`` sets a default + class Manager(Person): + __mapper_args__ = {'polymorphic_identity': 'manager'} + golf_swing = Column(String(50)) + +The attribute exclusion logic is provided by the ``exclude_properties`` mapper argument, +and declarative's default behavior can be disabled by passing an explicit +``exclude_properties`` collection (empty or otherwise) to the ``__mapper_args__``. + +Concrete Table Inheritance +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Concrete is defined as a subclass which has its own table and sets the +``concrete`` keyword argument to ``True``:: + + class Person(Base): + __tablename__ = 'people' + id = Column(Integer, primary_key=True) + name = Column(String(50)) + + class Engineer(Person): + __tablename__ = 'engineers' + __mapper_args__ = {'concrete':True} + id = Column(Integer, primary_key=True) + primary_language = Column(String(50)) + name = Column(String(50)) + +Usage of an abstract base class is a little less straightforward as it requires +usage of :func:`~sqlalchemy.orm.util.polymorphic_union`:: + + engineers = Table('engineers', Base.metadata, + Column('id', Integer, primary_key=True), + Column('name', String(50)), + Column('primary_language', String(50)) + ) + managers = Table('managers', Base.metadata, + Column('id', Integer, primary_key=True), + Column('name', String(50)), + Column('golf_swing', String(50)) + ) + + punion = polymorphic_union({ + 'engineer':engineers, + 'manager':managers + }, 'type', 'punion') + + class Person(Base): + __table__ = punion + __mapper_args__ = {'polymorphic_on':punion.c.type} + + class Engineer(Person): + __table__ = engineers + __mapper_args__ = {'polymorphic_identity':'engineer', 'concrete':True} + + class Manager(Person): + __table__ = managers + __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True} + +Class Usage +=========== + +As a convenience feature, the :func:`declarative_base` sets a default constructor on classes which takes keyword arguments, and assigns them to the named attributes:: @@ -248,7 +383,7 @@ named attributes:: Note that ``declarative`` has no integration built in with sessions, and is only intended as an optional syntax for the regular usage of mappers and Table -objects. A typical application setup using ``scoped_session`` might look +objects. A typical application setup using :func:`~sqlalchemy.orm.scoped_session` might look like:: engine = create_engine('postgres://scott:tiger@localhost/test') @@ -257,9 +392,10 @@ like:: bind=engine)) Base = declarative_base() -Mapped instances then make usage of ``Session`` in the usual way. +Mapped instances then make usage of :class:`~sqlalchemy.orm.session.Session` in the usual way. """ + from sqlalchemy.schema import Table, Column, MetaData from sqlalchemy.orm import synonym as _orm_synonym, mapper, comparable_property, class_mapper from sqlalchemy.orm.interfaces import MapperProperty @@ -301,6 +437,25 @@ def _as_declarative(cls, classname, dict_): # set up attributes in the order they were created our_stuff.sort(key=lambda key: our_stuff[key]._creation_order) + # extract columns from the class dict + cols = [] + for key, c in our_stuff.iteritems(): + if isinstance(c, ColumnProperty): + for col in c.columns: + if isinstance(col, Column) and col.table is None: + _undefer_column_name(key, col) + cols.append(col) + elif isinstance(c, Column): + _undefer_column_name(key, c) + cols.append(c) + # if the column is the same name as the key, + # remove it from the explicit properties dict. + # the normal rules for assigning column-based properties + # will take over, including precedence of columns + # in multi-column ColumnProperties. + if key == c.key: + del our_stuff[key] + table = None if '__table__' not in cls.__dict__: if '__tablename__' in cls.__dict__: @@ -319,23 +474,6 @@ def _as_declarative(cls, classname, dict_): if autoload: table_kw['autoload'] = True - cols = [] - for key, c in our_stuff.iteritems(): - if isinstance(c, ColumnProperty): - for col in c.columns: - if isinstance(col, Column) and col.table is None: - _undefer_column_name(key, col) - cols.append(col) - elif isinstance(c, Column): - _undefer_column_name(key, c) - cols.append(c) - # if the column is the same name as the key, - # remove it from the explicit properties dict. - # the normal rules for assigning column-based properties - # will take over, including precedence of columns - # in multi-column ColumnProperties. - if key == c.key: - del our_stuff[key] cls.__table__ = table = Table(tablename, cls.metadata, *(tuple(cols) + tuple(args)), **table_kw) else: @@ -364,9 +502,36 @@ def _as_declarative(cls, classname, dict_): if not table and 'inherits' not in mapper_args: raise exceptions.InvalidRequestError("Class %r does not have a __table__ or __tablename__ " "specified and does not inherit from an existing table-mapped class." % cls) + + elif 'inherits' in mapper_args and not mapper_args.get('concrete', False): + inherited_mapper = class_mapper(mapper_args['inherits'], compile=False) + inherited_table = inherited_mapper.local_table + + if not table: + # single table inheritance. + # ensure no table args + table_args = cls.__dict__.get('__table_args__') + if table_args is not None: + raise exceptions.ArgumentError("Can't place __table_args__ on an inherited class with no table.") + + # add any columns declared here to the inherited table. + for c in cols: + if c.primary_key: + raise exceptions.ArgumentError("Can't place primary key columns on an inherited class with no table.") + inherited_table.append_column(c) + + # single or joined inheritance + # exclude any cols on the inherited table which are not mapped on the parent class, to avoid + # mapping columns specific to sibling/nephew classes + inherited_mapper = class_mapper(mapper_args['inherits'], compile=False) + inherited_table = inherited_mapper.local_table + + if 'exclude_properties' not in mapper_args: + mapper_args['exclude_properties'] = exclude_properties = \ + set([c.key for c in inherited_table.c if c not in inherited_mapper._columntoproperty]) + exclude_properties.difference_update([c.key for c in cols]) - cls.__mapper__ = mapper_cls(cls, table, properties=our_stuff, - **mapper_args) + cls.__mapper__ = mapper_cls(cls, table, properties=our_stuff, **mapper_args) class DeclarativeMeta(type): def __init__(cls, classname, bases, dict_): @@ -515,11 +680,11 @@ def declarative_base(bind=None, metadata=None, mapper=None, cls=object, into Table and Mapper assignments. :param bind: An optional :class:`~sqlalchemy.engine.base.Connectable`, will be assigned - the ``bind`` attribute on the :class:`~sqlalchemy.schema.MetaData` instance. + the ``bind`` attribute on the :class:`~sqlalchemy.MetaData` instance. The `engine` keyword argument is a deprecated synonym for `bind`. :param metadata: - An optional :class:`~sqlalchemy.schema.MetaData` instance. All :class:`~sqlalchemy.schema.Table` + An optional :class:`~sqlalchemy.MetaData` instance. All :class:`~sqlalchemy.schema.Table` objects implicitly declared by subclasses of the base will share this MetaData. A MetaData instance will be create if none is provided. The MetaData instance will be diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 9abcf90dd..483e1c332 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -78,7 +78,7 @@ class Validator(AttributeExtension): def polymorphic_union(table_map, typecolname, aliasname='p_union'): """Create a ``UNION`` statement used by a polymorphic mapper. - See the `SQLAlchemy` advanced mapping docs for an example of how + See :ref:`concrete_inheritance` for an example of how this is used. """ diff --git a/test/ext/declarative.py b/test/ext/declarative.py index 29daf9c29..3176832f3 100644 --- a/test/ext/declarative.py +++ b/test/ext/declarative.py @@ -4,12 +4,11 @@ from sqlalchemy.ext import declarative as decl from sqlalchemy import exc from testlib import sa, testing from testlib.sa import MetaData, Table, Column, Integer, String, ForeignKey, ForeignKeyConstraint, asc, Index -from testlib.sa.orm import relation, create_session, class_mapper, eagerload, compile_mappers, backref, clear_mappers +from testlib.sa.orm import relation, create_session, class_mapper, eagerload, compile_mappers, backref, clear_mappers, polymorphic_union from testlib.testing import eq_ from orm._base import ComparableEntity, MappedTest - -class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): +class DeclarativeTestBase(testing.TestBase, testing.AssertsExecutionResults): def setUp(self): global Base Base = decl.declarative_base(testing.db) @@ -17,7 +16,8 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): def tearDown(self): clear_mappers() Base.metadata.drop_all() - + +class DeclarativeTest(DeclarativeTestBase): def test_basic(self): class User(Base, ComparableEntity): __tablename__ = 'users' @@ -625,7 +625,115 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): sess.flush() eq_(sess.query(User).filter(User.name == "SOMENAME someuser").one(), u1) - def test_custom_inh(self): + def test_reentrant_compile_via_foreignkey(self): + class User(Base, ComparableEntity): + __tablename__ = 'users' + + id = Column('id', Integer, primary_key=True) + name = Column('name', String(50)) + addresses = relation("Address", backref="user") + + class Address(Base, ComparableEntity): + __tablename__ = 'addresses' + + id = Column('id', Integer, primary_key=True) + email = Column('email', String(50)) + user_id = Column('user_id', Integer, ForeignKey(User.id)) + + # previous versions would force a re-entrant mapper compile + # via the User.id inside the ForeignKey but this is no + # longer the case + sa.orm.compile_mappers() + + Base.metadata.create_all() + u1 = User(name='u1', addresses=[ + Address(email='one'), + Address(email='two'), + ]) + sess = create_session() + sess.add(u1) + sess.flush() + sess.clear() + + eq_(sess.query(User).all(), [User(name='u1', addresses=[ + Address(email='one'), + Address(email='two'), + ])]) + + def test_relation_reference(self): + class Address(Base, ComparableEntity): + __tablename__ = 'addresses' + + id = Column('id', Integer, primary_key=True) + email = Column('email', String(50)) + user_id = Column('user_id', Integer, ForeignKey('users.id')) + + class User(Base, ComparableEntity): + __tablename__ = 'users' + + id = Column('id', Integer, primary_key=True) + name = Column('name', String(50)) + addresses = relation("Address", backref="user", + primaryjoin=id == Address.user_id) + + User.address_count = sa.orm.column_property( + sa.select([sa.func.count(Address.id)]). + where(Address.user_id == User.id).as_scalar()) + + Base.metadata.create_all() + + u1 = User(name='u1', addresses=[ + Address(email='one'), + Address(email='two'), + ]) + sess = create_session() + sess.add(u1) + sess.flush() + sess.clear() + + eq_(sess.query(User).all(), + [User(name='u1', address_count=2, addresses=[ + Address(email='one'), + Address(email='two')])]) + + def test_pk_with_fk_init(self): + class Bar(Base): + __tablename__ = 'bar' + + id = sa.Column(sa.Integer, sa.ForeignKey("foo.id"), primary_key=True) + ex = sa.Column(sa.Integer, primary_key=True) + + class Foo(Base): + __tablename__ = 'foo' + + id = sa.Column(sa.Integer, primary_key=True) + bars = sa.orm.relation(Bar) + + assert Bar.__mapper__.primary_key[0] is Bar.__table__.c.id + assert Bar.__mapper__.primary_key[1] is Bar.__table__.c.ex + + + def test_with_explicit_autoloaded(self): + meta = MetaData(testing.db) + t1 = Table('t1', meta, + Column('id', String(50), primary_key=True), + Column('data', String(50))) + meta.create_all() + try: + class MyObj(Base): + __table__ = Table('t1', Base.metadata, autoload=True) + + sess = create_session() + m = MyObj(id="someid", data="somedata") + sess.add(m) + sess.flush() + + eq_(t1.select().execute().fetchall(), [('someid', 'somedata')]) + finally: + meta.drop_all() + +class DeclarativeInheritanceTest(DeclarativeTestBase): + def test_custom_join_condition(self): class Foo(Base): __tablename__ = 'foo' id = Column('id', Integer, primary_key=True) @@ -639,7 +747,7 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): # compile succeeds because inherit_condition is honored compile_mappers() - def test_joined_inheritance(self): + def test_joined(self): class Company(Base, ComparableEntity): __tablename__ = 'companies' id = Column('id', Integer, primary_key=True) @@ -670,6 +778,7 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): Base.metadata.create_all() sess = create_session() + c1 = Company(name="MegaCorp, Inc.", employees=[ Engineer(name="dilbert", primary_language="java"), Engineer(name="wally", primary_language="c++"), @@ -707,14 +816,13 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): assert sess.query(Person).filter(Manager.name=='dogbert').one().id self.assert_sql_count(testing.db, go, 1) - def test_inheritance_with_undefined_relation(self): + def test_with_undefined_foreignkey(self): class Parent(Base): __tablename__ = 'parent' id = Column('id', Integer, primary_key=True) tp = Column('type', String(50)) __mapper_args__ = dict(polymorphic_on = tp) - class Child1(Parent): __tablename__ = 'child1' id = Column('id', Integer, ForeignKey('parent.id'), primary_key=True) @@ -732,135 +840,185 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): sa.orm.compile_mappers() # no exceptions here - def test_reentrant_compile_via_foreignkey(self): - class User(Base, ComparableEntity): - __tablename__ = 'users' - + def test_single_colsonbase(self): + """test single inheritance where all the columns are on the base class.""" + + class Company(Base, ComparableEntity): + __tablename__ = 'companies' id = Column('id', Integer, primary_key=True) name = Column('name', String(50)) - addresses = relation("Address", backref="user") - - class Address(Base, ComparableEntity): - __tablename__ = 'addresses' + employees = relation("Person") + class Person(Base, ComparableEntity): + __tablename__ = 'people' id = Column('id', Integer, primary_key=True) - email = Column('email', String(50)) - user_id = Column('user_id', Integer, ForeignKey(User.id)) + company_id = Column('company_id', Integer, + ForeignKey('companies.id')) + name = Column('name', String(50)) + discriminator = Column('type', String(50)) + primary_language = Column('primary_language', String(50)) + golf_swing = Column('golf_swing', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} - # this forces a re-entrant compile() due to the User.id within the - # ForeignKey - sa.orm.compile_mappers() + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + + class Manager(Person): + __mapper_args__ = {'polymorphic_identity':'manager'} Base.metadata.create_all() - u1 = User(name='u1', addresses=[ - Address(email='one'), - Address(email='two'), - ]) + sess = create_session() - sess.add(u1) - sess.flush() - sess.clear() + c1 = Company(name="MegaCorp, Inc.", employees=[ + Engineer(name="dilbert", primary_language="java"), + Engineer(name="wally", primary_language="c++"), + Manager(name="dogbert", golf_swing="fore!") + ]) - eq_(sess.query(User).all(), [User(name='u1', addresses=[ - Address(email='one'), - Address(email='two'), - ])]) + c2 = Company(name="Elbonia, Inc.", employees=[ + Engineer(name="vlad", primary_language="cobol") + ]) - def test_relation_reference(self): - class Address(Base, ComparableEntity): - __tablename__ = 'addresses' + sess.add(c1) + sess.add(c2) + sess.flush() + sess.clear() - id = Column('id', Integer, primary_key=True) - email = Column('email', String(50)) - user_id = Column('user_id', Integer, ForeignKey('users.id')) + eq_((sess.query(Person). + filter(Engineer.primary_language == 'cobol').first()), + Engineer(name='vlad')) + eq_((sess.query(Company). + filter(Company.employees.of_type(Engineer). + any(Engineer.primary_language == 'cobol')).first()), + c2) - class User(Base, ComparableEntity): - __tablename__ = 'users' + def test_single_colsonsub(self): + """test single inheritance where the columns are local to their class. + + this is a newer usage. + + """ + class Company(Base, ComparableEntity): + __tablename__ = 'companies' id = Column('id', Integer, primary_key=True) name = Column('name', String(50)) - addresses = relation("Address", backref="user", - primaryjoin=id == Address.user_id) + employees = relation("Person") - User.address_count = sa.orm.column_property( - sa.select([sa.func.count(Address.id)]). - where(Address.user_id == User.id).as_scalar()) + class Person(Base, ComparableEntity): + __tablename__ = 'people' + id = Column(Integer, primary_key=True) + company_id = Column(Integer, + ForeignKey('companies.id')) + name = Column(String(50)) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} + + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + primary_language = Column(String(50)) + class Manager(Person): + __mapper_args__ = {'polymorphic_identity':'manager'} + golf_swing = Column(String(50)) + + # we have here a situation that is somewhat unique. + # the Person class is mapped to the "people" table, but it + # was mapped when the table did not include the "primary_language" + # or "golf_swing" columns. declarative will also manipulate + # the exclude_properties collection so that sibling classes + # don't cross-pollinate. + + assert Person.__table__.c.company_id + assert Person.__table__.c.golf_swing + assert Person.__table__.c.primary_language + assert Engineer.primary_language + assert Manager.golf_swing + assert not hasattr(Person, 'primary_language') + assert not hasattr(Person, 'golf_swing') + assert not hasattr(Engineer, 'golf_swing') + assert not hasattr(Manager, 'primary_language') + Base.metadata.create_all() - u1 = User(name='u1', addresses=[ - Address(email='one'), - Address(email='two'), - ]) sess = create_session() - sess.add(u1) + + e1 = Engineer(name="dilbert", primary_language="java") + e2 = Engineer(name="wally", primary_language="c++") + m1 = Manager(name="dogbert", golf_swing="fore!") + c1 = Company(name="MegaCorp, Inc.", employees=[e1, e2, m1]) + + e3 =Engineer(name="vlad", primary_language="cobol") + c2 = Company(name="Elbonia, Inc.", employees=[e3]) + sess.add(c1) + sess.add(c2) sess.flush() sess.clear() - eq_(sess.query(User).all(), - [User(name='u1', address_count=2, addresses=[ - Address(email='one'), - Address(email='two')])]) - - def test_pk_with_fk_init(self): - class Bar(Base): - __tablename__ = 'bar' - - id = sa.Column(sa.Integer, sa.ForeignKey("foo.id"), primary_key=True) - ex = sa.Column(sa.Integer, primary_key=True) - - class Foo(Base): - __tablename__ = 'foo' + eq_((sess.query(Person). + filter(Engineer.primary_language == 'cobol').first()), + Engineer(name='vlad')) + eq_((sess.query(Company). + filter(Company.employees.of_type(Engineer). + any(Engineer.primary_language == 'cobol')).first()), + c2) + + eq_( + sess.query(Engineer).filter_by(primary_language='cobol').one(), + Engineer(name="vlad", primary_language="cobol") + ) - id = sa.Column(sa.Integer, primary_key=True) - bars = sa.orm.relation(Bar) - - assert Bar.__mapper__.primary_key[0] is Bar.__table__.c.id - assert Bar.__mapper__.primary_key[1] is Bar.__table__.c.ex - - def test_single_inheritance(self): + def test_joined_from_single(self): class Company(Base, ComparableEntity): __tablename__ = 'companies' id = Column('id', Integer, primary_key=True) name = Column('name', String(50)) employees = relation("Person") - + class Person(Base, ComparableEntity): __tablename__ = 'people' - id = Column('id', Integer, primary_key=True) - company_id = Column('company_id', Integer, - ForeignKey('companies.id')) - name = Column('name', String(50)) + id = Column(Integer, primary_key=True) + company_id = Column(Integer, ForeignKey('companies.id')) + name = Column(String(50)) discriminator = Column('type', String(50)) - primary_language = Column('primary_language', String(50)) - golf_swing = Column('golf_swing', String(50)) __mapper_args__ = {'polymorphic_on':discriminator} - class Engineer(Person): - __mapper_args__ = {'polymorphic_identity':'engineer'} - class Manager(Person): __mapper_args__ = {'polymorphic_identity':'manager'} + golf_swing = Column(String(50)) + + class Engineer(Person): + __tablename__ = 'engineers' + __mapper_args__ = {'polymorphic_identity':'engineer'} + id = Column(Integer, ForeignKey('people.id'), primary_key=True) + primary_language = Column(String(50)) + + assert Person.__table__.c.golf_swing + assert not Person.__table__.c.has_key('primary_language') + assert Engineer.__table__.c.primary_language + assert Engineer.primary_language + assert Manager.golf_swing + assert not hasattr(Person, 'primary_language') + assert not hasattr(Person, 'golf_swing') + assert not hasattr(Engineer, 'golf_swing') + assert not hasattr(Manager, 'primary_language') Base.metadata.create_all() sess = create_session() - c1 = Company(name="MegaCorp, Inc.", employees=[ - Engineer(name="dilbert", primary_language="java"), - Engineer(name="wally", primary_language="c++"), - Manager(name="dogbert", golf_swing="fore!") - ]) - - c2 = Company(name="Elbonia, Inc.", employees=[ - Engineer(name="vlad", primary_language="cobol") - ]) + e1 = Engineer(name="dilbert", primary_language="java") + e2 = Engineer(name="wally", primary_language="c++") + m1 = Manager(name="dogbert", golf_swing="fore!") + c1 = Company(name="MegaCorp, Inc.", employees=[e1, e2, m1]) + e3 =Engineer(name="vlad", primary_language="cobol") + c2 = Company(name="Elbonia, Inc.", employees=[e3]) sess.add(c1) sess.add(c2) sess.flush() sess.clear() - eq_((sess.query(Person). + eq_((sess.query(Person).with_polymorphic(Engineer). filter(Engineer.primary_language == 'cobol').first()), Engineer(name='vlad')) eq_((sess.query(Company). @@ -868,25 +1026,174 @@ class DeclarativeTest(testing.TestBase, testing.AssertsExecutionResults): any(Engineer.primary_language == 'cobol')).first()), c2) - def test_with_explicit_autoloaded(self): - meta = MetaData(testing.db) - t1 = Table('t1', meta, - Column('id', String(50), primary_key=True), - Column('data', String(50))) - meta.create_all() - try: - class MyObj(Base): - __table__ = Table('t1', Base.metadata, autoload=True) + eq_( + sess.query(Engineer).filter_by(primary_language='cobol').one(), + Engineer(name="vlad", primary_language="cobol") + ) - sess = create_session() - m = MyObj(id="someid", data="somedata") - sess.add(m) - sess.flush() + def test_single_fksonsub(self): + """test single inheritance with a foreign key-holding column on a subclass. - eq_(t1.select().execute().fetchall(), [('someid', 'somedata')]) - finally: - meta.drop_all() + """ + class Person(Base, ComparableEntity): + __tablename__ = 'people' + id = Column(Integer, primary_key=True) + name = Column(String(50)) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} + + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + primary_language_id = Column(String(50), ForeignKey('languages.id')) + primary_language = relation("Language") + + class Language(Base, ComparableEntity): + __tablename__ = 'languages' + id = Column(Integer, primary_key=True) + name = Column(String(50)) + + assert not hasattr(Person, 'primary_language_id') + + Base.metadata.create_all() + + sess = create_session() + + java, cpp, cobol = Language(name='java'),Language(name='cpp'), Language(name='cobol') + e1 = Engineer(name="dilbert", primary_language=java) + e2 = Engineer(name="wally", primary_language=cpp) + e3 =Engineer(name="vlad", primary_language=cobol) + sess.add_all([e1, e2, e3]) + sess.flush() + sess.clear() + + eq_((sess.query(Person). + filter(Engineer.primary_language.has(Language.name=='cobol')).first()), + Engineer(name='vlad', primary_language=Language(name='cobol'))) + + eq_( + sess.query(Engineer).filter(Engineer.primary_language.has(Language.name=='cobol')).one(), + Engineer(name="vlad", primary_language=Language(name='cobol')) + ) + + eq_( + sess.query(Person).join(Engineer.primary_language).order_by(Language.name).all(), + [ + Engineer(name='vlad', primary_language=Language(name='cobol')), + Engineer(name='wally', primary_language=Language(name='cpp')), + Engineer(name='dilbert', primary_language=Language(name='java')), + ] + ) + + def test_single_three_levels(self): + class Person(Base, ComparableEntity): + __tablename__ = 'people' + id = Column(Integer, primary_key=True) + name = Column(String(50)) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} + + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + primary_language = Column(String(50)) + + class JuniorEngineer(Engineer): + __mapper_args__ = {'polymorphic_identity':'junior_engineer'} + nerf_gun = Column(String(50)) + + class Manager(Person): + __mapper_args__ = {'polymorphic_identity':'manager'} + golf_swing = Column(String(50)) + + assert JuniorEngineer.nerf_gun + assert JuniorEngineer.primary_language + assert JuniorEngineer.name + assert Manager.golf_swing + assert Engineer.primary_language + assert not hasattr(Engineer, 'golf_swing') + assert not hasattr(Engineer, 'nerf_gun') + assert not hasattr(Manager, 'nerf_gun') + assert not hasattr(Manager, 'primary_language') + + def test_single_no_special_cols(self): + class Person(Base, ComparableEntity): + __tablename__ = 'people' + id = Column('id', Integer, primary_key=True) + name = Column('name', String(50)) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} + + def go(): + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + primary_language = Column('primary_language', String(50)) + foo_bar = Column(Integer, primary_key=True) + self.assertRaisesMessage(sa.exc.ArgumentError, "place primary key", go) + + def test_single_no_table_args(self): + class Person(Base, ComparableEntity): + __tablename__ = 'people' + id = Column('id', Integer, primary_key=True) + name = Column('name', String(50)) + discriminator = Column('type', String(50)) + __mapper_args__ = {'polymorphic_on':discriminator} + + def go(): + class Engineer(Person): + __mapper_args__ = {'polymorphic_identity':'engineer'} + primary_language = Column('primary_language', String(50)) + __table_args__ = () + self.assertRaisesMessage(sa.exc.ArgumentError, "place __table_args__", go) + + def test_concrete(self): + engineers = Table('engineers', Base.metadata, + Column('id', Integer, primary_key=True), + Column('name', String(50)), + Column('primary_language', String(50)) + ) + managers = Table('managers', Base.metadata, + Column('id', Integer, primary_key=True), + Column('name', String(50)), + Column('golf_swing', String(50)) + ) + + punion = polymorphic_union({ + 'engineer':engineers, + 'manager':managers + }, 'type', 'punion') + + class Person(Base, ComparableEntity): + __table__ = punion + __mapper_args__ = {'polymorphic_on':punion.c.type} + + class Engineer(Person): + __table__ = engineers + __mapper_args__ = {'polymorphic_identity':'engineer', 'concrete':True} + + class Manager(Person): + __table__ = managers + __mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True} + + Base.metadata.create_all() + sess = create_session() + + e1 = Engineer(name="dilbert", primary_language="java") + e2 = Engineer(name="wally", primary_language="c++") + m1 = Manager(name="dogbert", golf_swing="fore!") + e3 = Engineer(name="vlad", primary_language="cobol") + + sess.add_all([e1, e2, m1, e3]) + sess.flush() + sess.clear() + eq_( + sess.query(Person).order_by(Person.name).all(), + [ + Engineer(name='dilbert'), Manager(name='dogbert'), + Engineer(name='vlad'), Engineer(name='wally') + ] + ) + + def produce_test(inline, stringbased): class ExplicitJoinTest(testing.ORMTest): |