sane is a command runner made simple.



sane is a command runner made simple.

Bit depressing, eh?


sane is:

  • A single Python file, providing
  • A decorator (@recipe), and a function (sane_run)

sane does not:

  • Have its own domain specific language,
  • Have an install process,
  • Require anything other than python3,
  • Restrict your Python code.


  • More portable

At ~600 lines of code in a single file, sane is extremely portable, being made to be distributed alongside your code base. Being pure Python makes it cross-platform and with an extremely low adoption barrier. sane does not parse Python, or do otherwise "meta" operations, improving its future-proofness. sane aims to do only as much as reasonably documentable in a single README, and aims to have the minimum amount of gotchas, while preserving maximum flexibility.

  • More readable

Its simple syntax and operation make it easy to understand and modify your recipe files. Everything is just Python, meaning neither you nor your users have to learn yet another domain specific language.

  • More flexible

You are free to keep state as you see fit, and all correct Python is valid. sane can function as a build system or as a command runner.


Below is a sane recipes file to compile a C executable (Makefile style).


Exists in the root of a C project folder, with the following structure


   └ src
      └ *.c (source files)

The `build` recipe will build an executable at the root.
The executable can be launched with `python`.

import os
from subprocess import run
from glob import glob

from sane import *
from sane import _Help as Help

CC = "gcc"
EXE = "main"
SRC_DIR = "src"
OBJ_DIR = "obj"


# Ensure source and objects directories exist
os.makedirs(SRC_DIR, exist_ok=True)
os.makedirs(OBJ_DIR, exist_ok=True)

sources = glob(f'{SRC_DIR}/*.c')

# Define a compile recipe for each source file in SRC_DIR
for source_file in sources:
    basename = os.path.basename(source_file)
    obj_file = f'{OBJ_DIR}/{basename}.o'
    objects_older_than_source = (
        Help.file_condition(sources=[source_file], targets=[obj_file]))
            info=f'Compiles the file \'{source_file}\'')
    def compile():
        run(f'{CC} {COMPILE_FLAGS} -c {source_file} -o {obj_file}', shell=True)

# Define a linking recipe
        info='Links the executable.')
def link():
    obj_files = glob(f'{OBJ_DIR}/*.o')
    run(f'{CC} {" ".join(obj_files)} -o {EXE}', shell=True)

# Define a run recipe
        info='Runs the compiled executable.')
def run_exe():
    run(f'./{EXE}', shell=True)


The Flow of Recipes

sane uses recipes, conditions and hooks.

Recipe: A python function, with dependencies (on either/both other recipes and hooks), hooks, and conditions.

Conditions: Argument-less functions returning True or False.

Hook: A non-unique indentifier for a recipe. When a recipe depends on a hook, it depends on every recipe tagged with that hook.

The dependency tree of a given recipe is built and ran with sane_run(recipe). This is done according to a simple recursive algorithm:

  1. Starting with the root recipe,
  2. If the current recipe has no conditions or dependencies, register it as active
  3. Otherwise, if any of the conditions is satisfied or dependency recipes is active, register it as active.
  4. Sort the active recipes in descending depth and order of enumeration,
  5. Run the recipes in order.

In concrete terms, this means that if

  • Recipe A depends on B
  • B has some conditions and depends on C
  • C has some conditions


  • If any of B's conditions is satisfied, but none of C's are, B is called and then A is called
  • If any of C's conditions is satisfied, C, B, A are called in that order
  • Otherwise, nothing is ran.

The @recipe decorator

Recipes are defined by decorating an argument-less function with @recipe:

def my_recipe():
    # ...

name: The name ('str') of the recipe. If unspecified or None, it is inferred from the __name__ attribute of the recipe function. However, recipe names must be unique, so dynamically created recipes (from, e.g., within a loop) typically require this argument.

hooks: list of strings defining hooks for this recipe.

recipe_deps: list of string names that this recipe depends on. If an element of the list is not a string, a name is inferred from the __name__ attribute, but this may cause an error if it does not match the given name.

hook_deps: list of string hooks that this recipe depends on. This means that the recipe implicitly depends on any recipe tagged with one of these hooks.

conditions: list of callables with signature () -> bool. If any of these is True, the recipe is considered active (see The Flow of Recipes for more information).

info: a description string to display when recipes are listed with --list.


sane_run(default=None, cli=True)

This function should be called at the end of a recipes file, which will trigger command-line arguments parsing, and run either the command-line provided recipe, or, if none is specified, the defined default recipe. (If neither are defined, an error is reported, and the program exits.)

(There are exceptions to this: --help, --list and similars will simply output the request information and exit.)

By default, sane_run runs in "CLI mode" (cli=True). However, sane_run can also be called in "programmatic mode" (cli=False). In this mode, command-line arguments will be ignored, and the default recipe will be ran (observing dependencies, like in CLI mode). This is useful if you wish to programmatically call upon a recipe (and its subtree).

To see the available options and syntax when calling a recipes file (e.g.,, call

python --help


It is recommended to just include in the same directory as your project. You can do this easily with curl

curl '' >

However, because it's convenient, sane is also available to install from PyPi with

pip install sane-build



sane provides a few helper functions that are not included by default. These are contained in a Help class and can be imported with

from sane import _Help as Help



Returns a callable that is True if the newest file in sources is older than the oldest files in targets, or if any of the files in targets does not exist.

sources: list of string path to files.

targets: list of string path to files.


The sane logging functions are exposed in Help as log, warn, error. These take a single string as a message, and the error function terminates the program with exit(1).

Calling python ... is Gruesome

I suggest defining the following alias

alias sane='python3'


This tool is licensed under an MIT license. See LICENSE for details. The LICENSE is included at the top of, so you may redistribute this file alone freely.


💕 If you liked sane, consider buying me a coffee.

Miguel M.
Hi, nice to meet you. I study physics, program (games) and make music. You can find my portfolio below!
Miguel M.
A drop-in replacement for argparse that allows options to also be set via config files and/or environment variables.

ConfigArgParse Overview Applications with more than a handful of user-settable options are best configured through a combination of command line args,

null 544 Oct 18, 2021
A thin, practical wrapper around terminal capabilities in Python

Blessings Coding with Blessings looks like this... from blessings import Terminal t = Terminal() print(t.bold('Hi there!')) print(t.bold_red_on_brig

Erik Rose 1.3k Oct 19, 2021
Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.

Python Fire Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object. Python Fire is a s

Google 20.3k Oct 24, 2021
Color text streams with a polished command line interface

colout(1) -- Color Up Arbitrary Command Output Synopsis colout [-h] [-r RESOURCE] colout [-g] [-c] [-l min,max] [-a] [-t] [-T DIR] [-P DIR] [-d COLORM

nojhan 1.1k Sep 28, 2021
Pythonic command line arguments parser, that will make you smile

docopt creates beautiful command-line interfaces Video introduction to docopt: PyCon UK 2012: Create *beautiful* command-line interfaces with Python N

null 7.5k Oct 25, 2021
Rich is a Python library for rich text and beautiful formatting in the terminal.

Rich 中文 readme • lengua española readme • Läs på svenska Rich is a Python library for rich text and beautiful formatting in the terminal. The Rich API

Will McGugan 30.4k Oct 24, 2021
Python composable command line interface toolkit

$ click_ Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary. It's the "Comm

The Pallets Projects 11.5k Oct 24, 2021
A simple terminal Christmas tree made with Python

Python Christmas Tree A simple CLI Christmas tree made with Python Installation Just clone the repository and run $ python More opti

Francisco B. 34 Oct 6, 2021
Simple cross-platform colored terminal text in Python

Colorama Makes ANSI escape character sequences (for producing colored terminal text and cursor positioning) work under MS Windows. PyPI for releases |

Jonathan Hartley 2.6k Oct 23, 2021
Typer, build great CLIs. Easy to code. Based on Python type hints.

Typer, build great CLIs. Easy to code. Based on Python type hints. Documentation: Source Code:

Sebastián Ramírez 6.5k Oct 22, 2021
Python Command-line Application Tools

Clint: Python Command-line Interface Tools Clint is a module filled with a set of awesome tools for developing commandline applications. C ommand L in

Kenneth Reitz Archive 57 Oct 12, 2021
Cement is an advanced Application Framework for Python, with a primary focus on CLI

Cement Framework Cement is an advanced Application Framework for Python, with a primary focus on Command Line Interfaces (CLI). Its goal is to introdu

Data Folk Labs, LLC 1k Oct 25, 2021
Python and tab completion, better together.

argcomplete - Bash tab completion for argparse Tab complete all the things! Argcomplete provides easy, extensible command line tab completion of argum

Andrey Kislyuk 991 Oct 22, 2021
A fast, stateless http slash commands framework for scale. Built by the Crunchy bot team.

Roid ?? A fast, stateless http slash commands framework for scale. Built by the Crunchy bot team. ?? Installation You can install roid in it's default

Harrison Burt 7 Oct 17, 2021
plotting in the terminal

bashplotlib plotting in the terminal what is it? bashplotlib is a python package and command line tool for making basic plots in the terminal. It's a

Greg Lamp 1.6k Oct 17, 2021
Library for building powerful interactive command line applications in Python

Python Prompt Toolkit prompt_toolkit is a library for building powerful interactive command line applications in Python. Read the documentation on rea

prompt-toolkit 7.3k Oct 23, 2021
Python library that measures the width of unicode strings rendered to a terminal

Introduction This library is mainly for CLI programs that carefully produce output for Terminals, or make pretend to be an emulator. Problem Statement

Jeff Quast 250 Oct 15, 2021
A cross platform package to do curses-like operations, plus higher level APIs and widgets to create text UIs and ASCII art animations

ASCIIMATICS Asciimatics is a package to help people create full-screen text UIs (from interactive forms to ASCII animations) on any platform. It is li

null 2.8k Oct 23, 2021
Command line animations based on the state of the system

shell-emotions Command line animations based on the state of the system for Linux or Windows 10 The ascii animations were created using a modified ver

Simon Malave 61 Oct 21, 2021