httk.workflow.configuration

Manage XDG configuration for workflow commands.

The per-user configuration and data directory functions are provided by httk.core.userdirs and re-exported here for workflow callers. Operator identity — signing keys, named identities, and signatures — lives in httk.core.identity; the workflow configuration below holds only machine-level settings such as machine_names.

Attributes

CONFIG_FORMAT
CONFIG_FORMAT_VERSION
CONFIG_KEYS

Classes

ConfigKey

Describe one member the user configuration is allowed to carry.

Functions

settable_config_keys()	Return the configuration keys config set accepts, in order.
remotes_home()	Return where this user's remote definitions live.
launchers_home()	Return where this user's manager launcher definitions live.
config_path()	Return the path of this user's configuration file.
read_config()	Read the user configuration, returning an empty mapping if absent.
machine_names()	Return the configured names by which this machine is addressed.
write_config(values)	Write a versioned user configuration.
set_config_key(key, value)	Set one registered configuration key and return the written path.
unset_config_key(key)	Remove one registered configuration key and return the written path.
import_v1_configuration([source])	Import safe metadata and public identity from a legacy ~/.httk tree.

Module Contents

httk.workflow.configuration.CONFIG_FORMAT = 'httk-config'

httk.workflow.configuration.CONFIG_FORMAT_VERSION = 2

class httk.workflow.configuration.ConfigKey

Describe one member the user configuration is allowed to carry.

Parameters:

• name – Configuration member name.

• description – Human-readable explanation shown to operators.

• settable – Whether config set may change the member.

name: str

description: str

settable: bool = True

httk.workflow.configuration.CONFIG_KEYS: collections.abc.Mapping[str, ConfigKey]

httk.workflow.configuration.settable_config_keys()

Return the configuration keys config set accepts, in order.

Returns:

Settable configuration member names.

Return type:

tuple[str, …]

httk.workflow.configuration.remotes_home()

Return where this user’s remote definitions live.

Returns:

Per-user remote definition directory.

Return type:

pathlib.Path

httk.workflow.configuration.launchers_home()

Return where this user’s manager launcher definitions live.

Returns:

Per-user manager launcher definition directory.

Return type:

pathlib.Path

httk.workflow.configuration.config_path()

Return the path of this user’s configuration file.

Returns:

User configuration path.

Return type:

pathlib.Path

httk.workflow.configuration.read_config()

Read the user configuration, returning an empty mapping if absent.

A document of an unrecognized format or version is refused by name rather than read as if its members meant what this implementation means by them.

Returns:

Configuration members, or an empty mapping when no file exists.

Raises:

ValueError – If the file is not a supported configuration document.

Return type:

dict[str, object]

httk.workflow.configuration.machine_names()

Return the configured names by which this machine is addressed.

Returns:

Names configured for this machine.

Raises:

ValueError – If machine_names is not a valid comma-separated value.

Return type:

frozenset[str]

httk.workflow.configuration.write_config(values)

Write a versioned user configuration.

Parameters:

values (collections.abc.Mapping[str, object]) – Configuration members to write.

Returns:

Path of the written configuration file.

Return type:

pathlib.Path

httk.workflow.configuration.set_config_key(key, value)

Set one registered configuration key and return the written path.

Parameters:

• key (str) – Settable configuration member name.

• value (str) – New member value.

Returns:

Path of the written configuration file.

Raises:

ValueError – If the key is not settable or its value is invalid.

Return type:

pathlib.Path

httk.workflow.configuration.unset_config_key(key)

Remove one registered configuration key and return the written path.

Parameters:

key (str) – Settable configuration member name.

Returns:

Path of the written configuration file.

Raises:

ValueError – If the key is not settable or is not configured.

Return type:

pathlib.Path

httk.workflow.configuration.import_v1_configuration(source=None)

Import safe metadata and public identity from a legacy ~/.httk tree.

The named operator identity report and legacy public key are returned from httk.core.identity.import_v1_identity; the workflow configuration records only where the import came from. Legacy 64-byte private material is deliberately left untouched.

Parameters:

source (str | os.PathLike[str] | None) – Legacy configuration root, or the default legacy home.

Returns:

Imported workflow configuration and identity report members.

Raises:

FileNotFoundError – If the legacy configuration file is absent.

Return type:

dict[str, object]