API Reference

Functions

Create a project, run its recipes, and report its state.

init(): Create the project structure at path.
example(): Download a ready-to-run example project.
new_recipe(): Create recipes/<name>/ with a template recipe.toml and a stub step.
run(): Run one recipe’s steps in order and record what it produced.
sync(): Make the views and datapackage.json match the recipe folders, like uv sync.
check(): Report the state of the project, without changing anything.
cookbook(): Write cookbook.json, the ledger of the recipes the project uses.
root(): The project folder, found from the current folder.

What run, sync, check and cookbook return.

Every error is a UsefulViewsError and carries its facts as attributes and to_dict().

UsefulViewsError: Base class for every error useful-views raises.
RecipeRefused: A recipe was refused because it breaks a rule; nothing on disk changed.
StepFailed: A step exited with an error, so nothing was recorded.
OutputError: After the steps ran, a declared output was missing, empty or unreadable.
ProjectError: The project itself is missing or damaged, or a file could not be written.
ProjectNotFound: No useful-views project was found from the current folder or root=.
ExampleError: An example could not be downloaded or set up.
CookbookError: The cookbook cannot be written because the project is not in sync.
UsefulViewsWarning: Something worth knowing that does not stop the operation.

The numbered rules a recipe must follow.