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 0x799ce4644290>], section: ~types.Annotated[str | None, <typer.models.OptionInfo object at 0x799ce462fed0>] = None, *, raw: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce4664590>] = 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 0x799ce4665310>])

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

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

saturnin._scripts.commands.recipes.edit_recipe(recipe_name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x799ce46c17d0>])[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 0x799ce46c0290>])

saturnin._scripts.commands.recipes.create_recipe(recipe_name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x799ce46c0790>], components: ~typing.Annotated[list[str], <typer.models.ArgumentInfo object at 0x799ce46c08d0>], *, plain: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce46c2290>] = 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 0x799ce46c1290>])

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

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

saturnin._scripts.commands.recipes.install_recipe(recipe_file: ~types.Annotated[~pathlib.Path | None, <typer.models.OptionInfo object at 0x799ce46c1dd0>] = None, application: ~types.Annotated[str | None, <typer.models.OptionInfo object at 0x799ce46c0fd0>] = None, recipe_name: ~types.Annotated[str | None, <typer.models.OptionInfo object at 0x799ce4790810>] = 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 0x799ce4585050>])

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

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

saturnin._scripts.commands.recipes.uninstall_recipe(recipe_name: ~types.Annotated[str | None, <typer.models.ArgumentInfo object at 0x799ce46e3cd0>] = None, save_to: ~types.Annotated[~pathlib.Path | None, <typer.models.OptionInfo object at 0x799ce46e3e50>] = 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 0x799ce46e2c10>])

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

saturnin._scripts.commands.recipes.run_recipe(ctx: ~typer.models.Context, section: ~types.Annotated[str | None, <typer.models.OptionInfo object at 0x799ce46ffd10>] = None, config: ~types.Annotated[list[str] | None, <typer.models.OptionInfo object at 0x799ce4584d10>] = None, *, print_outcome: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce4597e10>] = False, quiet: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce451e6d0>] = False, main_thread: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce451db90>] = 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 0x799ce450cd90>]) – 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 0x799ce450cf10>]) – 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 0x799ce450d1d0>]) – If True, the final execution outcome of the service(s) will be printed to the console.

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

  • main_thread (Annotated[bool, <typer.models.OptionInfo object at 0x799ce450d710>]) – 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