Split off cli_helpers and cli_machinery internal modules (623f749) - derivepassphrase.git

Split off cli_helpers and cli_machinery internal modules

Marco Ricci commited on 2025-01-29 22:23:26
Zeige 9 geänderte Dateien mit 2226 Einfügungen und 2064 Löschungen.

Split off the `logging` and `click` support code (the "machinery") and
the command-specific helper functions (the "helpers") into separate
modules under `derivepassphrase._internals`.  Change all functions,
classes and attributes within those new modules to be public with
respect to the module, since the module itself is already non-public.

Also document all previously undocumented classes and functions:
`cli_helpers.ORIGIN`, `cli_helpers.check_for_misleading_passphrase`,
`cli_helpers.key_to_phrase` and `cli_helpers.print_config_as_sh_script`.
Add a better default value (`cli_helpers.default_error_callback`) for
the `error_callback` parameter of `cli_helpers.key_to_phrase`, and
document that too.  Finally, since the shell completion parts are now
split across two modules, add an explicit TODO to the
`cli_machinery.ZshComplete` class to add context.

docs/reference/derivepassphrase._internals.cli_helpers.md 0000000..d9f7a75
docs/reference/derivepassphrase._internals.cli_machinery.md 0000000..835797c
mkdocs_devsetup.yml 35c5163..1645de0
src/derivepassphrase/_internals/cli_helpers.py 0000000..a418a5a
src/derivepassphrase/_internals/cli_machinery.py 0000000..f662925
src/derivepassphrase/cli.py b272050..4982d66
tests/__init__.py d1b7f41..fc8ed9b
tests/test_derivepassphrase_cli.py 3f7e141..4fec3fb
tests/test_derivepassphrase_ssh_agent.py 5ab1a6c..ff9be64

docs/reference/derivepassphrase._internals.cli_helpers.md

Zeige Datei @ 623f749

...	...	@@ -0,0 +1,3 @@
	1	+::: derivepassphrase._internals.cli_helpers
	2	+ options:
	3	+ heading_level: 1

docs/reference/derivepassphrase._internals.cli_machinery.md

Zeige Datei @ 623f749

...	...	@@ -0,0 +1,3 @@
	1	+::: derivepassphrase._internals.cli_machinery
	2	+ options:
	3	+ heading_level: 1

mkdocs_devsetup.yml

Zeige Datei @ 623f749

@@ -29,12 +29,14 @@ nav:
     - Technical prerequisites:
       - 'Using derivepassphrase vault with an SSH key': reference/prerequisites-ssh-key.md
     - 'Internal API docs: Submodule derivepassphrase._internals':
+      - Submodule cli_helpers: reference/derivepassphrase._internals.cli_helpers.md
+      - Submodule cli_machinery: reference/derivepassphrase._internals.cli_machinery.md
       - Submodule cli_messages: reference/derivepassphrase._internals.cli_messages.md
     - 'Internal API docs: Tests':
       - Basic testing infrastructure: reference/tests.md
       - Localization machinery: reference/tests.test_l10n.md
       - derivepassphrase command-line:
-        - cli module: reference/tests.test_derivepassphrase_cli.md
+        - cli module, helpers and machinery: reference/tests.test_derivepassphrase_cli.md
         - '"export vault" subcommand tests': reference/tests.test_derivepassphrase_cli_export_vault.md
       - exporter module: reference/tests.test_derivepassphrase_exporter.md
       - sequin module: reference/tests.test_derivepassphrase_sequin.md

src/derivepassphrase/_internals/cli_helpers.py

Zeige Datei @ 623f749

...	...	@@ -0,0 +1,810 @@
	1	+# SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>
	2	+#
	3	+# SPDX-License-Identifier: Zlib
	4	+
	5	+# ruff: noqa: TRY400
	6	+
	7	+"""Helper functions for the derivepassphrase command-line.
	8	+
	9	+Warning:
	10	+ Non-public module (implementation detail), provided for didactical and
	11	+ educational purposes only. Subject to change without notice, including
	12	+ removal.
	13	+
	14	+"""
	15	+
	16	+from __future__ import annotations
	17	+
	18	+import base64
	19	+import copy
	20	+import enum
	21	+import json
	22	+import logging
	23	+import os
	24	+import pathlib
	25	+import shlex
	26	+import sys
	27	+import unicodedata
	28	+from typing import TYPE_CHECKING, Callable, NoReturn, TextIO, cast
	29	+
	30	+import click
	31	+import click.shell_completion
	32	+from typing_extensions import Any
	33	+
	34	+import derivepassphrase as dpp
	35	+from derivepassphrase import _types, ssh_agent, vault
	36	+from derivepassphrase._internals import cli_messages as _msg
	37	+
	38	+if sys.version_info >= (3, 11):
	39	+ import tomllib
	40	+else:
	41	+ import tomli as tomllib
	42	+
	43	+if TYPE_CHECKING:
	44	+ import socket
	45	+ from collections.abc import (
	46	+ Iterator,
	47	+ Sequence,
	48	+ )
	49	+
	50	+ from typing_extensions import Buffer
	51	+
	52	+__author__ = dpp.__author__
	53	+__version__ = dpp.__version__
	54	+
	55	+PROG_NAME = _msg.PROG_NAME
	56	+KEY_DISPLAY_LENGTH = 50
	57	+
	58	+# Error messages
	59	+INVALID_VAULT_CONFIG = 'Invalid vault config'
	60	+AGENT_COMMUNICATION_ERROR = 'Error communicating with the SSH agent'
	61	+NO_SUITABLE_KEYS = 'No suitable SSH keys were found'
	62	+EMPTY_SELECTION = 'Empty selection'
	63	+
	64	+
	65	+# Shell completion
	66	+# ================
	67	+
	68	+# Use naive filename completion for the `path` argument of
	69	+# `derivepassphrase vault`'s `--import` and `--export` options, as well
	70	+# as the `path` argument of `derivepassphrase export vault`. The latter
	71	+# treats the pseudo-filename `VAULT_PATH` specially, but this is awkward
	72	+# to combine with standard filename completion, particularly in bash, so
	73	+# we would probably have to implement all completion (`VAULT_PATH` and
	74	+# filename completion) ourselves, lacking some niceties of bash's
	75	+# built-in completion (e.g., adding spaces or slashes depending on
	76	+# whether the completion is a directory or a complete filename).
	77	+
	78	+
	79	+def shell_complete_path(
	80	+ ctx: click.Context,
	81	+ parameter: click.Parameter,
	82	+ value: str,
	83	+) -> list[str \| click.shell_completion.CompletionItem]:
	84	+ """Request standard path completion for the `path` argument.""" # noqa: DOC201
	85	+ del ctx, parameter, value
	86	+ return [click.shell_completion.CompletionItem('', type='file')]
	87	+
	88	+
	89	+# The standard `click` shell completion scripts serialize the completion
	90	+# items as newline-separated one-line entries, which get silently
	91	+# corrupted if the value contains newlines. Each shell imposes
	92	+# additional restrictions: Fish uses newlines in all internal completion
	93	+# helper scripts, so it is difficult, if not impossible, to register
	94	+# completion entries containing newlines if completion comes from within
	95	+# a Fish completion function (instead of a Fish builtin). Zsh's
	96	+# completion system supports descriptions for each completion item, and
	97	+# the completion helper functions parse every entry as a colon-separated
	98	+# 2-tuple of item and description, meaning any colon in the item value
	99	+# must be escaped. Finally, Bash requires the result array to be
	100	+# populated at the completion function's top-level scope, but for/while
	101	+# loops within pipelines do not run at top-level scope, and Bash also
	102	+# strips NUL characters from command substitution output, making it
	103	+# difficult to read in external data into an array in a cross-platform
	104	+# manner from entirely within Bash.
	105	+#
	106	+# We capitulate in front of these problems---most egregiously because of
	107	+# Fish---and ensure that completion items (in this case: service names)
	108	+# never contain ASCII control characters by refusing to offer such
	109	+# items as valid completions. On the other side, `derivepassphrase`
	110	+# will warn the user when configuring or importing a service with such
	111	+# a name that it will not be available for shell completion.
	112	+
	113	+
	114	+def is_completable_item(obj: object) -> bool:
	115	+ """Return whether the item is completable on the command-line.
	116	+
	117	+ The item is completable if and only if it contains no ASCII control
	118	+ characters (U+0000 through U+001F, and U+007F).
	119	+
	120	+ """
	121	+ obj = str(obj)
	122	+ forbidden = frozenset(chr(i) for i in range(32)) \| {'\x7f'}
	123	+ return not any(f in obj for f in forbidden)
	124	+
	125	+
	126	+def shell_complete_service(
	127	+ ctx: click.Context,
	128	+ parameter: click.Parameter,
	129	+ value: str,
	130	+) -> list[str \| click.shell_completion.CompletionItem]:
	131	+ """Return known vault service names as completion items.
	132	+
	133	+ Service names are looked up in the vault configuration file. All
	134	+ errors will be suppressed. Additionally, any service names deemed
	135	+ not completable as per [`is_completable_item`][] will be silently
	136	+ skipped.
	137	+
	138	+ """
	139	+ del ctx, parameter
	140	+ try:
	141	+ config = load_config()
	142	+ return sorted(
	143	+ sv
	144	+ for sv in config['services']
	145	+ if sv.startswith(value) and is_completable_item(sv)
	146	+ )
	147	+ except FileNotFoundError:
	148	+ try:
	149	+ config, _exc = migrate_and_load_old_config()
	150	+ return sorted(
	151	+ sv
	152	+ for sv in config['services']
	153	+ if sv.startswith(value) and is_completable_item(sv)
	154	+ )
	155	+ except FileNotFoundError:
	156	+ return []
	157	+ except Exception: # noqa: BLE001
	158	+ return []
	159	+
	160	+
	161	+# Vault
	162	+# =====
	163	+
	164	+config_filename_table = {
	165	+ None: '.',
	166	+ 'vault': 'vault.json',
	167	+ 'user configuration': 'config.toml',
	168	+ # TODO(the-13th-letter): Remove the old settings.json file.
	169	+ # https://the13thletter.info/derivepassphrase/latest/upgrade-notes.html#v1.0-old-settings-file
	170	+ 'old settings.json': 'settings.json',
	171	+}
	172	+
	173	+
	174	+def config_filename(
	175	+ subsystem: str \| None = 'old settings.json',
	176	+) -> pathlib.Path:
	177	+ """Return the filename of the configuration file for the subsystem.
	178	+
	179	+ The (implicit default) file is currently named `settings.json`,
	180	+ located within the configuration directory as determined by the
	181	+ `DERIVEPASSPHRASE_PATH` environment variable, or by
	182	+ [`click.get_app_dir`][] in POSIX mode. Depending on the requested
	183	+ subsystem, this will usually be a different file within that
	184	+ directory.
	185	+
	186	+ Args:
	187	+ subsystem:
	188	+ Name of the configuration subsystem whose configuration
	189	+ filename to return. If not given, return the old filename
	190	+ from before the subcommand migration. If `None`, return the
	191	+ configuration directory instead.
	192	+
	193	+ Raises:
	194	+ AssertionError:
	195	+ An unknown subsystem was passed.
	196	+
	197	+ Deprecated:
	198	+ Since v0.2.0: The implicit default subsystem and the old
	199	+ configuration filename are deprecated, and will be removed in v1.0.
	200	+ The subsystem will be mandatory to specify.
	201	+
	202	+ """
	203	+ path = pathlib.Path(
	204	+ os.getenv(PROG_NAME.upper() + '_PATH')
	205	+ or click.get_app_dir(PROG_NAME, force_posix=True)
	206	+ )
	207	+ try:
	208	+ filename = config_filename_table[subsystem]
	209	+ except (KeyError, TypeError): # pragma: no cover
	210	+ msg = f'Unknown configuration subsystem: {subsystem!r}'
	211	+ raise AssertionError(msg) from None
	212	+ return path / filename
	213	+
	214	+
	215	+def load_config() -> _types.VaultConfig:
	216	+ """Load a vault(1)-compatible config from the application directory.
	217	+
	218	+ The filename is obtained via [`config_filename`][]. This must be
	219	+ an unencrypted JSON file.
	220	+
	221	+ Returns:
	222	+ The vault settings. See [`_types.VaultConfig`][] for details.
	223	+
	224	+ Raises:
	225	+ OSError:
	226	+ There was an OS error accessing the file.
	227	+ ValueError:
	228	+ The data loaded from the file is not a vault(1)-compatible
	229	+ config.
	230	+
	231	+ """
	232	+ filename = config_filename(subsystem='vault')
	233	+ with filename.open('rb') as fileobj:
	234	+ data = json.load(fileobj)
	235	+ if not _types.is_vault_config(data):
	236	+ raise ValueError(INVALID_VAULT_CONFIG)
	237	+ return data
	238	+
	239	+
	240	+# TODO(the-13th-letter): Remove this function.
	241	+# https://the13thletter.info/derivepassphrase/latest/upgrade-notes.html#v1.0-old-settings-file
	242	+def migrate_and_load_old_config() -> tuple[
	243	+ _types.VaultConfig, OSError \| None
	244	+]:
	245	+ """Load and migrate a vault(1)-compatible config.
	246	+
	247	+ The (old) filename is obtained via [`config_filename`][]. This
	248	+ must be an unencrypted JSON file. After loading, the file is
	249	+ migrated to the new standard filename.
	250	+
	251	+ Returns:
	252	+ The vault settings, and an optional exception encountered during
	253	+ migration. See [`_types.VaultConfig`][] for details on the
	254	+ former.
	255	+
	256	+ Raises:
	257	+ OSError:
	258	+ There was an OS error accessing the old file.
	259	+ ValueError:
	260	+ The data loaded from the file is not a vault(1)-compatible
	261	+ config.
	262	+
	263	+ """
	264	+ new_filename = config_filename(subsystem='vault')
	265	+ old_filename = config_filename(subsystem='old settings.json')
	266	+ with old_filename.open('rb') as fileobj:
	267	+ data = json.load(fileobj)
	268	+ if not _types.is_vault_config(data):
	269	+ raise ValueError(INVALID_VAULT_CONFIG)
	270	+ try:
	271	+ old_filename.rename(new_filename)
	272	+ except OSError as exc:
	273	+ return data, exc
	274	+ else:
	275	+ return data, None
	276	+
	277	+
	278	+def save_config(config: _types.VaultConfig, /) -> None:
	279	+ """Save a vault(1)-compatible config to the application directory.
	280	+
	281	+ The filename is obtained via [`config_filename`][]. The config
	282	+ will be stored as an unencrypted JSON file.
	283	+
	284	+ Args:
	285	+ config:
	286	+ vault configuration to save.
	287	+
	288	+ Raises:
	289	+ OSError:
	290	+ There was an OS error accessing or writing the file.
	291	+ ValueError:
	292	+ The data cannot be stored as a vault(1)-compatible config.
	293	+
	294	+ """
	295	+ if not _types.is_vault_config(config):
	296	+ raise ValueError(INVALID_VAULT_CONFIG)
	297	+ filename = config_filename(subsystem='vault')
	298	+ filedir = filename.resolve().parent
	299	+ filedir.mkdir(parents=True, exist_ok=True)
	300	+ with filename.open('w', encoding='UTF-8') as fileobj:
	301	+ json.dump(config, fileobj)
	302	+
	303	+
	304	+def load_user_config() -> dict[str, Any]:
	305	+ """Load the user config from the application directory.
	306	+
	307	+ The filename is obtained via [`config_filename`][].
	308	+
	309	+ Returns:
	310	+ The user configuration, as a nested `dict`.
	311	+
	312	+ Raises:
	313	+ OSError:
	314	+ There was an OS error accessing the file.
	315	+ ValueError:
	316	+ The data loaded from the file is not a valid configuration
	317	+ file.
	318	+
	319	+ """
	320	+ filename = config_filename(subsystem='user configuration')
	321	+ with filename.open('rb') as fileobj:
	322	+ return tomllib.load(fileobj)
	323	+
	324	+
	325	+def get_suitable_ssh_keys(
	326	+ conn: ssh_agent.SSHAgentClient \| socket.socket \| None = None, /
	327	+) -> Iterator[_types.SSHKeyCommentPair]:
	328	+ """Yield all SSH keys suitable for passphrase derivation.
	329	+
	330	+ Suitable SSH keys are queried from the running SSH agent (see
	331	+ [`ssh_agent.SSHAgentClient.list_keys`][]).
	332	+
	333	+ Args:
	334	+ conn:
	335	+ An optional connection hint to the SSH agent. See
	336	+ [`ssh_agent.SSHAgentClient.ensure_agent_subcontext`][].
	337	+
	338	+ Yields:
	339	+ Every SSH key from the SSH agent that is suitable for passphrase
	340	+ derivation.
	341	+
	342	+ Raises:
	343	+ KeyError:
	344	+ `conn` was `None`, and the `SSH_AUTH_SOCK` environment
	345	+ variable was not found.
	346	+ NotImplementedError:
	347	+ `conn` was `None`, and this Python does not support
	348	+ [`socket.AF_UNIX`][], so the SSH agent client cannot be
	349	+ automatically set up.
	350	+ OSError:
	351	+ `conn` was a socket or `None`, and there was an error
	352	+ setting up a socket connection to the agent.
	353	+ LookupError:
	354	+ No keys usable for passphrase derivation are loaded into the
	355	+ SSH agent.
	356	+ RuntimeError:
	357	+ There was an error communicating with the SSH agent.
	358	+ ssh_agent.SSHAgentFailedError:
	359	+ The agent failed to supply a list of loaded keys.
	360	+
	361	+ """
	362	+ with ssh_agent.SSHAgentClient.ensure_agent_subcontext(conn) as client:
	363	+ try:
	364	+ all_key_comment_pairs = list(client.list_keys())
	365	+ except EOFError as exc: # pragma: no cover
	366	+ raise RuntimeError(AGENT_COMMUNICATION_ERROR) from exc
	367	+ suitable_keys = copy.copy(all_key_comment_pairs)
	368	+ for pair in all_key_comment_pairs:
	369	+ key, _comment = pair
	370	+ if vault.Vault.is_suitable_ssh_key(key, client=client):
	371	+ yield pair
	372	+ if not suitable_keys: # pragma: no cover
	373	+ raise LookupError(NO_SUITABLE_KEYS)
	374	+
	375	+
	376	+def prompt_for_selection(
	377	+ items: Sequence[str \| bytes],
	378	+ heading: str = 'Possible choices:',
	379	+ single_choice_prompt: str = 'Confirm this choice?',
	380	+ ctx: click.Context \| None = None,
	381	+) -> int:
	382	+ """Prompt user for a choice among the given items.
	383	+
	384	+ Print the heading, if any, then present the items to the user. If
	385	+ there are multiple items, prompt the user for a selection, validate
	386	+ the choice, then return the list index of the selected item. If
	387	+ there is only a single item, request confirmation for that item
	388	+ instead, and return the correct index.
	389	+
	390	+ Args:
	391	+ items:
	392	+ The list of items to choose from.
	393	+ heading:
	394	+ A heading for the list of items, to print immediately
	395	+ before. Defaults to a reasonable standard heading. If
	396	+ explicitly empty, print no heading.
	397	+ single_choice_prompt:
	398	+ The confirmation prompt if there is only a single possible
	399	+ choice. Defaults to a reasonable standard prompt.
	400	+ ctx:
	401	+ An optional `click` context, from which output device
	402	+ properties and color preferences will be queried.
	403	+
	404	+ Returns:
	405	+ An index into the items sequence, indicating the user's
	406	+ selection.
	407	+
	408	+ Raises:
	409	+ IndexError:
	410	+ The user made an invalid or empty selection, or requested an
	411	+ abort.
	412	+
	413	+ """
	414	+ n = len(items)
	415	+ color = ctx.color if ctx is not None else None
	416	+ if heading:
	417	+ click.echo(click.style(heading, bold=True), color=color)
	418	+ for i, x in enumerate(items, start=1):
	419	+ click.echo(click.style(f'[{i}]', bold=True), nl=False, color=color)
	420	+ click.echo(' ', nl=False, color=color)
	421	+ click.echo(x, color=color)
	422	+ if n > 1:
	423	+ choices = click.Choice([''] + [str(i) for i in range(1, n + 1)])
	424	+ choice = click.prompt(
	425	+ f'Your selection? (1-{n}, leave empty to abort)',
	426	+ err=True,
	427	+ type=choices,
	428	+ show_choices=False,
	429	+ show_default=False,
	430	+ default='',
	431	+ )
	432	+ if not choice:
	433	+ raise IndexError(EMPTY_SELECTION)
	434	+ return int(choice) - 1
	435	+ prompt_suffix = (
	436	+ ' ' if single_choice_prompt.endswith(tuple('?.!')) else ': '
	437	+ )
	438	+ try:
	439	+ click.confirm(
	440	+ single_choice_prompt,
	441	+ prompt_suffix=prompt_suffix,
	442	+ err=True,
	443	+ abort=True,
	444	+ default=False,
	445	+ show_default=False,
	446	+ )
	447	+ except click.Abort:
	448	+ raise IndexError(EMPTY_SELECTION) from None
	449	+ return 0
	450	+
	451	+
	452	+def select_ssh_key(
	453	+ conn: ssh_agent.SSHAgentClient \| socket.socket \| None = None,
	454	+ /,
	455	+ *,
	456	+ ctx: click.Context \| None = None,
	457	+) -> bytes \| bytearray:
	458	+ """Interactively select an SSH key for passphrase derivation.
	459	+
	460	+ Suitable SSH keys are queried from the running SSH agent (see
	461	+ [`ssh_agent.SSHAgentClient.list_keys`][]), then the user is prompted
	462	+ interactively (see [`click.prompt`][]) for a selection.
	463	+
	464	+ Args:
	465	+ conn:
	466	+ An optional connection hint to the SSH agent. See
	467	+ [`ssh_agent.SSHAgentClient.ensure_agent_subcontext`][].
	468	+ ctx:
	469	+ An `click` context, queried for output device properties and
	470	+ color preferences when issuing the prompt.
	471	+
	472	+ Returns:
	473	+ The selected SSH key.
	474	+
	475	+ Raises:
	476	+ KeyError:
	477	+ `conn` was `None`, and the `SSH_AUTH_SOCK` environment
	478	+ variable was not found.
	479	+ NotImplementedError:
	480	+ `conn` was `None`, and this Python does not support
	481	+ [`socket.AF_UNIX`][], so the SSH agent client cannot be
	482	+ automatically set up.
	483	+ OSError:
	484	+ `conn` was a socket or `None`, and there was an error
	485	+ setting up a socket connection to the agent.
	486	+ IndexError:
	487	+ The user made an invalid or empty selection, or requested an
	488	+ abort.
	489	+ LookupError:
	490	+ No keys usable for passphrase derivation are loaded into the
	491	+ SSH agent.
	492	+ RuntimeError:
	493	+ There was an error communicating with the SSH agent.
	494	+ SSHAgentFailedError:
	495	+ The agent failed to supply a list of loaded keys.
	496	+ """
	497	+ suitable_keys = list(get_suitable_ssh_keys(conn))
	498	+ key_listing: list[str] = []
	499	+ unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
	500	+ for key, comment in suitable_keys:
	501	+ keytype = unstring_prefix(key)[0].decode('ASCII')
	502	+ key_str = base64.standard_b64encode(key).decode('ASCII')
	503	+ remaining_key_display_length = KEY_DISPLAY_LENGTH - 1 - len(keytype)
	504	+ key_extract = min(
	505	+ key_str,
	506	+ '...' + key_str[-remaining_key_display_length:],
	507	+ key=len,
	508	+ )
	509	+ comment_str = comment.decode('UTF-8', errors='replace')
	510	+ key_listing.append(f'{keytype} {key_extract} {comment_str}')
	511	+ choice = prompt_for_selection(
	512	+ key_listing,
	513	+ heading='Suitable SSH keys:',
	514	+ single_choice_prompt='Use this key?',
	515	+ ctx=ctx,
	516	+ )
	517	+ return suitable_keys[choice].key
	518	+
	519	+
	520	+def prompt_for_passphrase() -> str:
	521	+ """Interactively prompt for the passphrase.
	522	+
	523	+ Calls [`click.prompt`][] internally. Moved into a separate function
	524	+ mainly for testing/mocking purposes.
	525	+
	526	+ Returns:
	527	+ The user input.
	528	+
	529	+ """
	530	+ return cast(
	531	+ 'str',
	532	+ click.prompt(
	533	+ 'Passphrase',
	534	+ default='',
	535	+ hide_input=True,
	536	+ show_default=False,
	537	+ err=True,
	538	+ ),
	539	+ )
	540	+
	541	+
	542	+def toml_key(*parts: str) -> str:
	543	+ """Return a formatted TOML key, given its parts."""
	544	+
	545	+ def escape(string: str) -> str:
	546	+ translated = string.translate({
	547	+ 0: r'\u0000',
	548	+ 1: r'\u0001',
	549	+ 2: r'\u0002',
	550	+ 3: r'\u0003',
	551	+ 4: r'\u0004',
	552	+ 5: r'\u0005',
	553	+ 6: r'\u0006',
	554	+ 7: r'\u0007',
	555	+ 8: r'\b',
	556	+ 9: r'\t',
	557	+ 10: r'\n',
	558	+ 11: r'\u000B',
	559	+ 12: r'\f',
	560	+ 13: r'\r',
	561	+ 14: r'\u000E',
	562	+ 15: r'\u000F',
	563	+ ord('"'): r'\"',
	564	+ ord('\\'): r'\\',
	565	+ 127: r'\u007F',
	566	+ })
	567	+ return f'"{translated}"' if translated != string else string
	568	+
	569	+ return '.'.join(map(escape, parts))
	570	+
	571	+
	572	+class ORIGIN(enum.Enum):
	573	+ """The origin of a setting, if not from the user configuration file.
	574	+
	575	+ Attributes:
	576	+ INTERACTIVE: interactive input
	577	+
	578	+ """
	579	+ INTERACTIVE: str = 'interactive input'
	580	+ """"""
	581	+
	582	+
	583	+def check_for_misleading_passphrase(
	584	+ key: tuple[str, ...] \| ORIGIN,
	585	+ value: dict[str, Any],
	586	+ *,
	587	+ main_config: dict[str, Any],
	588	+ ctx: click.Context \| None = None,
	589	+) -> None:
	590	+ """Check for a misleading passphrase according to user configuration.
	591	+
	592	+ Look up the desired Unicode normalization form in the user
	593	+ configuration, and if the passphrase is not normalized according to
	594	+ this form, issue a warning to the user.
	595	+
	596	+ Args:
	597	+ key:
	598	+ A vault configuration key or an origin of the
	599	+ value/configuration section, e.g. [`ORIGIN.INTERACTIVE`][],
	600	+ or `("global",)`, or `("services", "foo")`.
	601	+ value:
	602	+ The vault configuration section maybe containing
	603	+ a passphrase to vet.
	604	+ main_config:
	605	+ The parsed main user configuration.
	606	+ ctx:
	607	+ The click context. This is necessary to pass output options
	608	+ set on the context to the logging machinery.
	609	+
	610	+ Raises:
	611	+ AssertionError:
	612	+ The main user configuration is invalid.
	613	+
	614	+ """
	615	+ form_key = 'unicode-normalization-form'
	616	+ default_form: str = main_config.get('vault', {}).get(
	617	+ f'default-{form_key}', 'NFC'
	618	+ )
	619	+ form_dict: dict[str, dict] = main_config.get('vault', {}).get(form_key, {})
	620	+ form: Any = (
	621	+ default_form
	622	+ if isinstance(key, ORIGIN) or key == ('global',)
	623	+ else form_dict.get(key[1], default_form)
	624	+ )
	625	+ config_key = (
	626	+ toml_key('vault', key[1], form_key)
	627	+ if isinstance(key, tuple) and len(key) > 1 and key[1] in form_dict
	628	+ else f'vault.default-{form_key}'
	629	+ )
	630	+ if form not in {'NFC', 'NFD', 'NFKC', 'NFKD'}:
	631	+ msg = f'Invalid value {form!r} for config key {config_key}'
	632	+ raise AssertionError(msg)
	633	+ logger = logging.getLogger(PROG_NAME)
	634	+ formatted_key = (
	635	+ key.value if isinstance(key, ORIGIN) else _types.json_path(key)
	636	+ )
	637	+ if 'phrase' in value:
	638	+ phrase = value['phrase']
	639	+ if not unicodedata.is_normalized(form, phrase):
	640	+ logger.warning(
	641	+ (
	642	+ 'The %s passphrase is not %s-normalized. Its '
	643	+ 'serialization as a byte string may not be what you '
	644	+ 'expect it to be, even if it displays correctly. '
	645	+ 'Please make sure to double-check any derived '
	646	+ 'passphrases for unexpected results.'
	647	+ ),
	648	+ formatted_key,
	649	+ form,
	650	+ stacklevel=2,
	651	+ extra={'color': ctx.color if ctx is not None else None},
	652	+ )
	653	+
	654	+
	655	+def default_error_callback(
	656	+ message: Any, # noqa: ANN401
	657	+ /,
	658	+ *_args: Any, # noqa: ANN401
	659	+ **_kwargs: Any, # noqa: ANN401
	660	+) -> NoReturn: # pragma: no cover
	661	+ """Calls [`sys.exit`][] on its first argument, ignoring the rest."""
	662	+ sys.exit(message)
	663	+
	664	+
	665	+def key_to_phrase(
	666	+ key: str \| Buffer,
	667	+ /,
	668	+ *,
	669	+ error_callback: Callable[..., NoReturn] = default_error_callback,
	670	+) -> bytes:
	671	+ """Return the equivalent master passphrase, or abort.
	672	+
	673	+ This wrapper around [`vault.Vault.phrase_from_key`][] emits
	674	+ user-facing error messages if no equivalent master passphrase can be
	675	+ obtained from the key, because this is the first point of contact
	676	+ with the SSH agent.
	677	+
	678	+ """
	679	+ key = base64.standard_b64decode(key)
	680	+ try:
	681	+ with ssh_agent.SSHAgentClient.ensure_agent_subcontext() as client:
	682	+ try:
	683	+ return vault.Vault.phrase_from_key(key, conn=client)
	684	+ except ssh_agent.SSHAgentFailedError as exc:
	685	+ try:
	686	+ keylist = client.list_keys()
	687	+ except ssh_agent.SSHAgentFailedError:
	688	+ pass
	689	+ except Exception as exc2: # noqa: BLE001
	690	+ exc.__context__ = exc2
	691	+ else:
	692	+ if not any( # pragma: no branch
	693	+ k == key for k, _ in keylist
	694	+ ):
	695	+ error_callback(
	696	+ _msg.TranslatedString(
	697	+ _msg.ErrMsgTemplate.SSH_KEY_NOT_LOADED
	698	+ )
	699	+ )
	700	+ error_callback(
	701	+ _msg.TranslatedString(
	702	+ _msg.ErrMsgTemplate.AGENT_REFUSED_SIGNATURE
	703	+ ),
	704	+ exc_info=exc,
	705	+ )
	706	+ except KeyError:
	707	+ error_callback(
	708	+ _msg.TranslatedString(_msg.ErrMsgTemplate.NO_SSH_AGENT_FOUND)
	709	+ )
	710	+ except NotImplementedError:
	711	+ error_callback(_msg.TranslatedString(_msg.ErrMsgTemplate.NO_AF_UNIX))
	712	+ except OSError as exc:
	713	+ error_callback(
	714	+ _msg.TranslatedString(
	715	+ _msg.ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT,
	716	+ error=exc.strerror,
	717	+ filename=exc.filename,
	718	+ ).maybe_without_filename()
	719	+ )
	720	+ except RuntimeError as exc:
	721	+ error_callback(
	722	+ _msg.TranslatedString(_msg.ErrMsgTemplate.CANNOT_UNDERSTAND_AGENT),
	723	+ exc_info=exc,
	724	+ )
	725	+
	726	+
	727	+def print_config_as_sh_script(
	728	+ config: _types.VaultConfig,
	729	+ /,
	730	+ *,
	731	+ outfile: TextIO,
	732	+ prog_name_list: Sequence[str],
	733	+) -> None:
	734	+ """Print the given vault configuration as a sh(1) script.
	735	+
	736	+ This implements the `--export-as=sh` option of `derivepassphrase vault`.
	737	+
	738	+ Args:
	739	+ config:
	740	+ The configuration to serialize.
	741	+ outfile:
	742	+ A file object to write the output to.
	743	+ prog_name_list:
	744	+ A list of (subcommand) names for the command emitting this
	745	+ output, e.g. `["derivepassphrase", "vault"]`.
	746	+
	747	+ """
	748	+ service_keys = (
	749	+ 'length',
	750	+ 'repeat',
	751	+ 'lower',
	752	+ 'upper',
	753	+ 'number',
	754	+ 'space',
	755	+ 'dash',
	756	+ 'symbol',
	757	+ )
	758	+ print('#!/bin/sh -e', file=outfile)
	759	+ print(file=outfile)
	760	+ print(shlex.join([*prog_name_list, '--clear']), file=outfile)
	761	+ sv_obj_pairs: list[
	762	+ tuple[
	763	+ str \| None,
	764	+ _types.VaultConfigGlobalSettings
	765	+ \| _types.VaultConfigServicesSettings,
	766	+ ],
	767	+ ] = list(config['services'].items())
	768	+ if config.get('global', {}):
	769	+ sv_obj_pairs.insert(0, (None, config['global']))
	770	+ for sv, sv_obj in sv_obj_pairs:
	771	+ this_service_keys = tuple(k for k in service_keys if k in sv_obj)
	772	+ this_other_keys = tuple(k for k in sv_obj if k not in service_keys)
	773	+ if this_other_keys:
	774	+ other_sv_obj = {k: sv_obj[k] for k in this_other_keys} # type: ignore[literal-required]
	775	+ dumped_config = json.dumps(
	776	+ (
	777	+ {'services': {sv: other_sv_obj}}
	778	+ if sv is not None
	779	+ else {'global': other_sv_obj, 'services': {}}
	780	+ ),
	781	+ ensure_ascii=False,
	782	+ indent=None,
	783	+ )
	784	+ print(
	785	+ shlex.join([*prog_name_list, '--import', '-']) + " <<'HERE'",
	786	+ dumped_config,
	787	+ 'HERE',
	788	+ sep='\n',
	789	+ file=outfile,
	790	+ )
	791	+ if not this_service_keys and not this_other_keys and sv:
	792	+ dumped_config = json.dumps(
	793	+ {'services': {sv: {}}},
	794	+ ensure_ascii=False,
	795	+ indent=None,
	796	+ )
	797	+ print(
	798	+ shlex.join([*prog_name_list, '--import', '-']) + " <<'HERE'",
	799	+ dumped_config,
	800	+ 'HERE',
	801	+ sep='\n',
	802	+ file=outfile,
	803	+ )
	804	+ elif this_service_keys:
	805	+ tokens = [*prog_name_list, '--config']
	806	+ for key in this_service_keys:
	807	+ tokens.extend([f'--{key}', str(sv_obj[key])]) # type: ignore[literal-required]
	808	+ if sv is not None:
	809	+ tokens.extend(['--', sv])
	810	+ print(shlex.join(tokens), file=outfile)

src/derivepassphrase/_internals/cli_machinery.py

Zeige Datei @ 623f749

...	...	@@ -0,0 +1,1196 @@
	1	+# SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>
	2	+#
	3	+# SPDX-License-Identifier: Zlib
	4	+
	5	+# ruff: noqa: TRY400
	6	+
	7	+"""Command-line machinery for derivepassphrase.
	8	+
	9	+Warning:
	10	+ Non-public module (implementation detail), provided for didactical and
	11	+ educational purposes only. Subject to change without notice, including
	12	+ removal.
	13	+
	14	+"""
	15	+
	16	+from __future__ import annotations
	17	+
	18	+import collections
	19	+import inspect
	20	+import logging
	21	+import os
	22	+import warnings
	23	+from typing import TYPE_CHECKING, Callable, Literal, TextIO, TypeVar
	24	+
	25	+import click
	26	+import click.shell_completion
	27	+from typing_extensions import Any, ParamSpec, override
	28	+
	29	+import derivepassphrase as dpp
	30	+from derivepassphrase._internals import cli_messages as _msg
	31	+
	32	+if TYPE_CHECKING:
	33	+ import types
	34	+ from collections.abc import (
	35	+ MutableSequence,
	36	+ )
	37	+
	38	+ from typing_extensions import Self
	39	+
	40	+__author__ = dpp.__author__
	41	+__version__ = dpp.__version__
	42	+
	43	+PROG_NAME = _msg.PROG_NAME
	44	+
	45	+# Error messages
	46	+NOT_AN_INTEGER = 'not an integer'
	47	+NOT_A_NONNEGATIVE_INTEGER = 'not a non-negative integer'
	48	+NOT_A_POSITIVE_INTEGER = 'not a positive integer'
	49	+
	50	+
	51	+# Logging
	52	+# =======
	53	+
	54	+
	55	+class ClickEchoStderrHandler(logging.Handler):
	56	+ """A [`logging.Handler`][] for `click` applications.
	57	+
	58	+ Outputs log messages to [`sys.stderr`][] via [`click.echo`][].
	59	+
	60	+ """
	61	+
	62	+ def emit(self, record: logging.LogRecord) -> None:
	63	+ """Emit a log record.
	64	+
	65	+ Format the log record, then emit it via [`click.echo`][] to
	66	+ [`sys.stderr`][].
	67	+
	68	+ """
	69	+ click.echo(
	70	+ self.format(record),
	71	+ err=True,
	72	+ color=getattr(record, 'color', None),
	73	+ )
	74	+
	75	+
	76	+class CLIofPackageFormatter(logging.Formatter):
	77	+ """A [`logging.LogRecord`][] formatter for the CLI of a Python package.
	78	+
	79	+ Assuming a package `PKG` and loggers within the same hierarchy
	80	+ `PKG`, format all log records from that hierarchy for proper user
	81	+ feedback on the console. Intended for use with [`click`][CLICK] and
	82	+ when `PKG` provides a command-line tool `PKG` and when logs from
	83	+ that package should show up as output of the command-line tool.
	84	+
	85	+ Essentially, this prepends certain short strings to the log message
	86	+ lines to make them readable as standard error output.
	87	+
	88	+ Because this log output is intended to be displayed on standard
	89	+ error as high-level diagnostic output, you are strongly discouraged
	90	+ from changing the output format to include more tokens besides the
	91	+ log message. Use a dedicated log file handler instead, without this
	92	+ formatter.
	93	+
	94	+ [CLICK]: https://pypi.org/projects/click/
	95	+
	96	+ """
	97	+
	98	+ def __init__(
	99	+ self,
	100	+ *,
	101	+ prog_name: str = PROG_NAME,
	102	+ package_name: str \| None = None,
	103	+ ) -> None:
	104	+ self.prog_name = prog_name
	105	+ self.package_name = (
	106	+ package_name
	107	+ if package_name is not None
	108	+ else prog_name.lower().replace(' ', '_').replace('-', '_')
	109	+ )
	110	+
	111	+ def format(self, record: logging.LogRecord) -> str:
	112	+ """Format a log record suitably for standard error console output.
	113	+
	114	+ Prepend the formatted string `"PROG_NAME: LABEL"` to each line
	115	+ of the message, where `PROG_NAME` is the program name, and
	116	+ `LABEL` depends on the record's level and on the logger name as
	117	+ follows:
	118	+
	119	+ * For records at level [`logging.DEBUG`][], `LABEL` is
	120	+ `"Debug: "`.
	121	+ * For records at level [`logging.INFO`][], `LABEL` is the
	122	+ empty string.
	123	+ * For records at level [`logging.WARNING`][], `LABEL` is
	124	+ `"Deprecation warning: "` if the logger is named
	125	+ `PKG.deprecation` (where `PKG` is the package name), else
	126	+ `"Warning: "`.
	127	+ * For records at level [`logging.ERROR`][] and
	128	+ [`logging.CRITICAL`][] `"Error: "`, `LABEL` is the empty
	129	+ string.
	130	+
	131	+ The level indication strings at level `WARNING` or above are
	132	+ highlighted. Use [`click.echo`][] to output them and remove
	133	+ color output if necessary.
	134	+
	135	+ Args:
	136	+ record: A log record.
	137	+
	138	+ Returns:
	139	+ A formatted log record.
	140	+
	141	+ Raises:
	142	+ AssertionError:
	143	+ The log level is not supported.
	144	+
	145	+ """
	146	+ preliminary_result = record.getMessage()
	147	+ prefix = f'{self.prog_name}: '
	148	+ if record.levelname == 'DEBUG': # pragma: no cover
	149	+ level_indicator = 'Debug: '
	150	+ elif record.levelname == 'INFO':
	151	+ level_indicator = ''
	152	+ elif record.levelname == 'WARNING':
	153	+ level_indicator = (
	154	+ f'{click.style("Deprecation warning", bold=True)}: '
	155	+ if record.name.endswith('.deprecation')
	156	+ else f'{click.style("Warning", bold=True)}: '
	157	+ )
	158	+ elif record.levelname in {'ERROR', 'CRITICAL'}:
	159	+ level_indicator = ''
	160	+ else: # pragma: no cover
	161	+ msg = f'Unsupported logging level: {record.levelname}'
	162	+ raise AssertionError(msg)
	163	+ parts = [
	164	+ ''.join(
	165	+ prefix + level_indicator + line
	166	+ for line in preliminary_result.splitlines(True) # noqa: FBT003
	167	+ )
	168	+ ]
	169	+ if record.exc_info:
	170	+ parts.append(self.formatException(record.exc_info) + '\n')
	171	+ return ''.join(parts)
	172	+
	173	+
	174	+class StandardCLILogging:
	175	+ """Set up CLI logging handlers upon instantiation."""
	176	+
	177	+ prog_name = PROG_NAME
	178	+ package_name = PROG_NAME.lower().replace(' ', '_').replace('-', '_')
	179	+ cli_formatter = CLIofPackageFormatter(
	180	+ prog_name=prog_name, package_name=package_name
	181	+ )
	182	+ cli_handler = ClickEchoStderrHandler()
	183	+ cli_handler.addFilter(logging.Filter(name=package_name))
	184	+ cli_handler.setFormatter(cli_formatter)
	185	+ cli_handler.setLevel(logging.WARNING)
	186	+ warnings_handler = ClickEchoStderrHandler()
	187	+ warnings_handler.addFilter(logging.Filter(name='py.warnings'))
	188	+ warnings_handler.setFormatter(cli_formatter)
	189	+ warnings_handler.setLevel(logging.WARNING)
	190	+
	191	+ @classmethod
	192	+ def ensure_standard_logging(cls) -> StandardLoggingContextManager:
	193	+ """Return a context manager to ensure standard logging is set up."""
	194	+ return StandardLoggingContextManager(
	195	+ handler=cls.cli_handler,
	196	+ root_logger=cls.package_name,
	197	+ )
	198	+
	199	+ @classmethod
	200	+ def ensure_standard_warnings_logging(
	201	+ cls,
	202	+ ) -> StandardWarningsLoggingContextManager:
	203	+ """Return a context manager to ensure warnings logging is set up."""
	204	+ return StandardWarningsLoggingContextManager(
	205	+ handler=cls.warnings_handler,
	206	+ )
	207	+
	208	+
	209	+class StandardLoggingContextManager:
	210	+ """A reentrant context manager setting up standard CLI logging.
	211	+
	212	+ Ensures that the given handler (defaulting to the CLI logging
	213	+ handler) is added to the named logger (defaulting to the root
	214	+ logger), and if it had to be added, then that it will be removed
	215	+ upon exiting the context.
	216	+
	217	+ Reentrant, but not thread safe, because it temporarily modifies
	218	+ global state.
	219	+
	220	+ """
	221	+
	222	+ def __init__(
	223	+ self,
	224	+ handler: logging.Handler,
	225	+ root_logger: str \| None = None,
	226	+ ) -> None:
	227	+ self.handler = handler
	228	+ self.root_logger_name = root_logger
	229	+ self.base_logger = logging.getLogger(self.root_logger_name)
	230	+ self.action_required: MutableSequence[bool] = collections.deque()
	231	+
	232	+ def __enter__(self) -> Self:
	233	+ self.action_required.append(
	234	+ self.handler not in self.base_logger.handlers
	235	+ )
	236	+ if self.action_required[-1]:
	237	+ self.base_logger.addHandler(self.handler)
	238	+ return self
	239	+
	240	+ def __exit__(
	241	+ self,
	242	+ exc_type: type[BaseException] \| None,
	243	+ exc_value: BaseException \| None,
	244	+ exc_tb: types.TracebackType \| None,
	245	+ ) -> Literal[False]:
	246	+ if self.action_required[-1]:
	247	+ self.base_logger.removeHandler(self.handler)
	248	+ self.action_required.pop()
	249	+ return False
	250	+
	251	+
	252	+class StandardWarningsLoggingContextManager(StandardLoggingContextManager):
	253	+ """A reentrant context manager setting up standard warnings logging.
	254	+
	255	+ Ensures that warnings are being diverted to the logging system, and
	256	+ that the given handler (defaulting to the CLI logging handler) is
	257	+ added to the warnings logger. If the handler had to be added, then
	258	+ it will be removed upon exiting the context.
	259	+
	260	+ Reentrant, but not thread safe, because it temporarily modifies
	261	+ global state.
	262	+
	263	+ """
	264	+
	265	+ def __init__(
	266	+ self,
	267	+ handler: logging.Handler,
	268	+ ) -> None:
	269	+ super().__init__(handler=handler, root_logger='py.warnings')
	270	+ self.stack: MutableSequence[
	271	+ tuple[
	272	+ Callable[
	273	+ [
	274	+ type[BaseException] \| None,
	275	+ BaseException \| None,
	276	+ types.TracebackType \| None,
	277	+ ],
	278	+ None,
	279	+ ],
	280	+ Callable[
	281	+ [
	282	+ str \| Warning,
	283	+ type[Warning],
	284	+ str,
	285	+ int,
	286	+ TextIO \| None,
	287	+ str \| None,
	288	+ ],
	289	+ None,
	290	+ ],
	291	+ ]
	292	+ ] = collections.deque()
	293	+
	294	+ def __enter__(self) -> Self:
	295	+ def showwarning( # noqa: PLR0913,PLR0917
	296	+ message: str \| Warning,
	297	+ category: type[Warning],
	298	+ filename: str,
	299	+ lineno: int,
	300	+ file: TextIO \| None = None,
	301	+ line: str \| None = None,
	302	+ ) -> None:
	303	+ if file is not None: # pragma: no cover
	304	+ self.stack[0][1](
	305	+ message, category, filename, lineno, file, line
	306	+ )
	307	+ else:
	308	+ logging.getLogger('py.warnings').warning(
	309	+ str(
	310	+ warnings.formatwarning(
	311	+ message, category, filename, lineno, line
	312	+ )
	313	+ )
	314	+ )
	315	+
	316	+ ctx = warnings.catch_warnings()
	317	+ exit_func = ctx.__exit__
	318	+ ctx.__enter__()
	319	+ self.stack.append((exit_func, warnings.showwarning))
	320	+ warnings.showwarning = showwarning
	321	+ return super().__enter__()
	322	+
	323	+ def __exit__(
	324	+ self,
	325	+ exc_type: type[BaseException] \| None,
	326	+ exc_value: BaseException \| None,
	327	+ exc_tb: types.TracebackType \| None,
	328	+ ) -> Literal[False]:
	329	+ ret = super().__exit__(exc_type, exc_value, exc_tb)
	330	+ val = self.stack.pop()[0](exc_type, exc_value, exc_tb)
	331	+ assert not val
	332	+ return ret
	333	+
	334	+
	335	+P = ParamSpec('P')
	336	+R = TypeVar('R')
	337	+
	338	+
	339	+def adjust_logging_level(
	340	+ ctx: click.Context,
	341	+ /,
	342	+ param: click.Parameter \| None = None,
	343	+ value: int \| None = None,
	344	+) -> None:
	345	+ """Change the logs that are emitted to standard error.
	346	+
	347	+ This modifies the [`StandardCLILogging`][] settings such that log
	348	+ records at the respective level are emitted, based on the `param`
	349	+ and the `value`.
	350	+
	351	+ """
	352	+ # Note: If multiple options use this callback, then we will be
	353	+ # called multiple times. Ensure the runs are idempotent.
	354	+ if param is None or value is None or ctx.resilient_parsing:
	355	+ return
	356	+ StandardCLILogging.cli_handler.setLevel(value)
	357	+ logging.getLogger(StandardCLILogging.package_name).setLevel(value)
	358	+
	359	+
	360	+# Option parsing and grouping
	361	+# ===========================
	362	+
	363	+
	364	+class OptionGroupOption(click.Option):
	365	+ """A [`click.Option`][] with an associated group name and group epilog.
	366	+
	367	+ Used by [`CommandWithHelpGroups`][] to print help sections. Each
	368	+ subclass contains its own group name and epilog.
	369	+
	370	+ Attributes:
	371	+ option_group_name:
	372	+ The name of the option group. Used as a heading on the help
	373	+ text for options in this section.
	374	+ epilog:
	375	+ An epilog to print after listing the options in this
	376	+ section.
	377	+
	378	+ """
	379	+
	380	+ option_group_name: object = ''
	381	+ """"""
	382	+ epilog: object = ''
	383	+ """"""
	384	+
	385	+ def __init__(self, args: Any, *kwargs: Any) -> None: # noqa: ANN401
	386	+ if self.__class__ == __class__: # type: ignore[name-defined]
	387	+ raise NotImplementedError
	388	+ # Though click 8.1 mostly defers help text processing until the
	389	+ # `BaseCommand.format_*` methods are called, the Option
	390	+ # constructor still preprocesses the help text, and asserts that
	391	+ # the help text is a string. Work around this by removing the
	392	+ # help text from the constructor arguments and re-adding it,
	393	+ # unprocessed, after constructor finishes.
	394	+ unset = object()
	395	+ help = kwargs.pop('help', unset) # noqa: A001
	396	+ super().__init__(args, *kwargs)
	397	+ if help is not unset: # pragma: no branch
	398	+ self.help = help
	399	+
	400	+
	401	+class StandardOption(OptionGroupOption):
	402	+ pass
	403	+
	404	+
	405	+# Portions of this class are based directly on code from click 8.1.
	406	+# (This does not in general include docstrings, unless otherwise noted.)
	407	+# They are subject to the 3-clause BSD license in the following
	408	+# paragraphs. Modifications to their code are marked with respective
	409	+# comments; they too are released under the same license below. The
	410	+# original code did not contain any "noqa" or "pragma" comments.
	411	+#
	412	+# Copyright 2024 Pallets
	413	+#
	414	+# Redistribution and use in source and binary forms, with or
	415	+# without modification, are permitted provided that the
	416	+# following conditions are met:
	417	+#
	418	+# 1. Redistributions of source code must retain the above
	419	+# copyright notice, this list of conditions and the
	420	+# following disclaimer.
	421	+#
	422	+# 2. Redistributions in binary form must reproduce the above
	423	+# copyright notice, this list of conditions and the
	424	+# following disclaimer in the documentation and/or other
	425	+# materials provided with the distribution.
	426	+#
	427	+# 3. Neither the name of the copyright holder nor the names
	428	+# of its contributors may be used to endorse or promote
	429	+# products derived from this software without specific
	430	+# prior written permission.
	431	+#
	432	+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
	433	+# CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
	434	+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
	435	+# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	436	+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
	437	+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	438	+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	439	+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
	440	+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	441	+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	442	+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	443	+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	444	+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	445	+class CommandWithHelpGroups(click.Command):
	446	+ """A [`click.Command`][] with support for some help text customizations.
	447	+
	448	+ Supports help/option groups, group epilogs, and help text objects
	449	+ (objects that stringify to help texts). The latter is primarily
	450	+ used to implement translations.
	451	+
	452	+ Inspired by [a comment on `pallets/click#373`][CLICK_ISSUE] for
	453	+ help/option group support, and further modified to include group
	454	+ epilogs and help text objects.
	455	+
	456	+ [CLICK_ISSUE]: https://github.com/pallets/click/issues/373#issuecomment-515293746
	457	+
	458	+ """
	459	+
	460	+ @staticmethod
	461	+ def _text(text: object, /) -> str:
	462	+ if isinstance(text, (list, tuple)):
	463	+ return '\n\n'.join(str(x) for x in text)
	464	+ return str(text)
	465	+
	466	+ # This method is based on click 8.1; see the comment above the class
	467	+ # declaration for license details.
	468	+ def collect_usage_pieces(self, ctx: click.Context) -> list[str]:
	469	+ """Return the pieces for the usage string.
	470	+
	471	+ Args:
	472	+ ctx:
	473	+ The click context.
	474	+
	475	+ """
	476	+ rv = [str(self.options_metavar)] if self.options_metavar else []
	477	+ for param in self.get_params(ctx):
	478	+ rv.extend(str(x) for x in param.get_usage_pieces(ctx))
	479	+ return rv
	480	+
	481	+ # This method is based on click 8.1; see the comment above the class
	482	+ # declaration for license details.
	483	+ def get_help_option(
	484	+ self,
	485	+ ctx: click.Context,
	486	+ ) -> click.Option \| None:
	487	+ """Return a standard help option object.
	488	+
	489	+ Args:
	490	+ ctx:
	491	+ The click context.
	492	+
	493	+ """
	494	+ help_options = self.get_help_option_names(ctx)
	495	+
	496	+ if not help_options or not self.add_help_option: # pragma: no cover
	497	+ return None
	498	+
	499	+ def show_help(
	500	+ ctx: click.Context,
	501	+ param: click.Parameter, # noqa: ARG001
	502	+ value: str,
	503	+ ) -> None:
	504	+ if value and not ctx.resilient_parsing:
	505	+ click.echo(ctx.get_help(), color=ctx.color)
	506	+ ctx.exit()
	507	+
	508	+ # Modified from click 8.1: We use StandardOption and a non-str
	509	+ # object as the help string.
	510	+ return StandardOption(
	511	+ help_options,
	512	+ is_flag=True,
	513	+ is_eager=True,
	514	+ expose_value=False,
	515	+ callback=show_help,
	516	+ help=_msg.TranslatedString(_msg.Label.HELP_OPTION_HELP_TEXT),
	517	+ )
	518	+
	519	+ # This method is based on click 8.1; see the comment above the class
	520	+ # declaration for license details.
	521	+ def get_short_help_str(
	522	+ self,
	523	+ limit: int = 45,
	524	+ ) -> str:
	525	+ """Return the short help string for a command.
	526	+
	527	+ If only a long help string is given, shorten it.
	528	+
	529	+ Args:
	530	+ limit:
	531	+ The maximum width of the short help string.
	532	+
	533	+ """
	534	+ # Modification against click 8.1: Call `_text()` on `self.help`
	535	+ # to allow help texts to be general objects, not just strings.
	536	+ # Used to implement translatable strings, as objects that
	537	+ # stringify to the translation.
	538	+ if self.short_help: # pragma: no cover
	539	+ text = inspect.cleandoc(self._text(self.short_help))
	540	+ elif self.help:
	541	+ text = click.utils.make_default_short_help(
	542	+ self._text(self.help), limit
	543	+ )
	544	+ else: # pragma: no cover
	545	+ text = ''
	546	+ if self.deprecated: # pragma: no cover
	547	+ # Modification against click 8.1: The translated string is
	548	+ # looked up in the derivepassphrase message domain, not the
	549	+ # gettext default domain.
	550	+ text = str(
	551	+ _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
	552	+ ).format(text=text)
	553	+ return text.strip()
	554	+
	555	+ # This method is based on click 8.1; see the comment above the class
	556	+ # declaration for license details.
	557	+ def format_help_text(
	558	+ self,
	559	+ ctx: click.Context,
	560	+ formatter: click.HelpFormatter,
	561	+ ) -> None:
	562	+ """Format the help text prologue, if any.
	563	+
	564	+ Args:
	565	+ ctx:
	566	+ The click context.
	567	+ formatter:
	568	+ The formatter for the `--help` listing.
	569	+
	570	+ """
	571	+ del ctx
	572	+ # Modification against click 8.1: Call `_text()` on `self.help`
	573	+ # to allow help texts to be general objects, not just strings.
	574	+ # Used to implement translatable strings, as objects that
	575	+ # stringify to the translation.
	576	+ text = (
	577	+ inspect.cleandoc(self._text(self.help).partition('\f')[0])
	578	+ if self.help is not None
	579	+ else ''
	580	+ )
	581	+ if self.deprecated: # pragma: no cover
	582	+ # Modification against click 8.1: The translated string is
	583	+ # looked up in the derivepassphrase message domain, not the
	584	+ # gettext default domain.
	585	+ text = str(
	586	+ _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
	587	+ ).format(text=text)
	588	+ if text: # pragma: no branch
	589	+ formatter.write_paragraph()
	590	+ with formatter.indentation():
	591	+ formatter.write_text(text)
	592	+
	593	+ # This method is based on click 8.1; see the comment above the class
	594	+ # declaration for license details. Consider the whole section
	595	+ # marked as modified; the code modifications are too numerous to
	596	+ # mark individually.
	597	+ def format_options(
	598	+ self,
	599	+ ctx: click.Context,
	600	+ formatter: click.HelpFormatter,
	601	+ ) -> None:
	602	+ r"""Format options on the help listing, grouped into sections.
	603	+
	604	+ This is a callback for [`click.Command.get_help`][] that
	605	+ implements the `--help` listing, by calling appropriate methods
	606	+ of the `formatter`. We list all options (like the base
	607	+ implementation), but grouped into sections according to the
	608	+ concrete [`click.Option`][] subclass being used. If the option
	609	+ is an instance of some subclass of [`OptionGroupOption`][], then
	610	+ the section heading and the epilog are taken from the
	611	+ [`option_group_name`] [OptionGroupOption.option_group_name] and
	612	+ [`epilog`] [OptionGroupOption.epilog] attributes; otherwise, the
	613	+ section heading is "Options" (or "Other options" if there are
	614	+ other option groups) and the epilog is empty.
	615	+
	616	+ We unconditionally call [`format_commands`][], and rely on it to
	617	+ act as a no-op if we aren't actually a [`click.MultiCommand`][].
	618	+
	619	+ Args:
	620	+ ctx:
	621	+ The click context.
	622	+ formatter:
	623	+ The formatter for the `--help` listing.
	624	+
	625	+ """
	626	+ default_group_name = ''
	627	+ help_records: dict[str, list[tuple[str, str]]] = {}
	628	+ epilogs: dict[str, str] = {}
	629	+ params = self.params[:]
	630	+ if ( # pragma: no branch
	631	+ (help_opt := self.get_help_option(ctx)) is not None
	632	+ and help_opt not in params
	633	+ ):
	634	+ params.append(help_opt)
	635	+ for param in params:
	636	+ rec = param.get_help_record(ctx)
	637	+ if rec is not None:
	638	+ rec = (rec[0], self._text(rec[1]))
	639	+ if isinstance(param, OptionGroupOption):
	640	+ group_name = self._text(param.option_group_name)
	641	+ epilogs.setdefault(group_name, self._text(param.epilog))
	642	+ else: # pragma: no cover
	643	+ group_name = default_group_name
	644	+ help_records.setdefault(group_name, []).append(rec)
	645	+ if default_group_name in help_records: # pragma: no branch
	646	+ default_group = help_records.pop(default_group_name)
	647	+ default_group_label = (
	648	+ _msg.Label.OTHER_OPTIONS_LABEL
	649	+ if len(default_group) > 1
	650	+ else _msg.Label.OPTIONS_LABEL
	651	+ )
	652	+ default_group_name = self._text(
	653	+ _msg.TranslatedString(default_group_label)
	654	+ )
	655	+ help_records[default_group_name] = default_group
	656	+ for group_name, records in help_records.items():
	657	+ with formatter.section(group_name):
	658	+ formatter.write_dl(records)
	659	+ epilog = inspect.cleandoc(epilogs.get(group_name, ''))
	660	+ if epilog:
	661	+ formatter.write_paragraph()
	662	+ with formatter.indentation():
	663	+ formatter.write_text(epilog)
	664	+ self.format_commands(ctx, formatter)
	665	+
	666	+ # This method is based on click 8.1; see the comment above the class
	667	+ # declaration for license details. Consider the whole section
	668	+ # marked as modified; the code modifications are too numerous to
	669	+ # mark individually.
	670	+ def format_commands(
	671	+ self,
	672	+ ctx: click.Context,
	673	+ formatter: click.HelpFormatter,
	674	+ ) -> None:
	675	+ """Format the subcommands, if any.
	676	+
	677	+ If called on a command object that isn't derived from
	678	+ [`click.MultiCommand`][], then do nothing.
	679	+
	680	+ Args:
	681	+ ctx:
	682	+ The click context.
	683	+ formatter:
	684	+ The formatter for the `--help` listing.
	685	+
	686	+ """
	687	+ if not isinstance(self, click.MultiCommand):
	688	+ return
	689	+ commands: list[tuple[str, click.Command]] = []
	690	+ for subcommand in self.list_commands(ctx):
	691	+ cmd = self.get_command(ctx, subcommand)
	692	+ if cmd is None or cmd.hidden: # pragma: no cover
	693	+ continue
	694	+ commands.append((subcommand, cmd))
	695	+ if commands: # pragma: no branch
	696	+ longest_command = max((cmd[0] for cmd in commands), key=len)
	697	+ limit = formatter.width - 6 - len(longest_command)
	698	+ rows: list[tuple[str, str]] = []
	699	+ for subcommand, cmd in commands:
	700	+ help_str = self._text(cmd.get_short_help_str(limit) or '')
	701	+ rows.append((subcommand, help_str))
	702	+ if rows: # pragma: no branch
	703	+ commands_label = self._text(
	704	+ _msg.TranslatedString(_msg.Label.COMMANDS_LABEL)
	705	+ )
	706	+ with formatter.section(commands_label):
	707	+ formatter.write_dl(rows)
	708	+
	709	+ # This method is based on click 8.1; see the comment above the class
	710	+ # declaration for license details.
	711	+ def format_epilog(
	712	+ self,
	713	+ ctx: click.Context,
	714	+ formatter: click.HelpFormatter,
	715	+ ) -> None:
	716	+ """Format the epilog, if any.
	717	+
	718	+ Args:
	719	+ ctx:
	720	+ The click context.
	721	+ formatter:
	722	+ The formatter for the `--help` listing.
	723	+
	724	+ """
	725	+ del ctx
	726	+ if self.epilog: # pragma: no branch
	727	+ # Modification against click 8.1: Call `str()` on
	728	+ # `self.epilog` to allow help texts to be general objects,
	729	+ # not just strings. Used to implement translatable strings,
	730	+ # as objects that stringify to the translation.
	731	+ epilog = inspect.cleandoc(self._text(self.epilog))
	732	+ formatter.write_paragraph()
	733	+ with formatter.indentation():
	734	+ formatter.write_text(epilog)
	735	+
	736	+
	737	+# Portions of this class are based directly on code from click 8.1.
	738	+# (This does not in general include docstrings, unless otherwise noted.)
	739	+# They are subject to the 3-clause BSD license in the following
	740	+# paragraphs. Modifications to their code are marked with respective
	741	+# comments; they too are released under the same license below. The
	742	+# original code did not contain any "noqa" or "pragma" comments.
	743	+#
	744	+# Copyright 2024 Pallets
	745	+#
	746	+# Redistribution and use in source and binary forms, with or
	747	+# without modification, are permitted provided that the
	748	+# following conditions are met:
	749	+#
	750	+# 1. Redistributions of source code must retain the above
	751	+# copyright notice, this list of conditions and the
	752	+# following disclaimer.
	753	+#
	754	+# 2. Redistributions in binary form must reproduce the above
	755	+# copyright notice, this list of conditions and the
	756	+# following disclaimer in the documentation and/or other
	757	+# materials provided with the distribution.
	758	+#
	759	+# 3. Neither the name of the copyright holder nor the names
	760	+# of its contributors may be used to endorse or promote
	761	+# products derived from this software without specific
	762	+# prior written permission.
	763	+#
	764	+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
	765	+# CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
	766	+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
	767	+# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	768	+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
	769	+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	770	+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	771	+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
	772	+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	773	+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	774	+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	775	+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	776	+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	777	+#
	778	+# TODO(the-13th-letter): Remove this class and license block in v1.0.
	779	+# https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#v1.0-implied-subcommands
	780	+class DefaultToVaultGroup(CommandWithHelpGroups, click.Group):
	781	+ """A helper class to implement the default-to-"vault"-subcommand behavior.
	782	+
	783	+ Modifies internal [`click.MultiCommand`][] methods, and thus is both
	784	+ an implementation detail and a kludge.
	785	+
	786	+ """
	787	+
	788	+ def resolve_command(
	789	+ self, ctx: click.Context, args: list[str]
	790	+ ) -> tuple[str \| None, click.Command \| None, list[str]]:
	791	+ """Resolve a command, defaulting to "vault" instead of erroring out.""" # noqa: DOC201
	792	+ cmd_name = click.utils.make_str(args[0])
	793	+
	794	+ # Get the command
	795	+ cmd = self.get_command(ctx, cmd_name)
	796	+
	797	+ # If we can't find the command but there is a normalization
	798	+ # function available, we try with that one.
	799	+ if ( # pragma: no cover
	800	+ cmd is None and ctx.token_normalize_func is not None
	801	+ ):
	802	+ cmd_name = ctx.token_normalize_func(cmd_name)
	803	+ cmd = self.get_command(ctx, cmd_name)
	804	+
	805	+ # If we don't find the command we want to show an error message
	806	+ # to the user that it was not provided. However, there is
	807	+ # something else we should do: if the first argument looks like
	808	+ # an option we want to kick off parsing again for arguments to
	809	+ # resolve things like --help which now should go to the main
	810	+ # place.
	811	+ if cmd is None and not ctx.resilient_parsing:
	812	+ if click.parser.split_opt(cmd_name)[0]:
	813	+ self.parse_args(ctx, ctx.args)
	814	+ ####
	815	+ # BEGIN modifications for derivepassphrase
	816	+ #
	817	+ # Instead of calling ctx.fail here, default to "vault", and
	818	+ # issue a deprecation warning.
	819	+ deprecation = logging.getLogger(f'{PROG_NAME}.deprecation')
	820	+ deprecation.warning(
	821	+ _msg.TranslatedString(
	822	+ _msg.WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED
	823	+ )
	824	+ )
	825	+ cmd_name = 'vault'
	826	+ cmd = self.get_command(ctx, cmd_name)
	827	+ assert cmd is not None, 'Mandatory subcommand "vault" missing!'
	828	+ args = [cmd_name, *args]
	829	+ #
	830	+ # END modifications for derivepassphrase
	831	+ ####
	832	+ return cmd_name if cmd else None, cmd, args[1:]
	833	+
	834	+
	835	+# TODO(the-13th-letter): Base this class on CommandWithHelpGroups and
	836	+# click.Group in v1.0.
	837	+# https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#v1.0-implied-subcommands
	838	+class TopLevelCLIEntryPoint(DefaultToVaultGroup):
	839	+ """A minor variation of DefaultToVaultGroup for the top-level command.
	840	+
	841	+ When called as a function, this sets up the environment properly
	842	+ before invoking the actual callbacks. Currently, this means setting
	843	+ up the logging subsystem and the delegation of Python warnings to
	844	+ the logging subsystem.
	845	+
	846	+ The environment setup can be bypassed by calling the `.main` method
	847	+ directly.
	848	+
	849	+ """
	850	+
	851	+ def __call__( # pragma: no cover
	852	+ self,
	853	+ *args: Any, # noqa: ANN401
	854	+ **kwargs: Any, # noqa: ANN401
	855	+ ) -> Any: # noqa: ANN401
	856	+ """""" # noqa: D419
	857	+ # Coverage testing is done with the `click.testing` module,
	858	+ # which does not use the `__call__` shortcut. So it is normal
	859	+ # that this function is never called, and thus should be
	860	+ # excluded from coverage.
	861	+ with (
	862	+ StandardCLILogging.ensure_standard_logging(),
	863	+ StandardCLILogging.ensure_standard_warnings_logging(),
	864	+ ):
	865	+ return self.main(args, *kwargs)
	866	+
	867	+
	868	+# Actual option groups and callbacks used by derivepassphrase
	869	+# ===========================================================
	870	+
	871	+def color_forcing_callback(
	872	+ ctx: click.Context,
	873	+ param: click.Parameter,
	874	+ value: Any, # noqa: ANN401
	875	+) -> None:
	876	+ """Force the `click` context to honor `NO_COLOR` and `FORCE_COLOR`."""
	877	+ del param, value
	878	+ if os.environ.get('NO_COLOR'):
	879	+ ctx.color = False
	880	+ if os.environ.get('FORCE_COLOR'):
	881	+ ctx.color = True
	882	+
	883	+
	884	+def validate_occurrence_constraint(
	885	+ ctx: click.Context,
	886	+ param: click.Parameter,
	887	+ value: Any, # noqa: ANN401
	888	+) -> int \| None:
	889	+ """Check that the occurrence constraint is valid (int, 0 or larger).
	890	+
	891	+ Args:
	892	+ ctx: The `click` context.
	893	+ param: The current command-line parameter.
	894	+ value: The parameter value to be checked.
	895	+
	896	+ Returns:
	897	+ The parsed parameter value.
	898	+
	899	+ Raises:
	900	+ click.BadParameter: The parameter value is invalid.
	901	+
	902	+ """
	903	+ del ctx # Unused.
	904	+ del param # Unused.
	905	+ if value is None:
	906	+ return value
	907	+ if isinstance(value, int):
	908	+ int_value = value
	909	+ else:
	910	+ try:
	911	+ int_value = int(value, 10)
	912	+ except ValueError as exc:
	913	+ raise click.BadParameter(NOT_AN_INTEGER) from exc
	914	+ if int_value < 0:
	915	+ raise click.BadParameter(NOT_A_NONNEGATIVE_INTEGER)
	916	+ return int_value
	917	+
	918	+
	919	+def validate_length(
	920	+ ctx: click.Context,
	921	+ param: click.Parameter,
	922	+ value: Any, # noqa: ANN401
	923	+) -> int \| None:
	924	+ """Check that the length is valid (int, 1 or larger).
	925	+
	926	+ Args:
	927	+ ctx: The `click` context.
	928	+ param: The current command-line parameter.
	929	+ value: The parameter value to be checked.
	930	+
	931	+ Returns:
	932	+ The parsed parameter value.
	933	+
	934	+ Raises:
	935	+ click.BadParameter: The parameter value is invalid.
	936	+
	937	+ """
	938	+ del ctx # Unused.
	939	+ del param # Unused.
	940	+ if value is None:
	941	+ return value
	942	+ if isinstance(value, int):
	943	+ int_value = value
	944	+ else:
	945	+ try:
	946	+ int_value = int(value, 10)
	947	+ except ValueError as exc:
	948	+ raise click.BadParameter(NOT_AN_INTEGER) from exc
	949	+ if int_value < 1:
	950	+ raise click.BadParameter(NOT_A_POSITIVE_INTEGER)
	951	+ return int_value
	952	+
	953	+
	954	+def version_option_callback(
	955	+ ctx: click.Context,
	956	+ param: click.Parameter,
	957	+ value: bool, # noqa: FBT001
	958	+) -> None:
	959	+ del param
	960	+ if value and not ctx.resilient_parsing:
	961	+ click.echo(
	962	+ str(
	963	+ _msg.TranslatedString(
	964	+ _msg.Label.VERSION_INFO_TEXT,
	965	+ PROG_NAME=PROG_NAME,
	966	+ __version__=__version__,
	967	+ )
	968	+ ),
	969	+ )
	970	+ ctx.exit()
	971	+
	972	+
	973	+def version_option(f: Callable[P, R]) -> Callable[P, R]:
	974	+ return click.option(
	975	+ '--version',
	976	+ is_flag=True,
	977	+ is_eager=True,
	978	+ expose_value=False,
	979	+ callback=version_option_callback,
	980	+ cls=StandardOption,
	981	+ help=_msg.TranslatedString(_msg.Label.VERSION_OPTION_HELP_TEXT),
	982	+ )(f)
	983	+
	984	+
	985	+color_forcing_pseudo_option = click.option(
	986	+ '--_pseudo-option-color-forcing',
	987	+ '_color_forcing',
	988	+ is_flag=True,
	989	+ is_eager=True,
	990	+ expose_value=False,
	991	+ hidden=True,
	992	+ callback=color_forcing_callback,
	993	+ help='(pseudo-option)',
	994	+)
	995	+
	996	+
	997	+class PassphraseGenerationOption(OptionGroupOption):
	998	+ """Passphrase generation options for the CLI."""
	999	+
	1000	+ option_group_name = _msg.TranslatedString(
	1001	+ _msg.Label.PASSPHRASE_GENERATION_LABEL
	1002	+ )
	1003	+ epilog = _msg.TranslatedString(
	1004	+ _msg.Label.PASSPHRASE_GENERATION_EPILOG,
	1005	+ metavar=_msg.TranslatedString(
	1006	+ _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
	1007	+ ),
	1008	+ )
	1009	+
	1010	+
	1011	+class ConfigurationOption(OptionGroupOption):
	1012	+ """Configuration options for the CLI."""
	1013	+
	1014	+ option_group_name = _msg.TranslatedString(_msg.Label.CONFIGURATION_LABEL)
	1015	+ epilog = _msg.TranslatedString(_msg.Label.CONFIGURATION_EPILOG)
	1016	+
	1017	+
	1018	+class StorageManagementOption(OptionGroupOption):
	1019	+ """Storage management options for the CLI."""
	1020	+
	1021	+ option_group_name = _msg.TranslatedString(
	1022	+ _msg.Label.STORAGE_MANAGEMENT_LABEL
	1023	+ )
	1024	+ epilog = _msg.TranslatedString(
	1025	+ _msg.Label.STORAGE_MANAGEMENT_EPILOG,
	1026	+ metavar=_msg.TranslatedString(
	1027	+ _msg.Label.STORAGE_MANAGEMENT_METAVAR_PATH
	1028	+ ),
	1029	+ )
	1030	+
	1031	+
	1032	+class CompatibilityOption(OptionGroupOption):
	1033	+ """Compatibility and incompatibility options for the CLI."""
	1034	+
	1035	+ option_group_name = _msg.TranslatedString(
	1036	+ _msg.Label.COMPATIBILITY_OPTION_LABEL
	1037	+ )
	1038	+
	1039	+
	1040	+class LoggingOption(OptionGroupOption):
	1041	+ """Logging options for the CLI."""
	1042	+
	1043	+ option_group_name = _msg.TranslatedString(_msg.Label.LOGGING_LABEL)
	1044	+ epilog = ''
	1045	+
	1046	+
	1047	+debug_option = click.option(
	1048	+ '--debug',
	1049	+ 'logging_level',
	1050	+ is_flag=True,
	1051	+ flag_value=logging.DEBUG,
	1052	+ expose_value=False,
	1053	+ callback=adjust_logging_level,
	1054	+ help=_msg.TranslatedString(_msg.Label.DEBUG_OPTION_HELP_TEXT),
	1055	+ cls=LoggingOption,
	1056	+)
	1057	+verbose_option = click.option(
	1058	+ '-v',
	1059	+ '--verbose',
	1060	+ 'logging_level',
	1061	+ is_flag=True,
	1062	+ flag_value=logging.INFO,
	1063	+ expose_value=False,
	1064	+ callback=adjust_logging_level,
	1065	+ help=_msg.TranslatedString(_msg.Label.VERBOSE_OPTION_HELP_TEXT),
	1066	+ cls=LoggingOption,
	1067	+)
	1068	+quiet_option = click.option(
	1069	+ '-q',
	1070	+ '--quiet',
	1071	+ 'logging_level',
	1072	+ is_flag=True,
	1073	+ flag_value=logging.ERROR,
	1074	+ expose_value=False,
	1075	+ callback=adjust_logging_level,
	1076	+ help=_msg.TranslatedString(_msg.Label.QUIET_OPTION_HELP_TEXT),
	1077	+ cls=LoggingOption,
	1078	+)
	1079	+
	1080	+
	1081	+def standard_logging_options(f: Callable[P, R]) -> Callable[P, R]:
	1082	+ """Decorate the function with standard logging click options.
	1083	+
	1084	+ Adds the three click options `-v`/`--verbose`, `-q`/`--quiet` and
	1085	+ `--debug`, which calls back into the [`adjust_logging_level`][]
	1086	+ function (with different argument values).
	1087	+
	1088	+ Args:
	1089	+ f: A callable to decorate.
	1090	+
	1091	+ Returns:
	1092	+ The decorated callable.
	1093	+
	1094	+ """
	1095	+ return debug_option(verbose_option(quiet_option(f)))
	1096	+
	1097	+
	1098	+# Shell completion
	1099	+# ================
	1100	+
	1101	+# TODO(the-13th-letter): Remove this once upstream click's Zsh completion
	1102	+# script properly supports colons.
	1103	+#
	1104	+# https://github.com/pallets/click/pull/2846
	1105	+class ZshComplete(click.shell_completion.ZshComplete):
	1106	+ """Zsh completion class that supports colons.
	1107	+
	1108	+ `click`'s Zsh completion class (at least v8.1.7 and v8.1.8) uses
	1109	+ some completion helper functions (provided by Zsh) that parse each
	1110	+ completion item into value-description pairs, separated by a colon.
	1111	+ Other completion helper functions don't. Correspondingly, any
	1112	+ internal colons in the completion item's value sometimes need to be
	1113	+ escaped, and sometimes don't.
	1114	+
	1115	+ The "right" way to fix this is to modify the Zsh completion script
	1116	+ to only use one type of serialization: either escaped, or unescaped.
	1117	+ However, the Zsh completion script itself may already be installed
	1118	+ in the user's Zsh settings, and we have no way of knowing that.
	1119	+ Therefore, it is better to change the `format_completion` method to
	1120	+ adaptively and "smartly" emit colon-escaped output or not, based on
	1121	+ whether the completion script will be using it.
	1122	+
	1123	+ """
	1124	+
	1125	+ @override
	1126	+ def format_completion(
	1127	+ self,
	1128	+ item: click.shell_completion.CompletionItem,
	1129	+ ) -> str:
	1130	+ """Return a suitable serialization of the CompletionItem.
	1131	+
	1132	+ This serialization ensures colons in the item value are properly
	1133	+ escaped if and only if the completion script will attempt to
	1134	+ pass a colon-separated key/description pair to the underlying
	1135	+ Zsh machinery. This is the case if and only if the help text is
	1136	+ non-degenerate.
	1137	+
	1138	+ """
	1139	+ help_ = item.help or '_'
	1140	+ value = item.value.replace(':', r'\:' if help_ != '_' else ':')
	1141	+ return f'{item.type}\n{value}\n{help_}'
	1142	+
	1143	+
	1144	+# Our ZshComplete class depends crucially on the exact shape of the Zsh
	1145	+# completion script. So only fix the completion formatter if the
	1146	+# completion script is still the same.
	1147	+#
	1148	+# (This Zsh script is part of click, and available under the
	1149	+# 3-clause-BSD license.)
	1150	+_ORIG_SOURCE_TEMPLATE = """\
	1151	+#compdef %(prog_name)s
	1152	+
	1153	+%(complete_func)s() {
	1154	+ local -a completions
	1155	+ local -a completions_with_descriptions
	1156	+ local -a response
	1157	+ (( ! $+commands[%(prog_name)s] )) && return 1
	1158	+
	1159	+ response=("${(@f)$(env COMP_WORDS="${words[*]}" COMP_CWORD=$((CURRENT-1)) \
	1160	+%(complete_var)s=zsh_complete %(prog_name)s)}")
	1161	+
	1162	+ for type key descr in ${response}; do
	1163	+ if [[ "$type" == "plain" ]]; then
	1164	+ if [[ "$descr" == "_" ]]; then
	1165	+ completions+=("$key")
	1166	+ else
	1167	+ completions_with_descriptions+=("$key":"$descr")
	1168	+ fi
	1169	+ elif [[ "$type" == "dir" ]]; then
	1170	+ _path_files -/
	1171	+ elif [[ "$type" == "file" ]]; then
	1172	+ _path_files -f
	1173	+ fi
	1174	+ done
	1175	+
	1176	+ if [ -n "$completions_with_descriptions" ]; then
	1177	+ _describe -V unsorted completions_with_descriptions -U
	1178	+ fi
	1179	+
	1180	+ if [ -n "$completions" ]; then
	1181	+ compadd -U -V unsorted -a completions
	1182	+ fi
	1183	+}
	1184	+
	1185	+if [[ $zsh_eval_context[-1] == loadautofunc ]]; then
	1186	+ # autoload from fpath, call function directly
	1187	+ %(complete_func)s "$@"
	1188	+else
	1189	+ # eval/source/. command, register function for later
	1190	+ compdef %(complete_func)s %(prog_name)s
	1191	+fi
	1192	+"""
	1193	+if (
	1194	+ click.shell_completion.ZshComplete.source_template == _ORIG_SOURCE_TEMPLATE
	1195	+): # pragma: no cover
	1196	+ click.shell_completion.add_completion_class(ZshComplete)

src/derivepassphrase/cli.py

Zeige Datei @ 623f749

@@ -10,25 +10,15 @@ from __future__ import annotations
 
 import base64
 import collections
-import copy
-import enum
 import functools
-import inspect
 import json
 import logging
 import os
-import pathlib
-import shlex
-import sys
-import unicodedata
-import warnings
 from typing import (
     TYPE_CHECKING,
-    Callable,
     Literal,
     NoReturn,
     TextIO,
-    TypeVar,
     cast,
 )
 
@@ -36,26 +26,15 @@ import click
 import click.shell_completion
 from typing_extensions import (
     Any,
-    ParamSpec,
-    Self,
-    override,
 )
 
 import derivepassphrase as dpp
 from derivepassphrase import _types, exporter, ssh_agent, vault
+from derivepassphrase._internals import cli_helpers, cli_machinery
 from derivepassphrase._internals import cli_messages as _msg
 
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
-
 if TYPE_CHECKING:
-    import socket
-    import types
     from collections.abc import (
-        Iterator,
-        MutableSequence,
         Sequence,
     )
 
@@ -65,1141 +44,6 @@ __version__ = dpp.__version__
 __all__ = ('derivepassphrase',)
 
 PROG_NAME = _msg.PROG_NAME
-KEY_DISPLAY_LENGTH = 50
-
-# Error messages
-_INVALID_VAULT_CONFIG = 'Invalid vault config'
-_AGENT_COMMUNICATION_ERROR = 'Error communicating with the SSH agent'
-_NO_SUITABLE_KEYS = 'No suitable SSH keys were found'
-_EMPTY_SELECTION = 'Empty selection'
-_NOT_AN_INTEGER = 'not an integer'
-_NOT_A_NONNEGATIVE_INTEGER = 'not a non-negative integer'
-_NOT_A_POSITIVE_INTEGER = 'not a positive integer'
-
-
-# Logging
-# =======
-
-
-class ClickEchoStderrHandler(logging.Handler):
-    """A [`logging.Handler`][] for `click` applications.
-
-    Outputs log messages to [`sys.stderr`][] via [`click.echo`][].
-
-    """
-
-    def emit(self, record: logging.LogRecord) -> None:
-        """Emit a log record.
-
-        Format the log record, then emit it via [`click.echo`][] to
-        [`sys.stderr`][].
-
-        """
-        click.echo(
-            self.format(record),
-            err=True,
-            color=getattr(record, 'color', None),
-        )
-
-
-class CLIofPackageFormatter(logging.Formatter):
-    """A [`logging.LogRecord`][] formatter for the CLI of a Python package.
-
-    Assuming a package `PKG` and loggers within the same hierarchy
-    `PKG`, format all log records from that hierarchy for proper user
-    feedback on the console.  Intended for use with [`click`][CLICK] and
-    when `PKG` provides a command-line tool `PKG` and when logs from
-    that package should show up as output of the command-line tool.
-
-    Essentially, this prepends certain short strings to the log message
-    lines to make them readable as standard error output.
-
-    Because this log output is intended to be displayed on standard
-    error as high-level diagnostic output, you are strongly discouraged
-    from changing the output format to include more tokens besides the
-    log message.  Use a dedicated log file handler instead, without this
-    formatter.
-
-    [CLICK]: https://pypi.org/projects/click/
-
-    """
-
-    def __init__(
-        self,
-        *,
-        prog_name: str = PROG_NAME,
-        package_name: str | None = None,
-    ) -> None:
-        self.prog_name = prog_name
-        self.package_name = (
-            package_name
-            if package_name is not None
-            else prog_name.lower().replace(' ', '_').replace('-', '_')
-        )
-
-    def format(self, record: logging.LogRecord) -> str:
-        """Format a log record suitably for standard error console output.
-
-        Prepend the formatted string `"PROG_NAME: LABEL"` to each line
-        of the message, where `PROG_NAME` is the program name, and
-        `LABEL` depends on the record's level and on the logger name as
-        follows:
-
-          * For records at level [`logging.DEBUG`][], `LABEL` is
-            `"Debug: "`.
-          * For records at level [`logging.INFO`][], `LABEL` is the
-            empty string.
-          * For records at level [`logging.WARNING`][], `LABEL` is
-            `"Deprecation warning: "` if the logger is named
-            `PKG.deprecation` (where `PKG` is the package name), else
-            `"Warning: "`.
-          * For records at level [`logging.ERROR`][] and
-            [`logging.CRITICAL`][] `"Error: "`, `LABEL` is the empty
-            string.
-
-        The level indication strings at level `WARNING` or above are
-        highlighted.  Use [`click.echo`][] to output them and remove
-        color output if necessary.
-
-        Args:
-            record: A log record.
-
-        Returns:
-            A formatted log record.
-
-        Raises:
-            AssertionError:
-                The log level is not supported.
-
-        """
-        preliminary_result = record.getMessage()
-        prefix = f'{self.prog_name}: '
-        if record.levelname == 'DEBUG':  # pragma: no cover
-            level_indicator = 'Debug: '
-        elif record.levelname == 'INFO':
-            level_indicator = ''
-        elif record.levelname == 'WARNING':
-            level_indicator = (
-                f'{click.style("Deprecation warning", bold=True)}: '
-                if record.name.endswith('.deprecation')
-                else f'{click.style("Warning", bold=True)}: '
-            )
-        elif record.levelname in {'ERROR', 'CRITICAL'}:
-            level_indicator = ''
-        else:  # pragma: no cover
-            msg = f'Unsupported logging level: {record.levelname}'
-            raise AssertionError(msg)
-        parts = [
-            ''.join(
-                prefix + level_indicator + line
-                for line in preliminary_result.splitlines(True)  # noqa: FBT003
-            )
-        ]
-        if record.exc_info:
-            parts.append(self.formatException(record.exc_info) + '\n')
-        return ''.join(parts)
-
-
-class StandardCLILogging:
-    """Set up CLI logging handlers upon instantiation."""
-
-    prog_name = PROG_NAME
-    package_name = PROG_NAME.lower().replace(' ', '_').replace('-', '_')
-    cli_formatter = CLIofPackageFormatter(
-        prog_name=prog_name, package_name=package_name
-    )
-    cli_handler = ClickEchoStderrHandler()
-    cli_handler.addFilter(logging.Filter(name=package_name))
-    cli_handler.setFormatter(cli_formatter)
-    cli_handler.setLevel(logging.WARNING)
-    warnings_handler = ClickEchoStderrHandler()
-    warnings_handler.addFilter(logging.Filter(name='py.warnings'))
-    warnings_handler.setFormatter(cli_formatter)
-    warnings_handler.setLevel(logging.WARNING)
-
-    @classmethod
-    def ensure_standard_logging(cls) -> StandardLoggingContextManager:
-        """Return a context manager to ensure standard logging is set up."""
-        return StandardLoggingContextManager(
-            handler=cls.cli_handler,
-            root_logger=cls.package_name,
-        )
-
-    @classmethod
-    def ensure_standard_warnings_logging(
-        cls,
-    ) -> StandardWarningsLoggingContextManager:
-        """Return a context manager to ensure warnings logging is set up."""
-        return StandardWarningsLoggingContextManager(
-            handler=cls.warnings_handler,
-        )
-
-
-class StandardLoggingContextManager:
-    """A reentrant context manager setting up standard CLI logging.
-
-    Ensures that the given handler (defaulting to the CLI logging
-    handler) is added to the named logger (defaulting to the root
-    logger), and if it had to be added, then that it will be removed
-    upon exiting the context.
-
-    Reentrant, but not thread safe, because it temporarily modifies
-    global state.
-
-    """
-
-    def __init__(
-        self,
-        handler: logging.Handler,
-        root_logger: str | None = None,
-    ) -> None:
-        self.handler = handler
-        self.root_logger_name = root_logger
-        self.base_logger = logging.getLogger(self.root_logger_name)
-        self.action_required: MutableSequence[bool] = collections.deque()
-
-    def __enter__(self) -> Self:
-        self.action_required.append(
-            self.handler not in self.base_logger.handlers
-        )
-        if self.action_required[-1]:
-            self.base_logger.addHandler(self.handler)
-        return self
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_value: BaseException | None,
-        exc_tb: types.TracebackType | None,
-    ) -> Literal[False]:
-        if self.action_required[-1]:
-            self.base_logger.removeHandler(self.handler)
-        self.action_required.pop()
-        return False
-
-
-class StandardWarningsLoggingContextManager(StandardLoggingContextManager):
-    """A reentrant context manager setting up standard warnings logging.
-
-    Ensures that warnings are being diverted to the logging system, and
-    that the given handler (defaulting to the CLI logging handler) is
-    added to the warnings logger. If the handler had to be added, then
-    it will be removed upon exiting the context.
-
-    Reentrant, but not thread safe, because it temporarily modifies
-    global state.
-
-    """
-
-    def __init__(
-        self,
-        handler: logging.Handler,
-    ) -> None:
-        super().__init__(handler=handler, root_logger='py.warnings')
-        self.stack: MutableSequence[
-            tuple[
-                Callable[
-                    [
-                        type[BaseException] | None,
-                        BaseException | None,
-                        types.TracebackType | None,
-                    ],
-                    None,
-                ],
-                Callable[
-                    [
-                        str | Warning,
-                        type[Warning],
-                        str,
-                        int,
-                        TextIO | None,
-                        str | None,
-                    ],
-                    None,
-                ],
-            ]
-        ] = collections.deque()
-
-    def __enter__(self) -> Self:
-        def showwarning(  # noqa: PLR0913,PLR0917
-            message: str | Warning,
-            category: type[Warning],
-            filename: str,
-            lineno: int,
-            file: TextIO | None = None,
-            line: str | None = None,
-        ) -> None:
-            if file is not None:  # pragma: no cover
-                self.stack[0][1](
-                    message, category, filename, lineno, file, line
-                )
-            else:
-                logging.getLogger('py.warnings').warning(
-                    str(
-                        warnings.formatwarning(
-                            message, category, filename, lineno, line
-                        )
-                    )
-                )
-
-        ctx = warnings.catch_warnings()
-        exit_func = ctx.__exit__
-        ctx.__enter__()
-        self.stack.append((exit_func, warnings.showwarning))
-        warnings.showwarning = showwarning
-        return super().__enter__()
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_value: BaseException | None,
-        exc_tb: types.TracebackType | None,
-    ) -> Literal[False]:
-        ret = super().__exit__(exc_type, exc_value, exc_tb)
-        val = self.stack.pop()[0](exc_type, exc_value, exc_tb)
-        assert not val
-        return ret
-
-
-P = ParamSpec('P')
-R = TypeVar('R')
-
-
-def adjust_logging_level(
-    ctx: click.Context,
-    /,
-    param: click.Parameter | None = None,
-    value: int | None = None,
-) -> None:
-    """Change the logs that are emitted to standard error.
-
-    This modifies the [`StandardCLILogging`][] settings such that log
-    records at the respective level are emitted, based on the `param`
-    and the `value`.
-
-    """
-    # Note: If multiple options use this callback, then we will be
-    # called multiple times.  Ensure the runs are idempotent.
-    if param is None or value is None or ctx.resilient_parsing:
-        return
-    StandardCLILogging.cli_handler.setLevel(value)
-    logging.getLogger(StandardCLILogging.package_name).setLevel(value)
-
-
-# Option parsing and grouping
-# ===========================
-
-
-class OptionGroupOption(click.Option):
-    """A [`click.Option`][] with an associated group name and group epilog.
-
-    Used by [`CommandWithHelpGroups`][] to print help sections.  Each
-    subclass contains its own group name and epilog.
-
-    Attributes:
-        option_group_name:
-            The name of the option group.  Used as a heading on the help
-            text for options in this section.
-        epilog:
-            An epilog to print after listing the options in this
-            section.
-
-    """
-
-    option_group_name: object = ''
-    """"""
-    epilog: object = ''
-    """"""
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401
-        if self.__class__ == __class__:  # type: ignore[name-defined]
-            raise NotImplementedError
-        # Though click 8.1 mostly defers help text processing until the
-        # `BaseCommand.format_*` methods are called, the Option
-        # constructor still preprocesses the help text, and asserts that
-        # the help text is a string.  Work around this by removing the
-        # help text from the constructor arguments and re-adding it,
-        # unprocessed, after constructor finishes.
-        unset = object()
-        help = kwargs.pop('help', unset)  # noqa: A001
-        super().__init__(*args, **kwargs)
-        if help is not unset:  # pragma: no branch
-            self.help = help
-
-
-class StandardOption(OptionGroupOption):
-    pass
-
-
-# Portions of this class are based directly on code from click 8.1.
-# (This does not in general include docstrings, unless otherwise noted.)
-# They are subject to the 3-clause BSD license in the following
-# paragraphs.  Modifications to their code are marked with respective
-# comments; they too are released under the same license below.  The
-# original code did not contain any "noqa" or "pragma" comments.
-#
-#     Copyright 2024 Pallets
-#
-#     Redistribution and use in source and binary forms, with or
-#     without modification, are permitted provided that the
-#     following conditions are met:
-#
-#      1. Redistributions of source code must retain the above
-#         copyright notice, this list of conditions and the
-#         following disclaimer.
-#
-#      2. Redistributions in binary form must reproduce the above
-#         copyright notice, this list of conditions and the
-#         following disclaimer in the documentation and/or other
-#         materials provided with the distribution.
-#
-#      3. Neither the name of the copyright holder nor the names
-#         of its contributors may be used to endorse or promote
-#         products derived from this software without specific
-#         prior written permission.
-#
-#     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-#     CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
-#     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-#     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-#     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
-#     CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-#     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-#     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-#     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-#     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-#     CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-#     OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-#     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-class CommandWithHelpGroups(click.Command):
-    """A [`click.Command`][] with support for some help text customizations.
-
-    Supports help/option groups, group epilogs, and help text objects
-    (objects that stringify to help texts).  The latter is primarily
-    used to implement translations.
-
-    Inspired by [a comment on `pallets/click#373`][CLICK_ISSUE] for
-    help/option group support, and further modified to include group
-    epilogs and help text objects.
-
-    [CLICK_ISSUE]: https://github.com/pallets/click/issues/373#issuecomment-515293746
-
-    """
-
-    @staticmethod
-    def _text(text: object, /) -> str:
-        if isinstance(text, (list, tuple)):
-            return '\n\n'.join(str(x) for x in text)
-        return str(text)
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.
-    def collect_usage_pieces(self, ctx: click.Context) -> list[str]:
-        """Return the pieces for the usage string.
-
-        Args:
-            ctx:
-                The click context.
-
-        """
-        rv = [str(self.options_metavar)] if self.options_metavar else []
-        for param in self.get_params(ctx):
-            rv.extend(str(x) for x in param.get_usage_pieces(ctx))
-        return rv
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.
-    def get_help_option(
-        self,
-        ctx: click.Context,
-    ) -> click.Option | None:
-        """Return a standard help option object.
-
-        Args:
-            ctx:
-                The click context.
-
-        """
-        help_options = self.get_help_option_names(ctx)
-
-        if not help_options or not self.add_help_option:  # pragma: no cover
-            return None
-
-        def show_help(
-            ctx: click.Context,
-            param: click.Parameter,  # noqa: ARG001
-            value: str,
-        ) -> None:
-            if value and not ctx.resilient_parsing:
-                click.echo(ctx.get_help(), color=ctx.color)
-                ctx.exit()
-
-        # Modified from click 8.1: We use StandardOption and a non-str
-        # object as the help string.
-        return StandardOption(
-            help_options,
-            is_flag=True,
-            is_eager=True,
-            expose_value=False,
-            callback=show_help,
-            help=_msg.TranslatedString(_msg.Label.HELP_OPTION_HELP_TEXT),
-        )
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.
-    def get_short_help_str(
-        self,
-        limit: int = 45,
-    ) -> str:
-        """Return the short help string for a command.
-
-        If only a long help string is given, shorten it.
-
-        Args:
-            limit:
-                The maximum width of the short help string.
-
-        """
-        # Modification against click 8.1: Call `_text()` on `self.help`
-        # to allow help texts to be general objects, not just strings.
-        # Used to implement translatable strings, as objects that
-        # stringify to the translation.
-        if self.short_help:  # pragma: no cover
-            text = inspect.cleandoc(self._text(self.short_help))
-        elif self.help:
-            text = click.utils.make_default_short_help(
-                self._text(self.help), limit
-            )
-        else:  # pragma: no cover
-            text = ''
-        if self.deprecated:  # pragma: no cover
-            # Modification against click 8.1: The translated string is
-            # looked up in the derivepassphrase message domain, not the
-            # gettext default domain.
-            text = str(
-                _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
-            ).format(text=text)
-        return text.strip()
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.
-    def format_help_text(
-        self,
-        ctx: click.Context,
-        formatter: click.HelpFormatter,
-    ) -> None:
-        """Format the help text prologue, if any.
-
-        Args:
-            ctx:
-                The click context.
-            formatter:
-                The formatter for the `--help` listing.
-
-        """
-        del ctx
-        # Modification against click 8.1: Call `_text()` on `self.help`
-        # to allow help texts to be general objects, not just strings.
-        # Used to implement translatable strings, as objects that
-        # stringify to the translation.
-        text = (
-            inspect.cleandoc(self._text(self.help).partition('\f')[0])
-            if self.help is not None
-            else ''
-        )
-        if self.deprecated:  # pragma: no cover
-            # Modification against click 8.1: The translated string is
-            # looked up in the derivepassphrase message domain, not the
-            # gettext default domain.
-            text = str(
-                _msg.TranslatedString(_msg.Label.DEPRECATED_COMMAND_LABEL)
-            ).format(text=text)
-        if text:  # pragma: no branch
-            formatter.write_paragraph()
-            with formatter.indentation():
-                formatter.write_text(text)
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.  Consider the whole section
-    # marked as modified; the code modifications are too numerous to
-    # mark individually.
-    def format_options(
-        self,
-        ctx: click.Context,
-        formatter: click.HelpFormatter,
-    ) -> None:
-        r"""Format options on the help listing, grouped into sections.
-
-        This is a callback for [`click.Command.get_help`][] that
-        implements the `--help` listing, by calling appropriate methods
-        of the `formatter`.  We list all options (like the base
-        implementation), but grouped into sections according to the
-        concrete [`click.Option`][] subclass being used.  If the option
-        is an instance of some subclass of [`OptionGroupOption`][], then
-        the section heading and the epilog are taken from the
-        [`option_group_name`] [OptionGroupOption.option_group_name] and
-        [`epilog`] [OptionGroupOption.epilog] attributes; otherwise, the
-        section heading is "Options" (or "Other options" if there are
-        other option groups) and the epilog is empty.
-
-        We unconditionally call [`format_commands`][], and rely on it to
-        act as a no-op if we aren't actually a [`click.MultiCommand`][].
-
-        Args:
-            ctx:
-                The click context.
-            formatter:
-                The formatter for the `--help` listing.
-
-        """
-        default_group_name = ''
-        help_records: dict[str, list[tuple[str, str]]] = {}
-        epilogs: dict[str, str] = {}
-        params = self.params[:]
-        if (  # pragma: no branch
-            (help_opt := self.get_help_option(ctx)) is not None
-            and help_opt not in params
-        ):
-            params.append(help_opt)
-        for param in params:
-            rec = param.get_help_record(ctx)
-            if rec is not None:
-                rec = (rec[0], self._text(rec[1]))
-                if isinstance(param, OptionGroupOption):
-                    group_name = self._text(param.option_group_name)
-                    epilogs.setdefault(group_name, self._text(param.epilog))
-                else:  # pragma: no cover
-                    group_name = default_group_name
-                help_records.setdefault(group_name, []).append(rec)
-        if default_group_name in help_records:  # pragma: no branch
-            default_group = help_records.pop(default_group_name)
-            default_group_label = (
-                _msg.Label.OTHER_OPTIONS_LABEL
-                if len(default_group) > 1
-                else _msg.Label.OPTIONS_LABEL
-            )
-            default_group_name = self._text(
-                _msg.TranslatedString(default_group_label)
-            )
-            help_records[default_group_name] = default_group
-        for group_name, records in help_records.items():
-            with formatter.section(group_name):
-                formatter.write_dl(records)
-            epilog = inspect.cleandoc(epilogs.get(group_name, ''))
-            if epilog:
-                formatter.write_paragraph()
-                with formatter.indentation():
-                    formatter.write_text(epilog)
-        self.format_commands(ctx, formatter)
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.  Consider the whole section
-    # marked as modified; the code modifications are too numerous to
-    # mark individually.
-    def format_commands(
-        self,
-        ctx: click.Context,
-        formatter: click.HelpFormatter,
-    ) -> None:
-        """Format the subcommands, if any.
-
-        If called on a command object that isn't derived from
-        [`click.MultiCommand`][], then do nothing.
-
-        Args:
-            ctx:
-                The click context.
-            formatter:
-                The formatter for the `--help` listing.
-
-        """
-        if not isinstance(self, click.MultiCommand):
-            return
-        commands: list[tuple[str, click.Command]] = []
-        for subcommand in self.list_commands(ctx):
-            cmd = self.get_command(ctx, subcommand)
-            if cmd is None or cmd.hidden:  # pragma: no cover
-                continue
-            commands.append((subcommand, cmd))
-        if commands:  # pragma: no branch
-            longest_command = max((cmd[0] for cmd in commands), key=len)
-            limit = formatter.width - 6 - len(longest_command)
-            rows: list[tuple[str, str]] = []
-            for subcommand, cmd in commands:
-                help_str = self._text(cmd.get_short_help_str(limit) or '')
-                rows.append((subcommand, help_str))
-            if rows:  # pragma: no branch
-                commands_label = self._text(
-                    _msg.TranslatedString(_msg.Label.COMMANDS_LABEL)
-                )
-                with formatter.section(commands_label):
-                    formatter.write_dl(rows)
-
-    # This method is based on click 8.1; see the comment above the class
-    # declaration for license details.
-    def format_epilog(
-        self,
-        ctx: click.Context,
-        formatter: click.HelpFormatter,
-    ) -> None:
-        """Format the epilog, if any.
-
-        Args:
-            ctx:
-                The click context.
-            formatter:
-                The formatter for the `--help` listing.
-
-        """
-        del ctx
-        if self.epilog:  # pragma: no branch
-            # Modification against click 8.1: Call `str()` on
-            # `self.epilog` to allow help texts to be general objects,
-            # not just strings.  Used to implement translatable strings,
-            # as objects that stringify to the translation.
-            epilog = inspect.cleandoc(self._text(self.epilog))
-            formatter.write_paragraph()
-            with formatter.indentation():
-                formatter.write_text(epilog)
-
-
-def version_option_callback(
-    ctx: click.Context,
-    param: click.Parameter,
-    value: bool,  # noqa: FBT001
-) -> None:
-    del param
-    if value and not ctx.resilient_parsing:
-        click.echo(
-            str(
-                _msg.TranslatedString(
-                    _msg.Label.VERSION_INFO_TEXT,
-                    PROG_NAME=PROG_NAME,
-                    __version__=__version__,
-                )
-            ),
-        )
-        ctx.exit()
-
-
-def version_option(f: Callable[P, R]) -> Callable[P, R]:
-    return click.option(
-        '--version',
-        is_flag=True,
-        is_eager=True,
-        expose_value=False,
-        callback=version_option_callback,
-        cls=StandardOption,
-        help=_msg.TranslatedString(_msg.Label.VERSION_OPTION_HELP_TEXT),
-    )(f)
-
-
-def color_forcing_callback(
-    ctx: click.Context,
-    param: click.Parameter,
-    value: Any,  # noqa: ANN401
-) -> None:
-    """Force the `click` context to honor `NO_COLOR` and `FORCE_COLOR`."""
-    del param, value
-    if os.environ.get('NO_COLOR'):
-        ctx.color = False
-    if os.environ.get('FORCE_COLOR'):
-        ctx.color = True
-
-
-color_forcing_pseudo_option = click.option(
-    '--_pseudo-option-color-forcing',
-    '_color_forcing',
-    is_flag=True,
-    is_eager=True,
-    expose_value=False,
-    hidden=True,
-    callback=color_forcing_callback,
-    help='(pseudo-option)',
-)
-
-
-class LoggingOption(OptionGroupOption):
-    """Logging options for the CLI."""
-
-    option_group_name = _msg.TranslatedString(_msg.Label.LOGGING_LABEL)
-    epilog = ''
-
-
-debug_option = click.option(
-    '--debug',
-    'logging_level',
-    is_flag=True,
-    flag_value=logging.DEBUG,
-    expose_value=False,
-    callback=adjust_logging_level,
-    help=_msg.TranslatedString(_msg.Label.DEBUG_OPTION_HELP_TEXT),
-    cls=LoggingOption,
-)
-verbose_option = click.option(
-    '-v',
-    '--verbose',
-    'logging_level',
-    is_flag=True,
-    flag_value=logging.INFO,
-    expose_value=False,
-    callback=adjust_logging_level,
-    help=_msg.TranslatedString(_msg.Label.VERBOSE_OPTION_HELP_TEXT),
-    cls=LoggingOption,
-)
-quiet_option = click.option(
-    '-q',
-    '--quiet',
-    'logging_level',
-    is_flag=True,
-    flag_value=logging.ERROR,
-    expose_value=False,
-    callback=adjust_logging_level,
-    help=_msg.TranslatedString(_msg.Label.QUIET_OPTION_HELP_TEXT),
-    cls=LoggingOption,
-)
-
-
-def standard_logging_options(f: Callable[P, R]) -> Callable[P, R]:
-    """Decorate the function with standard logging click options.
-
-    Adds the three click options `-v`/`--verbose`, `-q`/`--quiet` and
-    `--debug`, which calls back into the [`adjust_logging_level`][]
-    function (with different argument values).
-
-    Args:
-        f: A callable to decorate.
-
-    Returns:
-        The decorated callable.
-
-    """
-    return debug_option(verbose_option(quiet_option(f)))
-
-
-# Shell completion
-# ================
-
-# Use naive filename completion for the `path` argument of
-# `derivepassphrase vault`'s `--import` and `--export` options, as well
-# as the `path` argument of `derivepassphrase export vault`.  The latter
-# treats the pseudo-filename `VAULT_PATH` specially, but this is awkward
-# to combine with standard filename completion, particularly in bash, so
-# we would probably have to implement *all* completion (`VAULT_PATH` and
-# filename completion) ourselves, lacking some niceties of bash's
-# built-in completion (e.g., adding spaces or slashes depending on
-# whether the completion is a directory or a complete filename).
-
-
-def _shell_complete_path(
-    ctx: click.Context,
-    parameter: click.Parameter,
-    value: str,
-) -> list[str | click.shell_completion.CompletionItem]:
-    """Request standard path completion for the `path` argument."""  # noqa: DOC201
-    del ctx, parameter, value
-    return [click.shell_completion.CompletionItem('', type='file')]
-
-
-# The standard `click` shell completion scripts serialize the completion
-# items as newline-separated one-line entries, which get silently
-# corrupted if the value contains newlines.  Each shell imposes
-# additional restrictions: Fish uses newlines in all internal completion
-# helper scripts, so it is difficult, if not impossible, to register
-# completion entries containing newlines if completion comes from within
-# a Fish completion function (instead of a Fish builtin).  Zsh's
-# completion system supports descriptions for each completion item, and
-# the completion helper functions parse every entry as a colon-separated
-# 2-tuple of item and description, meaning any colon in the item value
-# must be escaped.  Finally, Bash requires the result array to be
-# populated at the completion function's top-level scope, but for/while
-# loops within pipelines do not run at top-level scope, and Bash *also*
-# strips NUL characters from command substitution output, making it
-# difficult to read in external data into an array in a cross-platform
-# manner from entirely within Bash.
-#
-# We capitulate in front of these problems---most egregiously because of
-# Fish---and ensure that completion items (in this case: service names)
-# never contain ASCII control characters by refusing to offer such
-# items as valid completions.  On the other side, `derivepassphrase`
-# will warn the user when configuring or importing a service with such
-# a name that it will not be available for shell completion.
-
-
-def _is_completable_item(obj: object) -> bool:
-    """Return whether the item is completable on the command-line.
-
-    The item is completable if and only if it contains no ASCII control
-    characters (U+0000 through U+001F, and U+007F).
-
-    """
-    obj = str(obj)
-    forbidden = frozenset(chr(i) for i in range(32)) | {'\x7f'}
-    return not any(f in obj for f in forbidden)
-
-
-def _shell_complete_service(
-    ctx: click.Context,
-    parameter: click.Parameter,
-    value: str,
-) -> list[str | click.shell_completion.CompletionItem]:
-    """Return known vault service names as completion items.
-
-    Service names are looked up in the vault configuration file.  All
-    errors will be suppressed.  Additionally, any service names deemed
-    not completable as per [`_is_completable_item`][] will be silently
-    skipped.
-
-    """
-    del ctx, parameter
-    try:
-        config = _load_config()
-        return sorted(
-            sv
-            for sv in config['services']
-            if sv.startswith(value) and _is_completable_item(sv)
-        )
-    except FileNotFoundError:
-        try:
-            config, _exc = _migrate_and_load_old_config()
-            return sorted(
-                sv
-                for sv in config['services']
-                if sv.startswith(value) and _is_completable_item(sv)
-            )
-        except FileNotFoundError:
-            return []
-    except Exception:  # noqa: BLE001
-        return []
-
-
-class ZshComplete(click.shell_completion.ZshComplete):
-    """Zsh completion class that supports colons.
-
-    `click`'s Zsh completion class (at least v8.1.7 and v8.1.8) uses
-    some completion helper functions (provided by Zsh) that parse each
-    completion item into value-description pairs, separated by a colon.
-    Other completion helper functions don't.  Correspondingly, any
-    internal colons in the completion item's value sometimes need to be
-    escaped, and sometimes don't.
-
-    The "right" way to fix this is to modify the Zsh completion script
-    to only use one type of serialization: either escaped, or unescaped.
-    However, the Zsh completion script itself may already be installed
-    in the user's Zsh settings, and we have no way of knowing that.
-    Therefore, it is better to change the `format_completion` method to
-    adaptively and "smartly" emit colon-escaped output or not, based on
-    whether the completion script will be using it.
-
-    """
-
-    @override
-    def format_completion(
-        self,
-        item: click.shell_completion.CompletionItem,
-    ) -> str:
-        """Return a suitable serialization of the CompletionItem.
-
-        This serialization ensures colons in the item value are properly
-        escaped if and only if the completion script will attempt to
-        pass a colon-separated key/description pair to the underlying
-        Zsh machinery.  This is the case if and only if the help text is
-        non-degenerate.
-
-        """
-        help_ = item.help or '_'
-        value = item.value.replace(':', r'\:' if help_ != '_' else ':')
-        return f'{item.type}\n{value}\n{help_}'
-
-
-# Our ZshComplete class depends crucially on the exact shape of the Zsh
-# completion script.  So only fix the completion formatter if the
-# completion script is still the same.
-#
-# (This Zsh script is part of click, and available under the
-# 3-clause-BSD license.)
-_ORIG_SOURCE_TEMPLATE = """\
-#compdef %(prog_name)s
-
-%(complete_func)s() {
-    local -a completions
-    local -a completions_with_descriptions
-    local -a response
-    (( ! $+commands[%(prog_name)s] )) && return 1
-
-    response=("${(@f)$(env COMP_WORDS="${words[*]}" COMP_CWORD=$((CURRENT-1)) \
-%(complete_var)s=zsh_complete %(prog_name)s)}")
-
-    for type key descr in ${response}; do
-        if [[ "$type" == "plain" ]]; then
-            if [[ "$descr" == "_" ]]; then
-                completions+=("$key")
-            else
-                completions_with_descriptions+=("$key":"$descr")
-            fi
-        elif [[ "$type" == "dir" ]]; then
-            _path_files -/
-        elif [[ "$type" == "file" ]]; then
-            _path_files -f
-        fi
-    done
-
-    if [ -n "$completions_with_descriptions" ]; then
-        _describe -V unsorted completions_with_descriptions -U
-    fi
-
-    if [ -n "$completions" ]; then
-        compadd -U -V unsorted -a completions
-    fi
-}
-
-if [[ $zsh_eval_context[-1] == loadautofunc ]]; then
-    # autoload from fpath, call function directly
-    %(complete_func)s "$@"
-else
-    # eval/source/. command, register function for later
-    compdef %(complete_func)s %(prog_name)s
-fi
-"""
-if (
-    click.shell_completion.ZshComplete.source_template == _ORIG_SOURCE_TEMPLATE
-):  # pragma: no cover
-    click.shell_completion.add_completion_class(ZshComplete)
-
-
-# Top-level
-# =========
-
-
-# Portions of this class are based directly on code from click 8.1.
-# (This does not in general include docstrings, unless otherwise noted.)
-# They are subject to the 3-clause BSD license in the following
-# paragraphs.  Modifications to their code are marked with respective
-# comments; they too are released under the same license below.  The
-# original code did not contain any "noqa" or "pragma" comments.
-#
-#     Copyright 2024 Pallets
-#
-#     Redistribution and use in source and binary forms, with or
-#     without modification, are permitted provided that the
-#     following conditions are met:
-#
-#      1. Redistributions of source code must retain the above
-#         copyright notice, this list of conditions and the
-#         following disclaimer.
-#
-#      2. Redistributions in binary form must reproduce the above
-#         copyright notice, this list of conditions and the
-#         following disclaimer in the documentation and/or other
-#         materials provided with the distribution.
-#
-#      3. Neither the name of the copyright holder nor the names
-#         of its contributors may be used to endorse or promote
-#         products derived from this software without specific
-#         prior written permission.
-#
-#     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
-#     CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
-#     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-#     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-#     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
-#     CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-#     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-#     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-#     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-#     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-#     CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
-#     OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-#     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-#
-# TODO(the-13th-letter): Remove this class and license block in v1.0.
-# https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#v1.0-implied-subcommands
-class _DefaultToVaultGroup(CommandWithHelpGroups, click.Group):
-    """A helper class to implement the default-to-"vault"-subcommand behavior.
-
-    Modifies internal [`click.MultiCommand`][] methods, and thus is both
-    an implementation detail and a kludge.
-
-    """
-
-    def resolve_command(
-        self, ctx: click.Context, args: list[str]
-    ) -> tuple[str | None, click.Command | None, list[str]]:
-        """Resolve a command, defaulting to "vault" instead of erroring out."""  # noqa: DOC201
-        cmd_name = click.utils.make_str(args[0])
-
-        # Get the command
-        cmd = self.get_command(ctx, cmd_name)
-
-        # If we can't find the command but there is a normalization
-        # function available, we try with that one.
-        if (  # pragma: no cover
-            cmd is None and ctx.token_normalize_func is not None
-        ):
-            cmd_name = ctx.token_normalize_func(cmd_name)
-            cmd = self.get_command(ctx, cmd_name)
-
-        # If we don't find the command we want to show an error message
-        # to the user that it was not provided.  However, there is
-        # something else we should do: if the first argument looks like
-        # an option we want to kick off parsing again for arguments to
-        # resolve things like --help which now should go to the main
-        # place.
-        if cmd is None and not ctx.resilient_parsing:
-            if click.parser.split_opt(cmd_name)[0]:
-                self.parse_args(ctx, ctx.args)
-            ####
-            # BEGIN modifications for derivepassphrase
-            #
-            # Instead of calling ctx.fail here, default to "vault", and
-            # issue a deprecation warning.
-            deprecation = logging.getLogger(f'{PROG_NAME}.deprecation')
-            deprecation.warning(
-                _msg.TranslatedString(
-                    _msg.WarnMsgTemplate.V10_SUBCOMMAND_REQUIRED
-                )
-            )
-            cmd_name = 'vault'
-            cmd = self.get_command(ctx, cmd_name)
-            assert cmd is not None, 'Mandatory subcommand "vault" missing!'
-            args = [cmd_name, *args]
-            #
-            # END modifications for derivepassphrase
-            ####
-        return cmd_name if cmd else None, cmd, args[1:]
-
-
-# TODO(the-13th-letter): Base this class on CommandWithHelpGroups and
-# click.Group in v1.0.
-# https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#v1.0-implied-subcommands
-class _TopLevelCLIEntryPoint(_DefaultToVaultGroup):
-    """A minor variation of _DefaultToVaultGroup for the top-level command.
-
-    When called as a function, this sets up the environment properly
-    before invoking the actual callbacks.  Currently, this means setting
-    up the logging subsystem and the delegation of Python warnings to
-    the logging subsystem.
-
-    The environment setup can be bypassed by calling the `.main` method
-    directly.
-
-    """
-
-    def __call__(  # pragma: no cover
-        self,
-        *args: Any,  # noqa: ANN401
-        **kwargs: Any,  # noqa: ANN401
-    ) -> Any:  # noqa: ANN401
-        """"""  # noqa: D419
-        # Coverage testing is done with the `click.testing` module,
-        # which does not use the `__call__` shortcut.  So it is normal
-        # that this function is never called, and thus should be
-        # excluded from coverage.
-        with (
-            StandardCLILogging.ensure_standard_logging(),
-            StandardCLILogging.ensure_standard_warnings_logging(),
-        ):
-            return self.main(*args, **kwargs)
 
 
 @click.group(
@@ -1210,16 +54,16 @@ class _TopLevelCLIEntryPoint(_DefaultToVaultGroup):
     },
     epilog=_msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EPILOG_01),
     invoke_without_command=True,
-    cls=_TopLevelCLIEntryPoint,
+    cls=cli_machinery.TopLevelCLIEntryPoint,
     help=(
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_01),
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_02),
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_03),
     ),
 )
-@version_option
-@color_forcing_pseudo_option
-@standard_logging_options
+@cli_machinery.version_option
+@cli_machinery.color_forcing_pseudo_option
+@cli_machinery.standard_logging_options
 @click.pass_context
 def derivepassphrase(ctx: click.Context, /) -> None:
     """Derive a strong passphrase, deterministically, from a master secret.
@@ -1265,16 +109,16 @@ def derivepassphrase(ctx: click.Context, /) -> None:
         'allow_interspersed_args': False,
     },
     invoke_without_command=True,
-    cls=_DefaultToVaultGroup,
+    cls=cli_machinery.DefaultToVaultGroup,
     help=(
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_01),
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_02),
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_03),
     ),
 )
-@version_option
-@color_forcing_pseudo_option
-@standard_logging_options
+@cli_machinery.version_option
+@cli_machinery.color_forcing_pseudo_option
+@cli_machinery.standard_logging_options
 @click.pass_context
 def derivepassphrase_export(ctx: click.Context, /) -> None:
     """Export a foreign configuration to standard output.
@@ -1314,7 +158,7 @@ def derivepassphrase_export(ctx: click.Context, /) -> None:
 @derivepassphrase_export.command(
     'vault',
     context_settings={'help_option_names': ['-h', '--help']},
-    cls=CommandWithHelpGroups,
+    cls=cli_machinery.CommandWithHelpGroups,
     help=(
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_EXPORT_VAULT_01),
         _msg.TranslatedString(
@@ -1348,7 +192,7 @@ def derivepassphrase_export(ctx: click.Context, /) -> None:
             _msg.Label.EXPORT_VAULT_FORMAT_METAVAR_FMT,
         ),
     ),
-    cls=StandardOption,
+    cls=cli_machinery.StandardOption,
 )
 @click.option(
     '-k',
@@ -1361,16 +205,16 @@ def derivepassphrase_export(ctx: click.Context, /) -> None:
             _msg.Label.EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT,
         ),
     ),
-    cls=StandardOption,
+    cls=cli_machinery.StandardOption,
 )
-@version_option
-@color_forcing_pseudo_option
-@standard_logging_options
+@cli_machinery.version_option
+@cli_machinery.color_forcing_pseudo_option
+@cli_machinery.standard_logging_options
 @click.argument(
     'path',
     metavar=_msg.TranslatedString(_msg.Label.EXPORT_VAULT_METAVAR_PATH),
     required=True,
-    shell_complete=_shell_complete_path,
+    shell_complete=cli_helpers.shell_complete_path,
 )
 @click.pass_context
 def derivepassphrase_export_vault(
@@ -1468,712 +312,10 @@ def derivepassphrase_export_vault(
         ctx.exit(1)
 
 
-# Vault
-# =====
-
-_config_filename_table = {
-    None: '.',
-    'vault': 'vault.json',
-    'user configuration': 'config.toml',
-    # TODO(the-13th-letter): Remove the old settings.json file.
-    # https://the13thletter.info/derivepassphrase/latest/upgrade-notes.html#v1.0-old-settings-file
-    'old settings.json': 'settings.json',
-}
-
-
-def _config_filename(
-    subsystem: str | None = 'old settings.json',
-) -> pathlib.Path:
-    """Return the filename of the configuration file for the subsystem.
-
-    The (implicit default) file is currently named `settings.json`,
-    located within the configuration directory as determined by the
-    `DERIVEPASSPHRASE_PATH` environment variable, or by
-    [`click.get_app_dir`][] in POSIX mode.  Depending on the requested
-    subsystem, this will usually be a different file within that
-    directory.
-
-    Args:
-        subsystem:
-            Name of the configuration subsystem whose configuration
-            filename to return.  If not given, return the old filename
-            from before the subcommand migration.  If `None`, return the
-            configuration directory instead.
-
-    Raises:
-        AssertionError:
-            An unknown subsystem was passed.
-
-    Deprecated:
-        Since v0.2.0: The implicit default subsystem and the old
-        configuration filename are deprecated, and will be removed in v1.0.
-        The subsystem will be mandatory to specify.
-
-    """
-    path = pathlib.Path(
-        os.getenv(PROG_NAME.upper() + '_PATH')
-        or click.get_app_dir(PROG_NAME, force_posix=True)
-    )
-    try:
-        filename = _config_filename_table[subsystem]
-    except (KeyError, TypeError):  # pragma: no cover
-        msg = f'Unknown configuration subsystem: {subsystem!r}'
-        raise AssertionError(msg) from None
-    return path / filename
-
-
-def _load_config() -> _types.VaultConfig:
-    """Load a vault(1)-compatible config from the application directory.
-
-    The filename is obtained via [`_config_filename`][].  This must be
-    an unencrypted JSON file.
-
-    Returns:
-        The vault settings.  See [`_types.VaultConfig`][] for details.
-
-    Raises:
-        OSError:
-            There was an OS error accessing the file.
-        ValueError:
-            The data loaded from the file is not a vault(1)-compatible
-            config.
-
-    """
-    filename = _config_filename(subsystem='vault')
-    with filename.open('rb') as fileobj:
-        data = json.load(fileobj)
-    if not _types.is_vault_config(data):
-        raise ValueError(_INVALID_VAULT_CONFIG)
-    return data
-
-
-# TODO(the-13th-letter): Remove this function.
-# https://the13thletter.info/derivepassphrase/latest/upgrade-notes.html#v1.0-old-settings-file
-def _migrate_and_load_old_config() -> tuple[
-    _types.VaultConfig, OSError | None
-]:
-    """Load and migrate a vault(1)-compatible config.
-
-    The (old) filename is obtained via [`_config_filename`][].  This
-    must be an unencrypted JSON file.  After loading, the file is
-    migrated to the new standard filename.
-
-    Returns:
-        The vault settings, and an optional exception encountered during
-        migration.  See [`_types.VaultConfig`][] for details on the
-        former.
-
-    Raises:
-        OSError:
-            There was an OS error accessing the old file.
-        ValueError:
-            The data loaded from the file is not a vault(1)-compatible
-            config.
-
-    """
-    new_filename = _config_filename(subsystem='vault')
-    old_filename = _config_filename(subsystem='old settings.json')
-    with old_filename.open('rb') as fileobj:
-        data = json.load(fileobj)
-    if not _types.is_vault_config(data):
-        raise ValueError(_INVALID_VAULT_CONFIG)
-    try:
-        old_filename.rename(new_filename)
-    except OSError as exc:
-        return data, exc
-    else:
-        return data, None
-
-
-def _save_config(config: _types.VaultConfig, /) -> None:
-    """Save a vault(1)-compatible config to the application directory.
-
-    The filename is obtained via [`_config_filename`][].  The config
-    will be stored as an unencrypted JSON file.
-
-    Args:
-        config:
-            vault configuration to save.
-
-    Raises:
-        OSError:
-            There was an OS error accessing or writing the file.
-        ValueError:
-            The data cannot be stored as a vault(1)-compatible config.
-
-    """
-    if not _types.is_vault_config(config):
-        raise ValueError(_INVALID_VAULT_CONFIG)
-    filename = _config_filename(subsystem='vault')
-    filedir = filename.resolve().parent
-    filedir.mkdir(parents=True, exist_ok=True)
-    with filename.open('w', encoding='UTF-8') as fileobj:
-        json.dump(config, fileobj)
-
-
-def _load_user_config() -> dict[str, Any]:
-    """Load the user config from the application directory.
-
-    The filename is obtained via [`_config_filename`][].
-
-    Returns:
-        The user configuration, as a nested `dict`.
-
-    Raises:
-        OSError:
-            There was an OS error accessing the file.
-        ValueError:
-            The data loaded from the file is not a valid configuration
-            file.
-
-    """
-    filename = _config_filename(subsystem='user configuration')
-    with filename.open('rb') as fileobj:
-        return tomllib.load(fileobj)
-
-
-def _get_suitable_ssh_keys(
-    conn: ssh_agent.SSHAgentClient | socket.socket | None = None, /
-) -> Iterator[_types.SSHKeyCommentPair]:
-    """Yield all SSH keys suitable for passphrase derivation.
-
-    Suitable SSH keys are queried from the running SSH agent (see
-    [`ssh_agent.SSHAgentClient.list_keys`][]).
-
-    Args:
-        conn:
-            An optional connection hint to the SSH agent.  See
-            [`ssh_agent.SSHAgentClient.ensure_agent_subcontext`][].
-
-    Yields:
-        Every SSH key from the SSH agent that is suitable for passphrase
-        derivation.
-
-    Raises:
-        KeyError:
-            `conn` was `None`, and the `SSH_AUTH_SOCK` environment
-            variable was not found.
-        NotImplementedError:
-            `conn` was `None`, and this Python does not support
-            [`socket.AF_UNIX`][], so the SSH agent client cannot be
-            automatically set up.
-        OSError:
-            `conn` was a socket or `None`, and there was an error
-            setting up a socket connection to the agent.
-        LookupError:
-            No keys usable for passphrase derivation are loaded into the
-            SSH agent.
-        RuntimeError:
-            There was an error communicating with the SSH agent.
-        ssh_agent.SSHAgentFailedError:
-            The agent failed to supply a list of loaded keys.
-
-    """
-    with ssh_agent.SSHAgentClient.ensure_agent_subcontext(conn) as client:
-        try:
-            all_key_comment_pairs = list(client.list_keys())
-        except EOFError as exc:  # pragma: no cover
-            raise RuntimeError(_AGENT_COMMUNICATION_ERROR) from exc
-        suitable_keys = copy.copy(all_key_comment_pairs)
-        for pair in all_key_comment_pairs:
-            key, _comment = pair
-            if vault.Vault.is_suitable_ssh_key(key, client=client):
-                yield pair
-    if not suitable_keys:  # pragma: no cover
-        raise LookupError(_NO_SUITABLE_KEYS)
-
-
-def _prompt_for_selection(
-    items: Sequence[str | bytes],
-    heading: str = 'Possible choices:',
-    single_choice_prompt: str = 'Confirm this choice?',
-    ctx: click.Context | None = None,
-) -> int:
-    """Prompt user for a choice among the given items.
-
-    Print the heading, if any, then present the items to the user.  If
-    there are multiple items, prompt the user for a selection, validate
-    the choice, then return the list index of the selected item.  If
-    there is only a single item, request confirmation for that item
-    instead, and return the correct index.
-
-    Args:
-        items:
-            The list of items to choose from.
-        heading:
-            A heading for the list of items, to print immediately
-            before.  Defaults to a reasonable standard heading.  If
-            explicitly empty, print no heading.
-        single_choice_prompt:
-            The confirmation prompt if there is only a single possible
-            choice.  Defaults to a reasonable standard prompt.
-        ctx:
-            An optional `click` context, from which output device
-            properties and color preferences will be queried.
-
-    Returns:
-        An index into the items sequence, indicating the user's
-        selection.
-
-    Raises:
-        IndexError:
-            The user made an invalid or empty selection, or requested an
-            abort.
-
-    """
-    n = len(items)
-    color = ctx.color if ctx is not None else None
-    if heading:
-        click.echo(click.style(heading, bold=True), color=color)
-    for i, x in enumerate(items, start=1):
-        click.echo(click.style(f'[{i}]', bold=True), nl=False, color=color)
-        click.echo(' ', nl=False, color=color)
-        click.echo(x, color=color)
-    if n > 1:
-        choices = click.Choice([''] + [str(i) for i in range(1, n + 1)])
-        choice = click.prompt(
-            f'Your selection? (1-{n}, leave empty to abort)',
-            err=True,
-            type=choices,
-            show_choices=False,
-            show_default=False,
-            default='',
-        )
-        if not choice:
-            raise IndexError(_EMPTY_SELECTION)
-        return int(choice) - 1
-    prompt_suffix = (
-        ' ' if single_choice_prompt.endswith(tuple('?.!')) else ': '
-    )
-    try:
-        click.confirm(
-            single_choice_prompt,
-            prompt_suffix=prompt_suffix,
-            err=True,
-            abort=True,
-            default=False,
-            show_default=False,
-        )
-    except click.Abort:
-        raise IndexError(_EMPTY_SELECTION) from None
-    return 0
-
-
-def _select_ssh_key(
-    conn: ssh_agent.SSHAgentClient | socket.socket | None = None,
-    /,
-    *,
-    ctx: click.Context | None = None,
-) -> bytes | bytearray:
-    """Interactively select an SSH key for passphrase derivation.
-
-    Suitable SSH keys are queried from the running SSH agent (see
-    [`ssh_agent.SSHAgentClient.list_keys`][]), then the user is prompted
-    interactively (see [`click.prompt`][]) for a selection.
-
-    Args:
-        conn:
-            An optional connection hint to the SSH agent.  See
-            [`ssh_agent.SSHAgentClient.ensure_agent_subcontext`][].
-        ctx:
-            An `click` context, queried for output device properties and
-            color preferences when issuing the prompt.
-
-    Returns:
-        The selected SSH key.
-
-    Raises:
-        KeyError:
-            `conn` was `None`, and the `SSH_AUTH_SOCK` environment
-            variable was not found.
-        NotImplementedError:
-            `conn` was `None`, and this Python does not support
-            [`socket.AF_UNIX`][], so the SSH agent client cannot be
-            automatically set up.
-        OSError:
-            `conn` was a socket or `None`, and there was an error
-            setting up a socket connection to the agent.
-        IndexError:
-            The user made an invalid or empty selection, or requested an
-            abort.
-        LookupError:
-            No keys usable for passphrase derivation are loaded into the
-            SSH agent.
-        RuntimeError:
-            There was an error communicating with the SSH agent.
-        SSHAgentFailedError:
-            The agent failed to supply a list of loaded keys.
-    """
-    suitable_keys = list(_get_suitable_ssh_keys(conn))
-    key_listing: list[str] = []
-    unstring_prefix = ssh_agent.SSHAgentClient.unstring_prefix
-    for key, comment in suitable_keys:
-        keytype = unstring_prefix(key)[0].decode('ASCII')
-        key_str = base64.standard_b64encode(key).decode('ASCII')
-        remaining_key_display_length = KEY_DISPLAY_LENGTH - 1 - len(keytype)
-        key_extract = min(
-            key_str,
-            '...' + key_str[-remaining_key_display_length:],
-            key=len,
-        )
-        comment_str = comment.decode('UTF-8', errors='replace')
-        key_listing.append(f'{keytype} {key_extract}  {comment_str}')
-    choice = _prompt_for_selection(
-        key_listing,
-        heading='Suitable SSH keys:',
-        single_choice_prompt='Use this key?',
-        ctx=ctx,
-    )
-    return suitable_keys[choice].key
-
-
-def _prompt_for_passphrase() -> str:
-    """Interactively prompt for the passphrase.
-
-    Calls [`click.prompt`][] internally.  Moved into a separate function
-    mainly for testing/mocking purposes.
-
-    Returns:
-        The user input.
-
-    """
-    return cast(
-        'str',
-        click.prompt(
-            'Passphrase',
-            default='',
-            hide_input=True,
-            show_default=False,
-            err=True,
-        ),
-    )
-
-
-def _toml_key(*parts: str) -> str:
-    """Return a formatted TOML key, given its parts."""
-
-    def escape(string: str) -> str:
-        translated = string.translate({
-            0: r'\u0000',
-            1: r'\u0001',
-            2: r'\u0002',
-            3: r'\u0003',
-            4: r'\u0004',
-            5: r'\u0005',
-            6: r'\u0006',
-            7: r'\u0007',
-            8: r'\b',
-            9: r'\t',
-            10: r'\n',
-            11: r'\u000B',
-            12: r'\f',
-            13: r'\r',
-            14: r'\u000E',
-            15: r'\u000F',
-            ord('"'): r'\"',
-            ord('\\'): r'\\',
-            127: r'\u007F',
-        })
-        return f'"{translated}"' if translated != string else string
-
-    return '.'.join(map(escape, parts))
-
-
-class _ORIGIN(enum.Enum):
-    INTERACTIVE: str = 'interactive input'
-
-
-def _check_for_misleading_passphrase(
-    key: tuple[str, ...] | _ORIGIN,
-    value: dict[str, Any],
-    *,
-    main_config: dict[str, Any],
-    ctx: click.Context | None = None,
-) -> None:
-    form_key = 'unicode-normalization-form'
-    default_form: str = main_config.get('vault', {}).get(
-        f'default-{form_key}', 'NFC'
-    )
-    form_dict: dict[str, dict] = main_config.get('vault', {}).get(form_key, {})
-    form: Any = (
-        default_form
-        if isinstance(key, _ORIGIN) or key == ('global',)
-        else form_dict.get(key[1], default_form)
-    )
-    config_key = (
-        _toml_key('vault', key[1], form_key)
-        if isinstance(key, tuple) and len(key) > 1 and key[1] in form_dict
-        else f'vault.default-{form_key}'
-    )
-    if form not in {'NFC', 'NFD', 'NFKC', 'NFKD'}:
-        msg = f'Invalid value {form!r} for config key {config_key}'
-        raise AssertionError(msg)
-    logger = logging.getLogger(PROG_NAME)
-    formatted_key = (
-        key.value if isinstance(key, _ORIGIN) else _types.json_path(key)
-    )
-    if 'phrase' in value:
-        phrase = value['phrase']
-        if not unicodedata.is_normalized(form, phrase):
-            logger.warning(
-                (
-                    'The %s passphrase is not %s-normalized.  Its '
-                    'serialization as a byte string may not be what you '
-                    'expect it to be, even if it *displays* correctly.  '
-                    'Please make sure to double-check any derived '
-                    'passphrases for unexpected results.'
-                ),
-                formatted_key,
-                form,
-                stacklevel=2,
-                extra={'color': ctx.color if ctx is not None else None},
-            )
-
-
-def _key_to_phrase(
-    key_: str | bytes | bytearray,
-    /,
-    *,
-    error_callback: Callable[..., NoReturn] = sys.exit,
-) -> bytes | bytearray:
-    key = base64.standard_b64decode(key_)
-    try:
-        with ssh_agent.SSHAgentClient.ensure_agent_subcontext() as client:
-            try:
-                return vault.Vault.phrase_from_key(key, conn=client)
-            except ssh_agent.SSHAgentFailedError as exc:
-                try:
-                    keylist = client.list_keys()
-                except ssh_agent.SSHAgentFailedError:
-                    pass
-                except Exception as exc2:  # noqa: BLE001
-                    exc.__context__ = exc2
-                else:
-                    if not any(  # pragma: no branch
-                        k == key for k, _ in keylist
-                    ):
-                        error_callback(
-                            _msg.TranslatedString(
-                                _msg.ErrMsgTemplate.SSH_KEY_NOT_LOADED
-                            )
-                        )
-                error_callback(
-                    _msg.TranslatedString(
-                        _msg.ErrMsgTemplate.AGENT_REFUSED_SIGNATURE
-                    ),
-                    exc_info=exc,
-                )
-    except KeyError:
-        error_callback(
-            _msg.TranslatedString(_msg.ErrMsgTemplate.NO_SSH_AGENT_FOUND)
-        )
-    except NotImplementedError:
-        error_callback(_msg.TranslatedString(_msg.ErrMsgTemplate.NO_AF_UNIX))
-    except OSError as exc:
-        error_callback(
-            _msg.TranslatedString(
-                _msg.ErrMsgTemplate.CANNOT_CONNECT_TO_AGENT,
-                error=exc.strerror,
-                filename=exc.filename,
-            ).maybe_without_filename()
-        )
-    except RuntimeError as exc:
-        error_callback(
-            _msg.TranslatedString(_msg.ErrMsgTemplate.CANNOT_UNDERSTAND_AGENT),
-            exc_info=exc,
-        )
-
-
-def _print_config_as_sh_script(
-    config: _types.VaultConfig,
-    /,
-    *,
-    outfile: TextIO,
-    prog_name_list: Sequence[str],
-) -> None:
-    service_keys = (
-        'length',
-        'repeat',
-        'lower',
-        'upper',
-        'number',
-        'space',
-        'dash',
-        'symbol',
-    )
-    print('#!/bin/sh -e', file=outfile)
-    print(file=outfile)
-    print(shlex.join([*prog_name_list, '--clear']), file=outfile)
-    sv_obj_pairs: list[
-        tuple[
-            str | None,
-            _types.VaultConfigGlobalSettings
-            | _types.VaultConfigServicesSettings,
-        ],
-    ] = list(config['services'].items())
-    if config.get('global', {}):
-        sv_obj_pairs.insert(0, (None, config['global']))
-    for sv, sv_obj in sv_obj_pairs:
-        this_service_keys = tuple(k for k in service_keys if k in sv_obj)
-        this_other_keys = tuple(k for k in sv_obj if k not in service_keys)
-        if this_other_keys:
-            other_sv_obj = {k: sv_obj[k] for k in this_other_keys}  # type: ignore[literal-required]
-            dumped_config = json.dumps(
-                (
-                    {'services': {sv: other_sv_obj}}
-                    if sv is not None
-                    else {'global': other_sv_obj, 'services': {}}
-                ),
-                ensure_ascii=False,
-                indent=None,
-            )
-            print(
-                shlex.join([*prog_name_list, '--import', '-']) + " <<'HERE'",
-                dumped_config,
-                'HERE',
-                sep='\n',
-                file=outfile,
-            )
-        if not this_service_keys and not this_other_keys and sv:
-            dumped_config = json.dumps(
-                {'services': {sv: {}}},
-                ensure_ascii=False,
-                indent=None,
-            )
-            print(
-                shlex.join([*prog_name_list, '--import', '-']) + " <<'HERE'",
-                dumped_config,
-                'HERE',
-                sep='\n',
-                file=outfile,
-            )
-        elif this_service_keys:
-            tokens = [*prog_name_list, '--config']
-            for key in this_service_keys:
-                tokens.extend([f'--{key}', str(sv_obj[key])])  # type: ignore[literal-required]
-            if sv is not None:
-                tokens.extend(['--', sv])
-            print(shlex.join(tokens), file=outfile)
-
-
-# Concrete option groups used by this command-line interface.
-class PassphraseGenerationOption(OptionGroupOption):
-    """Passphrase generation options for the CLI."""
-
-    option_group_name = _msg.TranslatedString(
-        _msg.Label.PASSPHRASE_GENERATION_LABEL
-    )
-    epilog = _msg.TranslatedString(
-        _msg.Label.PASSPHRASE_GENERATION_EPILOG,
-        metavar=_msg.TranslatedString(
-            _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
-        ),
-    )
-
-
-class ConfigurationOption(OptionGroupOption):
-    """Configuration options for the CLI."""
-
-    option_group_name = _msg.TranslatedString(_msg.Label.CONFIGURATION_LABEL)
-    epilog = _msg.TranslatedString(_msg.Label.CONFIGURATION_EPILOG)
-
-
-class StorageManagementOption(OptionGroupOption):
-    """Storage management options for the CLI."""
-
-    option_group_name = _msg.TranslatedString(
-        _msg.Label.STORAGE_MANAGEMENT_LABEL
-    )
-    epilog = _msg.TranslatedString(
-        _msg.Label.STORAGE_MANAGEMENT_EPILOG,
-        metavar=_msg.TranslatedString(
-            _msg.Label.STORAGE_MANAGEMENT_METAVAR_PATH
-        ),
-    )
-
-
-class CompatibilityOption(OptionGroupOption):
-    """Compatibility and incompatibility options for the CLI."""
-
-    option_group_name = _msg.TranslatedString(
-        _msg.Label.COMPATIBILITY_OPTION_LABEL
-    )
-
-
-def _validate_occurrence_constraint(
-    ctx: click.Context,
-    param: click.Parameter,
-    value: Any,  # noqa: ANN401
-) -> int | None:
-    """Check that the occurrence constraint is valid (int, 0 or larger).
-
-    Args:
-        ctx: The `click` context.
-        param: The current command-line parameter.
-        value: The parameter value to be checked.
-
-    Returns:
-        The parsed parameter value.
-
-    Raises:
-        click.BadParameter: The parameter value is invalid.
-
-    """
-    del ctx  # Unused.
-    del param  # Unused.
-    if value is None:
-        return value
-    if isinstance(value, int):
-        int_value = value
-    else:
-        try:
-            int_value = int(value, 10)
-        except ValueError as exc:
-            raise click.BadParameter(_NOT_AN_INTEGER) from exc
-    if int_value < 0:
-        raise click.BadParameter(_NOT_A_NONNEGATIVE_INTEGER)
-    return int_value
-
-
-def _validate_length(
-    ctx: click.Context,
-    param: click.Parameter,
-    value: Any,  # noqa: ANN401
-) -> int | None:
-    """Check that the length is valid (int, 1 or larger).
-
-    Args:
-        ctx: The `click` context.
-        param: The current command-line parameter.
-        value: The parameter value to be checked.
-
-    Returns:
-        The parsed parameter value.
-
-    Raises:
-        click.BadParameter: The parameter value is invalid.
-
-    """
-    del ctx  # Unused.
-    del param  # Unused.
-    if value is None:
-        return value
-    if isinstance(value, int):
-        int_value = value
-    else:
-        try:
-            int_value = int(value, 10)
-        except ValueError as exc:
-            raise click.BadParameter(_NOT_AN_INTEGER) from exc
-    if int_value < 1:
-        raise click.BadParameter(_NOT_A_POSITIVE_INTEGER)
-    return int_value
-
-
 @derivepassphrase.command(
     'vault',
     context_settings={'help_option_names': ['-h', '--help']},
-    cls=CommandWithHelpGroups,
+    cls=cli_machinery.CommandWithHelpGroups,
     help=(
         _msg.TranslatedString(_msg.Label.DERIVEPASSPHRASE_VAULT_01),
         _msg.TranslatedString(
@@ -2196,7 +338,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_PHRASE_HELP_TEXT
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '-k',
@@ -2206,7 +348,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_KEY_HELP_TEXT
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '-l',
@@ -2214,14 +356,14 @@ def _validate_length(
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_length,
+    callback=cli_machinery.validate_length,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '-r',
@@ -2229,98 +371,98 @@ def _validate_length(
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_REPEAT_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--lower',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_LOWER_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--upper',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_UPPER_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--number',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_NUMBER_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--space',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_SPACE_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--dash',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_DASH_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '--symbol',
     metavar=_msg.TranslatedString(
         _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
     ),
-    callback=_validate_occurrence_constraint,
+    callback=cli_machinery.validate_occurrence_constraint,
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_SYMBOL_HELP_TEXT,
         metavar=_msg.TranslatedString(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=PassphraseGenerationOption,
+    cls=cli_machinery.PassphraseGenerationOption,
 )
 @click.option(
     '-n',
@@ -2333,7 +475,7 @@ def _validate_length(
             _msg.Label.VAULT_METAVAR_SERVICE
         ),
     ),
-    cls=ConfigurationOption,
+    cls=cli_machinery.ConfigurationOption,
 )
 @click.option(
     '-c',
@@ -2346,7 +488,7 @@ def _validate_length(
             _msg.Label.VAULT_METAVAR_SERVICE
         ),
     ),
-    cls=ConfigurationOption,
+    cls=cli_machinery.ConfigurationOption,
 )
 @click.option(
     '-x',
@@ -2359,7 +501,7 @@ def _validate_length(
             _msg.Label.VAULT_METAVAR_SERVICE
         ),
     ),
-    cls=ConfigurationOption,
+    cls=cli_machinery.ConfigurationOption,
 )
 @click.option(
     '--delete-globals',
@@ -2367,7 +509,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_DELETE_GLOBALS_HELP_TEXT,
     ),
-    cls=ConfigurationOption,
+    cls=cli_machinery.ConfigurationOption,
 )
 @click.option(
     '-X',
@@ -2377,7 +519,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_DELETE_ALL_HELP_TEXT,
     ),
-    cls=ConfigurationOption,
+    cls=cli_machinery.ConfigurationOption,
 )
 @click.option(
     '-e',
@@ -2392,8 +534,8 @@ def _validate_length(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=StorageManagementOption,
-    shell_complete=_shell_complete_path,
+    cls=cli_machinery.StorageManagementOption,
+    shell_complete=cli_helpers.shell_complete_path,
 )
 @click.option(
     '-i',
@@ -2408,8 +550,8 @@ def _validate_length(
             _msg.Label.PASSPHRASE_GENERATION_METAVAR_NUMBER
         ),
     ),
-    cls=StorageManagementOption,
-    shell_complete=_shell_complete_path,
+    cls=cli_machinery.StorageManagementOption,
+    shell_complete=cli_helpers.shell_complete_path,
 )
 @click.option(
     '--overwrite-existing/--merge-existing',
@@ -2418,7 +560,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_OVERWRITE_HELP_TEXT
     ),
-    cls=CompatibilityOption,
+    cls=cli_machinery.CompatibilityOption,
 )
 @click.option(
     '--unset',
@@ -2439,7 +581,7 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_UNSET_HELP_TEXT
     ),
-    cls=CompatibilityOption,
+    cls=cli_machinery.CompatibilityOption,
 )
 @click.option(
     '--export-as',
@@ -2448,17 +590,17 @@ def _validate_length(
     help=_msg.TranslatedString(
         _msg.Label.DERIVEPASSPHRASE_VAULT_EXPORT_AS_HELP_TEXT
     ),
-    cls=CompatibilityOption,
+    cls=cli_machinery.CompatibilityOption,
 )
-@version_option
-@color_forcing_pseudo_option
-@standard_logging_options
+@cli_machinery.version_option
+@cli_machinery.color_forcing_pseudo_option
+@cli_machinery.standard_logging_options
 @click.argument(
     'service',
     metavar=_msg.TranslatedString(_msg.Label.VAULT_METAVAR_SERVICE),
     required=False,
     default=None,
-    shell_complete=_shell_complete_service,
+    shell_complete=cli_helpers.shell_complete_service,
 )
 @click.pass_context
 def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
@@ -2590,14 +732,14 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
         if isinstance(param, click.Option):
             group: type[click.Option]
             known_option_groups = [
-                PassphraseGenerationOption,
-                ConfigurationOption,
-                StorageManagementOption,
-                LoggingOption,
-                CompatibilityOption,
-                StandardOption,
+                cli_machinery.PassphraseGenerationOption,
+                cli_machinery.ConfigurationOption,
+                cli_machinery.StorageManagementOption,
+                cli_machinery.LoggingOption,
+                cli_machinery.CompatibilityOption,
+                cli_machinery.StandardOption,
             ]
-            if isinstance(param, OptionGroupOption):
+            if isinstance(param, cli_machinery.OptionGroupOption):
                 for class_ in known_option_groups:
                     if isinstance(param, class_):
                         group = class_
@@ -2664,14 +806,14 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
 
     def get_config() -> _types.VaultConfig:
         try:
-            return _load_config()
+            return cli_helpers.load_config()
         except FileNotFoundError:
             try:
-                backup_config, exc = _migrate_and_load_old_config()
+                backup_config, exc = cli_helpers.migrate_and_load_old_config()
             except FileNotFoundError:
                 return {'services': {}}
-            old_name = _config_filename(subsystem='old settings.json').name
-            new_name = _config_filename(subsystem='vault').name
+            old_name = cli_helpers.config_filename(subsystem='old settings.json').name
+            new_name = cli_helpers.config_filename(subsystem='vault').name
             deprecation.warning(
                 _msg.TranslatedString(
                     _msg.WarnMsgTemplate.V01_STYLE_CONFIG,
@@ -2719,7 +861,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
 
     def put_config(config: _types.VaultConfig, /) -> None:
         try:
-            _save_config(config)
+            cli_helpers.save_config(config)
         except OSError as exc:
             err(
                 _msg.TranslatedString(
@@ -2740,7 +882,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
 
     def get_user_config() -> dict[str, Any]:
         try:
-            return _load_user_config()
+            return cli_helpers.load_user_config()
         except FileNotFoundError:
             return {}
         except OSError as exc:
@@ -2764,19 +906,19 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
     configuration: _types.VaultConfig
 
     check_incompatible_options('--phrase', '--key')
-    for group in (ConfigurationOption, StorageManagementOption):
+    for group in (cli_machinery.ConfigurationOption, cli_machinery.StorageManagementOption):
         for opt in options_in_group[group]:
             if opt != params_by_str['--config']:
-                for other_opt in options_in_group[PassphraseGenerationOption]:
+                for other_opt in options_in_group[cli_machinery.PassphraseGenerationOption]:
                     check_incompatible_options(opt, other_opt)
 
-    for group in (ConfigurationOption, StorageManagementOption):
+    for group in (cli_machinery.ConfigurationOption, cli_machinery.StorageManagementOption):
         for opt in options_in_group[group]:
-            for other_opt in options_in_group[ConfigurationOption]:
+            for other_opt in options_in_group[cli_machinery.ConfigurationOption]:
                 check_incompatible_options(opt, other_opt)
-            for other_opt in options_in_group[StorageManagementOption]:
+            for other_opt in options_in_group[cli_machinery.StorageManagementOption]:
                 check_incompatible_options(opt, other_opt)
-    sv_or_global_options = options_in_group[PassphraseGenerationOption]
+    sv_or_global_options = options_in_group[cli_machinery.PassphraseGenerationOption]
     for param in sv_or_global_options:
         if is_param_set(param) and not (
             service is not None or is_param_set(params_by_str['--config'])
@@ -2799,7 +941,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
     no_sv_options = [
         params_by_str['--delete-globals'],
         params_by_str['--clear'],
-        *options_in_group[StorageManagementOption],
+        *options_in_group[cli_machinery.StorageManagementOption],
     ]
     for param in no_sv_options:
         if is_param_set(param) and service is not None:
@@ -2948,7 +1090,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                 extra={'color': ctx.color},
             )
         for service_name in sorted(maybe_config['services'].keys()):
-            if not _is_completable_item(service_name):
+            if not cli_helpers.is_completable_item(service_name):
                 logger.warning(
                     _msg.TranslatedString(
                         _msg.WarnMsgTemplate.SERVICE_NAME_INCOMPLETABLE,
@@ -2957,14 +1099,14 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     extra={'color': ctx.color},
                 )
         try:
-            _check_for_misleading_passphrase(
+            cli_helpers.check_for_misleading_passphrase(
                 ('global',),
                 cast('dict[str, Any]', maybe_config.get('global', {})),
                 main_config=user_config,
                 ctx=ctx,
             )
             for key, value in maybe_config['services'].items():
-                _check_for_misleading_passphrase(
+                cli_helpers.check_for_misleading_passphrase(
                     ('services', key),
                     cast('dict[str, Any]', value),
                     main_config=user_config,
@@ -3059,7 +1201,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     ):
                         prog_name_pieces.appendleft(this_ctx.parent.info_name)
                         this_ctx = this_ctx.parent
-                    _print_config_as_sh_script(
+                    cli_helpers.print_config_as_sh_script(
                         configuration,
                         outfile=outfile,
                         prog_name_list=prog_name_pieces,
@@ -3116,7 +1258,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
         if use_key:
             try:
                 key = base64.standard_b64encode(
-                    _select_ssh_key(ctx=ctx)
+                    cli_helpers.select_ssh_key(ctx=ctx)
                 ).decode('ASCII')
             except IndexError:
                 err(
@@ -3162,7 +1304,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                     exc_info=exc,
                 )
         elif use_phrase:
-            maybe_phrase = _prompt_for_passphrase()
+            maybe_phrase = cli_helpers.prompt_for_passphrase()
             if not maybe_phrase:
                 err(
                     _msg.TranslatedString(
@@ -3183,7 +1325,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             elif use_phrase:
                 view['phrase'] = phrase
                 try:
-                    _check_for_misleading_passphrase(
+                    cli_helpers.check_for_misleading_passphrase(
                         ('services', service) if service else ('global',),
                         {'phrase': phrase},
                         main_config=user_config,
@@ -3225,7 +1367,7 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
                         setting=setting,
                     )
                     raise click.UsageError(str(err_msg))
-            if not _is_completable_item(service):
+            if not cli_helpers.is_completable_item(service):
                 logger.warning(
                     _msg.TranslatedString(
                         _msg.WarnMsgTemplate.SERVICE_NAME_INCOMPLETABLE,
@@ -3257,8 +1399,8 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             }
             if use_phrase:
                 try:
-                    _check_for_misleading_passphrase(
-                        _ORIGIN.INTERACTIVE,
+                    cli_helpers.check_for_misleading_passphrase(
+                        cli_helpers.ORIGIN.INTERACTIVE,
                         {'phrase': phrase},
                         main_config=user_config,
                         ctx=ctx,
@@ -3279,12 +1421,12 @@ def derivepassphrase_vault(  # noqa: C901,PLR0912,PLR0913,PLR0914,PLR0915
             # a key is given.  Finally, if nothing is set, error out.
             if use_key or use_phrase:
                 kwargs['phrase'] = (
-                    _key_to_phrase(key, error_callback=err)
+                    cli_helpers.key_to_phrase(key, error_callback=err)
                     if use_key
                     else phrase
                 )
             elif kwargs.get('key'):
-                kwargs['phrase'] = _key_to_phrase(
+                kwargs['phrase'] = cli_helpers.key_to_phrase(
                     kwargs['key'], error_callback=err
                 )
             elif kwargs.get('phrase'):

tests/__init__.py

Zeige Datei @ 623f749

@@ -27,6 +27,7 @@ from hypothesis import strategies
 from typing_extensions import NamedTuple, Self, assert_never
 
 from derivepassphrase import _types, cli, ssh_agent, vault
+from derivepassphrase._internals import cli_helpers, cli_machinery
 
 __all__ = ()
 
@@ -1738,7 +1739,7 @@ def suitable_ssh_keys(conn: Any) -> Iterator[_types.SSHKeyCommentPair]:
     """Return a two-item list of SSH test keys (key/comment pairs).
 
     Intended as a monkeypatching replacement for
-    `cli._get_suitable_ssh_keys` to better script and test the
+    `cli_machinery.get_suitable_ssh_keys` to better script and test the
     interactive key selection.  When used this way, `derivepassphrase`
     believes that only those two keys are loaded and suitable.
 
@@ -1806,18 +1807,20 @@ def isolated_config(
     # https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.9
     with contextlib.ExitStack() as stack:
         stack.enter_context(runner.isolated_filesystem())
-        stack.enter_context(cli.StandardCLILogging.ensure_standard_logging())
         stack.enter_context(
-            cli.StandardCLILogging.ensure_standard_warnings_logging()
+            cli_machinery.StandardCLILogging.ensure_standard_logging()
+        )
+        stack.enter_context(
+            cli_machinery.StandardCLILogging.ensure_standard_warnings_logging()
         )
         cwd = str(pathlib.Path.cwd().resolve())
         monkeypatch.setenv('HOME', cwd)
         monkeypatch.setenv('USERPROFILE', cwd)
         monkeypatch.delenv(env_name, raising=False)
-        config_dir = cli._config_filename(subsystem=None)
+        config_dir = cli_helpers.config_filename(subsystem=None)
         config_dir.mkdir(parents=True, exist_ok=True)
         if isinstance(main_config_str, str):
-            cli._config_filename('user configuration').write_text(
+            cli_helpers.config_filename('user configuration').write_text(
                 main_config_str, encoding='UTF-8'
             )
         yield
@@ -1855,7 +1858,7 @@ def isolated_vault_config(
     with isolated_config(
         monkeypatch=monkeypatch, runner=runner, main_config_str=main_config_str
     ):
-        config_filename = cli._config_filename(subsystem='vault')
+        config_filename = cli_helpers.config_filename(subsystem='vault')
         with config_filename.open('w', encoding='UTF-8') as outfile:
             json.dump(vault_config, outfile)
         yield

tests/test_derivepassphrase_cli.py

Zeige Datei @ 623f749

@@ -28,6 +28,7 @@ from typing_extensions import Any, NamedTuple
 
 import tests
 from derivepassphrase import _types, cli, ssh_agent, vault
+from derivepassphrase._internals import cli_helpers, cli_machinery
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Sequence
@@ -655,7 +656,7 @@ class TestCLI:
                 )
             )
             monkeypatch.setattr(
-                cli, '_prompt_for_passphrase', tests.auto_prompt
+                cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -687,7 +688,7 @@ class TestCLI:
                 )
             )
             monkeypatch.setattr(
-                cli, '_prompt_for_passphrase', tests.auto_prompt
+                cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -788,7 +789,7 @@ class TestCLI:
                 )
             )
             monkeypatch.setattr(
-                cli, '_get_suitable_ssh_keys', tests.suitable_ssh_keys
+                cli_helpers, 'get_suitable_ssh_keys', tests.suitable_ssh_keys
             )
             monkeypatch.setattr(
                 vault.Vault, 'phrase_from_key', tests.phrase_from_key
@@ -1080,7 +1081,7 @@ class TestCLI:
                 )
             )
             monkeypatch.setattr(
-                cli, '_prompt_for_passphrase', tests.auto_prompt
+                cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -1116,7 +1117,7 @@ class TestCLI:
                     )
                 )
                 monkeypatch.setattr(
-                    cli, '_prompt_for_passphrase', tests.auto_prompt
+                    cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
                 )
                 result_ = runner.invoke(
                     cli.derivepassphrase_vault,
@@ -1158,7 +1159,7 @@ class TestCLI:
                 )
             )
             monkeypatch.setattr(
-                cli, '_prompt_for_passphrase', tests.auto_prompt
+                cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -1171,7 +1172,7 @@ class TestCLI:
             assert all(map(is_expected_warning, caplog.record_tuples)), (
                 'expected known error output'
             )
-            assert cli._load_config() == {
+            assert cli_helpers.load_config() == {
                 'global': {'length': 30},
                 'services': {},
             }, 'requested configuration change was not applied'
@@ -1188,7 +1189,7 @@ class TestCLI:
             assert all(map(is_expected_warning, caplog.record_tuples)), (
                 'expected known error output'
             )
-            assert cli._load_config() == {
+            assert cli_helpers.load_config() == {
                 'global': {'length': 30},
                 'services': {'': {'length': 40}},
             }, 'requested configuration change was not applied'
@@ -1263,7 +1264,7 @@ class TestCLI:
                 input=json.dumps(config),
                 catch_exceptions=False,
             )
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config2 = json.load(infile)
@@ -1316,7 +1317,7 @@ class TestCLI:
                 input=json.dumps(config),
                 catch_exceptions=False,
             )
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config3 = json.load(infile)
@@ -1403,10 +1404,10 @@ class TestCLI:
                     vault_config={'services': {}},
                 )
             )
-            cli._config_filename(subsystem='vault').write_text(
+            cli_helpers.config_filename(subsystem='vault').write_text(
                 'This string is not valid JSON.\n', encoding='UTF-8'
             )
-            dname = cli._config_filename(subsystem=None)
+            dname = cli_helpers.config_filename(subsystem=None)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--import', os.fsdecode(dname)],
@@ -1441,7 +1442,7 @@ class TestCLI:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='vault').unlink(missing_ok=True)
+            cli_helpers.config_filename(subsystem='vault').unlink(missing_ok=True)
             result_ = runner.invoke(
                 # Test parent context navigation by not calling
                 # `cli.derivepassphrase_vault` directly.  Used e.g. in
@@ -1514,7 +1515,7 @@ class TestCLI:
                     runner=runner,
                 )
             )
-            config_file = cli._config_filename(subsystem='vault')
+            config_file = cli_helpers.config_filename(subsystem='vault')
             config_file.unlink(missing_ok=True)
             config_file.mkdir(parents=True, exist_ok=True)
             result_ = runner.invoke(
@@ -1552,7 +1553,7 @@ class TestCLI:
                     runner=runner,
                 )
             )
-            dname = cli._config_filename(subsystem=None)
+            dname = cli_helpers.config_filename(subsystem=None)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--export', os.fsdecode(dname), *export_options],
@@ -1588,7 +1589,7 @@ class TestCLI:
                     runner=runner,
                 )
             )
-            config_dir = cli._config_filename(subsystem=None)
+            config_dir = cli_helpers.config_filename(subsystem=None)
             with contextlib.suppress(FileNotFoundError):
                 shutil.rmtree(config_dir)
             config_dir.write_text('Obstruction!!\n')
@@ -1635,7 +1636,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(result_)
             assert result.clean_exit(empty_stderr=True), 'expected clean exit'
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config = json.load(infile)
@@ -1669,7 +1670,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(result_)
             assert result.clean_exit(empty_stderr=True), 'expected clean exit'
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config = json.load(infile)
@@ -1706,7 +1707,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(result_)
             assert result.clean_exit(empty_stderr=True), 'expected clean exit'
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config = json.load(infile)
@@ -1742,7 +1743,7 @@ contents go here
             assert result.error_exit(error='the user aborted the request'), (
                 'expected known error message'
             )
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config = json.load(infile)
@@ -1816,7 +1817,7 @@ contents go here
                 )
             )
             monkeypatch.setattr(
-                cli, '_get_suitable_ssh_keys', tests.suitable_ssh_keys
+                cli_helpers, 'get_suitable_ssh_keys', tests.suitable_ssh_keys
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -1826,7 +1827,7 @@ contents go here
             )
             result = tests.ReadableResult.parse(result_)
             assert result.clean_exit(), 'expected clean exit'
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config = json.load(infile)
@@ -1884,7 +1885,7 @@ contents go here
                 )
             )
             monkeypatch.setattr(
-                cli, '_get_suitable_ssh_keys', tests.suitable_ssh_keys
+                cli_helpers, 'get_suitable_ssh_keys', tests.suitable_ssh_keys
             )
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
@@ -1919,7 +1920,7 @@ contents go here
             def raiser(*_args: Any, **_kwargs: Any) -> None:
                 raise RuntimeError(custom_error)
 
-            monkeypatch.setattr(cli, '_select_ssh_key', raiser)
+            monkeypatch.setattr(cli_helpers, 'select_ssh_key', raiser)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--key', '--config'],
@@ -2009,7 +2010,7 @@ contents go here
                 )
             )
             tests.make_file_readonly(
-                cli._config_filename(subsystem='vault'),
+                cli_helpers.config_filename(subsystem='vault'),
                 try_race_free_implementation=try_race_free_implementation,
             )
             result_ = runner.invoke(
@@ -2045,7 +2046,7 @@ contents go here
                 del config
                 raise RuntimeError(custom_error)
 
-            monkeypatch.setattr(cli, '_save_config', raiser)
+            monkeypatch.setattr(cli_helpers, 'save_config', raiser)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--config', '--length=15', '--', DUMMY_SERVICE],
@@ -2267,7 +2268,7 @@ contents go here
                 )
             )
             with contextlib.suppress(FileNotFoundError):
-                shutil.rmtree(cli._config_filename(subsystem=None))
+                shutil.rmtree(cli_helpers.config_filename(subsystem=None))
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--config', '-p'],
@@ -2279,7 +2280,7 @@ contents go here
             assert result.stderr == 'Passphrase:', (
                 'program unexpectedly failed?!'
             )
-            with cli._config_filename(subsystem='vault').open(
+            with cli_helpers.config_filename(subsystem='vault').open(
                 encoding='UTF-8'
             ) as infile:
                 config_readback = json.load(infile)
@@ -2313,17 +2314,17 @@ contents go here
                     runner=runner,
                 )
             )
-            save_config_ = cli._save_config
+            save_config_ = cli_helpers.save_config
 
             def obstruct_config_saving(*args: Any, **kwargs: Any) -> Any:
-                config_dir = cli._config_filename(subsystem=None)
+                config_dir = cli_helpers.config_filename(subsystem=None)
                 with contextlib.suppress(FileNotFoundError):
                     shutil.rmtree(config_dir)
                 config_dir.write_text('Obstruction!!\n')
-                monkeypatch.setattr(cli, '_save_config', save_config_)
+                monkeypatch.setattr(cli_helpers, 'save_config', save_config_)
                 return save_config_(*args, **kwargs)
 
-            monkeypatch.setattr(cli, '_save_config', obstruct_config_saving)
+            monkeypatch.setattr(cli_helpers, 'save_config', obstruct_config_saving)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--config', '-p'],
@@ -2357,7 +2358,7 @@ contents go here
                 del config
                 raise RuntimeError(custom_error)
 
-            monkeypatch.setattr(cli, '_save_config', raiser)
+            monkeypatch.setattr(cli_helpers, 'save_config', raiser)
             result_ = runner.invoke(
                 cli.derivepassphrase_vault,
                 ['--config', '-p'],
@@ -2730,7 +2731,7 @@ class TestCLIUtils:
         self,
         config: Any,
     ) -> None:
-        """`cli._load_config` works for valid configurations."""
+        """[`cli_helpers.load_config`][] works for valid configurations."""
         runner = click.testing.CliRunner(mix_stderr=False)
         # TODO(the-13th-letter): Rewrite using parenthesized
         # with-statements.
@@ -2744,15 +2745,15 @@ class TestCLIUtils:
                     vault_config=config,
                 )
             )
-            config_filename = cli._config_filename(subsystem='vault')
+            config_filename = cli_helpers.config_filename(subsystem='vault')
             with config_filename.open(encoding='UTF-8') as fileobj:
                 assert json.load(fileobj) == config
-            assert cli._load_config() == config
+            assert cli_helpers.load_config() == config
 
     def test_110_save_bad_config(
         self,
     ) -> None:
-        """`cli._save_config` fails for bad configurations."""
+        """[`cli_helpers.save_config`][] fails for bad configurations."""
         runner = click.testing.CliRunner(mix_stderr=False)
         # TODO(the-13th-letter): Rewrite using parenthesized
         # with-statements.
@@ -2769,10 +2770,10 @@ class TestCLIUtils:
             stack.enter_context(
                 pytest.raises(ValueError, match='Invalid vault config')
             )
-            cli._save_config(None)  # type: ignore[arg-type]
+            cli_helpers.save_config(None)  # type: ignore[arg-type]
 
     def test_111_prompt_for_selection_multiple(self) -> None:
-        """`cli._prompt_for_selection` works in the "multiple" case."""
+        """[`cli_helpers.prompt_for_selection`][] works in the "multiple" case."""
 
         @click.command()
         @click.option('--heading', default='Our menu:')
@@ -2798,7 +2799,7 @@ class TestCLIUtils:
                     'and a fried egg on top and spam'
                 ),
             ]
-            index = cli._prompt_for_selection(items, heading=heading)
+            index = cli_helpers.prompt_for_selection(items, heading=heading)
             click.echo('A fine choice: ', nl=False)
             click.echo(items[index])
             click.echo('(Note: Vikings strictly optional.)')
@@ -2849,14 +2850,14 @@ Your selection? (1-10, leave empty to abort):\x20
         ), 'expected known output'
 
     def test_112_prompt_for_selection_single(self) -> None:
-        """`cli._prompt_for_selection` works in the "single" case."""
+        """[`cli_helpers.prompt_for_selection`][] works in the "single" case."""
 
         @click.command()
         @click.option('--item', default='baked beans')
         @click.argument('prompt')
         def driver(item: str, prompt: str) -> None:
             try:
-                cli._prompt_for_selection(
+                cli_helpers.prompt_for_selection(
                     [item], heading='', single_choice_prompt=prompt
                 )
             except IndexError:
@@ -2898,14 +2899,14 @@ Boo.
     def test_113_prompt_for_passphrase(
         self,
     ) -> None:
-        """`cli._prompt_for_passphrase` works."""
+        """[`cli_helpers.prompt_for_passphrase`][] works."""
         with pytest.MonkeyPatch.context() as monkeypatch:
             monkeypatch.setattr(
                 click,
                 'prompt',
                 lambda *a, **kw: json.dumps({'args': a, 'kwargs': kw}),
             )
-            res = json.loads(cli._prompt_for_passphrase())
+            res = json.loads(cli_helpers.prompt_for_passphrase())
         err_msg = 'missing arguments to passphrase prompt'
         assert 'args' in res, err_msg
         assert 'kwargs' in res, err_msg
@@ -2926,17 +2927,17 @@ Boo.
         standard error prefixed with the program name.
 
         """
-        prog_name = cli.StandardCLILogging.prog_name
-        package_name = cli.StandardCLILogging.package_name
+        prog_name = cli_machinery.StandardCLILogging.prog_name
+        package_name = cli_machinery.StandardCLILogging.package_name
         logger = logging.getLogger(package_name)
         deprecation_logger = logging.getLogger(f'{package_name}.deprecation')
-        logging_cm = cli.StandardCLILogging.ensure_standard_logging()
+        logging_cm = cli_machinery.StandardCLILogging.ensure_standard_logging()
         with logging_cm:
             assert (
                 sum(
                     1
                     for h in logger.handlers
-                    if h is cli.StandardCLILogging.cli_handler
+                    if h is cli_machinery.StandardCLILogging.cli_handler
                 )
                 == 1
             )
@@ -2947,7 +2948,7 @@ Boo.
                     sum(
                         1
                         for h in logger.handlers
-                        if h is cli.StandardCLILogging.cli_handler
+                        if h is cli_machinery.StandardCLILogging.cli_handler
                     )
                     == 1
                 )
@@ -2963,7 +2964,7 @@ Boo.
                 sum(
                     1
                     for h in logger.handlers
-                    if h is cli.StandardCLILogging.cli_handler
+                    if h is cli_machinery.StandardCLILogging.cli_handler
                 )
                 == 1
             )
@@ -2990,7 +2991,7 @@ Boo.
         actually emits to standard error.
 
         """
-        warnings_cm = cli.StandardCLILogging.ensure_standard_warnings_logging()
+        warnings_cm = cli_machinery.StandardCLILogging.ensure_standard_warnings_logging()
         THE_FUTURE = 'the future will be here sooner than you think'  # noqa: N806
         JUST_TESTING = 'just testing whether warnings work'  # noqa: N806
         with warnings_cm:
@@ -2998,7 +2999,7 @@ Boo.
                 sum(
                     1
                     for h in logging.getLogger('py.warnings').handlers
-                    if h is cli.StandardCLILogging.warnings_handler
+                    if h is cli_machinery.StandardCLILogging.warnings_handler
                 )
                 == 1
             )
@@ -3053,7 +3054,7 @@ Boo.
         """
         prog_name_list = ('derivepassphrase', 'vault')
         with io.StringIO() as outfile:
-            cli._print_config_as_sh_script(
+            cli_helpers.print_config_as_sh_script(
                 config, outfile=outfile, prog_name_list=prog_name_list
             )
             script = outfile.getvalue()
@@ -3073,7 +3074,7 @@ Boo.
             for result_ in vault_config_exporter_shell_interpreter(script):
                 result = tests.ReadableResult.parse(result_)
                 assert result.clean_exit()
-            assert cli._load_config() == config
+            assert cli_helpers.load_config() == config
 
     @tests.hypothesis_settings_coverage_compatible
     @hypothesis.given(
@@ -3345,7 +3346,7 @@ Boo.
                 assert result.clean_exit(empty_stderr=True), (
                     'expected clean exit'
                 )
-                with cli._config_filename(subsystem='vault').open(
+                with cli_helpers.config_filename(subsystem='vault').open(
                     encoding='UTF-8'
                 ) as infile:
                     config_readback = json.load(infile)
@@ -3363,8 +3364,8 @@ Boo.
     @pytest.mark.parametrize(
         ['vfunc', 'input'],
         [
-            (cli._validate_occurrence_constraint, 20),
-            (cli._validate_length, 20),
+            (cli_machinery.validate_occurrence_constraint, 20),
+            (cli_machinery.validate_length, 20),
         ],
     )
     def test_210a_validate_constraints_manually(
@@ -3383,7 +3384,7 @@ Boo.
         running_ssh_agent: tests.RunningSSHAgentInfo,
         conn_hint: str,
     ) -> None:
-        """`cli._get_suitable_ssh_keys` works."""
+        """[`cli_helpers.get_suitable_ssh_keys`][] works."""
         with pytest.MonkeyPatch.context() as monkeypatch:
             monkeypatch.setenv('SSH_AUTH_SOCK', running_ssh_agent.socket)
             monkeypatch.setattr(
@@ -3403,7 +3404,7 @@ Boo.
                 hint = None
             exception: Exception | None = None
             try:
-                list(cli._get_suitable_ssh_keys(hint))
+                list(cli_helpers.get_suitable_ssh_keys(hint))
             except RuntimeError:  # pragma: no cover
                 pass
             except Exception as e:  # noqa: BLE001 # pragma: no cover
@@ -3418,7 +3419,7 @@ Boo.
         skip_if_no_af_unix_support: None,
         ssh_agent_client_with_test_keys_loaded: ssh_agent.SSHAgentClient,
     ) -> None:
-        """All errors in `cli._key_to_phrase` are handled."""
+        """All errors in [`cli_helpers.key_to_phrase`][] are handled."""
 
         class ErrCallback(BaseException):
             def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -3454,19 +3455,19 @@ Boo.
                 with pytest.raises(
                     ErrCallback, match='not loaded into the agent'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
             with monkeypatch.context() as mp:
                 mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail)
                 with pytest.raises(
                     ErrCallback, match='SSH agent failed to or refused to'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
             with monkeypatch.context() as mp:
                 mp.setattr(ssh_agent.SSHAgentClient, 'list_keys', fail_runtime)
                 with pytest.raises(
                     ErrCallback, match='SSH agent failed to or refused to'
                 ) as excinfo:
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
                 assert excinfo.value.kwargs
                 assert isinstance(
                     excinfo.value.kwargs['exc_info'],
@@ -3482,25 +3483,25 @@ Boo.
                 with pytest.raises(
                     ErrCallback, match='Cannot find any running SSH agent'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
             with monkeypatch.context() as mp:
                 mp.setenv('SSH_AUTH_SOCK', os.environ['SSH_AUTH_SOCK'] + '~')
                 with pytest.raises(
                     ErrCallback, match='Cannot connect to the SSH agent'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
             with monkeypatch.context() as mp:
                 mp.delattr(socket, 'AF_UNIX', raising=True)
                 with pytest.raises(
                     ErrCallback, match='does not support UNIX domain sockets'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
             with monkeypatch.context() as mp:
                 mp.setattr(ssh_agent.SSHAgentClient, 'sign', fail_runtime)
                 with pytest.raises(
                     ErrCallback, match='violates the communications protocol'
                 ):
-                    cli._key_to_phrase(loaded_key, error_callback=err)
+                    cli_helpers.key_to_phrase(loaded_key, error_callback=err)
 
 
 # TODO(the-13th-letter): Remove this class in v1.0.
@@ -3544,10 +3545,10 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(config, indent=2) + '\n', encoding='UTF-8'
             )
-            assert cli._migrate_and_load_old_config()[0] == config
+            assert cli_helpers.migrate_and_load_old_config()[0] == config
 
     @pytest.mark.parametrize(
         'config',
@@ -3585,10 +3586,10 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(config, indent=2) + '\n', encoding='UTF-8'
             )
-            assert cli._migrate_and_load_old_config() == (config, None)
+            assert cli_helpers.migrate_and_load_old_config() == (config, None)
 
     @pytest.mark.parametrize(
         'config',
@@ -3626,13 +3627,13 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(config, indent=2) + '\n', encoding='UTF-8'
             )
-            cli._config_filename(subsystem='vault').mkdir(
+            cli_helpers.config_filename(subsystem='vault').mkdir(
                 parents=True, exist_ok=True
             )
-            config2, err = cli._migrate_and_load_old_config()
+            config2, err = cli_helpers.migrate_and_load_old_config()
             assert config2 == config
             assert isinstance(err, OSError)
             assert err.errno == errno.EISDIR
@@ -3673,11 +3674,11 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(config, indent=2) + '\n', encoding='UTF-8'
             )
-            with pytest.raises(ValueError, match=cli._INVALID_VAULT_CONFIG):
-                cli._migrate_and_load_old_config()
+            with pytest.raises(ValueError, match=cli_helpers.INVALID_VAULT_CONFIG):
+                cli_helpers.migrate_and_load_old_config()
 
     def test_200_forward_export_vault_path_parameter(
         self,
@@ -3771,7 +3772,7 @@ class TestCLITransition:
                 )
             )
             monkeypatch.setattr(
-                cli, '_prompt_for_passphrase', tests.auto_prompt
+                cli_helpers, 'prompt_for_passphrase', tests.auto_prompt
             )
             result_ = runner.invoke(
                 cli.derivepassphrase,
@@ -3844,7 +3845,7 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(
                     {'services': {DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS}},
                     indent=2,
@@ -3883,7 +3884,7 @@ class TestCLITransition:
                     runner=runner,
                 )
             )
-            cli._config_filename(subsystem='old settings.json').write_text(
+            cli_helpers.config_filename(subsystem='old settings.json').write_text(
                 json.dumps(
                     {'services': {DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS}},
                     indent=2,
@@ -3896,7 +3897,7 @@ class TestCLITransition:
                 raise OSError(
                     errno.EACCES,
                     os.strerror(errno.EACCES),
-                    cli._config_filename(subsystem='vault'),
+                    cli_helpers.config_filename(subsystem='vault'),
                 )
 
             monkeypatch.setattr(os, 'replace', raiser)
@@ -3933,11 +3934,11 @@ class TestCLITransition:
                     vault_config=config,
                 )
             )
-            old_name = cli._config_filename(subsystem='old settings.json')
-            new_name = cli._config_filename(subsystem='vault')
+            old_name = cli_helpers.config_filename(subsystem='old settings.json')
+            new_name = cli_helpers.config_filename(subsystem='vault')
             old_name.unlink(missing_ok=True)
             new_name.rename(old_name)
-            assert cli._shell_complete_service(
+            assert cli_helpers.shell_complete_service(
                 click.Context(cli.derivepassphrase),
                 click.Argument(['some_parameter']),
                 '',
@@ -4182,7 +4183,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             The amended configuration.
 
         """
-        cli._save_config(config)
+        cli_helpers.save_config(config)
         config_global = config.get('global', {})
         maybe_unset = set(maybe_unset) - setting.keys()
         if overwrite:
@@ -4211,7 +4212,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         )
         result = tests.ReadableResult.parse(result_)
         assert result.clean_exit(empty_stderr=False)
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     @stateful.rule(
@@ -4255,7 +4256,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             The amended configuration.
 
         """
-        cli._save_config(config)
+        cli_helpers.save_config(config)
         config_service = config['services'].get(service, {})
         maybe_unset = set(maybe_unset) - setting.keys()
         if overwrite:
@@ -4285,7 +4286,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         )
         result = tests.ReadableResult.parse(result_)
         assert result.clean_exit(empty_stderr=False)
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     @stateful.rule(
@@ -4306,7 +4307,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             The pruned configuration.
 
         """
-        cli._save_config(config)
+        cli_helpers.save_config(config)
         config.pop('global', None)
         result_ = self.runner.invoke(
             cli.derivepassphrase_vault,
@@ -4316,7 +4317,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         )
         result = tests.ReadableResult.parse(result_)
         assert result.clean_exit(empty_stderr=False)
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     @stateful.rule(
@@ -4346,7 +4347,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
 
         """
         config, service = config_and_service
-        cli._save_config(config)
+        cli_helpers.save_config(config)
         config['services'].pop(service, None)
         result_ = self.runner.invoke(
             cli.derivepassphrase_vault,
@@ -4356,7 +4357,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         )
         result = tests.ReadableResult.parse(result_)
         assert result.clean_exit(empty_stderr=False)
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     @stateful.rule(
@@ -4377,7 +4378,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             The empty configuration.
 
         """
-        cli._save_config(config)
+        cli_helpers.save_config(config)
         config = {'services': {}}
         result_ = self.runner.invoke(
             cli.derivepassphrase_vault,
@@ -4387,7 +4388,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         )
         result = tests.ReadableResult.parse(result_)
         assert result.clean_exit(empty_stderr=False)
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     @stateful.rule(
@@ -4418,7 +4419,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
             The imported or merged configuration.
 
         """
-        cli._save_config(base_config)
+        cli_helpers.save_config(base_config)
         config = (
             self.fold_configs(config_to_import, base_config)
             if not overwrite
@@ -4435,7 +4436,7 @@ class ConfigManagementStateMachine(stateful.RuleBasedStateMachine):
         assert tests.ReadableResult.parse(result_).clean_exit(
             empty_stderr=False
         )
-        assert cli._load_config() == config
+        assert cli_helpers.load_config() == config
         return config
 
     def teardown(self) -> None:
@@ -4481,9 +4482,10 @@ def zsh_format(item: click.shell_completion.CompletionItem) -> str:
     dictated by [`click`][].  Upstream `click` currently (v8.2.0) does
     not deal with colons in the value correctly when the help text is
     non-degenerate.  Our formatter here does, provided the upstream
-    `zsh` completion script is used; see the [`cli.ZshComplete`][]
-    class.  A request is underway to merge this change into upstream
-    `click`; see [`pallets/click#2846`][PR2846].
+    `zsh` completion script is used; see the
+    [`cli_machinery.ZshComplete`][] class.  A request is underway to
+    merge this change into upstream `click`; see
+    [`pallets/click#2846`][PR2846].
 
     [PR2846]: https://github.com/pallets/click/pull/2846
 
@@ -4579,7 +4581,7 @@ class TestShellCompletion:
         is_completable: bool,
     ) -> None:
         """Our `_is_completable_item` predicate for service names works."""
-        assert cli._is_completable_item(partial) == is_completable
+        assert cli_helpers.is_completable_item(partial) == is_completable
 
     @pytest.mark.parametrize(
         ['command_prefix', 'incomplete', 'completions'],
@@ -4820,7 +4822,7 @@ class TestShellCompletion:
         [
             pytest.param(
                 {'services': {DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy()}},
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 [DUMMY_SERVICE],
@@ -4828,7 +4830,7 @@ class TestShellCompletion:
             ),
             pytest.param(
                 {'services': {}},
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 [],
@@ -4841,7 +4843,7 @@ class TestShellCompletion:
                         'newline\nin\nname': DUMMY_CONFIG_SETTINGS.copy(),
                     }
                 },
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 [DUMMY_SERVICE],
@@ -4854,7 +4856,7 @@ class TestShellCompletion:
                         'backspace\bin\bname': DUMMY_CONFIG_SETTINGS.copy(),
                     }
                 },
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 [DUMMY_SERVICE],
@@ -4867,7 +4869,7 @@ class TestShellCompletion:
                         'colon:in:name': DUMMY_CONFIG_SETTINGS.copy(),
                     }
                 },
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 sorted([DUMMY_SERVICE, 'colon:in:name']),
@@ -4884,7 +4886,7 @@ class TestShellCompletion:
                         'del\x7fin\x7fname': DUMMY_CONFIG_SETTINGS.copy(),
                     }
                 },
-                cli._shell_complete_service,
+                cli_helpers.shell_complete_service,
                 ['vault'],
                 '',
                 sorted([DUMMY_SERVICE, 'colon:in:name']),
@@ -4892,7 +4894,7 @@ class TestShellCompletion:
             ),
             pytest.param(
                 {'services': {DUMMY_SERVICE: DUMMY_CONFIG_SETTINGS.copy()}},
-                cli._shell_complete_path,
+                cli_helpers.shell_complete_path,
                 ['vault', '--import'],
                 '',
                 [click.shell_completion.CompletionItem('', type='file')],
@@ -4900,7 +4902,7 @@ class TestShellCompletion:
             ),
             pytest.param(
                 {'services': {}},
-                cli._shell_complete_path,
+                cli_helpers.shell_complete_path,
                 ['vault', '--import'],
                 '',
                 [click.shell_completion.CompletionItem('', type='file')],
@@ -5166,7 +5168,7 @@ class TestShellCompletion:
             assert tests.warning_emitted(
                 'not be available for completion', caplog.record_tuples
             ), 'expected known warning message in stderr'
-            assert cli._load_config() == config
+            assert cli_helpers.load_config() == config
             comp = self.Completions(['vault'], incomplete)
             assert frozenset(comp.get_words()) == completions
 
@@ -5189,8 +5191,8 @@ class TestShellCompletion:
                     },
                 )
             )
-            cli._config_filename(subsystem='vault').unlink(missing_ok=True)
-            assert not cli._shell_complete_service(
+            cli_helpers.config_filename(subsystem='vault').unlink(missing_ok=True)
+            assert not cli_helpers.shell_complete_service(
                 click.Context(cli.derivepassphrase),
                 click.Argument(['some_parameter']),
                 '',
@@ -5221,8 +5223,8 @@ class TestShellCompletion:
             def raiser(*_a: Any, **_kw: Any) -> NoReturn:
                 raise exc_type('just being difficult')  # noqa: EM101,TRY003
 
-            monkeypatch.setattr(cli, '_load_config', raiser)
-            assert not cli._shell_complete_service(
+            monkeypatch.setattr(cli_helpers, 'load_config', raiser)
+            assert not cli_helpers.shell_complete_service(
                 click.Context(cli.derivepassphrase),
                 click.Argument(['some_parameter']),
                 '',

tests/test_derivepassphrase_ssh_agent.py

Zeige Datei @ 623f749

@@ -20,7 +20,8 @@ import pytest
 from hypothesis import strategies
 
 import tests
-from derivepassphrase import _types, cli, ssh_agent, vault
+from derivepassphrase import _types, ssh_agent, vault
+from derivepassphrase._internals import cli_helpers, cli_machinery
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -576,8 +577,8 @@ class TestAgentInteraction:
 
         @click.command()
         def driver() -> None:
-            """Call `cli._select_ssh_key` directly, as a command."""
-            key = cli._select_ssh_key()
+            """Call [`cli_helpers.select_ssh_key`][] directly, as a command."""
+            key = cli_helpers.select_ssh_key()
             click.echo(base64.standard_b64encode(key).decode('ASCII'))
 
         # TODO(the-13th-letter): (Continued from above.)  Update input


...	...	@@ -29,12 +29,14 @@ nav:
29	29	- Technical prerequisites:
30	30	- 'Using derivepassphrase vault with an SSH key': reference/prerequisites-ssh-key.md
31	31	- 'Internal API docs: Submodule derivepassphrase._internals':
	32	+ - Submodule cli_helpers: reference/derivepassphrase._internals.cli_helpers.md
	33	+ - Submodule cli_machinery: reference/derivepassphrase._internals.cli_machinery.md
32	34	- Submodule cli_messages: reference/derivepassphrase._internals.cli_messages.md
33	35	- 'Internal API docs: Tests':
34	36	- Basic testing infrastructure: reference/tests.md
35	37	- Localization machinery: reference/tests.test_l10n.md
36	38	- derivepassphrase command-line:
37		- - cli module: reference/tests.test_derivepassphrase_cli.md
	39	+ - cli module, helpers and machinery: reference/tests.test_derivepassphrase_cli.md
38	40	- '"export vault" subcommand tests': reference/tests.test_derivepassphrase_cli_export_vault.md
39	41	- exporter module: reference/tests.test_derivepassphrase_exporter.md
40	42	- sequin module: reference/tests.test_derivepassphrase_sequin.md

...	...	@@ -27,6 +27,7 @@ from hypothesis import strategies
27	27	from typing_extensions import NamedTuple, Self, assert_never
28	28
29	29	from derivepassphrase import _types, cli, ssh_agent, vault
	30	+from derivepassphrase._internals import cli_helpers, cli_machinery
30	31
31	32	__all__ = ()
32	33
...	...	@@ -1738,7 +1739,7 @@ def suitable_ssh_keys(conn: Any) -> Iterator[_types.SSHKeyCommentPair]:
1738	1739	"""Return a two-item list of SSH test keys (key/comment pairs).
1739	1740
1740	1741	Intended as a monkeypatching replacement for
1741		- `cli._get_suitable_ssh_keys` to better script and test the
	1742	+ `cli_machinery.get_suitable_ssh_keys` to better script and test the
1742	1743	interactive key selection. When used this way, `derivepassphrase`
1743	1744	believes that only those two keys are loaded and suitable.
1744	1745
...	...	@@ -1806,18 +1807,20 @@ def isolated_config(
1806	1807	# https://the13thletter.info/derivepassphrase/latest/pycompatibility/#after-eol-py3.9
1807	1808	with contextlib.ExitStack() as stack:
1808	1809	stack.enter_context(runner.isolated_filesystem())
1809		- stack.enter_context(cli.StandardCLILogging.ensure_standard_logging())
1810	1810	stack.enter_context(
1811		- cli.StandardCLILogging.ensure_standard_warnings_logging()
	1811	+ cli_machinery.StandardCLILogging.ensure_standard_logging()
	1812	+ )
	1813	+ stack.enter_context(
	1814	+ cli_machinery.StandardCLILogging.ensure_standard_warnings_logging()
1812	1815	)
1813	1816	cwd = str(pathlib.Path.cwd().resolve())
1814	1817	monkeypatch.setenv('HOME', cwd)
1815	1818	monkeypatch.setenv('USERPROFILE', cwd)
1816	1819	monkeypatch.delenv(env_name, raising=False)
1817		- config_dir = cli._config_filename(subsystem=None)
	1820	+ config_dir = cli_helpers.config_filename(subsystem=None)
1818	1821	config_dir.mkdir(parents=True, exist_ok=True)
1819	1822	if isinstance(main_config_str, str):
1820		- cli._config_filename('user configuration').write_text(
	1823	+ cli_helpers.config_filename('user configuration').write_text(
1821	1824	main_config_str, encoding='UTF-8'
1822	1825	)
1823	1826	yield
...	...	@@ -1855,7 +1858,7 @@ def isolated_vault_config(
1855	1858	with isolated_config(
1856	1859	monkeypatch=monkeypatch, runner=runner, main_config_str=main_config_str
1857	1860	):
1858		- config_filename = cli._config_filename(subsystem='vault')
	1861	+ config_filename = cli_helpers.config_filename(subsystem='vault')
1859	1862	with config_filename.open('w', encoding='UTF-8') as outfile:
1860	1863	json.dump(vault_config, outfile)
1861	1864	yield

...	...	@@ -20,7 +20,8 @@ import pytest
20	20	from hypothesis import strategies
21	21
22	22	import tests
23		-from derivepassphrase import _types, cli, ssh_agent, vault
	23	+from derivepassphrase import _types, ssh_agent, vault
	24	+from derivepassphrase._internals import cli_helpers, cli_machinery
24	25
25	26	if TYPE_CHECKING:
26	27	from collections.abc import Iterable
...	...	@@ -576,8 +577,8 @@ class TestAgentInteraction:
576	577
577	578	@click.command()
578	579	def driver() -> None:
579		- """Call `cli._select_ssh_key` directly, as a command."""
580		- key = cli._select_ssh_key()
	580	+ """Call [`cli_helpers.select_ssh_key`][] directly, as a command."""
	581	+ key = cli_helpers.select_ssh_key()
581	582	click.echo(base64.standard_b64encode(key).decode('ASCII'))
582	583
583	584	# TODO(the-13th-letter): (Continued from above.) Update input
584	585