# API Reference


## Functions


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


[init()](init.md#useful_views.init)  
Create the project structure at `path`.

[example()](example.md#useful_views.example)  
Download a ready-to-run example project.

[new_recipe()](new_recipe.md#useful_views.new_recipe)  
Create `recipes/<name>/` with a template `recipe.toml` and a stub step.

[run()](run.md#useful_views.run)  
Run one recipe's steps in order and record what it produced.

[sync()](sync.md#useful_views.sync)  
Make the views and datapackage.json match the recipe folders, like `uv sync`.

[check()](check.md#useful_views.check)  
Report the state of the project, without changing anything.

[cookbook()](cookbook.md#useful_views.cookbook)  
Write `cookbook.json`, the ledger of the recipes the project uses.

[root()](root.md#useful_views.root)  
The project folder, found from the current folder.


## Results


What run, sync, check and cookbook return.


[RunResult](RunResult.md#useful_views.RunResult)  
What `run` did.

[SyncResult](SyncResult.md#useful_views.SyncResult)  
What `sync` did.

[Finding](Finding.md#useful_views.Finding)  
One problem `check` found.

[CookbookResult](CookbookResult.md#useful_views.CookbookResult)  
What `cookbook` did, or found with `check=True`.


## Errors and warnings


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


[UsefulViewsError](UsefulViewsError.md#useful_views.UsefulViewsError)  
Base class for every error useful-views raises.

[RecipeRefused](RecipeRefused.md#useful_views.RecipeRefused)  
A recipe was refused because it breaks a rule; nothing on disk changed.

[StepFailed](StepFailed.md#useful_views.StepFailed)  
A step exited with an error, so nothing was recorded.

[OutputError](OutputError.md#useful_views.OutputError)  
After the steps ran, a declared output was missing, empty or unreadable.

[ProjectError](ProjectError.md#useful_views.ProjectError)  
The project itself is missing or damaged, or a file could not be written.

[ProjectNotFound](ProjectNotFound.md#useful_views.ProjectNotFound)  
No useful-views project was found from the current folder or `root=`.

[ExampleError](ExampleError.md#useful_views.ExampleError)  
An example could not be downloaded or set up.

[CookbookError](CookbookError.md#useful_views.CookbookError)  
The cookbook cannot be written because the project is not in sync.

[UsefulViewsWarning](UsefulViewsWarning.md#useful_views.UsefulViewsWarning)  
Something worth knowing that does not stop the operation.


## Rules


The numbered rules a recipe must follow.


[RULES](RULES.md#useful_views.RULES)  
The numbered rules a recipe must follow: RULES\[7\] is rule 7, a Rule.

[Rule](Rule.md#useful_views.Rule)  
One rule a recipe must follow.