Warning: Some of this material is highly opinionated.

Frontmatter: Before I say anything, let me point you to the official Style Guide for Python Code, PEP 0008.

Part 1 - Documentation

Documenting your code is a great practice that is usually considered second-priority. But, it's not. It's quite important and easy actually!

# Inline Comments



In [19]:

    
# Inline comments are good, but need to be relevant.
# There can be comment blocks, like this section here.
# Comments can also follow code on the same line as seen below
# in our two examples.

# Below, I adjust the border width.
x = 2

x = 3  # Compensate for border

Documentation Strings (aka '''docstrings''')

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.



In [20]:

    
#print __doc__



In [21]:

    
import os
#print os.__doc__



In [22]:

    
#print os.system.__doc__

Breakout!

Start plaing with some docstrings inside classes, functions and at the top of your scripts. See how to generate different __doc__ statements.

Sphinx

Sphinx is a preferred choice for Python documentation. There is an autodoc feature that generates generic documentation and can pull code's docstrings as well. A quick reStructuredText Primer is also available.

reStructuredText markup (rst)
Read the Docs free hosting

A little Python documentation humor...

EXTERIOR: DAGOBAH -- DAY
      With Yoda strapped to his back, Luke climbs up one of
   the many thick vines that grow in the swamp until he
   reaches the Dagobah statistics lab. Panting heavily, he
   continues his exercises -- grepping, installing new
   packages, logging in as root, and writing replacements for
   two-year-old shell scripts in Python.
YODA: Code! Yes. A programmer's strength flows from code maintainability. But beware of Perl. Terse syntax... more than one way to do it... default variables. The dark side of code maintainability are they. Easily they flow, quick to join you when code you write. If once you start down the dark path, forever will it dominate your destiny, consume you it will.

LUKE: Is Perl better than Python?

YODA: No... no... no. Quicker, easier, more seductive.

LUKE: But how will I know why Python is better than Perl?

YODA: You will know. When your code you try to read six months from now.

Part 2 - Version Control & Repositories

Within a project's evolution, management of revisions, significant releases, and collaborative development becomes too large to keep renaming files or creating duplicates.

Semantic Versioning

Version Control via Git

Some really good, simple guides that we are going to use:

More Resources:

Other Version Control Systems:

Mercurial
Apache Subversion (svn)
Concurrent Versions System (CVS)

Repository Hosting

You can keep repositories local only, but hosting them online for collaboration and also sharing helps with development. As you can see with our Bootcamp lectures, we have more capability to interact with our students. GitHub is one among many hosting sites and I will not go in depth about those here.

Part 3 - Project Structure & Packaging

Aside: Module & Package importing.

When writing Python code, the file you are working on is a Python module (i.e., script.py). After putting it in a folder alongside a __init__.py file, it has become a Python Package. Let's see how this works:

An example:

.
./modu
./modu/modu.py  # the modu module inside the modu package
./modu/__init__.py



In [18]:

    
import modu
# now we access modu's scripts via modu.{}
from modu import modu
# here we access the modu module inside the modu package

Any directory with an __init__.py file is considered a Python package.



In [15]:

    
%%bash
#mkdir package_name      # containing folder
#cd package_name

#touch README.md         # highest level of documentation (minimum: project name)
#touch CHANGELOG         # optional: if included in README
#touch LICENSE.txt       # protect your code
#touch setup.py          # for easy_install
#touch requirements.txt  # package dependencies
#mkdir docs              # Sphinx
#mkdir package_name
#touch package_name/__init__.py  # needed for import

.
./package_name
./package_name/docs
./package_name/LICENSE.txt
./package_name/README.md
./package_name/setup.py
./package_name/requirements.txt
./package_name/package_name
./package_name/package_name/__init__.py

PyPA Sample Project gives a sample setup.py file that we can explore:



In [16]:

    
# %load http://raw.githubusercontent.com/pypa/sampleproject/master/setup.py

Virtual Environments (virtualenv & virtualenvwrapper)

A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.



In [ ]:

    
# pip freeze > requirements.txt

Packaging

There are some great guides out there and I will just point you to them to read at your convenience.



In [ ]: