Skip to content
Branch: master
Go to file
This branch is 8 commits ahead, 648 commits behind audreyr:master.

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time


Python-Boilerplate cookiecutter template

This is a CookieCutter template for generating a Python project. It provides simple starting points for using some of the popular best-practices:

  • Proper setuptools-compatible package layout.
  • py.test-based tests.
  • buildout for managing development tools or developing multiple-package projects
  • Usage of the Travis-CI continuous integration service.

Note that the same template is available for use with PasteScript via the python_boilerplate_template package.


Before you can use this template you should install cookiecutter is via easy_install or pip:

$ easy_install cookiecutter

The cookiecutter executable should appear in your Python's bin/ (in Windows Scripts/) directory. You might need to add that directory to your PATH to run the executable. You should also have git installed in your system.


To initialize a directory layout for a new project, ensure that cookiecutter is in your path and run:

$ cookiecutter

After asking some basic questions, the tool will create the following project layout for you:

  +-- .gitignore           # Git configuration
  +-- .travis.yml          # Travis-CI configuration
  +--         # Buildout bootstrap-script
  +-- buildout.cfg         # Buildout project configuration
  +-- setup.cfg            # Configuration for py.test and other tools
  +--            # Information on how to use the project
  +-- src/                 # Directory for keeping (possible multiple) project eggs
      +- <egg_name>/       # First egg of the project
         +-- package/      # Python source files
         +-- tests/        # Tests
         +-- .gitignore    # Git configuration
         +-- .travis.yml   # Travis-CI configuration
         +-- setup.cfg     # Configuration for py.test and other tools
         +--      # Package metadata
         +--   # Files to include in the package
         +-- README.rst    # Package description
         +-- LICENSE.txt   # License
         +-- CHANGELOG.txt # Changelog

This structure suggests you develop your project as a collection of eggs, with each egg having its separate subdirectory within src/. Each egg uses the standard setuptools layout, and the whole project relies on buildout to organize the parts.

Project preparation

The next thing to do after having created the project layout is to add the code to a version control repository. There are two common options for you to choose from:

  1. For smaller single-package projects you might want to keep only the Python's package code (i.e. src/<egg_name>) under version control, and consider the rest (the buildout.cfg and all that comes with it) to be your local development environment.
  2. For larger projects you should consider keeping the whole development environment (including buildout.cfg, perhaps several eggs under src, docs in doc, etc) under version control.

If you decided in favor of Option 1:

  • Create a version control repository under src/<egg_name>. Here is an example with Git:

    > cd src/<egg_name>
    > git init
    > git add .
    > git commit -m "Initial package structure"

    If you are using Github, proceed by creating a <your-project> repository on the Github website, and then doing:

    > git remote add origin<username>/<your-project>.git
    > git push origin master
  • You can safely delete the .travis.yml file in the root of the project (but leave the one within the src/<egg_name> directory).

If you decided in favor of Option 2:

  • Create a version control repository under the project root. The Git/Github example above applies, except for the first cd line.
  • Drop .travis.yml from the src/<egg_name> directory (leave the one in the project root).

Before you begin developing your code, you may wish to tune the src/<egg_name>/README.rst file. This file should contain a detailed description of what your package is supposed to do. In particular, when you submit your package to PyPI, the contents of this file will be shown on the package index page.

In addition, the LICENSE.txt included with the boilerplate code is a copy of the MIT license. If you project uses a different license, replace this file to match.

Eventually, you will also want to edit the to reflect the development instructions that apply to your project.

Finally, review the settings in src/<egg_name>/ (e.g., the classifiers parameter might require tuning).

Once you are done with the preparation, you can start developing by running python and then buildout. See next section.

Common development tasks

  • Setting up the development environment before first use:

    > python
    > export PATH=$PWD/bin:$PATH
        (in Windows: set PATH=%CD%\bin;%PATH%)
    > buildout
  • Running tests
    Tests are kept in the tests directory and are run using:
    > py.test
  • Creating Sphinx documentation:

    > sphinx-quickstart
    (Fill in the values, edit documentation, add it to version control)
    (Generate documentation by something like "cd docs; make html")

    (See this guide for more details)

  • Specifying dependencies for your package:
    Edit the install_requires line in src/<egg_name>/ by listing all the dependent packages.
  • Producing executable scripts:
    Edit the console_scripts section of entry_points in src/<egg_name>/ Then run buildout. The corresponding scripts will be created in the bin/ subdirectory. Note that the boilerplate project already contains one dummy script as an example.
  • Debugging the code manually:
    Simply run bin/python. This generated interpreter script has the project package included in the path.
  • Publishing the package on Pypi:

    > cd src/<egg_name>
    > python register sdist upload
  • Creating an egg or a windows installer for the package:

    > cd src/<egg_name>
    > python bdist_egg
    > python bdist_wininst
  • Travis-CI integration:
    To use the Travis-CI continuous integration service, follow the instructions at the Travis-CI website to register an account and connect your Github repository to Travis. The boilerplate code contains a minimal .travis.yml configuration file that might help you get started.
  • Other tools:
    The initial buildout.cfg includes several useful code-checking tools under the [tools] section. Adapt this list to your needs (remember to run buildout each time you change buildout.cfg).
  • Working with
    If you are working on a small project you might prefer to drop the whole buildout business completely and only work from within the package directory (i.e. make src\<egg_name> your project root). In this case you should know that you can use
    > python develop

    to include the package into the system-wide Python path. Once this is done, you can run tests via:

    > python test

    Finally, to remove the package from the system-wide Python path, run:

    > python develop -u
  • Developing multi-package projects:
    Sometimes you might need to split your project into several packages, or use a customized version of some package in your project. In this case, put additional packages as subdirectories of src/ alongside the original src/<egg_name>, and register them in buildout.cfg. For example, if you want to add a new package to your project, do
    > cd src/
    > cookiecutter
    > paster create <new_package_name>

    Then add src/<new_package_name> to version control and add the directory src/<new_package_name> to the develop list in buildout.cfg. Also, if necessary, add <new_package_name> to the [main] part of buildout.cfg and mention it in the [pytest] configuration section of setup.cfg.


Copyright & License

Copyright (c) 2014, Konstantin Tretyakov. MIT License.


Cookiecutter template for a a new buildout/pytest/travis/setuptools-enabled Python project.



No releases published


You can’t perform that action at this time.