Merged revisions 67117-67119,67123-67124,67143 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r67117 | georg.brandl | 2008-11-06 11:17:58 +0100 (Thu, 06 Nov 2008) | 2 lines
#4268: Use correct module for two toplevel functions.
........
r67118 | georg.brandl | 2008-11-06 11:19:11 +0100 (Thu, 06 Nov 2008) | 2 lines
#4267: small fixes in sqlite3 docs.
........
r67119 | georg.brandl | 2008-11-06 11:20:49 +0100 (Thu, 06 Nov 2008) | 2 lines
#4245: move Thread section to the top.
........
r67123 | georg.brandl | 2008-11-06 19:49:15 +0100 (Thu, 06 Nov 2008) | 2 lines
#4247: add "pass" examples to tutorial.
........
r67124 | andrew.kuchling | 2008-11-06 20:23:02 +0100 (Thu, 06 Nov 2008) | 1 line
Fix grammar error; reword two paragraphs
........
r67143 | georg.brandl | 2008-11-07 09:27:39 +0100 (Fri, 07 Nov 2008) | 2 lines
Fix syntax.
........
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 5fdddcb..2a55cf1 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -196,6 +196,41 @@
... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...
+This is commonly used for creating minimal classes such as exceptions, or
+for ignoring unwanted exceptions::
+
+ >>> class ParserError(Exception):
+ ... pass
+ ...
+ >>> try:
+ ... import audioop
+ ... except ImportError:
+ ... pass
+ ...
+
+Another place :keyword:`pass` can be used is as a place-holder for a function or
+conditional body when you are working on new code, allowing you to keep
+thinking at a more abstract level. However, as :keyword:`pass` is silently
+ignored, a better choice may be to raise a :exc:`NotImplementedError`
+exception::
+
+ >>> def initlog(*args):
+ ... raise NotImplementedError # Open logfile if not already open
+ ... if not logfp:
+ ... raise NotImplementedError # Set up dummy log back-end
+ ... raise NotImplementedError('Call log initialization handler')
+ ...
+
+If :keyword:`pass` were used here and you later ran tests, they may fail
+without indicating why. Using :exc:`NotImplementedError` causes this code
+to raise an exception, telling you exactly where the incomplete code
+is. Note the two calling styles of the exceptions above.
+The first style, with no message but with an accompanying comment,
+lets you easily leave the comment when you remove the exception,
+which ideally would be a good description for
+the block of code the exception is a placeholder for. However, the
+third example, providing a message for the exception, will produce
+a more useful traceback.
.. _tut-functions: