Make sure that upgrade() is thread-safe (as it appears not
to be) by using a lock that all connections from the same
engine will use.

Change-Id: I2b2b1be9e797099c8412fc6819465e550b1b934a
Closes-Bug: #1559496

Instead of a custom loop and backoff just use the retrying
library to do this same code and delegate the loop complexity
to it instead.

Change-Id: Iaf02cc728d2a2cfc7077300e03d7ef25522717b7

Change-Id: I415a81d3b6b15b17a9a91cc2a0681c159172a4e1

Since this module contains more than the logbook
class and really is a our generic models that are used
to hold the runtime structure it is more appropriate to
place it under a models module and deprecate the usage
of the old module by placing a warning there (so that
when it is imported that warning is triggered).

Change-Id: I79def5ee08f560d38f2c9dcefd0b33becc2a4d36

Part of blueprint make-things-speedy

Change-Id: I3ac092e98a492d3a70c7780efb4647d593fa70d1

In order to prevent a thread from closing a backend
while another thread is getting a connection (which
can result in an engine being created) stop this kind
of concurrent mutation by creating a engine (if it
was not user provided) in the constructor.

In the close the engine dispose is called (which will
according to the docs just create a new pool anyway)
so there is no need to recreate the full engine object
from its same configuration again.

Change-Id: Id1fa3001b3ebbe76bbcdb08ed4add6a9e16ea96b

Also fixes up some inline-code/examples docs to
correctly display in the generated docs (and
tweaks some URI capitalization).

Change-Id: I001ef2460eb5e9a884ca6db6e8d6f72864191fe7

In the zookeeper jobboard (and persistence backends) we
are associating the cause of a new exception when raising a
exception. Using the new exception helper we can make this
work better on py2.x and py3.x so that the py3.x version
has the chain setup correctly (while the py2.x version just
uses the class 'cause' attribute instead).

Change-Id: Ieeac2f70e1834d4612556565762ffd3be3e5b5a1