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 plugin and git-installed templates, without running git.
`install_template`(uri)	Fetch and install the template a git URI names.
`uninstall_templates`(selector)	Remove installed git templates by URI or name, without running git.
`resolve_template`(selector)	Resolve a template path, git URI, qualified plugin selector, or bare name.
`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'¶

class httk.core.project.templates.TemplateParameter¶

Describe one template instantiate parameter.

name: str¶

type: str¶

description: str | None¶

default: object | None¶

has_default: bool¶

class httk.core.project.templates.ProjectTemplate¶

Describe a validated project template.

name: str¶

description: str | None¶

files: tuple[str, ...]¶

instantiate_file: str | None¶

parameters: tuple[TemplateParameter, ...]¶

root: pathlib.Path¶

requires: tuple[httk.core.requirements.Requirement, ...] = ()¶

check_requires()¶

Require the template’s [template] requires to be met.

Raises:: RequirementError – If an installed distribution is missing or too old.

class httk.core.project.templates.TemplateInstantiateRequest¶

Describe the request received by a template instantiate hook.

template: str¶

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

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

httk.core.project.templates.parse_template_manifest(directory)¶

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()¶

Return all valid plugin and git-installed templates, without running git.

Returns:: (source, template) pairs sorted by source and name, where the source is the plugin name or the canonical git+ URI.
Return type:: tuple[tuple[str, ProjectTemplate], …]

httk.core.project.templates.install_template(uri)¶

Fetch and install the template a git URI names.

Parameters:

uri (str) – Supply a git+… URI whose member holds httk_project_template.toml.

Returns:

The installed entry; its uri is the canonical pinned URI.

Raises:

RequirementError – If the template’s requires are unmet; no entry is written.
ValueError – If the URI is invalid, git fails, or the template is missing or invalid.

Return type:

httk.core.git_sources.InstalledGitMember

httk.core.project.templates.uninstall_templates(selector)¶

Remove installed git templates by URI or name, without running git.

A pinned URI removes that entry, an unpinned URI every entry of its repository and subdirectory, and a name every entry of the lineage it resolves to. Plugin templates are removed with their plugin instead.

Parameters:: selector (str) – Give a git+… URI or a template name.
Returns:: The removed entries.
Raises:: ValueError – If the selector matches no installed git template, or a name is claimed by several installed git sources.
Return type:: tuple[httk.core.git_sources.InstalledGitMember, …]

httk.core.project.templates.resolve_template(selector)¶

Resolve a template path, git URI, qualified plugin selector, or bare name.

A git+… URI is fetched and installed (see install_template()). A bare name considers plugin templates and installed git templates; it must select exactly one of them. The selected template’s requires, and those of the plugin providing it, are checked before it is returned.

Parameters:

selector (str) – Select an explicit directory, git+… URI, plugin:name, or bare name.

Returns:

The selected project template.

Raises:

RequirementError – If the template’s or its plugin’s requirements are unmet.
ValueError – If the selector cannot identify exactly one template.

Return type:

ProjectTemplate

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

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)¶

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:

RequirementError – If the template’s requires are unmet; nothing is copied.
ValueError – If validation, copying, or hook execution fails.

Return type:

tuple[str, …]

httk.core.project.templates.template_instantiate_main(fn)¶

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