DEV: Adds deprecation utility

zipline/utils/deprecate.py

@@ -0,0 +1,46 @@
+"""Utilities for marking deprecated functions."""
+# Copyright 2016 Quantopian, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import warnings
+from functools import wraps
+
+
+def deprecated(msg=None, stacklevel=2):
+    """
+    Used to mark a function as deprecated.
+
+    Parameters
+    ----------
+    msg : str
+        The message to display in the deprecation warning.
+    stacklevel : int
+        How far up the stack the warning needs to go, before
+        showing the relevant calling lines.
+    Usage
+    -----
+    @deprecated(msg='function_a is deprecated! Use function_b instead.')
+    def function_a(*args, **kwargs):
+    """
+    def deprecated_dec(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                msg or "Function %s is deprecated." % fn.__name__,
+                category=DeprecationWarning,
+                stacklevel=stacklevel
+            )
+            return fn(*args, **kwargs)
+        return wrapper
+    return deprecated_dec