Mercurial > pylearn
annotate doc/v2_planning/API_coding_style.txt @ 1173:a0f178bc9052
changes during the meeting
author | pascanur |
---|---|
date | Fri, 17 Sep 2010 16:12:33 -0400 |
parents | d7192e52653e |
children | fe6c25eb1e37 |
rev | line source |
---|---|
1143
fa1715e759e3
Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff
changeset
|
1 ========================= |
fa1715e759e3
Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff
changeset
|
2 Coding Style Guidelines |
fa1715e759e3
Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff
changeset
|
3 ========================= |
fa1715e759e3
Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff
changeset
|
4 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
5 Main Goals |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
6 ========== |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
7 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
8 * Code should be compatible with Python 2.4 and above (using 2to3 for |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
9 conversion to Python 3.x). This may not be possible in the short term |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
10 for Theano-dependent code. |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
11 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
12 * Code should be easy to read, understand and update by developers and |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
13 users. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
14 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
15 * Code should be well-documented and well-tested. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
16 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
17 Python Coding Guidelines |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
18 ======================== |
1143
fa1715e759e3
Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff
changeset
|
19 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
20 Official Guidelines |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
21 ------------------- |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
22 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
23 Source Material |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
24 ~~~~~~~~~~~~~~~ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
25 |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
26 The four main documents describing our Python coding guidelines are: |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
27 * `PEP 8 -- Style Guide for Python Code |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
28 <http://www.python.org/dev/peps/pep-0008>`_ |
1173 | 29 * `Google Python Style Guide |
30 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_ | |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
31 * `PEP 257 -- Docstring Conventions |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
32 <http://www.python.org/dev/peps/pep-0257>`_ |
1147
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
33 * `Numpy Docstring Standard |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
34 <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard>`_ |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
35 |
1147
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
36 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
37 However, there are a few points mentioned in those documents that we decided |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
38 to do differently: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
39 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
40 * Use only one space (not two) after a sentence-ending period in comments. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
41 |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
42 * You do not need to add an extra blank line before the closing quotes of |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
43 a multi-line docstring. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
44 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
45 .. code-block:: python |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
46 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
47 # Good. |
1173 | 48 """ |
49 This is a multi-line docstring. | |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
50 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
51 Which means it has more than one line. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
52 """ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
53 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
54 # Bad. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
55 """This is a multi-line docstring. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
56 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
57 Which means it has more than one line. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
58 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
59 """ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
60 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
61 Excerpts |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
62 ~~~~~~~~ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
63 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
64 We emphasize here a few important topics that are found in the official |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
65 guidelines: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
66 |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
67 * Avoid using lists if all you care about is iterating on something. Using |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
68 lists: |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
69 - uses more memory (and possibly more CPU if the code may break out of |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
70 the iteration), |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
71 - can lead to ugly code when converted to Python 3 with 2to3, |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
72 - can have a different behavior if evaluating elements in the list has |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
73 side effects (if you want these side effects, make it explicit by |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
74 assigning the list to some variable before iterating on it). |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
75 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
76 +------------------------+------------------------+ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
77 | Iterative version | List version | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
78 +========================+========================+ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
79 | .. code-block:: python | .. code-block:: python | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
80 | | | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
81 | my_dict.iterkeys | my_dict.keys | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
82 | my_dict.itervalues | my_dict.values | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
83 | my_dict.iteritems | my_dict.items | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
84 +------------------------+------------------------+ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
85 | .. code-block:: python | .. code-block:: python | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
86 | | | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
87 | itertools.ifilter | filter | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
88 | itertools.imap | map | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
89 | itertools.izip | zip | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
90 +------------------------+------------------------+ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
91 | .. code-block:: python | .. code-block:: python | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
92 | | | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
93 | xrange | range | |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
94 +------------------------+------------------------+ |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
95 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
96 Code example with ``map``: |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
97 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
98 .. code-block:: python |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
99 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
100 # Good. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
101 for f_x in imap(f, x): |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
102 ... |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
103 all_f_x = map(f, x) |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
104 map(f, x) |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
105 # Bad. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
106 for element in map(f, x): |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
107 ... |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
108 imap(f, x) |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
109 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
110 * Generally prefer list comprehensions to ``map`` / ``filter``, as the former are |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
111 easier to read. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
112 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
113 .. code-block:: python |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
114 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
115 # Good. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
116 non_comments = [line.strip() for line in my_file.readlines() |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
117 if not line.startswith('#')] |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
118 # Bad. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
119 non_comments = map(str.strip, |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
120 ifilter(lambda line: not line.startswith('#'), |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
121 my_file.readlines())) |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
122 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
123 * Use ``in`` on container objects instead of using class-specific methods: |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
124 it is easier to read and may allow you to re-use your code with different |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
125 container types. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
126 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
127 .. code-block:: python |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
128 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
129 # Good. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
130 has_key = key in my_dict |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
131 has_substring = substring in my_string |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
132 # Bad. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
133 has_key = my_dict.has_key(key) |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
134 has_substring = my_string.find(substring) >= 0 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
135 |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
136 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
137 Additional Recommendations |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
138 -------------------------- |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
139 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
140 Things you should do even if they are not listed in official guidelines: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
141 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
142 * Avoid backslashes whenever possible. They make it more |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
143 difficult to edit code, and they are ugly (as well as potentially |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
144 dangerous if there are trailing white spaces). |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
145 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
146 .. code-block:: python |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
147 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
148 # Good. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
149 if (cond_1 and |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
150 cond_2 and |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
151 cond_3): |
1173 | 152 |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
153 ... |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
154 # Bad. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
155 if cond_1 and \ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
156 cond_2 and \ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
157 cond_3: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
158 ... |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
159 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
160 * When indenting multi-line statements like lists or function arguments, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
161 keep elements of the same level aligned with each other. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
162 The position of the first |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
163 element (on the same line or a new line) should be chosen depending on |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
164 what is easiest to read (sometimes both can be ok). |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
165 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
166 .. code-block:: python |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
167 |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
168 # Good. |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
169 for my_very_long_variable_name in [my_foo, my_bar, my_love, |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
170 my_everything]: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
171 ... |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
172 for my_very_long_variable_name in [ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
173 my_foo, my_bar, my_love, my_everything]: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
174 ... |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
175 # Good iff the list needs to be frequently updated or is easier to |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
176 # understand when each element is on its own line. |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
177 for my_very_long_variable_name in [ |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
178 my_foo, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
179 my_bar, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
180 my_love, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
181 my_everything, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
182 ]: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
183 ... |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
184 # Good as long as it does not require more than two lines. |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
185 for my_very_long_variable_name in [my_foo, |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
186 my_bar]: |
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
187 ... |
1145
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
188 # Bad. |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
189 for my_very_long_variable_name in [my_foo, my_bar, my_love, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
190 my_everything]: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
191 ... |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
192 for my_very_long_variable_name in [my_foo, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
193 my_bar, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
194 my_love, |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
195 my_everything]: |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
196 ... |
d6d73a9f07b8
API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents:
1143
diff
changeset
|
197 |
1150
d7192e52653e
coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents:
1148
diff
changeset
|
198 |
1147
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
199 The ``logging`` Module vs. the ``warning`` Module |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
200 ================================================= |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
201 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
202 The ``logging`` Module |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
203 ---------------------- |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
204 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
205 A central logging facility for Python capable of logging messages of various |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
206 categories/urgency and choosing with some granularity which messages are |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
207 displayed/suppressed, as well as where they are displayed or written. This |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
208 includes an ``INFO`` level for innocuous status information, a ``WARNING`` level |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
209 for unexpected state that is still recoverable, ``DEBUG`` for detailed |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
210 information which is only really of interest when things are going wrong, etc. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
211 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
212 In addition to the `library documentation`_, see this helpful tutorial, |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
213 `Python Logging 101`_. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
214 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
215 .. _library documentation: http://docs.python.org/library/logging.html |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
216 .. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
217 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
218 The ``warning`` Module |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
219 ---------------------- |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
220 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
221 The ``warning`` module in the standard library and its main interface, the |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
222 ``warn()`` function, allows the programmer to issue warnings in situations where |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
223 they wish to alert the user to some condition, but the situation is not |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
224 urgent enough to throw an exception. By default, a warning issued at a given |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
225 line of the code will only be displayed the first time that line is executed. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
226 By default, warnings are written to ``sys.stderr`` but the ``warning`` module |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
227 contains flexible facilities for altering the defaults, redirecting, etc. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
228 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
229 Which? When? |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
230 ------------ |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
231 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
232 It is our feeling that the ``logging`` module's ``WARNING`` level be used to log |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
233 warnings more meant for *internal*, *developer* consumption, to log situations |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
234 where something unexpected happened that may be indicative of a problem but |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
235 is several layers of abstraction below what a user of the library would |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
236 care about. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
237 |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
238 By contrast, the warning module should be used for warnings intended for user |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
239 consumption, e.g. alerting them that their version of Pylearn is older than |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
240 this plugin requires, so things may not work as expected, or that a given |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
241 function/class/method is slated for deprecation in a coming release (early |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
242 in the library's lifetime, ``DeprecationWarning`` will likely be the most common |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
243 case). The warning message issued through this facility should avoid |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
244 referring to Pylearn internals. |
f6011a2aff0b
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents:
1145
diff
changeset
|
245 |
1148
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
246 Code Sample |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
247 =========== |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
248 |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
249 The following code sample illustrates many of the coding guidelines one should |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
250 follow in Pylearn. |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
251 |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
252 .. code-block:: python |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
253 |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
254 import os, sys, time |
2da593b0f29d
API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents:
1147
diff
changeset
|
255 |