Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e7b146f

Browse files
gvanrossumgvanrossum
committed
The third and final doc-string sweep by Ka-Ping Yee.
The attached patches update the standard library so that all modules have docstrings beginning with one-line summaries. A new docstring was added to formatter. The docstring for os.py was updated to mention nt, os2, ce in addition to posix, dos, mac.
1 parent 54f22ed commit e7b146f

29 files changed

Lines changed: 942 additions & 829 deletions

‎Lib/quopri.py‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,34 @@
11
#! /usr/bin/env python
22

3-
# Conversions to/from quoted-printable transport encoding as per RFC-1521
3+
"""Conversions to/from quoted-printable transport encoding as per RFC-1521."""
4+
45
# (Dec 1991 version).
56

67
ESCAPE = '='
78
MAXLINESIZE = 76
89
HEX = '0123456789ABCDEF'
910

1011
def needsquoting(c, quotetabs):
12+
"""Decide whether a particular character needs to be quoted.
13+
14+
The 'quotetabs' flag indicates whether tabs should be quoted."""
1115
if c == '\t':
1216
return not quotetabs
1317
return c == ESCAPE or not(' ' <= c <= '~')
1418

1519
def quote(c):
20+
"""Quote a single character."""
1621
if c == ESCAPE:
1722
return ESCAPE * 2
1823
else:
1924
i = ord(c)
2025
return ESCAPE + HEX[i/16] + HEX[i%16]
2126

2227
def encode(input, output, quotetabs):
28+
"""Read 'input', apply quoted-printable encoding, and write to 'output'.
29+
30+
'input' and 'output' are files with readline() and write() methods.
31+
The 'quotetabs' flag indicates whether tabs should be quoted."""
2332
while 1:
2433
line = input.readline()
2534
if not line: break
@@ -42,6 +51,9 @@ def encode(input, output, quotetabs):
4251
output.write(new + '\n')
4352

4453
def decode(input, output):
54+
"""Read 'input', apply quoted-printable decoding, and write to 'output'.
55+
56+
'input' and 'output' are files with readline() and write() methods."""
4557
new = ''
4658
while 1:
4759
line = input.readline()
@@ -73,9 +85,11 @@ def decode(input, output):
7385
output.write(new)
7486

7587
def ishex(c):
88+
"""Return true if the character 'c' is a hexadecimal digit."""
7689
return '0' <= c <= '9' or 'a' <= c <= 'f' or 'A' <= c <= 'F'
7790

7891
def unhex(s):
92+
"""Get the integer value of a hexadecimal number."""
7993
bits = 0
8094
for c in s:
8195
if '0' <= c <= '9':

‎Lib/random.py‎

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,24 @@
1-
# R A N D O M V A R I A B L E G E N E R A T O R S
2-
#
3-
# distributions on the real line:
4-
# ------------------------------
5-
# normal (Gaussian)
6-
# lognormal
7-
# negative exponential
8-
# gamma
9-
# beta
10-
#
11-
# distributions on the circle (angles 0 to 2pi)
12-
# ---------------------------------------------
13-
# circular uniform
14-
# von Mises
15-
16-
# Translated from anonymously contributed C/C++ source.
17-
18-
# Multi-threading note: the random number generator used here is not
19-
# thread-safe; it is possible that two calls return the same random
20-
# value. See whrandom.py for more info.
1+
"""Random variable generators.
2+
3+
distributions on the real line:
4+
------------------------------
5+
normal (Gaussian)
6+
lognormal
7+
negative exponential
8+
gamma
9+
beta
10+
11+
distributions on the circle (angles 0 to 2pi)
12+
---------------------------------------------
13+
circular uniform
14+
von Mises
15+
16+
Translated from anonymously contributed C/C++ source.
17+
18+
Multi-threading note: the random number generator used here is not
19+
thread-safe; it is possible that two calls return the same random
20+
value. See whrandom.py for more info.
21+
"""
2122

2223
import whrandom
2324
from whrandom import random, uniform, randint, choice, randrange # For export!

‎Lib/regex_syntax.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
1-
# These bits are passed to regex.set_syntax() to choose among
2-
# alternative regexp syntaxes.
1+
"""Constants for selecting regexp syntaxes for the obsolete regex module.
2+
3+
This module is only for backward compatibility. "regex" has now
4+
been replaced by the new regular expression module, "re".
5+
6+
These bits are passed to regex.set_syntax() to choose among
7+
alternative regexp syntaxes.
8+
"""
39

410
# 1 means plain parentheses serve as grouping, and backslash
511
# parentheses are needed for literal searching.

‎Lib/regsub.py‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1-
# Regular expression subroutines:
2-
# sub(pat, repl, str): replace first occurrence of pattern in string
3-
# gsub(pat, repl, str): replace all occurrences of pattern in string
4-
# split(str, pat, maxsplit): split string using pattern as delimiter
5-
# splitx(str, pat, maxsplit): split string using pattern as delimiter plus
6-
# return delimiters
1+
"""Regexp-based split and replace using the obsolete regex module.
72
3+
This module is only for backward compatibility. These operations
4+
are now provided by the new regular expression module, "re".
5+
6+
sub(pat, repl, str): replace first occurrence of pattern in string
7+
gsub(pat, repl, str): replace all occurrences of pattern in string
8+
split(str, pat, maxsplit): split string using pattern as delimiter
9+
splitx(str, pat, maxsplit): split string using pattern as delimiter plus
10+
return delimiters
11+
"""
812

913
import regex
1014

‎Lib/repr.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Redo the `...` (representation) but with limits on most sizes.
1+
"""Redo the `...` (representation) but with limits on most sizes."""
22

33
import string
44

‎Lib/sgmllib.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# A parser for SGML, using the derived class as static DTD.
1+
"""A parser for SGML, using the derived class as a static DTD."""
22

33
# XXX This only supports those SGML features used by HTML.
44

‎Lib/shlex.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
"""A lexical analyzer class for simple shell-like syntaxes."""
2+
13
# Module and documentation by Eric S. Raymond, 21 Dec 1998
24

35
import sys

‎Lib/shutil.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""Utility functions for copying files.
1+
"""Utility functions for copying files and directory trees.
22
33
XXX The functions here don't copy the resource fork or other metadata on Mac.
44

‎Lib/stat.py‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
1-
# Module 'stat'
2-
#
3-
# Defines constants and functions for interpreting stat/lstat struct
4-
# as returned by os.stat() and os.lstat() (if it exists).
5-
#
6-
# Suggested usage: from stat import *
7-
#
1+
"""Constants/functions for interpreting results of os.stat() and os.lstat().
2+
3+
Suggested usage: from stat import *
4+
"""
5+
86
# XXX Strictly spoken, this module may have to be adapted for each POSIX
97
# implementation; in practice, however, the numeric constants used by
108
# stat() are almost universal (even for stat() emulations on non-UNIX

‎Lib/statcache.py‎

Lines changed: 12 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
# Module 'statcache'
2-
#
3-
# Maintain a cache of file stats.
4-
# There are functions to reset the cache or to selectively remove items.
1+
"""Maintain a cache of file stats.
2+
There are functions to reset the cache or to selectively remove items.
3+
"""
54

65
import os
76
from stat import *
@@ -12,42 +11,37 @@
1211
cache = {}
1312

1413

15-
# Stat a file, possibly out of the cache.
16-
#
1714
def stat(path):
15+
"""Stat a file, possibly out of the cache."""
1816
if cache.has_key(path):
1917
return cache[path]
2018
cache[path] = ret = os.stat(path)
2119
return ret
2220

2321

24-
# Reset the cache completely.
25-
#
2622
def reset():
23+
"""Reset the cache completely."""
2724
global cache
2825
cache = {}
2926

3027

31-
# Remove a given item from the cache, if it exists.
32-
#
3328
def forget(path):
29+
"""Remove a given item from the cache, if it exists."""
3430
if cache.has_key(path):
3531
del cache[path]
3632

3733

38-
# Remove all pathnames with a given prefix.
39-
#
4034
def forget_prefix(prefix):
35+
"""Remove all pathnames with a given prefix."""
4136
n = len(prefix)
4237
for path in cache.keys():
4338
if path[:n] == prefix:
4439
del cache[path]
4540

4641

47-
# Forget about a directory and all entries in it, but not about
48-
# entries in subdirectories.
49-
#
5042
def forget_dir(prefix):
43+
"""Forget about a directory and all entries in it, but not about
44+
entries in subdirectories."""
5145
if prefix[-1:] == '/' and prefix <> '/':
5246
prefix = prefix[:-1]
5347
forget(prefix)
@@ -62,19 +56,17 @@ def forget_dir(prefix):
6256
del cache[path]
6357

6458

65-
# Remove all pathnames except with a given prefix.
66-
# Normally used with prefix = '/' after a chdir().
67-
#
6859
def forget_except_prefix(prefix):
60+
"""Remove all pathnames except with a given prefix.
61+
Normally used with prefix = '/' after a chdir()."""
6962
n = len(prefix)
7063
for path in cache.keys():
7164
if path[:n] <> prefix:
7265
del cache[path]
7366

7467

75-
# Check for directory.
76-
#
7768
def isdir(path):
69+
"""Check for directory."""
7870
try:
7971
st = stat(path)
8072
except os.error:

0 commit comments

Comments
 (0)