Buildout is an awesome build management tool for Python projects, managing dependencies and featuring rich recipes for accomplishing advanced tasks. The main problem seems to be that documentation is lacking and/or terrible. Plus, project setup is painstaking and difficult to get right. Since I have years of experience in Maven, where creating a buildable project takes (literally) seconds to accomplish, this initially made Buildout too much of a hurdle. However, that’s now changed, as I’ve recently released version 0.1.0 of buildout-starter, an installable Python script to make creating Python and Django projects with Buildout a snap.
First, we’ll need to install buildout-starter which will automate everything for us. If you’re on a Linux variant or on OSX, make sure that
easy_install as well as Python are installed on your machine. On Windows, naturally it’s a bit harder, and you’ll have to install from source to get things rolling.
On Unix/Linux/OSX, either run this:
sudo pip install buildout-starter
sudo easy_install buildout-starter
buildout-starter on your machine.
Now that it’s hopefully installed, we’ll be able to quickly throw together a project to generate a simple Python script.
A Bare-Bones Python Project
To generate a bare-bones Python project, simply run this from your favorite terminal:
A new Buildout-ready project will be generated for you in the
Git Repository Generation
If you have Git installed and you’d like to automate the creation of a Git repository and a default
.gitignore file, you can pass
--git as a paramater to
buildout-start like this:
buildout-start --git myprojectname
That will create your project as well as initialize a Git repository in it, saving you a few steps. It also creates a
.gitignore file as mentioned above, ignoring all project build folders.
Eclipse PyDev Integration/Support
If you’re working in Eclipse with PyDev, you can also enable PyDev support at project creation time by passing the
buildout-start --pydev myprojectname
This will generate an Eclipse
.pydevproject file in your project’s base directory, ready to integrate with Eclipse. Don’t forget to run
bin/buildout after changing dependencies for these files to be updated with the right paths to their corresponding eggs.
IPython Shell Support
If you’re like me and prefer using the IPython shell instead of the default Python shell, as it provides many more features, you can easily add this to your project’s configuration at project creation time by passing the
buildout-start --ipython myprojectname
In addition to the
bin/python interpreter generated by default, you’ll also now have one at
bin/ipython which, unsurprisingly, points to an IPython shell for your project.
Django Project Generation
buildout-starter also features Django project generation, which saves even more time in configuration. Simply pass the
--django flag to the script to generate a Django project as opposed to a bare-bones Python project:
buildout-start --django myproject
This will create everything needed for Django project development. We’ll discuss this a bit more in the next part of the tutorial.
Custom Python-safe Package Names
If your project name contains any non-alphanumeric characters, you’ll quickly realize that
sanitizes them to get rid of non-Python identifier characters. Hyphens are converted to underscores, but everything else is wiped out. If you’d like to specify a custom sanitized project name, you can do so by passing the
--package-name flag with a sanitized project name:
buildout-start -p myproject my-project
By default, a project created with the name
my-project would have its name sanitized to
my_project. Since we don’t want that to happen (we’d rather get rid of the hyphen/underscore altogether), we pass the
-p flag with a value of
myproject to specify that we want the package name to be
myproject instead of the generated
Mix and Match Flags
All flags specified above can be mixed and matched to generate a project as needed:
buildout-start -p myproject --django --ipython --pydev --git my-project
This will generate a project named
my-project with a package name of
myproject. The project will be a Django project, with PyDev support, and an IPython interpreter. Additionally, a Git repository will be initialized in the project directory. Awesome!
In the next tutorial, we’ll discuss how to make and work with a simple Python project.