[Python-checkins] r87820 - python/branches/py3k/Doc/library/exceptions.rst

Fri Jan 7 19:28:45 CET 2011

Author: georg.brandl
Date: Fri Jan 7 19:28:45 2011
New Revision: 87820
Log:
#10856: document (Base)Exception.args better.
Modified:
 python/branches/py3k/Doc/library/exceptions.rst
Modified: python/branches/py3k/Doc/library/exceptions.rst
==============================================================================

--- python/branches/py3k/Doc/library/exceptions.rst	(original)
+++ python/branches/py3k/Doc/library/exceptions.rst	Fri Jan 7 19:28:45 2011
@@ -18,12 +18,10 @@
 
 The built-in exceptions listed below can be generated by the interpreter or
 built-in functions. Except where mentioned, they have an "associated value"
-indicating the detailed cause of the error. This may be a string or a tuple
-containing several items of information (e.g., an error code and a string
-explaining the code). The associated value is usually passed to the exception
-class's constructor. If the exception class is derived from the standard root
-class :exc:`BaseException`, the associated value is present as the exception
-instance's :attr:`args` attribute.
+indicating the detailed cause of the error. This may be a string or a tuple of
+several items of information (e.g., an error code and a string explaining the
+code). The associated value is usually passed as arguments to the exception
+class's constructor.
 
 User code can raise built-in exceptions. This can be used to test an exception
 handler or to report an error condition "just like" the situation in which the
@@ -38,16 +36,32 @@
 
 The following exceptions are used mostly as base classes for other exceptions.
 
-.. XXX document with_traceback()
-
 .. exception:: BaseException
 
 The base class for all built-in exceptions. It is not meant to be directly
- inherited by user-defined classes (for that use :exc:`Exception`). If
+ inherited by user-defined classes (for that, use :exc:`Exception`). If
 :func:`bytes` or :func:`str` is called on an instance of this class, the
- representation of the argument(s) to the instance are returned or the empty
- string when there were no arguments. All arguments are stored in :attr:`args`
- as a tuple.
+ representation of the argument(s) to the instance are returned, or the empty
+ string when there were no arguments.
+
+ .. attribute:: args
+
+ The tuple of arguments given to the exception constructor. Some built-in
+ exceptions (like :exc:`IOError`) expect a certain number of arguments and
+ assign a special meaning to the elements of this tuple, while others are
+ usually called only with a single string giving an error message.
+
+ .. method:: with_traceback(tb)
+
+ This method sets *tb* as the new traceback for the exception and returns
+ the exception object. It is usually used in exception handling code like
+ this::
+
+ try:
+ ...
+ except SomeException:
+ tb = sys.exc_info()[2]
+ raise OtherException(...).with_traceback(tb)
 
 
 .. exception:: Exception
