diff options
| -rw-r--r-- | doc/build/static/docs.css | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/scoping.py | 6 | ||||
| -rw-r--r-- | lib/sqlalchemy/schema.py | 11 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/expression.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/util.py | 41 |
7 files changed, 53 insertions, 23 deletions
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index c0d634557..145e49b8c 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -155,12 +155,13 @@ li.toctree-l1 ul li li th.field-name { text-align:right; } -div.note, div.warning { + +div.note, div.warning, p.deprecated { background-color:#EEFFEF; } -div.admonition, div.topic { +div.admonition, div.topic, p.deprecated { border:1px solid #CCCCCC; margin:5px 5px 5px 5px; padding:5px 5px 5px 35px; diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 684df51ca..b481261d5 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -2308,9 +2308,9 @@ class ResultProxy(object): return self.context._inserted_primary_key - @util.deprecated("Use inserted_primary_key") + @util.deprecated("0.6", "Use :attr:`.ResultProxy.inserted_primary_key`") def last_inserted_ids(self): - """deprecated. use :attr:`~ResultProxy.inserted_primary_key`.""" + """Return the primary key for the row just inserted.""" return self.inserted_primary_key diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index c269c8bb9..c33687484 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -745,7 +745,9 @@ class Query(object): # given arg is a FROM clause self._setup_aliasizers(self._entities[l:]) - @util.pending_deprecation("0.7", "add_column() is superceded by add_columns()", False) + @util.pending_deprecation("0.7", + ":meth:`.add_column` is superceded by :meth:`.add_columns`", + False) def add_column(self, column): """Add a column expression to the list of result columns to be returned. diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index 40bbb3299..af518e407 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -58,13 +58,11 @@ class ScopedSession(object): self.registry().close() self.registry.clear() - @deprecated("Session.mapper is deprecated. " + @deprecated("0.5", ":meth:`.ScopedSession.mapper` is deprecated. " "Please see http://www.sqlalchemy.org/trac/wiki/UsageRecipes/SessionAwareMapper " "for information on how to replicate its behavior.") def mapper(self, *args, **kwargs): - """return a mapper() function which associates this ScopedSession with the Mapper. - - DEPRECATED. + """return a :func:`.mapper` function which associates this ScopedSession with the Mapper. """ diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 5f82a0200..5b5983858 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -1405,9 +1405,16 @@ class DefaultClause(FetchedValue): (self.arg, self.for_update) class PassiveDefault(DefaultClause): + """A DDL-specified DEFAULT column value. + + .. deprecated:: 0.6 :class:`.PassiveDefault` is deprecated. + Use :class:`.DefaultClause`. + """ + @util.deprecated("0.6", + ":class:`.PassiveDefault` is deprecated. " + "Use :class:`.DefaultClause`.", + False) def __init__(self, *arg, **kw): - util.warn_deprecated("PassiveDefault is deprecated. " - "Use DefaultClause.") DefaultClause.__init__(self, *arg, **kw) class Constraint(SchemaItem): diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index 0a5edb42f..be327fdfd 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -3469,8 +3469,9 @@ class _SelectBaseMixin(Executable): return self.as_scalar().label(name) @_generative - @util.deprecated(message="autocommit() is deprecated. " - "Use .execution_options(autocommit=True)") + @util.deprecated("0.6", message=":func:`.autocommit` is deprecated. " + "Use :func:`.Executable.execution_options` " + "with the 'autocommit' flag.") def autocommit(self): """return a new selectable with the 'autocommit' flag set to True.""" diff --git a/lib/sqlalchemy/util.py b/lib/sqlalchemy/util.py index d274e3635..7eb0a522f 100644 --- a/lib/sqlalchemy/util.py +++ b/lib/sqlalchemy/util.py @@ -4,7 +4,14 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -import inspect, itertools, operator, sys, warnings, weakref, gc +import inspect +import itertools +import operator +import sys +import warnings +import weakref +import re + # Py2K import __builtin__ # end Py2K @@ -1622,21 +1629,23 @@ def warn_deprecated(msg, stacklevel=3): def warn_pending_deprecation(msg, stacklevel=3): warnings.warn(msg, exc.SAPendingDeprecationWarning, stacklevel=stacklevel) -def deprecated(message=None, add_deprecation_to_docstring=True): +def deprecated(version, message=None, add_deprecation_to_docstring=True): """Decorates a function and issues a deprecation warning on use. - message + :param message: If provided, issue message in the warning. A sensible default is used if not provided. - add_deprecation_to_docstring + :param 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.' + header = ".. deprecated:: %s %s" % \ + (version, (message or '')) else: header = None @@ -1653,37 +1662,49 @@ def pending_deprecation(version, message=None, add_deprecation_to_docstring=True): """Decorates a function and issues a pending deprecation warning on use. - version + :param version: An approximate future version at which point the pending deprecation will become deprecated. Not used in messaging. - message + :param message: If provided, issue message in the warning. A sensible default is used if not provided. - add_deprecation_to_docstring + :param 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 = ".. deprecated:: %s (pending) %s" % (version, (message or '')) + header = ".. deprecated:: %s (pending) %s" % \ + (version, (message or '')) else: header = None if message is None: message = "Call to deprecated function %(func)s" - + def decorate(fn): return _decorate_with_warning( fn, exc.SAPendingDeprecationWarning, message % dict(func=fn.__name__), header) return decorate +def _sanitize_rest(text): + def repl(m): + type_, name = m.group(1, 2) + if type_ in ("func", "meth"): + name += "()" + return name + return re.sub(r'\:(\w+)\:`~?\.?(.+?)`', repl, text) + + def _decorate_with_warning(func, wtype, message, docstring_header=None): """Wrap a function with a warnings.warn and augmented docstring.""" + message = _sanitize_rest(message) + @decorator def warned(fn, *args, **kwargs): warnings.warn(wtype(message), stacklevel=3) |