such as ``.. versionaddedd::``, ``.. versionchanged::`` and ``.. deprecated::``.
The above will respond to ``create_engine("mysql+foodialect://")`` and load the
``MyMySQLDialect`` class from the ``myapp.dialect`` module.
-The ``register()`` function is new in SQLAlchemy 0.8.
+.. versionadded:: 0.8
Connection / Engine API
=======================
======
SQLAlchemy includes an event API which publishes a wide variety of hooks into
-the internals of both SQLAlchemy Core and ORM. The system is all new
-as of version 0.7 and supercedes the previous system of "extension", "proxy",
-and "listener" classes.
+the internals of both SQLAlchemy Core and ORM.
+
+.. versionadded:: 0.7
+ The system supercedes the previous system of "extension", "proxy",
+ and "listener" classes.
Event Registration
------------------
============
This section describes the event interfaces provided in
-SQLAlchemy Core. The event system in 0.7 is all new and
-supercedes the previous system of "extension", "listener", and
-"proxy" classes. For an introduction to the event listening API,
-see :ref:`event_toplevel`. ORM events are described in
-:ref:`orm_event_toplevel`.
+SQLAlchemy Core.
+For an introduction to the event listening API, see :ref:`event_toplevel`.
+ORM events are described in :ref:`orm_event_toplevel`.
+
+.. versionadded:: 0.7
+ The event system supercedes the previous system of "extension", "listener",
+ and "proxy" classes.
Connection Pool Events
-----------------------
This section describes the class-based core event interface introduced in
SQLAlchemy 0.5. The ORM analogue is described at :ref:`dep_interfaces_orm_toplevel`.
-As of SQLAlchemy 0.7, the new event system described in
-:ref:`event_toplevel` replaces the extension/proxy/listener system, providing
-a consistent interface to all events without the need for subclassing.
+.. deprecated:: 0.7
+ The new event system described in :ref:`event_toplevel` replaces
+ the extension/proxy/listener system, providing a consistent interface
+ to all events without the need for subclassing.
Execution, Connection and Cursor Events
---------------------------------------
Note in the example above, the :class:`.Index` construct is created
externally to the table which it corresponds, using :class:`.Column`
-objects directly. As of SQLAlchemy 0.7, :class:`.Index` also supports
+objects directly. :class:`.Index` also supports
"inline" definition inside the :class:`.Table`, using string names to
identify columns::
Index('idx_col34', 'col3', 'col4', unique=True)
)
+.. versionadded:: 0.7
+ Support of "inline" definition inside the :class:`.Table`
+ for :class:`.Index`\ .
+
The :class:`~sqlalchemy.schema.Index` object also supports its own ``create()`` method:
.. sourcecode:: python+sql
Multiple Table Updates
----------------------
-.. note::
-
- This feature is new as of version 0.7.4.
+.. versionadded:: 0.7.4
The Postgresql, Microsoft SQL Server, and MySQL backends all support UPDATE statements
that refer to multiple tables. For PG and MSSQL, this is the "UPDATE FROM" syntax,
ORM Events
==========
-The ORM includes a wide variety of hooks available for subscription. The event
-system in 0.7 is all new and supercedes the previous system of "extension" classes.
+The ORM includes a wide variety of hooks available for subscription.
+
+.. versionadded:: 0.7
+ The event supercedes the previous system of "extension" classes.
+
For an introduction to the event API, see :ref:`event_toplevel`. Non-ORM events
such as those regarding connections and low-level statement execution are described in
:ref:`core_event_toplevel`.
AND keyword.keyword = :keyword_1)
:class:`.AssociationProxy` can be used with :meth:`.Query.join` somewhat manually
-using the :attr:`~.AssociationProxy.attr` attribute in a star-args context (new in 0.7.3)::
+using the :attr:`~.AssociationProxy.attr` attribute in a star-args context::
q = session.query(User).join(*User.keywords)
+.. versionadded:: 0.7.3
+ :attr:`~.AssociationProxy.attr` attribute in a star-args context.
+
:attr:`~.AssociationProxy.attr` is composed of :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`,
which are just synonyms for the actual proxied attributes, and can also
-be used for querying (also new in 0.7.3)::
+be used for querying::
uka = aliased(UserKeyword)
ka = aliased(Keyword)
join(uka, User.keywords.local_attr).\
join(ka, User.keywords.remote_attr)
+.. versionadded:: 0.7.3
+ :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`,
+ synonyms for the actual proxied attributes, and usable for querying.
+
API Documentation
-----------------
.. autoclass:: AssociationProxy
:members:
- :undoc-members:
\ No newline at end of file
+ :undoc-members:
``Engineer`` objects, :func:`.orm.with_polymorphic` is
not needed since you would query against the ``Engineer`` class directly.
-:func:`.orm.with_polymorphic` is new in 0.8 and is an improved
-version of the existing :meth:`.Query.with_polymorphic` method.
-:meth:`.Query.with_polymorphic` has the same purpose, except is not as
+:meth:`.Query.with_polymorphic` has the same purpose
+as :func:`.orm.with_polymorphic`, except is not as
flexible in its usage patterns in that it only applies to the first full
mapping, which then impacts all occurrences of that class or the target
subclasses within the :class:`.Query`. For simple cases it might be
session.query(Employee).with_polymorphic([Engineer, Manager]).\
filter(or_(Engineer.engineer_info=='w', Manager.manager_data=='q'))
+.. versionadded:: 0.8
+ :func:`.orm.with_polymorphic`, an improved version of
+ :meth:`.Query.with_polymorphic` method.
+
The mapper also accepts ``with_polymorphic`` as a configurational argument so
that the joined-style load will be issued automatically. This argument may be
the string ``'*'``, a list of classes, or a tuple consisting of either,
Concrete Inheritance with Declarative
++++++++++++++++++++++++++++++++++++++
-As of 0.7.3, the :ref:`declarative_toplevel` module includes helpers for concrete inheritance.
-See :ref:`declarative_concrete_helpers` for more information.
+.. versionadded:: 0.7.3
+ The :ref:`declarative_toplevel` module includes helpers for concrete
+ inheritance. See :ref:`declarative_concrete_helpers` for more information.
Using Relationships with Inheritance
------------------------------------
existed in SQLAlchemy 0.1, which progressed with more kinds of events up
until SQLAlchemy 0.5. The non-ORM analogue is described at :ref:`dep_interfaces_core_toplevel`.
-As of SQLAlchemy 0.7, the new event system described in
-:ref:`event_toplevel` replaces the extension/proxy/listener system, providing
-a consistent interface to all events without the need for subclassing.
+.. deprecated:: 0.7
+ As of SQLAlchemy 0.7, the new event system described in
+ :ref:`event_toplevel` replaces the extension/proxy/listener system, providing
+ a consistent interface to all events without the need for subclassing.
Mapper Events
-----------------
Default Loading Strategies
--------------------------
-.. note::
-
- Default loader strategies are a new feature as of version 0.7.5.
+.. versionadded:: 0.7.5
+ Default loader strategies as a new feature.
Each of :func:`.joinedload`, :func:`.subqueryload`, :func:`.lazyload`,
and :func:`.noload` can be used to set the default style of
--------
Synonyms are a mapper-level construct that applies expression behavior to a descriptor
-based attribute. The functionality of synonym is superceded as of 0.7 by hybrid attributes.
+based attribute.
+
+.. versionchanged:: 0.7
+ The functionality of synonym is superceded as of 0.7 by hybrid attributes.
.. autofunction:: synonym
provides a single attribute which represents the group of columns using the
class you provide.
-.. note::
- As of SQLAlchemy 0.7, composites have been simplified such that
+.. versionchanged:: 0.7
+ Composites have been simplified such that
they no longer "conceal" the underlying column based attributes. Additionally,
in-place mutation is no longer automatic; see the section below on
enabling mutability to support tracking of in-place changes.
Tracking In-Place Mutations on Composites
-----------------------------------------
-As of SQLAlchemy 0.7, in-place changes to an existing composite value are
+In-place changes to an existing composite value are
not tracked automatically. Instead, the composite class needs to provide
events to its parent object explicitly. This task is largely automated
via the usage of the :class:`.MutableComposite` mixin, which uses events
to associate each user-defined composite object with all parent associations.
Please see the example in :ref:`mutable_composites`.
+.. versionchanged:: 0.7
+ No automatic tracking of in-place changes to an existing composite value.
+
Redefining Comparison Operations for Composites
-----------------------------------------------
The above mapping features a composite :class:`.ForeignKeyConstraint`
bridging the ``widget_id`` and ``favorite_entry_id`` columns. To ensure
that ``Widget.widget_id`` remains an "autoincrementing" column we specify
-``autoincrement='ignore_fk'`` on :class:`.Column` (new in 0.7.4), and additionally on each
+``autoincrement='ignore_fk'`` on :class:`.Column`, and additionally on each
:func:`.relationship` we must limit those columns considered as part of
the foreign key for the purposes of joining and cross-population.
+.. versionadded:: 0.7.4
+ ``autoincrement='ignore_fk'`` on :class:`.Column`\ .
+
.. _passive_updates:
Mutable Primary Keys / Update Cascades
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
