Skip to main content

A light-weight, multi-platform, build tool for Python with Continuous Integration servers like Jenkins in mind.

Project description

Dovetail is a light-weight, multi-platform build tool for Python with Continuous Integration servers like Jenkins in mind.


TL;DR

Builds are complex, integrate many tools and sometimes must run on many platforms. Writing good build scripts is hard.

Dovetail helps in all these areas, and is not a rip’n’replace for your existing tools. You can readily automate a build using Dovetail.


Building an application is not just running:

> python setup.py sdist

What about:

  • Building binary distributions for several target platforms

  • Building the user documentation and the API docs?

  • Running your unit tests, sometimes using several test frameworks?

  • Installing your application in a clean virtual environment and running user tests?

  • Running code quality tools like Coverage and Pylint?

  • Tagging your code in your DVCS?

  • Uploading the artifacts to a repository? That’s probably at least an Egg, a source distribution, documentation and your web site

How can you guarantee everyone, especially the new team members, are building in the same way?

Many teams solve this by writing scripts, but that raises more questions:

  • Do you have a lot of scripts lying around, each doing their own thing, and little shared code?

  • Do you have operating system specific scripts that do the same thing, but on different operating systems?

  • Are your scripts reliable and maintainable?

If you need to improve in these areas, Dovetail can help. Dovetail:

  • Is pure Python, so the build runs everywhere and is maintainable

  • Provides a simple API to externalize many common build requirements

  • There are no new configuration file formats or 4GLs of abstruse XML or other syntaxes

  • Makes it simple to query the build environment and adjust the build appropriately

  • Audits all the build steps and decisions

  • Properly catches build errors and displays the details of what went wrong

  • Makes it terribly easy to automate the build in a tool like Jenkins.

A nice unexpected benefit for the maintainer was that it has become easier to build in my IDE; I also get precisely the same build from the command line.

Dovetail does not replace Setuptools or distutils - these are the perfect tools for the specific build step of creating a distributable package.

Functionality

A Dovetail build script is a standard Python script. Functions are declared to be tasks in the build by decorating them. Further decorators declare:

  • Task dependencies, with the same build script or across related files

  • Required packages, which are downloaded and installed if not present

  • Conditions, such as tests on environment variables or the file system.

  • Build directory structure

  • Error conditions, such as a non-zero return or output in stderr.

Dovetail works with numerous other tools to automate build steps, and has built-in integration with Virtualenv. Any build can be run in either the Python version on the path, or any nominated virtual environment.

Dovetail installs packages as required, even in the middle of a build. This means that you run a simple task in a complex build without installing all the documentation and test packages.

Example

A trivial example of a Dovetail build script is given below. It uses Sphinx to build the project documentation:

from dovetail import task, requires, check_result, call, mkdirs, do_if, IsDir
from os import path
from shutil import rmtree

DOCSOURCE = path.abspath(path.join(path.dirname(__file__), "source"))
BUILD     = path.abspath(path.join(path.dirname(__file__), "..", "build"))

@task                  # Declares the function clean() is a build task
@do_if(IsDir(BUILD))   # Only run if the build directory exists
def clean():
    """Clean the project of all build artifacts"""
    rmtree(BUILD)

@task                  # Declares the function clean() is a build task
@requires('sphinx')    # Ensures the sphinx package is installed
@mkdirs(BUILD)         # Make the build directory if it doesn't exist
@check_result          # Fails the build if sphinx fails
def doc():
    """Builds the Sphinx User documentation"""
    return call("sphinx-build {0} {1}".format(DOCSOURCE, BUILD).split(' '))

Builds are run simply from the OS command line:

$ dovetail clean doc

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Dovetail-1.0beta2.tar.gz (66.4 kB view details)

Uploaded Source

Built Distribution

Dovetail-1.0beta2-py2.7.egg (197.5 kB view details)

Uploaded Egg

File details

Details for the file Dovetail-1.0beta2.tar.gz.

File metadata

  • Download URL: Dovetail-1.0beta2.tar.gz
  • Upload date:
  • Size: 66.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for Dovetail-1.0beta2.tar.gz
Algorithm Hash digest
SHA256 5c2324257f482d9a3b6499c653e26a57ab1aafebee9cd120cf88587d2a539195
MD5 9766f88580ded4cdc0ccee592ea842a7
BLAKE2b-256 e5a3a26489d68f45e9dd38d4b075ac4dde33a92b7b22f2ebe9df9a090440c1eb

See more details on using hashes here.

File details

Details for the file Dovetail-1.0beta2-py2.7.egg.

File metadata

File hashes

Hashes for Dovetail-1.0beta2-py2.7.egg
Algorithm Hash digest
SHA256 8548db870485d7cfe601f2fb7b8513c1a60412b7b6e0404cbdc91a9a0ed4f8bf
MD5 fa93586ea6d1cd587288491fa8de130b
BLAKE2b-256 5226494923cb7ab596b0d3b63ebc935186799902b52933a524a9bc1a3c5e6d4d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page