~sambuddhabasu1/mailman/fix_mailman_run

1

Python coding style guide for Mailman

2

3

$Revision: 8145 $

2

4

3

5

4

NOTE: The canonical version of this style guide can be found at:

6

5

18

17

preferences used instead.

19

18

20

19

Remember rule #1, A Foolish Consistency is the Hobgoblin of Little Minds.

21

That said, here's a quick outline of where my preferences depart from Guido's:

22

23

- Imports usually should be on separate lines. While it's sometimes

24

okay to say

25

26

from types import StringType, ListType

27

28

it's never okay to say

29

30

import os, sys

31

32

Put these on separate lines.

20

That said, here's a quick outline of where my preferences depart from PEP 8.

21

22

- After file comments (e.g. license block), add a __metaclass__ definition so

23

that (in Python 2.x) all classes will be new-style. Following that, add an

24

__all__ section that names, one-per-line, all the public names exported by

25

this module.

33

26

34

27

- Imports are always put at the top of the file, just after any module

35

comments and docstrings, and before module globals and constants.

28

comments and docstrings, and before module globals and constants, but after

29

any __future__ imports, or __metaclass__ and __all__ definitions.

30

36

31

Imports should be grouped, with the order being:

37

32

38

33

1. standard library imports

39

2. related major package imports (i.e. all email package imports next)

34

2. related major package imports (e.g. all email package imports next)

40

35

3. application specific imports

41

36

42

37

From-imports should follow non-from imports. Dotted imports should follow

43

38

non-dotted imports. Non-dotted imports should be grouped by increasing

44

length, while dotted imports should be grouped roughly alphabetically.

39

length, while dotted imports should be grouped alphabetically.

45

40

46

41

- In general, there should be at most one class per module, if the module

47

42

contains class definitions. If it's a module of functions, that's fine,

48

43

group them as common sense dictates. A class-containing module can also

49

contain some helper functions, but it's best to keep these non-public

50

(i.e. use a single leading underscore).

44

contain some helper functions, but it's best to keep these non-public by not

45

including them in the __all__ section.

51

46

52

Always give the class and the module the same name, differing only by case

53

as PEP 8 recommends. E.g.

47

Give the class and the module the same name, differing only by case as PEP 8

48

recommends. E.g.

54

49

55

50

from mailman.parser import Parser

56

51

67

62

68

63

and use "myclass.MyClass"

69

64

65

You can also use 'import...as' to rename a clashing symbol.

66

70

67

- Right hanging comments are discouraged, in favor of preceding comments.

71

E.g.

68

E.g. bad:

72

69

73

70

foo = blarzigop(bar) # if you don't blarzigop it, it'll shlorp

74

71

75

should be written as

72

Good:

76

73

77

# if you don't blarzigop it, it'll shlorp

74

# If you don't blarzigop it, it'll shlorp.

78

75

foo = blarzigop(bar)

79

76

77

Comments should always be complete sentences, with proper capitalization and

78

full stops at the end.

79

80

- Major sections of code in a module should be separated by line feed

81

characters (e.g. ^L -- that's a single character control-L not two

82

characters). This helps with Emacs navigation.

85

before big blocks of constants which follow imports, and any place else that

86

would be convenient to jump to. Always put two blank lines before a ^L.

87

88

- Put to blank lines between any module level function. Put only one blank

89

line between methods in a class. No blank lines between the class

90

definition and the first method in the class (although class docstrings

91

often go in this space).

88

- Put two blank lines between any top level construct or block of code

89

(e.g. after import blocks). Put only one blank line between methods in a

90

class. No blank lines between the class definition and the first method in

91

the class. No blank lines between a class/method and its docstrings.

92

93

- Try to minimize the vertical whitespace in a class. If you're inclined to

94

separate stanzas of code for readability, consider putting a comment in

107

- an almost fanatical devotion to the pope

108

"""

109

110

- Write docstrings for all public modules, functions, classes, and methods.

111

Docstrings are not necessary and usually discouraged for non-public methods,

112

but you should have a comment that describes what the method does. This

113

comment should appear after the "def" line.

110

- Write docstrings for modules, functions, classes, and methods. Docstrings

111

can be omitted for special methods (e.g. __init__() or __str__()) where the

112

meaning is obvious.

114

113

115

114

- PEP 257 describes good docstrings conventions. Note that most importantly,

116

115

the """ that ends a multiline docstring should be on a line by itself, e.g.:

120

119

Optional plotz says to frobnicate the bizbaz first.

121

120

"""

122

121

123

- For one liner docstrings, keep the closing """ on the same line --

124

except for module docstrings!

122

- For one liner docstrings, keep the closing """ on the same line.

125

123

126

- <> is strongly preferred over !=

124

- <> is strongly preferred over != (Sadly, Python is making this harder to

125

follow and it cannot be followed for Python 3).

127

126

128

127

- fill-column for docstrings should be 78.

129

128

130

- Always use string methods instead of string module functions.

131

132

- For sequences, (strings, lists, tuples), use the fact that empty sequences

133

are false, so "if not seq" or "if seq" is preferable to "if len(seq)" or "if

134

not len(seq)". Always use True and False instead of 1 and 0 for boolean

135

values.

129

- When testing the emptiness of sequences, use "if len(seq) == 0" instead of

130

relying on the falseness of empty sequences. However, if a variable can be

131

one of several false values, it's okay to just use "if seq", though a

132

preceding comment is usually in order.

136

133

137

134

- Always decide whether a class's methods and instance variables should be

138

public or non-public. In general, never make data variables public unless

139

you're implementing essentially a record. It's almost always preferable to

140

give a functional interface to your class instead (Python 2.2's descriptors

141

and properties make this much nicer).

142

143

Also decide whether your attributes should be private or not. The

144

difference between private and non-public is that the former will never be

145

useful for a derived class, while the latter might be. Yes, you should

146

design your classes with inheritance in mind!

147

148

- Single leading underscores are generally preferred for non-public

135

public or non-public.

136

137

Single leading underscores are generally preferred for non-public

149

138

attributes. Use double leading underscores only in classes designed for

150

139

inheritance to ensure that truly private attributes will never name clash.

151

140

~sambuddhabasu1/mailman/fix_mailman_run_error