saturnin._scripts.commands.recipes

Saturnin recipe management commands.

This module provides Typer commands for listing, showing, editing, installing, uninstalling, and creating Saturnin recipes. Recipes are configuration files that define how to run services or bundles of services.

Globals

saturnin._scripts.commands.recipes.app

Typer command group for recipe management commands

Parameters:
Return type:

Any

Command functions

saturnin._scripts.commands.recipes.list_recipes() → None[source]

Lists all installed Saturnin recipes.

Displays a table with the recipe name, type (service or bundle), execution mode (normal or daemon), whether it’s associated with an application, and a brief description.

Return type:

None

saturnin._scripts.commands.recipes.show_recipe(recipe_name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7092a325af90>], section: ~types.Annotated[str | None, <typer.models.OptionInfo object at 0x7092a320be50>] = None, *, raw: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7092a333f350>] = False)[source]

Displays detailed information about an installed Saturnin recipe.

By default, it analyzes the recipe file, showing its metadata (type, execution mode, associated application), a description, and a breakdown of its components (services within a bundle or the single service) along with their configurations as defined in the specified or default section (e.g., ‘service’ or ‘bundle’).

If a recipe contains multiple service/bundle configuration sections (variants), use the --section option to specify which one to analyze.

The --raw option will instead print the entire content of the recipe file with syntax highlighting.

Parameters:

  • recipe_name (Annotated[str, <typer.models.ArgumentInfo object at 0x7092a333f6d0>])

  • section (Annotated[str | None, <typer.models.OptionInfo object at 0x7092a333f850>])

  • raw (Annotated[bool, <typer.models.OptionInfo object at 0x7092a3253150>])

saturnin._scripts.commands.recipes.edit_recipe(recipe_name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7092a325b2d0>])[source]

Opens the specified installed recipe file in an external editor.

The editor is determined by the EDITOR environment variable or Saturnin’s configured default. After editing, the recipe registry is reloaded.

Parameters:

recipe_name (Annotated[str, <typer.models.ArgumentInfo object at 0x7092a320b850>])

saturnin._scripts.commands.recipes.create_recipe(recipe_name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7092a3288e10>], components: ~typing.Annotated[list[str], <typer.models.ArgumentInfo object at 0x7092a3288a10>], *, plain: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7092a316fc10>] = False)[source]

Creates a new recipe template file for the specified Saturnin service(s).

The generated recipe file will contain default configurations for the listed services. This template typically requires further modification to suit specific needs.

  • If one component is specified, a ‘service’ type recipe is created.

  • If multiple components are specified, a ‘bundle’ type recipe is created.

—

After generating the template, it will be opened in an external editor for immediate customization. If saved, the new recipe is installed.

Parameters:

  • recipe_name (Annotated[str, <typer.models.ArgumentInfo object at 0x7092a327a9d0>])

  • components (Annotated[list[str], <typer.models.ArgumentInfo object at 0x7092a3275550>])

  • plain (Annotated[bool, <typer.models.OptionInfo object at 0x7092a3274a90>])

saturnin._scripts.commands.recipes.install_recipe(recipe_file: Path | None, <typer.models.OptionInfo object at 0x7092a316c9d0>]=None, application: Annotated[str | None, <typer.models.OptionInfo object at 0x7092a3287450>]=None, recipe_name: Annotated[str | None, <typer.models.OptionInfo object at 0x7092a32e00d0>]=None)[source]

Installs a new recipe into the Saturnin environment.

A recipe can be installed either from an external cfg file (using --recipe-file) or by generating it from an installed Saturnin application (using --application). The installed recipe will be copied/created in Saturnin’s recipes directory.

If recipe_name is not provided, it’s automatically derived:

  • From the filename if --recipe-file is used (e.g., my_service.cfg becomes my_service).

  • From the application’s default recipe name if --application is used.

—

The command validates that all services and applications required by the recipe are currently installed in the Saturnin environment.

Parameters:

  • recipe_file (Annotated[Path | None, <typer.models.OptionInfo object at 0x7092a32e0390>])

  • application (Annotated[str | None, <typer.models.OptionInfo object at 0x7092a32e0210>])

  • recipe_name (Annotated[str | None, <typer.models.OptionInfo object at 0x7092a32e0310>])

saturnin._scripts.commands.recipes.uninstall_recipe(recipe_name: Annotated[str | None, <typer.models.ArgumentInfo object at 0x7092a311a2d0>]=None, save_to: Path | None, <typer.models.OptionInfo object at 0x7092a311ab50>]=None)[source]

Uninstalls a Saturnin recipe from the environment.

If the --save-to option is provided, the content of the recipe file will be saved to the specified path before the original recipe file is deleted from Saturnin’s recipes directory.

Parameters:

  • recipe_name (Annotated[str | None, <typer.models.ArgumentInfo object at 0x7092a311b750>])

  • save_to (Annotated[Path | None, <typer.models.OptionInfo object at 0x7092a311bad0>])

saturnin._scripts.commands.recipes.run_recipe(ctx: Context, section: Annotated[str | None, <typer.models.OptionInfo object at 0x7092a32e1610>]=None, config: Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7092a3107150>]=None, *, print_outcome: Annotated[bool, <typer.models.OptionInfo object at 0x7092a3107550>]=False, quiet: Annotated[bool, <typer.models.OptionInfo object at 0x7092a3107790>]=False, main_thread: Annotated[bool, <typer.models.OptionInfo object at 0x7092a3106010>]=False) → None[source]

Internal handler to execute a Saturnin recipe.

This function is invoked by Typer when a run command, dynamically created from an installed recipe, is executed. It determines the recipe to run based on the invoked command name (ctx.command.name).

It constructs the appropriate command line for saturnin-service or saturnin-bundle (or a custom executor if specified in the recipe) and then executes it using subprocess.run.

If the recipe’s execution mode is DAEMON, this function utilizes saturnin-daemon start to launch the recipe as a background process, managing its PID file.

Parameters:

  • ctx (Context) – The Typer context, used to get the invoked command name (recipe name).

  • section (Annotated[str | None, <typer.models.OptionInfo object at 0x7092a3106450>]) – Optional name of the main configuration section within the recipe file. If not provided, defaults to ‘service’ or ‘bundle’ based on the recipe’s type.

  • config (Annotated[list[str] | None, <typer.models.OptionInfo object at 0x7092a3107fd0>]) – Optional list of paths to additional .cfg files whose configurations will be layered over the recipe’s base configuration.

  • print_outcome (Annotated[bool, <typer.models.OptionInfo object at 0x7092a3107b10>]) – If True, the final execution outcome of the service(s) will be printed to the console.

  • quiet (Annotated[bool, <typer.models.OptionInfo object at 0x7092a3107ed0>]) – If True, suppresses most console output from the executed service/bundle script.

  • main_thread (Annotated[bool, <typer.models.OptionInfo object at 0x7092a3107bd0>]) – If True and the recipe is for a single service, the service is run in the main thread of the saturnin-service script. This option is ignored for bundle recipes.

Return type:

None