|
Size: 1014
Comment: really wish there were more examples,...
|
← 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 1: | Line 1: |
| 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 |
|
| Line 2: | Line 5: |
| 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 |
<<TableOfContents>> |
| Line 8: | 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 10: | 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.'' | 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 12: | Line 13: |
| It is probably unrealistic to believe that you can get the whole thing at once. | == Examples == === Example Module === |
| Line 14: | Line 16: |
| = Discussion = | {{{ #!python """Short description of module. |
| Line 16: | Line 20: |
| I wish there were good examples of well-styled Python code! (Most Python modules do ''not'' follow Python style guidelines!) | Blah blah blah. This is the long description of the module. More brief explanations. |
| Line 18: | Line 23: |
| 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. | ClassNameA -- short description function_a -- short description function_b -- short description """ |
| Line 20: | Line 28: |
| -- LionKimbro [[DateTime(2005-02-19T08:10:35Z)]] | 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. eat_eggs -- does X eat_spam -- does Y """ def __init__(self, green_eggs, green_spam): """Init ClassNameA with some eggs and spam.""" foo() bar() baz() def eat_eggs(self): """One line documentation is like this.""" foo() bar() def eat_spam(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 _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() 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() }}} |
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()