Mercurial > pylearn

comparison doc/v2_planning/API_coding_style.txt @ 1147:f6011a2aff0b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt
author Olivier Delalleau <delallea@iro>
date Thu, 16 Sep 2010 16:24:47 -0400
parents d6d73a9f07b8
children 2da593b0f29d
comparison
equal deleted inserted replaced
1146:d693881ea4d2 1147:f6011a2aff0b
36 The three main documents describing our Python coding guidelines are: 36 The three main documents describing our Python coding guidelines are:
37 * `PEP 8 -- Style Guide for Python Code 37 * `PEP 8 -- Style Guide for Python Code
38 <http://www.python.org/dev/peps/pep-0008>`_ 38 <http://www.python.org/dev/peps/pep-0008>`_
39 * `PEP 257 -- Docstring Conventions 39 * `PEP 257 -- Docstring Conventions
40 <http://www.python.org/dev/peps/pep-0257>`_ 40 <http://www.python.org/dev/peps/pep-0257>`_
41 * `Numpy Docstring Standard
42 <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard>`_
41 * `Google Python Style Guide 43 * `Google Python Style Guide
42 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_ 44 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
45
43 46
44 However, there are a few points mentioned in those documents that we decided 47 However, there are a few points mentioned in those documents that we decided
45 to do differently: 48 to do differently:
46 49
47 * Use only one space (not two) after a sentence-ending period in comments. 50 * Use only one space (not two) after a sentence-ending period in comments.
105 my_bar, 108 my_bar,
106 my_love, 109 my_love,
107 my_everything]: 110 my_everything]:
108 ... 111 ...
109 112
113 The ``logging`` Module vs. the ``warning`` Module
114 =================================================
115
116 The ``logging`` Module
117 ----------------------
118
119 A central logging facility for Python capable of logging messages of various
120 categories/urgency and choosing with some granularity which messages are
121 displayed/suppressed, as well as where they are displayed or written. This
122 includes an ``INFO`` level for innocuous status information, a ``WARNING`` level
123 for unexpected state that is still recoverable, ``DEBUG`` for detailed
124 information which is only really of interest when things are going wrong, etc.
125
126 In addition to the `library documentation`_, see this helpful tutorial,
127 `Python Logging 101`_.
128
129 .. _library documentation: http://docs.python.org/library/logging.html
130 .. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html
131
132 The ``warning`` Module
133 ----------------------
134
135 The ``warning`` module in the standard library and its main interface, the
136 ``warn()`` function, allows the programmer to issue warnings in situations where
137 they wish to alert the user to some condition, but the situation is not
138 urgent enough to throw an exception. By default, a warning issued at a given
139 line of the code will only be displayed the first time that line is executed.
140 By default, warnings are written to ``sys.stderr`` but the ``warning`` module
141 contains flexible facilities for altering the defaults, redirecting, etc.
142
143 Which? When?
144 ------------
145
146 It is our feeling that the ``logging`` module's ``WARNING`` level be used to log
147 warnings more meant for *internal*, *developer* consumption, to log situations
148 where something unexpected happened that may be indicative of a problem but
149 is several layers of abstraction below what a user of the library would
150 care about.
151
152 By contrast, the warning module should be used for warnings intended for user
153 consumption, e.g. alerting them that their version of Pylearn is older than
154 this plugin requires, so things may not work as expected, or that a given
155 function/class/method is slated for deprecation in a coming release (early
156 in the library's lifetime, ``DeprecationWarning`` will likely be the most common
157 case). The warning message issued through this facility should avoid
158 referring to Pylearn internals.
159