[core] add deprecation module

Emanuele Palazzetti · Emanuele Palazzetti · commit 7af26f145d3e · 2018-04-13T14:00:55.000-04:00
diff --git a/ddtrace/contrib/cassandra/session.py b/ddtrace/contrib/cassandra/session.py
@@ -10,7 +10,9 @@
 # project
 from ddtrace import Pin
 from ddtrace.compat import stringify
-from ...util import deep_getattr, deprecated
+
+from ...utils.deprecation import deprecated
+from ...util import deep_getattr
 from ...ext import net, cassandra as cassx, errors
 
 log = logging.getLogger(__name__)
@@ -257,7 +259,7 @@ def _sanitize_query(span, query):
 # DEPRECATED
 #
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_cassandra(*args, **kwargs):
     return _get_traced_cluster(*args, **kwargs)
 
diff --git a/ddtrace/contrib/elasticsearch/transport.py b/ddtrace/contrib/elasticsearch/transport.py
@@ -1,17 +1,18 @@
 from elasticsearch import Transport
 from elasticsearch.exceptions import TransportError
 
-from .quantize import quantize
 from . import metadata
+from .quantize import quantize
+
+from ...utils.deprecation import deprecated
 from ...compat import urlencode
 from ...ext import AppTypes, http
-from ...util import deprecated
 
 DEFAULT_SERVICE = 'elasticsearch'
 SPAN_TYPE = 'elasticsearch'
 
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_transport(datadog_tracer, datadog_service=DEFAULT_SERVICE):
 
     datadog_tracer.set_service_info(
diff --git a/ddtrace/contrib/mongoengine/patch.py b/ddtrace/contrib/mongoengine/patch.py
@@ -1,7 +1,7 @@
 import mongoengine
 
 from .trace import WrappedConnect
-from ddtrace.util import deprecated
+from ...utils.deprecation import deprecated
 
 # Original connect function
 _connect = mongoengine.connect
@@ -13,7 +13,7 @@ def patch():
 def unpatch():
     setattr(mongoengine, 'connect', _connect)
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def trace_mongoengine(*args, **kwargs):
     return _connect
 
diff --git a/ddtrace/contrib/mysql/tracers.py b/ddtrace/contrib/mysql/tracers.py
@@ -1,7 +1,8 @@
 import mysql.connector
 
-from ddtrace.util import deprecated
+from ...utils.deprecation import deprecated
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_mysql_connection(*args, **kwargs):
     return mysql.connector.MySQLConnection
diff --git a/ddtrace/contrib/psycopg/connection.py b/ddtrace/contrib/psycopg/connection.py
@@ -9,13 +9,13 @@
 from ...ext import net
 from ...ext import sql
 from ...ext import AppTypes
-from ...util import deprecated
+from ...utils.deprecation import deprecated
 
 # 3p
 from psycopg2.extensions import connection, cursor
 
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def connection_factory(tracer, service="postgres"):
     """ Return a connection factory class that will can be used to trace
         postgres queries.
diff --git a/ddtrace/contrib/pymongo/client.py b/ddtrace/contrib/pymongo/client.py
@@ -9,11 +9,11 @@
 
 # project
 import ddtrace
+from ...utils.deprecation import deprecated
 from ...compat import iteritems
 from ...ext import AppTypes
 from ...ext import mongo as mongox
 from ...ext import net as netx
-from ...util import deprecated
 from .parse import parse_spec, parse_query, parse_msg
 
 # Original Client class
@@ -22,7 +22,7 @@
 log = logging.getLogger(__name__)
 
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def trace_mongo_client(client, tracer, service=mongox.TYPE):
     tracer.set_service_info(
         service=service,
diff --git a/ddtrace/contrib/pymysql/tracers.py b/ddtrace/contrib/pymysql/tracers.py
@@ -1,7 +1,8 @@
 import pymysql.connections
 
-from ddtrace.util import deprecated
+from ...utils.deprecation import deprecated
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_pymysql_connection(*args, **kwargs):
     return pymysql.connections.Connection
diff --git a/ddtrace/contrib/redis/tracers.py b/ddtrace/contrib/redis/tracers.py
@@ -1,18 +1,20 @@
 from redis import StrictRedis
 
-from ...util import deprecated
+from ...utils.deprecation import deprecated
+
 
 DEFAULT_SERVICE = 'redis'
 
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_redis(ddtracer, service=DEFAULT_SERVICE, meta=None):
     return _get_traced_redis(ddtracer, StrictRedis, service, meta)
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def get_traced_redis_from(ddtracer, baseclass, service=DEFAULT_SERVICE, meta=None):
     return _get_traced_redis(ddtracer, baseclass, service, meta)
 
+
 def _get_traced_redis(ddtracer, baseclass, service, meta):
     return baseclass
-
diff --git a/ddtrace/contrib/sqlite3/connection.py b/ddtrace/contrib/sqlite3/connection.py
@@ -1,7 +1,8 @@
 from sqlite3 import Connection
 
-from ddtrace.util import deprecated
+from ...utils.deprecation import deprecated
 
-@deprecated(message='Use patching instead (see the docs).', version='0.6.0')
+
+@deprecated(message='Use patching instead (see the docs).', version='1.0.0')
 def connection_factory(*args, **kwargs):
     return Connection
diff --git a/ddtrace/util.py b/ddtrace/util.py
@@ -1,24 +1,6 @@
 import os
-import inspect
-import logging
 import wrapt
-
-from functools import wraps
-
-
-def deprecated(message='', version=None):
-    """Function decorator to report a deprecated function"""
-    def decorator(func):
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            logger = logging.getLogger(func.__module__)
-            logger.warning("%s is deprecated and will be remove in future versions%s. %s",
-                           func.__name__,
-                           ' (%s)' % version if version else '',
-                           message)
-            return func(*args, **kwargs)
-        return wrapper
-    return decorator
+import inspect
 
 
 def deep_getattr(obj, attr_string, default=None):
diff --git a/ddtrace/utils/__init__.py b/ddtrace/utils/__init__.py
diff --git a/ddtrace/utils/deprecation.py b/ddtrace/utils/deprecation.py
@@ -0,0 +1,56 @@
+import warnings
+
+from functools import wraps
+
+
+def format_message(name, message, version):
+    """Message formatter to create `DeprecationWarning` messages
+    such as:
+
+        'fn' is deprecated and will be remove in future versions (1.0).
+    """
+    return "'{}' is deprecated and will be remove in future versions{}. {}".format(
+        name,
+        ' ({})'.format(version) if version else '',
+        message,
+    )
+
+
+def warn(message, stacklevel=2):
+    """Helper function used as a ``DeprecationWarning``."""
+    warnings.warn(message, DeprecationWarning, stacklevel=stacklevel)
+
+
+def deprecation(name='', message='', version=None):
+    """Function to report a ``DeprecationWarning``. Bear in mind that `DeprecationWarning`
+    are ignored by default so they're not available in user logs. To show them,
+    the application must be launched with a special flag:
+
+        $ python -Wall script.py
+
+    This approach is used by most of the frameworks, including Django
+    (ref: https://docs.djangoproject.com/en/2.0/howto/upgrade-version/#resolving-deprecation-warnings)
+    """
+    msg = format_message(name, message, version)
+    warn(msg, stacklevel=4)
+
+
+def deprecated(message='', version=None):
+    """Decorator function to report a ``DeprecationWarning``. Bear
+    in mind that `DeprecationWarning` are ignored by default so they're
+    not available in user logs. To show them, the application must be launched
+    with a special flag:
+
+        $ python -Wall script.py
+
+    This approach is used by most of the frameworks, including Django
+    (ref: https://docs.djangoproject.com/en/2.0/howto/upgrade-version/#resolving-deprecation-warnings)
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            msg = format_message(func.__name__, message, version)
+            warn(msg, stacklevel=3)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
