diff options
Diffstat (limited to 'lib/sqlalchemy/orm')
| -rw-r--r-- | lib/sqlalchemy/orm/__init__.py | 462 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/events.py | 346 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/interfaces.py | 21 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/mapper.py | 60 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/properties.py | 8 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 469 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/state.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/util.py | 500 |
8 files changed, 967 insertions, 905 deletions
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 02cdd6a77..1a22fe3d1 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -52,9 +52,9 @@ from .relationships import ( remote_foreign ) from .session import ( - Session, - object_session, - sessionmaker, + Session, + object_session, + sessionmaker, make_transient ) from .scoping import ( @@ -68,7 +68,7 @@ from .. import util as sa_util from . import interfaces -# here, we can establish InstrumentationManager back +# here, we can establish InstrumentationManager back # in sqlalchemy.orm and sqlalchemy.orm.interfaces, which # also re-establishes the extended instrumentation system. #from ..ext import instrumentation as _ext_instrumentation @@ -166,7 +166,7 @@ def scoped_session(session_factory, scopefunc=None): return ScopedSession(session_factory, scopefunc=scopefunc) def create_session(bind=None, **kwargs): - """Create a new :class:`.Session` + """Create a new :class:`.Session` with no automation enabled by default. This function is used primarily for testing. The usual @@ -216,57 +216,57 @@ def relationship(argument, secondary=None, **kwargs): 'children': relationship(Child) }) - Some arguments accepted by :func:`.relationship` optionally accept a + Some arguments accepted by :func:`.relationship` optionally accept a callable function, which when called produces the desired value. The callable is invoked by the parent :class:`.Mapper` at "mapper initialization" time, which happens only when mappers are first used, and is assumed to be after all mappings have been constructed. This can be used - to resolve order-of-declaration and other dependency issues, such as + to resolve order-of-declaration and other dependency issues, such as if ``Child`` is declared below ``Parent`` in the same file:: - + mapper(Parent, properties={ - "children":relationship(lambda: Child, + "children":relationship(lambda: Child, order_by=lambda: Child.id) }) - + When using the :ref:`declarative_toplevel` extension, the Declarative initializer allows string arguments to be passed to :func:`.relationship`. - These string arguments are converted into callables that evaluate + These string arguments are converted into callables that evaluate the string as Python code, using the Declarative class-registry as a namespace. This allows the lookup of related classes to be automatic via their string name, and removes the need to import related classes at all into the local module space:: - + from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() - + class Parent(Base): __tablename__ = 'parent' id = Column(Integer, primary_key=True) children = relationship("Child", order_by="Child.id") - + A full array of examples and reference documentation regarding :func:`.relationship` is at :ref:`relationship_config_toplevel`. - + :param argument: a mapped class, or actual :class:`.Mapper` instance, representing the target of - the relationship. - + the relationship. + ``argument`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. :param secondary: for a many-to-many relationship, specifies the intermediary - table, and is an instance of :class:`.Table`. The ``secondary`` keyword + table, and is an instance of :class:`.Table`. The ``secondary`` keyword argument should generally only be used for a table that is not otherwise expressed in any class mapping, unless this relationship is declared as view only, otherwise - conflicting persistence operations can occur. - + conflicting persistence operations can occur. + ``secondary`` may - also be passed as a callable function which is evaluated at + also be passed as a callable function which is evaluated at mapper initialization time. :param active_history=False: @@ -282,16 +282,16 @@ def relationship(argument, secondary=None, **kwargs): :param backref: indicates the string name of a property to be placed on the related mapper's class that will handle this relationship in the other - direction. The other property will be created automatically + direction. The other property will be created automatically when the mappers are configured. Can also be passed as a :func:`backref` object to control the configuration of the new relationship. :param back_populates: - Takes a string name and has the same meaning as ``backref``, - except the complementing property is **not** created automatically, - and instead must be configured explicitly on the other mapper. The - complementing property should also indicate ``back_populates`` + Takes a string name and has the same meaning as ``backref``, + except the complementing property is **not** created automatically, + and instead must be configured explicitly on the other mapper. The + complementing property should also indicate ``back_populates`` to this relationship to ensure proper functioning. :param cascade: @@ -302,12 +302,12 @@ def relationship(argument, secondary=None, **kwargs): Available cascades are: - * ``save-update`` - cascade the :meth:`.Session.add` + * ``save-update`` - cascade the :meth:`.Session.add` operation. This cascade applies both to future and - past calls to :meth:`~sqlalchemy.orm.session.Session.add`, + past calls to :meth:`~sqlalchemy.orm.session.Session.add`, meaning new items added to a collection or scalar relationship - get placed into the same session as that of the parent, and - also applies to items which have been removed from this + get placed into the same session as that of the parent, and + also applies to items which have been removed from this relationship but are still part of unflushed history. * ``merge`` - cascade the :meth:`~sqlalchemy.orm.session.Session.merge` @@ -319,8 +319,8 @@ def relationship(argument, secondary=None, **kwargs): * ``delete`` - cascade the :meth:`.Session.delete` operation - * ``delete-orphan`` - if an item of the child's type is - detached from its parent, mark it for deletion. + * ``delete-orphan`` - if an item of the child's type is + detached from its parent, mark it for deletion. .. versionchanged:: 0.7 This option does not prevent @@ -329,7 +329,7 @@ def relationship(argument, secondary=None, **kwargs): that case, ensure the child's foreign key column(s) is configured as NOT NULL - * ``refresh-expire`` - cascade the :meth:`.Session.expire` + * ``refresh-expire`` - cascade the :meth:`.Session.expire` and :meth:`~sqlalchemy.orm.session.Session.refresh` operations * ``all`` - shorthand for "save-update,merge, refresh-expire, @@ -337,33 +337,33 @@ def relationship(argument, secondary=None, **kwargs): See the section :ref:`unitofwork_cascades` for more background on configuring cascades. - + :param cascade_backrefs=True: a boolean value indicating if the ``save-update`` cascade should - operate along an assignment event intercepted by a backref. + operate along an assignment event intercepted by a backref. When set to ``False``, the attribute managed by this relationship will not cascade an incoming transient object into the session of a persistent parent, if the event is received via backref. - + That is:: - + mapper(A, a_table, properties={ 'bs':relationship(B, backref="a", cascade_backrefs=False) }) - + If an ``A()`` is present in the session, assigning it to the "a" attribute on a transient ``B()`` will not place - the ``B()`` into the session. To set the flag in the other - direction, i.e. so that ``A().bs.append(B())`` won't add + the ``B()`` into the session. To set the flag in the other + direction, i.e. so that ``A().bs.append(B())`` won't add a transient ``A()`` into the session for a persistent ``B()``:: - + mapper(A, a_table, properties={ - 'bs':relationship(B, + 'bs':relationship(B, backref=backref("a", cascade_backrefs=False) ) }) - + See the section :ref:`unitofwork_cascades` for more background on configuring cascades. @@ -390,9 +390,9 @@ def relationship(argument, secondary=None, **kwargs): a list of columns which are to be used as "foreign key" columns. Normally, :func:`relationship` uses the :class:`.ForeignKey` and :class:`.ForeignKeyConstraint` objects present within the - mapped or secondary :class:`.Table` to determine the "foreign" side of + mapped or secondary :class:`.Table` to determine the "foreign" side of the join condition. This is used to construct SQL clauses in order - to load objects, as well as to "synchronize" values from + to load objects, as well as to "synchronize" values from primary key columns to referencing foreign key columns. The ``foreign_keys`` parameter overrides the notion of what's "foreign" in the table metadata, allowing the specification @@ -408,7 +408,7 @@ def relationship(argument, secondary=None, **kwargs): should artificially not be considered as foreign. ``foreign_keys`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. versionchanged:: 0.8 @@ -431,16 +431,16 @@ def relationship(argument, secondary=None, **kwargs): :param join_depth: when non-``None``, an integer value indicating how many levels - deep "eager" loaders should join on a self-referring or cyclical - relationship. The number counts how many times the same Mapper - shall be present in the loading condition along a particular join + deep "eager" loaders should join on a self-referring or cyclical + relationship. The number counts how many times the same Mapper + shall be present in the loading condition along a particular join branch. When left at its default of ``None``, eager loaders - will stop chaining when they encounter a the same target mapper + will stop chaining when they encounter a the same target mapper which is already higher up in the chain. This option applies both to joined- and subquery- eager loaders. - :param lazy='select': specifies - how the related items should be loaded. Default value is + :param lazy='select': specifies + how the related items should be loaded. Default value is ``select``. Values include: * ``select`` - items should be loaded lazily when the property is first @@ -463,12 +463,12 @@ def relationship(argument, secondary=None, **kwargs): which issues a JOIN to a subquery of the original statement. - * ``noload`` - no loading should occur at any time. This is to + * ``noload`` - no loading should occur at any time. This is to support "write-only" attributes, or attributes which are populated in some manner specific to the application. * ``dynamic`` - the attribute will return a pre-configured - :class:`~sqlalchemy.orm.query.Query` object for all read + :class:`~sqlalchemy.orm.query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. See the section :ref:`dynamic_relationship` for more details. @@ -483,9 +483,9 @@ def relationship(argument, secondary=None, **kwargs): :param load_on_pending=False: Indicates loading behavior for transient or pending parent objects. - + .. note:: - + load_on_pending is superseded by :meth:`.Session.enable_relationship_loading`. When set to ``True``, causes the lazy-loader to @@ -493,7 +493,7 @@ def relationship(argument, secondary=None, **kwargs): never been flushed. This may take effect for a pending object when autoflush is disabled, or for a transient object that has been "attached" to a :class:`.Session` but is not part of its pending - collection. + collection. The load_on_pending flag does not improve behavior when the ORM is used normally - object references should be constructed @@ -506,14 +506,14 @@ def relationship(argument, secondary=None, **kwargs): :param order_by: indicates the ordering that should be applied when loading these items. ``order_by`` is expected to refer to one of the :class:`.Column` - objects to which the target class is mapped, or + objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column. ``order_by`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. - + :param passive_deletes=False: Indicates loading behavior during delete operations. @@ -593,7 +593,7 @@ def relationship(argument, secondary=None, **kwargs): table). ``primaryjoin`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. :param remote_side: @@ -601,7 +601,7 @@ def relationship(argument, secondary=None, **kwargs): list of columns that form the "remote side" of the relationship. ``remote_side`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. .. versionchanged:: 0.8 @@ -613,10 +613,10 @@ def relationship(argument, secondary=None, **kwargs): :param query_class: a :class:`.Query` subclass that will be used as the base of the "appender query" returned by a "dynamic" relationship, that - is, a relationship that specifies ``lazy="dynamic"`` or was + is, a relationship that specifies ``lazy="dynamic"`` or was otherwise constructed using the :func:`.orm.dynamic_loader` function. - + :param secondaryjoin: a SQL expression that will be used as the join of an association table to the child object. By default, this value is @@ -624,7 +624,7 @@ def relationship(argument, secondary=None, **kwargs): child tables. ``secondaryjoin`` may also be passed as a callable function - which is evaluated at mapper initialization time, and may be passed as a + which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. :param single_parent=(True|False): @@ -632,7 +632,7 @@ def relationship(argument, secondary=None, **kwargs): from being associated with more than one parent at a time. This is used for many-to-one or many-to-many relationships that should be treated either as one-to-one or one-to-many. Its - usage is optional unless delete-orphan cascade is also + usage is optional unless delete-orphan cascade is also set on this relationship(), in which case its required. :param uselist=(True|False): @@ -665,13 +665,13 @@ def relation(*arg, **kw): def dynamic_loader(argument, **kw): """Construct a dynamically-loading mapper property. - This is essentially the same as + This is essentially the same as using the ``lazy='dynamic'`` argument with :func:`relationship`:: dynamic_loader(SomeClass) - + # is the same as - + relationship(SomeClass, lazy="dynamic") See the section :ref:`dynamic_relationship` for more details @@ -725,19 +725,19 @@ def column_property(*cols, **kw): :param doc: optional string that will be applied as the doc on the class-bound descriptor. - + :param expire_on_flush=True: Disable expiry on flush. A column_property() which refers to a SQL expression (and not a single table-bound column) is considered to be a "read only" property; populating it has no effect on the state of data, and it can only return database state. For this reason a column_property()'s value - is expired whenever the parent object is involved in a + is expired whenever the parent object is involved in a flush, that is, has any kind of "dirty" state within a flush. Setting this parameter to ``False`` will have the effect of leaving any existing value present after the flush proceeds. Note however that the :class:`.Session` with default expiration - settings still expires + settings still expires all attributes after a :meth:`.Session.commit` call, however. .. versionadded:: 0.7.3 @@ -747,7 +747,7 @@ def column_property(*cols, **kw): :class:`.AttributeExtension` instance, or list of extensions, which will be prepended to the list of attribute listeners for the resulting - descriptor placed on the class. + descriptor placed on the class. **Deprecated.** Please see :class:`.AttributeEvents`. """ @@ -807,7 +807,7 @@ def backref(name, **kwargs): Used with the ``backref`` keyword argument to :func:`relationship` in place of a string argument, e.g.:: - + 'items':relationship(SomeItem, backref=backref('parent', lazy='subquery')) """ @@ -821,7 +821,7 @@ def deferred(*columns, **kwargs): Used with the "properties" dictionary sent to :func:`mapper`. See also: - + :ref:`deferred` """ @@ -829,47 +829,47 @@ def deferred(*columns, **kwargs): def mapper(class_, local_table=None, *args, **params): """Return a new :class:`~.Mapper` object. - + This function is typically used behind the scenes via the Declarative extension. When using Declarative, many of the usual :func:`.mapper` arguments are handled by the Declarative extension itself, including ``class_``, ``local_table``, ``properties``, and ``inherits``. - Other options are passed to :func:`.mapper` using + Other options are passed to :func:`.mapper` using the ``__mapper_args__`` class variable:: - + class MyClass(Base): __tablename__ = 'my_table' id = Column(Integer, primary_key=True) type = Column(String(50)) alt = Column("some_alt", Integer) - + __mapper_args__ = { 'polymorphic_on' : type } Explicit use of :func:`.mapper` - is often referred to as *classical mapping*. The above + is often referred to as *classical mapping*. The above declarative example is equivalent in classical form to:: - + my_table = Table("my_table", metadata, Column('id', Integer, primary_key=True), Column('type', String(50)), Column("some_alt", Integer) ) - + class MyClass(object): pass - - mapper(MyClass, my_table, - polymorphic_on=my_table.c.type, + + mapper(MyClass, my_table, + polymorphic_on=my_table.c.type, properties={ 'alt':my_table.c.some_alt }) - + See also: - + :ref:`classical_mapping` - discussion of direct usage of :func:`.mapper` @@ -877,10 +877,10 @@ def mapper(class_, local_table=None, *args, **params): this argument is automatically passed as the declared class itself. - :param local_table: The :class:`.Table` or other selectable - to which the class is mapped. May be ``None`` if + :param local_table: The :class:`.Table` or other selectable + to which the class is mapped. May be ``None`` if this mapper inherits from another mapper using single-table - inheritance. When using Declarative, this argument is + inheritance. When using Declarative, this argument is automatically passed by the extension, based on what is configured via the ``__table__`` argument or via the :class:`.Table` produced as a result of the ``__tablename__`` and :class:`.Column` @@ -901,30 +901,30 @@ def mapper(class_, local_table=None, *args, **params): particular primary key value. A "partial primary key" can occur if one has mapped to an OUTER JOIN, for example. - :param batch: Defaults to ``True``, indicating that save operations - of multiple entities can be batched together for efficiency. + :param batch: Defaults to ``True``, indicating that save operations + of multiple entities can be batched together for efficiency. Setting to False indicates that an instance will be fully saved before saving the next - instance. This is used in the extremely rare case that a - :class:`.MapperEvents` listener requires being called + instance. This is used in the extremely rare case that a + :class:`.MapperEvents` listener requires being called in between individual row persistence operations. - :param column_prefix: A string which will be prepended + :param column_prefix: A string which will be prepended to the mapped attribute name when :class:`.Column` objects are automatically assigned as attributes to the - mapped class. Does not affect explicitly specified - column-based properties. - + mapped class. Does not affect explicitly specified + column-based properties. + See the section :ref:`column_prefix` for an example. :param concrete: If True, indicates this mapper should use concrete table inheritance with its parent mapper. - + See the section :ref:`concrete_inheritance` for an example. - :param exclude_properties: A list or set of string column names to - be excluded from mapping. - + :param exclude_properties: A list or set of string column names to + be excluded from mapping. + See :ref:`include_exclude_cols` for an example. :param extension: A :class:`.MapperExtension` instance or @@ -933,47 +933,47 @@ def mapper(class_, local_table=None, *args, **params): :class:`.Mapper`. **Deprecated.** Please see :class:`.MapperEvents`. :param include_properties: An inclusive list or set of string column - names to map. - + names to map. + See :ref:`include_exclude_cols` for an example. - :param inherits: A mapped class or the corresponding :class:`.Mapper` + :param inherits: A mapped class or the corresponding :class:`.Mapper` of one indicating a superclass to which this :class:`.Mapper` should *inherit* from. The mapped class here must be a subclass of the other mapper's class. When using Declarative, this argument is passed automatically as a result of the natural class - hierarchy of the declared classes. - + hierarchy of the declared classes. + See also: - + :ref:`inheritance_toplevel` - + :param inherit_condition: For joined table inheritance, a SQL expression which will define how the two tables are joined; defaults to a natural join between the two tables. :param inherit_foreign_keys: When ``inherit_condition`` is used and the - columns present are missing a :class:`.ForeignKey` configuration, - this parameter can be used to specify which columns are "foreign". + columns present are missing a :class:`.ForeignKey` configuration, + this parameter can be used to specify which columns are "foreign". In most cases can be left as ``None``. :param non_primary: Specify that this :class:`.Mapper` is in addition to the "primary" mapper, that is, the one used for persistence. The :class:`.Mapper` created here may be used for ad-hoc mapping of the class to an alternate selectable, for loading - only. - + only. + The ``non_primary`` feature is rarely needed with modern usage. :param order_by: A single :class:`.Column` or list of :class:`.Column` objects for which selection operations should use as the default - ordering for entities. By default mappers have no pre-defined + ordering for entities. By default mappers have no pre-defined ordering. :param passive_updates: Indicates UPDATE behavior of foreign key - columns when a primary key column changes on a joined-table inheritance + columns when a primary key column changes on a joined-table inheritance mapping. Defaults to ``True``. When True, it is assumed that ON UPDATE CASCADE is configured on @@ -986,41 +986,41 @@ def mapper(class_, local_table=None, *args, **params): operation for an update. The :class:`.Mapper` here will emit an UPDATE statement for the dependent columns during a primary key change. - + See also: - - :ref:`passive_updates` - description of a similar feature as + + :ref:`passive_updates` - description of a similar feature as used with :func:`.relationship` - :param polymorphic_on: Specifies the column, attribute, or - SQL expression used to determine the target class for an + :param polymorphic_on: Specifies the column, attribute, or + SQL expression used to determine the target class for an incoming row, when inheriting classes are present. - + This value is commonly a :class:`.Column` object that's present in the mapped :class:`.Table`:: - + class Employee(Base): __tablename__ = 'employee' - + id = Column(Integer, primary_key=True) discriminator = Column(String(50)) - + __mapper_args__ = { "polymorphic_on":discriminator, "polymorphic_identity":"employee" } - + It may also be specified - as a SQL expression, as in this example where we + as a SQL expression, as in this example where we use the :func:`.case` construct to provide a conditional approach:: class Employee(Base): __tablename__ = 'employee' - + id = Column(Integer, primary_key=True) discriminator = Column(String(50)) - + __mapper_args__ = { "polymorphic_on":case([ (discriminator == "EN", "engineer"), @@ -1028,14 +1028,14 @@ def mapper(class_, local_table=None, *args, **params): ], else_="employee"), "polymorphic_identity":"employee" } - - It may also refer to any attribute + + It may also refer to any attribute configured with :func:`.column_property`, or to the string name of one:: - + class Employee(Base): __tablename__ = 'employee' - + id = Column(Integer, primary_key=True) discriminator = Column(String(50)) employee_type = column_property( @@ -1044,7 +1044,7 @@ def mapper(class_, local_table=None, *args, **params): (discriminator == "MA", "manager"), ], else_="employee") ) - + __mapper_args__ = { "polymorphic_on":employee_type, "polymorphic_identity":"employee" @@ -1057,8 +1057,8 @@ def mapper(class_, local_table=None, *args, **params): When setting ``polymorphic_on`` to reference an attribute or expression that's not present in the - locally mapped :class:`.Table`, yet the value - of the discriminator should be persisted to the database, + locally mapped :class:`.Table`, yet the value + of the discriminator should be persisted to the database, the value of the discriminator is not automatically set on new instances; this must be handled by the user, @@ -1068,27 +1068,27 @@ def mapper(class_, local_table=None, *args, **params): from sqlalchemy import event from sqlalchemy.orm import object_mapper - + @event.listens_for(Employee, "init", propagate=True) def set_identity(instance, *arg, **kw): mapper = object_mapper(instance) instance.discriminator = mapper.polymorphic_identity - + Where above, we assign the value of ``polymorphic_identity`` for the mapped class to the ``discriminator`` attribute, thus persisting the value to the ``discriminator`` column in the database. - + See also: - + :ref:`inheritance_toplevel` - - :param polymorphic_identity: Specifies the value which + + :param polymorphic_identity: Specifies the value which identifies this particular class as returned by the column expression referred to by the ``polymorphic_on`` setting. As rows are received, the value corresponding to the ``polymorphic_on`` column expression is compared - to this value, indicating which subclass should + to this value, indicating which subclass should be used for the newly reconstructed object. :param properties: A dictionary mapping the string names of object @@ -1106,11 +1106,11 @@ def mapper(class_, local_table=None, *args, **params): This is normally simply the primary key of the ``local_table``, but can be overridden here. - :param version_id_col: A :class:`.Column` + :param version_id_col: A :class:`.Column` that will be used to keep a running version id of mapped entities in the database. This is used during save operations to ensure that no other thread or process has updated the instance during the - lifetime of the entity, else a :class:`~sqlalchemy.orm.exc.StaleDataError` + lifetime of the entity, else a :class:`~sqlalchemy.orm.exc.StaleDataError` exception is thrown. By default the column must be of :class:`.Integer` type, unless ``version_id_generator`` specifies a new generation @@ -1127,13 +1127,13 @@ def mapper(class_, local_table=None, *args, **params): __tablename__ = 'mytable' id = Column(Integer, primary_key=True) version_uuid = Column(String(32)) - + __mapper_args__ = { 'version_id_col':version_uuid, 'version_id_generator':lambda version:uuid.uuid4().hex } - The callable receives the current version identifier as its + The callable receives the current version identifier as its single argument. :param with_polymorphic: A tuple in the form ``(<classes>, @@ -1144,20 +1144,20 @@ def mapper(class_, local_table=None, *args, **params): ``'*'`` may be used to indicate all descending classes should be loaded immediately. The second tuple argument <selectable> indicates a selectable that will be used to query for multiple - classes. - + classes. + See also: - + :ref:`concrete_inheritance` - typically uses ``with_polymorphic`` to specify a UNION statement to select from. - - :ref:`with_polymorphic` - usage example of the related + + :ref:`with_polymorphic` - usage example of the related :meth:`.Query.with_polymorphic` method - + """ return Mapper(class_, local_table, *args, **params) -def synonym(name, map_column=False, descriptor=None, +def synonym(name, map_column=False, descriptor=None, comparator_factory=None, doc=None): """Denote an attribute name as a synonym to a mapped property. @@ -1179,7 +1179,7 @@ def synonym(name, map_column=False, descriptor=None, mapper(MyClass, sometable, properties={ "status":synonym("_status", map_column=True) }) - + Above, the ``status`` attribute of MyClass will produce expression behavior against the table column named ``status``, using the Python attribute ``_status`` on the mapped class @@ -1195,24 +1195,24 @@ def synonym(name, map_column=False, descriptor=None, column to map. """ - return SynonymProperty(name, map_column=map_column, - descriptor=descriptor, + return SynonymProperty(name, map_column=map_column, + descriptor=descriptor, comparator_factory=comparator_factory, doc=doc) def comparable_property(comparator_factory, descriptor=None): - """Provides a method of applying a :class:`.PropComparator` + """Provides a method of applying a :class:`.PropComparator` to any Python descriptor attribute. .. versionchanged:: 0.7 :func:`.comparable_property` is superseded by - the :mod:`~sqlalchemy.ext.hybrid` extension. See the example + the :mod:`~sqlalchemy.ext.hybrid` extension. See the example at :ref:`hybrid_custom_comparators`. - Allows any Python descriptor to behave like a SQL-enabled + Allows any Python descriptor to behave like a SQL-enabled attribute when used at the class level in queries, allowing redefinition of expression operator behavior. - + In the example below we redefine :meth:`.PropComparator.operate` to wrap both sides of an expression in ``func.lower()`` to produce case-insensitive comparison:: @@ -1226,7 +1226,7 @@ def comparable_property(comparator_factory, descriptor=None): class CaseInsensitiveComparator(PropComparator): def __clause_element__(self): return self.prop - + def operate(self, op, other): return op( func.lower(self.__clause_element__()), @@ -1243,13 +1243,13 @@ def comparable_property(comparator_factory, descriptor=None): CaseInsensitiveComparator(mapper.c.word, mapper) ) - - A mapping like the above allows the ``word_insensitive`` attribute + + A mapping like the above allows the ``word_insensitive`` attribute to render an expression like:: - + >>> print SearchWord.word_insensitive == "Trucks" lower(search_word.word) = lower(:lower_1) - + :param comparator_factory: A PropComparator subclass or factory that defines operator behavior for this property. @@ -1275,7 +1275,7 @@ def clear_mappers(): """Remove all mappers from all classes. This function removes all instrumentation from classes and disposes - of their associated mappers. Once called, the classes are unmapped + of their associated mappers. Once called, the classes are unmapped and can be later re-mapped with new mappers. :func:`.clear_mappers` is *not* for normal use, as there is literally no @@ -1286,12 +1286,12 @@ def clear_mappers(): such, :func:`.clear_mappers` is only for usage in test suites that re-use the same classes with different mappings, which is itself an extremely rare use case - the only such use case is in fact SQLAlchemy's own test suite, - and possibly the test suites of other ORM extension libraries which + and possibly the test suites of other ORM extension libraries which intend to test various combinations of mapper construction upon a fixed set of classes. """ - mapperlib._COMPILE_MUTEX.acquire() + mapperlib._CONFIGURE_MUTEX.acquire() try: while _mapper_registry: try: @@ -1301,7 +1301,7 @@ def clear_mappers(): except KeyError: pass finally: - mapperlib._COMPILE_MUTEX.release() + mapperlib._CONFIGURE_MUTEX.release() def joinedload(*keys, **kw): """Return a ``MapperOption`` that will convert the property of the given @@ -1321,7 +1321,7 @@ def joinedload(*keys, **kw): query(User).options(joinedload(User.orders)) # joined-load the "keywords" collection on each "Item", - # but not the "items" collection on "Order" - those + # but not the "items" collection on "Order" - those # remain lazily loaded. query(Order).options(joinedload(Order.items, Item.keywords)) @@ -1336,17 +1336,17 @@ def joinedload(*keys, **kw): query(Order).options(joinedload(Order.user, innerjoin=True)) - .. note:: - + .. note:: + The join created by :func:`joinedload` is anonymously aliased such that it **does not affect the query results**. An :meth:`.Query.order_by` or :meth:`.Query.filter` call **cannot** reference these aliased - tables - so-called "user space" joins are constructed using + tables - so-called "user space" joins are constructed using :meth:`.Query.join`. The rationale for this is that :func:`joinedload` is only applied in order to affect how related objects or collections are loaded as an optimizing detail - it can be added or removed with no impact - on actual results. See the section :ref:`zen_of_eager_loading` for - a detailed description of how this is used, including how to use a single + on actual results. See the section :ref:`zen_of_eager_loading` for + a detailed description of how this is used, including how to use a single explicit JOIN for filtering/ordering and eager loading simultaneously. See also: :func:`subqueryload`, :func:`lazyload` @@ -1355,7 +1355,7 @@ def joinedload(*keys, **kw): innerjoin = kw.pop('innerjoin', None) if innerjoin is not None: return ( - strategies.EagerLazyOption(keys, lazy='joined'), + strategies.EagerLazyOption(keys, lazy='joined'), strategies.EagerJoinOption(keys, innerjoin) ) else: @@ -1363,7 +1363,7 @@ def joinedload(*keys, **kw): def joinedload_all(*keys, **kw): """Return a ``MapperOption`` that will convert all properties along the - given dot-separated path or series of mapped attributes + given dot-separated path or series of mapped attributes into an joined eager load. .. versionchanged:: 0.6beta3 @@ -1395,7 +1395,7 @@ def joinedload_all(*keys, **kw): innerjoin = kw.pop('innerjoin', None) if innerjoin is not None: return ( - strategies.EagerLazyOption(keys, lazy='joined', chained=True), + strategies.EagerLazyOption(keys, lazy='joined', chained=True), strategies.EagerJoinOption(keys, innerjoin, chained=True) ) else: @@ -1411,8 +1411,8 @@ def eagerload_all(*args, **kwargs): return joinedload_all(*args, **kwargs) def subqueryload(*keys): - """Return a ``MapperOption`` that will convert the property - of the given name or series of mapped attributes + """Return a ``MapperOption`` that will convert the property + of the given name or series of mapped attributes into an subquery eager load. Used with :meth:`~sqlalchemy.orm.query.Query.options`. @@ -1423,7 +1423,7 @@ def subqueryload(*keys): query(User).options(subqueryload(User.orders)) # subquery-load the "keywords" collection on each "Item", - # but not the "items" collection on "Order" - those + # but not the "items" collection on "Order" - those # remain lazily loaded. query(Order).options(subqueryload(Order.items, Item.keywords)) @@ -1440,7 +1440,7 @@ def subqueryload(*keys): def subqueryload_all(*keys): """Return a ``MapperOption`` that will convert all properties along the - given dot-separated path or series of mapped attributes + given dot-separated path or series of mapped attributes into a subquery eager load. Used with :meth:`~sqlalchemy.orm.query.Query.options`. @@ -1475,7 +1475,7 @@ def lazyload(*keys): def lazyload_all(*keys): """Return a ``MapperOption`` that will convert all the properties - along the given dot-separated path or series of mapped attributes + along the given dot-separated path or series of mapped attributes into a lazy load. Used with :meth:`~sqlalchemy.orm.query.Query.options`. @@ -1491,22 +1491,22 @@ def noload(*keys): Used with :meth:`~sqlalchemy.orm.query.Query.options`. - See also: :func:`lazyload`, :func:`eagerload`, + See also: :func:`lazyload`, :func:`eagerload`, :func:`subqueryload`, :func:`immediateload` """ return strategies.EagerLazyOption(keys, lazy=None) def immediateload(*keys): - """Return a ``MapperOption`` that will convert the property of the given + """Return a ``MapperOption`` that will convert the property of the given name or series of mapped attributes into an immediate load. - + The "immediate" load means the attribute will be fetched - with a separate SELECT statement per parent in the + with a separate SELECT statement per parent in the same way as lazy loading - except the loader is guaranteed to be called at load time before the parent object is returned in the result. - + The normal behavior of lazy loading applies - if the relationship is a simple many-to-one, and the child object is already present in the :class:`.Session`, @@ -1526,7 +1526,7 @@ def contains_alias(alias): the main table has been aliased. This is used in the very rare case that :func:`.contains_eager` - is being used in conjunction with a user-defined SELECT + is being used in conjunction with a user-defined SELECT statement that aliases the parent table. E.g.:: # define an aliased UNION called 'ulist' @@ -1538,18 +1538,18 @@ def contains_alias(alias): statement = statement.outerjoin(addresses).\\ select().apply_labels() - # create query, indicating "ulist" will be an - # alias for the main table, "addresses" + # create query, indicating "ulist" will be an + # alias for the main table, "addresses" # property should be eager loaded query = session.query(User).options( - contains_alias('ulist'), + contains_alias('ulist'), contains_eager('addresses')) # then get results via the statement results = query.from_statement(statement).all() - :param alias: is the string name of an alias, or a - :class:`~.sql.expression.Alias` object representing + :param alias: is the string name of an alias, or a + :class:`~.sql.expression.Alias` object representing the alias. """ @@ -1562,7 +1562,7 @@ def contains_eager(*keys, **kwargs): Used with :meth:`~sqlalchemy.orm.query.Query.options`. - The option is used in conjunction with an explicit join that loads + The option is used in conjunction with an explicit join that loads the desired rows, i.e.:: sess.query(Order).\\ @@ -1583,7 +1583,7 @@ def contains_eager(*keys, **kwargs): join((user_alias, Order.user)).\\ options(contains_eager(Order.user, alias=user_alias)) - See also :func:`eagerload` for the "automatic" version of this + See also :func:`eagerload` for the "automatic" version of this functionality. For additional examples of :func:`contains_eager` see @@ -1603,36 +1603,36 @@ def defer(*key): of the given name into a deferred load. Used with :meth:`.Query.options`. - + e.g.:: - + from sqlalchemy.orm import defer - query(MyClass).options(defer("attribute_one"), + query(MyClass).options(defer("attribute_one"), defer("attribute_two")) - + A class bound descriptor is also accepted:: - + query(MyClass).options( - defer(MyClass.attribute_one), + defer(MyClass.attribute_one), defer(MyClass.attribute_two)) - + A "path" can be specified onto a related or collection object using a dotted name. The :func:`.orm.defer` option will be applied to that object when loaded:: - + query(MyClass).options( - defer("related.attribute_one"), + defer("related.attribute_one"), defer("related.attribute_two")) - + To specify a path via class, send multiple arguments:: query(MyClass).options( - defer(MyClass.related, MyOtherClass.attribute_one), + defer(MyClass.related, MyOtherClass.attribute_one), defer(MyClass.related, MyOtherClass.attribute_two)) - + See also: - + :ref:`deferred` :param \*key: A key representing an individual path. Multiple entries @@ -1647,41 +1647,41 @@ def undefer(*key): of the given name into a non-deferred (regular column) load. Used with :meth:`.Query.options`. - + e.g.:: - + from sqlalchemy.orm import undefer - query(MyClass).options(undefer("attribute_one"), + query(MyClass).options(undefer("attribute_one"), undefer("attribute_two")) - + A class bound descriptor is also accepted:: - + query(MyClass).options( - undefer(MyClass.attribute_one), + undefer(MyClass.attribute_one), undefer(MyClass.attribute_two)) - + A "path" can be specified onto a related or collection object using a dotted name. The :func:`.orm.undefer` option will be applied to that object when loaded:: - + query(MyClass).options( - undefer("related.attribute_one"), + undefer("related.attribute_one"), undefer("related.attribute_two")) - + To specify a path via class, send multiple arguments:: query(MyClass).options( - undefer(MyClass.related, MyOtherClass.attribute_one), + undefer(MyClass.related, MyOtherClass.attribute_one), undefer(MyClass.related, MyOtherClass.attribute_two)) - + See also: - + :func:`.orm.undefer_group` as a means to "undefer" a group of attributes at once. - + :ref:`deferred` - + :param \*key: A key representing an individual path. Multiple entries are accepted to allow a multiple-token path for a single target, not multiple targets. @@ -1694,17 +1694,17 @@ def undefer_group(name): column properties into a non-deferred (regular column) load. Used with :meth:`.Query.options`. - + e.g.:: - + query(MyClass).options(undefer("group_one")) See also: - + :ref:`deferred` - - :param name: String name of the deferred group. This name is - established using the "group" name to the :func:`.orm.deferred` + + :param name: String name of the deferred group. This name is + established using the "group" name to the :func:`.orm.deferred` configurational function. """ diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 982c4d77f..53b42d051 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -91,11 +91,11 @@ class InstanceEvents(event.Events): When using :class:`.InstanceEvents`, several modifiers are available to the :func:`.event.listen` function. - :param propagate=False: When True, the event listener should - be applied to all inheriting mappers as well as the + :param propagate=False: When True, the event listener should + be applied to all inheriting mappers as well as the mapper which is the target of this listener. :param raw=False: When True, the "target" argument passed - to applicable event listener functions will be the + to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. @@ -142,17 +142,17 @@ class InstanceEvents(event.Events): def init(self, target, args, kwargs): """Receive an instance when it's constructor is called. - This method is only called during a userland construction of + This method is only called during a userland construction of an object. It is not called when an object is loaded from the database. """ def init_failure(self, target, args, kwargs): - """Receive an instance when it's constructor has been called, + """Receive an instance when it's constructor has been called, and raised an exception. - This method is only called during a userland construction of + This method is only called during a userland construction of an object. It is not called when an object is loaded from the database. @@ -168,12 +168,12 @@ class InstanceEvents(event.Events): instance's lifetime. Note that during a result-row load, this method is called upon - the first row received for this instance. Note that some - attributes and collections may or may not be loaded or even + the first row received for this instance. Note that some + attributes and collections may or may not be loaded or even initialized, depending on what's present in the result rows. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the @@ -184,16 +184,16 @@ class InstanceEvents(event.Events): """ def refresh(self, target, context, attrs): - """Receive an object instance after one or more attributes have + """Receive an object instance after one or more attributes have been refreshed from a query. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the current :class:`.Query` in progress. - :param attrs: iterable collection of attribute names which + :param attrs: iterable collection of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated. @@ -206,23 +206,23 @@ class InstanceEvents(event.Events): 'keys' is a list of attribute names. If None, the entire state was expired. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param attrs: iterable collection of attribute - names which were expired, or None if all attributes were + names which were expired, or None if all attributes were expired. """ def resurrect(self, target): - """Receive an object instance as it is 'resurrected' from + """Receive an object instance as it is 'resurrected' from garbage collection, which occurs when a "dirty" state falls out of scope. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. @@ -232,28 +232,28 @@ class InstanceEvents(event.Events): """Receive an object instance when its associated state is being pickled. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. - :param state_dict: the dictionary returned by + :param state_dict: the dictionary returned by :class:`.InstanceState.__getstate__`, containing the state to be pickled. - + """ def unpickle(self, target, state_dict): """Receive an object instance after it's associated state has been unpickled. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param state_dict: the dictionary sent to :class:`.InstanceState.__setstate__`, containing the state dictionary which was pickled. - + """ class MapperEvents(event.Events): @@ -267,7 +267,7 @@ class MapperEvents(event.Events): # execute a stored procedure upon INSERT, # apply the value to the row to be inserted target.calculated_value = connection.scalar( - "select my_special_function(%d)" + "select my_special_function(%d)" % target.special_number) # associate the listener function with SomeMappedClass, @@ -304,16 +304,16 @@ class MapperEvents(event.Events): When using :class:`.MapperEvents`, several modifiers are available to the :func:`.event.listen` function. - :param propagate=False: When True, the event listener should - be applied to all inheriting mappers as well as the + :param propagate=False: When True, the event listener should + be applied to all inheriting mappers as well as the mapper which is the target of this listener. :param raw=False: When True, the "target" argument passed - to applicable event listener functions will be the + to applicable event listener functions will be the instance's :class:`.InstanceState` management object, rather than the mapped instance itself. :param retval=False: when True, the user-defined event function must have a return value, the purpose of which is either to - control subsequent event propagation, or to otherwise alter + control subsequent event propagation, or to otherwise alter the operation in progress by the mapper. Possible return values are: @@ -322,7 +322,7 @@ class MapperEvents(event.Events): * ``sqlalchemy.orm.interfaces.EXT_STOP`` - cancel all subsequent event handlers in the chain. * other values - the return value specified by specific listeners, - such as :meth:`~.MapperEvents.translate_row` or + such as :meth:`~.MapperEvents.translate_row` or :meth:`~.MapperEvents.create_instance`. """ @@ -335,12 +335,12 @@ class MapperEvents(event.Events): if issubclass(target, orm.Mapper): return target else: - return orm.class_mapper(target, compile=False) + return orm.class_mapper(target, configure=False) else: return target @classmethod - def _listen(cls, target, identifier, fn, + def _listen(cls, target, identifier, fn, raw=False, retval=False, propagate=False): if not raw or not retval: @@ -370,7 +370,7 @@ class MapperEvents(event.Events): event.Events._listen(target, identifier, fn) def instrument_class(self, mapper, class_): - """Receive a class when the mapper is first constructed, + """Receive a class when the mapper is first constructed, before instrumentation is applied to the mapped class. This event is the earliest phase of mapper construction. @@ -404,11 +404,11 @@ class MapperEvents(event.Events): This corresponds to the :func:`.orm.configure_mappers` call, which note is usually called automatically as mappings are first used. - + Theoretically this event is called once per application, but is actually called any time new mappers have been affected by a :func:`.orm.configure_mappers` call. If new mappings - are constructed after existing ones have already been used, + are constructed after existing ones have already been used, this event can be called again. """ @@ -420,9 +420,9 @@ class MapperEvents(event.Events): This listener is typically registered with ``retval=True``. It is called when the mapper first receives a row, before the object identity or the instance itself has been derived - from that row. The given row may or may not be a + from that row. The given row may or may not be a :class:`.RowProxy` object - it will always be a dictionary-like - object which contains mapped columns as keys. The + object which contains mapped columns as keys. The returned object should also be a dictionary-like object which recognizes mapped columns as keys. @@ -431,7 +431,7 @@ class MapperEvents(event.Events): :param context: the :class:`.QueryContext`, which includes a handle to the current :class:`.Query` in progress as well as additional state information. - :param row: the result row being handled. This may be + :param row: the result row being handled. This may be an actual :class:`.RowProxy` or may be a dictionary containing :class:`.Column` objects as keys. :return: When configured with ``retval=True``, the function @@ -454,18 +454,18 @@ class MapperEvents(event.Events): :param context: the :class:`.QueryContext`, which includes a handle to the current :class:`.Query` in progress as well as additional state information. - :param row: the result row being handled. This may be + :param row: the result row being handled. This may be an actual :class:`.RowProxy` or may be a dictionary containing :class:`.Column` objects as keys. :param class\_: the mapped class. :return: When configured with ``retval=True``, the return value - should be a newly created instance of the mapped class, + should be a newly created instance of the mapped class, or ``EXT_CONTINUE`` indicating that default object construction should take place. """ - def append_result(self, mapper, context, row, target, + def append_result(self, mapper, context, row, target, result, **flags): """Receive an object instance before that instance is appended to a result list. @@ -478,27 +478,27 @@ class MapperEvents(event.Events): :param context: the :class:`.QueryContext`, which includes a handle to the current :class:`.Query` in progress as well as additional state information. - :param row: the result row being handled. This may be + :param row: the result row being handled. This may be an actual :class:`.RowProxy` or may be a dictionary containing :class:`.Column` objects as keys. - :param target: the mapped instance being populated. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being populated. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param result: a list-like object where results are being appended. - :param \**flags: Additional state information about the + :param \**flags: Additional state information about the current handling of the row. :return: If this method is registered with ``retval=True``, a return value of ``EXT_STOP`` will prevent the instance - from being appended to the given result list, whereas a + from being appended to the given result list, whereas a return value of ``EXT_CONTINUE`` will result in the default behavior of appending the value to the result list. """ - def populate_instance(self, mapper, context, row, + def populate_instance(self, mapper, context, row, target, **flags): """Receive an instance before that instance has its attributes populated. @@ -518,11 +518,11 @@ class MapperEvents(event.Events): :param context: the :class:`.QueryContext`, which includes a handle to the current :class:`.Query` in progress as well as additional state information. - :param row: the result row being handled. This may be + :param row: the result row being handled. This may be an actual :class:`.RowProxy` or may be a dictionary containing :class:`.Column` objects as keys. - :param target: the mapped instance. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: When configured with ``retval=True``, a return @@ -536,9 +536,9 @@ class MapperEvents(event.Events): """Receive an object instance before an INSERT statement is emitted corresponding to that instance. - This event is used to modify local, non-object related + This event is used to modify local, non-object related attributes on the instance before an INSERT occurs, as well - as to emit additional SQL statements on the given + as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the @@ -552,23 +552,23 @@ class MapperEvents(event.Events): .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -576,12 +576,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit INSERT statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being persisted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being persisted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -594,7 +594,7 @@ class MapperEvents(event.Events): This event is used to modify in-Python-only state on the instance after an INSERT occurs, as well - as to emit additional SQL statements on the given + as to emit additional SQL statements on the given connection. The event is often called for a batch of objects of the @@ -608,23 +608,23 @@ class MapperEvents(event.Events): .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -632,12 +632,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit INSERT statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being persisted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being persisted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -648,9 +648,9 @@ class MapperEvents(event.Events): """Receive an object instance before an UPDATE statement is emitted corresponding to that instance. - This event is used to modify local, non-object related + This event is used to modify local, non-object related attributes on the instance before an UPDATE occurs, as well - as to emit additional SQL statements on the given + as to emit additional SQL statements on the given connection. This method is called for all instances that are @@ -683,23 +683,23 @@ class MapperEvents(event.Events): .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -707,12 +707,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit UPDATE statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being persisted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being persisted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -724,12 +724,12 @@ class MapperEvents(event.Events): This event is used to modify in-Python-only state on the instance after an UPDATE occurs, as well - as to emit additional SQL statements on the given + as to emit additional SQL statements on the given connection. This method is called for all instances that are marked as "dirty", *even those which have no net changes - to their column-based attributes*, and for which + to their column-based attributes*, and for which no UPDATE statement has proceeded. An object is marked as dirty when any of its column-based attributes have a "set attribute" operation called or when any of its @@ -756,23 +756,23 @@ class MapperEvents(event.Events): .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -780,12 +780,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit UPDATE statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being persisted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being persisted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -796,33 +796,33 @@ class MapperEvents(event.Events): """Receive an object instance before a DELETE statement is emitted corresponding to that instance. - This event is used to emit additional SQL statements on + This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class before their DELETE statements are emitted at - once in a later step. + once in a later step. .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -830,12 +830,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit DELETE statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being deleted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being deleted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -846,33 +846,33 @@ class MapperEvents(event.Events): """Receive an object instance after a DELETE statement has been emitted corresponding to that instance. - This event is used to emit additional SQL statements on + This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event. The event is often called for a batch of objects of the same class after their DELETE statements have been emitted at - once in a previous step. + once in a previous step. .. warning:: Mapper-level flush events are designed to operate **on attributes - local to the immediate object being handled + local to the immediate object being handled and via SQL operations with the given** :class:`.Connection` **only.** - Handlers here should **not** make alterations to the state of + Handlers here should **not** make alterations to the state of the :class:`.Session` overall, and in general should not - affect any :func:`.relationship` -mapped attributes, as + affect any :func:`.relationship` -mapped attributes, as session cascade rules will not function properly, nor is it - always known if the related class has already been handled. + always known if the related class has already been handled. Operations that **are not supported in mapper events** include: - + * :meth:`.Session.add` * :meth:`.Session.delete` * Mapped collection append, add, remove, delete, discard, etc. * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` - + Operations which manipulate the state of the object relative to other objects are better handled: - + * In the ``__init__()`` method of the mapped object itself, or another method designed to establish some particular state. * In a ``@validates`` handler, see :ref:`simple_validators` @@ -880,12 +880,12 @@ class MapperEvents(event.Events): :param mapper: the :class:`.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`.Connection` being used to emit DELETE statements for this instance. This - provides a handle into the current transaction on the + provides a handle into the current transaction on the target database specific to this instance. - :param target: the mapped instance being deleted. If - the event is configured with ``raw=True``, this will + :param target: the mapped instance being deleted. If + the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :return: No return value is supported by this event. @@ -952,7 +952,7 @@ class SessionEvents(event.Events): transaction is ongoing. :param session: The target :class:`.Session`. - + """ def after_commit(self, session): @@ -960,19 +960,19 @@ class SessionEvents(event.Events): Note that this may not be per-flush if a longer running transaction is ongoing. - + :param session: The target :class:`.Session`. - + """ def after_rollback(self, session): """Execute after a real DBAPI rollback has occurred. - + Note that this event only fires when the *actual* rollback against - the database occurs - it does *not* fire each time the - :meth:`.Session.rollback` method is called, if the underlying + the database occurs - it does *not* fire each time the + :meth:`.Session.rollback` method is called, if the underlying DBAPI transaction has already been rolled back. In many - cases, the :class:`.Session` will not be in + cases, the :class:`.Session` will not be in an "active" state during this event, as the current transaction is not valid. To acquire a :class:`.Session` which is active after the outermost rollback has proceeded, @@ -984,23 +984,23 @@ class SessionEvents(event.Events): """ def after_soft_rollback(self, session, previous_transaction): - """Execute after any rollback has occurred, including "soft" + """Execute after any rollback has occurred, including "soft" rollbacks that don't actually emit at the DBAPI level. - + This corresponds to both nested and outer rollbacks, i.e. - the innermost rollback that calls the DBAPI's - rollback() method, as well as the enclosing rollback + the innermost rollback that calls the DBAPI's + rollback() method, as well as the enclosing rollback calls that only pop themselves from the transaction stack. - - The given :class:`.Session` can be used to invoke SQL and - :meth:`.Session.query` operations after an outermost rollback + + The given :class:`.Session` can be used to invoke SQL and + :meth:`.Session.query` operations after an outermost rollback by first checking the :attr:`.Session.is_active` flag:: @event.listens_for(Session, "after_soft_rollback") def do_something(session, previous_transaction): if session.is_active: session.execute("select * from some_table") - + :param session: The target :class:`.Session`. :param previous_transaction: The :class:`.SessionTransaction` transactional marker object which was just closed. The current :class:`.SessionTransaction` @@ -1030,7 +1030,7 @@ class SessionEvents(event.Events): Note that the session's state is still in pre-flush, i.e. 'new', 'dirty', and 'deleted' lists still show pre-flush state as well as the history settings on instance attributes. - + :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. @@ -1044,8 +1044,8 @@ class SessionEvents(event.Events): This will be when the 'new', 'dirty', and 'deleted' lists are in their final state. An actual commit() may or may not have occurred, depending on whether or not the flush started its own - transaction or participated in a larger transaction. - + transaction or participated in a larger transaction. + :param session: The target :class:`.Session`. :param flush_context: Internal :class:`.UOWTransaction` object which handles the details of the flush. @@ -1056,9 +1056,9 @@ class SessionEvents(event.Events): :param session: The target :class:`.Session`. :param transaction: The :class:`.SessionTransaction`. - :param connection: The :class:`~.engine.base.Connection` object + :param connection: The :class:`~.engine.base.Connection` object which will be used for SQL statements. - + """ def before_attach(self, session, instance): @@ -1066,30 +1066,30 @@ class SessionEvents(event.Events): This is called before an add, delete or merge causes the object to be part of the session. - - .. versionadded:: 0.8. Note that :meth:`.after_attach` now - fires off after the item is part of the session. + + .. versionadded:: 0.8. Note that :meth:`.after_attach` now + fires off after the item is part of the session. :meth:`.before_attach` is provided for those cases where the item should not yet be part of the session state. - + """ def after_attach(self, session, instance): """Execute after an instance is attached to a session. - This is called after an add, delete or merge. - + This is called after an add, delete or merge. + .. note:: - + As of 0.8, this event fires off *after* the item has been fully associated with the session, which is different than previous releases. For event - handlers that require the object not yet + handlers that require the object not yet be part of session state (such as handlers which may autoflush while the target object is not yet complete) consider the new :meth:`.before_attach` event. - + """ def after_bulk_update( self, session, query, query_context, result): @@ -1098,7 +1098,7 @@ class SessionEvents(event.Events): This is called as a result of the :meth:`.Query.update` method. :param query: the :class:`.Query` object that this update operation was - called upon. + called upon. :param query_context: The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. :param result: the :class:`.ResultProxy` returned as a result of the @@ -1112,7 +1112,7 @@ class SessionEvents(event.Events): This is called as a result of the :meth:`.Query.delete` method. :param query: the :class:`.Query` object that this update operation was - called upon. + called upon. :param query_context: The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. :param result: the :class:`.ResultProxy` returned as a result of the @@ -1163,15 +1163,15 @@ class AttributeEvents(event.Events): :param propagate=False: When True, the listener function will be established not just for the class attribute given, but - for attributes of the same name on all current subclasses - of that class, as well as all future subclasses of that - class, using an additional listener that listens for + for attributes of the same name on all current subclasses + of that class, as well as all future subclasses of that + class, using an additional listener that listens for instrumentation events. :param raw=False: When True, the "target" argument to the event will be the :class:`.InstanceState` management object, rather than the mapped instance itself. - :param retval=False: when True, the user-defined event - listening must return the "value" argument from the + :param retval=False: when True, the user-defined event + listening must return the "value" argument from the function. This gives the listening function the opportunity to change the value that is ultimately used for a "set" or "append" event. @@ -1187,7 +1187,7 @@ class AttributeEvents(event.Events): return target @classmethod - def _listen(cls, target, identifier, fn, active_history=False, + def _listen(cls, target, identifier, fn, active_history=False, raw=False, retval=False, propagate=False): if active_history: @@ -1228,9 +1228,9 @@ class AttributeEvents(event.Events): be the :class:`.InstanceState` object. :param value: the value being appended. If this listener is registered with ``retval=True``, the listener - function must return this value, or a new value which + function must return this value, or a new value which replaces it. - :param initiator: the attribute implementation object + :param initiator: the attribute implementation object which initiated this event. :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. @@ -1244,7 +1244,7 @@ class AttributeEvents(event.Events): If the listener is registered with ``raw=True``, this will be the :class:`.InstanceState` object. :param value: the value being removed. - :param initiator: the attribute implementation object + :param initiator: the attribute implementation object which initiated this event. :return: No return value is defined for this event. """ @@ -1257,15 +1257,15 @@ class AttributeEvents(event.Events): be the :class:`.InstanceState` object. :param value: the value being set. If this listener is registered with ``retval=True``, the listener - function must return this value, or a new value which + function must return this value, or a new value which replaces it. :param oldvalue: the previous value being replaced. This may also be the symbol ``NEVER_SET`` or ``NO_VALUE``. If the listener is registered with ``active_history=True``, the previous value of the attribute will be loaded from - the database if the existing value is currently unloaded + the database if the existing value is currently unloaded or expired. - :param initiator: the attribute implementation object + :param initiator: the attribute implementation object which initiated this event. :return: if the event was registered with ``retval=True``, the given value, or a new effective value, should be returned. diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 1b1d7dfa9..1e47e6616 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -55,8 +55,17 @@ MANYTOMANY = util.symbol('MANYTOMANY') from .deprecated_interfaces import AttributeExtension, SessionExtension, \ MapperExtension +class _InspectionAttr(object): + """Define a series of attributes that all ORM inspection + targets need to have.""" -class MapperProperty(object): + is_selectable = False + is_aliased_class = False + is_instance = False + is_mapper = False + is_property = False + +class MapperProperty(_InspectionAttr): """Manage the relationship of a ``Mapper`` to a single class attribute, as well as that attribute as it appears on individual instances of the class, including attribute instrumentation, @@ -77,6 +86,8 @@ class MapperProperty(object): """ + is_property = True + def setup(self, context, entity, path, adapter, **kwargs): """Called by Query for the purposes of constructing a SQL statement. @@ -115,8 +126,8 @@ class MapperProperty(object): def instrument_class(self, mapper): # pragma: no-coverage raise NotImplementedError() - _compile_started = False - _compile_finished = False + _configure_started = False + _configure_finished = False def init(self): """Called after all mappers are created to assemble @@ -124,9 +135,9 @@ class MapperProperty(object): initialization steps. """ - self._compile_started = True + self._configure_started = True self.do_init() - self._compile_finished = True + self._configure_finished = True @property def class_attribute(self): diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 9aff3cb85..01b4d3a0f 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -19,11 +19,11 @@ import weakref from itertools import chain from collections import deque -from .. import sql, util, log, exc as sa_exc, event, schema +from .. import sql, util, log, exc as sa_exc, event, schema, inspection from ..sql import expression, visitors, operators, util as sql_util from . import instrumentation, attributes, \ exc as orm_exc, events, loading -from .interfaces import MapperProperty +from .interfaces import MapperProperty, _InspectionAttr from .util import _INSTRUMENTOR, _class_to_mapper, \ _state_mapper, class_mapper, \ @@ -51,10 +51,10 @@ _memoized_configured_property = util.group_expirable_memoized_property() # column NO_ATTRIBUTE = util.symbol('NO_ATTRIBUTE') -# lock used to synchronize the "mapper compile" step -_COMPILE_MUTEX = util.threading.RLock() +# lock used to synchronize the "mapper configure" step +_CONFIGURE_MUTEX = util.threading.RLock() -class Mapper(object): +class Mapper(_InspectionAttr): """Define the correlation of class attributes to database table columns. @@ -182,7 +182,7 @@ class Mapper(object): # prevent this mapper from being constructed # while a configure_mappers() is occurring (and defer a # configure_mappers() until construction succeeds) - _COMPILE_MUTEX.acquire() + _CONFIGURE_MUTEX.acquire() try: self._configure_inheritance() self._configure_legacy_instrument_class() @@ -196,11 +196,23 @@ class Mapper(object): self._log("constructed") self._expire_memoizations() finally: - _COMPILE_MUTEX.release() + _CONFIGURE_MUTEX.release() # major attributes initialized at the classlevel so that # they can be Sphinx-documented. + is_mapper = True + """Part of the inspection API.""" + + @property + def mapper(self): + """Part of the inspection API. + + Returns self. + + """ + return self + local_table = None """The :class:`.Selectable` which this :class:`.Mapper` manages. @@ -435,7 +447,7 @@ class Mapper(object): if self.inherits: if isinstance(self.inherits, type): - self.inherits = class_mapper(self.inherits, compile=False) + self.inherits = class_mapper(self.inherits, configure=False) if not issubclass(self.class_, self.inherits.class_): raise sa_exc.ArgumentError( "Class '%s' does not inherit from '%s'" % @@ -1185,10 +1197,10 @@ class Mapper(object): for key, prop in l: self._log("initialize prop %s", key) - if prop.parent is self and not prop._compile_started: + if prop.parent is self and not prop._configure_started: prop.init() - if prop._compile_finished: + if prop._configure_finished: prop.post_instrument_class(self) self._log("_post_configure_properties() complete") @@ -1263,11 +1275,11 @@ class Mapper(object): def has_property(self, key): return key in self._props - def get_property(self, key, _compile_mappers=True): + def get_property(self, key, _configure_mappers=True): """return a MapperProperty associated with the given key. """ - if _compile_mappers and _new_mappers: + if _configure_mappers and _new_mappers: configure_mappers() try: @@ -1352,10 +1364,13 @@ class Mapper(object): @_memoized_configured_property def _with_polymorphic_mappers(self): + if _new_mappers: + configure_mappers() if not self.with_polymorphic: return [self] return self._mappers_from_spec(*self.with_polymorphic) + @_memoized_configured_property def _with_polymorphic_selectable(self): if not self.with_polymorphic: @@ -1369,6 +1384,22 @@ class Mapper(object): self._mappers_from_spec(spec, selectable), False) + with_polymorphic_mappers = _with_polymorphic_mappers + """The list of :class:`.Mapper` objects included in the + default "polymorphic" query. + + """ + + selectable = _with_polymorphic_selectable + """The :func:`.select` construct this :class:`.Mapper` selects from + by default. + + Normally, this is equivalent to :attr:`.mapped_table`, unless + the ``with_polymorphic`` feature is in use, in which case the + full "polymoprhic" selectable is returned. + + """ + def _with_polymorphic_args(self, spec=None, selectable=False, innerjoin=False): if self.with_polymorphic: @@ -1886,6 +1917,7 @@ class Mapper(object): return result +inspection._self_inspects(Mapper) log.class_logger(Mapper) def configure_mappers(): @@ -1902,7 +1934,7 @@ def configure_mappers(): return _call_configured = None - _COMPILE_MUTEX.acquire() + _CONFIGURE_MUTEX.acquire() try: global _already_compiling if _already_compiling: @@ -1944,7 +1976,7 @@ def configure_mappers(): finally: _already_compiling = False finally: - _COMPILE_MUTEX.release() + _CONFIGURE_MUTEX.release() if _call_configured is not None: _call_configured.dispatch.after_configured() diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index efad54839..6b1dd6462 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -886,7 +886,7 @@ class RelationshipProperty(StrategizedProperty): def _add_reverse_property(self, key): - other = self.mapper.get_property(key, _compile_mappers=False) + other = self.mapper.get_property(key, _configure_mappers=False) self._reverse_property.add(other) other._reverse_property.add(self) @@ -912,7 +912,7 @@ class RelationshipProperty(StrategizedProperty): """ if isinstance(self.argument, type): mapper_ = mapper.class_mapper(self.argument, - compile=False) + configure=False) elif isinstance(self.argument, mapper.Mapper): mapper_ = self.argument elif util.callable(self.argument): @@ -921,7 +921,7 @@ class RelationshipProperty(StrategizedProperty): # configurational schemes mapper_ = mapper.class_mapper(self.argument(), - compile=False) + configure=False) else: raise sa_exc.ArgumentError("relationship '%s' expects " "a class or a mapper argument (received: %s)" @@ -1037,7 +1037,7 @@ class RelationshipProperty(StrategizedProperty): if not self.is_primary() \ and not mapper.class_mapper( self.parent.class_, - compile=False).has_property(self.key): + configure=False).has_property(self.key): raise sa_exc.ArgumentError("Attempting to assign a new " "relationship '%s' to a non-primary mapper on " "class '%s'. New relationships can only be added " diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index ed600a2f0..f981399db 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -6,14 +6,14 @@ """The Query class and support. -Defines the :class:`.Query` class, the central +Defines the :class:`.Query` class, the central construct used by the ORM to construct database queries. The :class:`.Query` class should not be confused with the -:class:`.Select` class, which defines database -SELECT operations at the SQL (non-ORM) level. ``Query`` differs from -``Select`` in that it returns ORM-mapped objects and interacts with an -ORM session, whereas the ``Select`` construct interacts directly with the +:class:`.Select` class, which defines database +SELECT operations at the SQL (non-ORM) level. ``Query`` differs from +``Select`` in that it returns ORM-mapped objects and interacts with an +ORM session, whereas the ``Select`` construct interacts directly with the database to return iterable result sets. """ @@ -21,7 +21,7 @@ database to return iterable result sets. from itertools import chain from . import ( - attributes, interfaces, object_mapper, persistence, + attributes, interfaces, object_mapper, persistence, exc as orm_exc, loading ) from .util import ( @@ -57,15 +57,15 @@ class Query(object): """ORM-level SQL construction object. :class:`.Query` is the source of all SELECT statements generated by the - ORM, both those formulated by end-user query operations as well as by - high level internal operations such as related collection loading. It + ORM, both those formulated by end-user query operations as well as by + high level internal operations such as related collection loading. It features a generative interface whereby successive calls return a new - :class:`.Query` object, a copy of the former with additional + :class:`.Query` object, a copy of the former with additional criteria and options associated with it. - :class:`.Query` objects are normally initially generated using the - :meth:`~.Session.query` method of :class:`.Session`. For a full - walkthrough of :class:`.Query` usage, see the + :class:`.Query` objects are normally initially generated using the + :meth:`~.Session.query` method of :class:`.Session`. For a full + walkthrough of :class:`.Query` usage, see the :ref:`ormtutorial_toplevel`. """ @@ -133,16 +133,16 @@ class Query(object): if ext_info.mapper.mapped_table not in \ self._polymorphic_adapters: self._mapper_loads_polymorphically_with( - ext_info.mapper, + ext_info.mapper, sql_util.ColumnAdapter( - ext_info.selectable, + ext_info.selectable, ext_info.mapper._equivalent_columns ) ) aliased_adapter = None elif ext_info.is_aliased_class: aliased_adapter = sql_util.ColumnAdapter( - ext_info.selectable, + ext_info.selectable, ext_info.mapper._equivalent_columns ) else: @@ -199,8 +199,8 @@ class Query(object): def _adapt_col_list(self, cols): return [ self._adapt_clause( - expression._literal_as_text(o), - True, True) + expression._literal_as_text(o), + True, True) for o in cols ] @@ -209,7 +209,7 @@ class Query(object): self._orm_only_adapt = False def _adapt_clause(self, clause, as_filter, orm_only): - """Adapt incoming clauses to transformations which + """Adapt incoming clauses to transformations which have been applied within this query.""" adapters = [] @@ -228,12 +228,12 @@ class Query(object): if self._from_obj_alias: # for the "from obj" alias, apply extra rule to the - # 'ORM only' check, if this query were generated from a + # 'ORM only' check, if this query were generated from a # subquery of itself, i.e. _from_selectable(), apply adaption # to all SQL constructs. adapters.append( ( - getattr(self, '_orm_only_from_obj_alias', orm_only), + getattr(self, '_orm_only_from_obj_alias', orm_only), self._from_obj_alias.replace ) ) @@ -261,8 +261,8 @@ class Query(object): return e return visitors.replacement_traverse( - clause, - {}, + clause, + {}, replace ) @@ -297,7 +297,7 @@ class Query(object): def _only_mapper_zero(self, rationale=None): if len(self._entities) > 1: raise sa_exc.InvalidRequestError( - rationale or + rationale or "This operation requires a Query " "against a single mapper." ) @@ -318,7 +318,7 @@ class Query(object): def _only_entity_zero(self, rationale=None): if len(self._entities) > 1: raise sa_exc.InvalidRequestError( - rationale or + rationale or "This operation requires a Query " "against a single mapper." ) @@ -392,13 +392,13 @@ class Query(object): ): if getattr(self, attr) is not notset: raise sa_exc.InvalidRequestError( - "Can't call Query.%s() when %s has been called" % + "Can't call Query.%s() when %s has been called" % (meth, methname) ) - def _get_options(self, populate_existing=None, - version_check=None, - only_load_props=None, + def _get_options(self, populate_existing=None, + version_check=None, + only_load_props=None, refresh_state=None): if populate_existing: self._populate_existing = populate_existing @@ -435,17 +435,17 @@ class Query(object): return stmt._annotate({'no_replacement_traverse': True}) def subquery(self, name=None): - """return the full SELECT statement represented by + """return the full SELECT statement represented by this :class:`.Query`, embedded within an :class:`.Alias`. Eager JOIN generation within the query is disabled. The statement will not have disambiguating labels - applied to the list of selected columns unless the + applied to the list of selected columns unless the :meth:`.Query.with_labels` method is used to generate a new :class:`.Query` with the option enabled. - :param name: string name to be assigned as the alias; + :param name: string name to be assigned as the alias; this is passed through to :meth:`.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. @@ -455,23 +455,23 @@ class Query(object): return self.enable_eagerloads(False).statement.alias(name=name) def cte(self, name=None, recursive=False): - """Return the full SELECT statement represented by this + """Return the full SELECT statement represented by this :class:`.Query` represented as a common table expression (CTE). .. versionadded:: 0.7.6 - Parameters and usage are the same as those of the - :meth:`._SelectBase.cte` method; see that method for + Parameters and usage are the same as those of the + :meth:`._SelectBase.cte` method; see that method for further details. - Here is the `Postgresql WITH - RECURSIVE example + Here is the `Postgresql WITH + RECURSIVE example <http://www.postgresql.org/docs/8.4/static/queries-with.html>`_. - Note that, in this example, the ``included_parts`` cte and the + Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which - means the columns are accessed via the ``.c.`` attribute. The - ``parts_alias`` object is an :func:`.orm.aliased` instance of the - ``Part`` entity, so column-mapped attributes are available + means the columns are accessed via the ``.c.`` attribute. The + ``parts_alias`` object is an :func:`.orm.aliased` instance of the + ``Part`` entity, so column-mapped attributes are available directly:: from sqlalchemy.orm import aliased @@ -483,8 +483,8 @@ class Query(object): quantity = Column(Integer) included_parts = session.query( - Part.sub_part, - Part.part, + Part.sub_part, + Part.part, Part.quantity).\\ filter(Part.part=="our part").\\ cte(name="included_parts", recursive=True) @@ -493,8 +493,8 @@ class Query(object): parts_alias = aliased(Part, name="p") included_parts = included_parts.union_all( session.query( - parts_alias.part, - parts_alias.sub_part, + parts_alias.part, + parts_alias.sub_part, parts_alias.quantity).\\ filter(parts_alias.part==incl_alias.c.sub_part) ) @@ -515,8 +515,8 @@ class Query(object): statement.cte(name=name, recursive=recursive) def label(self, name): - """Return the full SELECT statement represented by this - :class:`.Query`, converted + """Return the full SELECT statement represented by this + :class:`.Query`, converted to a scalar subquery with a label of the given name. Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.label`. @@ -529,7 +529,7 @@ class Query(object): def as_scalar(self): - """Return the full SELECT statement represented by this :class:`.Query`, converted + """Return the full SELECT statement represented by this :class:`.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.as_scalar`. @@ -546,7 +546,7 @@ class Query(object): @_generative() def enable_eagerloads(self, value): - """Control whether or not eager joins and subqueries are + """Control whether or not eager joins and subqueries are rendered. When set to False, the returned Query will not render @@ -582,17 +582,17 @@ class Query(object): def enable_assertions(self, value): """Control whether assertions are generated. - When set to False, the returned Query will - not assert its state before certain operations, + When set to False, the returned Query will + not assert its state before certain operations, including that LIMIT/OFFSET has not been applied when filter() is called, no criterion exists when get() is called, and no "from_statement()" exists when filter()/order_by()/group_by() etc. - is called. This more permissive mode is used by - custom Query subclasses to specify criterion or + is called. This more permissive mode is used by + custom Query subclasses to specify criterion or other modifiers outside of the usual usage patterns. - Care should be taken to ensure that the usage + Care should be taken to ensure that the usage pattern is even possible. A statement applied by from_statement() will override any criterion set by filter() or order_by(), for example. @@ -604,7 +604,7 @@ class Query(object): def whereclause(self): """A readonly attribute which returns the current WHERE criterion for this Query. - This returned value is a SQL expression construct, or ``None`` if no + This returned value is a SQL expression construct, or ``None`` if no criterion has been established. """ @@ -612,39 +612,39 @@ class Query(object): @_generative() def _with_current_path(self, path): - """indicate that this query applies to objects loaded + """indicate that this query applies to objects loaded within a certain path. - Used by deferred loaders (see strategies.py) which transfer - query options from an originating query to a newly generated + Used by deferred loaders (see strategies.py) which transfer + query options from an originating query to a newly generated query intended for the deferred load. """ self._current_path = path @_generative(_no_clauseelement_condition) - def with_polymorphic(self, - cls_or_mappers, - selectable=None, + def with_polymorphic(self, + cls_or_mappers, + selectable=None, polymorphic_on=None): """Load columns for inheriting classes. - :meth:`.Query.with_polymorphic` applies transformations + :meth:`.Query.with_polymorphic` applies transformations to the "main" mapped class represented by this :class:`.Query`. The "main" mapped class here means the :class:`.Query` object's first argument is a full class, i.e. ``session.query(SomeClass)``. These transformations allow additional tables to be present in the FROM clause so that columns for a joined-inheritance subclass are available in the query, both for the purposes - of load-time efficiency as well as the ability to use + of load-time efficiency as well as the ability to use these columns at query time. See the documentation section :ref:`with_polymorphic` for details on how this method is used. .. versionchanged:: 0.8 - A new and more flexible function - :func:`.orm.with_polymorphic` supersedes + A new and more flexible function + :func:`.orm.with_polymorphic` supersedes :meth:`.Query.with_polymorphic`, as it can apply the equivalent functionality to any set of columns or classes in the :class:`.Query`, not just the "zero mapper". See that @@ -657,8 +657,8 @@ class Query(object): "No primary mapper set up for this Query.") entity = self._entities[0]._clone() self._entities = [entity] + self._entities[1:] - entity.set_with_polymorphic(self, - cls_or_mappers, + entity.set_with_polymorphic(self, + cls_or_mappers, selectable=selectable, polymorphic_on=polymorphic_on) @@ -671,15 +671,15 @@ class Query(object): overwritten. In particular, it's usually impossible to use this setting with - eagerly loaded collections (i.e. any lazy='joined' or 'subquery') - since those collections will be cleared for a new load when + eagerly loaded collections (i.e. any lazy='joined' or 'subquery') + since those collections will be cleared for a new load when encountered in a subsequent result batch. In the case of 'subquery' loading, the full result for all rows is fetched which generally defeats the purpose of :meth:`~sqlalchemy.orm.query.Query.yield_per`. Also note that many DBAPIs do not "stream" results, pre-buffering - all rows before making them available, including mysql-python and - psycopg2. :meth:`~sqlalchemy.orm.query.Query.yield_per` will also + all rows before making them available, including mysql-python and + psycopg2. :meth:`~sqlalchemy.orm.query.Query.yield_per` will also set the ``stream_results`` execution option to ``True``, which currently is only understood by psycopg2 and causes server side cursors to be used. @@ -690,7 +690,7 @@ class Query(object): self._execution_options['stream_results'] = True def get(self, ident): - """Return an instance based on the given primary key identifier, + """Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: @@ -699,24 +699,24 @@ class Query(object): some_object = session.query(VersionedFoo).get((5, 10)) - :meth:`~.Query.get` is special in that it provides direct + :meth:`~.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned - directly from this collection and no SQL is emitted, + directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. - :meth:`~.Query.get` also will perform a check if - the object is present in the identity map and - marked as expired - a SELECT + :meth:`~.Query.get` also will perform a check if + the object is present in the identity map and + marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :meth:`~.Query.get` is only used to return a single - mapped instance, not multiple instances or + mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating :class:`.Query` must be constructed in this way, @@ -728,7 +728,7 @@ class Query(object): A lazy-loading, many-to-one attribute configured by :func:`.relationship`, using a simple - foreign-key-to-primary-key criterion, will also use an + foreign-key-to-primary-key criterion, will also use an operation equivalent to :meth:`~.Query.get` in order to retrieve the target value from the local identity map before querying the database. See :ref:`loading_toplevel` @@ -737,10 +737,10 @@ class Query(object): :param ident: A scalar or tuple value representing the primary key. For a composite primary key, the order of identifiers corresponds in most cases - to that of the mapped :class:`.Table` object's + to that of the mapped :class:`.Table` object's primary key columns. For a :func:`.mapper` that was given the ``primary key`` argument during - construction, the order of identifiers corresponds + construction, the order of identifiers corresponds to the elements present in this collection. :return: The object instance, or ``None``. @@ -792,14 +792,14 @@ class Query(object): :meth:`.Select.correlate` after coercion to expression constructs. The correlation arguments take effect in such cases - as when :meth:`.Query.from_self` is used, or when - a subquery as returned by :meth:`.Query.subquery` is + as when :meth:`.Query.from_self` is used, or when + a subquery as returned by :meth:`.Query.subquery` is embedded in another :func:`~.expression.select` construct. """ self._correlate = self._correlate.union( - _orm_selectable(s) + _orm_selectable(s) for s in args) @_generative() @@ -816,11 +816,11 @@ class Query(object): @_generative() def populate_existing(self): - """Return a :class:`.Query` that will expire and refresh all instances + """Return a :class:`.Query` that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. - :meth:`.populate_existing` does not improve behavior when - the ORM is used normally - the :class:`.Session` object's usual + :meth:`.populate_existing` does not improve behavior when + the ORM is used normally - the :class:`.Session` object's usual behavior of maintaining a transaction and expiring all attributes after rollback or commit handles object state automatically. This method is not intended for general use. @@ -841,7 +841,7 @@ class Query(object): def with_parent(self, instance, property=None): """Add filtering criterion that relates the given instance - to a child object or collection, using its attribute state + to a child object or collection, using its attribute state as well as an established :func:`.relationship()` configuration. @@ -866,7 +866,7 @@ class Query(object): else: raise sa_exc.InvalidRequestError( "Could not locate a property which relates instances " - "of class '%s' to instances of class '%s'" % + "of class '%s' to instances of class '%s'" % ( self._mapper_zero().class_.__name__, instance.__class__.__name__) @@ -876,7 +876,7 @@ class Query(object): @_generative() def add_entity(self, entity, alias=None): - """add a mapped entity to the list of result columns + """add a mapped entity to the list of result columns to be returned.""" if alias is not None: @@ -895,7 +895,7 @@ class Query(object): self.session = session def from_self(self, *entities): - """return a Query that selects from this Query's + """return a Query that selects from this Query's SELECT statement. \*entities - optional list of entities which will replace @@ -917,11 +917,11 @@ class Query(object): @_generative() def _from_selectable(self, fromclause): for attr in ( - '_statement', '_criterion', + '_statement', '_criterion', '_order_by', '_group_by', - '_limit', '_offset', - '_joinpath', '_joinpoint', - '_distinct', '_having', + '_limit', '_offset', + '_joinpath', '_joinpoint', + '_distinct', '_having', '_prefixes', ): self.__dict__.pop(attr, None) @@ -937,7 +937,7 @@ class Query(object): e.adapt_to_selectable(self, self._from_obj[0]) def values(self, *columns): - """Return an iterator yielding result tuples corresponding + """Return an iterator yielding result tuples corresponding to the given list of columns""" if not columns: @@ -950,7 +950,7 @@ class Query(object): _values = values def value(self, column): - """Return a scalar result corresponding to the given + """Return a scalar result corresponding to the given column expression.""" try: # Py3K @@ -975,7 +975,7 @@ class Query(object): filter(User.name.like('%ed%')).\\ order_by(Address.email) - # given *only* User.id==5, Address.email, and 'q', what + # given *only* User.id==5, Address.email, and 'q', what # would the *next* User in the result be ? subq = q.with_entities(Address.email).\\ order_by(None).\\ @@ -992,7 +992,7 @@ class Query(object): @_generative() def add_columns(self, *column): - """Add one or more column expressions to the list + """Add one or more column expressions to the list of result columns to be returned.""" self._entities = list(self._entities) @@ -1003,13 +1003,13 @@ class Query(object): # given arg is a FROM clause self._set_entity_selectables(self._entities[l:]) - @util.pending_deprecation("0.7", - ":meth:`.add_column` is superseded by :meth:`.add_columns`", + @util.pending_deprecation("0.7", + ":meth:`.add_column` is superseded by :meth:`.add_columns`", False) def add_column(self, column): """Add a column expression to the list of result columns to be returned. - Pending deprecation: :meth:`.add_column` will be superseded by + Pending deprecation: :meth:`.add_column` will be superseded by :meth:`.add_columns`. """ @@ -1068,13 +1068,13 @@ class Query(object): @_generative() def with_hint(self, selectable, text, dialect_name='*'): - """Add an indexing hint for the given entity or selectable to + """Add an indexing hint for the given entity or selectable to this :class:`.Query`. - Functionality is passed straight through to - :meth:`~sqlalchemy.sql.expression.Select.with_hint`, - with the addition that ``selectable`` can be a - :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class + Functionality is passed straight through to + :meth:`~sqlalchemy.sql.expression.Select.with_hint`, + with the addition that ``selectable`` can be a + :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class /etc. """ mapper, selectable, is_aliased_class = _entity_info(selectable) @@ -1085,7 +1085,7 @@ class Query(object): def execution_options(self, **kwargs): """ Set non-SQL options which take effect during execution. - The options are the same as those accepted by + The options are the same as those accepted by :meth:`.Connection.execution_options`. Note that the ``stream_results`` execution option is enabled @@ -1108,14 +1108,14 @@ class Query(object): ``FOR UPDATE`` (standard SQL, supported by most dialects) ``'update_nowait'`` - passes ``for_update='nowait'``, which - translates to ``FOR UPDATE NOWAIT`` (supported by Oracle, + translates to ``FOR UPDATE NOWAIT`` (supported by Oracle, PostgreSQL 8.1 upwards) ``'read'`` - passes ``for_update='read'``, which translates to - ``LOCK IN SHARE MODE`` (for MySQL), and ``FOR SHARE`` (for + ``LOCK IN SHARE MODE`` (for MySQL), and ``FOR SHARE`` (for PostgreSQL) - ``'read_nowait'`` - passes ``for_update='read_nowait'``, which + ``'read_nowait'`` - passes ``for_update='read_nowait'``, which translates to ``FOR SHARE NOWAIT`` (supported by PostgreSQL). .. versionadded:: 0.7.7 @@ -1126,7 +1126,7 @@ class Query(object): @_generative() def params(self, *args, **kwargs): - """add values for bind parameters which may have been + """add values for bind parameters which may have been specified in filter(). parameters may be specified using \**kwargs, or optionally a single @@ -1158,7 +1158,7 @@ class Query(object): session.query(MyClass).\\ filter(MyClass.name == 'some name', MyClass.id > 5) - The criterion is any SQL expression object applicable to the + The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced into SQL expression constructs via the :func:`.text` construct. @@ -1200,8 +1200,8 @@ class Query(object): session.query(MyClass).\\ filter_by(name = 'some name', id = 5) - The keyword expressions are extracted from the primary - entity of the query, or the last entity that was the + The keyword expressions are extracted from the primary + entity of the query, or the last entity that was the target of a call to :meth:`.Query.join`. See also: @@ -1216,15 +1216,15 @@ class Query(object): @_generative(_no_statement_condition, _no_limit_offset) def order_by(self, *criterion): - """apply one or more ORDER BY criterion to the query and return + """apply one or more ORDER BY criterion to the query and return the newly resulting ``Query`` - All existing ORDER BY settings can be suppressed by + All existing ORDER BY settings can be suppressed by passing ``None`` - this will suppress any ORDER BY configured on mappers as well. Alternatively, an existing ORDER BY setting on the Query - object can be entirely cancelled by passing ``False`` + object can be entirely cancelled by passing ``False`` as the value - use this before calling methods where an ORDER BY is invalid. @@ -1248,11 +1248,10 @@ class Query(object): @_generative(_no_statement_condition, _no_limit_offset) def group_by(self, *criterion): - """apply one or more GROUP BY criterion to the query and return + """apply one or more GROUP BY criterion to the query and return the newly resulting :class:`.Query`""" criterion = list(chain(*[_orm_columns(c) for c in criterion])) - criterion = self._adapt_col_list(criterion) if self._group_by is False: @@ -1266,15 +1265,15 @@ class Query(object): newly resulting :class:`.Query`. :meth:`having` is used in conjunction with :meth:`group_by`. - + HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: - + q = session.query(User.id).\\ join(User.addresses).\\ group_by(User.id).\\ having(func.count(Address.id) > 2) - + """ if isinstance(criterion, basestring): @@ -1310,7 +1309,7 @@ class Query(object): will nest on each ``union()``, and produces:: - SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION + SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y) UNION SELECT * FROM Z) Whereas:: @@ -1319,14 +1318,14 @@ class Query(object): produces:: - SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION + SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION SELECT * FROM Z) Note that many database backends do not allow ORDER BY to be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting - :class:`.Query` object will not render ORDER BY within + :class:`.Query` object will not render ORDER BY within its SELECT statement. """ @@ -1397,29 +1396,29 @@ class Query(object): **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, - with a relationship ``User.addresses`` representing a collection - of ``Address`` objects associated with each ``User``. The most common + with a relationship ``User.addresses`` representing a collection + of ``Address`` objects associated with each ``User``. The most common usage of :meth:`~.Query.join` is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) - Where above, the call to :meth:`~.Query.join` along ``User.addresses`` + Where above, the call to :meth:`~.Query.join` along ``User.addresses`` will result in SQL equivalent to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to :meth:`~.Query.join` as the *on clause*, that is, it indicates - how the "ON" portion of the JOIN should be constructed. For a + how the "ON" portion of the JOIN should be constructed. For a single-entity query such as the one above (i.e. we start by selecting only from - ``User`` and nothing else), the relationship can also be specified by its + ``User`` and nothing else), the relationship can also be specified by its string name:: q = session.query(User).join("addresses") - :meth:`~.Query.join` can also accommodate multiple + :meth:`~.Query.join` can also accommodate multiple "on clause" arguments to produce a chain of joins, such as below where a join across four related entities is constructed:: @@ -1436,17 +1435,17 @@ class Query(object): **Joins to a Target Entity or Selectable** A second form of :meth:`~.Query.join` allows any mapped entity - or core selectable construct as a target. In this usage, + or core selectable construct as a target. In this usage, :meth:`~.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) - The above calling form of :meth:`.join` will raise an error if - either there are no foreign keys between the two entities, or if + The above calling form of :meth:`.join` will raise an error if + either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the - above calling form, :meth:`~.Query.join` is called upon to + above calling form, :meth:`~.Query.join` is called upon to create the "on clause" automatically for us. The target can be any mapped entity or selectable, such as a :class:`.Table`:: @@ -1455,11 +1454,11 @@ class Query(object): **Joins to a Target with an ON Clause** The third calling form allows both the target entity as well - as the ON clause to be passed explicitly. Suppose for + as the ON clause to be passed explicitly. Suppose for example we wanted to join to ``Address`` twice, using - an alias the second time. We use :func:`~sqlalchemy.orm.aliased` + an alias the second time. We use :func:`~sqlalchemy.orm.aliased` to create a distinct alias of ``Address``, and join - to it using the ``target, onclause`` form, so that the + to it using the ``target, onclause`` form, so that the alias can be specified explicitly as the target along with the relationship to instruct how the ON clause should proceed:: @@ -1473,13 +1472,13 @@ class Query(object): Where above, the generated SQL would be similar to:: - SELECT user.* FROM user + SELECT user.* FROM user JOIN address ON user.id = address.user_id JOIN address AS address_1 ON user.id=address_1.user_id WHERE address.email_address = :email_address_1 AND address_1.email_address = :email_address_2 - The two-argument calling form of :meth:`~.Query.join` + The two-argument calling form of :meth:`~.Query.join` also allows us to construct arbitrary joins with SQL-oriented "on clause" expressions, not relying upon configured relationships at all. Any SQL expression can be passed as the ON clause @@ -1489,7 +1488,7 @@ class Query(object): q = session.query(User).join(Address, User.id==Address.user_id) .. versionchanged:: 0.7 - In SQLAlchemy 0.6 and earlier, the two argument form of + In SQLAlchemy 0.6 and earlier, the two argument form of :meth:`~.Query.join` requires the usage of a tuple: ``query(User).join((Address, User.id==Address.user_id))``\ . This calling form is accepted in 0.7 and further, though @@ -1500,9 +1499,9 @@ class Query(object): **Advanced Join Targeting and Adaption** - There is a lot of flexibility in what the "target" can be when using - :meth:`~.Query.join`. As noted previously, it also accepts - :class:`.Table` constructs and other selectables such as :func:`.alias` + There is a lot of flexibility in what the "target" can be when using + :meth:`~.Query.join`. As noted previously, it also accepts + :class:`.Table` constructs and other selectables such as :func:`.alias` and :func:`.select` constructs, with either the one or two-argument forms:: addresses_q = select([Address.user_id]).\\ @@ -1512,7 +1511,7 @@ class Query(object): q = session.query(User).\\ join(addresses_q, addresses_q.c.user_id==User.id) - :meth:`~.Query.join` also features the ability to *adapt* a + :meth:`~.Query.join` also features the ability to *adapt* a :meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target selectable. Below we construct a JOIN from ``User`` to a subquery against ``Address``, allowing the relationship denoted by ``User.addresses`` to *adapt* itself @@ -1526,12 +1525,12 @@ class Query(object): Producing SQL similar to:: - SELECT user.* FROM user + SELECT user.* FROM user JOIN ( - SELECT address.id AS id, - address.user_id AS user_id, - address.email_address AS email_address - FROM address + SELECT address.id AS id, + address.user_id AS user_id, + address.email_address AS email_address + FROM address WHERE address.email_address = :email_address_1 ) AS anon_1 ON user.id = anon_1.user_id @@ -1548,7 +1547,7 @@ class Query(object): cases where it's needed, using :meth:`~.Query.select_from`. Below we construct a query against ``Address`` but can still make usage of ``User.addresses`` as our ON clause by instructing - the :class:`.Query` to select first from the ``User`` + the :class:`.Query` to select first from the ``User`` entity:: q = session.query(Address).select_from(User).\\ @@ -1557,8 +1556,8 @@ class Query(object): Which will produce SQL similar to:: - SELECT address.* FROM user - JOIN address ON user.id=address.user_id + SELECT address.* FROM user + JOIN address ON user.id=address.user_id WHERE user.name = :name_1 **Constructing Aliases Anonymously** @@ -1572,8 +1571,8 @@ class Query(object): join("children", "children", aliased=True) When ``aliased=True`` is used, the actual "alias" construct - is not explicitly available. To work with it, methods such as - :meth:`.Query.filter` will adapt the incoming entity to + is not explicitly available. To work with it, methods such as + :meth:`.Query.filter` will adapt the incoming entity to the last join point:: q = session.query(Node).\\ @@ -1600,23 +1599,23 @@ class Query(object): reset_joinpoint().\\ filter(Node.name == 'parent 1) - For an example of ``aliased=True``, see the distribution + For an example of ``aliased=True``, see the distribution example :ref:`examples_xmlpersistence` which illustrates an XPath-like query system using algorithmic joins. - :param *props: A collection of one or more join conditions, - each consisting of a relationship-bound attribute or string - relationship name representing an "on clause", or a single + :param *props: A collection of one or more join conditions, + each consisting of a relationship-bound attribute or string + relationship name representing an "on clause", or a single target entity, or a tuple in the form of ``(target, onclause)``. A special two-argument calling form of the form ``target, onclause`` is also accepted. - :param aliased=False: If True, indicate that the JOIN target should be + :param aliased=False: If True, indicate that the JOIN target should be anonymously aliased. Subsequent calls to :class:`~.Query.filter` - and similar will adapt the incoming criterion to the target + and similar will adapt the incoming criterion to the target alias, until :meth:`~.Query.reset_joinpoint` is called. :param from_joinpoint=False: When using ``aliased=True``, a setting of True here will cause the join to be from the most recent - joined target, rather than starting back from the original + joined target, rather than starting back from the original FROM clauses of the query. See also: @@ -1627,7 +1626,7 @@ class Query(object): is used for inheritance relationships. :func:`.orm.join` - a standalone ORM-level join function, - used internally by :meth:`.Query.join`, which in previous + used internally by :meth:`.Query.join`, which in previous SQLAlchemy versions was the primary ORM-level joining interface. """ @@ -1636,8 +1635,8 @@ class Query(object): if kwargs: raise TypeError("unknown arguments: %s" % ','.join(kwargs.iterkeys())) - return self._join(props, - outerjoin=False, create_aliases=aliased, + return self._join(props, + outerjoin=False, create_aliases=aliased, from_joinpoint=from_joinpoint) def outerjoin(self, *props, **kwargs): @@ -1652,8 +1651,8 @@ class Query(object): if kwargs: raise TypeError("unknown arguments: %s" % ','.join(kwargs.iterkeys())) - return self._join(props, - outerjoin=True, create_aliases=aliased, + return self._join(props, + outerjoin=True, create_aliases=aliased, from_joinpoint=from_joinpoint) def _update_joinpoint(self, jp): @@ -1679,9 +1678,9 @@ class Query(object): self._reset_joinpoint() if len(keys) == 2 and \ - isinstance(keys[0], (expression.FromClause, + isinstance(keys[0], (expression.FromClause, type, AliasedClass)) and \ - isinstance(keys[1], (basestring, expression.ClauseElement, + isinstance(keys[1], (basestring, expression.ClauseElement, interfaces.PropComparator)): # detect 2-arg form of join and # convert to a tuple. @@ -1691,7 +1690,7 @@ class Query(object): if isinstance(arg1, tuple): # "tuple" form of join, multiple # tuples are accepted as well. The simpler - # "2-arg" form is preferred. May deprecate + # "2-arg" form is preferred. May deprecate # the "tuple" usage. arg1, arg2 = arg1 else: @@ -1765,11 +1764,11 @@ class Query(object): raise NotImplementedError("query.join(a==b) not supported.") self._join_left_to_right( - left_entity, - right_entity, onclause, + left_entity, + right_entity, onclause, outerjoin, create_aliases, prop) - def _join_left_to_right(self, left, right, + def _join_left_to_right(self, left, right, onclause, outerjoin, create_aliases, prop): """append a JOIN to the query's from clause.""" @@ -1785,12 +1784,12 @@ class Query(object): not create_aliases: raise sa_exc.InvalidRequestError( "Can't construct a join from %s to %s, they " - "are the same entity" % + "are the same entity" % (left, right)) right, right_is_aliased, onclause = self._prepare_right_side( right, onclause, - outerjoin, create_aliases, + outerjoin, create_aliases, prop) # if joining on a MapperProperty path, @@ -1805,11 +1804,11 @@ class Query(object): '_joinpoint_entity':right } - self._join_to_left(left, right, - right_is_aliased, + self._join_to_left(left, right, + right_is_aliased, onclause, outerjoin) - def _prepare_right_side(self, right, onclause, outerjoin, + def _prepare_right_side(self, right, onclause, outerjoin, create_aliases, prop): right_mapper, right_selectable, right_is_aliased = _entity_info(right) @@ -1860,11 +1859,11 @@ class Query(object): # until reset_joinpoint() is called. if need_adapter: self._filter_aliases = ORMAdapter(right, - equivalents=right_mapper and + equivalents=right_mapper and right_mapper._equivalent_columns or {}, chain_to=self._filter_aliases) - # if the onclause is a ClauseElement, adapt it with any + # if the onclause is a ClauseElement, adapt it with any # adapters that are in place right now if isinstance(onclause, expression.ClauseElement): onclause = self._adapt_clause(onclause, True, True) @@ -1877,7 +1876,7 @@ class Query(object): self._mapper_loads_polymorphically_with( right_mapper, ORMAdapter( - right, + right, equivalents=right_mapper._equivalent_columns ) ) @@ -1887,19 +1886,19 @@ class Query(object): def _join_to_left(self, left, right, right_is_aliased, onclause, outerjoin): left_mapper, left_selectable, left_is_aliased = _entity_info(left) - # this is an overly broad assumption here, but there's a + # this is an overly broad assumption here, but there's a # very wide variety of situations where we rely upon orm.join's # adaption to glue clauses together, with joined-table inheritance's # wide array of variables taking up most of the space. # Setting the flag here is still a guess, so it is a bug - # that we don't have definitive criterion to determine when - # adaption should be enabled (or perhaps that we're even doing the + # that we don't have definitive criterion to determine when + # adaption should be enabled (or perhaps that we're even doing the # whole thing the way we are here). join_to_left = not right_is_aliased and not left_is_aliased if self._from_obj and left_selectable is not None: replace_clause_index, clause = sql_util.find_join_source( - self._from_obj, + self._from_obj, left_selectable) if clause is not None: # the entire query's FROM clause is an alias of itself (i.e. @@ -1915,9 +1914,9 @@ class Query(object): join_to_left = False try: - clause = orm_join(clause, - right, - onclause, isouter=outerjoin, + clause = orm_join(clause, + right, + onclause, isouter=outerjoin, join_to_left=join_to_left) except sa_exc.ArgumentError, ae: raise sa_exc.InvalidRequestError( @@ -1947,7 +1946,7 @@ class Query(object): "Could not find a FROM clause to join from") try: - clause = orm_join(clause, right, onclause, + clause = orm_join(clause, right, onclause, isouter=outerjoin, join_to_left=join_to_left) except sa_exc.ArgumentError, ae: raise sa_exc.InvalidRequestError( @@ -1966,7 +1965,7 @@ class Query(object): This method is usually used in conjunction with the ``aliased=True`` feature of the :meth:`~.Query.join` - method. See the example in :meth:`~.Query.join` for how + method. See the example in :meth:`~.Query.join` for how this is used. """ @@ -1977,7 +1976,7 @@ class Query(object): """Set the FROM clause of this :class:`.Query` explicitly. Sending a mapped class or entity here effectively replaces the - "left edge" of any calls to :meth:`~.Query.join`, when no + "left edge" of any calls to :meth:`~.Query.join`, when no joinpoint is otherwise established - usually, the default "join point" is the leftmost entity in the :class:`~.Query` object's list of entities to be selected. @@ -1985,7 +1984,7 @@ class Query(object): Mapped entities or plain :class:`~.Table` or other selectables can be sent here which will form the default FROM clause. - See the example in :meth:`~.Query.join` for a typical + See the example in :meth:`~.Query.join` for a typical usage of :meth:`~.Query.select_from`. """ @@ -2072,21 +2071,21 @@ class Query(object): construct. """ - if not criterion: - self._distinct = True - else: + if not criterion: + self._distinct = True + else: criterion = self._adapt_col_list(criterion) if isinstance(self._distinct, list): self._distinct += criterion - else: - self._distinct = criterion + else: + self._distinct = criterion @_generative() def prefix_with(self, *prefixes): """Apply the prefixes to the query and return the newly resulting ``Query``. - :param \*prefixes: optional prefixes, typically strings, + :param \*prefixes: optional prefixes, typically strings, not using any commas. In particular is useful for MySQL keywords. e.g.:: @@ -2097,7 +2096,7 @@ class Query(object): Would render:: - SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name + SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name FROM users .. versionadded:: 0.7.7 @@ -2131,7 +2130,7 @@ class Query(object): if isinstance(statement, basestring): statement = sql.text(statement) - if not isinstance(statement, + if not isinstance(statement, (expression._TextClause, expression._SelectBase)): raise sa_exc.ArgumentError( @@ -2141,12 +2140,12 @@ class Query(object): self._statement = statement def first(self): - """Return the first result of this ``Query`` or + """Return the first result of this ``Query`` or None if the result doesn't contain any row. first() applies a limit of one within the generated SQL, so that - only one primary entity row is generated on the server side - (note this may consist of multiple result rows if join-loaded + only one primary entity row is generated on the server side + (note this may consist of multiple result rows if join-loaded collections are present). Calling ``first()`` results in an execution of the underlying query. @@ -2164,22 +2163,22 @@ class Query(object): def one(self): """Return exactly one result or raise an exception. - Raises ``sqlalchemy.orm.exc.NoResultFound`` if the query selects - no rows. Raises ``sqlalchemy.orm.exc.MultipleResultsFound`` + Raises ``sqlalchemy.orm.exc.NoResultFound`` if the query selects + no rows. Raises ``sqlalchemy.orm.exc.MultipleResultsFound`` if multiple object identities are returned, or if multiple rows are returned for a query that does not return object identities. Note that an entity query, that is, one which selects one or more mapped classes as opposed to individual column attributes, - may ultimately represent many rows but only one row of + may ultimately represent many rows but only one row of unique entity or entities - this is a successful result for one(). Calling ``one()`` results in an execution of the underlying query. .. versionchanged:: 0.6 - ``one()`` fully fetches all results instead of applying - any kind of limit, so that the "unique"-ing of entities does not + ``one()`` fully fetches all results instead of applying + any kind of limit, so that the "unique"-ing of entities does not conceal multiple object identities. """ @@ -2246,7 +2245,7 @@ class Query(object): @property def column_descriptions(self): - """Return metadata about the columns which would be + """Return metadata about the columns which would be returned by this :class:`.Query`. Format is a list of dictionaries:: @@ -2362,11 +2361,11 @@ class Query(object): .. versionchanged:: 0.7 The above scheme is newly refined as of 0.7b3. - For fine grained control over specific columns + For fine grained control over specific columns to count, to skip the usage of a subquery or otherwise control of the FROM clause, or to use other aggregate functions, - use :attr:`~sqlalchemy.sql.expression.func` + use :attr:`~sqlalchemy.sql.expression.func` expressions in conjunction with :meth:`~.Session.query`, i.e.:: @@ -2413,7 +2412,7 @@ class Query(object): ``'evaluate'`` - Evaluate the query's criteria in Python straight on the objects in the session. If evaluation of the criteria isn't - implemented, an error is raised. In that case you probably + implemented, an error is raised. In that case you probably want to use the 'fetch' strategy as a fallback. The expression evaluator currently doesn't account for differing @@ -2428,7 +2427,7 @@ class Query(object): state of dependent objects subject to delete or delete-orphan cascade to be correctly represented. - Note that the :meth:`.MapperEvents.before_delete` and + Note that the :meth:`.MapperEvents.before_delete` and :meth:`.MapperEvents.after_delete` events are **not** invoked from this method. It instead invokes :meth:`.SessionEvents.after_bulk_delete`. @@ -2480,7 +2479,7 @@ class Query(object): or call expire_all()) in order for the state of dependent objects subject foreign key cascade to be correctly represented. - Note that the :meth:`.MapperEvents.before_update` and + Note that the :meth:`.MapperEvents.before_update` and :meth:`.MapperEvents.after_update` events are **not** invoked from this method. It instead invokes :meth:`.SessionEvents.after_bulk_update`. @@ -2489,7 +2488,7 @@ class Query(object): #TODO: value keys need to be mapped to corresponding sql cols and # instr.attr.s to string keys - #TODO: updates of manytoone relationships need to be converted to + #TODO: updates of manytoone relationships need to be converted to # fk assignments #TODO: cascades need handling. @@ -2529,11 +2528,11 @@ class Query(object): strategy(*rec[1:]) if context.from_clause: - # "load from explicit FROMs" mode, + # "load from explicit FROMs" mode, # i.e. when select_from() or join() is used context.froms = list(context.from_clause) else: - # "load from discrete FROMs" mode, + # "load from discrete FROMs" mode, # i.e. when each _MappedEntity has its own FROM context.froms = context.froms @@ -2558,7 +2557,7 @@ class Query(object): return context def _compound_eager_statement(self, context): - # for eager joins present and LIMIT/OFFSET/DISTINCT, + # for eager joins present and LIMIT/OFFSET/DISTINCT, # wrap the query inside a select, # then append eager joins onto that @@ -2578,7 +2577,7 @@ class Query(object): context.whereclause, from_obj=context.froms, use_labels=context.labels, - # TODO: this order_by is only needed if + # TODO: this order_by is only needed if # LIMIT/OFFSET is present in self._select_args, # else the application on the outside is enough order_by=context.order_by, @@ -2598,17 +2597,17 @@ class Query(object): context.adapter = sql_util.ColumnAdapter(inner, equivs) statement = sql.select( - [inner] + context.secondary_columns, - for_update=context.for_update, + [inner] + context.secondary_columns, + for_update=context.for_update, use_labels=context.labels) from_clause = inner for eager_join in context.eager_joins.values(): # EagerLoader places a 'stop_on' attribute on the join, - # giving us a marker as to where the "splice point" of + # giving us a marker as to where the "splice point" of # the join should be from_clause = sql_util.splice_joins( - from_clause, + from_clause, eager_join, eager_join.stop_on) statement.append_from(from_clause) @@ -2630,7 +2629,7 @@ class Query(object): if self._distinct and context.order_by: order_by_col_expr = list( chain(*[ - sql_util.unwrap_order_by(o) + sql_util.unwrap_order_by(o) for o in context.order_by ]) ) @@ -2662,12 +2661,12 @@ class Query(object): def _adjust_for_single_inheritance(self, context): """Apply single-table-inheritance filtering. - + For all distinct single-table-inheritance mappers represented in the columns clause of this query, add criterion to the WHERE clause of the given QueryContext such that only the appropriate subtypes are selected from the total results. - + """ for (ext_info, adapter) in self._mapper_adapter_map.values(): if ext_info.entity in self._join_entities: @@ -2677,7 +2676,7 @@ class Query(object): if adapter: single_crit = adapter.traverse(single_crit) single_crit = self._adapt_clause(single_crit, False, False) - context.whereclause = sql.and_(context.whereclause, + context.whereclause = sql.and_(context.whereclause, single_crit) def __str__(self): @@ -2728,7 +2727,7 @@ class _MapperEntity(_QueryEntity): self._label_name = self.mapper.class_.__name__ self.path = self.entity_zero._sa_path_registry - def set_with_polymorphic(self, query, cls_or_mappers, + def set_with_polymorphic(self, query, cls_or_mappers, selectable, polymorphic_on): if self.is_aliased_class: raise NotImplementedError( @@ -2746,8 +2745,8 @@ class _MapperEntity(_QueryEntity): self._polymorphic_discriminator = polymorphic_on self.selectable = from_obj - query._mapper_loads_polymorphically_with(self.mapper, - sql_util.ColumnAdapter(from_obj, + query._mapper_loads_polymorphically_with(self.mapper, + sql_util.ColumnAdapter(from_obj, self.mapper._equivalent_columns)) filter_fn = id @@ -2800,7 +2799,7 @@ class _MapperEntity(_QueryEntity): elif not adapter: adapter = context.adapter - # polymorphic mappers which have concrete tables in + # polymorphic mappers which have concrete tables in # their hierarchy usually # require row aliasing unconditionally. if not adapter and self.mapper._requires_row_aliasing: @@ -2811,7 +2810,7 @@ class _MapperEntity(_QueryEntity): if self.primary_entity: _instance = loading.instance_processor( self.mapper, - context, + context, self.path, adapter, only_load_props=query._only_load_props, @@ -2822,7 +2821,7 @@ class _MapperEntity(_QueryEntity): else: _instance = loading.instance_processor( self.mapper, - context, + context, self.path, adapter, polymorphic_discriminator= @@ -2967,12 +2966,12 @@ class _ColumnEntity(_QueryEntity): def adapt_to_selectable(self, query, sel): c = _ColumnEntity(query, sel.corresponding_column(self.column)) - c._label_name = self._label_name + c._label_name = self._label_name c.entity_zero = self.entity_zero c.entities = self.entities def setup_entity(self, ext_info, aliased_adapter): - if 'selectable' not in self.__dict__: + if 'selectable' not in self.__dict__: self.selectable = ext_info.selectable self.froms.add(ext_info.selectable) diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py index ea0e89caf..2b846832e 100644 --- a/lib/sqlalchemy/orm/state.py +++ b/lib/sqlalchemy/orm/state.py @@ -13,7 +13,7 @@ defines a large part of the ORM's interactivity. import weakref from .. import util -from . import exc as orm_exc, attributes, util as orm_util +from . import exc as orm_exc, attributes, util as orm_util, interfaces from .attributes import ( PASSIVE_NO_RESULT, SQL_OK, NEVER_SET, ATTR_WAS_SET, NO_VALUE,\ @@ -24,7 +24,7 @@ instrumentation = util.importlater("sqlalchemy.orm", "instrumentation") mapperlib = util.importlater("sqlalchemy.orm", "mapperlib") -class InstanceState(object): +class InstanceState(interfaces._InspectionAttr): """tracks state information at the instance level.""" session_id = None @@ -39,6 +39,8 @@ class InstanceState(object): deleted = False _load_pending = False + is_instance = True + def __init__(self, obj, manager): self.class_ = obj.__class__ self.manager = manager diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index de55c8991..03af1ad76 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -7,7 +7,7 @@ from .. import sql, util, event, exc as sa_exc, inspection from ..sql import expression, util as sql_util, operators -from .interfaces import PropComparator, MapperProperty +from .interfaces import PropComparator, MapperProperty, _InspectionAttr from itertools import chain from . import attributes, exc import re @@ -31,15 +31,15 @@ class CascadeOptions(frozenset): def __new__(cls, arg): values = set([ - c for c + c for c in re.split('\s*,\s*', arg or "") if c ]) if values.difference(cls._allowed_cascades): raise sa_exc.ArgumentError( - "Invalid cascade option(s): %s" % - ", ".join([repr(x) for x in + "Invalid cascade option(s): %s" % + ", ".join([repr(x) for x in sorted( values.difference(cls._allowed_cascades) )]) @@ -99,12 +99,12 @@ def polymorphic_union(table_map, typecolname, aliasname='p_union', cast_nulls=Tr See :ref:`concrete_inheritance` for an example of how this is used. - :param table_map: mapping of polymorphic identities to + :param table_map: mapping of polymorphic identities to :class:`.Table` objects. - :param typecolname: string name of a "discriminator" column, which will be + :param typecolname: string name of a "discriminator" column, which will be derived from the query, producing the polymorphic identity for each row. If ``None``, no polymorphic discriminator is generated. - :param aliasname: name of the :func:`~sqlalchemy.sql.expression.alias()` + :param aliasname: name of the :func:`~sqlalchemy.sql.expression.alias()` construct generated. :param cast_nulls: if True, non-existent columns, which are represented as labeled NULLs, will be passed into CAST. This is a legacy behavior that is problematic @@ -118,7 +118,7 @@ def polymorphic_union(table_map, typecolname, aliasname='p_union', cast_nulls=Tr for key in table_map.keys(): table = table_map[key] - # mysql doesnt like selecting from a select; + # mysql doesnt like selecting from a select; # make it an alias of the select if isinstance(table, sql.Select): table = table.alias() @@ -216,14 +216,14 @@ class ORMAdapter(sql_util.ColumnAdapter): and the AliasedClass if any is referenced. """ - def __init__(self, entity, equivalents=None, + def __init__(self, entity, equivalents=None, chain_to=None, adapt_required=False): self.mapper, selectable, is_aliased_class = _entity_info(entity) if is_aliased_class: self.aliased_class = entity else: self.aliased_class = None - sql_util.ColumnAdapter.__init__(self, selectable, + sql_util.ColumnAdapter.__init__(self, selectable, equivalents, chain_to, adapt_required=adapt_required) @@ -253,9 +253,9 @@ class PathRegistry(object): The path structure has a limited amount of caching, where each "root" ultimately pulls from a fixed registry associated with - the first mapper, that also contains elements for each of its - property keys. However paths longer than two elements, which - are the exception rather than the rule, are generated on an + the first mapper, that also contains elements for each of its + property keys. However paths longer than two elements, which + are the exception rather than the rule, are generated on an as-needed basis. """ @@ -290,7 +290,7 @@ class PathRegistry(object): def serialize(self): path = self.path return zip( - [m.class_ for m in [path[i] for i in range(0, len(path), 2)]], + [m.class_ for m in [path[i] for i in range(0, len(path), 2)]], [path[i] for i in range(1, len(path), 2)] + [None] ) @@ -391,7 +391,7 @@ class AliasedClass(object): The resulting object is an instance of :class:`.AliasedClass`, however it implements a ``__getattribute__()`` scheme which will proxy attribute access to that of the ORM class being aliased. All classmethods - on the mapped entity should also be available here, including + on the mapped entity should also be available here, including hybrids created with the :ref:`hybrids_toplevel` extension, which will receive the :class:`.AliasedClass` as the "class" argument when classmethods are called. @@ -399,17 +399,18 @@ class AliasedClass(object): :param cls: ORM mapped entity which will be "wrapped" around an alias. :param alias: a selectable, such as an :func:`.alias` or :func:`.select` construct, which will be rendered in place of the mapped table of the - ORM entity. If left as ``None``, an ordinary :class:`.Alias` of the + ORM entity. If left as ``None``, an ordinary :class:`.Alias` of the ORM entity's mapped table will be generated. :param name: A name which will be applied both to the :class:`.Alias` if one is generated, as well as the name present in the "named tuple" returned by the :class:`.Query` object when results are returned. :param adapt_on_names: if True, more liberal "matching" will be used when - mapping the mapped columns of the ORM entity to those of the given selectable - - a name-based match will be performed if the given selectable doesn't - otherwise have a column that corresponds to one on the entity. The - use case for this is when associating an entity with some derived - selectable such as one that uses aggregate functions:: + mapping the mapped columns of the ORM entity to those of the + given selectable - a name-based match will be performed if the + given selectable doesn't otherwise have a column that corresponds + to one on the entity. The use case for this is when associating + an entity with some derived selectable such as one that uses + aggregate functions:: class UnitPrice(Base): __tablename__ = 'unit_price' @@ -421,43 +422,52 @@ class AliasedClass(object): func.sum(UnitPrice.price).label('price') ).group_by(UnitPrice.unit_id).subquery() - aggregated_unit_price = aliased(UnitPrice, alias=aggregated_unit_price, adapt_on_names=True) + aggregated_unit_price = aliased(UnitPrice, + alias=aggregated_unit_price, adapt_on_names=True) - Above, functions on ``aggregated_unit_price`` which - refer to ``.price`` will return the - ``fund.sum(UnitPrice.price).label('price')`` column, - as it is matched on the name "price". Ordinarily, the "price" function wouldn't - have any "column correspondence" to the actual ``UnitPrice.price`` column - as it is not a proxy of the original. + Above, functions on ``aggregated_unit_price`` which refer to + ``.price`` will return the + ``fund.sum(UnitPrice.price).label('price')`` column, as it is + matched on the name "price". Ordinarily, the "price" function + wouldn't have any "column correspondence" to the actual + ``UnitPrice.price`` column as it is not a proxy of the original. .. versionadded:: 0.7.3 """ - def __init__(self, cls, alias=None, - name=None, + def __init__(self, cls, alias=None, + name=None, adapt_on_names=False, with_polymorphic_mappers=(), with_polymorphic_discriminator=None): - self.__mapper = _class_to_mapper(cls) - self.__target = self.__mapper.class_ - self.__adapt_on_names = adapt_on_names + mapper = _class_to_mapper(cls) if alias is None: - alias = self.__mapper._with_polymorphic_selectable.alias( - name=name) + alias = mapper._with_polymorphic_selectable.alias(name=name) + self._aliased_insp = AliasedInsp( + mapper, + alias, + name, + with_polymorphic_mappers, + with_polymorphic_discriminator + ) + self._setup(self._aliased_insp, adapt_on_names) + + def _setup(self, aliased_insp, adapt_on_names): + self.__adapt_on_names = adapt_on_names + mapper = aliased_insp.mapper + alias = aliased_insp.selectable + self.__target = mapper.class_ + self.__adapt_on_names = adapt_on_names self.__adapter = sql_util.ClauseAdapter(alias, - equivalents=self.__mapper._equivalent_columns, + equivalents=mapper._equivalent_columns, adapt_on_names=self.__adapt_on_names) - self.__alias = alias - self.__with_polymorphic_mappers = with_polymorphic_mappers - self.__with_polymorphic_discriminator = \ - with_polymorphic_discriminator - for poly in with_polymorphic_mappers: - setattr(self, poly.class_.__name__, + for poly in aliased_insp.with_polymorphic_mappers: + setattr(self, poly.class_.__name__, AliasedClass(poly.class_, alias)) # used to assign a name to the RowTuple object # returned by Query. - self._sa_label_name = name + self._sa_label_name = aliased_insp.name self.__name__ = 'AliasedClass_' + str(self.__target) @util.memoized_property @@ -466,45 +476,41 @@ class AliasedClass(object): def __getstate__(self): return { - 'mapper':self.__mapper, - 'alias':self.__alias, - 'name':self._sa_label_name, - 'adapt_on_names':self.__adapt_on_names, + 'mapper': self._aliased_insp.mapper, + 'alias': self._aliased_insp.selectable, + 'name': self._aliased_insp.name, + 'adapt_on_names': self.__adapt_on_names, 'with_polymorphic_mappers': - self.__with_polymorphic_mappers, + self._aliased_insp.with_polymorphic_mappers, 'with_polymorphic_discriminator': - self.__with_polymorphic_discriminator + self._aliased_insp.polymorphic_on } def __setstate__(self, state): - self.__mapper = state['mapper'] - self.__target = self.__mapper.class_ - self.__adapt_on_names = state['adapt_on_names'] - alias = state['alias'] - self.__adapter = sql_util.ClauseAdapter(alias, - equivalents=self.__mapper._equivalent_columns, - adapt_on_names=self.__adapt_on_names) - self.__alias = alias - self.__with_polymorphic_mappers = \ - state.get('with_polymorphic_mappers') - self.__with_polymorphic_discriminator = \ - state.get('with_polymorphic_discriminator') - name = state['name'] - self._sa_label_name = name - self.__name__ = 'AliasedClass_' + str(self.__target) + self._aliased_insp = AliasedInsp( + state['mapper'], + state['alias'], + state['name'], + state.get('with_polymorphic_mappers'), + state.get('with_polymorphic_discriminator') + ) + self._setup(self._aliased_insp, state['adapt_on_names']) def __adapt_element(self, elem): return self.__adapter.traverse(elem).\ _annotate({ - 'parententity': self, - 'parentmapper':self.__mapper} + 'parententity': self, + 'parentmapper': self._aliased_insp.mapper} ) def __adapt_prop(self, existing, key): comparator = existing.comparator.adapted(self.__adapt_element) - queryattr = attributes.QueryableAttribute(self, key, - impl=existing.impl, parententity=self, comparator=comparator) + queryattr = attributes.QueryableAttribute( + self, key, + impl=existing.impl, + parententity=self, + comparator=comparator) setattr(self, key, queryattr) return queryattr @@ -539,6 +545,19 @@ class AliasedClass(object): return '<AliasedClass at 0x%x; %s>' % ( id(self), self.__target.__name__) +AliasedInsp = util.namedtuple("AliasedInsp", [ + "mapper", + "selectable", + "name", + "with_polymorphic_mappers", + "polymorphic_on" + ]) + +class AliasedInsp(_InspectionAttr, AliasedInsp): + is_aliased_class = True + +inspection._inspects(AliasedClass)(lambda target: target._aliased_insp) + def aliased(element, alias=None, name=None, adapt_on_names=False): if isinstance(element, expression.FromClause): if adapt_on_names: @@ -547,10 +566,10 @@ def aliased(element, alias=None, name=None, adapt_on_names=False): ) return element.alias(name) else: - return AliasedClass(element, alias=alias, + return AliasedClass(element, alias=alias, name=name, adapt_on_names=adapt_on_names) -def with_polymorphic(base, classes, selectable=False, +def with_polymorphic(base, classes, selectable=False, polymorphic_on=None, aliased=False, innerjoin=False): """Produce an :class:`.AliasedClass` construct which specifies @@ -595,8 +614,8 @@ def with_polymorphic(base, classes, selectable=False, :param polymorphic_on: a column to be used as the "discriminator" column for the given selectable. If not given, the polymorphic_on - attribute of the base classes' mapper will be used, if any. This - is useful for mappings that don't have polymorphic loading + attribute of the base classes' mapper will be used, if any. This + is useful for mappings that don't have polymorphic loading behavior by default. :param innerjoin: if True, an INNER JOIN will be used. This should @@ -604,12 +623,13 @@ def with_polymorphic(base, classes, selectable=False, """ primary_mapper = _class_to_mapper(base) mappers, selectable = primary_mapper.\ - _with_polymorphic_args(classes, selectable, innerjoin=innerjoin) + _with_polymorphic_args(classes, selectable, + innerjoin=innerjoin) if aliased: selectable = selectable.alias() - return AliasedClass(base, - selectable, - with_polymorphic_mappers=mappers, + return AliasedClass(base, + selectable, + with_polymorphic_mappers=mappers, with_polymorphic_discriminator=polymorphic_on) @@ -620,7 +640,7 @@ def _orm_annotate(element, exclude=None): Elements within the exclude collection will be cloned but not annotated. """ - return sql_util._deep_annotate(element, {'_orm_adapt':True}, exclude) + return sql_util._deep_annotate(element, {'_orm_adapt': True}, exclude) def _orm_deannotate(element): """Remove annotations that link a column to a particular mapping. @@ -631,7 +651,7 @@ def _orm_deannotate(element): """ - return sql_util._deep_deannotate(element, + return sql_util._deep_deannotate(element, values=("_orm_adapt", "parententity") ) @@ -643,7 +663,7 @@ class _ORMJoin(expression.Join): __visit_name__ = expression.Join.__visit_name__ - def __init__(self, left, right, onclause=None, + def __init__(self, left, right, onclause=None, isouter=False, join_to_left=True): adapt_from = None @@ -720,8 +740,8 @@ def join(left, right, onclause=None, isouter=False, join_to_left=True): as its functionality is encapsulated within that of the :meth:`.Query.join` method, which features a significant amount of automation beyond :func:`.orm.join` - by itself. Explicit usage of :func:`.orm.join` - with :class:`.Query` involves usage of the + by itself. Explicit usage of :func:`.orm.join` + with :class:`.Query` involves usage of the :meth:`.Query.select_from` method, as in:: from sqlalchemy.orm import join @@ -729,7 +749,7 @@ def join(left, right, onclause=None, isouter=False, join_to_left=True): select_from(join(User, Address, User.addresses)).\\ filter(Address.email_address=='foo@bar.com') - In modern SQLAlchemy the above join can be written more + In modern SQLAlchemy the above join can be written more succinctly as:: session.query(User).\\ @@ -759,12 +779,12 @@ def with_parent(instance, prop): The SQL rendered is the same as that rendered when a lazy loader would fire off from the given parent on that attribute, meaning - that the appropriate state is taken from the parent object in + that the appropriate state is taken from the parent object in Python without the need to render joins to the parent table in the rendered statement. .. versionchanged:: 0.6.4 - This method accepts parent instances in all + This method accepts parent instances in all persistence states, including transient, persistent, and detached. Only the requisite primary key/foreign key attributes need to be populated. Previous versions didn't work with transient @@ -775,8 +795,8 @@ def with_parent(instance, prop): :param property: String property name, or class-bound attribute, which indicates - what relationship from the instance should be used to reconcile the - parent/child relationship. + what relationship from the instance should be used to reconcile the + parent/child relationship. """ if isinstance(prop, basestring): @@ -785,112 +805,44 @@ def with_parent(instance, prop): elif isinstance(prop, attributes.QueryableAttribute): prop = prop.property - return prop.compare(operators.eq, - instance, + return prop.compare(operators.eq, + instance, value_is_parent=True) -extended_entity_info = util.namedtuple("extended_entity_info", [ - "entity", - "mapper", - "selectable", - "is_aliased_class", - "with_polymorphic_mappers", - "with_polymorphic_discriminator" -]) -def _extended_entity_info(entity, compile=True): - if isinstance(entity, AliasedClass): - return extended_entity_info( - entity, - entity._AliasedClass__mapper, \ - entity._AliasedClass__alias, \ - True, \ - entity._AliasedClass__with_polymorphic_mappers, \ - entity._AliasedClass__with_polymorphic_discriminator - ) - - if isinstance(entity, mapperlib.Mapper): - mapper = entity - - elif isinstance(entity, type): - class_manager = attributes.manager_of_class(entity) - - if class_manager is None: - return extended_entity_info(entity, None, entity, False, [], None) - - mapper = class_manager.mapper - else: - return extended_entity_info(entity, None, entity, False, [], None) - - if compile and mapperlib.module._new_mappers: - mapperlib.configure_mappers() - return extended_entity_info( - entity, - mapper, \ - mapper._with_polymorphic_selectable, \ - False, \ - mapper._with_polymorphic_mappers, \ - mapper.polymorphic_on - ) - -def _entity_info(entity, compile=True): - """Return mapping information given a class, mapper, or AliasedClass. - - Returns 3-tuple of: mapper, mapped selectable, boolean indicating if this - is an aliased() construct. - - If the given entity is not a mapper, mapped class, or aliased construct, - returns None, the entity, False. This is typically used to allow - unmapped selectables through. - - """ - return _extended_entity_info(entity, compile)[1:4] - -def _entity_descriptor(entity, key): - """Return a class attribute given an entity and string name. - - May return :class:`.InstrumentedAttribute` or user-defined - attribute. - - """ - if isinstance(entity, expression.FromClause): - description = entity - entity = entity.c - elif not isinstance(entity, (AliasedClass, type)): - description = entity = entity.class_ - else: - description = entity - - try: - return getattr(entity, key) - except AttributeError: - raise sa_exc.InvalidRequestError( - "Entity '%s' has no property '%s'" % - (description, key) - ) - -def _orm_columns(entity): - mapper, selectable, is_aliased_class = _entity_info(entity) - if isinstance(selectable, expression.Selectable): - return [c for c in selectable.c] - else: - return [selectable] - -def _orm_selectable(entity): - mapper, selectable, is_aliased_class = _entity_info(entity) - return selectable - def _attr_as_key(attr): if hasattr(attr, 'key'): return attr.key else: return expression._column_as_key(attr) -def _is_aliased_class(entity): - return isinstance(entity, AliasedClass) _state_mapper = util.dottedgetter('manager.mapper') +@inspection._inspects(object) +def _inspect_mapped_object(instance): + try: + return attributes.instance_state(instance) + # TODO: whats the py-2/3 syntax to catch two + # different kinds of exceptions at once ? + except exc.UnmappedClassError: + return None + except exc.NO_STATE: + return None + +@inspection._inspects(type) +def _inspect_mapped_class(class_, configure=False): + try: + class_manager = attributes.manager_of_class(class_) + mapper = class_manager.mapper + if configure and mapperlib.module._new_mappers: + mapperlib.configure_mappers() + return mapper + + except exc.NO_STATE: + return None + + def object_mapper(instance): """Given an object, return the primary Mapper associated with the object instance. @@ -904,101 +856,167 @@ def object_mapper(instance): """ return object_state(instance).mapper -@inspection._inspects(object) def object_state(instance): """Given an object, return the primary Mapper associated with the object instance. Raises UnmappedInstanceError if no mapping is configured. - This function is available via the inspection system as:: + Equivalent functionality is available via the inspection system as:: inspect(instance) + Using the inspection system will raise plain + :class:`.InvalidRequestError` if the instance is not part of + a mapping. + """ - try: - return attributes.instance_state(instance) - # TODO: whats the py-2/3 syntax to catch two - # different kinds of exceptions at once ? - except exc.UnmappedClassError: - raise exc.UnmappedInstanceError(instance) - except exc.NO_STATE: + state = _inspect_mapped_object(instance) + if state is None: raise exc.UnmappedInstanceError(instance) + else: + return state - -@inspection._inspects(type) -def class_mapper(class_, compile=True): - """Given a class, return the primary :class:`.Mapper` associated +def class_mapper(class_, configure=True): + """Given a class, return the primary :class:`.Mapper` associated with the key. Raises :class:`.UnmappedClassError` if no mapping is configured on the given class, or :class:`.ArgumentError` if a non-class object is passed. - This function is available via the inspection system as:: + Equivalent functionality is available via the inspection system as:: inspect(some_mapped_class) - """ + Using the inspection system will raise plain + :class:`.InvalidRequestError` if the class is not mapped. - try: - class_manager = attributes.manager_of_class(class_) - mapper = class_manager.mapper - - except exc.NO_STATE: - if not isinstance(class_, type): - raise sa_exc.ArgumentError("Class object expected, got '%r'." % class_) + """ + mapper = _inspect_mapped_class(class_, configure=configure) + if mapper is None: + if not isinstance(class_, type): + raise sa_exc.ArgumentError( + "Class object expected, got '%r'." % class_) raise exc.UnmappedClassError(class_) + else: + return mapper - if compile and mapperlib.module._new_mappers: - mapperlib.configure_mappers() - return mapper - -def _class_to_mapper(class_or_mapper, compile=True): - if _is_aliased_class(class_or_mapper): - return class_or_mapper._AliasedClass__mapper - - elif isinstance(class_or_mapper, type): - try: - class_manager = attributes.manager_of_class(class_or_mapper) - mapper = class_manager.mapper - except exc.NO_STATE: - raise exc.UnmappedClassError(class_or_mapper) - elif isinstance(class_or_mapper, mapperlib.Mapper): - mapper = class_or_mapper +def _class_to_mapper(class_or_mapper): + insp = inspection.inspect(class_or_mapper, False) + if insp is not None: + return insp.mapper else: raise exc.UnmappedClassError(class_or_mapper) - if compile and mapperlib.module._new_mappers: - mapperlib.configure_mappers() - return mapper +def _mapper_or_none(entity): + """Return the :class:`.Mapper` for the given class or None if the + class is not mapped.""" -def has_identity(object): - state = attributes.instance_state(object) - return state.has_identity + insp = inspection.inspect(entity, False) + if insp is not None: + return insp.mapper + else: + return None -def _is_mapped_class(cls): - """Return True if the given object is a mapped class, +def _is_mapped_class(entity): + """Return True if the given object is a mapped class, :class:`.Mapper`, or :class:`.AliasedClass`.""" - if isinstance(cls, (AliasedClass, mapperlib.Mapper)): - return True - if isinstance(cls, expression.ClauseElement): - return False - if isinstance(cls, type): - manager = attributes.manager_of_class(cls) - return manager and _INSTRUMENTOR in manager.info - return False + insp = inspection.inspect(entity, False) + return insp is not None and \ + hasattr(insp, "mapper") and \ + ( + insp.is_mapper + or insp.is_aliased_class + ) -def _mapper_or_none(cls): - """Return the :class:`.Mapper` for the given class or None if the - class is not mapped.""" - manager = attributes.manager_of_class(cls) - if manager is not None and _INSTRUMENTOR in manager.info: - return manager.info[_INSTRUMENTOR] +def _is_aliased_class(entity): + insp = inspection.inspect(entity, False) + return insp is not None and \ + getattr(insp, "is_aliased_class", False) + +extended_entity_info = util.namedtuple("extended_entity_info", [ + "entity", + "mapper", + "selectable", + "is_aliased_class", + "with_polymorphic_mappers", + "with_polymorphic_discriminator" +]) +def _extended_entity_info(entity): + insp = inspection.inspect(entity) + return extended_entity_info( + entity, + insp.mapper if not insp.is_selectable else None, + insp.selectable, + insp.is_aliased_class if not insp.is_selectable else False, + insp.with_polymorphic_mappers if not insp.is_selectable else None, + insp.polymorphic_on if not insp.is_selectable else None + ) + +def _entity_info(entity, compile=True): + """Return mapping information given a class, mapper, or AliasedClass. + + Returns 3-tuple of: mapper, mapped selectable, boolean indicating if this + is an aliased() construct. + + If the given entity is not a mapper, mapped class, or aliased construct, + returns None, the entity, False. This is typically used to allow + unmapped selectables through. + + """ + insp = inspection.inspect(entity) + return \ + insp.mapper if not insp.is_selectable else None,\ + insp.selectable,\ + insp.is_aliased_class if not insp.is_selectable else False, + + +def _entity_descriptor(entity, key): + """Return a class attribute given an entity and string name. + + May return :class:`.InstrumentedAttribute` or user-defined + attribute. + + """ + insp = inspection.inspect(entity) + if insp.is_selectable: + description = entity + entity = insp.c + elif insp.is_aliased_class: + description = entity + elif hasattr(insp, "mapper"): + description = entity = insp.mapper.class_ else: - return None + description = entity + + try: + return getattr(entity, key) + except AttributeError: + raise sa_exc.InvalidRequestError( + "Entity '%s' has no property '%s'" % + (description, key) + ) + +def _orm_columns(entity): + insp = inspection.inspect(entity, False) + if hasattr(insp, 'selectable'): + return [c for c in insp.selectable.c] + else: + return [entity] + +def _orm_selectable(entity): + insp = inspection.inspect(entity, False) + if hasattr(insp, 'selectable'): + return insp.selectable + else: + return entity + +def has_identity(object): + state = attributes.instance_state(object) + return state.has_identity def instance_str(instance): """Return a string describing an instance.""" |