httk.core.project.templates¶

Parse, resolve, and instantiate httk project templates.

Attributes¶

TEMPLATE_MANIFEST

Classes¶

`TemplateParameter`	Describe one template instantiate parameter.
`ProjectTemplate`	Describe a validated project template.
`TemplateInstantiateRequest`	Describe the request received by a template instantiate hook.

Functions¶

`parse_template_manifest`(directory)	Parse and validate one project-template manifest.
`available_templates`()	Return all valid templates from installed plugins, sorted by name and id.
`resolve_template`(selector)	Resolve a template path, qualified plugin selector, or bare template id.
`check_parameters`(template, supplied)	Validate supplied parameters and apply declared defaults.
`instantiate_template`(template, project_root, ...[, ...])	Copy a template into an initialized project and run its optional hook.
`template_instantiate_main`(fn)	Run a template hook function using the v1 JSON stdin/stdout protocol.

Module Contents¶

httk.core.project.templates.TEMPLATE_MANIFEST = 'httk_project_template.toml'[source]¶

class httk.core.project.templates.TemplateParameter[source]¶

Describe one template instantiate parameter.

name: str[source]¶

type: str[source]¶

description: str | None[source]¶

default: object | None[source]¶

has_default: bool[source]¶

class httk.core.project.templates.ProjectTemplate[source]¶

Describe a validated project template.

id: str[source]¶

description: str | None[source]¶

files: tuple[str, Ellipsis][source]¶

instantiate_file: str | None[source]¶

parameters: tuple[TemplateParameter, Ellipsis][source]¶

root: pathlib.Path[source]¶

class httk.core.project.templates.TemplateInstantiateRequest[source]¶

Describe the request received by a template instantiate hook.

template: str[source]¶

parameters: collections.abc.Mapping[str, object][source]¶

project: collections.abc.Mapping[str, object][source]¶

httk.core.project.templates.parse_template_manifest(directory)[source]¶

Parse and validate one project-template manifest.

Parameters:: directory (pathlib.Path) – Locate the template directory.
Returns:: The validated project template.
Raises:: ValueError – If the template directory or manifest is malformed.
Return type:: ProjectTemplate

httk.core.project.templates.available_templates()[source]¶

Return all valid templates from installed plugins, sorted by name and id.

httk.core.project.templates.resolve_template(selector)[source]¶

Resolve a template path, qualified plugin selector, or bare template id.

Parameters:: selector (str) – Select an explicit directory, plugin:id, or bare id.
Returns:: The selected project template.
Raises:: ValueError – If the selector cannot identify exactly one template.
Return type:: ProjectTemplate

httk.core.project.templates.check_parameters(template, supplied)[source]¶

Validate supplied parameters and apply declared defaults.

Parameters:

template (ProjectTemplate) – Validate against this template’s declaration.
supplied (collections.abc.Mapping[str, object]) – Supply user parameter values.

Returns:

Supplied values combined with optional defaults.

Raises:

ValueError – If names or values do not match the declaration.

Return type:

dict[str, object]

httk.core.project.templates.instantiate_template(template, project_root, parameters, *, project_info, timeout=3600.0)[source]¶

Copy a template into an initialized project and run its optional hook.

Parameters:

template (ProjectTemplate) – Instantiate this validated template.
project_root (pathlib.Path) – Initialized project root to populate.
parameters (collections.abc.Mapping[str, object]) – Supply template parameter values.
project_info (collections.abc.Mapping[str, object]) – Supply project metadata for the hook request.
timeout (float) – Limit hook execution time in seconds.

Returns:

Hook notes, or an empty tuple when no notes are returned.

Raises:

ValueError – If validation, copying, or hook execution fails.

Return type:

tuple[str, Ellipsis]

httk.core.project.templates.template_instantiate_main(fn)[source]¶

Run a template hook function using the v1 JSON stdin/stdout protocol.

Parameters:: fn (collections.abc.Callable[[TemplateInstantiateRequest], collections.abc.Mapping[str, object] | None]) – Handle the decoded template instantiate request.
Returns:: Nothing; the response is written as one JSON document.
Return type:: None