=== File organization === * The Encoding * The Copyright * The License * The Documentation String * The Imports * Authorship information * The Code {{{#!highlight sh # -*- coding: UTF-8 -*- # Copyright (C) YEARS AUTHOR-NAME __author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell" __copyright__ = "Copyright 2007, The Cogent Project" __credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley", "Matthew Wakefield"] __license__ = "GPL" __version__ = "1.0.1" __maintainer__ = "Rob Knight" __email__ = "rob@example.com" __status__ = "Production" }}} Status should typically be one of "Prototype", "Development", or "Production". __maintainer__ should be the person who will fix bugs and make improvements if imported. __credits__ differs from __author__ in that __credits__ includes people who reported bug fixes, made suggestions, etc. but did not actually write the code. === Comments === Comments should be full sentences, end with a period. {{{#!highlight sh def aLongFunction(x, y, z): # 2000 lines of code follow... return 1 # end aLongFunction }}} === Abbreviations === {{{ alignment aln archaeal arch auxillary aux bacterial bact character ch citation cite current curr database db dictionary dict directory dir end of file eof eukaryotic euk frequency freq expected exp index idx input in length ln maximum max minimum min mitochondrial mt number num observed obs original orig output out phylogeny phylo previous prev protein prot record rec reference ref sequence seq standard deviation stdev statistics stats size sz string str structure struct temporary temp taxonomic tax variance var }}} and {{{ class cls thread th transaction txn deferred dfd format fmt template tmpl implementation impl button btn_* checkbox chk_* middleware *_mw callback cb filename fn file object f }}} re_ for regular expression strings. rx_ for compiled regular expressions. m for matches. r for return values. === Function calls === Attempt to minimize vertical space, while not compromising readability. {{{#!highlight python result = someFunction(one, two, three) }}} over {{{#!highlight python result = someFunction( one, two, three) }}} over {{{#!highlight python result = someFunction( one, two, three ) }}} The latter is acceptable if line 1 or any of the arguments are long. E.g.: {{{#!highlight python result = someFunctionWithALongName( one, two, aLongThirdArgument ) }}} === ElementTrees/XML parsing === Use {{{elem}}} for unknown elements. Prefix 'x' onto elements/trees. E.g. for use xbody, use xtable, etc. From: http://self.maluke.com/style == Function/class documentation == pydoc has no standard (it just prints docstrings as-is), but the [[https://devguide.python.org/documenting/|core Python documentation has some tone/etc guidelines]]. [[https://www.python.org/dev/peps/pep-0257/|PEP257: Docstring Conventions]] specifies some stuff, but it is not very structured. [[https://www.python.org/dev/peps/pep-0287/|PEP287: reStructuredText Docstring Format]] also has some info. [[http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html?highlight=domains#id3|Sphinx has some standards]]. [[https://sphinxcontrib-napoleon.readthedocs.io/en/latest/|Napoleon format]], specified in Google's Python Style Guide, is very readable and has a module for Sphinx. [[https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html|Comprehensive example list]]. [[https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard|numpy has it's own docstring style guide]]. == Other resources == * [[http://code.google.com/p/soc/wiki/PythonStyleGuide|PythonStyleGuide - soc - Style guide for Python code contributed to Melange - SoC (Spice of Creation) - Google Project Hosting]] * [[https://google.github.io/styleguide/pyguide.html|Google Python Style Guide]] * [[https://github.com/google/yapf|google/yapf: A formatter for Python files]]. clang-format-like, similar to gofmt == Parsing JSON == Rather than doing {{{#!highlight python numbers=off blah['one']['two'] }}} Python 3.3+ has the !SimpleNamespace module: {{{#!highlight python numbers=off import types my_dict = { 'one': {'two': 2} } blah = SimpleNamespace(**my_dict) print(blah.one.two) }}} There are also 3rd-party libraries like [[https://pypi.org/project/python-box/|python-box]] == Lectures & Videos == === PyCon 2015: Beyond PEP8: Best practices for beautiful intelligible code === [[https://www.youtube.com/watch?v=wf-BqAjZb8M|Raymond Hettinger - Beyond PEP 8 -- Best practices for beautiful intelligible code - PyCon 2015 - YouTube]] * Adding an arbitrary line break to make a line <= 80 characters, shortening variable names, etc does NOT make code better. * "Foolish consistency is the hobgoblin of little minds" — right at the top of PEP8, people read right through it! [[http://www.youtube.com/watch?v=D_6ybDcU5gc|PyCon 2016: Refactoring Python: Why and How to Restructure Your Code]] is also relevant (not technical enough to need notes).