Mercurial > pylearn

annotate doc/v2_planning/API_coding_style.txt @ 1170:53340a8df1fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Started to write full code sample
author Olivier Delalleau <delallea@iro>
date Fri, 17 Sep 2010 14:37:00 -0400
parents 4f1b9e0a1377
children fe6c25eb1e37 10bc5ebb5823
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
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
5 Note: until the Pylearn documentation is properly compiled, you can view
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
6 the HTML version of this document `here
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
7 <http://www.iro.umontreal.ca/~delallea/tmp/coding_style/html/API_coding_style.html>`_.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
8
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
9 Main Goals
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
10 ==========
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 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
13 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
14 for Theano-dependent code.
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
15
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
16 * 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
17 users.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
18
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
19 * 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
20
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
21 Python Coding Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
22 ========================
1143
fa1715e759e3 Added API file for coding style committee (now we just need to fill it)
Olivier Delalleau <delallea@iro>
parents:
diff changeset
23
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
24 Official Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
25 -------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
26
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
27 Source Material
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
28 ~~~~~~~~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
29
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
30 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
31 * `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
32 <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
33 * `PEP 257 -- Docstring Conventions
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
34 <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
35 * `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
36 <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
37 * `Google Python Style Guide
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
38 <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
39
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
40
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
41 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
42 to do differently:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
43
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
44 * 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
45
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
46 * 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
47 a multi-line docstring.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
48
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
49 .. code-block:: python
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 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
52 """This is a multi-line docstring.
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 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
55 """
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 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
58 """This is a multi-line docstring.
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 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
61
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
62 """
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
63
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
64 * Standard library imports can (and should) be on the same line, to avoid
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
65 wasting space on straighforward imports:
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
66
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
67 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
68
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
69 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
70 import os, sys, time
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
71 # Good when it does not fit on a single line.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
72 import std_lib_module_1, std_lib_module_2, std_lib_module_3
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
73 import std_lib_module_4, std_lib_module_5, std_lib_module_6
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
74 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
75 import os
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
76 import sys
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
77 import time
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
78
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
79 * Importing class / functions from a module is allowed when these are
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
80 used multiple times, and no ambiguity is possible.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
81
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
82 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
83
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
84 # Good when Bar and Blah are used many times.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
85 from foo import Bar, Blah
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
86 do_something_with(Bar(), Blah(), Bar(), Blah(), Bar(), Blah())
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
87 # Good in most situations.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
88 import foo
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
89 do_something_with(foo.Bar(), foo.Blah())
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
90 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
91 from foo import *
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
92 from numpy import any # Potential ambiguity with __builtin__.any
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
93
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
94 Excerpts
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
95 ~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
96
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
97 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
98 guidelines:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
99
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
100 * Only use ASCII characters in code files.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
101
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
102 * Code indent must be done with four blank characters (no tabs).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
103
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
104 * Limit lines to 79 characters.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
105
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
106 * Naming conventions: ``ClassName``, ``TOP_LEVEL_CONSTANT``,
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
107 ``everything_else``.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
108
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
109 * Comments should start with a capital letter (unless the first word is a
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
110 code identifier) and end with a period (short inline comments may skip
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
111 the period at the end).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
112
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
113 * Imports should be listed in alphabetical order. It makes it easier to
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
114 verify that something is imported, and avoids duplicated imports.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
115
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
116 * Use absolute imports only. This is compatible across a wider range of
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
117 Python versions, and avoids confusion about what is being
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
118 imported.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
119
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
120 * Avoid renaming imported modules. This makes code more difficult to
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
121 re-use, and is not grep-friendly.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
122
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
123 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
124
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
125 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
126 from theano import tensor
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
127 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
128 from theano import tensor as T
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
129
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
130 * 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
131 lists:
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
132
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
133 - uses more memory (and possibly more CPU if the code may break out of
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
134 the iteration),
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
135 - can lead to ugly code when converted to Python 3 with 2to3,
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
136 - can have a different behavior if evaluating elements in the list has
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
137 side effects (if you want these side effects, make it explicit by
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
138 assigning the list to some variable before iterating on it).
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
139
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
140 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
141 | Iterative version | List version |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
142 +========================+========================+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
143 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
144 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
145 | my_dict.iterkeys | my_dict.keys |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
146 | my_dict.itervalues | my_dict.values |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
147 | my_dict.iteritems | my_dict.items |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
148 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
149 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
150 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
151 | itertools.ifilter | filter |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
152 | itertools.imap | map |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
153 | itertools.izip | zip |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
154 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
155 | .. code-block:: python | .. code-block:: python |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
156 | | |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
157 | xrange | range |
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
158 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
159
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
160 Code example with ``map``:
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
161
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
162 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
163
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
164 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
165 for f_x in imap(f, x):
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
166 ...
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
167 all_f_x = map(f, x)
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
168 map(f, x) # f has some side effect.
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
169 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
170 for element in map(f, x):
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
171 ...
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
172 imap(f, x)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
173
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
174 * 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
175 easier to read.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
176
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
177 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
178
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
179 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
180 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
181 if not line.startswith('#')]
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
182 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
183 non_comments = map(str.strip,
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
184 ifilter(lambda line: not line.startswith('#'),
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
185 my_file.readlines()))
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
186
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
187 * 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
188 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
189 container types.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
190
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
191 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
192
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
193 # Good.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
194 has_key = key in my_dict
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
195 has_substring = substring in my_string
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
196 # Bad.
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
197 has_key = my_dict.has_key(key)
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
198 has_substring = my_string.find(substring) >= 0
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
199
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
200 * Do not use mutable arguments as default values. Instead, use a helper
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
201 function (conditional expressions are forbidden at this point, see
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
202 below).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
203
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
204 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
205
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
206 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
207 def f(array=None):
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
208 array = pylearn.if_none(array, [])
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
209 ...
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
210 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
211 def f(array=[]): # Dangerous if `array` is modified down the road.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
212 ...
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
213
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
214 * Use a leading underscore '_' in names of internal attributes / methods,
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
215 but avoid the double underscore '__' unless you know what you are
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
216 doing.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
217
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
218
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
219 Additional Recommendations
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
220 --------------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
221
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
222 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
223
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
224 * All Python code files should start like this:
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
225
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
226 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
227
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
228 """Module docstring as the first line, as usual."""
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
229
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
230 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
231 __copyright__ = "(c) 2010, Universite de Montreal"
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
232 __license__ = "3-clause BSD License"
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
233 __contact__ = "Name Of Current Guardian of this file <email@address>"
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
234
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
235 * Use ``//`` for integer division and ``/ float(...)`` if you want the
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
236 floating point operation (for readability and compatibility across all
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
237 versions of Python).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
238
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
239 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
240
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
241 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
242 n_samples_per_split = n_samples // n_splits
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
243 mean_x = sum(x) / float(len(x))
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
244 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
245 n_samples_per_split = n_samples / n_splits
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
246 mean_x = sum(x) / len(x)
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
247
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
248 * Always raise an exception with ``raise MyException(args)`` where ``MyException``
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
249 inherits from ``Exception``. This is required for compatibility across
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
250 all versions of Python.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
251
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
252 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
253
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
254 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
255 raise NotImplementedError('The Pylearn team is too lazy.')
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
256 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
257 raise NotImplementedError, 'The Pylearn team is too lazy.'
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
258 raise 'The Pylearn team is too lazy to implement this.'
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
259
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
260 * Use either ``try ... except`` or ``try ... finally``, but do not mix
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
261 ``except`` with ``finally`` (which is not supported in Python 2.4).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
262 You can however embed one into the other to mimic the ``try ... except ...
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
263 finally`` behavior.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
264
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
265 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
266
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
267 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
268 try:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
269 try:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
270 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
271 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
272 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
273 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
274 always_do_this_regardless_of_what_happened()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
275 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
276 try:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
277 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
278 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
279 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
280 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
281 always_do_this_regardless_of_what_happened()
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
282
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
283 * No conditional expression (not supported in Python 2.4). These are
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
284 expressions of the form ``x = y if condition else z``.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
285
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
286 * Do not use the ``all`` and ``any`` builtin functions (they are not supported
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
287 in Python 2.4). Instead, import them from ``theano.gof.python25`` (or
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
288 use ``numpy.all`` / ``numpy.any`` for array data).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
289
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
290 * Do not use the ``hashlib`` module (not supported in Python 2.4). We will
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
291 probably provide a wrapper around it to be compatible with all Python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
292 versions.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
293
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
294 * Use ``numpy.inf`` and ``numpy.nan`` rather than
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
295 ``float('inf')`` / ``float('nan')`` (should be slightly more efficient even
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
296 if efficiency is typically not an issue here, the main goal being code
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
297 consistency). Also, always use ``numpy.isinf`` / ``numpy.isnan`` to
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
298 test infinite / NaN values. This is important because ``numpy.nan !=
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
299 float('nan')``.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
300
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
301 * 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
302 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
303 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
304
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
305 .. code-block:: python
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
306
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
307 # Good.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
308 if (cond_1 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
309 cond_2 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
310 cond_3):
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
311 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
312 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
313 if cond_1 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
314 cond_2 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
315 cond_3:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
316 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
317
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
318 * 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
319 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
320 The position of the first
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
321 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
322 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
323
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
324 .. code-block:: python
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
325
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
326 # Good.
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
327 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
328 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
329 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
330 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
331 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
332 ...
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
333 # 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
334 # 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
335 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
336 my_foo,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
337 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
338 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
339 my_everything,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
340 ]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
341 ...
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
342 # 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
343 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
344 my_bar]:
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
345 ...
1145
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
346 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
347 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
348 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
349 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
350 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
351 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
352 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
353 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
354 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines
Olivier Delalleau <delallea@iro>
parents: 1143
diff changeset
355
1159
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
356 * Use the ``key`` argument instead of ``cmp`` when sorting (for Python 3
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
357 compatibility).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
358
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
359 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
360
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
361 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
362 my_list.sort(key=abs)
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
363 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
364 my_list.sort(cmp=lambda x, y: cmp(abs(x), abs(y)))
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
365
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
366 * Whenever you read / write binary files, specify it in the mode ('rb' for
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
367 reading, 'wb' for writing). This is important for cross-platform and
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
368 Python 3 compatibility (e.g. when pickling / unpickling objects).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
369
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
370 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
371
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
372 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
373 cPickle.dump(obj, open('my_obj.pkl', 'wb', protocol=-1))
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
374 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
375 cPickle.dump(obj, open('my_obj.pkl', 'w', protocol=-1))
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
376
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
377 * Avoid tuple parameter unpacking as it can lead to very ugly code when
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
378 converting to Python 3.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
379
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
380 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
381
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
382 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
383 def f(x, y_z):
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
384 y, z = y_z
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
385 ...
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
386 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
387 def f(x, (y, z)):
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
388 ...
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
389
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
390 * Only use ``cPickle``, not ``pickle`` (except for debugging purpose since
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
391 error messages from ``pickle`` are sometimes easier to understand).
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
392
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
393 * A script's only top-level code should be something like:
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
394
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
395 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
396
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
397 if __name__ == '__main__':
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
398 sys.exit(main())
531e77fb67f2 coding_style: Moved more elements to official 'API'
Olivier Delalleau <delallea@iro>
parents: 1150
diff changeset
399
1150
d7192e52653e coding_style: Moved some elements to official API
Olivier Delalleau <delallea@iro>
parents: 1148
diff changeset
400
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
401 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
402 =================================================
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
403
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
404 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
405 ----------------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
406
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
407 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
408 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
409 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
410 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
411 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
412 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
413
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
414 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
415 `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
416
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
417 .. _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
418 .. _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
419
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
420 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
421 ----------------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
422
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
423 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
424 ``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
425 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
426 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
427 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
428 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
429 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
430
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
431 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
432 ------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
433
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
434 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
435 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
436 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
437 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
438 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
439
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
Olivier Delalleau <delallea@iro>
parents: 1145
diff changeset
440 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
441 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
442 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
443 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
444 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
445 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
446 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
447
1148
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
448 Code Sample
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
449 ===========
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
450
1170
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
451 The following code sample illustrates some of the coding guidelines one should
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
452 follow in Pylearn. This is still a work-in-progress.
1148
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
453
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
454 .. 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
455
1170
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
456 #! /usr/env/bin python
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
457
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
458 """Sample code. There may still be mistakes / missing elements."""
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
459
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
460 __authors__ = "Olivier Delalleau"
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
461 __copyright__ = "(c) 2010, Universite de Montreal"
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
462 __license__ = "3-clause BSD License"
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
463 __contact__ = "Olivier Delalleau <delallea@iro>"
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
464
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
465 # Standard library imports are on a single line.
1148
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability
Olivier Delalleau <delallea@iro>
parents: 1147
diff changeset
466 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
467
1170
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
468 # Third-party imports come after standard library imports, and there is
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
469 # only one import per line. Imports are sorted lexicographically.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
470 import numpy
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
471 import scipy
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
472 import theano
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
473 # Put 'from' imports below.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
474 from numpy import argmax
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
475 from theano import tensor
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
476
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
477 # Application-specific imports come last.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
478 from pylearn import dataset
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
479 from pylearn.optimization import minimize
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
480
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
481 def print_files_in(directory):
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
482 """Print the first line of each file in given directory."""
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
483 # TODO To be continued...
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
484
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
485 def main():
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
486 if len(sys.argv) != 2:
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
487 # Note: conventions on how to display script documentation and
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
488 # parse arguments are still to-be-determined.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
489 print("""\
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
490 Usage: %s <directory>
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
491 Print first line of each file in given directory (in alphabetic order)."""
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
492 % os.path.basename(sys.argv[0]))
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
493 return 1
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
494 print_files_in(sys.argv[1])
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
495 return 0
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
496
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
497 # Top-level executable code should be minimal.
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
498 if __name__ == '__main__':
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
499 sys.exit(main())
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
500
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
501
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
502 Automatic Code Verification
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
503 ===========================
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
504
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
505 Tools will be available to make it easier to automatically ensure that code
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
506 committed to Pylearn complies to above specifications. This work is not
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
507 finalized yet, but David started a `Wiki page`_ with helpful configuration
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
508 tips for Vim.
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
509
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
510 .. _Wiki page: http://www.iro.umontreal.ca/~lisa/twiki/bin/view.cgi/Divers/VimPythonRecommendations
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
511
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
512 TODO
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
513 ====
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
514
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
515 Things still missing from this document, being discussed in coding_style.txt:
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
516 - Proper style for C code and Mercurial commits
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
517 - Enforcing 100% test coverage of the code base
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
518 - Providing ways to add type checking for function arguments
1170
53340a8df1fa coding_style: Started to write full code sample
Olivier Delalleau <delallea@iro>
parents: 1162
diff changeset
519 - Conventions for script usage documentation and argument parsing
1162
4f1b9e0a1377 coding_style: Moved more stuff to API
Olivier Delalleau <delallea@iro>
parents: 1159
diff changeset
520