Settings

sereto.models.settings

ConvertRecipe

Bases: RenderRecipe

Recipe for converting between file formats using RenderTools.

Attributes:

Name	Type	Description
name		name of the recipe
input_format	FileFormat	input file format
tools	FileFormat	list of RenderTool names to run

Source code in sereto/models/settings.py

class ConvertRecipe(RenderRecipe):
    """Recipe for converting between file formats using `RenderTool`s.

    Attributes:
        name: name of the recipe
        input_format: input file format
        tools: list of `RenderTool` names to run
    """

    input_format: FileFormat
    output_format: FileFormat

    @field_validator("input_format", "output_format", mode="before")
    @classmethod
    def load_file_format(cls, v: Any) -> FileFormat:
        match v:
            case FileFormat():
                return v
            case str():
                return FileFormat(v)
            case _:
                raise ValueError("invalid type for FileFormat")

Plugins

Bases: SeretoBaseModel

Plugins settings.

Attributes:

Name	Type	Description
enabled	bool	whether plugins are enabled
directory	str	path to the directory containing plugins (%TEMPLATES% will be replaced with the templates path`)

Source code in sereto/models/settings.py

class Plugins(SeretoBaseModel):
    """Plugins settings.

    Attributes:
        enabled: whether plugins are enabled
        directory: path to the directory containing plugins (`%TEMPLATES%` will be replaced with the templates path`)
    """

    enabled: bool = False
    directory: str = "%TEMPLATES%/plugins"

RenderRecipe

Bases: SeretoBaseModel

Recipe for rendering and converting files using RenderTools.

Attributes:

Name	Type	Description
name	str	name of the recipe
tools	Annotated[list[str], MinLen(1)]	list of RenderTool names to run

Source code in sereto/models/settings.py

class RenderRecipe(SeretoBaseModel):
    """Recipe for rendering and converting files using `RenderTool`s.

    Attributes:
        name: name of the recipe
        tools: list of `RenderTool` names to run
    """

    name: str
    tools: Annotated[list[str], MinLen(1)]

RenderTool

Bases: SeretoBaseModel

Commands used in recipes.

Attributes:

Name	Type	Description
name	str	name of the tool
command	str	command to run
args	list[str]	list of arguments to pass to the command

Source code in sereto/models/settings.py

class RenderTool(SeretoBaseModel):
    """Commands used in recipes.

    Attributes:
        name: name of the tool
        command: command to run
        args: list of arguments to pass to the command
    """

    name: str
    command: str
    args: list[str]

    @validate_call
    def run(
        self, cwd: DirectoryPath | None = None, input: bytes | None = None, replacements: dict[str, str] | None = None
    ) -> bytes:
        # Prepare the command
        command = [self.command] + self.args
        if replacements is not None:
            command = replace_strings(text=command, replacements=replacements)
        Console().log(
            Markdown(
                dedent(f"""\
                    Running command:
                    ```bash
                    {escape(' '.join(command))}
                    ```
                """)
            )
        )
        Console().line()

        # Run the command and measure the execution time
        start_time = time.time()
        result = subprocess.run(command, cwd=cwd, input=input, capture_output=True)
        end_time = time.time()

        # Check if the command failed
        if result.returncode != 0:
            Console().log(
                Markdown(f"""\
Command failed ({result.returncode}):
```text
{escape(result.stderr.decode("utf-8"))}
```
""")
            )
            Console().line()
            raise SeretoCalledProcessError("command execution failed")

        # Report success
        Console().log(f"Command finished in {end_time - start_time:.2f} s")

        # Return the command output
        return result.stdout

Settings

Bases: SeretoBaseSettings

Global settings:

Attributes:

Name	Type	Description
projects_path	DirectoryPath	path to the directory containing all projects
templates_path	DirectoryPath	path to the directory containing templates
render	Render	rendering settings
categories	TypeCategories	supported categories - list of strings (2-20 lower-alpha characters; also dash and underscore is possible in all positions except the first and last one)

Raises:

Type	Description
SeretoPathError	If the file is not found or permission is denied.
SeretoValueError	If the JSON file is invalid.

Source code in sereto/models/settings.py

class Settings(SeretoBaseSettings):
    """Global settings:

    Attributes:
        projects_path: path to the directory containing all projects
        templates_path: path to the directory containing templates
        render: rendering settings
        categories: supported categories - list of strings (2-20 lower-alpha characters; also dash and underscore is
            possible in all positions except the first and last one)

    Raises:
        SeretoPathError: If the file is not found or permission is denied.
        SeretoValueError: If the JSON file is invalid.
    """

    projects_path: DirectoryPath
    templates_path: DirectoryPath
    render: Render = Field(default=DEFAULT_RENDER_CONFIG)
    categories: TypeCategories = Field(default=DEFAULT_CATEGORIES)
    plugins: Plugins = Field(default_factory=Plugins)

    @staticmethod
    def get_path() -> Path:
        return Path(get_app_dir(app_name="sereto")) / "settings.json"

    @classmethod
    def load_from(cls, file: FilePath) -> Self:
        try:
            return cls.model_validate_json(file.read_bytes())
        except FileNotFoundError:
            raise SeretoPathError(f"file not found at '{file}'") from None
        except PermissionError:
            raise SeretoPathError(f"permission denied for '{file}'") from None
        except ValidationError as e:
            raise SeretoValueError(f"invalid settings\n\n{e}") from e