Boilerplate Metadata#

Prept boilerplate data is stored in preptconfig.json file. The classes documented provide a rich interface to interact with (i.e. read and dynamically manipulate) this file.

class prept.BoilerplateInfo(name: str, path: Path, installed: bool = False, summary: str | None = None, version: Version | str | None = None, ignore_paths: list[str] | None = None, default_generate_directory: str | None = None, template_provider: str | None = None, template_provider_params: dict[str, Any] | None = None, template_files: list[str] | None = None, template_paths: list[str] | None = None, template_variables: dict[str, dict[str, Any]] | None = None, allow_extra_variables: bool = False, variable_input_mode: Literal['all', 'required_only', 'optional_only', 'none'] = 'all', engine: GenerationEngine | str | None = None)#

Represents a boilerplate.

This is a wrapper class for information stored in preptconfig.json.

property path: Path#

The pathlib.Path pointing towards this boilerplate.

Note that this is the path where the boilerplate configuration file is located, not the generation path.

property name: str#

The name of boilerplate.

Boilerplate names must pass the following set of rules:

  • Consists of alphanumeric, hyphens, and underscores characters.

  • Must begin with a letter or underscore.

  • Names are not case-sensitive.

property summary: str | None#

A summary or brief describing the boilerplate.

This attribute can be set to None or null in preptconfig.json which is the default setting.

property version: Version | None#

The version of boilerplate.

If provided, version must follow the specification described in PEP 440: https://peps.python.org/pep-0440/

This attribute can be set to None or null in preptconfig.json which is the default setting.

property ignore_paths: list[str]#

List of paths that are not included in code generated from boilerplate.

This option is useful in ignoring any irrelevant paths such as .git. Note that Prept automatically ignores boilerplate configuration file regardless of the value of this attribute.

This attribute can be set to None or null in preptconfig.json to include every file and directory which is the default setting.

property default_generate_directory: str#

The default directory that boilerplate generates code in.

This directory is used (or created) if user does not specify -O in “prept new” command.

If not provided or is None, defaults to the name of boilerplate at the time of generation.

property template_provider: type[TemplateProvider] | None#

The name of template provider for this boilerplate, if any.

Template providers act as middleware for processing template files. See documentation of TemplateProvider for more information.

By default, no template provider is set. Prept provides two built-in template providers by default:

  • string-sub for $-substitutions

  • jinja2 based on Jinja templates (requires Jinja2 installed)

This option can take name of third party template providers as well using : to separate module name and template provider name. For example, foobar::baz means baz template provider from the foobar module or package.

Changed in version 0.2.0: This function now takes spec in standard Python module format i.e. module_name:object instead of module_name::object.

property template_provider_params: dict[str, Any]#

The keyword parameters passed to the constructor of template provider.

This is useful for passing extra metadata to a template provider that can be used to modify its behavior.

property template_files: list[str]#

List of file paths (as patterns) that are templates.

These files are processed by the given template provider which must also be set for this option to have any effect.

Note that this is a list of gitignore like patterns similar to ignore_paths setting so it is possible to include/exclude all files at a specific path.

property template_paths: list[str]#

The paths which are treated as templates.

These paths are passed to template provider’s process_path() method and all file name or directory names are processed, injecting any variable values where placeholders are present.

This is not the same as template_files which are the files whose content is processed, not path.

Added in version 0.2.0.

property allow_extra_variables: bool#

Whether arbitrary variables that are not in template_variables are allowed.

This is false by default. If set to true, arbitrary variables are allowed through the -V option in prept new command.

property variable_input_mode: str#

The mode of input of variables.

This determines the variables that are prompted to be input after prept new is ran.

There are three possible values:

  • all (default): Prompt input for all variables, including required and optional.

  • required_only: Prompt input for only required variables.

  • optional_only: Prompt input for only optional variables.

  • none: Disable variables input.

In the case of optional_only and none, required variables must be provided using the prept new -V option otherwise an error is raised.

Added in version 0.2.0.

property engine: GenerationEngine | None#

Generation engine for dynamic generation.

This takes the engine path in the following format module:engine_instance where module is name of a Python module that contains engine instance and engine_instance is name of object from the module that is an instance of GenerationEngine.

classmethod from_path(path: Path | str) → Self#

Loads boilerplate information from its path.

Raises ConfigNotFound or InvalidConfig if boilerplate configuration does not exist or is invalid, respectively.

Parameters:

path (pathlib.Path | str) – The path to boilerplate directory.

Returns:

The loaded boilerplate.

Return type:

BoilerplateInfo

classmethod from_installation(name: str) → Self#

Loads boilerplate from the installation.

Raises ConfigNotFound or InvalidConfig if boilerplate configuration does not exist or is invalid, respectively. If boilerplate does not exist, then BoilerplateNotFound is raised.

Parameters:

name (str) – The name of boilerplate.

Returns:

The loaded boilerplate.

Return type:

BoilerplateInfo

classmethod resolve(value: Any) → Self#

Resolves a boilerplate from given value.

The resolution order is as follows:

  • The passed value is first tested as path and if the path exists, boilerplate is loaded from this path if possible.

  • If path resolution fails, boilerplate is loaded from installation.

If boilerplate cannot be resolved through any step, the BoilerplateNotFound error is raised.

Returns:

The loaded boilerplate.

Return type:

BoilerplateInfo

dump() → dict[str, Any]#

Returns the boilerplate in raw data form.

The result is compatible with the preptconfig.json schema.

save() → None#

Saves the boilerplate configuration.

If configuration is not already present (boilerplate is not initialized), it is saved hence initializing the boilerplate.

Template Variables#

Template variables are defined in preptconfig.json and their values are provided at generation time. These variables are injected into template files by the template providers.

class prept.TemplateVariable(boilerplate: BoilerplateInfo, name: str, summary: str | None = None, required: bool = True, default: Any = None)#

Wrapper class around template variable structure.

These are the objects in values of template_variables key in preptconfig.json.

property name: str#

The name of template variable.

Variable names must pass the following set of rules:

  • Consists of alphanumeric and underscores characters.

  • Must begin with a letter or underscore.

  • Names are case-sensitive.

property summary: str | None#

A summary or brief describing the variable.

This can be set to None or null in preptconfig.json which is the default setting.

property required: bool#

Whether the variable is required.

By default, variables are required.

property default: Any#

The default value of this variable.

This is the value that is assigned to variable if no value is provided to it at the time of generation. If set to None/null, no default is set.

If this option is set (non-null), required is automatically determined as false regardless of its user set value, if any.