Builddrone

	Project	GitHub · PyPI
	Environment

Builddrone is a JSON-driven build orchestration framework and command-line interface for Python projects. A pipeline is made up of named stages, and each stage executes an ordered list of registered modules.

Installation

Install the latest released version from PyPI:

python -m pip install builddrone

For local development, install the project in editable mode together with its development tools from the repository root:

python -m pip install -e ".[dev]"

Builddrone requires Python 3.10 or newer.

Blueprint format

Builddrone loads blueprint.json from the current working directory. The top-level keys are stage names, and each stage contains module steps:

{
  "build": [
    {
      "module": "python.venv",
      "args": {"source": ".venv"}
    },
    {
      "module": "python.install",
      "args": {"requirements": "requirements.txt"}
    },
    {
      "module": "python.run",
      "args": {"source": "main.py"}
    }
  ]
}

Relative paths are resolved from the directory containing blueprint.json. Each step runs only after the preceding step succeeds.

Command-line usage

Run a stage from the directory containing its blueprint:

cd example/python
python -m builddrone build
python -m builddrone cleanup

The Python example creates .venv automatically, installs its requirements, lints and runs main.py, and builds a wheel and source distribution with python -m build. The separate cleanup stage removes the temporary environment and generated build artifacts.

The Robot Framework example runs similarly:

cd example/robotframework
python -m builddrone test
python -m builddrone cleanup

Its robotframework.test step writes results/output.xml, and robotframework.rebot converts that result into reports under results/rebot.

Built-in modules

Filesystem

Python

Robot Framework

Both Robot Framework modules accept an ordered arguments list and an optional cwd:

Each string in the list is emitted as a standalone command-line argument. Each single-entry object is emitted as a key followed by its value; list values emit the key followed by multiple values, and boolean true emits only the key. This keeps positional arguments explicit and avoids using null as a sentinel:

{
  "module": "robotframework.test",
  "args": {
    "arguments": [
      {"--outputdir": "results"},
      "tests"
    ]
  }
}

Using Builddrone as a framework

Built-in modules are registered by ExecutionEngine. Custom modules can be added by passing them to the constructor:

from builddrone.base_module import BaseModule
from builddrone.execution_engine import ExecutionEngine


class GreetingModule(BaseModule):
    def run(self, runner, args):
        runner.logger.info("Hello from %s", args.get("name", "Builddrone"))


engine = ExecutionEngine({"custom.greeting": GreetingModule()})
engine.run("build")

The custom module can then be used in blueprint.json:

{
  "build": [
    {
      "module": "custom.greeting",
      "args": {"name": "Builddrone"}
    }
  ]
}

Every module receives a Runner and a dictionary of arguments. The runner executes commands with the currently selected Python interpreter and exposes the blueprint's base directory for relative paths.

Execution flow

python -m builddrone <stage>
        |
        v
load blueprint.json -> select stage -> execute steps -> report failures

Any non-zero command exit code raises DroneException and stops the stage.

License

MIT License