Using Transactions
==================
-.. note:: This section describes how to use transactions when working directly
+.. note::
+
+ This section describes how to use transactions when working directly
with :class:`.Engine` and :class:`.Connection` objects. When using the
SQLAlchemy ORM, the public API for transaction control is via the
:class:`.Session` object, which makes usage of the :class:`.Transaction`
"pool_logging_name" keyword arguments with :func:`sqlalchemy.create_engine`.
.. note::
+
The SQLAlchemy :class:`.Engine` conserves Python function call overhead
by only emitting log statements when the current logging level is detected
as ``logging.INFO`` or ``logging.DEBUG``. It only checks this level when
access two "hops" with a single access, one "hop" to the
associated object, and a second to a target attribute.
-.. note:: When using the association object pattern, it is
+.. note::
+
+ When using the association object pattern, it is
advisable that the association-mapped table not be used
as the ``secondary`` argument on a :func:`.relationship`
elsewhere, unless that :func:`.relationship` contains
()
COMMIT
-.. note:: Users familiar with the syntax of CREATE TABLE may notice that the
+.. note::
+
+ Users familiar with the syntax of CREATE TABLE may notice that the
VARCHAR columns were generated without a length; on SQLite and Postgresql,
this is a valid datatype, but on others, it's not allowed. So if running
this tutorial on one of those databases, and you wish to use SQLAlchemy to
``Address`` it is **one to many**. SQLAlchemy is automatically aware of
many-to-one/one-to-many based on foreign keys.
-.. note:: The :func:`~sqlalchemy.orm.relationship()` function has historically
+.. note::
+
+ The :func:`~sqlalchemy.orm.relationship()` function has historically
been known as :func:`~sqlalchemy.orm.relation()`, which is the name that's
available in all versions of SQLAlchemy prior to 0.6beta2, including the 0.5
and 0.4 series. :func:`~sqlalchemy.orm.relationship()` is only available
:func:`~sqlalchemy.orm.subqueryload`. We'll also see another way to "eagerly"
load in the next section.
-.. note:: The join created by :func:`.joinedload` is anonymously aliased such that
+.. 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
relationship needs to be removed, so we need to tear down the mappings
completely and start again.
-.. note:: Tearing down mappers with :func:`~.orm.clear_mappers` is not a typical
+.. note::
+
+ Tearing down mappers with :func:`~.orm.clear_mappers` is not a typical
operation, and normal applications do not need to use this function. It is
here so that the tutorial code can be executed as a whole.
"""Mark a class-level method as representing the definition of
a mapped property or special declarative member name.
- .. note:: @declared_attr is available as
+ .. note::
+
+ @declared_attr is available as
``sqlalchemy.util.classproperty`` for SQLAlchemy versions
0.6.2, 0.6.3, 0.6.4.
(as in the mapper example above). This implementation depends on the list
starting in the proper order, so be SURE to put an order_by on your relationship.
-.. warning:: ``ordering_list`` only provides limited functionality when a primary
+.. warning::
+
+ ``ordering_list`` only provides limited functionality when a primary
key column or unique column is the target of the sort. Since changing the order of
entries often means that two rows must trade values, this is not possible when
the value is constrained by a primary key or unique constraint, since one of the rows
def relationship(argument, secondary=None, **kwargs):
"""Provide a relationship of a primary Mapper to a secondary Mapper.
- .. note:: :func:`relationship` is historically known as
+ .. note::
+
+ :func:`relationship` is historically known as
:func:`relation` prior to version 0.6.
This corresponds to a parent-child or associative table relationship. The
"""Return a ``MapperOption`` that will convert the property of the given
name into an joined eager load.
- .. note:: This function is known as :func:`eagerload` in all versions
- of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4
- series. :func:`eagerload` will remain available for the foreseeable
- future in order to enable cross-compatibility.
+ .. note::
+
+ This function is known as :func:`eagerload` in all versions
+ of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4
+ series. :func:`eagerload` will remain available for the foreseeable
+ future in order to enable cross-compatibility.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
query(Order).options(joinedload(Order.user, innerjoin=True))
- .. note:: The join created by :func:`joinedload` is anonymously aliased such that
+ .. 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
"""Return a ``MapperOption`` that will convert all properties along the
given dot-separated path into an joined eager load.
- .. note:: This function is known as :func:`eagerload_all` in all versions
+ .. note::
+
+ This function is known as :func:`eagerload_all` in all versions
of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4
series. :func:`eagerload_all` will remain available for the
foreseeable future in order to enable cross-compatibility.
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
