PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
-There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory.
+There are two types of docstrings, one-line and multi-line. Their names
+should be fairly self explanatory.
One-line docstrings: ::
def kos_root():
Sphinx
------
-Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text.
+Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref`
+markup language into a range of output formats including HTML, LaTeX (for
+printable PDF versions), manual pages and plain text.
.. note:: This Guide is built with Sphinx_
reStructuredText
----------------
-Most Python documentation is written with reStructuredText_. The `reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the `reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ should help you familiarize yourself with its syntax.
+Most Python documentation is written with reStructuredText_. The
+`reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_ and the
+`reStructuredText Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
+should help you familiarize yourself with its syntax.
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
# 1, 4
# 2, 5
-The ``enumerate`` function has better readability than handling a counter manually. Moreover,
+The ``enumerate`` function has better readability than handling a counter
+manually. Moreover,
it is better optimized for iterators.
Read From a File
for line in f:
print line
-The ``with`` statement is better because it will ensure you always close the file,
-even if an exception is raised.
+The ``with`` statement is better because it will ensure you always close the
+file, even if an exception is raised.
Returning Multiple Values from a Function
-----------------------------------------
Line Continuations
~~~~~~~~~~~~~~~~~~
-When a logical line of code is longer than the accepted limit, you need to split it over multiple
-physical lines. Python interpreter will join consecutive lines if the last character of the line is
-a backslash. This is helpful sometime but is preferably avoided, because of its fragility: a white
-space added to the end of the line, after the backslash, will break the code and may have unexpected
-results.
+When a logical line of code is longer than the accepted limit, you need to
+split it over multiple physical lines. Python interpreter will join consecutive
+lines if the last character of the line is a backslash. This is helpful
+sometime but is preferably avoided, because of its fragility: a white space
+added to the end of the line, after the backslash, will break the code and may
+have unexpected results.
-A prefered solution is to use parenthesis around your elements. Left with an unclosed parenthesis on an end-of-line
-the Python interpreter will join the next line until the parenthesis is closed. The same behavior holds for
-curly and square braces.
+A prefered solution is to use parenthesis around your elements. Left with an
+unclosed parenthesis on an end-of-line the Python interpreter will join the
+next line until the parenthesis is closed. The same behavior holds for curly
+and square braces.
**Bad**:
from some.deep.module.inside.a.module import (a_nice_function, another_nice_function,
yet_another_nice_functio)
-However, more often than not having to split long logical line is a sign that you
-are trying to do too many things at the same time, which may hinder readability.
+However, more often than not having to split long logical line is a sign that
+you are trying to do too many things at the same time, which may hinder
+readability.
- Try hard to make tests that run fast. If one single test needs more than a
few millisecond to run, development will be slowed down or the tests will not
be run as often as desirable. In some cases, test can't be fast because they
- need a complex data structure to work on, and this data structure must be loaded
- every time the test runs. Keep these heavier tests in a separate test suite
- that is run by some scheduled task, and run all other tests as often as needed.
+ need a complex data structure to work on, and this data structure must be
+ loaded every time the test runs. Keep these heavier tests in a separate test
+ suite that is run by some scheduled task, and run all other tests as often
+ as needed.
- Learn your tools and learn how to run a single test or a test case. Then,
when developing a function inside a module, run this function's tests very
When comming back to work, you will have a pointer to where you were and get
faster on tracks.
-- The first step when you are debugging your code is to write a new test pinpointing
- the bug. While it is not always possible to do, those bug catching test are among
- the most valuable piece of code in your project.
+- The first step when you are debugging your code is to write a new test
+ pinpointing the bug. While it is not always possible to do, those bug
+ catching test are among the most valuable piece of code in your project.
- Use long and descriptive names for testing functions. The style guide here is
slighlty different than that of running code, where short names are often
- Another use of the testing code is as an introduction to new developers. When
someone will have to work on the code base, runnning and reading the related
testing code is often the best they can do. They will or should discover the
- hot spots, where most difficulties arise, and the corner cases. If they have to
- add some functionality, the first step should be to add a test and, by this mean,
- ensure the new functionality is not already a working path that has not been
- plugged in the interface.
+ hot spots, where most difficulties arise, and the corner cases. If they have
+ to add some functionality, the first step should be to add a test and, by this
+ mean, ensure the new functionality is not already a working path that has not
+ been plugged in the interface.
The Basics
::::::::::
Doctest
-------
-The doctest module searches for pieces of text that look like interactive Python
-sessions in docstrings, and then executes those sessions to verify that they work exactly as
-shown.
+The doctest module searches for pieces of text that look like interactive
+Python sessions in docstrings, and then executes those sessions to verify that
+they work exactly as shown.
-Doctests have a different use case than proper unit tests: they are usually less
-detailed and don't catch special cases or obscure regression bugs. They are
-useful as an expressive documentation of the main use cases of a module and
-its components. However, doctests should run automatically each time
-the full test suite runs.
+Doctests have a different use case than proper unit tests: they are usually
+less detailed and don't catch special cases or obscure regression bugs. They
+are useful as an expressive documentation of the main use cases of a module and
+its components. However, doctests should run automatically each time the full
+test suite runs.
A simple doctest in a function:
import doctest
doctest.testmod()
-When running this module from the command line as in ``python module.py``, the doctests
-will run and complain if anything is not behaving as described in the docstrings.
+When running this module from the command line as in ``python module.py``, the
+doctests will run and complain if anything is not behaving as described in the
+docstrings.
Tools
:::::
$ pip install pytest
-Despite being a fully-featured and extensible test tool it boasts a simple
+Despite being a fully-featured and extensible test tool it boasts a simple
syntax. Creating a test suite is as easy as writing a module with a couple of
functions
tox
---
-tox is a tool for automating test environment management and testing against multiple
-interpreter configurations
+tox is a tool for automating test environment management and testing against
+multiple interpreter configurations
::
git://git.eng.unimelb.edu.au / python-guide.git / commitdiff