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¶

`config_home`()	Return the httk configuration directory.
`data_home`()	Return the httk data directory.
`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_home()¶

Return the httk configuration directory.

Returns:: Resolved per-user configuration directory.
Return type:: pathlib.Path

httk.workflow.configuration.data_home()¶

Return the httk data directory.

Returns:: Resolved per-user data directory.
Return type:: pathlib.Path

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, Ellipsis]

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]