# useful_views

> A framework and data project structure in which every derived table records the recipe that made it.

## Docs

### API Reference

#### Functions
> Create a project, run its recipes, and report its state.

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

#### Results
> What run, sync, check and cookbook return.

- [RunResult](https://jameshorine.github.io/useful-views/reference/RunResult.html): What `run` did
- [SyncResult](https://jameshorine.github.io/useful-views/reference/SyncResult.html): What `sync` did
- [Finding](https://jameshorine.github.io/useful-views/reference/Finding.html): One problem `check` found
- [CookbookResult](https://jameshorine.github.io/useful-views/reference/CookbookResult.html): 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](https://jameshorine.github.io/useful-views/reference/UsefulViewsError.html): Base class for every error useful-views raises
- [RecipeRefused](https://jameshorine.github.io/useful-views/reference/RecipeRefused.html): A recipe was refused because it breaks a rule; nothing on disk changed
- [StepFailed](https://jameshorine.github.io/useful-views/reference/StepFailed.html): A step exited with an error, so nothing was recorded
- [OutputError](https://jameshorine.github.io/useful-views/reference/OutputError.html): After the steps ran, a declared output was missing, empty or unreadable
- [ProjectError](https://jameshorine.github.io/useful-views/reference/ProjectError.html): The project itself is missing or damaged, or a file could not be written
- [ProjectNotFound](https://jameshorine.github.io/useful-views/reference/ProjectNotFound.html): No useful-views project was found from the current folder or `root=`
- [ExampleError](https://jameshorine.github.io/useful-views/reference/ExampleError.html): An example could not be downloaded or set up
- [CookbookError](https://jameshorine.github.io/useful-views/reference/CookbookError.html): The cookbook cannot be written because the project is not in sync
- [UsefulViewsWarning](https://jameshorine.github.io/useful-views/reference/UsefulViewsWarning.html): Something worth knowing that does not stop the operation

#### Rules
> The numbered rules a recipe must follow.

- [RULES](https://jameshorine.github.io/useful-views/reference/RULES.html): The numbered rules a recipe must follow: RULES[7] is rule 7, a Rule
- [Rule](https://jameshorine.github.io/useful-views/reference/Rule.html): One rule a recipe must follow