pylearn: doc/v2_planning/API_coding

annotate doc/v2_planning/API_coding_style.txt @ 1377:0665274b14af

Minor fixes for better Sphinx doc output

author	Olivier Delalleau <delallea@iro>
date	Thu, 18 Nov 2010 14:14:48 -0500
parents	7b61bfda1dab
children	3d4615ee96a4

rev	line source
1143 fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	1 =========================
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	2 Coding Style Guidelines
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	3 =========================
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	4
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	5 Main Goals
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	6 ==========
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	7
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	8 * Code should be compatible with Python 2.4 and above (using 2to3 for
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	9 conversion to Python 3.x). This may not be possible in the short term
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	10 for Theano-dependent code.
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	11
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	12 * Code should be easy to read, understand and update by developers and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	13 users.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	14
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	15 * Code should be well-documented and well-tested.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	16
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	17 Python Coding Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	18 ========================
1143 fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	19
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	20 Official Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	21 -------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	22
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	23 Source Material
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	24 ~~~~~~~~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	25
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	26 The four main documents describing our Python coding guidelines are:
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	27 * `PEP 8 -- Style Guide for Python Code
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	28 <http://www.python.org/dev/peps/pep-0008>`_
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	29 * `Google Python Style Guide
a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	30 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	31 * `PEP 257 -- Docstring Conventions
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	32 <http://www.python.org/dev/peps/pep-0257>`_
1147 f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	33 * `Numpy Docstring Standard
1373 90116fb3636b fix and URL that was moved. Frederic Bastien <nouiz@nouiz.org> parents: 1325 diff changeset	34 <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	35
1147 f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	36
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	37 However, there are a few points mentioned in those documents that we decided
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	38 to do differently:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	39
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	40 * Use only one space (not two) after a sentence-ending period in comments.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	41
1183 bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	42 .. code-block:: python
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	43
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	44 # Good.
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	45 # This is the first sentence. It is followed by a single blank space.
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	46 # Bad.
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	47 # This is the first sentence. It is followed by two blank spaces.
bc1b445e22fa API_coding_style: Added code example to explain the point about the number of spaces after a period Olivier Delalleau <delallea@iro> parents: 1180 diff changeset	48
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	49 * You do not need to add an extra blank line before the closing quotes of
1180 9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	50 a multi-line docstring. Also, we ask that the first line of a multi-line
9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	51 docstring should contain only the opening quotes.
1150 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 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	54
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	55 # Good.
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	56 """
a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	57 This is a multi-line docstring.
1150 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 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	60 """
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 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	63 """This is a multi-line docstring.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	64
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	65 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	66
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	67 """
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	68
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	69 * 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	70 wasting space on straighforward imports:
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	71
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	72 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	73
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	74 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	75 import os, sys, time
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	76 # 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	77 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	78 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	79 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	80 import os
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	81 import sys
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	82 import time
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 * 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	85 used multiple times, and no ambiguity is possible.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	86
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	87 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	88
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	89 # 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	90 from foo import Bar, Blah
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	91 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	92 # Good in most situations.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	93 import foo
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	94 do_something_with(foo.Bar(), foo.Blah())
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	95 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	96 from foo import *
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	97 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	98
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	99 Excerpts
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	100 ~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	101
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	102 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	103 guidelines:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	104
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	105 * Only use ASCII characters in code files.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	106
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	107 * 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	108
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	109 * Limit lines to 79 characters.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	110
1236 23f63ecf0a9a API_coding_style: Added no trailing spaces requirement Olivier Delalleau <delallea@iro> parents: 1232 diff changeset	111 * No trailing spaces.
23f63ecf0a9a API_coding_style: Added no trailing spaces requirement Olivier Delalleau <delallea@iro> parents: 1232 diff changeset	112
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	113 * Naming conventions: ``ClassName``, ``TOP_LEVEL_CONSTANT``,
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	114 ``everything_else``.
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 * 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	117 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	118 the period at the end).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	119
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	120 * 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	121 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	122
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	123 * 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	124 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	125 imported.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	126
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	127 * 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	128 re-use, and is not grep-friendly.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	129
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	130 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	131
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	132 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	133 from theano import tensor
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	134 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	135 from theano import tensor as T
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	136
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	137 * 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	138 lists:
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	139
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	140 - 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	141 the iteration),
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	142 - 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	143 - 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	144 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	145 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	146
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	147 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	148 \| Iterative version \| List version \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	149 +========================+========================+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	150 \| .. code-block:: python \| .. code-block:: python \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	151 \| \| \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	152 \| my_dict.iterkeys \| my_dict.keys \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	153 \| my_dict.itervalues \| my_dict.values \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	154 \| my_dict.iteritems \| my_dict.items \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	155 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	156 \| .. code-block:: python \| .. code-block:: python \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	157 \| \| \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	158 \| itertools.ifilter \| filter \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	159 \| itertools.imap \| map \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	160 \| itertools.izip \| zip \|
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 \| .. 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 \| xrange \| range \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	165 +------------------------+------------------------+
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 Code example with ``map``:
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	168
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	169 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	170
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	171 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	172 for f_x in 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 all_f_x = map(f, x)
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	175 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	176 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	177 for element in map(f, x):
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 imap(f, x)
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	180
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	181 * 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	182 easier to read.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	183
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	184 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	185
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	186 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	187 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	188 if not line.startswith('#')]
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	189 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	190 non_comments = map(str.strip,
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	191 ifilter(lambda line: not line.startswith('#'),
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	192 my_file.readlines()))
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	193
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	194 * 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	195 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	196 container types.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	197
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	198 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	199
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	200 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	201 has_key = key in my_dict
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	202 has_substring = substring in my_string
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	203 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	204 has_key = my_dict.has_key(key)
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	205 has_substring = my_string.find(substring) >= 0
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	206
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	207 * 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	208 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	209 below).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	210
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	211 .. code-block:: python
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 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	214 def f(array=None):
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	215 array = pylearn.if_none(array, [])
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	216 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	217 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	218 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	219 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	220
1254 705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	221 * All top-level classes should inherit from ``object``. It makes some
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	222 'under-the-hood' differences that can be very useful for Python black
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	223 magic adepts.
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	224
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	225 .. code-block:: python
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	226
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	227 # Good.
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	228 class MyClass(object):
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	229 pass
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	230 # Bad.
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	231 class MyClass:
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	232 pass
705795076efd API_coding_style: Added recommendation about how classes should derive from object Olivier Delalleau <delallea@iro> parents: 1236 diff changeset	233
1184 5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	234 * Always raise an exception with ``raise MyException(args)`` where ``MyException``
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	235 inherits from ``Exception``. This is required for compatibility across
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	236 all versions of Python.
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	237
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	238 .. code-block:: python
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	239
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	240 # Good.
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	241 raise NotImplementedError('The Pylearn team is too lazy.')
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	242 # Bad.
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	243 raise NotImplementedError, 'The Pylearn team is too lazy.'
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	244 raise 'The Pylearn team is too lazy to implement this.'
5783948b3f8c API_coding_style: Moved the point about how to raise exception since it is found in official documents Olivier Delalleau <delallea@iro> parents: 1183 diff changeset	245
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	246 * 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	247 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	248 doing.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	249
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	250
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	251 Additional Recommendations
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	252 --------------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	253
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	254 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	255
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	256 * All Python code files should start like this:
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	257
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	258 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	259
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	260 """Module docstring as the first line, as usual."""
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	261
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	262 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	263 __copyright__ = "(c) 2010, Universite de Montreal"
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	264 __license__ = "3-clause BSD License"
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	265 __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	266
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	267 * 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	268 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	269 versions of Python).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	270
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	271 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	272
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	273 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	274 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	275 mean_x = sum(x) / float(len(x))
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	276 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	277 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	278 mean_x = sum(x) / len(x)
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	279
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	280 * 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	281 ``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	282 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	283 finally`` behavior.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	284
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	285 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	286
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	287 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	288 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	289 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	290 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	291 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	292 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	293 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	294 always_do_this_regardless_of_what_happened()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	295 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	296 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	297 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	298 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	299 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	300 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	301 always_do_this_regardless_of_what_happened()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	302
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	303 * 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	304 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	305
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	306 * 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	307 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	308 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	309
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	310 * 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	311 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	312 versions.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	313
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	314 * Use ``numpy.inf`` and ``numpy.nan`` rather than
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	315 ``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	316 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	317 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	318 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	319 float('nan')``.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	320
1305 b60a9b6eee68 API_coding_style: Added point mentioned during meeting Olivier Delalleau <delallea@iro> parents: 1303 diff changeset	321 * Whenever possible, mimic the numpy / scipy interfaces when writing code
b60a9b6eee68 API_coding_style: Added point mentioned during meeting Olivier Delalleau <delallea@iro> parents: 1303 diff changeset	322 similar to what can be found in these packages.
b60a9b6eee68 API_coding_style: Added point mentioned during meeting Olivier Delalleau <delallea@iro> parents: 1303 diff changeset	323
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	324 * 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	325 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	326 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	327
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	328 .. code-block:: python
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 # Good.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	331 if (cond_1 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	332 cond_2 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	333 cond_3):
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	334
1180 9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	335 # Note that we added a blank line above to avoid confusion between
9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	336 # conditions and the rest of the code (this would not have been
9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	337 # needed if they were at significantly different indentation levels).
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	338 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	339 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	340 if cond_1 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	341 cond_2 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	342 cond_3:
1180 9ebd40d31a1b API_coding_style: Added some comments following up on what was discussed during meeting Olivier Delalleau <delallea@iro> parents: 1179 diff changeset	343
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	344 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	345
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	346 * 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	347 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	348 The position of the first
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	349 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	350 what is easiest to read (sometimes both can be ok).
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	351 Other formattings may be ok depending on the specific situation, use
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	352 common sense and pick whichever looks best.
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	353
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	354 .. code-block:: python
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	355
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	356 # Good.
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	357 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	358 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	359 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	360 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	361 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	362 ...
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	363 # 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	364 # 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	365 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	366 my_foo,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	367 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	368 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	369 my_everything,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	370 ]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	371 ...
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	372 # 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	373 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	374 my_bar]:
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	375 ...
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	376 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	377 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	378 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	379 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	380 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	381 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	382 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	383 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	384 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	385
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	386 * 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	387 compatibility).
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 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	390
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	391 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	392 my_list.sort(key=abs)
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	393 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	394 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	395
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	396 * 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	397 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	398 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	399
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	400 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	401
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	402 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	403 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	404 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	405 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	406
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	407 * 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	408 converting to Python 3.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	409
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	410 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	411
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	412 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	413 def f(x, y_z):
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	414 y, z = y_z
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	415 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	416 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	417 def f(x, (y, z)):
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	418 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	419
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	420 * 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	421 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	422
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	423 * 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	424
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	425 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	426
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	427 if __name__ == '__main__':
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	428 sys.exit(main())
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	429
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	430
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	431 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	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 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	435 ----------------------
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
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 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	438 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	439 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	440 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	441 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	442 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	443
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 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	445 `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	446
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 .. _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	448 .. _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	449
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	450 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	451 ----------------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	452
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	453 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	454 ``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	455 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	456 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	457 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	458 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	459 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	460
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	461 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	462 ------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	463
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	464 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	465 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	466 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	467 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	468 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	469
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	470 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	471 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	472 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	473 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	474 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	475 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	476 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	477
1148 2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	478 Code Sample
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	479 ===========
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	480
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	481 The following code sample illustrates some of the coding guidelines one should
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	482 follow in Pylearn. This is still a work-in-progress. Feel free to improve it and
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	483 add more!
1148 2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	484
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	485 .. 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	486
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	487 #! /usr/env/bin python
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	488
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	489 """Sample code. Edit it as you like!"""
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	490
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	491 __authors__ = "Olivier Delalleau"
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	492 __copyright__ = "(c) 2010, Universite de Montreal"
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	493 __license__ = "3-clause BSD License"
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	494 __contact__ = "Olivier Delalleau <delallea@iro>"
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	495
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	496 # 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	497 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	498
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	499 # 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	500 # 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	501 import numpy
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	502 import scipy
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	503 import theano
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	504 # Individual 'from' imports come after packages.
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	505 from numpy import argmax
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	506 from theano import tensor
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	507
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	508 # Application-specific imports come last.
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	509 # The absolute path should always be used.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	510 from pylearn import datasets, learner
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	511 from pylearn.formulas import noise
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	512
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	513
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	514 # All exceptions inherit from Exception.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	515 class PylearnError(Exception):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	516 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	517 pass
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	518
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	519 # All top-level classes inherit from object.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	520 class StorageExample(object):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	521 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	522 pass
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	523
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	524
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	525 # Two blank lines between definitions of top-level classes and functions.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	526 class AwesomeLearner(learner.Learner):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	527 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	528
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	529 def __init__(self, print_fields=None):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	530 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	531 # print_fields is a list of strings whose counts found in the
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	532 # training set should be printed at the end of training. If None,
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	533 # then nothing is printed.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	534 # Do not forget to call the parent class constructor.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	535 super(AwesomeLearner, self).__init__()
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	536 # Use None instead of an empty list as default argument to
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	537 # print_fields to avoid issues with mutable default arguments.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	538 self.print_fields = if_none(print_fields, [])
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	539
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	540 # One blank line between method definitions.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	541 def add_field(self, field):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	542 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	543 # Test if something belongs to a container with `in`, not
1318 565e4ef0bfbd Fixed comment in example: lists have no find() method Olivier Delalleau <delallea@iro> parents: 1305 diff changeset	544 # container-specific methods like `index`.
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	545 if field in self.print_fields:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	546 # TODO Print a warning and do nothing.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	547 pass
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	548 else:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	549 # This is why using [] as default to print_fields in the
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	550 # constructor would have been a bad idea.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	551 self.print_fields.append(field)
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	552
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	553 def train(self, dataset):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	554 # TODO Write doc (store the mean of each field in the training
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	555 # set).
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	556 self.mean_fields = {}
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	557 count = {}
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	558 for sample_dict in dataset:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	559 # Whenever it is enough for what you need, use iterative
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	560 # instead of list versions of dictionary methods.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	561 for field, value in sample_dict.iteritems():
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	562 # Keep line length to max 80 characters, using parentheses
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	563 # instead of \ to continue long lines.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	564 self.mean_fields[field] = (self.mean_fields.get(field, 0) +
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	565 value)
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	566 count[field] = count.get(field, 0) + 1
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	567 for field in self.mean_fields:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	568 self.mean_fields[field] /= float(count[field])
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	569 for field in self.print_fields:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	570 # Test is done with `in`, not `has_key`.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	571 if field in self.sum_fields:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	572 # TODO Use log module instead.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	573 print '%s: %s' % (field, self.sum_fields[field])
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	574 else:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	575 # TODO Print warning.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	576 pass
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	577
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	578 def test_error(self, dataset):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	579 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	580 if not hasattr(self, 'sum_fields'):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	581 # Exceptions should be raised as follows (in particular, no
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	582 # string exceptions!).
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	583 raise PylearnError('Cannot test a learner that was not '
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	584 'trained.')
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	585 error = 0
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	586 count = 0
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	587 for sample_dict in dataset:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	588 for field, value in sample_dict.iteritems():
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	589 try:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	590 # Minimize code into a try statement.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	591 mean = self.mean_fields[field]
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	592 # Always specicy which kind of exception you are
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	593 # intercepting with except.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	594 except KeyError:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	595 raise PylearnError(
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	596 "Found in a test sample a field ('%s') that had "
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	597 "never been seen in the training set." % field)
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	598 error += (value - self.mean_fields[field])**2
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	599 count += 1
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	600 # Remember to divide by a floating point number unless you
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	601 # explicitly want an integer division (in which case you should
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	602 # use //).
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	603 mse = error / float(count)
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	604 # TODO Use log module instead.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	605 print 'MSE: %s' % mse
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	606 return mse
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	607
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	608
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	609 def if_none(val_if_not_none, val_if_none):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	610 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	611 if val_if_not_none is not None:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	612 return val_if_not_none
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	613 else:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	614 return val_if_none
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	615
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	616
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	617 def print_subdirs_in(directory):
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	618 # TODO Write doc.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	619 # Using list comprehension rather than filter.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	620 sub_dirs = sorted([d for d in os.listdir(directory)
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	621 if os.path.isdir(os.path.join(directory, d))])
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	622 print '%s: %s' % (directory, ' '.join(sub_dirs))
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	623 # A `for` loop is often easier to read than a call to `map`.
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	624 for d in sub_dirs:
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	625 print_subdirs_in(os.path.join(directory, d))
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	626
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	627
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	628 def main():
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	629 if len(sys.argv) != 2:
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	630 # Note: conventions on how to display script documentation and
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	631 # parse arguments are still to-be-determined. This is just one
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	632 # way to do it.
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	633 print("""\
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	634 Usage: %s <directory>
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	635 For the given directory and all sub-directories found inside it, print
b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	636 the list of the directories they contain."""
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	637 % os.path.basename(sys.argv[0]))
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	638 return 1
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	639 print_subdirs_in(sys.argv[1])
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	640 return 0
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	641
1303 b5673b32e8ec API_coding_style: More work on code example Olivier Delalleau <delallea@iro> parents: 1254 diff changeset	642
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	643 # Top-level executable code should be minimal.
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	644 if __name__ == '__main__':
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	645 sys.exit(main())
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	646
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	647
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	648 Automatic Code Verification
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	649 ===========================
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	650
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	651 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	652 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	653 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	654 tips for Vim.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	655
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	656 .. _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	657
1324 075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	658 Commit message
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	659 ==============
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	660
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	661 * A one line summary. Try to keep it short, and provide the information
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	662 that seems most useful to other developers: in particular the goal of
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	663 a change is more useful than its description (which is always
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	664 available through the changeset patch log). E.g. say "Improved stability
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	665 of cost computation" rather than "Replaced log(exp(a) + exp(b)) by
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	666 a * log(1 + exp(b -a)) in cost computation".
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	667 * If needed a blank line followed by a more detailed summary
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	668 * Make a commit for each logical modification
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	669 * This makes reviews easier to do
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	670 * This makes debugging easier as we can more easily pinpoint errors in
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	671 commits with hg bisect
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	672 * NEVER commit reformatting with functionality changes
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	673 * Review your change before commiting
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	674 * "hg diff <files>..." to see the diff you have done
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	675 * "hg record" allows you to select which changes to a file should be
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	676 committed. To enable it, put into the file ~/.hgrc:
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	677
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	678 .. code-block:: bash
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	679
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	680 [extensions]
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	681 hgext.record=
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	682
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	683 * hg record / diff force you to review your code, never commit without
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	684 running one of these two commands first
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	685 * Write detailed commit messages in the past tense, not present tense.
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	686 * Good: "Fixed Unicode bug in RSS API."
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	687 * Bad: "Fixes Unicode bug in RSS API."
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	688 * Bad: "Fixing Unicode bug in RSS API."
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	689 * Separate bug fixes from feature changes.
1325 4efa2630f430 Minor grammar improvements Olivier Delalleau <delallea@iro> parents: 1324 diff changeset	690 * When fixing a ticket, start the message with "Fixed #abc"
1324 075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	691 * Can make a system to change the ticket?
1325 4efa2630f430 Minor grammar improvements Olivier Delalleau <delallea@iro> parents: 1324 diff changeset	692 * When referencing a ticket, start the message with "Refs #abc"
1324 075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	693 * Can make a system to put a comment to the ticket?
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	694
075a0f1c1ffc added to the web page the commit message recommendation. Frederic Bastien <nouiz@nouiz.org> parents: 1318 diff changeset	695
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	696 TODO
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	697 ====
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	698
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	699 Things still missing from this document, being discussed in coding_style.txt:
1375 7b61bfda1dab Commit guidelines have been added in API_coding_style Olivier Delalleau <delallea@iro> parents: 1373 diff changeset	700 - Proper style for C code
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	701 - Enforcing 100% test coverage of the code base
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	702 - 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	703 - Conventions for script usage documentation and argument parsing
1178 10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code Olivier Delalleau <delallea@iro> parents: 1170 diff changeset	704 - Conventions for class / method / function documentation
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code Olivier Delalleau <delallea@iro> parents: 1170 diff changeset	705 - Guidelines for serialization-friendly code (hint: nested and lambda
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code Olivier Delalleau <delallea@iro> parents: 1170 diff changeset	706 functions, as well as instance methods, cannot be serialized, and
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code Olivier Delalleau <delallea@iro> parents: 1170 diff changeset	707 apparently there are some issues with decorators -- to be investigated).
10bc5ebb5823 coding_style: Added note about the need to provide guidelines for serialization-friendly code Olivier Delalleau <delallea@iro> parents: 1170 diff changeset	708
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	709

Mercurial > pylearn

annotate doc/v2_planning/API_coding_style.txt @ 1377:0665274b14af