httk.workflow.adapters

Versioned JSON remote-adapter bundles.

Attributes

ADAPTER_OPERATIONS
ADAPTER_EXECUTABLE
CREDENTIALS_FILE
METADATA_FILE
ADAPTER_FORMAT
REQUEST_FORMAT
RESULT_FORMAT
PERSISTABLE_REMOTE_SETTINGS
REMOTE_WORKSPACE_INIT_COMMAND
REMOTE_WORKSPACE_DELETE_COMMAND
REMOTE_WORKSPACE_FSCK_COMMAND
REMOTE_WORKSPACE_GC_COMMAND
REMOTE_WORKSPACE_LIST_COMMAND
REMOTE_WORKSPACE_MOVE_COMMAND
REMOTE_RECEIVE_COMMAND
REMOTE_OFFER_COMMAND
REMOTE_RETIRE_COMMAND
REMOTE_STATUS_COMMAND
REMOTE_WORKSPACE_SETTINGS_COMMAND
REMOTE_WORKSPACE_WORKFLOW_PRELUDE_COMMAND
REMOTE_MANAGER_COMMAND
SEED_SETTING_MAP

Classes

RemoteTarget

Resolved remote bundle.

Functions

submit_remote_managers(target, name, root, *, count, ...)	Submit managers for a far-side workspace name using its probed root.
probe_remote_workspace(target, name, *, timeout[, ...])	Return the UUID and current root reported for a remote workspace name.
seed_application_settings(bundle)	Return the application settings a remote seeds a workspace with.
metadata_path(bundle)	Return the metadata file of one adapter bundle.
read_metadata(bundle)	Read the metadata of one adapter bundle.
validate_adapter_bundle(bundle)	Validate static adapter metadata and the single dispatcher executable.
valid_remote_name(name)	Validate and return one remote name.
resolve_remote(value, *[, project])	Resolve project-local before global remote definitions.
project_remote_roots(project_root)	Return where one project keeps its remotes.
list_remotes([project])	List definitions with project entries shadowing global entries.
add_remote(name, *, template[, global_scope, project])	Copy one maintained adapter template into user/project data.
split_settings(settings)	Partition --set values into persistable settings and credentials.
read_credentials(bundle)	Read remote credentials that never enter a project manifest.
store_credentials(bundle, settings)	Merge settings into the manifest-excluded remote credentials.
remote_settings(bundle)	Return persisted remote settings with credentials merged back in.
import_v1_remote(source, *[, name, global_scope, project])	Map a recognizable legacy executable bundle to the versioned contract.
run_adapter(bundle, operation, request, *[, timeout])	Execute one JSON adapter operation without invoking a shell.

Module Contents

httk.workflow.adapters.ADAPTER_OPERATIONS = ('configure', 'install', 'invoke', 'push', 'pull', 'start-manager', 'status')

httk.workflow.adapters.ADAPTER_EXECUTABLE = 'adapter'

httk.workflow.adapters.CREDENTIALS_FILE = 'credentials.json'

httk.workflow.adapters.METADATA_FILE = 'remote.json'

httk.workflow.adapters.ADAPTER_FORMAT = 'httk-computer-adapter'

httk.workflow.adapters.REQUEST_FORMAT = 'httk-computer-request'

httk.workflow.adapters.RESULT_FORMAT = 'httk-computer-result'

httk.workflow.adapters.PERSISTABLE_REMOTE_SETTINGS

httk.workflow.adapters.REMOTE_WORKSPACE_INIT_COMMAND = ('httk', 'workflow', 'workspace', 'init')

httk.workflow.adapters.REMOTE_WORKSPACE_DELETE_COMMAND = ('httk', 'workflow', 'workspace', 'delete')

httk.workflow.adapters.REMOTE_WORKSPACE_FSCK_COMMAND = ('httk', 'workflow', 'workspace', 'fsck')

httk.workflow.adapters.REMOTE_WORKSPACE_GC_COMMAND = ('httk', 'workflow', 'workspace', 'gc')

httk.workflow.adapters.REMOTE_WORKSPACE_LIST_COMMAND = ('httk', 'workflow', 'workspace', 'list')

httk.workflow.adapters.REMOTE_WORKSPACE_MOVE_COMMAND = ('httk', 'workflow', 'workspace', 'move')

httk.workflow.adapters.REMOTE_RECEIVE_COMMAND = ('httk', 'workflow', 'transfer', 'receive')

httk.workflow.adapters.REMOTE_OFFER_COMMAND = ('httk', 'workflow', 'transfer', 'offer')

httk.workflow.adapters.REMOTE_RETIRE_COMMAND = ('httk', 'workflow', 'transfer', 'retire')

httk.workflow.adapters.REMOTE_STATUS_COMMAND = ('httk', 'workflow', 'workspace', 'status')

httk.workflow.adapters.REMOTE_WORKSPACE_SETTINGS_COMMAND = ('httk', 'workflow', 'workspace', 'settings')

httk.workflow.adapters.REMOTE_WORKSPACE_WORKFLOW_PRELUDE_COMMAND = ('httk', 'workflow', 'workspace', 'workflow-prelude')

httk.workflow.adapters.REMOTE_MANAGER_COMMAND = ('httk', 'workflow', 'manager', 'run')

httk.workflow.adapters.submit_remote_managers(target, name, root, *, count, argv_tail, timeout, adapter=None)

Submit managers for a far-side workspace name using its probed root.

Parameters:

• target (RemoteTarget) – The resolved remote adapter bundle.

• name (str) – The remote workspace name.

• root (str) – The remote workspace root.

• count (int) – The number of managers to submit.

• argv_tail (collections.abc.Sequence[str]) – Additional manager arguments.

• timeout (float | None) – The adapter operation timeout.

• adapter (collections.abc.Callable[Ellipsis, dict[str, Any]] | None) – The adapter callable, or run_adapter() when omitted.

Returns:

The adapter result document.

Return type:

dict[str, Any]

httk.workflow.adapters.probe_remote_workspace(target, name, *, timeout, noun='workspace', adapter=None)

Return the UUID and current root reported for a remote workspace name.

Parameters:

• target (RemoteTarget) – The resolved remote adapter bundle.

• name (str) – The remote workspace name.

• timeout (float | None) – The adapter operation timeout.

• noun (str) – The noun used in diagnostic messages.

• adapter (collections.abc.Callable[Ellipsis, dict[str, Any]] | None) – The adapter callable, or run_adapter() when omitted.

Returns:

The remote workspace identifier and root.

Raises:

• RuntimeError – If the remote status operation fails.

• ValueError – If the remote returns an incompatible status document.

Return type:

tuple[str, str]

httk.workflow.adapters.SEED_SETTING_MAP: collections.abc.Mapping[str, str]

httk.workflow.adapters.seed_application_settings(bundle)

Return the application settings a remote seeds a workspace with.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

The whitelisted application settings derived from the bundle.

Return type:

dict[str, object]

class httk.workflow.adapters.RemoteTarget

Resolved remote bundle.

Parameters:

• name – The remote name.

• bundle – The resolved adapter bundle path.

• project_local – Whether the bundle came from project data.

name: str

bundle: pathlib.Path

project_local: bool

httk.workflow.adapters.metadata_path(bundle)

Return the metadata file of one adapter bundle.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

The bundle metadata path.

Return type:

pathlib.Path

httk.workflow.adapters.read_metadata(bundle)

Read the metadata of one adapter bundle.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

The decoded metadata document.

Raises:

ValueError – If the metadata cannot be read as an object.

Return type:

dict[str, Any]

httk.workflow.adapters.validate_adapter_bundle(bundle)

Validate static adapter metadata and the single dispatcher executable.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

The validated metadata document.

Raises:

ValueError – If metadata, the dispatcher, or a required binary is invalid or unavailable.

Return type:

dict[str, Any]

httk.workflow.adapters.valid_remote_name(name)

Validate and return one remote name.

Parameters:

name (str) – The remote name to validate.

Returns:

The validated remote name.

Raises:

httk.workflow.errors.ResolutionMiss – If the name is not valid for remote resolution.

Return type:

str

httk.workflow.adapters.resolve_remote(value, *, project=None)

Resolve project-local before global remote definitions.

Parameters:

• value (str) – The remote name to resolve.

• project (str | os.PathLike[str] | None) – The project path, or the discovered project when omitted.

Returns:

The resolved remote target.

Raises:

httk.workflow.errors.ResolutionMiss – If the name is invalid or no bundle is found.

Return type:

RemoteTarget

httk.workflow.adapters.project_remote_roots(project_root)

Return where one project keeps its remotes.

Parameters:

project_root (pathlib.Path) – The project root.

Returns:

The project remote roots in precedence order.

Return type:

tuple[pathlib.Path, Ellipsis]

httk.workflow.adapters.list_remotes(project=None)

List definitions with project entries shadowing global entries.

Parameters:

project (str | os.PathLike[str] | None) – The project path, or the discovered project when omitted.

Returns:

Remote definitions with scope and bundle path.

Return type:

list[dict[str, object]]

httk.workflow.adapters.add_remote(name, *, template, global_scope=False, project=None)

Copy one maintained adapter template into user/project data.

Parameters:

• name (str) – The remote name to create.

• template (str) – The maintained adapter template name.

• global_scope (bool) – Whether to create the remote in global data.

• project (str | os.PathLike[str] | None) – The project path for a project-local remote.

Returns:

The newly created adapter bundle path.

Raises:

• ValueError – If the name, template, or scope is invalid.

• FileExistsError – If the destination already exists.

Return type:

pathlib.Path

httk.workflow.adapters.split_settings(settings)

Partition --set values into persistable settings and credentials.

Parameters:

settings (collections.abc.Mapping[str, str]) – The settings supplied by the caller.

Returns:

Persistable settings followed by manifest-excluded credentials.

Raises:

ValueError – If a setting name is retired or unsupported.

Return type:

tuple[dict[str, str], dict[str, str]]

httk.workflow.adapters.read_credentials(bundle)

Read remote credentials that never enter a project manifest.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

The stored credential document, or an empty mapping when absent.

Raises:

ValueError – If the credentials file is not a JSON object.

Return type:

dict[str, Any]

httk.workflow.adapters.store_credentials(bundle, settings)

Merge settings into the manifest-excluded remote credentials.

Parameters:

• bundle (str | os.PathLike[str]) – The adapter bundle path.

• settings (collections.abc.Mapping[str, str]) – Credential members to merge.

Returns:

The credentials file path.

Raises:

ValueError – If the existing credentials file is invalid.

Return type:

pathlib.Path

httk.workflow.adapters.remote_settings(bundle)

Return persisted remote settings with credentials merged back in.

Parameters:

bundle (str | os.PathLike[str]) – The adapter bundle path.

Returns:

Persisted settings and manifest-excluded credentials.

Raises:

ValueError – If adapter metadata or credentials are invalid.

Return type:

dict[str, Any]

httk.workflow.adapters.import_v1_remote(source, *, name=None, global_scope=False, project=None)

Map a recognizable legacy executable bundle to the versioned contract.

Legacy shell programs are never copied or executed. Only their simple assignment-only config files are read, and the result uses a maintained v2 adapter implementation. What is read is an httk v1 computer definition, so the legacy names below are the names that tree really uses.

Parameters:

• source (str | os.PathLike[str]) – The legacy executable bundle path.

• name (str | None) – The imported remote name, or the source directory name when omitted.

• global_scope (bool) – Whether to create the imported remote in global data.

• project (str | os.PathLike[str] | None) – The project path for a project-local import.

Returns:

The created versioned adapter bundle path.

Raises:

ValueError – If the legacy bundle cannot be recognized or imported.

Return type:

pathlib.Path

httk.workflow.adapters.run_adapter(bundle, operation, request, *, timeout=None)

Execute one JSON adapter operation without invoking a shell.

Parameters:

• bundle (str | os.PathLike[str]) – The adapter bundle path.

• operation (str) – The adapter operation name.

• request (collections.abc.Mapping[str, object]) – The operation request members.

• timeout (float | None) – The operation timeout, or the bundle default when omitted.

Returns:

The adapter result document.

Raises:

• TimeoutError – If the adapter exceeds its timeout.

• ValueError – If the request or result violates the adapter protocol.

• RuntimeError – If the adapter refuses or fails the operation.

Return type:

dict[str, Any]