This adds the very small plugin flake8-import-single which
will prevent us from having an import with more than one symbol
on a line.

Flake8 by itself prevents this pattern with E401:

import collections, os, sys

However does not do anything with this:

from sqlalchemy import Column, text

Both statements have the same issues generating merge artifacts
as well as presenting a manual decision to be made.   While
zimports generally cleans up such imports at the top level, we
don't enforce zimports / pre-commit use.

the plugin finds the same issue for imports that are inside of
test methods.   We shouldn't usually have imports in test methods
so most of them here are moved to be top level.

The version is pinned at 0.1.5; the project seems to have no
activity since 2019, however there are three 0.1.6dev releases
on pypi which stopped in September 2019, they seem to be
experiments with packaging.  The source for 0.1.5
is extremely simple and only reveals one method to flake8
(the run() method).

Change-Id: Icea894e43bad9c0b5d4feb5f49c6c666d6ea6aa1

Missing parenthesis in example code.

This patch adds new warnings for all elements that
don't indicate their caching behavior, including user-defined
ClauseElement subclasses and third party dialects.
it additionally adds new documentation to discuss an apparent
performance degradation in 1.4 when caching is disabled as a
result in the significant expense incurred by ORM
lazy loaders, which in 1.3 used BakedQuery so were actually
cached.

As a result of adding the warnings, a fair degree of
lesser used SQL expression objects identified that they did not
define caching behavior so would have been producing
``[no key]``, including PostgreSQL constructs ``hstore``
and ``array``.  These have been amended to use inherit
cache where appropriate.  "on conflict" constructs in
PostgreSQL, MySQL, SQLite still explicitly don't generate
a cache key at this time.

The change also adds a test for all constructs via
assert_compile() to assert they will not generate cache
warnings.

Fixes: #7394
Change-Id: I85958affbb99bfad0f5efa21bc8f2a95e7e46981

References: #4600
Change-Id: I2a62ddfe00bc562720f0eae700a497495d7a987a

References: #4600
Change-Id: I61e35bc93fe95610ae75b31c18a3282558cd4ffe

Fixed an issue in the ``CacheKey.to_offline_string()`` method used by the
dogpile.caching example where attempting to create a proper cache key from
the special "lambda" query generated by the lazy loader would fail to
include the parameter values, leading to an incorrect cache key.

Fixes: #6858
Change-Id: Ice27087583c6f3ff79cf7d5b879e5dd0a4e58158

Fixes: #6858
Change-Id: I9b4113243f9ef32f27dcd1f7e9751923283eba2d

It's better, the majority of these changes look more readable to me.
also found some docstrings that had formatting / quoting issues.

Change-Id: I582a45fde3a5648b2f36bab96bad56881321899b

* major additions to 1.4 migration doc; removed additional
  verbosity regarding caching methodology and reorganized the
  doc to present itself more as a "what's changed" guide

* as we now have a path for asyncio, update that doc so that
  we aren't spreading obsolete information

* updates to the 2.0 migration guide with latest info, however
  this is still an architecture doc and not a migration guide
  yet, will need further rework.

* start really talking about 1.x vs. 2.0 style everywhere.  Querying
  is most of the docs so this is going to be a prominent
  theme, start getting it to fit in

* Add introductory documentation for ORM example sections as these
  are too sparse

* new documentation for do_orm_execute(), many separate sections,
  adding deprecation notes to before_compile() and similar

* new example suites to illustrate do_orm_execute(),
  with_loader_criteria()

* modernized horizontal sharding examples and added a separate
  example to distinguish between multiple databases and single
  database w/ multiple tables use case

* introducing DEEP ALCHEMY, will use zzzeeksphinx 1.1.6

* no name for the alchemist yet however the dragon's name
  is Flambé

Change-Id: Id6b5c03b1ce9ddb7b280f66792212a0ef0a1c541

This patch makes several improvements in the area of
bulk updates and deletes as well as the new session mechanics.

RETURNING is now used for an UPDATE or DELETE statement
emitted for a diaelct that supports "full returning"
in order to satisfy the "fetch" strategy; this currently
includes PostgreSQL and SQL Server.  The Oracle dialect
does not support RETURNING for more than one row,
so a new dialect capability "full_returning" is added
in addition to the existing "implicit_returning", indicating
this dialect supports RETURNING for zero or more rows,
not just a single identity row.

The "fetch" strategy will gracefully degrade to
the previous SELECT mechanics for dialects that do not
support RETURNING.

Additionally, the "fetch" strategy will attempt to use
evaluation for the VALUES that were UPDATEd, rather
than just expiring the updated attributes.   Values should
be evalutable in all cases where the value is not
a SQL expression.

The new approach also incurs some changes in the
session.execute mechanics, where do_orm_execute() event
handlers can now be chained to each return results;
this is in turn used by the handler to detect on a
per-bind basis if the fetch strategy needs to
do a SELECT or if it can do RETURNING.  A test suite is
added to test_horizontal_shard that breaks up a single
UPDATE or DELETE operation among multiple backends
where some are SQLite and don't support RETURNING and
others are PostgreSQL and do.

The session event mechanics are corrected
in terms of the "orm pre execute" hook, which now
receives a flag "is_reentrant" so that the two
ORM implementations for this can skip on their work
if they are being called inside of ORMExecuteState.invoke(),
where previously bulk update/delete were calling its
SELECT a second time.

In order for "fetch" to get the correct identity when
called as pre-execute, it also requests the identity_token
for each mapped instance which is now added as an optional
capability of a SELECT for ORM columns.   the identity_token
that's placed by horizontal_sharding is now made available
within each result row, so that even when fetching a
merged result of plain rows we can tell which row belongs
to which identity token.

The evaluator that takes place within the ORM bulk update and delete for
synchronize_session="evaluate" now supports the IN and NOT IN operators.
Tuple IN is also supported.

Fixes: #1653

Change-Id: I2292b56ae004b997cef0ba4d3fc350ae1dd5efc1