Merge pull request #13 from okfn/feature-2420-deprecated

Merge pull request #13 from okfn/feature-2420-deprecated

ckan/lib/helpers.py

@@ -33,6 +33,7 @@
 from pylons import c
 from pylons.i18n import _
 
+from lib.maintain import deprecated
 import ckan.model as model
 get_available_locales = i18n.get_available_locales
 get_locales_dict = i18n.get_locales_dict
@@ -377,6 +378,7 @@ def unselected_facet_items(facet, limit=10):
             facets.append(facet_item)
     return sorted(facets, key=lambda item: item['count'], reverse=True)[:limit]
 
+@deprecated()
 def facet_items(*args, **kwargs):
     """
     DEPRECATED: Use the new facet data structure, and `unselected_facet_items()`
@@ -407,6 +409,7 @@ def _facet_items(name, limit=10):
 def facet_title(name):
     return config.get('search.facets.%s.title' % name, name.capitalize())
 
+@deprecated('Please use check_access instead.')
 def am_authorized(c, action, domain_object=None):
     ''' Deprecated. Please use check_access instead'''
     from ckan.authz import Authorizer
@@ -587,8 +590,9 @@ def render_datetime(datetime_, date_format=None, with_hours=False):
     else:
         return ''
 
+@deprecated()
 def datetime_to_date_str(datetime_):
-    '''Takes a datetime.datetime object and returns a string of it
+    '''DEPRECATED: Takes a datetime.datetime object and returns a string of it
     in ISO format.
     '''
     return datetime_.isoformat()

ckan/lib/maintain.py

@@ -0,0 +1,37 @@
+''' This module contains code that helps in maintaining the Ckan codebase. '''
+
+import logging
+import re
+
+log = logging.getLogger(__name__)
+
+
+def deprecated(message=''):
+    ''' This is a decorator used to mark functions as deprecated.
+
+    It logs a warning when the function is called. If a message is
+    passed it is also logged, this can be useful to indicate for example
+    that a different function should be used instead.
+
+    Additionally an exception is raised if the functions docstring does
+    not contain the word `deprecated`.'''
+    def decorator(fn):
+        # When decorating a function check that the docstring is correct.
+        if not fn.__doc__ or not re.search(r'\bdeprecated\b',
+                                           fn.__doc__, re.IGNORECASE):
+            raise Exception('Function %s() in module %s has been deprecated '
+                            'but this is not mentioned in the docstring. '
+                            'Please update the docstring for the function. '
+                            'It must include the word `deprecated`.'
+                            % (fn.__name__, fn.__module__))
+        # Log deprecated functions
+        log.info('Function %s() in module %s has been deprecated. %s'
+                            % (fn.__name__, fn.__module__, message))
+
+        def wrapped(*args, **kw):
+            log.warning('Function %s() in module %s has been deprecated '
+                         'and will be removed in a later release of ckan. %s'
+                         % (fn.__name__, fn.__module__, message))
+            return fn(*args, **kw)
+        return wrapped
+    return decorator