such as ``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::``.
through all mapping configurations collected, reflect the tables
named within and generate the actual mappers.
-The example is new in 0.7.5 and makes usage of the new
-``autoload_replace`` flag on :class:`.Table` to allow declared
-classes to override reflected columns.
+.. versionadded:: 0.7.5
+ This new example makes usage of the new
+ ``autoload_replace`` flag on :class:`.Table` to allow declared
+ classes to override reflected columns.
Usage example::
Scalar Select Comparisons
-------------------------
-The MSSQL dialect contains a legacy behavior whereby comparing
-a scalar select to a value using the ``=`` or ``!=`` operator
-will resolve to IN or NOT IN, respectively. This behavior is
-deprecated and will be removed in 0.8 - the ``s.in_()``/``~s.in_()`` operators
-should be used when IN/NOT IN are desired.
+.. deprecated:: 0.8
+ The MSSQL dialect contains a legacy behavior whereby comparing
+ a scalar select to a value using the ``=`` or ``!=`` operator
+ will resolve to IN or NOT IN, respectively. This behavior
+ will be removed in 0.8 - the ``s.in_()``/``~s.in_()`` operators
+ should be used when IN/NOT IN are desired.
For the time being, the existing behavior prevents a comparison
between scalar select and another value that actually wants to use ``=``.
well. When ``False``, unicode literals will be encoded first, and when
``True`` unicode literals will be passed straight through. This is an interim
flag that hopefully should not be needed when the unicode situation stabilizes
-for unix + PyODBC. New in 0.7.7.
+for unix + PyODBC.
+
+.. versionadded:: 0.7.7
+ ``supports_unicode_binds`` parameter to ``create_engine()``\ .
"""
isolation_level="READ UNCOMMITTED"
)
-(new in 0.7.6)
+.. versionadded:: 0.7.6
Keys
----
Unicode
-------
-SQLAlchemy 0.6 uses the "native unicode" mode provided as of cx_oracle 5. cx_oracle 5.0.2
-or greater is recommended for support of NCLOB. If not using cx_oracle 5, the NLS_LANG
-environment variable needs to be set in order for the oracle client library to use
-proper encoding, such as "AMERICAN_AMERICA.UTF8".
+.. versionchanged:: 0.6
+ SQLAlchemy uses the "native unicode" mode provided as of cx_oracle 5.
+ cx_oracle 5.0.2 or greater is recommended for support of NCLOB.
+ If not using cx_oracle 5, the NLS_LANG environment variable needs
+ to be set in order for the oracle client library to use proper encoding,
+ such as "AMERICAN_AMERICA.UTF8".
Also note that Oracle supports unicode data through the NVARCHAR and NCLOB data types.
When using the SQLAlchemy Unicode and UnicodeText types, these DDL types will be used
engine = create_engine("oracle+cx_oracle://dsn",
coerce_to_decimal=False)
-The ``coerce_to_decimal`` flag is new in 0.7.6.
+.. versionadded:: 0.7.6
+ Add the ``coerce_to_decimal`` flag.
Another alternative to performance is to use the
`cdecimal <http://pypi.python.org/pypi/cdecimal/>`_ library;
test to determine the current "decimal" character, which can be
a comma "," for european locales. From that point forward the
outputtypehandler uses that character to represent a decimal
-point (this behavior is new in version 0.6.6). Note that
-cx_oracle 5.0.3 or greater is required when dealing with
-numerics with locale settings that don't use a period "." as the
-decimal character.
+point. Note that cx_oracle 5.0.3 or greater is required
+when dealing with numerics with locale settings that don't use
+a period "." as the decimal character.
+
+.. versionchanged:: 0.6.6
+ The outputtypehandler uses a comma "," character to represent
+ a decimal point.
.. _OCI: http://www.oracle.com/technetwork/database/features/oci/index.html
SHOW search_path;
-Prior to version 0.7.3, cross-schema foreign keys when the schemas
-were also in the ``search_path`` could make an incorrect assumption
-if the schemas were explicitly stated on each :class:`.Table`.
+.. versionchanged:: 0.7.3
+ Prior to this version, cross-schema foreign keys when the schemas
+ were also in the ``search_path`` could make an incorrect assumption
+ if the schemas were explicitly stated on each :class:`.Table`.
Background on PG's ``search_path`` is at:
http://www.postgresql.org/docs/9.0/static/ddl-schemas.html#DDL-SCHEMAS-PATH
PostgreSQL allows the specification of an *operator class* for each column of
an index (see http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html).
The :class:`.Index` construct allows these to be specified via the ``postgresql_ops``
-keyword argument (new as of SQLAlchemy 0.7.2)::
+keyword argument::
Index('my_index', my_table.c.id, my_table.c.data,
postgresql_ops={
'id': 'int4_ops'
})
+.. versionadded:: 0.7.2
+ ``postgresql_ops`` keyword argument to :class:`.Index` construct.
+
Note that the keys in the ``postgresql_ops`` dictionary are the "key" name of
the :class:`.Column`, i.e. the name used to access it from the ``.c`` collection
of :class:`.Table`, which can be configured to be different than the actual
class should be considered mutable - this enables
"mutable types" mode in the ORM. Be sure to read the
notes for :class:`.MutableType` regarding ORM
- performance implications (default changed from ``True`` in
- 0.7.0).
+ performance implications.
+
+ .. versionchanged:: 0.7.0
+ Default changed from ``True``\ .
- .. note::
-
- This functionality is now superseded by the
- ``sqlalchemy.ext.mutable`` extension described in
- :ref:`mutable_toplevel`.
+ .. versionchanged:: 0.7
+ This functionality is now superseded by the
+ ``sqlalchemy.ext.mutable`` extension described in
+ :ref:`mutable_toplevel`.
:param as_tuple=False: Specify whether return results
should be converted to tuples from lists. DBAPIs such
as psycopg2 return lists by default. When tuples are
returned, the results are hashable. This flag can only
be set to ``True`` when ``mutable`` is set to
- ``False``. (new in 0.6.5)
+ ``False``.
+
+ .. versionadded:: 0.6.5
"""
if isinstance(item_type, ARRAY):
the :meth:`~.postgresql.ENUM.create` and
:meth:`~.postgresql.ENUM.drop` methods can
be used to emit SQL to a target bind.
- (new in 0.7.4)
-
+
+ .. versionadded:: 0.7.4
+
"""
self.create_type = kw.pop("create_type", True)
super(ENUM, self).__init__(*enums, **kw)
engine = create_engine("postgresql://user:pass@host/dbname", client_encoding='utf8')
This overrides the encoding specified in the Postgresql client configuration.
-The psycopg2-specific ``client_encoding`` parameter to :func:`.create_engine` is new as of
-SQLAlchemy 0.7.3.
+
+.. versionadded:: 0.7.3
+ The psycopg2-specific ``client_encoding`` parameter to :func:`.create_engine`.
SQLAlchemy can also be instructed to skip the usage of the psycopg2
``UNICODE`` extension and to instead utilize it's own unicode encode/decode
prevents a connection from being used again in a different thread and works
best with SQLite's coarse-grained file locking.
- .. note::
-
- The default selection of :class:`.NullPool` for SQLite file-based databases
- is new in SQLAlchemy 0.7. Previous versions
- select :class:`.SingletonThreadPool` by
- default for all SQLite databases.
+ .. versionchanged:: 0.7
+ Default selection of :class:`.NullPool` for SQLite file-based databases.
+ Previous versions select :class:`.SingletonThreadPool` by
+ default for all SQLite databases.
Modern versions of SQLite no longer have the threading restrictions, and assuming
the sqlite3/pysqlite library was built with SQLite's default threading mode
behavior of the pool, which is whether ``rollback()``,
``commit()``, or nothing is called upon connections
being returned to the pool. See the docstring for
- ``reset_on_return`` at :class:`.Pool`. (new as of 0.7.6)
+ ``reset_on_return`` at :class:`.Pool`.
+
+ .. versionadded:: 0.7.6
:param pool_timeout=30: number of seconds to wait before giving
up on getting a connection from the pool. This is only used
containing percent signs (and possibly other characters)
that is neutral regarding whether it's executed by the DBAPI
or piped into a script that's later invoked by
- command line tools. New in 0.7.6.
-
+ command line tools.
+
+ .. versionadded:: 0.7.6
+
:param stream_results: Available on: Connection, statement.
Indicate to the dialect that results should be
"streamed" and not pre-buffered, if possible. This is a limitation
close the :class:`.Connection` when that :class:`.ResultProxy`
has exhausted all result rows.
- New in 0.7.6.
+ .. versionadded:: 0.7.6
See also:
exception is then wrapped in a SQLAlchemy DBAPI exception
wrapper and re-thrown.
- New in 0.7.7.
+ .. versionadded:: 0.7.7
"""
"""The 'remote' :class:`.MapperProperty` referenced by this
:class:`.AssociationProxy`.
- New in 0.7.3.
+ .. versionadded:: 0.7.3
See also:
"""The 'local' :class:`.MapperProperty` referenced by this
:class:`.AssociationProxy`.
- New in 0.7.3.
+ .. versionadded:: 0.7.3
See also:
sess.query(Parent).join(*Parent.proxied.attr)
- New in 0.7.3.
+ .. versionadded:: 0.7.3
See also:
Using the Concrete Helpers
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-New helper classes released in 0.7.3 provides a simpler pattern for concrete inheritance.
+Helper classes provides a simpler pattern for concrete inheritance.
With these objects, the ``__declare_last__`` helper is used to configure the "polymorphic"
loader for the mapper after all subclasses have been declared.
+.. versionadded:: 0.7.3
+
An abstract base can be declared using the :class:`.AbstractConcreteBase` class::
from sqlalchemy.ext.declarative import AbstractConcreteBase
which can't be properly recreated at this level. For columns that
have foreign keys, as well as for the variety of mapper-level constructs
that require destination-explicit context, the
-:func:`~.declared_attr` decorator (renamed from ``sqlalchemy.util.classproperty`` in 0.6.5)
-is provided so that
+:func:`~.declared_attr` decorator is provided so that
patterns common to many classes can be defined as callables::
from sqlalchemy.ext.declarative import declared_attr
extension can use the resulting :class:`.Column` object as returned by
the method without the need to copy it.
+.. versionchanged:: > 0.6.5
+ Rename 0.6.5 ``sqlalchemy.util.classproperty`` into :func:`~.declared_attr`.
+
Columns generated by :func:`~.declared_attr` can also be
referenced by ``__mapper_args__`` to a limited degree, currently
by ``polymorphic_on`` and ``version_id_col``, by specifying the
``__declare_last__()``
~~~~~~~~~~~~~~~~~~~~~~
-The ``__declare_last__()`` hook, introduced in 0.7.3, allows definition of
+The ``__declare_last__()`` hook allows definition of
a class level function that is automatically called by the :meth:`.MapperEvents.after_configured`
event, which occurs after mappings are assumed to be completed and the 'configure' step
has finished::
""
# do something with mappings
+.. versionadded:: 0.7.3
+
.. _declarative_abstract:
``__abstract__``
~~~~~~~~~~~~~~~~~~~
-``__abstract__`` is introduced in 0.7.3 and causes declarative to skip the production
+``__abstract__`` causes declarative to skip the production
of a table or mapper for the class entirely. A class can be added within a hierarchy
in the same way as mixin (see :ref:`declarative_mixins`), allowing subclasses to extend
just from the special class::
DefaultBase.metadata.create_all(some_engine)
OtherBase.metadata_create_all(some_other_engine)
+.. versionadded:: 0.7.3
+
Class Constructor
=================
"""Mark a class-level method as representing the definition of
a mapped property or special declarative member name.
- .. note::
-
- @declared_attr is available as
- ``sqlalchemy.util.classproperty`` for SQLAlchemy versions
- 0.6.2, 0.6.3, 0.6.4.
+ .. versionchanged:: 0.6.{2,3,4}
+ ``@declared_attr`` is available as
+ ``sqlalchemy.util.classproperty`` for SQLAlchemy versions
+ 0.6.2, 0.6.3, 0.6.4.
@declared_attr turns the attribute into a scalar-like
property that can be invoked from the uninstantiated class.
or more columns from the underlying mapped table. The usual example is that of
a geometric "point", and is introduced in :ref:`mapper_composite`.
-As of SQLAlchemy 0.7, the internals of :func:`.orm.composite` have been
-greatly simplified and in-place mutation detection is no longer enabled by
-default; instead, the user-defined value must detect changes on its own and
-propagate them to all owning parents. The :mod:`sqlalchemy.ext.mutable`
-extension provides the helper class :class:`.MutableComposite`, which is a
-slight variant on the :class:`.Mutable` class.
+.. versionchanged:: 0.7
+ The internals of :func:`.orm.composite` have been
+ greatly simplified and in-place mutation detection is no longer enabled by
+ default; instead, the user-defined value must detect changes on its own and
+ propagate them to all owning parents. The :mod:`sqlalchemy.ext.mutable`
+ extension provides the helper class :class:`.MutableComposite`, which is a
+ slight variant on the :class:`.Mutable` class.
As is the case with :class:`.Mutable`, the user-defined composite class
subclasses :class:`.MutableComposite` as a mixin, and detects and delivers
"""
-.. note::
-
- SQLSoup is now its own project. Documentation
- and project status are available at:
-
- http://pypi.python.org/pypi/sqlsoup
-
- http://readthedocs.org/docs/sqlsoup
-
- SQLSoup will no longer be included with SQLAlchemy as of
- version 0.8.
+.. versionchanged:: 0.8
+ SQLSoup is now its own project. Documentation
+ and project status are available at:
+ http://pypi.python.org/pypi/sqlsoup and
+ http://readthedocs.org/docs/sqlsoup\ .
+ SQLSoup will no longer be included with SQLAlchemy.
Introduction
This is the "master" method that can be used to create any
configuration.
- (new in 0.6.6)
+ .. versionadded:: 0.6.6
:param attrname: String attribute name which will be
established as an attribute on this :class:.`.SqlSoup`
def map(self, selectable, base=None, **mapper_args):
"""Map a selectable directly.
- The class and its mapping are not cached and will
- be discarded once dereferenced (as of 0.6.6).
+ .. versionchanged:: 0.6.6
+ The class and its mapping are not cached and will
+ be discarded once dereferenced.
:param selectable: an :func:`.expression.select` construct.
:param base: a Python class which will be used as the
"""Map a selectable directly, wrapping the
selectable in a subquery with labels.
- The class and its mapping are not cached and will
- be discarded once dereferenced (as of 0.6.6).
+ .. versionchanged:: 0.6.6
+ The class and its mapping are not cached and will
+ be discarded once dereferenced.
:param selectable: an :func:`.expression.select` construct.
:param base: a Python class which will be used as the
base=None, **mapper_args):
"""Create an :func:`.expression.join` and map to it.
- The class and its mapping are not cached and will
- be discarded once dereferenced (as of 0.6.6).
+ .. versionchanged:: 0.6.6
+ The class and its mapping are not cached and will
+ be discarded once dereferenced.
:param left: a mapped class or table object.
:param right: a mapped class or table object.
def relationship(argument, secondary=None, **kwargs):
"""Provide a relationship of a primary Mapper to a secondary Mapper.
- .. note::
-
- :func:`relationship` is historically known as
- :func:`relation` prior to version 0.6.
+ .. versionchanged:: 0.6
+ :func:`relationship` is historically known as :func:`relation`.
This corresponds to a parent-child or associative table relationship. The
constructed class is an instance of :class:`.RelationshipProperty`.
* ``delete-orphan`` - if an item of the child's type is
detached from its parent, mark it for deletion.
- As of version 0.7, this option does not prevent
- a new instance of the child object from being persisted
- without a parent to start with; to constrain against
- that case, ensure the child's foreign key column(s)
- is configured as NOT NULL
+
+ .. versionchanged:: 0.7
+ This option does not prevent
+ a new instance of the child object from being persisted
+ without a parent to start with; to constrain against
+ that case, ensure the child's foreign key column(s)
+ is configured as NOT NULL
* ``refresh-expire`` - cascade the :meth:`.Session.expire`
and :meth:`~sqlalchemy.orm.session.Session.refresh` operations
* ``immediate`` - items should be loaded as the parents are loaded,
using a separate SELECT statement, or identity map fetch for
- simple many-to-one references. (new as of 0.6.5)
+ simple many-to-one references.
+
+ .. versionadded:: 0.6.5
* ``joined`` - items should be loaded "eagerly" in the same query as
that of the parent, using a JOIN or LEFT OUTER JOIN. Whether
flag is available for applications that make use of
:func:`.attributes.get_history` or :meth:`.Session.is_modified`
which also need to know
- the "previous" value of the attribute. (new in 0.6.6)
+ the "previous" value of the attribute.
+
+ .. versionadded:: 0.6.6
:param comparator_factory: a class which extends
:class:`.ColumnProperty.Comparator` which provides custom SQL clause
Note however that the :class:`.Session` with default expiration
settings still expires
all attributes after a :meth:`.Session.commit` call, however.
- New in 0.7.3.
-
+
+ .. versionadded:: 0.7.3
:param extension:
an
When ``True``, indicates that the "previous" value for a
scalar attribute should be loaded when replaced, if not
already loaded. See the same flag on :func:`.column_property`.
- (This flag becomes meaningful specifically for
- :func:`.composite` in 0.7 - previously it was a placeholder).
+
+ .. versionchanged:: 0.7
+ This flag specifically becomes meaningful
+ - previously it was a placeholder.
:param group:
A group name for this property when marked as deferred.
"polymorphic_identity":"employee"
}
- As of SQLAlchemy 0.7.4, it may also be specified
+ It may also be specified
as a SQL expression, as in this example where we
use the :func:`.case` construct to provide a conditional
approach::
"polymorphic_identity":"employee"
}
- Also as of 0.7.4, 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::
"polymorphic_on":employee_type,
"polymorphic_identity":"employee"
}
-
+
+ .. versionchanged:: 0.7.4
+ ``polymorphic_on`` may be specified as a SQL expression,
+ or refer to any attribute configured with
+ :func:`.column_property`, or to the string name of one.
+
When setting ``polymorphic_on`` to reference an
attribute or expression that's not present in the
locally mapped :class:`.Table`, yet the value
comparator_factory=None, doc=None):
"""Denote an attribute name as a synonym to a mapped property.
- .. note::
-
- :func:`.synonym` is superseded as of 0.7 by
- the :mod:`~sqlalchemy.ext.hybrid` extension. See
- the documentation for hybrids at :ref:`hybrids_toplevel`.
+ .. versionchanged:: 0.7
+ :func:`.synonym` is superseded by the :mod:`~sqlalchemy.ext.hybrid`
+ extension. See the documentation for hybrids
+ at :ref:`hybrids_toplevel`.
Used with the ``properties`` dictionary sent to
:func:`~sqlalchemy.orm.mapper`::
"""Provides a method of applying a :class:`.PropComparator`
to any Python descriptor attribute.
- .. note::
-
- :func:`.comparable_property` is superseded as of 0.7 by
- the :mod:`~sqlalchemy.ext.hybrid` extension. See the example
- at :ref:`hybrid_custom_comparators`.
-
+ .. versionchanged:: 0.7
+ :func:`.comparable_property` is superseded by
+ the :mod:`~sqlalchemy.ext.hybrid` extension. See the example
+ at :ref:`hybrid_custom_comparators`.
+
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.
"""Return a ``MapperOption`` that will convert the property of the given
name or series of mapped attributes 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.
+ .. versionchanged:: 0.6beta3
+ 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`.
given dot-separated path or series of mapped attributes
into an joined eager load.
- .. 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.
+ .. versionchanged:: 0.6beta3
+ 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.
Used with :meth:`~sqlalchemy.orm.query.Query.options`.
See also: :func:`lazyload`, :func:`eagerload`, :func:`subqueryload`
- New as of verison 0.6.5.
+ .. versionadded:: 0.6.5
"""
return strategies.EagerLazyOption(keys, lazy='immediate')
instance population will not proceed, giving this extension an
opportunity to populate the instance itself, if desired.
- As of 0.5, most usages of this hook are obsolete. For a
- generic "object has been newly created from a row" hook, use
- ``reconstruct_instance()``, or the ``@orm.reconstructor``
- decorator.
+ .. deprecated:: 0.5
+ Most usages of this hook are obsolete. For a
+ generic "object has been newly created from a row" hook, use
+ ``reconstruct_instance()``, or the ``@orm.reconstructor``
+ decorator.
"""
return EXT_CONTINUE
for the given :class:`.Session` is available via the
:attr:`.Session.transaction` attribute.
- New in 0.7.3.
+ .. versionadded:: 0.7.3
"""
* A mapped object with version_id_col was refreshed,
and the version number coming back from the database does
not match that of the object itself.
-
+
* A object is detached from its parent object, however
the object was previously attached to a different parent
identity which was garbage collected, and a decision
cannot be made if the new parent was really the most
- recent "parent" (new in 0.7.4).
+ recent "parent".
+
+ .. versionadded:: 0.7.4
"""
:param \*names: list of attribute names to be validated.
:param include_removes: if True, "remove" events will be
sent as well - the validation function must accept an additional
- argument "is_remove" which will be a boolean. New in 0.7.7.
+ argument "is_remove" which will be a boolean.
+
+ .. versionadded:: 0.7.7
"""
include_removes = kw.pop('include_removes', False)
"""Return the full SELECT statement represented by this :class:`.Query`
represented as a common table expression (CTE).
- The :meth:`.Query.cte` method is new in 0.7.6.
+ .. versionadded:: 0.7.6
Parameters and usage are the same as those of the
:meth:`._SelectBase.cte` method; see that method for
Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.label`.
- New in 0.6.5.
+ .. versionadded:: 0.6.5
"""
Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.as_scalar`.
- New in 0.6.5.
+ .. versionadded:: 0.6.5
"""
q = q.join((subq, subq.c.email < Address.email)).\\
limit(1)
- New in 0.6.5.
+ .. versionadded:: 0.6.5
"""
self._set_entities(entities)
This allows ad-hoc recipes to be created for :class:`.Query`
objects. See the example at :ref:`hybrid_transformers`.
- :meth:`~.Query.with_transformation` is new in SQLAlchemy 0.7.4.
+ .. versionadded:: 0.7.4
"""
return fn(self)
``'read_nowait'`` - passes ``for_update='read_nowait'``, which
translates to ``FOR SHARE NOWAIT`` (supported by PostgreSQL).
- New in 0.7.7: ``FOR SHARE`` and ``FOR SHARE NOWAIT`` (PostgreSQL)
+ .. versionadded:: 0.7.7
+ ``FOR SHARE`` and ``FOR SHARE NOWAIT`` (PostgreSQL).
"""
self._lockmode = mode
session.query(MyClass).filter(MyClass.name == 'some name')
- Multiple criteria are joined together by AND (new in 0.7.5)::
+ Multiple criteria are joined together by AND::
session.query(MyClass).\\
filter(MyClass.name == 'some name', MyClass.id > 5)
WHERE clause of a select. String expressions are coerced
into SQL expression constructs via the :func:`.text` construct.
+ .. versionchanged:: 0.7.5
+ Multiple criteria joined by AND.
+
See also:
:meth:`.Query.filter_by` - filter on keyword expressions.
q = session.query(User).join(Address, User.id==Address.user_id)
- .. note::
-
- 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
- is not necessary unless multiple join conditions are passed to
- a single :meth:`~.Query.join` call, which itself is also not
- generally necessary as it is now equivalent to multiple
- calls (this wasn't always the case).
+ .. versionchanged:: 0.7
+ 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
+ is not necessary unless multiple join conditions are passed to
+ a single :meth:`~.Query.join` call, which itself is also not
+ generally necessary as it is now equivalent to multiple
+ calls (this wasn't always the case).
**Advanced Join Targeting and Adaption**
SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name
FROM users
- New in 0.7.7.
+ .. versionadded:: 0.7.7
"""
if self._prefixes:
unique entity or entities - this is a successful result for one().
Calling ``one()`` results in an execution of the underlying query.
- As of 0.6, ``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.
+
+ .. versionchanged:: 0.6
+ ``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.
"""
ret = list(self)
SELECT <rest of query follows...>
) AS anon_1
- Note the above scheme is newly refined in 0.7
- (as of 0.7b3).
+ .. versionchanged:: 0.7
+ The above scheme is newly refined as of 0.7b3.
For fine grained control over specific columns
to count, to skip the usage of a subquery or
instances behind the scenes, with one :class:`~.engine.base.Transaction`
per :class:`~.engine.base.Engine` in use.
- Direct usage of :class:`.SessionTransaction` is not typically
- necessary as of SQLAlchemy 0.4; use the :meth:`.Session.rollback` and
- :meth:`.Session.commit` methods on :class:`.Session` itself to
- control the transaction.
-
+ .. versionchanged:: 0.4
+ Direct usage of :class:`.SessionTransaction` is not typically
+ necessary; use the :meth:`.Session.rollback` and
+ :meth:`.Session.commit` methods on :class:`.Session` itself to
+ control the transaction.
+
The current instance of :class:`.SessionTransaction` for a given
:class:`.Session` is available via the :attr:`.Session.transaction`
attribute.
of objects which involve existing database queries,
where the uncompleted object should not yet be flushed.
- New in 0.7.6.
+ .. versionadded:: 0.7.6
"""
autoflush = self.autoflush
E.g.::
return session.is_modified(someobject, passive=True)
-
- .. note::
-
- In SQLAlchemy 0.7 and earlier, the ``passive``
- flag should **always** be explicitly set to ``True``.
- The current default value of :data:`.attributes.PASSIVE_OFF`
- for this flag is incorrect, in that it loads unloaded
- collections and attributes which by definition
- have no modified state, and furthermore trips off
- autoflush which then causes all subsequent, possibly
- modified attributes to lose their modified state.
- The default value of the flag will be changed in 0.8.
-
+
+ .. versionchanged:: 0.8
+ In SQLAlchemy 0.7 and earlier, the ``passive``
+ flag should **always** be explicitly set to ``True``.
+ The current default value of :data:`.attributes.PASSIVE_OFF`
+ for this flag is incorrect, in that it loads unloaded
+ collections and attributes which by definition
+ have no modified state, and furthermore trips off
+ autoflush which then causes all subsequent, possibly
+ modified attributes to lose their modified state.
+ The default value of the flag will be changed in 0.8.
+
A few caveats to this method apply:
* Instances present in the :attr:`.Session.dirty` collection may report
is a bug, as unloaded attributes by definition have
no changes, and the load operation also triggers an
autoflush which then cancels out subsequent changes.
- This flag should **always be set to
- True**. In 0.8 the flag will be deprecated and the default
- set to ``True``.
+ This flag should **always be set to True**.
+ .. versionchanged:: 0.8
+ The flag will be deprecated and the default
+ set to ``True``.
"""
try:
have any "column correspondence" to the actual ``UnitPrice.price`` column
as it is not a proxy of the original.
- ``adapt_on_names`` is new in 0.7.3.
+ .. versionadded:: 0.7.3
"""
def __init__(self, cls, alias=None, name=None, adapt_on_names=False):
Python without the need to render joins to the parent table
in the rendered statement.
- As of 0.6.4, 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
- instances.
+ .. versionchanged:: 0.6.4
+ 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
+ instances.
:param instance:
An instance which has some :func:`.relationship`.
:param reset_on_return: Determine steps to take on
connections as they are returned to the pool.
- As of SQLAlchemy 0.7.6, reset_on_return can have any
- of these values:
-
+ reset_on_return can have any of these values:
+
* 'rollback' - call rollback() on the connection,
to release locks and transaction resources.
This is the default value. The vast majority
value is more dangerous than 'rollback' because
any data changes present on the transaction
are committed unconditionally.
- * None - don't do anything on the connection.
- This setting should only be made on a database
- that has no transaction support at all,
- namely MySQL MyISAM. By not doing anything,
- performance can be improved. This
- setting should **never be selected** for a
- database that supports transactions,
- as it will lead to deadlocks and stale
- state.
- * False - same as None, this is here for
- backwards compatibility.
-
+ * None - don't do anything on the connection.
+ This setting should only be made on a database
+ that has no transaction support at all,
+ namely MySQL MyISAM. By not doing anything,
+ performance can be improved. This
+ setting should **never be selected** for a
+ database that supports transactions,
+ as it will lead to deadlocks and stale
+ state.
+ * False - same as None, this is here for
+ backwards compatibility.
+
+ .. versionchanged:: 0.7.6
+ ``reset_on_return`` accepts values.
+
:param listeners: A list of
:class:`~sqlalchemy.interfaces.PoolListener`-like objects or
dictionaries of callables that receive events when DB-API
invalidation are not supported by this Pool implementation, since
no connections are held persistently.
- :class:`.NullPool` is used by the SQlite dialect automatically
- when a file-based database is used (as of SQLAlchemy 0.7).
- See :ref:`sqlite_toplevel`.
+ .. versionchanged:: 0.7
+ :class:`.NullPool` is used by the SQlite dialect automatically
+ when a file-based database is used. See :ref:`sqlite_toplevel`.
"""
This will raise an exception if more than one connection is checked out
at a time. Useful for debugging code that is using more connections
than desired.
-
- :class:`.AssertionPool` also logs a traceback of where
- the original connection was checked out, and reports
- this in the assertion error raised (new in 0.7).
+
+ .. versionchanged:: 0.7
+ :class:`.AssertionPool` also logs a traceback of where
+ the original connection was checked out, and reports
+ this in the assertion error raised.
"""
def __init__(self, *args, **kw):
excluded from the reflection process. Note that this does
not impact ``Column`` objects specified in the same call to ``Table``
which includes ``autoload``, those always take precedence.
- Defaults to ``True``. New in 0.7.5.
+ Defaults to ``True``.
+
+ .. versionadded:: 0.7.5
:param autoload_with: If autoload==True, this is an optional Engine
or Connection instance to be used for the table reflection. If
raised if additional table modifiers are specified when
the given :class:`.Table` is already present in the :class:`.MetaData`.
- As of version 0.7.4, ``extend_existing`` will work in conjunction
- with ``autoload=True`` to run a new reflection operation against
- the database; new :class:`.Column` objects will be produced
- from database metadata to replace those existing with the same
- name, and additional :class:`.Column` objects not present
- in the :class:`.Table` will be added.
+ .. versionchanged:: 0.7.4
+ ``extend_existing`` will work in conjunction
+ with ``autoload=True`` to run a new reflection operation against
+ the database; new :class:`.Column` objects will be produced
+ from database metadata to replace those existing with the same
+ name, and additional :class:`.Column` objects not present
+ in the :class:`.Table` will be added.
+
As is always the case with ``autoload=True``, :class:`.Column`
objects can be specified in the same :class:`.Table` constructor,
which will take precedence. I.e.::
* Part of the primary key
* Are not referenced by any foreign keys, unless
- the value is specified as ``'ignore_fk'`` (new in 0.7.4)
+ the value is specified as ``'ignore_fk'``
+
+ .. versionadded:: 0.7.4
* have no server side or client side defaults (with the exception
of Postgresql SERIAL).
to generate primary key identifiers (i.e. Firebird, Postgresql,
Oracle).
- As of 0.7.4, ``autoincrement`` accepts a special value ``'ignore_fk'``
- to indicate that autoincrementing status regardless of foreign key
- references. This applies to certain composite foreign key
- setups, such as the one demonstrated in the ORM documentation
- at :ref:`post_update`.
+ .. versionchanged:: 0.7.4
+ ``autoincrement`` accepts a special value ``'ignore_fk'``
+ to indicate that autoincrementing status regardless of foreign key
+ references. This applies to certain composite foreign key
+ setups, such as the one demonstrated in the ORM documentation
+ at :ref:`post_update`.
:param default: A scalar, Python callable, or
:class:`~sqlalchemy.sql.expression.ClauseElement` representing the
(defaults to the column name itself), unless ``link_to_name`` is
``True`` in which case the rendered name of the column is used.
- Note that if the schema name is not included, and the underlying
- :class:`.MetaData` has a "schema", that value will be used.
- (new in 0.7.4)
+ .. versionadded:: 0.7.4
+ Note that if the schema name is not included, and the underlying
+ :class:`.MetaData` has a "schema", that value will be used.
:param name: Optional string. An in-database name for the key if
`constraint` is not provided.
that is associated with a :class:`.MetaData` gains access to the
``bind`` of that :class:`.MetaData`, meaning the :meth:`.Sequence.create`
and :meth:`.Sequence.drop` methods will make usage of that engine
- automatically. Additionally, the appropriate CREATE SEQUENCE/
- DROP SEQUENCE DDL commands will be emitted corresponding to this
- :class:`.Sequence` when :meth:`.MetaData.create_all` and
- :meth:`.MetaData.drop_all` are invoked (new in 0.7).
+ automatically.
+
+ .. versionchanged:: 0.7
+ Additionally, the appropriate CREATE SEQUENCE/
+ DROP SEQUENCE DDL commands will be emitted corresponding to this
+ :class:`.Sequence` when :meth:`.MetaData.create_all` and
+ :meth:`.MetaData.drop_all` are invoked.
Note that when a :class:`.Sequence` is applied to a :class:`.Column`,
the :class:`.Sequence` is automatically associated with the
class PassiveDefault(DefaultClause):
"""A DDL-specified DEFAULT column value.
- .. deprecated:: 0.6 :class:`.PassiveDefault` is deprecated.
+ .. deprecated:: 0.6
+ :class:`.PassiveDefault` is deprecated.
Use :class:`.DefaultClause`.
"""
@util.deprecated("0.6",
:param schema:
The default schema to use for the :class:`.Table`, :class:`.Sequence`, and other
objects associated with this :class:`.MetaData`.
- Defaults to ``None``. New in 0.7.4.
-
+ Defaults to ``None``.
+
:param quote_schema:
Sets the ``quote_schema`` flag for those :class:`.Table`, :class:`.Sequence`,
and other objects which make usage of the local ``schema`` name.
- New in 0.7.4.
+
+ .. versionadded:: 0.7.4
+ ``schema`` and ``quote_schema`` parameters.
"""
self.tables = util.immutabledict()
class CreateSchema(_CreateDropBase):
"""Represent a CREATE SCHEMA statement.
- New in 0.7.4.
+ .. versionadded:: 0.7.4
The argument here is the string name of the schema.
The argument here is the string name of the schema.
- New in 0.7.4.
+ .. versionadded:: 0.7.4
+
"""
__visit_name__ = "drop_schema"
* With the Oracle and Postgresql dialects, the value ``"nowait"``
translates to ``FOR UPDATE NOWAIT``.
* With the Postgresql dialect, the values "read" and ``"read_nowait"``
- translate to ``FOR SHARE`` and ``FOR SHARE NOWAIT``, respectively
- (new in 0.7.7).
+ translate to ``FOR SHARE`` and ``FOR SHARE NOWAIT``, respectively.
+
+ .. versionadded:: 0.7.7
:param group_by:
a list of :class:`.ClauseElement` objects which will comprise the
may prefer to use the generative :meth:`~Update.where()`
method to specify the ``WHERE`` clause.
- The WHERE clause can refer to multiple tables as of version 0.7.4.
+ The WHERE clause can refer to multiple tables.
For databases which support this, an ``UPDATE FROM`` clause will
be generated, or on MySQL, a multi-table update. The statement
will fail on databases that don't have support for multi-table
as_scalar()
)
+ .. versionchanged:: 0.7.4
+ The WHERE clause can refer to multiple tables.
+
:param values:
Optional dictionary which specifies the ``SET`` conditions of the
``UPDATE``. If left as ``None``, the ``SET``
This function is also available from the :attr:`~.expression.func`
construct itself via the :meth:`.FunctionElement.over` method.
- New in 0.7.
+ .. versionadded:: 0.7
"""
return _Over(func, partition_by=partition_by, order_by=order_by)
See :func:`~.expression.over` for a full description.
- New in 0.7.
+ .. versionadded:: 0.7
"""
return over(self, partition_by=partition_by, order_by=order_by)
:meth:`._SelectBase.cte` method from any selectable.
See that method for complete examples.
- New in 0.7.6.
+ .. versionadded:: 0.7.6
"""
__visit_name__ = 'cte'
to be delivered to the FROM clause of the statement as well
as to a WITH clause at the top of the statement.
- The :meth:`._SelectBase.cte` method is new in 0.7.6.
-
+ .. versionadded:: 0.7.6
+
:param name: name given to the common table expression. Like
:meth:`._FromClause.alias`, the name can be left as ``None``
in which case an anonymous symbol will be used at query
"""Return a new :func:`.select` construct with its columns
clause replaced with the given columns.
- .. note::
-
- Due to a bug fix, this method has a slight
- behavioral change as of version 0.7.3.
- Prior to version 0.7.3, the FROM clause of
- a :func:`.select` was calculated upfront and as new columns
- were added; in 0.7.3 and later it's calculated
- at compile time, fixing an issue regarding late binding
- of columns to parent tables. This changes the behavior of
- :meth:`.Select.with_only_columns` in that FROM clauses no
- longer represented in the new list are dropped,
- but this behavior is more consistent in
- that the FROM clauses are consistently derived from the
- current columns clause. The original intent of this method
- is to allow trimming of the existing columns list to be fewer
- columns than originally present; the use case of replacing
- the columns list with an entirely different one hadn't
- been anticipated until 0.7.3 was released; the usage
- guidelines below illustrate how this should be done.
-
+ .. versionchanged:: 0.7.3
+ Due to a bug fix, this method has a slight
+ behavioral change as of version 0.7.3.
+ Prior to version 0.7.3, the FROM clause of
+ a :func:`.select` was calculated upfront and as new columns
+ were added; in 0.7.3 and later it's calculated
+ at compile time, fixing an issue regarding late binding
+ of columns to parent tables. This changes the behavior of
+ :meth:`.Select.with_only_columns` in that FROM clauses no
+ longer represented in the new list are dropped,
+ but this behavior is more consistent in
+ that the FROM clauses are consistently derived from the
+ current columns clause. The original intent of this method
+ is to allow trimming of the existing columns list to be fewer
+ columns than originally present; the use case of replacing
+ the columns list with an entirely different one hadn't
+ been anticipated until 0.7.3 was released; the usage
+ guidelines below illustrate how this should be done.
+
This method is exactly equivalent to as if the original
:func:`.select` had been called with the given columns
clause. I.e. a statement::
mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
- New in 0.7.6.
+ .. versionadded:: 0.7.6
:param text: Text of the hint.
:param selectable: optional :class:`.Table` that specifies
:param dialect_name: base name of the dialect which uses
this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
- New in 0.7.2.
+ .. versionadded:: 0.7.2
"""
return Variant(self, {dialect_name:type_})
The :class:`.Variant` type is typically constructed
using the :meth:`.TypeEngine.with_variant` method.
- New in 0.7.2.
+ .. versionadded:: 0.7.2
"""
:param dialect_name: base name of the dialect which uses
this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
- New in 0.7.2.
-
"""
if dialect_name in self.mapping:
a mutable Python object type. This functionality is used
only by the ORM.
- .. note::
-
- :class:`.MutableType` is superseded as of SQLAlchemy 0.7
+ .. versionchanged:: 0.7
+ :class:`.MutableType` is superseded
by the ``sqlalchemy.ext.mutable`` extension described in
:ref:`mutable_toplevel`. This extension provides an event
driven approach to in-place mutation detection that does not
the 6000 objects that have mutable attributes, possibly resulting
in tens of thousands of additional method calls for every query.
- As of SQLAlchemy 0.7, the ``sqlalchemy.ext.mutable`` is provided which
- allows an event driven approach to in-place mutation detection. This
- approach should now be favored over the usage of :class:`.MutableType`
- with ``mutable=True``. ``sqlalchemy.ext.mutable`` is described in
- :ref:`mutable_toplevel`.
+ .. versionchanged:: 0.7
+ As of SQLAlchemy 0.7, the ``sqlalchemy.ext.mutable`` is provided
+ which allows an event driven approach to in-place
+ mutation detection. This approach should now be favored over
+ the usage of :class:`.MutableType` with ``mutable=True``.
+ ``sqlalchemy.ext.mutable`` is described in :ref:`mutable_toplevel`.
"""
using the Python "equals" operator, unless the
``comparator`` argument is present. See
:class:`.MutableType` for details on "mutable" type
- behavior. (default changed from ``True`` in
- 0.7.0).
+ behavior.
+
+ .. versionchanged:: 0.7.0
+ Default changed from ``True``.
.. note::
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
