diff options
| -rw-r--r-- | lib/sqlalchemy/databases/mysql.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/__init__.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/exceptions.py | 3 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/assignmapper.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/declarative.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/mapper.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 18 | ||||
| -rw-r--r-- | lib/sqlalchemy/schema.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/util.py | 64 |
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 |