Implement new oslo.db.sqlalchemy.enginefacade module

This module presents a replacement for the EngineFacade
system.  At the center is the oslo.db.sqlalchemy.enginefacade
module, which when imported, provides decorators and context
managers which perform all database and ORM connectivity
functions transparently.   The docstrings as well
as the blueprint provide an introduction.

The patch includes a refactoring of sqlalchemy/session.py
into three dependent modules engines.py, orm.py and
enginefacade.py.  This is to maintain a non-cyclical import
structure as well as to maintain the import behavior of
oslo.db overall, as some projects such as glance currently
have dependencies on this structure.

There is also a slimming down and attempt at modernizing
some very old documentation in session.py.  The enginefacade
system should be preferred moving forward.

Implements: blueprint make-enginefacade-a-facade

Change-Id: I9a3d0c26bb727eb2c0bd823b9a12fde57cc7c9c3

1 files changed, 43 insertions, 0 deletions

diff --git a/oslo_db/exception.py b/oslo_db/exception.py
index 506006c..c1620e1 100644
--- a/oslo_db/exception.py
+++ b/oslo_db/exception.py
@@ -205,3 +205,46 @@ class RetryRequest(Exception):
     """
     def __init__(self, inner_exc):
         self.inner_exc = inner_exc
+
+
+class NoEngineContextEstablished(AttributeError):
+    """Error raised for non-present enginefacade attribute access.
+
+
+    This applies to the ``session`` and ``connection`` attributes
+    of a user-defined context and/or RequestContext object, when they
+    are accessed outside of the scope of an enginefacade decorator
+    or context manager.
+
+    The exception is a subclass of AttributeError so that
+    normal Python missing attribute behaviors are maintained, such
+    as support for ``getattr(context, 'session', None)``.
+
+
+    """
+
+
+class NotSupportedWarning(Warning):
+    """Warn that an argument or call that was passed is not supported.
+
+    This subclasses Warning so that it can be filtered as a distinct
+    category.
+
+    .. seealso::
+
+        https://docs.python.org/2/library/warnings.html
+
+    """
+
+
+class OsloDBDeprecationWarning(DeprecationWarning):
+    """Issued per usage of a deprecated API.
+
+    This subclasses DeprecationWarning so that it can be filtered as a distinct
+    category.
+
+    .. seealso::
+
+        https://docs.python.org/2/library/warnings.html
+
+    """