pylearn: doc/v2_planning/API_coding

annotate doc/v2_planning/API_coding_style.txt @ 1179:67f4edabb0cc

Merged

author	Olivier Delalleau <delallea@iro>
date	Fri, 17 Sep 2010 16:23:51 -0400
parents	10bc5ebb5823 fe6c25eb1e37
children	9ebd40d31a1b

rev	line source
1143 fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	1 =========================
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	2 Coding Style Guidelines
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	3 =========================
fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	4
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	5 Note: until the Pylearn documentation is properly compiled, you can view
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	6 the HTML version of this document `here
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	7 <http://www.iro.umontreal.ca/~delallea/tmp/coding_style/html/API_coding_style.html>`_.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	8
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	9 Main Goals
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	10 ==========
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	11
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	12 * Code should be compatible with Python 2.4 and above (using 2to3 for
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	13 conversion to Python 3.x). This may not be possible in the short term
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	14 for Theano-dependent code.
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	15
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	16 * Code should be easy to read, understand and update by developers and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	17 users.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	18
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	19 * Code should be well-documented and well-tested.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	20
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	21 Python Coding Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	22 ========================
1143 fa1715e759e3 Added API file for coding style committee (now we just need to fill it) Olivier Delalleau <delallea@iro> parents: diff changeset	23
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	24 Official Guidelines
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	25 -------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	26
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	27 Source Material
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	28 ~~~~~~~~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	29
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	30 The four main documents describing our Python coding guidelines are:
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	31 * `PEP 8 -- Style Guide for Python Code
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	32 <http://www.python.org/dev/peps/pep-0008>`_
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	33 * `Google Python Style Guide
a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	34 <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	35 * `PEP 257 -- Docstring Conventions
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	36 <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	37 * `Numpy Docstring Standard
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	38 <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard>`_
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	39
1147 f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	40
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	41 However, there are a few points mentioned in those documents that we decided
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	42 to do differently:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	43
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	44 * Use only one space (not two) after a sentence-ending period in comments.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	45
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	46 * You do not need to add an extra blank line before the closing quotes of
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	47 a multi-line docstring.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	48
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	49 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	50
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	51 # Good.
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	52 """
a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	53 This is a multi-line docstring.
1150 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 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	56 """
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	57
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	58 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	59 """This is a multi-line docstring.
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 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	62
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	63 """
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	64
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	65 * 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	66 wasting space on straighforward imports:
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	67
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	68 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	69
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	70 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	71 import os, sys, time
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	72 # 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	73 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	74 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	75 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	76 import os
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	77 import sys
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	78 import time
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	79
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	80 * 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	81 used multiple times, and no ambiguity is possible.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	82
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	83 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	84
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	85 # 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	86 from foo import Bar, Blah
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	87 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	88 # Good in most situations.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	89 import foo
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	90 do_something_with(foo.Bar(), foo.Blah())
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	91 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	92 from foo import *
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	93 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	94
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	95 Excerpts
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	96 ~~~~~~~~
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	97
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	98 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	99 guidelines:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	100
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	101 * Only use ASCII characters in code files.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	102
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	103 * 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	104
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	105 * Limit lines to 79 characters.
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 * Naming conventions: ``ClassName``, ``TOP_LEVEL_CONSTANT``,
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	108 ``everything_else``.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	109
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	110 * 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	111 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	112 the period at the end).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	113
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	114 * 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	115 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	116
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	117 * 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	118 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	119 imported.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	120
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	121 * 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	122 re-use, and is not grep-friendly.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	123
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	124 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	125
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	126 # Good.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	127 from theano import tensor
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	128 # Bad.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	129 from theano import tensor as T
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	130
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	131 * 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	132 lists:
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	133
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	134 - 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	135 the iteration),
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	136 - 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	137 - 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	138 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	139 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	140
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	141 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	142 \| Iterative version \| List version \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	143 +========================+========================+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	144 \| .. code-block:: python \| .. code-block:: python \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	145 \| \| \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	146 \| my_dict.iterkeys \| my_dict.keys \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	147 \| my_dict.itervalues \| my_dict.values \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	148 \| my_dict.iteritems \| my_dict.items \|
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 \| itertools.ifilter \| filter \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	153 \| itertools.imap \| map \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	154 \| itertools.izip \| zip \|
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 \| xrange \| range \|
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	159 +------------------------+------------------------+
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	160
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	161 Code example with ``map``:
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	162
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	163 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	164
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	165 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	166 for f_x in imap(f, x):
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	167 ...
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	168 all_f_x = map(f, x)
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	169 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	170 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	171 for element in map(f, x):
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	172 ...
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	173 imap(f, x)
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	174
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	175 * 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	176 easier to read.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	177
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	178 .. code-block:: python
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	179
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	180 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	181 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	182 if not line.startswith('#')]
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	183 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	184 non_comments = map(str.strip,
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	185 ifilter(lambda line: not line.startswith('#'),
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	186 my_file.readlines()))
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	187
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	188 * 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	189 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	190 container types.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	191
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	192 .. code-block:: python
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 # Good.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	195 has_key = key in my_dict
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	196 has_substring = substring in my_string
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	197 # Bad.
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	198 has_key = my_dict.has_key(key)
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	199 has_substring = my_string.find(substring) >= 0
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	200
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	201 * 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	202 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	203 below).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	204
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	205 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	206
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	207 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	208 def f(array=None):
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	209 array = pylearn.if_none(array, [])
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 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	212 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	213 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	214
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	215 * 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	216 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	217 doing.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	218
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	219
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	220 Additional Recommendations
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	221 --------------------------
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	222
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	223 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	224
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	225 * All Python code files should start like this:
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	226
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	227 .. code-block:: python
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	228
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	229 """Module docstring as the first line, as usual."""
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	230
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	231 __authors__ = "Olivier Delalleau, Frederic Bastien, David Warde-Farley"
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	232 __copyright__ = "(c) 2010, Universite de Montreal"
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	233 __license__ = "3-clause BSD License"
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	234 __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	235
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	236 * 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	237 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	238 versions of Python).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	239
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	240 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	241
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	242 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	243 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	244 mean_x = sum(x) / float(len(x))
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	245 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	246 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	247 mean_x = sum(x) / len(x)
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	248
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	249 * Always raise an exception with ``raise MyException(args)`` where ``MyException``
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	250 inherits from ``Exception``. This is required for compatibility across
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	251 all versions of Python.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	252
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	253 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	254
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	255 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	256 raise NotImplementedError('The Pylearn team is too lazy.')
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	257 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	258 raise NotImplementedError, 'The Pylearn team is too lazy.'
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	259 raise 'The Pylearn team is too lazy to implement this.'
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	260
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	261 * 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	262 ``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	263 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	264 finally`` behavior.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	265
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	266 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	267
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	268 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	269 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	270 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	271 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	272 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	273 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	274 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	275 always_do_this_regardless_of_what_happened()
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 try:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	278 something_that_may_fail()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	279 except SomeError:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	280 do_something_if_it_failed()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	281 finally:
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	282 always_do_this_regardless_of_what_happened()
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	283
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	284 * 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	285 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	286
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	287 * 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	288 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	289 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	290
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	291 * 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	292 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	293 versions.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	294
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	295 * Use ``numpy.inf`` and ``numpy.nan`` rather than
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	296 ``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	297 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	298 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	299 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	300 float('nan')``.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	301
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	302 * 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	303 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	304 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	305
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	306 .. code-block:: python
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	307
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	308 # Good.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	309 if (cond_1 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	310 cond_2 and
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	311 cond_3):
1173 a0f178bc9052 changes during the meeting pascanur parents: 1150 diff changeset	312
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	313 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	314 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	315 if cond_1 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	316 cond_2 and \
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	317 cond_3:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	318 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	319
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	320 * 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	321 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	322 The position of the first
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	323 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	324 what is easiest to read (sometimes both can be ok).
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	325
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	326 .. code-block:: python
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 # Good.
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	329 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	330 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	331 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	332 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	333 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	334 ...
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	335 # 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	336 # 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	337 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	338 my_foo,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	339 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	340 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	341 my_everything,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	342 ]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	343 ...
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	344 # 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	345 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	346 my_bar]:
d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	347 ...
1145 d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	348 # Bad.
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	349 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	350 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	351 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	352 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	353 my_bar,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	354 my_love,
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	355 my_everything]:
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	356 ...
d6d73a9f07b8 API_coding_style: Started to work on official guidelines Olivier Delalleau <delallea@iro> parents: 1143 diff changeset	357
1159 531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	358 * 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	359 compatibility).
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	360
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	361 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	362
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	363 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	364 my_list.sort(key=abs)
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	365 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	366 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	367
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	368 * 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	369 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	370 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	371
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	372 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	373
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	374 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	375 cPickle.dump(obj, open('my_obj.pkl', 'wb', protocol=-1))
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	376 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	377 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	378
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	379 * 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	380 converting to Python 3.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	381
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	382 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	383
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	384 # Good.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	385 def f(x, y_z):
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	386 y, z = y_z
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	387 ...
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	388 # Bad.
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	389 def f(x, (y, z)):
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
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	392 * 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	393 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	394
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	395 * 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	396
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	397 .. code-block:: python
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	398
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	399 if __name__ == '__main__':
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	400 sys.exit(main())
531e77fb67f2 coding_style: Moved more elements to official 'API' Olivier Delalleau <delallea@iro> parents: 1150 diff changeset	401
1150 d7192e52653e coding_style: Moved some elements to official API Olivier Delalleau <delallea@iro> parents: 1148 diff changeset	402
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	403 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	404 =================================================
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	405
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	406 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	407 ----------------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	408
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	409 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	410 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	411 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	412 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	413 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	414 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	415
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	416 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	417 `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	418
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	419 .. _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	420 .. _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	421
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	422 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	423 ----------------------
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	424
f6011a2aff0b coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt Olivier Delalleau <delallea@iro> parents: 1145 diff changeset	425 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	426 ``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	427 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	428 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	429 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	430 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	431 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	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 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	434 ------------
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 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	437 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	438 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	439 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	440 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	441
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 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	443 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	444 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	445 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	446 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	447 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	448 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	449
1148 2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	450 Code Sample
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	451 ===========
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	452
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	453 The following code sample illustrates some of the coding guidelines one should
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	454 follow in Pylearn. This is still a work-in-progress.
1148 2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	455
2da593b0f29d API_coding_style: Moved code sample at end of document for better readability Olivier Delalleau <delallea@iro> parents: 1147 diff changeset	456 .. 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	457
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	458 #! /usr/env/bin python
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	459
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	460 """Sample code. There may still be mistakes / missing elements."""
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	461
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	462 __authors__ = "Olivier Delalleau"
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	463 __copyright__ = "(c) 2010, Universite de Montreal"
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	464 __license__ = "3-clause BSD License"
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	465 __contact__ = "Olivier Delalleau <delallea@iro>"
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	466
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	467 # 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	468 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	469
1170 53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	470 # 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	471 # 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	472 import numpy
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	473 import scipy
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	474 import theano
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	475 # Put 'from' imports below.
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	476 from numpy import argmax
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	477 from theano import tensor
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	478
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	479 # Application-specific imports come last.
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	480 from pylearn import dataset
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	481 from pylearn.optimization import minimize
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	482
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	483 def print_files_in(directory):
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	484 """Print the first line of each file in given directory."""
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	485 # TODO To be continued...
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	486
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	487 def main():
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	488 if len(sys.argv) != 2:
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	489 # Note: conventions on how to display script documentation and
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	490 # parse arguments are still to-be-determined.
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	491 print("""\
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	492 Usage: %s <directory>
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	493 Print first line of each file in given directory (in alphabetic order)."""
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	494 % os.path.basename(sys.argv[0]))
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	495 return 1
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	496 print_files_in(sys.argv[1])
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	497 return 0
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	498
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	499 # Top-level executable code should be minimal.
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	500 if __name__ == '__main__':
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	501 sys.exit(main())
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	502
53340a8df1fa coding_style: Started to write full code sample Olivier Delalleau <delallea@iro> parents: 1162 diff changeset	503
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	504 Automatic Code Verification
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	505 ===========================
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	506
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	507 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	508 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	509 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	510 tips for Vim.
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	511
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	512 .. _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	513
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	514 TODO
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	515 ====
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	516
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	517 Things still missing from this document, being discussed in coding_style.txt:
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	518 - Proper style for C code and Mercurial commits
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	519 - Enforcing 100% test coverage of the code base
4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	520 - 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	521 - 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	522 - 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	523 - 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	524 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	525 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	526
1162 4f1b9e0a1377 coding_style: Moved more stuff to API Olivier Delalleau <delallea@iro> parents: 1159 diff changeset	527

Mercurial > pylearn

annotate doc/v2_planning/API_coding_style.txt @ 1179:67f4edabb0cc