pyfcstm.template

Built-in template asset management for pyfcstm.

This module provides the runtime-facing API for packaged built-in templates. The repository keeps editable template sources under the top-level templates/ directory, while packaged distributions ship zipped template assets under pyfcstm.template together with an index.json metadata file.

The functions in this module intentionally do only three things:

• list the built-in template names available in the installed package

• return metadata for one packaged template

• extract one packaged template into a normal directory so the existing pyfcstm.render.StateMachineCodeRenderer can consume it

This separation keeps built-in template distribution independent from the renderer itself. The module does not parse DSL code, does not render output files directly, and does not implement any template-specific business logic.

The module contains the following public components:

• list_templates() - Return the names of packaged built-in templates

• has_template() - Check whether one built-in template is available

• get_template_info() - Return metadata for one packaged template

• extract_template() - Extract one packaged template into a directory

Example:

>>> from pyfcstm.template import list_templates, extract_template
>>> isinstance(list_templates(), list)
True

Note

The packaged template assets are generated from repository-root template sources during the template packaging step. This module only reads the packaged results already present inside pyfcstm.

__all__

pyfcstm.template.__all__ = ['list_templates', 'has_template', 'get_template_info', 'extract_template']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

list_templates

pyfcstm.template.list_templates() → List[str]

Return the names of packaged built-in templates.

The names are read from the packaged index.json file and returned in the stored order. The result is suitable for CLI validation, documentation display, or built-in template discovery.

Returns:

Built-in template names available in the installed package.

Return type:

List[str]

Raises:

• FileNotFoundError – If the packaged template index is missing.

• json.JSONDecodeError – If the packaged template index is invalid JSON.

Example:

>>> from pyfcstm.template import list_templates
>>> templates = list_templates()
>>> isinstance(templates, list)
True

has_template

pyfcstm.template.has_template(name: str) → bool

Check whether a packaged built-in template exists.

Parameters:

name (str) – Built-in template name to check.

Returns:

True if the template exists, False otherwise.

Return type:

bool

Raises:

• FileNotFoundError – If the packaged template index is missing.

• json.JSONDecodeError – If the packaged template index is invalid JSON.

Example:

>>> from pyfcstm.template import has_template
>>> has_template('python') in (True, False)
True

get_template_info

pyfcstm.template.get_template_info(name: str) → Dict[str, object]

Return metadata for one packaged built-in template.

The returned dictionary is a shallow copy of the metadata entry stored in index.json. Callers may modify the returned mapping without affecting the packaged metadata loaded by subsequent calls.

Parameters:

name (str) – Built-in template name.

Returns:

Metadata dictionary for the requested built-in template.

Return type:

Dict[str, object]

Raises:

• LookupError – If the named template does not exist.

• FileNotFoundError – If the packaged template index is missing.

• json.JSONDecodeError – If the packaged template index is invalid JSON.

Example:

>>> from pyfcstm.template import get_template_info
>>> info = get_template_info('python')  
>>> info['name']  
'python'

extract_template

pyfcstm.template.extract_template(name: str, output_dir: str) → str

Extract a packaged built-in template into output_dir.

This function normally unpacks the zip archive referenced by the template metadata entry and returns the extracted template directory path. In a development repository checkout, the packaged zip asset may be absent while the editable source template still exists under the repository-root templates/ directory. In that case, the source template directory is copied into output_dir instead.

The extracted or copied directory is intended to be passed directly to pyfcstm.render.StateMachineCodeRenderer.

Parameters:

• name (str) – Built-in template name.

• output_dir (str) – Target directory for extraction.

Returns:

Extracted template directory path.

Return type:

str

Raises:

• LookupError – If the template does not exist.

• FileNotFoundError – If neither the packaged archive nor a development source template directory can be found, or if the extracted root directory is not present after unpacking.

• zipfile.BadZipFile – If the packaged archive is not a valid zip file.

Example:

>>> from tempfile import TemporaryDirectory
>>> from pyfcstm.template import extract_template
>>> with TemporaryDirectory() as td:
...     path = extract_template('python', td)  
...     isinstance(path, str)  
True