Issue 4247: Docs: Provide some examples of "pass" use in the tutorial. (original) (raw)

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

I originally had that, but then I realized that if I make it a comment I can then do something like "dw." on that line when I start filling in the code to keep the comment around. Because I find that when I fill in the high level comments they make nice comments to keep around for that code block.

I'm open to the exception string, but I deliberately switched from the string to comment.

Sean