based on feedback in #7271, the emphasis on TypeDecorator
as a solution to this problem is not very practical.  illustrate
a series of quick recipes that are useful for debugging purposes
to print out a repr() or simple stringify of a parameter
without the need to construct custom dialects or types.

Change-Id: I788ce1b5ea01d88dd0a22d03d06f35aabff5e5c8

Updated to Python 3, and to use `future=True`.
Also added outputs for `return_default=True`

Improve the interface used by adapted drivers, like the asyncio ones,
to access the actual connection object returned by the driver.

The :class:`_engine._ConnectionRecord` and
:class:`_engine._ConnectionFairy` now have two new attributes:

* ``dbapi_connection`` always represents a DBAPI compatible
object.  For pep-249 drivers, this is the DBAPI connection as it always
has been, previously accessed under the ``.connection`` attribute.
For asyncio drivers that SQLAlchemy adapts into a pep-249 interface,
the returned object will normally be a SQLAlchemy adaption object
called :class:`_engine.AdaptedConnection`.
* ``driver_connection`` always represents the actual connection object
maintained by the third party pep-249 DBAPI or async driver in use.
For standard pep-249 DBAPIs, this will always be the same object
as that of the ``dbapi_connection``.  For an asyncio driver, it will be
the underlying asyncio-only connection object.

The ``.connection`` attribute remains available and is now a legacy alias
of ``.dbapi_connection``.

Fixes: #6832
Change-Id: Ib72f97deefca96dce4e61e7c38ba430068d6a82e

(redo of 2999/I5609025feee8cfdecc09b55bfbf1bd13fa2e6602)

This PR is designed to bring more clarity within the docs by renaming object
instances that may be consfusingly similar to class, method, and attribute names.

For example, instances of the class `MetaData` are available on some  objects as
`.metadata` property, and had appeared within the docs as both `meta` and
`metadata` which has confused some users in the past. By this PR, the docs now
utilize the following naming convention:

* MetaData - SQLAlchemy class
* .metadata - SQLAlchemy API attributes
* metadata_obj - developer instantiated metadata objects or references

Detailed Changes:

* standardized `meta` and `metadata` instances to `metadata_obj`. note: the docs were evenly split between 'meta' and 'metadata'.
* standardized 'cursor' to 'cursor_obj' to avoid confusion with the method.
* standardized a 'scalar_subquery = ' to 'scalar_subq' to avoid confusion with the method.
* standardized a 'cte = ' to 'cte_obj' to avoid confusion with the method

Change-Id: I79c98aee16c5fc6649289b2dd7d6dfc368222fb4

Also replace http://pypi.python.org/pypi with https://pypi.org/project

Change-Id: I84b5005c39969a82140706472989f2a30b0c7685

Change-Id: If0231623491d7901046c76af3461f33ba504ff53
References: #6230

this is coming up more than once so provide a document

Change-Id: I23dcd4c7a6527b2f33502e67ffad4335f895e6f9

Add SelectBase.exists() method as it seems strange this is
not available already.  The Exists construct itself does
not provide full SELECT-building capabilities so it makes
sense this should be used more like a scalar_subquery.

Make sure stream_results is getting set up when yield_per
is used, for 2.0 style statements as well.  this was
hardcoded inside of Query.yield_per() and is now moved
to take place within QueryContext.

Change-Id: Icafcd4fd9b708772343d56edf40995c9e8f835d6

In order to invalidate a connection within a Transaction
block and an execution context, we need to take advantage
of the simpler transaction design added in 1.4.  The recipe
can be done on 1.3 but it requires a lot more hacking
and isn't worth it.

Clearly since the recipe is part of the tests now we can
in the future consider adding a feature that's built
in for this case but it would have to absolutely guarantee
the DBAPI is in autocommit mode and also prevent
any "write" operations from taking place.   Recipe for now.

Fixes: #5657
Change-Id: Ia9ea8cced084d154e83e4d1c259e080b776ec38a