Molot

Simple execution orchestrator.

Requirements

Molot requires Python 3.8 or above.

For development, you will need uv installed.

Usage

Create a new orchestration file, e.g. build.py for a build orchestration. Make it executable chmod +x build.py to make it easier to run.

#!/usr/bin/env python3
from molot import *

# Your targets and environment arguments here

evaluate()

Now you're ready to run the build script to see the help message:

./build.py

To only see a list of targets and environment arguments, call the built-in list target:

./build.py list

Not very exciting so far, let's learn how to add your own targets and environment arguments.

Targets

Any piece of work that your build needs to perform is defined as a target. Here's a trivial example of a target that executes ls.

@target(
    name="ls",
    description="lists current directory items",
    group="greetings",
    depends=["target1", "target2"]
)
def ls():
    shell("ls")

Parameters explained:

• name - unique name to reference the target (optional; function name is used by default)
• description - short description of what the target does displayed in the help message (optional)
• group - grouping to list target under (optional; listed under "ungrouped" by default)
• depends - list of other targets that must be executed first (optional)

Since all the parameters are optional, the shortest definition of the same target can be as follows:

@target()
def ls():
    shell("ls")

Here's how you run your new target:

./build.py ls

Dependency Resolution

Now we can define another target hello that depends on ls:

@target(description="say hello", depends=["ls"])
def hello():
    print("hello")

There is basic dependency resolution that checks for circular dependencies and finds all transitive dependency targets to execute before running the one that you called. When you call:

./build.py hello

What actually happens is equivalent to calling:

./build.py ls hello

Environment Arguments

Environment arguments ar a cross between environment variables and arguments. Values can be passed as the former and then overriden as the latter.

Here's how you define one:

ENV = envarg("ENV", default="dev", description="build environment")

Parameters explained:

• name - unique name for the argument
• default - default value if none is supplied (optional; None by default)
• description - short description of what the argument is displayed in the help message (optional)
• sensitive - indicates the value is sensitive and should be masked (optional)

The argument is evaluated right there (not inside of targets), so you can use that variable straightaway.

It can be set as a regular environment variable:

ENV=dev ./build.py sometarget

Alternatively, it can be passed as an argument:

./build.py sometarget --arg ENV=prod

Finally, you can pass .env file to load:

./build.py sometarget --dotenv /path/to/.env

If both are passed simultaneously, then argument takes precedence over the environment variable.

Examples

See examples for use cases that demonstrate the main features.