======================
Python
======================

iPython tricks
--------------

Use the ``cpaste'' command to copy in blocks of raw python code, even if the
indenting is a little weird. 

Style
-------
Python PEP-008 <http://www.python.org/dev/peps/pep-0008/>: Style Guide for
Python Code

pylint <http://pypi.python.org/pypi/pylint>, a Python syntax checker. Very
verbose, use pylint -E or at least pylint -r no.

For docstring documentation, refer to
PEP-257<http://www.python.org/dev/peps/pep-0257/> and the Sphinx
documentation<http://packages.python.org/an_example_pypi_project/sphinx.html
 >; specifically, document script functionality in a top level (above imports,
below any hashbang) docstring.

Use leading "#:" style comments to document important non-object/non-function
element definitions (eg, static variables) in a way that will get pulled out
into Sphinx.  Use "Google-style" function argument/return documentation instead
of "Sphinx style". For example:

    def public_fn_with_googley_docstring(name, state=None):
        """This function does something.

        Args:
            name (str):  The name to use.

        Kwargs:
            state (bool): Current state to be in.

        Returns:
            int.  The return code::

                0 -- Success!
                1 -- No good.
                2 -- Try again.

        Raises:
            AttributeError, KeyError

        A really great idea.  A way you might use me is

        >>> print public_fn_with_googley_docstring(name='foo', state=None)
        0

        BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

        """
        return 0

Packaging
-----------

Flask app packaging advice, including ``MANIFEST.in`` and non-PyPi dependancy
advice: http://flask.pocoo.org/docs/patterns/distribute/

Use ``console_scripts`` in ``setup.py`` to install system-wide scripts:
http://packages.python.org/distribute/setuptools.html#automatic-script-creation

For debian packaging, use [stdeb](http://pypi.python.org/pypi/stdeb)
(via [stackoverflow thread](http://stackoverflow.com/questions/7110604/standard-way-to-create-debian-packages-for-distributing-python-programs)).

"Fucking" String Encoding
---------------------------
(str/unicode errors in python are very prevalent and give me the rage)

The ``codecs`` package has some helpers; see for example
``open(f,mode,encoding)``.