saturnin._scripts.commands.site

Saturnin site management commands.

This module provides Typer commands for initializing and managing the Saturnin site environment, including directory creation, configuration file handling, and listing site-specific paths.

Globals

saturnin._scripts.commands.site.app

Typer command group for site management commands.

Parameters:

• args (Any)

• kwargs (Any)

Return type:

Any

Enums

class saturnin._scripts.commands.site._Configs(value)

Bases: Enum

Enumeration of manageable Saturnin configuration files.

FIREBIRD = 'firebird'

LOGGING = 'logging'

MAIN = 'main'

THEME = 'theme'

USER = 'user'

property path: Path

Returns the Path object for the selected configuration file type.

Command functions

saturnin._scripts.commands.site.create_home() → None

Creates the Saturnin ‘home’ subdirectory within the active virtual environment.

This command is typically used to establish a conventional location for Saturnin’s site-specific files when SATURNIN_HOME is not explicitly set and the virtual environment structure is preferred.

### Important:

To have the intended effect on the directory scheme used by initialize, this command should be executed before the initialize command.

Return type:

None

saturnin._scripts.commands.site.initialize(*, new_config: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce45ac750>] = False, yes: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce441c8d0>] = False) → None

Initializes the Saturnin environment and directory structure.

This command creates all standard directories required by Saturnin (for configuration, data, logs, etc.) and generates default configuration files (e.g., saturnin.conf, theme.conf).

#### Important Considerations:

Before running initialize, determine where Saturnin’s directories should reside:

• Central Home Directory: If you want all Saturnin directories to be

located under a specific central path, set the SATURNIN_HOME environment variable to this path before running initialize.

• Virtual Environment Home: If you prefer to keep Saturnin’s home

directory within its virtual environment, first execute the create home command, then run initialize.

• Platform Defaults: If neither SATURNIN_HOME is set nor create home

has been used to create a venv-local home, Saturnin will use platform-specific default locations for its directories.

—

Using the --new-config option will cause existing configuration files to be renamed with a bak extension before new default files are written.

Parameters:

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

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

Return type:

None

saturnin._scripts.commands.site.list_directories() → None

Lists the key directories used by Saturnin and indicates their existence. Emojis: :heavy_check_mark: (exists) / :heavy_multiplication_x: (does not exist)

Return type:

None

saturnin._scripts.commands.site.list_configs() → None

Lists Saturnin’s main configuration files and indicates their existence. Emojis: :heavy_check_mark: (exists) / :heavy_multiplication_x: (does not exist)

Return type:

None

saturnin._scripts.commands.site.list_datafiles() → None

Lists Saturnin’s key data files and indicates their existence. Emojis: :heavy_check_mark: (exists) / :heavy_multiplication_x: (does not exist)

Return type:

None

saturnin._scripts.commands.site.show_config(config_file: ~saturnin._scripts.commands.site.Annotated[~saturnin._scripts.commands.site._Configs, <typer.models.ArgumentInfo object at 0x799ce45a2710>])

Displays the content of a specified Saturnin configuration file.

The content is shown with syntax highlighting appropriate for the file type (e.g., ‘.conf’ files are highlighted as INI/CFG).

Parameters:

config_file (Annotated[_Configs, <typer.models.ArgumentInfo object at 0x799ce45f1090>])

saturnin._scripts.commands.site.edit_config(config_file: ~saturnin._scripts.commands.site.Annotated[~saturnin._scripts.commands.site._Configs, <typer.models.ArgumentInfo object at 0x799ce45af490>])

Opens the specified Saturnin configuration file in an external editor.

The editor used is determined by the EDITOR environment variable or Saturnin’s configured default editor. If changes are saved, the file is updated.

Parameters:

config_file (Annotated[_Configs, <typer.models.ArgumentInfo object at 0x799ce45ae810>])

saturnin._scripts.commands.site.create_config(config_file: ~saturnin._scripts.commands.site.Annotated[~saturnin._scripts.commands.site._Configs, <typer.models.ArgumentInfo object at 0x799ce443bd50>], *, new_config: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x799ce443bed0>] = False)

Creates a specified Saturnin configuration file with its default content.

If the file already exists, it will only be overwritten if --new-config is used (in which case the original is backed up).

Parameters:

• config_file (Annotated[_Configs, <typer.models.ArgumentInfo object at 0x799ce443bf90>])

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

Functions

saturnin._scripts.commands.site.ensure_dir(description: str, path: Path)

Ensures a directory exists, creating it (and any parents) if necessary.

Prints a status message to the console indicating the action taken.

Parameters:

• description (str) – A description of the directory’s purpose (for console output).

• path (Path) – The Path object representing the directory to ensure.

saturnin._scripts.commands.site.ensure_config(path: Path, content: str, new_config: bool)

Creates or updates a configuration file with the given content.

Prints status messages to the console. If new_config is True and the file exists, the original is backed up with a ‘.bak’ suffix before writing.

Parameters:

• path (Path) – The Path object for the configuration file.

• content (str) – The string content to write to the file.

• new_config (bool) – If True, overwrite an existing file (backing it up). If False, do nothing if the file already exists.

saturnin._scripts.commands.site.add_path(table: Table, description: str, path: Path) → None

Adds a row to a Rich Table displaying a path and its existence status.

The row includes the description, an indicator (✔/✖) of whether the path exists, and the string representation of the path.

Parameters:

• table (Table) – The Rich Table instance to which the row will be added.

• description (str) – A textual description of the path.

• path (Path) – The Path object to display and check for existence.

Return type:

None