- Developer Tools
Sridhar Ratnakumar, February 18, 2010
- virtualenv: If your project depends on certain Python packages, but you'd prefer not to pollute your global Python installation, use virtualenv to create isolated Python environments into which you can install the packages.
- PyPM, pip: But how do you install packages in first place? Using PyPM, the default package manager included in ActivePython, you can search and install packages to your home directory or a virtualenv. For packages not available in PyPM, ActivePython also provides pip.
- buildout: While PyPM and pip automate package discovery and installation, you might also want to automate the process further by using buildout. Instead of manually creating the virtualenv directory, typing "pypm install ..." for every module, and repeating this on each of your development and deployment machines, use buildout to create a repeatable build configuration. Tasks like creating isolated an interpreter sandbox (à la virtualenv), installing dependent packages, and updating cron jobs can be automated in order to "repeat" them in any number of development or deployment machines.
- Sphinx: While some of us consider ourself passionate about creating software, documenting that creative work may not seem so appealing. Sphinx is a tool that will make you want to write documentation!
As you are about to embark on your new Python-based project, it is perhaps good to consider using existing tools available in the Python community. Consider the following tools that the Python community has provided to ease one's development process:
Without going into the details of how these tools work - which you can always find in their documentation - here are some instructions on how to quickly set up your project directory to make use of these tools:
Creating a buildout directory layout by hand is no fun, so let's use a Paste template to automate this:
$ pypm install modern-package-template $ paster create -t modern_package HelloWorld
After answering the questions the following directory structure will be created:
$ tree HelloWorld/ HelloWorld/ |-- bootstrap.py |-- buildout.cfg |-- setup.cfg |-- setup.py `-- src |-- HelloWorld.egg-info | |-- PKG-INFO | |-- SOURCES.txt | |-- dependency_links.txt | |-- entry_points.txt | |-- not-zip-safe | `-- top_level.txt `-- helloworld `-- __init__.py
To list your project dependencies, you must edit setup.py. For example, if your project would depends on Jinja2, then open setup.py and add "jinja2" to the install_requires parameter (more details).
Then run the following to create an isolated Python environment with your project dependencies:
$ python2.6 bootstrap.py $ bin/buildout
Your dependencies should now be installed, and you can continue using them in your src/helloworld/ package. To setup this development environment in other machines, simply run bootstrap.py and bin/buildout as above.
As for writing documentation? Run the following to create your documentation directory structure:
$ pypm install sphinx $ sphinx-quickstart
When asked, the root path to your documentation should be something like "doc". Then to build your docs:
$ cd doc/ $ make html
Then open doc/_build/html/index.html in your web browser. To add/edit documentation, edit the *.rst files (in reST format) in the doc/ directory.
That is all there is to it. While committing your work (to git, hg or svn), make sure to exclude the buildout related directories: bin/, develop-eggs, parts and doc/_build.