|
Size: 3290
Comment: Ask about adding doctest docstring examples to this.
|
← Revision 11 as of 2024-08-21 23:33:21 ⇥
Size: 2674
Comment: Reworking article, removing discussion
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| * [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 |
* [[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 |
| Line 5: | Line 5: |
| [[TableOfContents()]] | <<TableOfContents>> |
| Line 9: | Line 9: |
| If you're anything like me, you probably can't just read PEP 8 & 257, and start writing perfect Python style. | There are a lot of rules in PEP 8 and 257! Learn and document in steps. |
| Line 11: | Line 11: |
| 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. |
The key is to use formatters and validators to ensure PEP 8 compliance. As your code is put through validators, you slowly learn all the intricate details of styling. |
| Line 16: | Line 14: |
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)]] |
|
| Line 24: | Line 15: |
This is my understanding of how a Python module by PEP-8 might look: |
|
| Line 49: | Line 38: |
| Line 59: | Line 47: |
| EatEggs -- does X EatSpam -- does Y |
eat_eggs -- does X eat_spam -- does Y |
| Line 69: | Line 57: |
| def EatEggs(self): | def eat_eggs(self): |
| Line 74: | Line 62: |
| def EatSpam(self): | def eat_spam(self): |
| Line 82: | Line 70: |
def _internal_use(self): # Eat eggs and spam. # # Docstrings are not necessary for non-public methods, but you # should have a comment that describes what the method does. # This comment should appear after the "def" line. self.eat_eggs() self.eat_spam() |
|
| Line 105: | Line 103: |
| Line 107: | Line 104: |
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)]] I know these PEPs make no mention of ''doctest'' code in docstrings. However, some of them might be nice in this example. |
Python style conventions are described in PEPs.
Contents
Learning Python Style
There are a lot of rules in PEP 8 and 257! Learn and document in steps.
The key is to use formatters and validators to ensure PEP 8 compliance. As your code is put through validators, you slowly learn all the intricate details of styling.
Examples
Example Module
Toggle line numbers
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 """What it is.
22
23 Notes on what it is and how it does it.
24
25 Lots to say, lots to say. I'm unclear on whether we need two spaces
26 between sentences or not. 72 characters wide. Blah blah blah.
27
28 Document methods in here, with a short explanation.
29
30 eat_eggs -- does X
31 eat_spam -- does Y
32 """
33
34 def __init__(self, green_eggs, green_spam):
35 """Init ClassNameA with some eggs and spam."""
36 foo()
37 bar()
38 baz()
39
40 def eat_eggs(self):
41 """One line documentation is like this."""
42 foo()
43 bar()
44
45 def eat_spam(self):
46 """Short explanation.
47
48 Multi-line spam has a one line description at top, seperated by
49 a space, and then more multi-line spam afterwards. Note that
50 the final triple-quote appears beneath.
51 """
52 baz()
53
54 def _internal_use(self):
55 # Eat eggs and spam.
56 #
57 # Docstrings are not necessary for non-public methods, but you
58 # should have a comment that describes what the method does.
59 # This comment should appear after the "def" line.
60
61 self.eat_eggs()
62 self.eat_spam()
63
64
65 def function_a(eggs, ham):
66 """A function_a is a foobar.
67
68 Again, multi-line rules apply in here as well, the same way. Note
69 that we have two spaces between module-level class and function
70 definitions. That's PEP-8 at work.
71 """
72 foo()
73 bar()
74 baz()
75
76
77 def function_b(eggs, ham):
78 """A function_b is a foobar.
79
80 Another one. Still two spaces separating functions and classes.
81 """
82 foo()
83 bar()
84 baz()