Skip to content

Settings

sereto.models.settings

ConvertRecipe

Bases: RenderRecipe

Recipe for converting between file formats using RenderTools.

Attributes:

Name Type Description
name str

name of the recipe
tools Annotated[list[str], MinLen(1)]

list of RenderTool names to run
input_format FileFormat

input file format
output_format FileFormat

output file format
Source code in sereto/models/settings.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class ConvertRecipe(RenderRecipe):
    """Recipe for converting between file formats using `RenderTool`s.

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

    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 
310
311
312
313
314
315
316
317
318
319
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"

Render

Bases: SeretoBaseModel

Rendering settings.

Attributes:

Name Type Description
report_recipes Annotated[list[RenderRecipe], MinLen(1)]

list of RenderRecipes for rendering reports
finding_group_recipes Annotated[list[RenderRecipe], MinLen(1)]

list of RenderRecipes for rendering finding groups
sow_recipes Annotated[list[RenderRecipe], MinLen(1)]

list of RenderRecipes for rendering SoWs
target_recipes Annotated[list[RenderRecipe], MinLen(1)]

list of RenderRecipes for rendering targets
convert_recipes Annotated[list[ConvertRecipe], MinLen(1)]

list of ConvertRecipes for converting between file formats
tools Annotated[list[RenderTool], MinLen(1)]

list of RenderTools used in recipes
Source code in sereto/models/settings.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
class Render(SeretoBaseModel):
    """Rendering settings.

    Attributes:
        report_recipes: list of `RenderRecipe`s for rendering reports
        finding_group_recipes: list of `RenderRecipe`s for rendering finding groups
        sow_recipes: list of `RenderRecipe`s for rendering SoWs
        target_recipes: list of `RenderRecipe`s for rendering targets
        convert_recipes: list of `ConvertRecipe`s for converting between file formats
        tools: list of `RenderTool`s used in recipes
    """

    report_recipes: Annotated[list[RenderRecipe], MinLen(1)]
    finding_group_recipes: Annotated[list[RenderRecipe], MinLen(1)]
    sow_recipes: Annotated[list[RenderRecipe], MinLen(1)]
    target_recipes: Annotated[list[RenderRecipe], MinLen(1)]
    convert_recipes: Annotated[list[ConvertRecipe], MinLen(1)]
    tools: Annotated[list[RenderTool], MinLen(1)]

    @model_validator(mode="after")
    def render_validator(self) -> Self:
        for recipe in self.report_recipes + self.finding_group_recipes + self.sow_recipes:
            if not all(tool in [t.name for t in self.tools] for tool in recipe.tools):
                raise ValueError(f"unknown tools in recipe {recipe.name!r}")
        tool_names = [t.name for t in self.tools]
        if len(tool_names) != len(set(tool_names)):
            raise ValueError("tools with duplicate name detected")
        return self

    @validate_call
    def get_report_recipe(self, name: str | None) -> RenderRecipe:
        """Get a report recipe by name.

        Args:
            name: The name of the recipe to get. If None, the first recipe is returned.
        """
        if name is None:
            return self.report_recipes[0]

        if len(res := [r for r in self.report_recipes if r.name == name]) != 1:
            raise SeretoValueError(f"no report recipe found with name {name!r}")

        return res[0]

    @validate_call
    def get_finding_group_recipe(self, name: str | None) -> RenderRecipe:
        """Get a finding group recipe by name.

        Args:
            name: The name of the recipe to get. If None, the first recipe is returned.
        """
        if name is None:
            return self.finding_group_recipes[0]

        if len(res := [r for r in self.finding_group_recipes if r.name == name]) != 1:
            raise SeretoValueError(f"no finding recipe found with name {name!r}")

        return res[0]

    @validate_call
    def get_sow_recipe(self, name: str | None) -> RenderRecipe:
        """Get a SoW recipe by name.

        Args:
            name: The name of the recipe to get. If None, the first recipe is returned.
        """
        if name is None:
            return self.sow_recipes[0]

        if len(res := [r for r in self.sow_recipes if r.name == name]) != 1:
            raise SeretoValueError(f"no SoW recipe found with name {name!r}")

        return res[0]

    @validate_call
    def get_target_recipe(self, name: str | None) -> RenderRecipe:
        """Get a target recipe by name.

        Args:
            name: The name of the recipe to get. If None, the first recipe is returned.
        """
        if name is None:
            return self.target_recipes[0]

        if len(res := [r for r in self.target_recipes if r.name == name]) != 1:
            raise SeretoValueError(f"no target recipe found with name {name!r}")

        return res[0]

    @validate_call
    def get_convert_recipe(
        self, name: str | None, input_format: FileFormat, output_format: FileFormat
    ) -> ConvertRecipe:
        """Get a convert recipe by name, input format, and output format.

        Args:
            name: The name of the recipe to get. If None, the first matching recipe is returned.
            input_format: The input file format.
            output_format: The output file format.
        """
        acceptable_recipes = [
            r for r in self.convert_recipes if r.input_format == input_format and r.output_format == output_format
        ]
        if len(acceptable_recipes) == 0:
            raise SeretoValueError(f"no convert recipe found for {input_format.value} -> {output_format.value}")

        if name is None:
            return acceptable_recipes[0]

        if len(res := [r for r in acceptable_recipes if r.name == name]) != 1:
            raise SeretoValueError(
                f"no convert recipe found for {input_format.value} -> {output_format.value} with name {name!r}"
            )

        return res[0]

get_convert_recipe(name, input_format, output_format)

Get a convert recipe by name, input format, and output format.

Parameters:

Name Type Description Default
name str | None

The name of the recipe to get. If None, the first matching recipe is returned.

 required
input_format FileFormat

The input file format.

 required
output_format FileFormat

The output file format.

 required
Source code in sereto/models/settings.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
@validate_call
def get_convert_recipe(
    self, name: str | None, input_format: FileFormat, output_format: FileFormat
) -> ConvertRecipe:
    """Get a convert recipe by name, input format, and output format.

    Args:
        name: The name of the recipe to get. If None, the first matching recipe is returned.
        input_format: The input file format.
        output_format: The output file format.
    """
    acceptable_recipes = [
        r for r in self.convert_recipes if r.input_format == input_format and r.output_format == output_format
    ]
    if len(acceptable_recipes) == 0:
        raise SeretoValueError(f"no convert recipe found for {input_format.value} -> {output_format.value}")

    if name is None:
        return acceptable_recipes[0]

    if len(res := [r for r in acceptable_recipes if r.name == name]) != 1:
        raise SeretoValueError(
            f"no convert recipe found for {input_format.value} -> {output_format.value} with name {name!r}"
        )

    return res[0]

get_finding_group_recipe(name)

Get a finding group recipe by name.

Parameters:

Name Type Description Default
name str | None

The name of the recipe to get. If None, the first recipe is returned.

 required
Source code in sereto/models/settings.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
@validate_call
def get_finding_group_recipe(self, name: str | None) -> RenderRecipe:
    """Get a finding group recipe by name.

    Args:
        name: The name of the recipe to get. If None, the first recipe is returned.
    """
    if name is None:
        return self.finding_group_recipes[0]

    if len(res := [r for r in self.finding_group_recipes if r.name == name]) != 1:
        raise SeretoValueError(f"no finding recipe found with name {name!r}")

    return res[0]

get_report_recipe(name)

Get a report recipe by name.

Parameters:

Name Type Description Default
name str | None

The name of the recipe to get. If None, the first recipe is returned.

 required
Source code in sereto/models/settings.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@validate_call
def get_report_recipe(self, name: str | None) -> RenderRecipe:
    """Get a report recipe by name.

    Args:
        name: The name of the recipe to get. If None, the first recipe is returned.
    """
    if name is None:
        return self.report_recipes[0]

    if len(res := [r for r in self.report_recipes if r.name == name]) != 1:
        raise SeretoValueError(f"no report recipe found with name {name!r}")

    return res[0]

get_sow_recipe(name)

Get a SoW recipe by name.

Parameters:

Name Type Description Default
name str | None

The name of the recipe to get. If None, the first recipe is returned.

 required
Source code in sereto/models/settings.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
@validate_call
def get_sow_recipe(self, name: str | None) -> RenderRecipe:
    """Get a SoW recipe by name.

    Args:
        name: The name of the recipe to get. If None, the first recipe is returned.
    """
    if name is None:
        return self.sow_recipes[0]

    if len(res := [r for r in self.sow_recipes if r.name == name]) != 1:
        raise SeretoValueError(f"no SoW recipe found with name {name!r}")

    return res[0]

get_target_recipe(name)

Get a target recipe by name.

Parameters:

Name Type Description Default
name str | None

The name of the recipe to get. If None, the first recipe is returned.

 required
Source code in sereto/models/settings.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
@validate_call
def get_target_recipe(self, name: str | None) -> RenderRecipe:
    """Get a target recipe by name.

    Args:
        name: The name of the recipe to get. If None, the first recipe is returned.
    """
    if name is None:
        return self.target_recipes[0]

    if len(res := [r for r in self.target_recipes if r.name == name]) != 1:
        raise SeretoValueError(f"no target recipe found with name {name!r}")

    return res[0]

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 
87
88
89
90
91
92
93
94
95
96
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 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
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)
plugins Plugins

plugins settings

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 
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
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)
        plugins: plugins settings

    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