From ceaa952f92a607b27c61b483051cd83ec5cfc41f Mon Sep 17 00:00:00 2001 From: bryan newbold Date: Wed, 19 Aug 2015 15:21:46 -0700 Subject: software/python: more style fixups --- software/python.page | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/software/python.page b/software/python.page index 538f73d..ca37287 100644 --- a/software/python.page +++ b/software/python.page @@ -15,23 +15,24 @@ indenting is a little weird. Style ------- -Python PEP-008 : Style Guide for +`Python PEP-008 `_: Style Guide for Python Code -pylint , a Python syntax checker. Very -verbose, use pylint -E (errors only) or at least pylint -r no (no report). Eg, -"pylint -r no file.py -d W0614 -d C -d R". +`pylint `_, a Python syntax checker. Very +verbose, use pylint -E (errors only) or at least ``pylint -r no`` (no report). +Eg, ``pylint -r no file.py -d W0614 -d C -d R``. For docstring documentation, refer to -PEP-257 and the Sphinx -documentation; specifically, document script functionality in a top level (above imports, +`PEP-257 `_ and the `Sphinx +documentation +`_; +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 +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: +of "Sphinx style". For example:: def public_fn_with_googley_docstring(name, state=None): """This function does something. @@ -62,7 +63,8 @@ of "Sphinx style". For example: """ return 0 -autopep8 is a tool to automatically pep8-ify a file: + +autopep8 is a tool to automatically pep8-ify a file. Use it like:: sudo pip install autopep8 autopep8 --in-place --select=W293,W191,W291 *.py @@ -79,8 +81,8 @@ 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)). +For debian packaging, use `stdeb `_ +(via `stackoverflow thread `_). For notes on pip vs. setup.py dependencies: https://caremad.io/blog/setup-vs-requirement/ @@ -100,32 +102,34 @@ number (as an int). RunSnakeRun ------------- -$ python -m cProfile -o ./dump.profile myscript.py --script-option blah -$ # run to completion or Ctrl-C, then -$ runsnakerun ./dump.profile +Example session:: + + $ python -m cProfile -o ./dump.profile myscript.py --script-option blah + $ # run to completion or Ctrl-C, then + $ runsnakerun ./dump.profile nosetests ------------- To do minimal tests without wrapping everything in a class, import assert -functions from nose.tools, eg: +functions from nose.tools, eg:: from nose.tools import assert_raises, assert_equal -To do interactive pdb debugging, simply: +To do interactive pdb debugging, simply:: $ nosetests --pdb - # or sometimes: + # or sometimes: $ nosetests --pdb-failures pdb ------- -To debug a script (interactive prompt on exception): +To debug a script (interactive prompt on exception):: python -m pdb myscript.py -or in-line, always at a particular point: +or in-line, always at a particular point:: import pdb; pdb.set_trace() -- cgit v1.2.3