Make it possible to use enginefacade decorators with class methods

The decorator form can now be used with bound methods after a fix
for the related bug was merged. Mention this in docs and release
notes, so that people are aware of it.

A new test is added to make sure this also works with class methods
(as well as to check that the proposed decorator applying order
is actually correct).

Related-Bug: #1520195

Change-Id: Ifea08114d6d89de9d67fcae397eb94c0afc4d339

1 files changed, 25 insertions, 2 deletions

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 98a74b0..448afaa 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -48,8 +48,7 @@ The context manager form is as follows:
 The decorator form accesses attributes off the user-defined context
 directly; the context must be decorated with the
 :func:`oslo_db.sqlalchemy.enginefacade.transaction_context_provider`
-decorator.   Each function must receive the context as the first
-positional argument:
+decorator.   Each function must receive the context argument:
 
 .. code:: python
 
@@ -82,6 +81,30 @@ positional argument:
    raised otherwise.
 
 
+The decorator form can also be used with class and instance methods which
+implicitly receive the first positional argument:
+
+.. code:: python
+
+    class DatabaseAccessLayer(object):
+
+        @classmethod
+        @enginefacade.reader
+        def some_reader_api_function(cls, context):
+            return context.session.query(SomeClass).all()
+
+        @enginefacade.writer
+        def some_writer_api_function(self, context, x, y):
+            context.session.add(SomeClass(x, y))
+
+.. note:: Note that enginefacade decorators must be applied **before**
+   `classmethod`, otherwise you will get a ``TypeError`` at import time
+   (as enginefacade will try to use ``inspect.getargspec()`` on a descriptor,
+   not on a bound method, please refer to the `Data Model
+   <https://docs.python.org/3/reference/datamodel.html#data-model>`_ section
+   of the Python Language Reference for details).
+
+
 The scope of transaction and connectivity for both approaches is managed
 transparently.   The configuration for the connection comes from the standard
 :obj:`oslo_config.cfg.CONF` collection.  Additional configurations can be