|
⇤ ← Revision 1 as of 2005-02-19 08:10:41
Size: 1014
Comment: really wish there were more examples,...
|
Size: 3161
Comment: example of pep-8 module formatting
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| Line 5: | Line 4: |
[[TableOfContents()]] |
|
| Line 14: | Line 15: |
| = Discussion = | == Examples == |
| Line 21: | Line 22: |
=== Example Module === This is my understanding of how a Python module by PEP-8 might look: {{{ #!python """Short description of module. Blah blah blah. This is the long description of the module. More brief explanations. ClassNameA -- short description function_a -- short description function_b -- short description """ import sys # standard library imports import os import optparse # related major package imports import eggs # application specific imports import spam class ClassNameA: """What it is. Notes on what it is and how it does it. Lots to say, lots to say. I'm unclear on whether we need two spaces between sentences or not. 72 characters wide. Blah blah blah. Document methods in here, with a short explanation. EatEggs -- does X EatSpam -- does Y """ def __init__(self, green_eggs, green_spam): """Init ClassNameA with some eggs and spam.""" foo() bar() baz() def EatEggs(self): """One line documentation is like this.""" foo() bar() def EatSpam(self): """Short explanation. Multi-line spam has a one line description at top, seperated by a space, and then more multi-line spam afterwards. Note that the final triple-quote appears beneath. """ baz() def function_a(eggs, ham): """A function_a is a foobar. Again, multi-line rules apply in here as well, the same way. Note that we have two spaces between module-level class and function definitions. That's PEP-8 at work. """ foo() bar() baz() def function_b(eggs, ham): """A function_b is a foobar. Another one. Still two spaces separating functions and classes. """ foo() bar() baz() }}} This may be incorrect; please correct it if you know better. In particular, I'm not sure if there are zero, one, or two spaces between the module docstring, and the import lines. -- LionKimbro [[DateTime(2005-02-21T04:44:51Z)]] |
Python style conventions are described in PEPs.
[http://www.python.org/peps/pep-0008.html PEP 8] -- Style Guide for Python Code
[http://www.python.org/peps/pep-0257.html PEP 257] -- Docstring Conventions
Learning Python Style
If you're anything like me, you probably can't just read PEP 8 & 257, and start writing perfect Python style.
I've had a lot of success learning (and applying) the document in steps. Start with your line width, spacings. Then work on imports, white space, ... Continue learning and applying the style in steps.
It is probably unrealistic to believe that you can get the whole thing at once.
Examples
I wish there were good examples of well-styled Python code! (Most Python modules do not follow Python style guidelines!)
I intend to write some examples here, and comment on the features of the formatting. Hopefully, people who understand the format better will correct the examples.
-- LionKimbro DateTime(2005-02-19T08:10:35Z)
Example Module
This is my understanding of how a Python module by PEP-8 might look:
1 """Short description of module.
2
3 Blah blah blah. This is the long description of the module. More brief
4 explanations.
5
6 ClassNameA -- short description
7 function_a -- short description
8 function_b -- short description
9 """
10
11 import sys # standard library imports
12 import os
13
14 import optparse # related major package imports
15
16 import eggs # application specific imports
17 import spam
18
19
20 class ClassNameA:
21
22 """What it is.
23
24 Notes on what it is and how it does it.
25
26 Lots to say, lots to say. I'm unclear on whether we need two spaces
27 between sentences or not. 72 characters wide. Blah blah blah.
28
29 Document methods in here, with a short explanation.
30
31 EatEggs -- does X
32 EatSpam -- does Y
33 """
34
35 def __init__(self, green_eggs, green_spam):
36 """Init ClassNameA with some eggs and spam."""
37 foo()
38 bar()
39 baz()
40
41 def EatEggs(self):
42 """One line documentation is like this."""
43 foo()
44 bar()
45
46 def EatSpam(self):
47 """Short explanation.
48
49 Multi-line spam has a one line description at top, seperated by
50 a space, and then more multi-line spam afterwards. Note that
51 the final triple-quote appears beneath.
52 """
53 baz()
54
55
56 def function_a(eggs, ham):
57 """A function_a is a foobar.
58
59 Again, multi-line rules apply in here as well, the same way. Note
60 that we have two spaces between module-level class and function
61 definitions. That's PEP-8 at work.
62 """
63 foo()
64 bar()
65 baz()
66
67
68 def function_b(eggs, ham):
69 """A function_b is a foobar.
70
71 Another one. Still two spaces separating functions and classes.
72 """
73 foo()
74 bar()
75 baz()
This may be incorrect; please correct it if you know better.
In particular, I'm not sure if there are zero, one, or two spaces between the module docstring, and the import lines.