Created deprecation filter

This filter can be used to notify users that an option has been deprecated.
The filter can be applied to any variable and can be made fatal.

USAGE:
{{ new_var | deprecated(old_var=old_var, old_var_name="old_var_name", new_var_name="new_var_name", removed_in="removed_in", fatal=false) }}'

Note that the key names need not be specified they're only shown in the usage
example for clarity.

PRACTICAL USAGE:
{{ new_var | deprecated(old_var, 'old_var_name', 'new_var_name', 'the next release') }}

Change-Id: Id4f830df4b96a9b0b0b7637c23dfe63dc142387c
Signed-off-by: Kevin Carter <kevin.carter@rackspace.com>

filter/osa-filters.py

@@ -14,12 +14,14 @@
 #
 # (c) 2015, Kevin Carter <kevin.carter@rackspace.com>
 
+import hashlib
+import logging
 import os
 import re
 import urlparse
-import hashlib
 
 from ansible import errors
+from jinja2.runtime import Undefined
 
 """Filter usage:
 
@@ -27,6 +29,95 @@ Simple filters that may be useful from within the stack
 """
 
 
+def _deprecated(new_var, old_var=None, old_var_name=None,
+                new_var_name=None, removed_in=None, fatal=False):
+    """Provide a deprecation warning on deprecated variables.
+
+    This filter will return the old_var value if defined along with a
+    deprecation warning that will inform the user that the old variable
+    should no longer be used.
+
+    In order to use this filter the old and new variable names must be provided
+    to the filter as a string which is used to render the warning message. The
+    removed_in option is used to give a date or release name where the old
+    option will be removed. Optionally, if fatal is set to True, the filter
+    will raise an exception if the old variable is used.
+
+    USAGE: {{ new_var | deprecated(old_var,
+                                   "old_var_name",
+                                   "new_var_name",
+                                   "removed_in",
+                                   false) }}
+
+    :param new_var: ``object``
+    :param old_var: ``object``
+    :param old_var_name: ``str``
+    :param new_var_name: ``str``
+    :param removed_in: ``str``
+    :param fatal: ``bol``
+    """
+    _usage = (
+        'USAGE: '
+        '{{ new_var | deprecated(old_var=old_var, old_var_name="old_var_name",'
+        ' new_var_name="new_var_name", removed_in="removed_in",'
+        ' fatal=false) }}'
+    )
+
+    if not old_var_name:
+        raise errors.AnsibleUndefinedVariable(
+            'To use this filter you must provide the "old_var_name" option'
+            ' with the string name of the old variable that will be'
+            ' replaced. ' + _usage
+        )
+    if not new_var_name:
+        raise errors.AnsibleUndefinedVariable(
+            'To use this filter you must provide the "new_var_name" option'
+            ' with the string name of the new variable that will replace the'
+            ' deprecated one. ' + _usage
+        )
+    if not removed_in:
+        raise errors.AnsibleUndefinedVariable(
+            'To use this filter you must provide the "removed_in" option with'
+            ' the string name of the release where the old_var will be'
+            ' removed. ' + _usage
+        )
+
+    # If old_var is undefined or has a None value return the new_var value
+    if isinstance(old_var, Undefined) or not old_var:
+        return new_var
+
+    name = 'Ansible-Warning| '
+    log = logging.getLogger(name)
+    for handler in log.handlers:
+        if name == handler.name:
+            break
+    else:
+        stream_handler = logging.StreamHandler()
+        stream_handler.setLevel(logging.DEBUG)
+        stream_handler.name = name
+        stream_format = logging.Formatter(
+            '%(asctime)s - %(name)s%(levelname)s => %(message)s'
+        )
+        stream_handler.setFormatter(stream_format)
+
+        log.setLevel(logging.DEBUG)
+        log.addHandler(stream_handler)
+
+    message = (
+        'Deprecated Option provided: Deprecated variable: "%(old)s", Removal'
+        ' timeframe: "%(removed_in)s", Future usage: "%(new)s"'
+        % {'old': old_var_name, 'new': new_var_name, 'removed_in': removed_in}
+    )
+
+    if str(fatal).lower() in ['yes', 'true']:
+        message = 'Fatally %s' % message
+        log.fatal(message)
+        raise RuntimeError(message)
+    else:
+        log.warn(message)
+        return old_var
+
+
 def _pip_requirement_split(requirement):
     version_descriptors = "(>=|<=|>|<|==|~=|!=)"
     requirement = requirement.split(';')
@@ -240,5 +331,6 @@ class FilterModule(object):
             'splitlines': splitlines,
             'filtered_list': filtered_list,
             'git_link_parse': git_link_parse,
-            'git_link_parse_name': git_link_parse_name
+            'git_link_parse_name': git_link_parse_name,
+            'deprecated': _deprecated
         }