Skip to content

Commit aef22fb

Browse files
rhettingerrhettinger
committed
Patch 560023 adding docstrings. 2.2 Candidate (after verifying modules were not updated after 2.2).
1 parent d68f517 commit aef22fb

9 files changed

Lines changed: 499 additions & 8 deletions

File tree

‎Lib/MimeWriter.py‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
"""Generic MIME writer.
22
3-
Classes:
4-
5-
MimeWriter - the only thing here.
3+
This module defines the class MimeWriter. The MimeWriter class implements
4+
a basic formatter for creating MIME multi-part files. It doesn't seek around
5+
the output file nor does it use large amounts of buffer space. You must write
6+
the parts out in the order that they should occur in the final file.
7+
MimeWriter does buffer the headers you add, allowing you to rearrange their
8+
order.
69
710
"""
811

@@ -86,6 +89,14 @@ def __init__(self, fp):
8689
self._headers = []
8790

8891
def addheader(self, key, value, prefix=0):
92+
"""Add a header line to the MIME message.
93+
94+
The key is the name of the header, where the value obviously provides
95+
the value of the header. The optional argument prefix determines
96+
where the header is inserted; 0 means append at the end, 1 means
97+
insert at the start. The default is to append.
98+
99+
"""
89100
lines = value.split("\n")
90101
while lines and not lines[-1]: del lines[-1]
91102
while lines and not lines[0]: del lines[0]
@@ -99,10 +110,26 @@ def addheader(self, key, value, prefix=0):
99110
self._headers.append(line)
100111

101112
def flushheaders(self):
113+
"""Writes out and forgets all headers accumulated so far.
114+
115+
This is useful if you don't need a body part at all; for example,
116+
for a subpart of type message/rfc822 that's (mis)used to store some
117+
header-like information.
118+
119+
"""
102120
self._fp.writelines(self._headers)
103121
self._headers = []
104122

105123
def startbody(self, ctype, plist=[], prefix=1):
124+
"""Returns a file-like object for writing the body of the message.
125+
126+
The content-type is set to the provided ctype, and the optional
127+
parameter, plist, provides additional parameters for the
128+
content-type declaration. The optional argument prefix determines
129+
where the header is inserted; 0 means append at the end, 1 means
130+
insert at the start. The default is to insert at the start.
131+
132+
"""
106133
for name, value in plist:
107134
ctype = ctype + ';\n %s=\"%s\"' % (name, value)
108135
self.addheader("Content-Type", ctype, prefix=prefix)
@@ -111,16 +138,42 @@ def startbody(self, ctype, plist=[], prefix=1):
111138
return self._fp
112139

113140
def startmultipartbody(self, subtype, boundary=None, plist=[], prefix=1):
141+
"""Returns a file-like object for writing the body of the message.
142+
143+
Additionally, this method initializes the multi-part code, where the
144+
subtype parameter provides the multipart subtype, the boundary
145+
parameter may provide a user-defined boundary specification, and the
146+
plist parameter provides optional parameters for the subtype. The
147+
optional argument, prefix, determines where the header is inserted;
148+
0 means append at the end, 1 means insert at the start. The default
149+
is to insert at the start. Subparts should be created using the
150+
nextpart() method.
151+
152+
"""
114153
self._boundary = boundary or mimetools.choose_boundary()
115154
return self.startbody("multipart/" + subtype,
116155
[("boundary", self._boundary)] + plist,
117156
prefix=prefix)
118157

119158
def nextpart(self):
159+
"""Returns a new instance of MimeWriter which represents an
160+
individual part in a multipart message.
161+
162+
This may be used to write the part as well as used for creating
163+
recursively complex multipart messages. The message must first be
164+
initialized with the startmultipartbody() method before using the
165+
nextpart() method.
166+
167+
"""
120168
self._fp.write("\n--" + self._boundary + "\n")
121169
return self.__class__(self._fp)
122170

123171
def lastpart(self):
172+
"""This is used to designate the last part of a multipart message.
173+
174+
It should always be used when writing multipart messages.
175+
176+
"""
124177
self._fp.write("\n--" + self._boundary + "--\n")
125178

126179

‎Lib/cmd.py‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,17 @@
5353
IDENTCHARS = string.ascii_letters + string.digits + '_'
5454

5555
class Cmd:
56+
"""A simple framework for writing line-oriented command interpreters.
57+
58+
These are often useful for test harnesses, administrative tools, and
59+
prototypes that will later be wrapped in a more sophisticated interface.
60+
61+
A Cmd instance or subclass instance is a line-oriented interpreter
62+
framework. There is no good reason to instantiate Cmd itself; rather,
63+
it's useful as a superclass of an interpreter class you define yourself
64+
in order to inherit Cmd's methods and encapsulate action methods.
65+
66+
"""
5667
prompt = PROMPT
5768
identchars = IDENTCHARS
5869
ruler = '='
@@ -67,6 +78,14 @@ class Cmd:
6778
use_rawinput = 1
6879

6980
def __init__(self, completekey='tab'):
81+
"""Instantiate a line-oriented interpreter framework.
82+
83+
The optional argument is the readline name of a completion key;
84+
it defaults to the Tab key. If completekey is not None and the
85+
readline module is available, command completion is done
86+
automatically.
87+
88+
"""
7089
if completekey:
7190
try:
7291
import readline
@@ -76,6 +95,12 @@ def __init__(self, completekey='tab'):
7695
pass
7796

7897
def cmdloop(self, intro=None):
98+
"""Repeatedly issue a prompt, accept input, parse an initial prefix
99+
off the received input, and dispatch to action methods, passing them
100+
the remainder of the line as argument.
101+
102+
"""
103+
79104
self.preloop()
80105
if intro is not None:
81106
self.intro = intro
@@ -106,15 +131,25 @@ def cmdloop(self, intro=None):
106131
self.postloop()
107132

108133
def precmd(self, line):
134+
"""Hook method executed just before the command line is
135+
interpreted, but after the input prompt is generated and issued.
136+
137+
"""
109138
return line
110139

111140
def postcmd(self, stop, line):
141+
"""Hook method executed just after a command dispatch is finished."""
112142
return stop
113143

114144
def preloop(self):
145+
"""Hook method executed once when the cmdloop() method is called."""
115146
pass
116147

117148
def postloop(self):
149+
"""Hook method executed once when the cmdloop() method is about to
150+
return.
151+
152+
"""
118153
pass
119154

120155
def parseline(self, line):
@@ -134,6 +169,15 @@ def parseline(self, line):
134169
return cmd, arg, line
135170

136171
def onecmd(self, line):
172+
"""Interpret the argument as though it had been typed in response
173+
to the prompt.
174+
175+
This may be overridden, but should not normally need to be;
176+
see the precmd() and postcmd() methods for useful execution hooks.
177+
The return value is a flag indicating whether interpretation of
178+
commands by the interpreter should stop.
179+
180+
"""
137181
cmd, arg, line = self.parseline(line)
138182
if not line:
139183
return self.emptyline()
@@ -150,13 +194,31 @@ def onecmd(self, line):
150194
return func(arg)
151195

152196
def emptyline(self):
197+
"""Called when an empty line is entered in response to the prompt.
198+
199+
If this method is not overridden, it repeats the last nonempty
200+
command entered.
201+
202+
"""
153203
if self.lastcmd:
154204
return self.onecmd(self.lastcmd)
155205

156206
def default(self, line):
207+
"""Called on an input line when the command prefix is not recognized.
208+
209+
If this method is not overridden, it prints an error message and
210+
returns.
211+
212+
"""
157213
print '*** Unknown syntax:', line
158214

159215
def completedefault(self, *ignored):
216+
"""Method called to complete an input line when no command-specific
217+
complete_*() method is available.
218+
219+
By default, it returns an empty list.
220+
221+
"""
160222
return []
161223

162224
def completenames(self, text, *ignored):

‎Lib/dumbdbm.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,5 +154,17 @@ def __del__(self):
154154

155155

156156
def open(file, flag=None, mode=0666):
157+
"""Open the database file, filename, and return corresponding object.
158+
159+
The flag argument, used to control how the database is opened in the
160+
other DBM implementations, is ignored in the dumbdbm module; the
161+
database is always opened for update, and will be created if it does
162+
not exist.
163+
164+
The optional mode argument is the UNIX mode of the file, used only when
165+
the database has to be created. It defaults to octal code 0666 (and
166+
will be modified by the prevailing umask).
167+
168+
"""
157169
# flag, mode arguments are currently ignored
158170
return _Database(file, mode)

‎Lib/formatter.py‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,15 @@
2727

2828

2929
class NullFormatter:
30+
"""A formatter which does nothing.
31+
32+
If the writer parameter is omitted, a NullWriter instance is created.
33+
No methods of the writer are called by NullFormatter instances.
34+
35+
Implementations should inherit from this class if implementing a writer
36+
interface but don't need to inherit any implementation.
37+
38+
"""
3039

3140
def __init__(self, writer=None):
3241
if not writer:
@@ -52,6 +61,13 @@ def assert_line_data(self, flag=1): pass
5261

5362

5463
class AbstractFormatter:
64+
"""The standard formatter.
65+
66+
This implementation has demonstrated wide applicability to many writers,
67+
and may be used directly in most circumstances. It has been used to
68+
implement a full-featured World Wide Web browser.
69+
70+
"""
5571

5672
# Space handling policy: blank spaces at the boundary between elements
5773
# are handled by the outermost context. "Literal" data is not checked
@@ -283,7 +299,13 @@ def assert_line_data(self, flag=1):
283299

284300

285301
class NullWriter:
286-
"""Minimal writer interface to use in testing & inheritance."""
302+
"""Minimal writer interface to use in testing & inheritance.
303+
304+
A writer which only provides the interface definition; no actions are
305+
taken on any methods. This should be the base class for all writers
306+
which do not need to inherit any implementation methods.
307+
308+
"""
287309
def __init__(self): pass
288310
def flush(self): pass
289311
def new_alignment(self, align): pass
@@ -300,6 +322,12 @@ def send_literal_data(self, data): pass
300322

301323

302324
class AbstractWriter(NullWriter):
325+
"""A writer which can be used in debugging formatters, but not much else.
326+
327+
Each method simply announces itself by printing its name and
328+
arguments on standard output.
329+
330+
"""
303331

304332
def new_alignment(self, align):
305333
print "new_alignment(%s)" % `align`
@@ -336,6 +364,13 @@ def send_literal_data(self, data):
336364

337365

338366
class DumbWriter(NullWriter):
367+
"""Simple writer class which writes output on the file object passed in
368+
as the file parameter or, if file is omitted, on standard output. The
369+
output is simply word-wrapped to the number of columns specified by
370+
the maxcol parameter. This class is suitable for reflowing a sequence
371+
of paragraphs.
372+
373+
"""
339374

340375
def __init__(self, file=None, maxcol=72):
341376
self.file = file or sys.stdout

‎Lib/gzip.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,52 @@ def read32(input):
2727
return struct.unpack("<l", input.read(4))[0]
2828

2929
def open(filename, mode="rb", compresslevel=9):
30+
"""Shorthand for GzipFile(filename, mode, compresslevel).
31+
32+
The filename argument is required; mode defaults to 'rb'
33+
and compresslevel defaults to 9.
34+
35+
"""
3036
return GzipFile(filename, mode, compresslevel)
3137

3238
class GzipFile:
39+
"""The GzipFile class simulates most of the methods of a file object with
40+
the exception of the readinto(), truncate(), and xreadlines() methods.
41+
42+
"""
3343

3444
myfileobj = None
3545

3646
def __init__(self, filename=None, mode=None,
3747
compresslevel=9, fileobj=None):
48+
"""Constructor for the GzipFile class.
49+
50+
At least one of fileobj and filename must be given a
51+
non-trivial value.
52+
53+
The new class instance is based on fileobj, which can be a regular
54+
file, a StringIO object, or any other object which simulates a file.
55+
It defaults to None, in which case filename is opened to provide
56+
a file object.
57+
58+
When fileobj is not None, the filename argument is only used to be
59+
included in the gzip file header, which may includes the original
60+
filename of the uncompressed file. It defaults to the filename of
61+
fileobj, if discernible; otherwise, it defaults to the empty string,
62+
and in this case the original filename is not included in the header.
63+
64+
The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', or 'wb',
65+
depending on whether the file will be read or written. The default
66+
is the mode of fileobj if discernible; otherwise, the default is 'rb'.
67+
Be aware that only the 'rb', 'ab', and 'wb' values should be used
68+
for cross-platform portability.
69+
70+
The compresslevel argument is an integer from 1 to 9 controlling the
71+
level of compression; 1 is fastest and produces the least compression,
72+
and 9 is slowest and produces the most compression. The default is 9.
73+
74+
"""
75+
3876
# guarantee the file is opened in binary mode on platforms
3977
# that care about that sort of thing
4078
if mode and 'b' not in mode:

0 commit comments

Comments
 (0)