Models#

Models represents the objects used inside Fabricius, for example, the File model is an object that represent a file we’re about to create.

In this page, you’re able to visit the available methods in our models and freely uses them.

class fabricius.models.file.File(name: str, extension: Optional[str] = None)#

The builder class to initialize a file template. The result (Through the generate() method) is the render of the file’s content. You can “commit” the file to the disk to persist the file’s content.

Parameters:

name (str) – The name of the file.
extension (str) – The extension of the file, without dot, same as name="<name>.<extension>" (Where <name> and <extensions> are the arguments given to the class).

template_content: str | None#: The content of the base template, if set.

name: str#: The name of the file that will be generated.

state: Literal['pending', 'persisted']#: The state of the file.

content: str | None#: The template’s content.

destination: pathlib.Path | None#: The destination of the file, if set.

renderer: type[fabricius.models.renderer.Renderer]#: The renderer to use to generate the file.

data: dict[str, Any]#: The data that will be passed to the renderer.

compute_destination() → Path#

Compute the destination of the file.

Raises:: fabricius.exceptions.MissingRequiredValueError – If the object does not have the property “destination” set. (Use to_directory())
Returns:: The final path.
Return type:: pathlib.Path

from_file(path: str | pathlib.Path) → Self#

Read the content from a file template.

Raises:: FileNotFoundError – If the file was not found.
Parameters:: path (str or pathlib.Path) – The path of the file template.

from_content(content: str) → Self#

Read the content from a string.

Parameters:: content (str) – The template you want to format.

to_directory(directory: str | os.PathLike[str] | pathlib.Path) → Self#

Set the directory where the file will be saved.

Raises:: NotADirectory – The given path exists but is not a directory.
Parameters:: directory (str or pathlib.Path) – Where the file will be stored. Does not include the file’s name.

use_mustache() → Self#: Use chevron (Mustache) to render the template.

use_string_template() → Self#: Use string.Template to render the template.

use_jinja() → Self#: Use Jinja2 to render the template.

with_renderer(renderer: Type[Renderer]) → Self#

Use a custom renderer to render the template.

Parameters:: renderer (Type of fabricius.models.renderer.Renderer) – The renderer to use to format the file. It must be not initialized.

with_data(data: dict[str, Any], *, overwrite: bool = True) → Self#

Add data to pass to the template.

Parameters:

data (fabricius.types.Data) – The data you want to pass to the template.
overwrite (bool) – If the data that already exists should be deleted. If False, the new data will be added on top of the already existing data. Default to True.

fake() → Self#: Set the file to fake the commit. This will ensure that the file does not get stored on the machine upon commit.

restore() → Self#: Set the file to not fake the commit. This will ensure that the file gets stored on the machine upon commit.

Hint

This is the default behavior. It’s only useful to use this method if you have used fake().

generate() → str#

Generate the file’s content.

Raises:: fabricius.exceptions.MissingRequiredValue – If no content to the file were added.
Returns:: The final content of the file.
Return type:: str

commit(*, overwrite: bool = False) → FileCommitResult#

Save the file to the disk.

Parameters:: overwrite (bool) – If a file exist at the given path, shall the overwrite parameter say if the file should be overwritten or not. Default to False.

:raises MissingRequiredValueError <fabricius.exceptions.MissingRequiredValueError>` : If a required value was not set. (Content or destination) :raises fabricius.exceptions.AlreadyCommittedError: If the file has already been saved to the disk. :raises FileExistsError: If the file already exists on the disk and overwrite is set to False. This is different from AlreadyCommittedError because this indicates that the content of the file this generator was never actually saved. :raises OSError: The file’s name is not valid for the OS.

Returns:: A typed dict with information about the created file.
Return type:: fabricius.types.FileCommitResult

class fabricius.models.signal.Signal(*, func_hint: Optional[Callable[[_F], Any]] = None)#

The Listener is the base class used to create listeners of events.

listeners: list[Callable[_F, Any]]#: The list of listeners that are subscribed to this signal.

connect(listener: Callable[[_F], Any]) → None#: Connect a listener to this signal.

disconnect(listener: Callable[[_F], Any]) → None#: Disconnect a listener to this signal.

send(*args: ~typing.~_F, **kwargs: ~typing.~_F) → list[Any]#: Sends the signal to all subscribed listeners.

class fabricius.models.renderer.Renderer(data: dict[str, Any])#

The Renderer is what translate and generates the output of templates. Core of the work.

You must subclass this class and override the render() method, if possible, also add a name.

name: ClassVar[str | None] = None#: The name of the renderer, not necessary, but suggested to add.

data: dict[str, Any]#: A dictionary that contains data passed by the users to pass inside the template.

abstract render(content: str) → str#

This method will process a given string, the template input and return the processed template as a string too.

Parameters:: content (str) – The template
Returns:: The result of the processed template.
Return type:: str

class fabricius.models.template.Template(base_folder: str | os.PathLike[str] | pathlib.Path, renderer: RendererType)#

The Template class represent “a collection of files that, in its whole, represents a project”

The difference between the Template class and a collection of File is that a template assumes all of your files have the same properties. (Requires the same renderer, the same data, etc.)

Typically, a template only use one renderer, and shares the same data across the whole project template.

The Template will assist creating a project, while providing a similar interface of the File model.

Parameters:

base_folder (fabricius.types.PathStrOrPath) – Indication of where the template should be generated.
renderer (Type of fabricius.models.renderer.Renderer) – The renderer to use with the template.

base_folder: Path#: The folder where the template will be generated.

state: Literal['pending', 'failed', 'persisted']#: The state of the template

files: list[fabricius.models.file.File]#: The list of files that will be rendered when committing.

data: dict[str, Any]#: The data to pass to the files.

renderer: RendererType#: The renderer that will be used to generate the files.

add_file(file: File) → Self#

add_files(files: Iterable[File]) → Self#

push_data(data: dict[str, Any]) → Self#

fake() → Self#

restore() → Self#

commit(*, overwrite: bool = False) → list[fabricius.types.FileCommitResult]#