# HG changeset patch # User Olivier Delalleau # Date 1284668687 14400 # Node ID f6011a2aff0b4a21ae1c27d4f2d92b671790d74f # Parent d693881ea4d2c32c85aba90929c17d068026c770 coding_style: Moved David's comments from coding_style.txt to API_coding_style.txt diff -r d693881ea4d2 -r f6011a2aff0b doc/v2_planning/API_coding_style.txt --- a/doc/v2_planning/API_coding_style.txt Thu Sep 16 16:12:02 2010 -0400 +++ b/doc/v2_planning/API_coding_style.txt Thu Sep 16 16:24:47 2010 -0400 @@ -38,9 +38,12 @@ `_ * `PEP 257 -- Docstring Conventions `_ + * `Numpy Docstring Standard + `_ * `Google Python Style Guide `_ + However, there are a few points mentioned in those documents that we decided to do differently: @@ -107,3 +110,50 @@ my_everything]: ... +The ``logging`` Module vs. the ``warning`` Module +================================================= + +The ``logging`` Module +---------------------- + +A central logging facility for Python capable of logging messages of various +categories/urgency and choosing with some granularity which messages are +displayed/suppressed, as well as where they are displayed or written. This +includes an ``INFO`` level for innocuous status information, a ``WARNING`` level +for unexpected state that is still recoverable, ``DEBUG`` for detailed +information which is only really of interest when things are going wrong, etc. + +In addition to the `library documentation`_, see this helpful tutorial, +`Python Logging 101`_. + +.. _library documentation: http://docs.python.org/library/logging.html +.. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html + +The ``warning`` Module +---------------------- + +The ``warning`` module in the standard library and its main interface, the +``warn()`` function, allows the programmer to issue warnings in situations where +they wish to alert the user to some condition, but the situation is not +urgent enough to throw an exception. By default, a warning issued at a given +line of the code will only be displayed the first time that line is executed. +By default, warnings are written to ``sys.stderr`` but the ``warning`` module +contains flexible facilities for altering the defaults, redirecting, etc. + +Which? When? +------------ + +It is our feeling that the ``logging`` module's ``WARNING`` level be used to log +warnings more meant for *internal*, *developer* consumption, to log situations +where something unexpected happened that may be indicative of a problem but +is several layers of abstraction below what a user of the library would +care about. + +By contrast, the warning module should be used for warnings intended for user +consumption, e.g. alerting them that their version of Pylearn is older than +this plugin requires, so things may not work as expected, or that a given +function/class/method is slated for deprecation in a coming release (early +in the library's lifetime, ``DeprecationWarning`` will likely be the most common +case). The warning message issued through this facility should avoid +referring to Pylearn internals. + diff -r d693881ea4d2 -r f6011a2aff0b doc/v2_planning/coding_style.txt --- a/doc/v2_planning/coding_style.txt Thu Sep 16 16:12:02 2010 -0400 +++ b/doc/v2_planning/coding_style.txt Thu Sep 16 16:24:47 2010 -0400 @@ -520,65 +520,6 @@ * Make public some configuration files / plugins for vim * Come up with official common file header (license in particular) -Extended docstring standard (DWF) ---------------------------------- - -In addition to the general guidelines of PEP 257, it is advised that we adopt -the NumPy docstring standard, or at least use it as a basis for formulating -our own. - -Read the detailed docstring standard at - -http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard - - -logging module, the warning module, and when to use which ---------------------------------------------------------- - -The logging module -################## - -A central logging facility for Python capable of logging messages of various -categories/urgency and choosing with some granularity which messages are -displayed/suppressed, as well as where they are displayed or written. This -includes an "INFO" level for innocuous status information, a "WARNING" level -for unexpected state that is still recoverable, "DEBUG" for detailed -information which is only really of interest when things are going wrong, etc. - -In addition to the `library documentation`_, see this helpful tutorial, -`Python Logging 101`_. - -.. _library documentation: http://docs.python.org/library/logging.html -.. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html - -The warning module -################## - -The warning module in the standard library and its main interface, the -warn() function, allows the programmer to issue warnings in situations where -they wish to alert the user to some condition, but the situation is not -urgent enough to throw an exception. By default, a warning issued at a given -line of the code will only be displayed the first time that line is executed. -By default, warnings are written to sys.stderr but the warning module -contains flexible facilities for altering the defaults, redirecting, etc. - -Which? When? -############ - -It's our feeling that the logging module's WARNING level be used to log -warnings more meant for *internal*, *developer* consumption, to log situations -where something unexpected happened that may be indicative of a problem but -it's several layers of abstraction below what a user of the library would -care about. - -By contrast, the warning module should be used for warnings intended for user -consumption, e.g. alerting them that their version of pylearn is older than -this plugin requires, so things may not work as expected, or that a given -function/class/method is slated for deprecation in a coming release (early -in the library's lifetime, DeprecationWarnings will likely be the most common -case). The warning message issued through this facility should avoid -referring to pylearn internals. - Suggested per-file boilerplate ------------------------------