API Reference

Module-Level API

The chorelib module exports a default RuleSet instance and convenience decorators. For most use cases, you can use these directly without creating a RuleSet manually.

import chorelib

main = chorelib.Main()

@chorelib.rule("output.txt", depends="input.txt")
def build(target, depends, needs):
    chorelib.shell("cp", depends[0], target)

@chorelib.task
def clean():
    chorelib.shell("rm -f output.txt")

if __name__ == "__main__":
    main.run()

Decorators

chorelib.rule: Decorator to register a file-based build rule on the default RuleSet. See RuleSet.rule() for parameters.

chorelib.task: Decorator to register a task on the default RuleSet. See RuleSet.task() for parameters.

chorelib.mtime: Decorator to register a custom mtime function on the default RuleSet. See RuleSet.mtime() for parameters.

Global Settings

chorelib.verbose: int

Global verbosity level controlling message output. Set automatically from -v flags by Main.

0 — normal (default)
1 — verbose
2 — debug messages
3+ — logging debug output

RuleSet

class chorelib.ruledef.RuleSet[source]

A collection of rules, tasks, and mtime definitions.

RuleSet provides decorator methods (rule, task, mtime) for registering build rules. It also handles target matching and default target selection.

rule(targets, *, depends=None, needs=None, default=False, doc=None)[source]

Decorator to register a file-based build rule.

Parameters:

targets (Path | str | Pattern[str] | Sequence[Path | str | Pattern[str] | Sequence[Union[TargetParamType, TargetsParamType]]] | None) – Target file path(s) or regex pattern(s). Accepts a single value or arbitrarily nested lists — nested lists are recursively flattened. Each element can be a str, Path, or compiled re.Pattern. A string starting with ^ is automatically compiled as a regex.
depends (str | Callable[[...], Any] | Path | Sequence[str | Callable[[...], Any] | Path | Sequence[Union[DepParamType, DepsParamType]]] | None) – Dependencies that trigger rebuilds when newer than the target. Accepts a single value or arbitrarily nested lists — nested lists are recursively flattened. Each element can be a str, Path, or callable. Backreferences (\1, \2) are expanded against the regex match when the target is a pattern.
needs (str | Callable[[...], Any] | Path | Sequence[str | Callable[[...], Any] | Path | Sequence[Union[DepParamType, DepsParamType]]] | None) – Order-only prerequisites (built first but do not trigger rebuilds). Accepts the same types as depends and is also recursively flattened.
default (bool) – If True, use this target when no targets are specified.
doc (str | None) – Documentation string for the rule.

Returns:

A decorator that registers the decorated function as the builder.

Return type:

Callable[[Callable[[…], Any]], Callable[[…], Any]]

task(name_or_func=None, *, needs=None, default=False, doc=None)[source]

Decorator to register a task (always-execute target).

Can be used with or without arguments:

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

@ruleset.task("build", needs="setup")
def build_all():
    ...

Parameters:

name_or_func (str | Callable[[...], Any] | None) – Task name (str) or the function itself (when used without arguments).
needs (str | Callable[[...], Any] | Path | Sequence[str | Callable[[...], Any] | Path | Sequence[Union[DepParamType, DepsParamType]]] | None) – Order-only prerequisites. Accepts a single value or arbitrarily nested lists — nested lists are recursively flattened. Each element can be a str, Path, or callable.
default (bool) – If True, use this task when no targets are specified.
doc (str | None) – Documentation string for the task.

Returns:

A decorator or the original function if called without arguments.

Return type:

Callable[[…], Any] | Callable[[Callable[[…], Any]], Callable[[…], Any]]

mtime(targets, mtime=None)[source]

Decorator to register a custom mtime function for targets.

Parameters:

targets (Path | str | Pattern[str] | Iterable[Path | str | Pattern[str]]) – Target name(s) or regex pattern(s) to match. Accepts a single value or arbitrarily nested lists — nested lists are recursively flattened. Each element can be a str, Path, or compiled re.Pattern. A string starting with ^ is automatically compiled as a regex.
mtime (Callable[[str], Any] | None) – Optional mtime function. If None, the decorated function is used.

Returns:

A decorator that registers the decorated function as the mtime callback.

Return type:

Callable[[Callable[[str], Any]], Callable[[str], Any]]

Main

class chorelib.depmain.Main(rules=None, *, no_default=False)[source]

CLI driver for chorelib build scripts.

Parses command-line arguments (targets, verbosity, workers, rebuild flags) and runs the async build process. Subclass this to add custom arguments via add_arguments.

Parameters:

rules (-) – The set of rules to use for the build. If not provided, defaults to chorelib._default_rules.
no_default (-) – If True, the program will not assume a default target if none are specified on the command line.

parse_args(parser)[source]

Parse command-line arguments. Override to customize parsing.

Parameters:: parser (ArgumentParser)
Return type:: Namespace

add_arguments(parser)[source]

Hook for subclasses to add custom command-line arguments.

Parameters:: parser (ArgumentParser)
Return type:: None

build(targets)[source]

Execute the async build for the given targets.

Parameters:: targets (list[str])
Return type:: None

get_default_targets()[source]

Return the default target(s) when none are specified on the command line.

Return type:: list[str]

run()[source]

Main entry point: parse args, configure logging, and execute the build.

Return type:: None

schedule

chorelib.deprunner.schedule(*targets)[source]

Dynamically add new targets to the running build from within a builder.

This function can be called from a builder function to request that additional targets be built. It is thread-safe and works from both the event loop thread and worker threads.

Parameters:: targets (str) – A list of target names to schedule for building.
Raises:: RuntimeError – If no build runner is currently active.
Return type:: None

Utility Functions

shell

chorelib.utils.shell(*cmd, cwd=None, text=True, check=True, capture=False, env=None, echo=True)[source]

Execute a command string via the system shell.

Multiple arguments are joined with spaces into a single shell command line.

Parameters:

*cmd (Any) – Command string(s) or objects to execute. Nested sequences are recursively flattened and each element is converted to a string, then joined with spaces into a single command line.
cwd (str | None) – Working directory for the command.
text (bool) – If True, decode stdout/stderr as text.
check (bool) – If True, raise CalledProcessError on non-zero exit.
capture (bool) – If True, capture and return stdout.
env (dict[str, str] | None) – Environment variables for the subprocess.
echo (bool) – If True, print the command to stderr.

Returns:

The captured stdout string if capture=True, otherwise None.

Return type:

str | None

command

chorelib.utils.command(*cmd, cwd=None, text=True, check=True, capture=False, env=None, echo=True)[source]

Execute a command directly without a shell (no shell interpretation).

Each argument is passed as a separate element in the argument list, avoiding shell injection risks.

Parameters:

*cmd (Any) – Command and arguments to execute. Nested sequences are recursively flattened and each element is converted to a string before being passed to the subprocess.
cwd (str | None) – Working directory for the command.
text (bool) – If True, decode stdout/stderr as text.
check (bool) – If True, raise CalledProcessError on non-zero exit.
capture (bool) – If True, capture and return stdout.
env (dict[str, str] | None) – Environment variables for the subprocess.
echo (bool) – If True, print the command to stderr.

Returns:

The captured stdout string if capture=True, otherwise None.

Return type:

str | None

message

chorelib.utils.message(msg, level=0)[source]

Print a message to stderr if the current verbosity level is sufficient.

Parameters:

msg (str) – The message string to display.
level (int) – Minimum verbosity level required to show the message. The message is printed only when chorelib.verbose >= level.

Return type:

None

flatten

chorelib.utils.flatten(seq, ignore_none=True)[source]

Recursively flatten nested iterables into a single sequence.

Strings are treated as atomic values and are not iterated over.

Parameters:

seq (Any) – A value or nested iterable to flatten.
ignore_none (bool) – If True, None values are skipped.

Yields:

Individual non-iterable elements from the input.

Return type:

Iterator[Any]

Exceptions

class chorelib.errors.RuleError[source]: General error related to rule definitions or dependency cycles.

class chorelib.errors.RuleNotFoundError[source]: Raised when no rule is found to build a requested target.

class chorelib.errors.TargetNotFoundError[source]: Raised when a target file or resource does not exist and has no builder.