## run()


Run one recipe's steps in order and record what it produced.


Usage

``` python
run(
    recipe,
    *,
    root=None,
)
```


Before anything on disk changes, the recipe is checked against the rules (`useful-views rules`). Then its views are deleted and `work/<recipe>/` is emptied, each step runs as its own process (from the project root, with this Python, its output shown as it runs), every declared view must have been written, and the run is recorded in `datapackage.json` and `useful-views/README.md`. Other recipes' records are not changed, and no other recipe is run: if other recipes read this one's views, a warning names them, because their views were made from the old ones (run `useful-views sync --all`, or run each of them, upstream first).


## Parameters


`recipe: str`  
The recipe's name, as in `"pwt_panel"` or `"recipes/pwt_panel/"`.

`root: str | Path | None = None`  
The project folder. By default it is found by walking up from the current folder to `datapackage.json`.


## Returns


`RunResult`  
A [RunResult](RunResult.md#useful_views.RunResult) naming the views written.


## Raises


`RecipeRefused`  
The recipe breaks a rule; nothing changed.

`StepFailed`  
A step failed; nothing was recorded and the recipe's views were removed.

`OutputError`  
A declared view was missing, empty or unreadable after the steps ran; nothing was recorded.

`ProjectError`  
Another useful-views command is changing the project, or a file could not be written or deleted.

`ProjectNotFound`  
No project was found.