cement.core.template

Cement core template module.

class cement.core.template.TemplateHandler(*args: Any, **kwargs: Any)

Bases: TemplateInterface, Handler

Base class that all template implementations should sub-class from. Keyword arguments passed to this class will override meta-data options.

class Meta

Bases: Meta

exclude: List[str] = None

List of file patterns to exclude (copy but not render as template)

ignore: List[str] = None

List of file patterns to ignore completely (not copy at all)

interface: str = 'template'

The interface that this handler implements.

label: str = None

Unique identifier (str), used internally.

copy(src: str, dest: str, data: Dict[str, Any], force: bool = False, exclude: List[str] | None = None, ignore: List[str] | None = None) → bool

Render src directory as template, including directory and file names, and copy to dest directory.

Parameters:

• src (str) – The source directory path.

• dest (str) – The destination directory path.

• data (dict) – The data dictionary to interpolate in the template.

• force (bool) – Whether to overwrite existing files.

• exclude (list) – List of regular expressions to match files that should only be copied, and not rendered as template.

• ignore (list) – List of regular expressions to match files that should be completely ignored and not copied at all.

Returns:

Returns True if the copy completed successfully.

Return type:

bool

Raises:

AssertionError – If the src template directory path does not exists, and when a dest file already exists and force is not True.

load(template_path: str) → Tuple[str | bytes, str, str | None]

Loads a template file first from self.app._meta.template_dirs and secondly from self.app._meta.template_module. The template_dirs have presedence.

Parameters:

template_path (str) – The secondary path of the template after either template_module or template_dirs prefix (set via App.Meta)

Returns:

The content of the template (str), the type of template (str: directory, or module), and the path (str) of the directory or module)

Return type:

tuple

Raises:

cement.core.exc.FrameworkError – If the template does not exist in either the template_module or template_dirs.

render(content: str | bytes, data: Dict[str, Any]) → str | None

Render content as template using using the data dictionary.

Parameters:

• content (str) – The content to render.

• data (dict) – The data dictionary to interpolate in the template.

Returns:

The rendered content, or None if nothing is rendered.

Return type:

str, None

class cement.core.template.TemplateInterface(**kw: Any)

Bases: Interface

This class defines the Template Interface. Handlers that implement this interface must provide the methods and attributes defined below. In general, most implementations should sub-class from the provided TemplateHandler base class as a starting point.

class Meta

Bases: Meta

Handler meta-data.

interface: str = 'template'

The string identifier of the interface

abstractmethod copy(src: str, dest: str, data: Dict[str, Any]) → bool

Render the src directory path, and copy to dest. This method must render directory and file names as template content, as well as the contents of files.

Parameters:

• src (str) – The source template directory path.

• dest (str) – The destination directory path.

• data (dict) – The data dictionary to render with template.

Returns:

Returns True if the copy completed successfully.

Return type:

bool

abstractmethod load(path: str) → Tuple[str | bytes, str, str | None]

Loads a template file first from self.app._meta.template_dirs and secondly from self.app._meta.template_module. The template_dirs have presedence.

Parameters:

path (str) – The secondary path of the template after either template_module or template_dirs prefix (set via App.Meta)

Returns:

The content of the template (str), the type of template (str: directory, or module), and the path (str) of the directory or module)

Return type:

tuple

Raises:

cement.core.exc.FrameworkError – If the template does not exist in either the template_module or template_dirs.

abstractmethod render(content: str, data: Dict[str, Any]) → str | None

Render content as a template using the data dict.

Parameters:

• content (str) – The content to be rendered as a template.

• data (dict) – The data dictionary to render with template.

Returns:

The rendered template string, or None if nothing is rendered.

Return type:

str, None