[New-bugs-announce] [issue4247] Docs: Provide some examples of "pass" use in the tutorial.

[Sean Reifschneider]

New submission from Sean Reifschneider <jafo at tummy.com>:

I'm giving a Python tutorial to a bunch of local people and have decided
to use the Python.org tutorial to go by.  One of the things I found I
wanted in the section on the "pass" statement was more information about
it's use.  But I also think it's worth mentioning using the
NotImplementedError if pass is used for stubbing out code.

This patch to the tutorial includes some example use cases, and also a
reference to NotImplementedError.  I would appreciate some review
however, as I'm not sure this discussion is appropriate.

Included below is the patch, for ease of reading, but it's also attached as
a patch (taken against trunk today).

Sean
===========

Index: Doc/tutorial/controlflow.rst
===================================================================
--- Doc/tutorial/controlflow.rst	(revision 67072)
+++ Doc/tutorial/controlflow.rst	(working copy)
@@ -166,7 +166,36 @@
    ...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
    ... 
 
+This is commonly used for creating minimal classes like with exceptions, or
+for skipping unwanted exceptions::
 
+   >>> class ParserError(Exception):
+   ...     pass
+   ... 
+   >>> try:
+   ...     import audioop
+   ... except ImportError:
+   ...     pass
+   ... 
+
+Another place it 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, allowing you to tell exactly where code that you
+need to complete is.
+
 .. _tut-functions:
 
 Defining Functions

----------
assignee: fdrake
components: Documentation
files: pass-examples.patch
keywords: easy, needs review, patch, patch
messages: 75452
nosy: fdrake, jafo
priority: normal
severity: normal
status: open
title: Docs: Provide some examples of "pass" use in the tutorial.
type: feature request
versions: Python 2.7
Added file: http://bugs.python.org/file11926/pass-examples.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4247>
_______________________________________