As discussed on python-dev, add a mechanism to indicate features

that are in the process of deprecation (PendingDeprecationWarning).
Docs could be improved.

7 files changed, 48 insertions, 16 deletions

diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
index b836811..ae16082 100644
--- a/Doc/lib/libexcs.tex
+++ b/Doc/lib/libexcs.tex
@@ -376,6 +376,10 @@ Base class for warnings generated by user code.
 Base class for warnings about deprecated features.
 \end{excdesc}
 
+\begin{excdesc}{PendingDeprecationWarning}
+Base class for warnings about features which will be deprecated in the future.
+\end{excdesc}
+
 \begin{excdesc}{SyntaxWarning}
 Base class for warnings about dubious syntax
 \end{excdesc}
@@ -423,6 +427,7 @@ The class hierarchy for built-in exceptions is:
      +---Warning
 	  +-- UserWarning
 	  +-- DeprecationWarning
+	  +-- PendingDeprecationWarning
 	  +-- SyntaxWarning
 	  +-- OverflowWarning
 	  +-- RuntimeWarning
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index dcf84cb..4e2e6bd 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -2453,25 +2453,26 @@ standard module \module{__builtin__}\refbimodindex{__builtin__}:
 >>> dir(__builtin__)
 ['ArithmeticError', 'AssertionError', 'AttributeError',
  'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError',
- 'Exception', 'FloatingPointError', 'IOError', 'ImportError',
+ 'Exception', 'False', 'FloatingPointError', 'IOError', 'ImportError',
  'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
  'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
  'NotImplementedError', 'OSError', 'OverflowError', 'OverflowWarning',
- 'ReferenceError', 'RuntimeError', 'RuntimeWarning', 'StandardError',
- 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
- 'SystemExit', 'TabError', 'TypeError', 'UnboundLocalError',
- 'UnicodeError', 'UserWarning', 'ValueError', 'Warning',
- 'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
- '__name__', 'abs', 'apply', 'buffer', 'callable', 'chr', 'classmethod',
- 'cmp', 'coerce', 'compile', 'complex', 'copyright', 'credits', 'delattr',
- 'dict', 'dir', 'divmod', 'eval', 'execfile', 'exit', 'file', 'filter',
- 'float', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id',
- 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len',
- 'license', 'list', 'locals', 'long', 'map', 'max', 'min', 'object',
- 'oct', 'open', 'ord', 'pow', 'property', 'quit', 'range', 'raw_input',
- 'reduce', 'reload', 'repr', 'round', 'setattr', 'slice', 'staticmethod',
- 'str', 'super', 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange',
- 'zip']
+ 'PendingDeprecationWarning', 'ReferenceError',
+ 'RuntimeError', 'RuntimeWarning', 'StandardError', 'StopIteration',
+ 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError',
+ 'True', 'TypeError', 'UnboundLocalError', 'UnicodeError', 'UserWarning',
+ 'ValueError', 'Warning', 'ZeroDivisionError', '__debug__', '__doc__',
+ '__import__', '__name__', 'abs', 'apply', 'bool', 'buffer',
+ 'callable', 'chr', 'classmethod', 'cmp', 'coerce', 'compile', 'complex',
+ 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod',
+ 'enumerate', 'eval', 'execfile', 'exit', 'file', 'filter', 'float',
+ 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id',
+ 'input', 'int', 'intern', 'isinstance', 'issubclass', 'iter',
+ 'len', 'license', 'list', 'locals', 'long', 'map', 'max', 'min',
+ 'object', 'oct', 'open', 'ord', 'pow', 'property', 'quit',
+ 'range', 'raw_input', 'reduce', 'reload', 'repr', 'round',
+ 'setattr', 'slice', 'staticmethod', 'str', 'string', 'super',
+ 'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
 \end{verbatim}
 
 
diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex
index ffa89ef..d47fe9a 100644
--- a/Doc/whatsnew/whatsnew23.tex
+++ b/Doc/whatsnew/whatsnew23.tex
@@ -342,6 +342,15 @@ strings \samp{True} and \samp{False} instead of \samp{1} and \samp{0}.
 %\end{itemize}
 
 
+%\begin{PendingDeprecationWarning}
+A new warning PendingDeprecationWarning was added to provide
+direction on features which are in the process of being deprecated.
+The warning will not be printed by default.  To see the pending
+deprecations, use -Walways::PendingDeprecationWarning:: on the command line
+or warnings.filterwarnings().
+%\end{PendingDeprecationWarning}
+
+
 %======================================================================
 \section{Specialized Object Allocator (pymalloc)\label{section-pymalloc}}
 
diff --git a/Include/pyerrors.h b/Include/pyerrors.h
index e2e2629..fa5634a 100644
--- a/Include/pyerrors.h
+++ b/Include/pyerrors.h
@@ -66,6 +66,7 @@ extern DL_IMPORT(PyObject *) PyExc_MemoryErrorInst;
 extern DL_IMPORT(PyObject *) PyExc_Warning;
 extern DL_IMPORT(PyObject *) PyExc_UserWarning;
 extern DL_IMPORT(PyObject *) PyExc_DeprecationWarning;
+extern DL_IMPORT(PyObject *) PyExc_PendingDeprecationWarning;
 extern DL_IMPORT(PyObject *) PyExc_SyntaxWarning;
 extern DL_IMPORT(PyObject *) PyExc_OverflowWarning;
 extern DL_IMPORT(PyObject *) PyExc_RuntimeWarning;
diff --git a/Lib/warnings.py b/Lib/warnings.py
index 435f1a7..fc6154f 100644
--- a/Lib/warnings.py
+++ b/Lib/warnings.py
@@ -262,3 +262,4 @@ if __name__ == "__main__":
 else:
     _processoptions(sys.warnoptions)
     filterwarnings("ignore", category=OverflowWarning, append=1)
+    filterwarnings("ignore", category=PendingDeprecationWarning, append=1)
diff --git a/Misc/NEWS b/Misc/NEWS
index 85da0d3..2c7646d 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -6,6 +6,12 @@ Type/class unification and new-style classes
 
 Core and builtins
 
+- A new warning PendingDeprecationWarning was added to provide
+  direction on features which are in the process of being deprecated.
+  The warning will not be printed by default.  To see the pending
+  deprecations, use -Walways::PendingDeprecationWarning::
+  as a command line option or warnings.filterwarnings() in code.
+
 - A new type object, 'string', is added.  This is a common base type
   for 'str' and 'unicode', and can be used instead of
   types.StringTypes, e.g. to test whether something is "a string":
diff --git a/Python/exceptions.c b/Python/exceptions.c
index 607d5cf..bd8f55d 100644
--- a/Python/exceptions.c
+++ b/Python/exceptions.c
@@ -110,6 +110,7 @@ Exception\n\
       |\n\
       +-- UserWarning\n\
       +-- DeprecationWarning\n\
+      +-- PendingDeprecationWarning\n\
       +-- SyntaxWarning\n\
       +-- OverflowWarning\n\
       +-- RuntimeWarning";
@@ -920,6 +921,11 @@ DeprecationWarning__doc__[] =
 "Base class for warnings about deprecated features.";
 
 static char
+PendingDeprecationWarning__doc__[] =
+"Base class for warnings about features which will be deprecated "
+"in the future.";
+
+static char
 SyntaxWarning__doc__[] = "Base class for warnings about dubious syntax.";
 
 static char
@@ -987,6 +993,7 @@ PyObject *PyExc_MemoryErrorInst;
 PyObject *PyExc_Warning;
 PyObject *PyExc_UserWarning;
 PyObject *PyExc_DeprecationWarning;
+PyObject *PyExc_PendingDeprecationWarning;
 PyObject *PyExc_SyntaxWarning;
 PyObject *PyExc_OverflowWarning;
 PyObject *PyExc_RuntimeWarning;
@@ -1063,6 +1070,8 @@ static struct {
  {"UserWarning", &PyExc_UserWarning, &PyExc_Warning, UserWarning__doc__},
  {"DeprecationWarning", &PyExc_DeprecationWarning, &PyExc_Warning,
   DeprecationWarning__doc__},
+ {"PendingDeprecationWarning", &PyExc_PendingDeprecationWarning, &PyExc_Warning,
+  PendingDeprecationWarning__doc__},
  {"SyntaxWarning", &PyExc_SyntaxWarning, &PyExc_Warning, SyntaxWarning__doc__},
  {"OverflowWarning", &PyExc_OverflowWarning, &PyExc_Warning,
   OverflowWarning__doc__},