[Python-modules-commits] [sqlalchemy] 02/04: Import sqlalchemy_1.0.11+ds1.orig.tar.gz
Piotr Ożarowski
piotr at moszumanska.debian.org
Fri Dec 25 18:39:38 UTC 2015
This is an automated email from the git hooks/post-receive script.
piotr pushed a commit to branch master
in repository sqlalchemy.
commit 02b25c3281c335209e797e1dc5234f23cf7727a0
Author: Piotr Ożarowski <piotr at debian.org>
Date: Fri Dec 25 18:59:34 2015 +0100
Import sqlalchemy_1.0.11+ds1.orig.tar.gz
---
PKG-INFO | 2 +-
doc/build/changelog/changelog_09.rst | 2 +-
doc/build/changelog/changelog_10.rst | 307 +++++++++++++++
doc/build/changelog/migration_10.rst | 2 +-
doc/build/conf.py | 4 +-
doc/build/core/defaults.rst | 22 +-
doc/build/core/event.rst | 6 +-
doc/build/core/metadata.rst | 5 -
doc/build/core/pooling.rst | 97 +++--
doc/build/core/tutorial.rst | 245 +++++++-----
doc/build/dialects/index.rst | 2 +-
doc/build/faq/sessions.rst | 2 +-
doc/build/orm/basic_relationships.rst | 96 ++++-
doc/build/orm/extensions/baked.rst | 8 +
doc/build/orm/loading_relationships.rst | 44 +++
doc/build/orm/mapped_sql_expr.rst | 2 +-
doc/build/orm/session_events.rst | 5 +-
doc/build/orm/tutorial.rst | 274 ++++++-------
doc/build/testdocs.py | 69 ----
lib/sqlalchemy/__init__.py | 2 +-
lib/sqlalchemy/dialects/mssql/base.py | 18 +-
lib/sqlalchemy/dialects/mssql/pymssql.py | 3 +-
lib/sqlalchemy/dialects/mysql/base.py | 14 +-
lib/sqlalchemy/dialects/postgresql/base.py | 12 +-
lib/sqlalchemy/dialects/postgresql/constraints.py | 2 +-
lib/sqlalchemy/engine/result.py | 2 +-
lib/sqlalchemy/events.py | 5 +
lib/sqlalchemy/ext/associationproxy.py | 4 +-
lib/sqlalchemy/ext/automap.py | 2 +-
lib/sqlalchemy/ext/baked.py | 9 +-
lib/sqlalchemy/ext/declarative/clsregistry.py | 3 +-
lib/sqlalchemy/ext/mutable.py | 10 +
lib/sqlalchemy/orm/__init__.py | 5 +
lib/sqlalchemy/orm/collections.py | 3 +-
lib/sqlalchemy/orm/dependency.py | 8 +-
lib/sqlalchemy/orm/events.py | 7 +-
lib/sqlalchemy/orm/mapper.py | 14 +-
lib/sqlalchemy/orm/persistence.py | 63 ++-
lib/sqlalchemy/orm/query.py | 181 ++++++++-
lib/sqlalchemy/orm/relationships.py | 26 +-
lib/sqlalchemy/orm/session.py | 18 +-
lib/sqlalchemy/orm/strategies.py | 16 +-
lib/sqlalchemy/orm/util.py | 6 +-
lib/sqlalchemy/sql/compiler.py | 6 +-
lib/sqlalchemy/sql/crud.py | 19 +-
lib/sqlalchemy/sql/dml.py | 164 +++++---
lib/sqlalchemy/sql/schema.py | 12 +-
lib/sqlalchemy/sql/type_api.py | 20 +
lib/sqlalchemy/sql/util.py | 1 -
lib/sqlalchemy/testing/assertions.py | 2 +-
lib/sqlalchemy/testing/assertsql.py | 17 +-
lib/sqlalchemy/testing/exclusions.py | 7 +-
lib/sqlalchemy/testing/fixtures.py | 10 +
lib/sqlalchemy/util/__init__.py | 2 +-
lib/sqlalchemy/util/compat.py | 1 +
lib/sqlalchemy/util/langhelpers.py | 8 +-
test/base/test_tutorials.py | 144 +++++++
test/base/test_utils.py | 5 +-
test/dialect/mssql/test_types.py | 122 +++++-
test/dialect/mysql/test_reflection.py | 325 +++++++++++-----
test/dialect/postgresql/test_compiler.py | 29 ++
test/dialect/postgresql/test_types.py | 18 +
test/ext/declarative/test_basic.py | 23 ++
test/ext/test_baked.py | 92 ++++-
test/ext/test_mutable.py | 49 ++-
test/orm/inheritance/test_relationship.py | 272 ++++++++++++-
test/orm/test_cycles.py | 49 ++-
test/orm/test_eager_relations.py | 113 +++++-
test/orm/test_query.py | 33 ++
test/orm/test_session.py | 3 +-
test/orm/test_transaction.py | 28 ++
test/orm/test_unitofworkv2.py | 447 +++++++++++++++++++++-
test/orm/test_update_delete.py | 39 +-
test/orm/test_versioning.py | 56 ++-
test/requirements.py | 4 +
test/sql/test_compiler.py | 26 +-
test/sql/test_insert.py | 26 ++
test/sql/test_returning.py | 27 ++
test/sql/test_update.py | 124 ++++++
tox.ini | 9 +-
80 files changed, 3324 insertions(+), 635 deletions(-)
diff --git a/PKG-INFO b/PKG-INFO
index fb1c2a9..ac53786 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,6 +1,6 @@
Metadata-Version: 1.1
Name: SQLAlchemy
-Version: 1.0.9
+Version: 1.0.11
Summary: Database Abstraction Library
Home-page: http://www.sqlalchemy.org
Author: Mike Bayer
diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index be88729..ace2242 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -1631,7 +1631,7 @@
with pytest.
The test plugin system has also been enhanced to support running
- tests against mutiple database URLs at once, by specifying the ``--db``
+ tests against multiple database URLs at once, by specifying the ``--db``
and/or ``--dburi`` flags multiple times. This does not run the entire test
suite for each database, but instead allows test cases that are specific
to certain backends make use of that backend as the test is run.
diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 2442ac7..25592a3 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -16,6 +16,313 @@
:start-line: 5
.. changelog::
+ :version: 1.0.11
+ :released: December 22, 2015
+
+ .. change::
+ :tags: bug, mysql
+ :versions: 1.1.0b1
+ :tickets: 3613
+
+ An adjustment to the regular expression used to parse MySQL views,
+ such that we no longer assume the "ALGORITHM" keyword is present in
+ the reflected view source, as some users have reported this not being
+ present in some Amazon RDS environments.
+
+ .. change::
+ :tags: bug, mysql
+ :versions: 1.1.0b1
+ :pullreq: github:222
+
+ Added new reserved words for MySQL 5.7 to the MySQL dialect,
+ including 'generated', 'optimizer_costs', 'stored', 'virtual'.
+ Pull request courtesy Hanno Schlichting.
+
+ .. change::
+ :tags: bug, ext
+ :tickets: 3605
+ :versions: 1.1.0b1
+
+ Further fixes to :ticket:`3605`, pop method on :class:`.MutableDict`,
+ where the "default" argument was not included.
+
+ .. change::
+ :tags: bug, ext
+ :tickets: 3612
+ :versions: 1.1.0b1
+
+ Fixed bug in baked loader system where the systemwide monkeypatch
+ for setting up baked lazy loaders would interfere with other
+ loader strategies that rely on lazy loading as a fallback, e.g.
+ joined and subquery eager loaders, leading to ``IndexError``
+ exceptions at mapper configuration time.
+
+ .. change::
+ :tags: bug, orm
+ :tickets: 3611
+ :versions: 1.1.0b1
+
+ Fixed regression caused in 1.0.10 by the fix for :ticket:`3593` where
+ the check added for a polymorphic joinedload from a
+ poly_subclass->class->poly_baseclass connection would fail for the
+ scenario of class->poly_subclass->class.
+
+ .. change::
+ :tags: bug, orm
+ :tickets: 3610
+ :versions: 1.1.0b1
+
+ Fixed bug where :meth:`.Session.bulk_update_mappings` and related
+ would not bump a version id counter when in use. The experience
+ here is still a little rough as the original version id is required
+ in the given dictionaries and there's not clean error reporting
+ on that yet.
+
+ .. change::
+ :tags: bug, sql
+ :tickets: 3609
+ :versions: 1.1.0b1
+
+ Fixed bug in :meth:`.Update.return_defaults` which would cause all
+ insert-default holding columns not otherwise included in the SET
+ clause (such as primary key cols) to get rendered into the RETURNING
+ even though this is an UPDATE.
+
+ .. change::
+ :tags: bug, orm
+ :tickets: 3609
+ :versions: 1.1.0b1
+
+ Major fixes to the :paramref:`.Mapper.eager_defaults` flag, this
+ flag would not be honored correctly in the case that multiple
+ UPDATE statements were to be emitted, either as part of a flush
+ or a bulk update operation. Additionally, RETURNING
+ would be emitted unnecessarily within update statements.
+
+ .. change::
+ :tags: bug, orm
+ :tickets: 3606
+ :versions: 1.1.0b1
+
+ Fixed bug where use of the :meth:`.Query.select_from` method would
+ cause a subsequent call to the :meth:`.Query.with_parent` method to
+ fail.
+
+.. changelog::
+ :version: 1.0.10
+ :released: December 11, 2015
+
+ .. change::
+ :tags: bug, ext
+ :tickets: 3605
+ :versions: 1.1.0b1
+
+ Added support for the ``dict.pop()`` and ``dict.popitem()`` methods
+ to the :class:`.mutable.MutableDict` class.
+
+ .. change::
+ :tags: change, tests
+ :versions: 1.1.0b1
+
+ The ORM and Core tutorials, which have always been in doctest format,
+ are now exercised within the normal unit test suite in both Python
+ 2 and Python 3.
+
+ .. change::
+ :tags: bug, sql
+ :tickets: 3603
+ :versions: 1.1.0b1
+
+ Fixed issue within the :meth:`.Insert.from_select` construct whereby
+ the :class:`.Select` construct would have its ``._raw_columns``
+ collection mutated in-place when compiling the :class:`.Insert`
+ construct, when the target :class:`.Table` has Python-side defaults.
+ The :class:`.Select` construct would compile standalone with the
+ erroneous column present subsequent to compilation of the
+ :class:`.Insert`, and the the :class:`.Insert` statement itself would
+ fail on a second compile attempt due to duplicate bound parameters.
+
+ .. change::
+ :tags: bug, mysql
+ :tickets: 3602
+ :versions: 1.1.0b1
+
+ Fixed bug in MySQL reflection where the "fractional sections portion"
+ of the :class:`.mysql.DATETIME`, :class:`.mysql.TIMESTAMP` and
+ :class:`.mysql.TIME` types would be incorrectly placed into the
+ ``timezone`` attribute, which is unused by MySQL, instead of the
+ ``fsp`` attribute.
+
+ .. change::
+ :tags: bug, orm
+ :tickets: 3599
+ :versions: 1.1.0b1
+
+ Fixed issue where post_update on a many-to-one relationship would
+ fail to emit an UPDATE in the case where the attribute were set to
+ None and not previously loaded.
+
+ .. change::
+ :tags: bug, sql, postgresql
+ :tickets: 3598
+ :versions: 1.1.0b1
+
+ Fixed bug where CREATE TABLE with a no-column table, but a constraint
+ such as a CHECK constraint would render an erroneous comma in the
+ definition; this scenario can occur such as with a Postgresql
+ INHERITS table that has no columns of its own.
+
+ .. change::
+ :tags: bug, mssql
+ :tickets: 3585
+ :versions: 1.1.0b1
+
+ Added the error "20006: Write to the server failed" to the list
+ of disconnect errors for the pymssql driver, as this has been observed
+ to render a connection unusable.
+
+ .. change::
+ :tags: bug, postgresql
+ :pullreq: github:216
+ :tickets: 3573
+ :versions: 1.1.0b1
+
+ Fixed issue where the "FOR UPDATE OF" Postgresql-specific SELECT
+ modifier would fail if the referred table had a schema qualifier;
+ PG needs the schema name to be omitted. Pull request courtesy
+ Diana Clarke.
+
+ .. change::
+ :tags: bug, postgresql
+ :pullreq: github:215
+ :versions: 1.1.0b1
+
+ Fixed bug where some varieties of SQL expression passed to the
+ "where" clause of :class:`.postgresql.ExcludeConstraint` would fail
+ to be accepted correctly. Pull request courtesy aisch.
+
+ .. change::
+ :tags: bug, orm, declarative
+ :pullreq: github:212
+ :versions: 1.1.0b1
+
+ Fixed bug where in Py2K a unicode literal would not be accepted as the
+ string name of a class or other argument within declarative using
+ :func:`.backref` on :func:`.relationship`. Pull request courtesy
+ Nils Philippsen.
+
+ .. change::
+ :tags: bug, mssql
+ :versions: 1.1.0b1
+ :pullreq: github:206
+
+ A descriptive ValueError is now raised in the event that SQL server
+ returns an invalid date or time format from a DATE or TIME
+ column, rather than failing with a NoneType error. Pull request
+ courtesy Ed Avis.
+
+ .. change::
+ :tags: bug, py3k
+ :versions: 1.1.0b1
+ :pullreq: github:210, github:218, github:211
+
+ Updates to internal getargspec() calls, some py36-related
+ fixture updates, and alterations to two iterators to "return" instead
+ of raising StopIteration, to allow tests to pass without
+ errors or warnings on Py3.5, Py3.6, pull requests courtesy
+ Jacob MacDonald, Luri de Silvio, and Phil Jones.
+
+ .. change::
+ :tags: bug, ext
+ :versions: 1.1.0b1
+ :tickets: 3597
+
+ Fixed an issue in baked queries where the .get() method, used either
+ directly or within lazy loads, didn't consider the mapper's "get clause"
+ as part of the cache key, causing bound parameter mismatches if the
+ clause got re-generated. This clause is cached by mappers
+ on the fly but in highly concurrent scenarios may be generated more
+ than once when first accessed.
+
+ .. change::
+ :tags: feature, sql
+ :versions: 1.1.0b1
+ :pullreq: github:200
+
+ Added support for parameter-ordered SET clauses in an UPDATE
+ statement. This feature is available by passing the
+ :paramref:`~.sqlalchemy.sql.expression.update.preserve_parameter_order`
+ flag either to the core :class:`.Update` construct or alternatively
+ adding it to the :paramref:`.Query.update.update_args` dictionary at
+ the ORM-level, also passing the parameters themselves as a list of 2-tuples.
+ Thanks to Gorka Eguileor for implementation and tests.
+
+ .. seealso::
+
+ :ref:`updates_order_parameters`
+
+ .. change::
+ :tags: bug, orm
+ :versions: 1.1.0b1
+ :tickets: 3593
+
+ Fixed bug which is actually a regression that occurred between
+ versions 0.8.0 and 0.8.1, due :ticket:`2714`. The case where
+ joined eager loading needs to join out over a subclass-bound
+ relationship when "with_polymorphic" were also used would fail
+ to join from the correct entity.
+
+ .. change::
+ :tags: bug, orm
+ :versions: 1.1.0b1
+ :tickets: 3592
+
+ Fixed joinedload bug which would occur when a. the query includes
+ limit/offset criteria that forces a subquery b. the relationship
+ uses "secondary" c. the primaryjoin of the relationship refers to
+ a column that is either not part of the primary key, or is a PK
+ col in a joined-inheritance subclass table that is under a different
+ attribute name than the parent table's primary key column d. the
+ query defers the columns that are present in the primaryjoin, typically
+ via not being included in load_only(); the necessary column(s) would
+ not be present in the subquery and produce invalid SQL.
+
+ .. change::
+ :tags: bug, orm
+ :versions: 1.1.0b1
+ :tickets: 2696
+
+ A rare case which occurs when a :meth:`.Session.rollback` fails in the
+ scope of a :meth:`.Session.flush` operation that's raising an
+ exception, as has been observed in some MySQL SAVEPOINT cases, prevents
+ the original database exception from being observed when it was
+ emitted during flush, but only on Py2K because Py2K does not support
+ exception chaining; on Py3K the originating exception is chained. As
+ a workaround, a warning is emitted in this specific case showing at
+ least the string message of the original database error before we
+ proceed to raise the rollback-originating exception.
+
+ .. change::
+ :tags: bug, postgresql
+ :versions: 1.1.0b1
+ :tickets: 3571
+
+ Fixed the ``.python_type`` attribute of :class:`.postgresql.INTERVAL`
+ to return ``datetime.timedelta`` in the same way as that of
+ :obj:`.types.Interval.python_type`, rather than raising
+ ``NotImplementedError``.
+
+ .. change::
+ :tags: bug, mssql
+ :pullreq: github:213
+ :versions: 1.1.0b1
+
+ Fixed issue where DDL generated for the MSSQL types DATETIME2,
+ TIME and DATETIMEOFFSET with a precision of "zero" would not generate
+ the precision field. Pull request courtesy Jacobo de Vera.
+
+
+.. changelog::
:version: 1.0.9
:released: October 20, 2015
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index 08e26fd..a4fbf11 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -2305,7 +2305,7 @@ Postgresql Dialect reflects Materialized Views, Foreign Tables
Changes are as follows:
* the :class:`Table` construct with ``autoload=True`` will now match a name
- that exists in the database as a materialized view or foriegn table.
+ that exists in the database as a materialized view or foreign table.
* :meth:`.Inspector.get_view_names` will return plain and materialized view
names.
diff --git a/doc/build/conf.py b/doc/build/conf.py
index 4cc4eb1..f3061b6 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -138,9 +138,9 @@ copyright = u'2007-2015, the SQLAlchemy authors and contributors'
# The short X.Y version.
version = "1.0"
# The full version, including alpha/beta/rc tags.
-release = "1.0.9"
+release = "1.0.11"
-release_date = "October 20, 2015"
+release_date = "December 12, 2015"
site_base = os.environ.get("RTD_SITE_BASE", "http://www.sqlalchemy.org")
site_adapter_template = "docs_adapter.mako"
diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst
index 4166ac4..a7287a3 100644
--- a/doc/build/core/defaults.rst
+++ b/doc/build/core/defaults.rst
@@ -45,7 +45,7 @@ defaults)::
Python-Executed Functions
-------------------------
-The ``default`` and ``onupdate`` keyword arguments also accept Python
+The :paramref:`.Column.default` and :paramref:`.Column.onupdate` keyword arguments also accept Python
functions. These functions are invoked at the time of insert or update if no
other value for that column is supplied, and the value returned is used for
the column's value. Below illustrates a crude "sequence" that assigns an
@@ -67,12 +67,12 @@ built-in capabilities of the database should normally be used, which may
include sequence objects or other autoincrementing capabilities. For primary
key columns, SQLAlchemy will in most cases use these capabilities
automatically. See the API documentation for
-:class:`~sqlalchemy.schema.Column` including the ``autoincrement`` flag, as
+:class:`~sqlalchemy.schema.Column` including the :paramref:`.Column.autoincrement` flag, as
well as the section on :class:`~sqlalchemy.schema.Sequence` later in this
chapter for background on standard primary key generation techniques.
To illustrate onupdate, we assign the Python ``datetime`` function ``now`` to
-the ``onupdate`` attribute::
+the :paramref:`.Column.onupdate` attribute::
import datetime
@@ -93,7 +93,7 @@ executes.
Context-Sensitive Default Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The Python functions used by ``default`` and ``onupdate`` may also make use of
+The Python functions used by :paramref:`.Column.default` and :paramref:`.Column.onupdate` may also make use of
the current statement's context in order to determine a value. The `context`
of a statement is an internal SQLAlchemy object which contains all information
about the statement being executed, including its source expression, the
@@ -185,21 +185,23 @@ performance reasons.
When the statement is executed with a single set of parameters (that is, it is
not an "executemany" style execution), the returned
:class:`~sqlalchemy.engine.ResultProxy` will contain a collection
-accessible via ``result.postfetch_cols()`` which contains a list of all
+accessible via :meth:`.ResultProxy.postfetch_cols` which contains a list of all
:class:`~sqlalchemy.schema.Column` objects which had an inline-executed
default. Similarly, all parameters which were bound to the statement,
including all Python and SQL expressions which were pre-executed, are present
-in the ``last_inserted_params()`` or ``last_updated_params()`` collections on
-:class:`~sqlalchemy.engine.ResultProxy`. The ``inserted_primary_key``
+in the :meth:`.ResultProxy.last_inserted_params` or :meth:`.ResultProxy.last_updated_params` collections on
+:class:`~sqlalchemy.engine.ResultProxy`. The :attr:`.ResultProxy.inserted_primary_key`
collection contains a list of primary key values for the row inserted (a list
so that single-column and composite-column primary keys are represented in the
same format).
+.. _server_defaults:
+
Server Side Defaults
--------------------
-A variant on the SQL expression default is the ``server_default``, which gets
-placed in the CREATE TABLE statement during a ``create()`` operation:
+A variant on the SQL expression default is the :paramref:`.Column.server_default`, which gets
+placed in the CREATE TABLE statement during a :meth:`.Table.create` operation:
.. sourcecode:: python+sql
@@ -215,7 +217,7 @@ A create call for the above table will produce::
created_at datetime default sysdate
)
-The behavior of ``server_default`` is similar to that of a regular SQL
+The behavior of :paramref:`.Column.server_default` is similar to that of a regular SQL
default; if it's placed on a primary key column for a database which doesn't
have a way to "postfetch" the ID, and the statement is not "inlined", the SQL
expression is pre-executed; otherwise, SQLAlchemy lets the default fire off on
diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst
index e6f6c9e..ced81a6 100644
--- a/doc/build/core/event.rst
+++ b/doc/build/core/event.rst
@@ -14,9 +14,9 @@ Event Registration
------------------
Subscribing to an event occurs through a single API point, the :func:`.listen` function,
-or alternatively the :func:`.listens_for` decorator. These functions
-accept a user-defined listening function, a string identifier which identifies the event to be
-intercepted, and a target. Additional positional and keyword arguments to these
+or alternatively the :func:`.listens_for` decorator. These functions accept a
+target, a string identifier which identifies the event to be intercepted, and
+a user-defined listening function. Additional positional and keyword arguments to these
two functions may be supported by
specific types of events, which may specify alternate interfaces for the given event function, or provide
instructions regarding secondary event targets based on the given target.
diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst
index c04de15..1eade1c 100644
--- a/doc/build/core/metadata.rst
+++ b/doc/build/core/metadata.rst
@@ -306,26 +306,21 @@ Column, Table, MetaData API
.. autoclass:: Column
:members:
:inherited-members:
- :undoc-members:
.. autoclass:: MetaData
:members:
- :undoc-members:
.. autoclass:: SchemaItem
:members:
- :undoc-members:
.. autoclass:: Table
:members:
:inherited-members:
- :undoc-members:
.. autoclass:: ThreadLocalMetaData
:members:
- :undoc-members:
diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst
index ce6d443..f9384fd 100644
--- a/doc/build/core/pooling.rst
+++ b/doc/build/core/pooling.rst
@@ -209,6 +209,8 @@ correspond to a single request failing with a 500 error, then the web applicatio
continuing normally beyond that. Hence the approach is "optimistic" in that frequent
database restarts are not anticipated.
+.. _pool_setting_recycle:
+
Setting Pool Recycle
~~~~~~~~~~~~~~~~~~~~~~~
@@ -231,9 +233,55 @@ of the :class:`.Pool` itself, independent of whether or not an :class:`.Engine`
Disconnect Handling - Pessimistic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-At the expense of some extra SQL emitted for each connection checked out from the pool,
-a "ping" operation established by a checkout event handler
-can detect an invalid connection before it is used::
+At the expense of some extra SQL emitted for each connection checked out from
+the pool, a "ping" operation established by a checkout event handler can
+detect an invalid connection before it is used. In modern SQLAlchemy, the
+best way to do this is to make use of the
+:meth:`.ConnectionEvents.engine_connect` event, assuming the use of a
+:class:`.Engine` and not just a raw :class:`.Pool` object::
+
+ from sqlalchemy import exc
+ from sqlalchemy import event
+ from sqlalchemy import select
+
+ some_engine = create_engine(...)
+
+ @event.listens_for(some_engine, "engine_connect")
+ def ping_connection(connection, branch):
+ if branch:
+ # "branch" refers to a sub-connection of a connection,
+ # we don't want to bother pinging on these.
+ return
+
+ try:
+ # run a SELECT 1. use a core select() so that
+ # the SELECT of a scalar value without a table is
+ # appropriately formatted for the backend
+ connection.scalar(select([1]))
+ except exc.DBAPIError as err:
+ # catch SQLAlchemy's DBAPIError, which is a wrapper
+ # for the DBAPI's exception. It includes a .connection_invalidated
+ # attribute which specifies if this connection is a "disconnect"
+ # condition, which is based on inspection of the original exception
+ # by the dialect in use.
+ if err.connection_invalidated:
+ # run the same SELECT again - the connection will re-validate
+ # itself and establish a new connection. The disconnect detection
+ # here also causes the whole connection pool to be invalidated
+ # so that all stale connections are discarded.
+ connection.scalar(select([1]))
+ else:
+ raise
+
+The above recipe has the advantage that we are making use of SQLAlchemy's
+facilities for detecting those DBAPI exceptions that are known to indicate
+a "disconnect" situation, as well as the :class:`.Engine` object's ability
+to correctly invalidate the current connection pool when this condition
+occurs and allowing the current :class:`.Connection` to re-validate onto
+a new DBAPI connection.
+
+For the much less common case of where a :class:`.Pool` is being used without
+an :class:`.Engine`, an older approach may be used as below::
from sqlalchemy import exc
from sqlalchemy import event
@@ -245,46 +293,19 @@ can detect an invalid connection before it is used::
try:
cursor.execute("SELECT 1")
except:
- # optional - dispose the whole pool
- # instead of invalidating one at a time
- # connection_proxy._pool.dispose()
-
# raise DisconnectionError - pool will try
# connecting again up to three times before raising.
raise exc.DisconnectionError()
cursor.close()
-Above, the :class:`.Pool` object specifically catches :class:`~sqlalchemy.exc.DisconnectionError` and attempts
-to create a new DBAPI connection, up to three times, before giving up and then raising
-:class:`~sqlalchemy.exc.InvalidRequestError`, failing the connection. This recipe will ensure
-that a new :class:`.Connection` will succeed even if connections
-in the pool have gone stale, provided that the database server is actually running. The expense
-is that of an additional execution performed per checkout. When using the ORM :class:`.Session`,
-there is one connection checkout per transaction, so the expense is fairly low. The ping approach
-above also works with straight connection pool usage, that is, even if no :class:`.Engine` were
-involved.
-
-The event handler can be tested using a script like the following, restarting the database
-server at the point at which the script pauses for input::
-
- from sqlalchemy import create_engine
- e = create_engine("mysql://scott:tiger@localhost/test", echo_pool=True)
- c1 = e.connect()
- c2 = e.connect()
- c3 = e.connect()
- c1.close()
- c2.close()
- c3.close()
-
- # pool size is now three.
-
- print "Restart the server"
- raw_input()
-
- for i in xrange(10):
- c = e.connect()
- print c.execute("select 1").fetchall()
- c.close()
+Above, the :class:`.Pool` object specifically catches
+:class:`~sqlalchemy.exc.DisconnectionError` and attempts to create a new DBAPI
+connection, up to three times, before giving up and then raising
+:class:`~sqlalchemy.exc.InvalidRequestError`, failing the connection. The
+disadvantage of the above approach is that we don't have any easy way of
+determining if the exception raised is in fact a "disconnect" situation, since
+there is no :class:`.Engine` or :class:`.Dialect` in play, and also the above
+error would occur individually for all stale connections still in the pool.
.. _pool_connection_invalidation:
diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index e660e2d..b52d194 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -149,11 +149,8 @@ each table first before creating, so it's safe to call multiple times:
.. sourcecode:: pycon+sql
- {sql}>>> metadata.create_all(engine) #doctest: +NORMALIZE_WHITESPACE
- PRAGMA table_info("users")
- ()
- PRAGMA table_info("addresses")
- ()
+ {sql}>>> metadata.create_all(engine)
+ SE...
CREATE TABLE users (
id INTEGER NOT NULL,
name VARCHAR,
@@ -243,7 +240,7 @@ data consists of literal values, SQLAlchemy automatically generates bind
parameters for them. We can peek at this data for now by looking at the
compiled form of the statement::
- >>> ins.compile().params #doctest: +NORMALIZE_WHITESPACE
+ >>> ins.compile().params # doctest: +SKIP
{'fullname': 'Jack Jones', 'name': 'jack'}
Executing
@@ -257,7 +254,7 @@ connections capable of issuing SQL to the database. To acquire a connection,
we use the ``connect()`` method::
>>> conn = engine.connect()
- >>> conn #doctest: +ELLIPSIS
+ >>> conn
<sqlalchemy.engine.base.Connection object at 0x...>
The :class:`~sqlalchemy.engine.Connection` object represents an actively
@@ -290,7 +287,8 @@ the SQLAlchemy :class:`~sqlalchemy.engine.Connection` object references a
DBAPI connection, the result, known as a
:class:`~sqlalchemy.engine.ResultProxy` object, is analogous to the DBAPI
cursor object. In the case of an INSERT, we can get important information from
-it, such as the primary key values which were generated from our statement:
+it, such as the primary key values which were generated from our statement
+using :attr:`.ResultProxy.inserted_primary_key`:
.. sourcecode:: pycon+sql
@@ -304,8 +302,11 @@ value would have been used. In either case, SQLAlchemy always knows how to get
at a newly generated primary key value, even though the method of generating
them is different across different databases; each database's
:class:`~sqlalchemy.engine.interfaces.Dialect` knows the specific steps needed to
-determine the correct value (or values; note that ``inserted_primary_key``
-returns a list so that it supports composite primary keys).
+determine the correct value (or values; note that
+:attr:`.ResultProxy.inserted_primary_key`
+returns a list so that it supports composite primary keys). Methods here
+range from using ``cursor.lastrowid``, to selecting from a database-specific
+function, to using ``INSERT..RETURNING`` syntax; this all occurs transparently.
.. _execute_multiple:
@@ -324,7 +325,7 @@ and use it in the "normal" way:
.. sourcecode:: pycon+sql
>>> ins = users.insert()
- >>> conn.execute(ins, id=2, name='wendy', fullname='Wendy Williams') # doctest: +ELLIPSIS
+ >>> conn.execute(ins, id=2, name='wendy', fullname='Wendy Williams')
{opensql}INSERT INTO users (id, name, fullname) VALUES (?, ?, ?)
(2, 'wendy', 'Wendy Williams')
COMMIT
@@ -343,7 +344,7 @@ inserted, as we do here to add some email addresses:
.. sourcecode:: pycon+sql
- >>> conn.execute(addresses.insert(), [ # doctest: +ELLIPSIS
+ >>> conn.execute(addresses.insert(), [
... {'user_id': 1, 'email_address' : 'jack at yahoo.com'},
... {'user_id': 1, 'email_address' : 'jack at msn.com'},
... {'user_id': 2, 'email_address' : 'www at www.org'},
@@ -382,7 +383,7 @@ statements is the :func:`.select` function:
>>> from sqlalchemy.sql import select
>>> s = select([users])
- >>> result = conn.execute(s) # doctest: +NORMALIZE_WHITESPACE
+ >>> result = conn.execute(s)
{opensql}SELECT users.id, users.name, users.fullname
FROM users
()
@@ -400,7 +401,7 @@ rows from it is to just iterate:
.. sourcecode:: pycon+sql
>>> for row in result:
- ... print row
+ ... print(row)
(1, u'jack', u'Jack Jones')
(2, u'wendy', u'Wendy Williams')
@@ -410,13 +411,13 @@ through dictionary access, using the string names of columns:
.. sourcecode:: pycon+sql
- {sql}>>> result = conn.execute(s) # doctest: +NORMALIZE_WHITESPACE
+ {sql}>>> result = conn.execute(s)
SELECT users.id, users.name, users.fullname
FROM users
()
{stop}>>> row = result.fetchone()
- >>> print "name:", row['name'], "; fullname:", row['fullname']
+ >>> print("name:", row['name'], "; fullname:", row['fullname'])
name: jack ; fullname: Jack Jones
Integer indexes work as well:
@@ -424,7 +425,7 @@ Integer indexes work as well:
.. sourcecode:: pycon+sql
>>> row = result.fetchone()
- >>> print "name:", row[1], "; fullname:", row[2]
+ >>> print("name:", row[1], "; fullname:", row[2])
name: wendy ; fullname: Wendy Williams
But another way, whose usefulness will become apparent later on, is to use the
@@ -432,8 +433,8 @@ But another way, whose usefulness will become apparent later on, is to use the
.. sourcecode:: pycon+sql
- {sql}>>> for row in conn.execute(s): # doctest: +NORMALIZE_WHITESPACE
- ... print "name:", row[users.c.name], "; fullname:", row[users.c.fullname]
+ {sql}>>> for row in conn.execute(s):
+ ... print("name:", row[users.c.name], "; fullname:", row[users.c.fullname])
SELECT users.id, users.name, users.fullname
FROM users
()
@@ -460,12 +461,12 @@ the ``c`` attribute of the :class:`~sqlalchemy.schema.Table` object:
.. sourcecode:: pycon+sql
>>> s = select([users.c.name, users.c.fullname])
- {sql}>>> result = conn.execute(s) # doctest: +NORMALIZE_WHITESPACE
+ {sql}>>> result = conn.execute(s)
SELECT users.name, users.fullname
FROM users
()
- {stop}>>> for row in result: #doctest: +NORMALIZE_WHITESPACE
- ... print row
+ {stop}>>> for row in result:
+ ... print(row)
(u'jack', u'Jack Jones')
(u'wendy', u'Wendy Williams')
@@ -478,7 +479,7 @@ our :func:`.select` statement:
.. sourcecode:: pycon+sql
{sql}>>> for row in conn.execute(select([users, addresses])):
- ... print row # doctest: +NORMALIZE_WHITESPACE
+ ... print(row)
SELECT users.id, users.name, users.fullname, addresses.id, addresses.user_id, addresses.email_address
FROM users, addresses
()
@@ -501,7 +502,7 @@ WHERE clause. We do that using :meth:`.Select.where`:
>>> s = select([users, addresses]).where(users.c.id == addresses.c.user_id)
{sql}>>> for row in conn.execute(s):
- ... print row # doctest: +NORMALIZE_WHITESPACE
+ ... print(row)
SELECT users.id, users.name, users.fullname, addresses.id,
addresses.user_id, addresses.email_address
FROM users, addresses
@@ -523,8 +524,8 @@ a WHERE clause. So lets see exactly what that expression is doing:
.. sourcecode:: pycon+sql
- >>> users.c.id == addresses.c.user_id #doctest: +ELLIPSIS
- <sqlalchemy.sql.expression.BinaryExpression object at 0x...>
+ >>> users.c.id == addresses.c.user_id
+ <sqlalchemy.sql.elements.BinaryExpression object at 0x...>
Wow, surprise ! This is neither a ``True`` nor a ``False``. Well what is it ?
@@ -548,7 +549,7 @@ some of its capabilities. We've seen how to equate two columns to each other:
.. sourcecode:: pycon+sql
- >>> print users.c.id == addresses.c.user_id
+ >>> print(users.c.id == addresses.c.user_id)
users.id = addresses.user_id
If we use a literal value (a literal meaning, not a SQLAlchemy clause object),
@@ -556,7 +557,7 @@ we get a bind parameter:
.. sourcecode:: pycon+sql
- >>> print users.c.id == 7
+ >>> print(users.c.id == 7)
users.id = :id_1
The ``7`` literal is embedded the resulting
@@ -573,22 +574,22 @@ equals, not equals, etc.:
.. sourcecode:: pycon+sql
- >>> print users.c.id != 7
+ >>> print(users.c.id != 7)
users.id != :id_1
>>> # None converts to IS NULL
- >>> print users.c.name == None
+ >>> print(users.c.name == None)
users.name IS NULL
>>> # reverse works too
- >>> print 'fred' > users.c.name
+ >>> print('fred' > users.c.name)
users.name < :name_1
If we add two integer columns together, we get an addition expression:
.. sourcecode:: pycon+sql
- >>> print users.c.id + addresses.c.id
+ >>> print(users.c.id + addresses.c.id)
users.id + addresses.id
Interestingly, the type of the :class:`~sqlalchemy.schema.Column` is important!
@@ -599,7 +600,7 @@ something different:
.. sourcecode:: pycon+sql
- >>> print users.c.name + users.c.fullname
+ >>> print(users.c.name + users.c.fullname)
users.name || users.fullname
Where ``||`` is the string concatenation operator used on most databases. But
@@ -607,8 +608,8 @@ not all of them. MySQL users, fear not:
.. sourcecode:: pycon+sql
- >>> print (users.c.name + users.c.fullname).\
- ... compile(bind=create_engine('mysql://'))
+ >>> print((users.c.name + users.c.fullname).
+ ... compile(bind=create_engine('mysql://'))) # doctest: +SKIP
concat(users.name, users.fullname)
The above illustrates the SQL that's generated for an
@@ -620,7 +621,7 @@ always use the :meth:`.ColumnOperators.op` method; this generates whatever opera
.. sourcecode:: pycon+sql
- >>> print users.c.name.op('tiddlywinks')('foo')
+ >>> print(users.c.name.op('tiddlywinks')('foo'))
users.name tiddlywinks :name_1
This function can also be used to make bitwise operators explicit. For example::
@@ -656,15 +657,16 @@ a :meth:`~.ColumnOperators.like`):
.. sourcecode:: pycon+sql
>>> from sqlalchemy.sql import and_, or_, not_
- >>> print and_(
+ >>> print(and_(
... users.c.name.like('j%'),
- ... users.c.id == addresses.c.user_id, #doctest: +NORMALIZE_WHITESPACE
+ ... users.c.id == addresses.c.user_id,
... or_(
... addresses.c.email_address == 'wendy at aol.com',
... addresses.c.email_address == 'jack at yahoo.com'
... ),
... not_(users.c.id > 5)
... )
+ ... )
users.name LIKE :name_1 AND users.id = addresses.user_id AND
(addresses.email_address = :email_address_1
OR addresses.email_address = :email_address_2)
@@ -676,12 +678,13 @@ parenthesis:
.. sourcecode:: pycon+sql
- >>> print users.c.name.like('j%') & (users.c.id == addresses.c.user_id) & \
+ >>> print(users.c.name.like('j%') & (users.c.id == addresses.c.user_id) &
... (
... (addresses.c.email_address == 'wendy at aol.com') | \
... (addresses.c.email_address == 'jack at yahoo.com')
... ) \
- ... & ~(users.c.id>5) # doctest: +NORMALIZE_WHITESPACE
+ ... & ~(users.c.id>5)
+ ... )
users.name LIKE :name_1 AND users.id = addresses.user_id AND
(addresses.email_address = :email_address_1
OR addresses.email_address = :email_address_2)
@@ -712,7 +715,7 @@ not have a name:
... )
... )
... )
... 5857 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/sqlalchemy.git
More information about the Python-modules-commits
mailing list