Skip to main content

Create build files and CLI tools easily.

Project description

Simplify repetitive project tasks with Python.

Bumpy aims to provide a simple and effective way to collect and automate build, test, and deploy tasks. In order to leverage Python’s powerful syntax while still maintaining a minimal and readable build file, Bumpy includes several helper functions to reduce the amount of code and clutter your build files need to include without sacrificing functionality. In addition, Bumpy requires only built-in Python libraries - that means no external dependencies!

Bumpy is derived from pynt, and by extension, microbuild.

Usage

Bumpy is simple to use. Just open a bum.py file, define your tasks, and run bump in the same directory.

import bumpy as b

@b.task
def build():
    '''Builds ALL THE CODE.'''
    print 'Building'
$ bump build
Building

API

Bumpy provides a simple function decorator to register and track your tasks, as well as several helper functions to make your life easier when interfacing with shell commands and files.

Tasks

In order to convert your lovely functions into a Bumpy task, it’s as simple as applying the @task decorator:

import bumpy as b

@b.task
def build():
    '''Builds ALL THE CODE.'''
    print 'Building'

The function name will be used as the task name. The docstring will be saved and used for the built-in help. Any arguments or keyword arguments will be parsed and registered as CLI flags.


Prerequisite tasks / files can be specified with an optional reqs keyword argument to @task:

@b.task(reqs=build)
def run():
    print 'Running'

reqs can be a single requirement or a tuple of requirements. A dependency will only be executed the first time it’s required, although it may be explicitly executed multiple times via the command line:

$ bump run
Building
Running
$ bump build run
Building
Running
$ bump build build run
Building
Building
Running

str requirements will be interpreted as files / paths.


Generated files can be specified with an optional gens keyword argument:

@b.task(gens='docs')
def docs():
    print 'Documenting'

Generated files will be saved and can be automatically deleted with Bumpy’s clean() helper function. Generated files will also be used to look up file-based dependency chains.


Task aliases can be specified with an optional alias keyword argument:

@b.task(alias='pkg', reqs=(build, docs))
def package():
    print 'Packaging'

alias can be a single alias or a tuple of aliases.


A task can be set as the ‘default’ task, ie the task that Bumpy will invoke if no arguments are provided, by providing 'default' as an optional argument:

@b.task('default'):
def build():
    print 'Building'

A task can be set as the ‘setup’ task, ie the task that Bumpy will invoke prior to any other tasks, by providing 'setup' as an optional argument:

@b.task('setup')
def setup():
    print 'Setting stuff up'

Setup tasks can also accept arguments. More on this later!


Similar to ‘setup’ tasks, ‘teardown’ tasks are invoked after every other task, just before exiting:

@b.task('teardown')
def teardown():
    print 'Tearing stuff down'

A task can be removed from the lookup table by adding a 'private' optional argument or by prefixing its name with an underscore:

@b.task('setup', 'private'):
def setup():
    print 'Setting stuff up'

@b.ask('teardown')
def _teardown():
    print 'Tearing stuff down'

Private tasks can still be required and executed, but cannot be invoked from the command line and will not be included in the built-in help.


A task can grab a reference to itself by adding a 'method' optional argument:

@b.task('method', gens='output.txt')
def output(self):
    print 'Generating {}'.format(self.gens)

Function arguments / keyword arguments will be converted into command-line flags and options.

@b.task
def docs(modules, format='markdown'):
    print 'Documenting {!r} as {}'.format(modules, format)

Which can then be invoked like this:

$ bump docs all
Documenting 'all' as markdown
$ bump docs --format rst bumpy
Documenting 'bumpy' as rst
$ bump docs
abort [bumpy.main]: Too few arguments: [docs] expects 1
$ bump docs --format rst
abort [bumpy.main]: Too few arguments: [docs] expects 1

Keyword arguments must come before standard arguments, contrary to Python’s standards.

Helpers

To abort task execution and display an error message, use abort(message, *formatargs):

@b.task
def abort():
    b.abort('This task is bad.')

If *formatargs are provided, message will be used as a string format for str.format.


To invoke shell commands, use shell(command, *formatargs):

@b.task
def echo():
    '''This is an example task that uses a shell command.'''
    print b.shell('echo hi')

If *formatargs are provided, command will be used as a string format for str.format.


To require tasks during execution rather than pre-execution, use require(*reqs):

@b.task
def test(fail=False):
    if fail:
        require(abort)

    print 'Flexibly surviving'

To check whether requirements are valid without actually executing them, use valid(*reqs).


To get the youngest age of a collection of files, use: age(*paths):

@b.task(reqs='input.txt', gens='output.txt')
def output():
    if b.age('input.txt') < b.age('output.txt'):
        b.shell('cp input.txt output.txt')

If you’re meticulous about recording your generated files with gens, Bumpy will be able to automatically remove all generated files with clean():

@b.task
def clean():
    b.clean()

Namespaces

Tasks can be grouped into namespaces by using an optional namespace keyword argument:

@b.task(namespace='db')
def init():
    print 'Initialize database'
$ bump db.init
Initialize database

When bumpy fires up, it searches for modules in a bump/ directory and imports them, assigning each an appropriate namespace. If you want tasks to be in the global namespace, add them to bump/__bumpy_main__.py, bum.py, or build.py, only the first of which will be imported. If tasks in one namespace depend on tasks in another, you can use Python’s import to import their containing module.

CLI

bump --version will print the currently running version of Bumpy.

bump -h or bump --help will print a built-in help message.

bump -f <file> will tell bump to load a different file instead of bum.py or build.py.

bump -v TASK will enable verbose mode, printing an enter/exit message each time a task begins and ends execution.

bump TASK1 TASK2 TASK3 will execute tasks in sequence

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

bumpy-0.4.3.tar.gz (8.9 kB view hashes)

Uploaded Source

Supported by

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