]> git.ipfire.org Git - thirdparty/sqlalchemy/sqlalchemy.git/commitdiff
get slightly better about deprecations in docstrings, tho this is kind of an uphill...
authorMike Bayer <mike_mp@zzzcomputing.com>
Tue, 10 Aug 2010 00:32:37 +0000 (20:32 -0400)
committerMike Bayer <mike_mp@zzzcomputing.com>
Tue, 10 Aug 2010 00:32:37 +0000 (20:32 -0400)
doc/build/static/docs.css
lib/sqlalchemy/engine/base.py
lib/sqlalchemy/orm/query.py
lib/sqlalchemy/orm/scoping.py
lib/sqlalchemy/schema.py
lib/sqlalchemy/sql/expression.py
lib/sqlalchemy/util.py

index c0d6345570955eca5a0c7cfa3bcc430e554566ad..145e49b8c0b66a8e4a8fd9b22fce124aad9921ab 100644 (file)
@@ -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;
index 684df51ca7eddafcf4ac0163a3fd6301a26de8c5..b481261d58c07eb9f5ba185d20345b4b48299b39 100644 (file)
@@ -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
         
index c269c8bb9fb4212a88d6535a922498577181e294..c3368748497f8a63fb5cde207a8c57791f46bf22 100644 (file)
@@ -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.
         
index 40bbb3299d9dfc2a3cc2fb624bf10e78c015c4c2..af518e407a669d1f5788bb258559d82eb03db3ea 100644 (file)
@@ -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.
 
         """
 
index 5f82a020097dd1f3bc08c757593d3ce456bc128f..5b598385879aaf79241c37de1dea7f791b802add 100644 (file)
@@ -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):
index 0a5edb42f1c57884276a8d753fc7da9aef5159b9..be327fdfd4ca8dc6a89991bca20b733ba5953f0c 100644 (file)
@@ -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."""
         
index d274e3635076abf9d0c26cc5bead40a4f3dc3476..7eb0a522f93bb32d7d0b723e1f0df233323a6c8a 100644 (file)
@@ -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)