Be gracious in deprecation of method signatures related to threadlocal removal.

Certain OpenStack projects that use pecan have overridden private methods of
`pecan.rest.RestController` for custom behavior, and these method signatures
are changing in the next release of pecan to support optional threadlocals.  As
good citizens, let's give these projects a deprecation period to get their
implementations back in sync with upstream pecan.

Change-Id: I02823c7fb79488aea0dd8ad3266aa7f0024bc4a0

2 files changed, 57 insertions, 9 deletions

diff --git a/pecan/rest.py b/pecan/rest.py
index 9cc8b35..e78d287 100644
--- a/pecan/rest.py
+++ b/pecan/rest.py
@@ -73,7 +73,10 @@ class RestController(object):
         )
 
         try:
-            result = handler(method, args, request)
+            if len(getargspec(handler).args) == 3:
+                result = handler(method, args)
+            else:
+                result = handler(method, args, request)
 
             #
             # If the signature of the handler does not match the number
@@ -99,7 +102,10 @@ class RestController(object):
         # return the result
         return result
 
-    def _handle_lookup(self, args, request):
+    def _handle_lookup(self, args, request=None):
+        if request is None:
+            self._raise_method_deprecation_warning(self.handle_lookup)
+
         # filter empty strings from the arg list
         args = list(six.moves.filter(bool, args))
 
@@ -162,10 +168,13 @@ class RestController(object):
                     request
                 )
 
-    def _handle_unknown_method(self, method, remainder, request):
+    def _handle_unknown_method(self, method, remainder, request=None):
         '''
         Routes undefined actions (like RESET) to the appropriate controller.
         '''
+        if request is None:
+            self._raise_method_deprecation_warning(self._handle_unknown_method)
+
         # try finding a post_{custom} or {custom} method first
         controller = self._find_controller('post_%s' % method, method)
         if controller:
@@ -183,10 +192,13 @@ class RestController(object):
 
         abort(404)
 
-    def _handle_get(self, method, remainder, request):
+    def _handle_get(self, method, remainder, request=None):
         '''
         Routes ``GET`` actions to the appropriate controller.
         '''
+        if request is None:
+            self._raise_method_deprecation_warning(self._handle_get)
+
         # route to a get_all or get if no additional parts are available
         if not remainder or remainder == ['']:
             controller = self._find_controller('get_all', 'get')
@@ -224,10 +236,13 @@ class RestController(object):
 
         abort(404)
 
-    def _handle_delete(self, method, remainder, request):
+    def _handle_delete(self, method, remainder, request=None):
         '''
         Routes ``DELETE`` actions to the appropriate controller.
         '''
+        if request is None:
+            self._raise_method_deprecation_warning(self._handle_delete)
+
         if remainder:
             match = self._handle_custom_action(method, remainder, request)
             if match:
@@ -254,10 +269,13 @@ class RestController(object):
 
         abort(404)
 
-    def _handle_post(self, method, remainder, request):
+    def _handle_post(self, method, remainder, request=None):
         '''
         Routes ``POST`` requests.
         '''
+        if request is None:
+            self._raise_method_deprecation_warning(self._handle_post)
+
         # check for custom POST/PUT requests
         if remainder:
             match = self._handle_custom_action(method, remainder, request)
@@ -275,10 +293,13 @@ class RestController(object):
 
         abort(404)
 
-    def _handle_put(self, method, remainder, request):
+    def _handle_put(self, method, remainder, request=None):
         return self._handle_post(method, remainder, request)
 
-    def _handle_custom_action(self, method, remainder, request):
+    def _handle_custom_action(self, method, remainder, request=None):
+        if request is None:
+            self._raise_method_deprecation_warning(self._handle_custom_action)
+
         remainder = [r for r in remainder if r]
         if remainder:
             if method in ('put', 'delete'):
@@ -302,3 +323,18 @@ class RestController(object):
         Sets default routing arguments.
         '''
         request.pecan.setdefault('routing_args', []).extend(args)
+
+    def _raise_method_deprecation_warning(self, handler):
+        warnings.warn(
+            (
+                "The function signature for %s.%s.%s is changing "
+                "in the next version of pecan.\nPlease update to: "
+                "`%s(self, method, remainder, request)`." % (
+                    self.__class__.__module__,
+                    self.__class__.__name__,
+                    handler.__name__,
+                    handler.__name__
+                )
+            ),
+            DeprecationWarning
+        )
diff --git a/pecan/routing.py b/pecan/routing.py
index 17a7e40..c6abb2e 100644
--- a/pecan/routing.py
+++ b/pecan/routing.py
@@ -24,13 +24,25 @@ class NonCanonicalPath(Exception):
         self.remainder = remainder
 
 
-def lookup_controller(obj, remainder, request):
+def lookup_controller(obj, remainder, request=None):
     '''
     Traverses the requested url path and returns the appropriate controller
     object, including default routes.
 
     Handles common errors gracefully.
     '''
+    if request is None:
+        warnings.warn(
+            (
+                "The function signature for %s.lookup_controller is changing "
+                "in the next version of pecan.\nPlease update to: "
+                "`lookup_controller(self, obj, remainder, request)`." % (
+                    __name__,
+                )
+            ),
+            DeprecationWarning
+        )
+
     notfound_handlers = []
     while True:
         try: