- Added PendingDeprecationWarning support

- Deprecation decorator is now a real decorator

10 files changed, 76 insertions, 36 deletions

diff --git a/lib/sqlalchemy/databases/mysql.py b/lib/sqlalchemy/databases/mysql.py
index f2544e9b5..f8be94e2d 100644
--- a/lib/sqlalchemy/databases/mysql.py
+++ b/lib/sqlalchemy/databases/mysql.py
@@ -1632,7 +1632,7 @@ class MySQLDialect(default.DefaultDialect):
             connectable = connectable.contextual_connect()
 
         return self.server_version_info(connectable)
-    get_version_info = util.deprecated(get_version_info)
+    get_version_info = util.deprecated()(get_version_info)
 
     def reflecttable(self, connection, table, include_columns):
         """Load column definitions from the server."""
diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 03162bac2..eab8b3c0b 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -72,16 +72,16 @@ __all__ = [
 def engine_descriptors():
     """Provide a listing of all the database implementations supported.
     
-    deprecated - this method will be removed in 0.5.
-    """
+    This method will be removed in 0.5.
 
+    """
     result = []
     for module in sqlalchemy.databases.__all__:
         module = getattr(
             __import__('sqlalchemy.databases.%s' % module).databases, module)
         result.append(module.descriptor())
     return result
-engine_descriptors = util.deprecated(engine_descriptors)
+engine_descriptors = util.deprecated()(engine_descriptors)
 
 
 default_strategy = 'plain'
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 5e8455b15..3d7e65198 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -464,11 +464,9 @@ class Compiled(object):
         raise NotImplementedError()
 
     def get_params(self, **params):
-        """Use construct_params().  (supports unicode names)
-        """
-
+        """Use construct_params().  (supports unicode names)"""
         return self.construct_params(params)
-    get_params = util.deprecated(get_params)
+    get_params = util.deprecated()(get_params)
 
     def construct_params(self, params):
         """Return the bind params for this compiled object.
diff --git a/lib/sqlalchemy/exceptions.py b/lib/sqlalchemy/exceptions.py
index 7bac05c26..a21a06b49 100644
--- a/lib/sqlalchemy/exceptions.py
+++ b/lib/sqlalchemy/exceptions.py
@@ -157,5 +157,8 @@ class NotSupportedError(DatabaseError):
 class SADeprecationWarning(DeprecationWarning):
     """Issued once per usage of a deprecated API."""
 
+class SAPendingDeprecationWarning(PendingDeprecationWarning):
+    """Issued once per usage of a deprecated API."""
+
 class SAWarning(RuntimeWarning):
     """Issued at runtime."""
diff --git a/lib/sqlalchemy/ext/assignmapper.py b/lib/sqlalchemy/ext/assignmapper.py
index 0fe203f9d..5a28fbe68 100644
--- a/lib/sqlalchemy/ext/assignmapper.py
+++ b/lib/sqlalchemy/ext/assignmapper.py
@@ -69,4 +69,4 @@ def assign_mapper(ctx, class_, *args, **kwargs):
     return m
 
 assign_mapper = util.deprecated(
-    assign_mapper, "assign_mapper is deprecated. Use scoped_session() instead.")
+    "assign_mapper is deprecated. Use scoped_session() instead.")(assign_mapper)
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index d8576d79b..04203f5bb 100644
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -251,10 +251,9 @@ def _deferred_relation(cls, prop):
     return prop
 
 def declared_synonym(prop, name):
-    """deprecated.  use synonym(name, descriptor=prop)."""
-
+    """Deprecated.  Use synonym(name, descriptor=prop)."""
     return _orm_synonym(name, descriptor=prop)
-declared_synonym = util.deprecated(declared_synonym)
+declared_synonym = util.deprecated(None, False)(declared_synonym)
 
 def synonym_for(name, map_column=False):
     """Decorator, make a Python @property a query synonym for a column.
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index fab7000ed..c906d63c1 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -898,7 +898,7 @@ class Mapper(object):
 
         import sqlalchemy.orm.query
         return sqlalchemy.orm.Query(self, session).instances(cursor, *mappers, **kwargs)
-    instances = util.deprecated(instances, add_deprecation_to_docstring=False)
+    instances = util.deprecated(None, False)(instances)
 
     def identity_key_from_row(self, row):
         """Return an identity-map key for use in storing/retrieving an
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index f39ef87c8..8c0f1335d 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1404,15 +1404,15 @@ class Query(object):
 
         return self._legacy_filter_by(*args, **params).one()
 
-for deprecated_method in ('list', 'scalar', 'count_by',
-                          'select_whereclause', 'get_by', 'select_by',
-                          'join_by', 'selectfirst', 'selectone', 'select',
-                          'execute', 'select_statement', 'select_text',
-                          'join_to', 'join_via', 'selectfirst_by',
-                          'selectone_by', 'apply_max', 'apply_min', 'apply_avg', 'apply_sum'):
-    setattr(Query, deprecated_method,
-            util.deprecated(getattr(Query, deprecated_method),
-                            add_deprecation_to_docstring=False))
+    for deprecated_method in ('list', 'scalar', 'count_by',
+                              'select_whereclause', 'get_by', 'select_by',
+                              'join_by', 'selectfirst', 'selectone', 'select',
+                              'execute', 'select_statement', 'select_text',
+                              'join_to', 'join_via', 'selectfirst_by',
+                              'selectone_by', 'apply_max', 'apply_min',
+                              'apply_avg', 'apply_sum'):
+        locals()[deprecated_method] = \
+            util.deprecated(None, False)(locals()[deprecated_method])
 
 class _QueryEntity(object):
     """represent an entity column returned within a Query result."""
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 1933c40f6..96ec5b8de 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -1413,7 +1413,7 @@ class MetaData(SchemaItem):
             self._bind = create_engine(bind, **kwargs)
         else:
             self._bind = bind
-    connect = util.deprecated(connect)
+    connect = util.deprecated()(connect)
 
     def bind(self):
         """An Engine or Connection to which this MetaData is bound.
@@ -1658,7 +1658,7 @@ class ThreadLocalMetaData(MetaData):
                 engine = create_engine(bind, **kwargs)
             bind = engine
         self._bind_to(bind)
-    connect = util.deprecated(connect)
+    connect = util.deprecated()(connect)
 
     def bind(self):
         """The bound Engine or Connection for this thread.
diff --git a/lib/sqlalchemy/util.py b/lib/sqlalchemy/util.py
index 8451d28b5..6919d1557 100644
--- a/lib/sqlalchemy/util.py
+++ b/lib/sqlalchemy/util.py
@@ -1082,7 +1082,7 @@ def reset_cached(instance, name):
         delattr(instance, '_cached_' + name)
     except AttributeError:
         pass
-    
+
 def warn(msg):
     if isinstance(msg, basestring):
         warnings.warn(msg, exceptions.SAWarning, stacklevel=3)
@@ -1092,7 +1092,7 @@ def warn(msg):
 def warn_deprecated(msg):
     warnings.warn(msg, exceptions.SADeprecationWarning, stacklevel=3)
 
-def deprecated(func, message=None, add_deprecation_to_docstring=True):
+def deprecated(message=None, add_deprecation_to_docstring=True):
     """Decorates a function and issues a deprecation warning on use.
 
     message
@@ -1105,21 +1105,62 @@ def deprecated(func, message=None, add_deprecation_to_docstring=True):
       provided, or sensible default if message is omitted.
     """
 
-    if message is not None:
-        warning = message % dict(func=func.__name__)
+    if add_deprecation_to_docstring:
+        header = message is not None and message or 'Deprecated.'
+    else:
+        header = None
+
+    if message is None:
+        message = "Call to deprecated function %(func)s"
+
+    def decorate(fn):
+        return _decorate_with_warning(
+            fn, exceptions.SADeprecationWarning,
+            message % dict(func=fn.__name__), header)
+    return decorate
+
+def pending_deprecation(version, message=None,
+                        add_deprecation_to_docstring=True):
+    """Decorates a function and issues a pending deprecation warning on use.
+
+    version
+      An approximate future version at which point the pending deprecation
+      will become deprecated.  Not used in messaging.
+
+    message
+      If provided, issue message in the warning.  A sensible default
+      is used if not provided.
+
+    add_deprecation_to_docstring
+      Default True.  If False, the wrapped function's __doc__ is left
+      as-is.  If True, the 'message' is prepended to the docs if
+      provided, or sensible default if message is omitted.
+    """
+
+    if add_deprecation_to_docstring:
+        header = message is not None and message or 'Deprecated.'
     else:
-        warning = "Call to deprecated function %s" % func.__name__
+        header = None
+
+    if message is None:
+        message = "Call to deprecated function %(func)s"
+
+    def decorate(fn):
+        return _decorate_with_warning(
+            fn, exceptions.SAPendingDeprecationWarning,
+            message % dict(func=fn.__name__), header)
+    return decorate
+
+def _decorate_with_warning(func, wtype, message, docstring_header=None):
+    """Wrap a function with a warnings.warn and augmented docstring."""
 
     def func_with_warning(*args, **kwargs):
-        warnings.warn(exceptions.SADeprecationWarning(warning),
-                      stacklevel=2)
+        warnings.warn(wtype(message), stacklevel=2)
         return func(*args, **kwargs)
 
     doc = func.__doc__ is not None and func.__doc__ or ''
-
-    if add_deprecation_to_docstring:
-        header = message is not None and warning or 'Deprecated.'
-        doc = '\n'.join((header.rstrip(), doc))
+    if docstring_header is not None:
+        doc = '\n'.join((docstring_header.rstrip(), doc))
 
     func_with_warning.__doc__ = doc
     func_with_warning.__dict__.update(func.__dict__)
@@ -1127,5 +1168,4 @@ def deprecated(func, message=None, add_deprecation_to_docstring=True):
         func_with_warning.__name__ = func.__name__
     except TypeError:
         pass
-
     return func_with_warning