httk.core.plugins

Re-export the httk plugin APIs.

Submodules

Attributes

PLUGIN_MANIFEST

PLUGIN_METADATA

Classes

InstalledPlugin

Describe one installed plugin and its installer metadata.

PluginManifest

Describe a validated plugin manifest.

PluginProgram

Describe one declared plugin program.

Functions

build_plugin(name)

Build and publish the declared programs of an installed plugin.

install_plugin(source, *[, force])

Install one plugin from an existing local directory.

uninstall_plugin(name)

Remove an installed plugin and its still-owned shims.

installed_plugins()

Read all valid installed plugins.

plugin_program(name, program)

Return the absolute path of an installed plugin program.

plugin_root(name)

Return the root of an installed plugin.

plugins_home()

Return the installed plugin directory.

shims_home()

Return the plugin shim directory.

parse_plugin_manifest(directory)

Parse and validate one plugin manifest.

Package Contents

httk.core.plugins.build_plugin(name)

Build and publish the declared programs of an installed plugin.

httk.core.plugins.install_plugin(source, *, force=False)

Install one plugin from an existing local directory.

source_sha256 is pre-build provenance: build output and the build log may change the installed tree after this digest is recorded.

Parameters:

  • source (str | pathlib.Path) – Supply the local plugin directory.

  • force (bool) – Replace an installed plugin with the same name.

Returns:

The installed plugin.

Raises:

  • RequirementError – If the plugin’s requires are unmet; nothing is placed.

  • ValueError – If the source or plugin is invalid or cannot be built.

Return type:

httk.core.plugins.installed.InstalledPlugin

httk.core.plugins.uninstall_plugin(name)

Remove an installed plugin and its still-owned shims.

httk.core.plugins.PLUGIN_MANIFEST = 'httk_plugin.toml'
httk.core.plugins.PLUGIN_METADATA = 'plugin.json'
class httk.core.plugins.InstalledPlugin

Describe one installed plugin and its installer metadata.

Parameters:

  • name – Name the installed plugin directory.

  • root – Locate the installed plugin directory.

  • manifest – Provide the parsed plugin.json object.

  • metadata – Provide the parsed plugin.json object.

name: str
root: pathlib.Path
manifest: httk.core.plugins.manifest.PluginManifest
metadata: collections.abc.Mapping[str, object]
check_requires()

Require the plugin’s [plugin] requires to be met before a member is used.

Every consumer of an installed plugin’s members (templates, workflows, programs) calls this one choke point.

Raises:

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

httk.core.plugins.installed_plugins()

Read all valid installed plugins.

Returns:

Valid installed plugins in directory-name order.

Return type:

tuple[InstalledPlugin, …]

httk.core.plugins.plugin_program(name, program)

Return the absolute path of an installed plugin program.

Parameters:

  • name (str) – Name the installed plugin.

  • program (str) – Name the declared program.

Returns:

The program’s absolute path.

Raises:
Return type:

pathlib.Path

httk.core.plugins.plugin_root(name)

Return the root of an installed plugin.

Parameters:

name (str) – Name the installed plugin directory.

Returns:

The installed plugin directory.

Raises:

ValueError – If the plugin is not installed.

Return type:

pathlib.Path

httk.core.plugins.plugins_home()

Return the installed plugin directory.

Returns:

The plugin data directory.

Return type:

pathlib.Path

httk.core.plugins.shims_home()

Return the plugin shim directory.

Returns:

The shim data directory.

Return type:

pathlib.Path

class httk.core.plugins.PluginManifest

Describe a validated plugin manifest.

Parameters:

  • name – Name the plugin.

  • description – Describe the plugin, when supplied.

  • templates – Name project-template directories.

  • workflows – Name workflow-package directories.

  • programs – Describe declared utility programs.

  • build – Describe the optional build.

  • root – Locate the parsed plugin directory.

  • requires – Give the minimum-version requirements on installed distributions.

name: str
description: str | None
templates: tuple[str, ...]
workflows: tuple[str, ...]
programs: tuple[PluginProgram, ...]
build: httk.core.building.BuildSpec | None
root: pathlib.Path
requires: tuple[httk.core.requirements.Requirement, ...] = ()
class httk.core.plugins.PluginProgram

Describe one declared plugin program.

Parameters:

  • name – Name the program and its shim.

  • file – Name the program member relative to the plugin root.

  • description – Describe the program, when supplied.

name: str
file: str
description: str | None
httk.core.plugins.parse_plugin_manifest(directory)

Parse and validate one plugin manifest.

Parameters:

directory (pathlib.Path) – Locate the plugin directory.

Returns:

The validated plugin manifest.

Raises:

ValueError – If the plugin directory or manifest is malformed.

Return type:

PluginManifest