Turn raw data into documented derived tables (useful views). Each recipe in recipes/ turns declared inputs into declared views by running numbered Python steps, and every run is recorded in datapackage.json.
Every command also runs as python -m useful_views ....
usage: useful-views [-h] [--version] [-C PATH] [--json] command ...
Global options
These go before the command; -C and --json may also go after it.
-h, --help |
show this help message and exit |
--version |
show program’s version number and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
useful-views init
Create the project structure in PATH: raw/, recipes/, work/, useful-views/, a starter README.md, AGENTS.md (for AI coding assistants), .gitignore and datapackage.json. Never overwrites a file.
usage: useful-views init [-h] [-C PATH] [--json] [--force] [path]
PATH (optional) |
project folder (default: the current folder) |
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
--force |
create the project even in your home folder or at the top of a drive |
useful-views example
Download an example project (raw data and recipes) from the useful-views-data repository, check every file’s SHA-256, and set it up like init. Then run: useful-views sync
usage: useful-views example [-h] [-C PATH] [--json] name [path]
NAME |
the example to download, such as pwt |
PATH (optional) |
folder to create (default: -example) |
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
useful-views new-recipe
Create recipes/NAME/ with a template recipe.toml and a stub step, 01_first_step.py. Both say TODO and are refused until you fill them in.
usage: useful-views new-recipe [-h] [-C PATH] [--json] name
NAME |
the recipe’s name: lowercase letters, digits and underscores, like pwt_panel |
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
useful-views run
Run one recipe. It is checked against the rules first (useful-views rules), then its views are deleted and work/RECIPE/ emptied, each step runs in numeric order as its own process with this Python and the project root as working directory, every declared view must be written, and the run is recorded in datapackage.json and useful-views/README.md. Other recipes are not run.
usage: useful-views run [-h] [-C PATH] [--json] recipe
RECIPE |
the recipe’s name, as in pwt_panel or recipes/pwt_panel/ |
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
useful-views check
Report what is missing or out of place, every rule a recipe breaks (refused), and recipes that sync would run. Changes nothing. Does not notice changes inside a step’s code.
usage: useful-views check [-h] [-C PATH] [--json]
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
useful-views sync
Make the views and datapackage.json match the recipe folders, like uv sync. Checks every recipe first and changes nothing if any would be refused. Then removes the records and view files of deleted recipes and outputs, and runs, upstream first, every recipe that is new, changed or missing its views, plus everything downstream of those.
usage: useful-views sync [-h] [-C PATH] [--json] [--all]
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
--all |
run every recipe again, upstream first (sync does not notice edits to a step’s code) |
useful-views cookbook
Write cookbook.json at the project root: every recorded recipe, in run order, with its description, inputs, outputs and steps, and the raw inputs the recipes read. Generated from datapackage.json, so the project must be in sync to write it. Commit it, like a lock file.
usage: useful-views cookbook [-h] [-C PATH] [--json] [--check]
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
--check |
do not write; exit 1 if cookbook.json is missing or out of date, or a recipe changed without a sync. Needs no data, so it works in CI |
useful-views rules
List the numbered rules. A refusal names the rule it broke.
usage: useful-views rules [-h] [-C PATH] [--json]
-h, --help |
show this help message and exit |
-C PATH, --project PATH |
run as if started in PATH (like git -C), for example a project folder |
--json |
print the result as JSON on standard output; other output goes to standard error |
Exit codes
0 |
success |
1 |
check found problems, or cookbook –check found the cookbook out of date |
2 |
usage error (unknown command or option, or a bad -C path) |
3 |
refused or failed (the message says what to fix, and in which file) |
130 |
interrupted (Ctrl-C) |
143 |
terminated (SIGTERM, from a CI cancel or a tool’s time limit; 129 SIGHUP; 149 Ctrl-Break) |