More trivial comment -> docstring transformations by Ka-Ping Yee,
who writes:
Here is batch 2, as a big collection of CVS context diffs.
Along with moving comments into docstrings, i've added a
couple of missing docstrings and attempted to make sure more
module docstrings begin with a one-line summary.
I did not add docstrings to the methods in profile.py for
fear of upsetting any careful optimizations there, though
i did move class documentation into class docstrings.
The convention i'm using is to leave credits/version/copyright
type of stuff in # comments, and move the rest of the descriptive
stuff about module usage into module docstrings. Hope this is
okay.
diff --git a/Lib/pipes.py b/Lib/pipes.py
index b82ed0c..4057fac 100644
--- a/Lib/pipes.py
+++ b/Lib/pipes.py
@@ -1,63 +1,62 @@
-# Conversion pipeline templates
-# =============================
+"""Conversion pipeline templates.
+
+The problem:
+------------
+
+Suppose you have some data that you want to convert to another format
+(e.g. from GIF image format to PPM image format). Maybe the
+conversion involves several steps (e.g. piping it through compress or
+uuencode). Some of the conversion steps may require that their input
+is a disk file, others may be able to read standard input; similar for
+their output. The input to the entire conversion may also be read
+from a disk file or from an open file, and similar for its output.
+
+The module lets you construct a pipeline template by sticking one or
+more conversion steps together. It will take care of creating and
+removing temporary files if they are necessary to hold intermediate
+data. You can then use the template to do conversions from many
+different sources to many different destinations. The temporary
+file names used are different each time the template is used.
+
+The templates are objects so you can create templates for many
+different conversion steps and store them in a dictionary, for
+instance.
-# The problem:
-# ------------
-#
-# Suppose you have some data that you want to convert to another format
-# (e.g. from GIF image format to PPM image format). Maybe the
-# conversion involves several steps (e.g. piping it through compress or
-# uuencode). Some of the conversion steps may require that their input
-# is a disk file, others may be able to read standard input; similar for
-# their output. The input to the entire conversion may also be read
-# from a disk file or from an open file, and similar for its output.
-#
-# The module lets you construct a pipeline template by sticking one or
-# more conversion steps together. It will take care of creating and
-# removing temporary files if they are necessary to hold intermediate
-# data. You can then use the template to do conversions from many
-# different sources to many different destinations. The temporary
-# file names used are different each time the template is used.
-#
-# The templates are objects so you can create templates for many
-# different conversion steps and store them in a dictionary, for
-# instance.
+Directions:
+-----------
+To create a template:
+ t = Template()
-# Directions:
-# -----------
-#
-# To create a template:
-# t = Template()
-#
-# To add a conversion step to a template:
-# t.append(command, kind)
-# where kind is a string of two characters: the first is '-' if the
-# command reads its standard input or 'f' if it requires a file; the
-# second likewise for the output. The command must be valid /bin/sh
-# syntax. If input or output files are required, they are passed as
-# $IN and $OUT; otherwise, it must be possible to use the command in
-# a pipeline.
-#
-# To add a conversion step at the beginning:
-# t.prepend(command, kind)
-#
-# To convert a file to another file using a template:
-# sts = t.copy(infile, outfile)
-# If infile or outfile are the empty string, standard input is read or
-# standard output is written, respectively. The return value is the
-# exit status of the conversion pipeline.
-#
-# To open a file for reading or writing through a conversion pipeline:
-# fp = t.open(file, mode)
-# where mode is 'r' to read the file, or 'w' to write it -- just like
-# for the built-in function open() or for os.popen().
-#
-# To create a new template object initialized to a given one:
-# t2 = t.clone()
-#
-# For an example, see the function test() at the end of the file.
+To add a conversion step to a template:
+ t.append(command, kind)
+where kind is a string of two characters: the first is '-' if the
+command reads its standard input or 'f' if it requires a file; the
+second likewise for the output. The command must be valid /bin/sh
+syntax. If input or output files are required, they are passed as
+$IN and $OUT; otherwise, it must be possible to use the command in
+a pipeline.
+
+To add a conversion step at the beginning:
+ t.prepend(command, kind)
+
+To convert a file to another file using a template:
+ sts = t.copy(infile, outfile)
+If infile or outfile are the empty string, standard input is read or
+standard output is written, respectively. The return value is the
+exit status of the conversion pipeline.
+
+To open a file for reading or writing through a conversion pipeline:
+ fp = t.open(file, mode)
+where mode is 'r' to read the file, or 'w' to write it -- just like
+for the built-in function open() or for os.popen().
+
+To create a new template object initialized to a given one:
+ t2 = t.clone()
+
+For an example, see the function test() at the end of the file.
+"""
import sys
@@ -81,37 +80,36 @@
SOURCE, SINK]
-# A pipeline template is a Template object:
-
class Template:
+ """Class representing a pipeline template."""
- # Template() returns a fresh pipeline template
def __init__(self):
+ """Template() returns a fresh pipeline template."""
self.debugging = 0
self.reset()
- # t.__repr__() implements `t`
def __repr__(self):
+ """t.__repr__() implements `t`."""
return '<Template instance, steps=' + `self.steps` + '>'
- # t.reset() restores a pipeline template to its initial state
def reset(self):
+ """t.reset() restores a pipeline template to its initial state."""
self.steps = []
- # t.clone() returns a new pipeline template with identical
- # initial state as the current one
def clone(self):
+ """t.clone() returns a new pipeline template with identical
+ initial state as the current one."""
t = Template()
t.steps = self.steps[:]
t.debugging = self.debugging
return t
- # t.debug(flag) turns debugging on or off
def debug(self, flag):
+ """t.debug(flag) turns debugging on or off."""
self.debugging = flag
- # t.append(cmd, kind) adds a new step at the end
def append(self, cmd, kind):
+ """t.append(cmd, kind) adds a new step at the end."""
if type(cmd) <> type(''):
raise TypeError, \
'Template.append: cmd must be a string'
@@ -132,8 +130,8 @@
'Template.append: missing $OUT in cmd'
self.steps.append((cmd, kind))
- # t.prepend(cmd, kind) adds a new step at the front
def prepend(self, cmd, kind):
+ """t.prepend(cmd, kind) adds a new step at the front."""
if type(cmd) <> type(''):
raise TypeError, \
'Template.prepend: cmd must be a string'
@@ -154,9 +152,9 @@
'Template.prepend: missing $OUT in cmd'
self.steps.insert(0, (cmd, kind))
- # t.open(file, rw) returns a pipe or file object open for
- # reading or writing; the file is the other end of the pipeline
def open(self, file, rw):
+ """t.open(file, rw) returns a pipe or file object open for
+ reading or writing; the file is the other end of the pipeline."""
if rw == 'r':
return self.open_r(file)
if rw == 'w':
@@ -164,10 +162,9 @@
raise ValueError, \
'Template.open: rw must be \'r\' or \'w\', not ' + `rw`
- # t.open_r(file) and t.open_w(file) implement
- # t.open(file, 'r') and t.open(file, 'w') respectively
-
def open_r(self, file):
+ """t.open_r(file) and t.open_w(file) implement
+ t.open(file, 'r') and t.open(file, 'w') respectively."""
if self.steps == []:
return open(file, 'r')
if self.steps[-1][1] == SINK: