Mercurial > pylearn

annotate doc/v2_planning/API_coding_style.txt @ 1150:d7192e52653e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Moved some elements to official API
author Olivier Delalleau <delallea@iro>
date Thu, 16 Sep 2010 17:00:58 -0400
parents 2da593b0f29d
children 531e77fb67f2 a0f178bc9052
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>`_
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
29 * `PEP 257 -- Docstring Conventions
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
30 <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
31 * `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
32 <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
33 * `Google Python Style Guide
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
34 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
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.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
48 """This is a multi-line docstring.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
49
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
50 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
51 """
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 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
54 """This is a multi-line docstring.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
55
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
56 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
57
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
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
60 Excerpts
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
61 ~~~~~~~~
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 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
64 guidelines:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
65
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
66 * 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
67 lists:
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
68 - 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
69 the iteration),
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
70 - 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
71 - 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
72 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
73 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
74
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 | Iterative version | List version |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
77 +========================+========================+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
78 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
79 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
80 | my_dict.iterkeys | my_dict.keys |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
81 | my_dict.itervalues | my_dict.values |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
82 | my_dict.iteritems | my_dict.items |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
83 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
84 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
85 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
86 | itertools.ifilter | filter |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
87 | itertools.imap | map |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
88 | itertools.izip | zip |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
89 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
90 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
91 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
92 | xrange | range |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
93 +------------------------+------------------------+
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 Code example with ``map``:
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
96
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
97 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
98
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
99 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
100 for f_x in imap(f, x):
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
101 ...
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
102 all_f_x = map(f, x)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
103 map(f, x)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
104 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
105 for element in map(f, x):
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
106 ...
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
107 imap(f, x)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
108
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
109 * 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
110 easier to read.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
111
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
112 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
113
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
114 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
115 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
116 if not line.startswith('#')]
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
117 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
118 non_comments = map(str.strip,
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
119 ifilter(lambda line: not line.startswith('#'),
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
120 my_file.readlines()))
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
121
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
122 * 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
123 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
124 container types.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
125
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
126 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
127
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
128 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
129 has_key = key in my_dict
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
130 has_substring = substring in my_string
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
131 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
132 has_key = my_dict.has_key(key)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
133 has_substring = my_string.find(substring) >= 0
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
134
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
135
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
136 Additional Recommendations
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
137 --------------------------
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 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
140
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
141 * 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
142 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
143 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
144
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
145 .. code-block:: python
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
146
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
147 # Good.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
148 if (cond_1 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
149 cond_2 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
150 cond_3):
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
151 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
152 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
153 if cond_1 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
154 cond_2 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
155 cond_3:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
156 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
157
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
158 * 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
159 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
160 The position of the first
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
161 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
162 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
163
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
164 .. code-block:: python
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 # Good.
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
167 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
168 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
169 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
170 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
171 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
172 ...
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
173 # 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
174 # 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
175 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
176 my_foo,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
177 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
178 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
179 my_everything,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
180 ]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
181 ...
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
182 # 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
183 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
184 my_bar]:
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
185 ...
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
186 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
187 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
188 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
189 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
190 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
191 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
192 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
193 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
194 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
195
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
196
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
197 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
198 =================================================
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
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 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
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
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 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
204 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
205 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
206 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
207 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
208 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
209
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 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
211 `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
212
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 .. _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
214 .. _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
215
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 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
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
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 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
220 ``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
221 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
222 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
223 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
224 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
225 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
226
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 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
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
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 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
231 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
232 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
233 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
234 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
235
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 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
237 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
238 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
239 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
240 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
241 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
242 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
243
1148
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
244 Code Sample
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
245 ===========
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
246
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
247 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
248 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
249
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
250 .. 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
251
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
252 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
253