Skip to content

derivepassphrase._internals.cli_messages

Messages for the command-line interface of derivepassphrase.

Also contains some machinery related to internationalization and localization.

Warning

Non-public module (implementation detail), provided for didactical and educational purposes only. Subject to change without notice, including removal.

MsgTemplate module-attribute

A type alias for all enums containing translatable strings as values.

MSG_TEMPLATE_CLASSES module-attribute

A collection all enums containing translatable strings as values.

DebugTranslations

Bases: NullTranslations

A debug object indicating which known message is being requested.

Each call to the *gettext methods will return the enum name if the message is a known translatable message for the derivepassphrase command-line interface, or the message itself otherwise.

TranslatableString

Bases: NamedTuple

Translatable string as used by the derivepassphrase command-line.

For typing purposes.

Attributes:

Name Type Description
l10n_context str

The localization context, as per gettext. Used to disambiguate different uses of the same translatable string.

singular str

The translatable message, base case.

plural str

The translatable message, plural case. Usually unset.

translator_comments str

Explicit commentary for the translator.

flags frozenset[str]

.mo file flags for this message, e.g. to indicate the string formatting style in use.

l10n_context instance-attribute

l10n_context: str

singular instance-attribute

singular: str

plural class-attribute instance-attribute

plural: str = ''

flags class-attribute instance-attribute

flags: frozenset[str] = frozenset()

translator_comments class-attribute instance-attribute

translator_comments: str = ''

fields

fields() -> list[str]

Return the replacement fields this template requires.

Raises:

Type Description
NotImplementedError

Replacement field discovery for %-formatting is not implemented.

maybe_without_filename

maybe_without_filename() -> Self

Return a new translatable string without the “filename” field.

Only acts upon translatable strings containing the exact contents ": {filename!r}". The specified part will be removed. This is correct usage in English for messages like "Cannot open file: {error}: {filename!r}.", but not necessarily in other languages.

rewrapped

rewrapped() -> Self

Return a rewrapped version of self.

Normalizes all parts assumed to contain English prose.

with_comments

with_comments(comments: str) -> Self

Add or replace the string’s translator comments.

The comments are assumed to contain English prose, and will be normalized.

Returns:

Type Description
Self

A new TranslatableString with the specified comments.

validate_flags

validate_flags(*extra_flags: str) -> Self

Add all flags, then validate them against the string.

Returns:

Type Description
Self

A new TranslatableString with the extra flags added, and all flags validated.

Raises:

Type Description
ValueError

The flags failed to validate. See the exact error message for details.

Examples:

>>> TranslatableString('', 'all OK').validate_flags()
...
TranslatableString(l10n_context='', singular='all OK', plural='',
                   flags=frozenset(), translator_comments='')
>>> TranslatableString('', '20% OK').validate_flags(
...     'no-python-format'
... )
...
TranslatableString(l10n_context='', singular='20% OK', plural='',
                   flags=frozenset({'no-python-format'}),
                   translator_comments='')
>>> TranslatableString('', '%d items').validate_flags()
...
Traceback (most recent call last):
    ...
ValueError: Missing flag for how to deal with percent character ...
>>> TranslatableString('', '{braces}').validate_flags()
...
Traceback (most recent call last):
    ...
ValueError: Missing flag for how to deal with brace character ...
>>> TranslatableString('', 'no braces').validate_flags(
...     'python-brace-format'
... )
...
Traceback (most recent call last):
    ...
ValueError: Missing format string parameters ...

TranslatedString

TranslatedString(
    template: str | TranslatableString | MsgTemplate,
    args_dict: Mapping[str, Any] = MappingProxyType({}),
    /,
    **kwargs: Any,
)

A string object that stringifies to its translation.

The translation and replacement value rendering is only performed when this string object is actually stringified.

Parameters:

Name Type Description Default
template str | TranslatableString | MsgTemplate

A template string, suitable for str.format. If a string, use it directly. If a TranslatableString, or a known enum value whose value is a TranslatableString, then use that string’s “singular” entry.

required
args_dict Mapping[str, Any]

Keyword arguments to be passed to str.format.

MappingProxyType({})
kwargs Any

More keyword arguments to be passed to str.format.

{}

__bool__

__bool__() -> bool

Return true if the rendered string is truthy.

__eq__

__eq__(other: object) -> bool

Return true if the rendered string is equal to other.

__hash__

__hash__() -> int

Return the hash of the rendered string.

__str__

__str__() -> str

Return the rendered translation of this string.

First, look up the translation of the string’s template. Then fill in the replacement fields. Cache the result for future calls.

maybe_without_filename

maybe_without_filename() -> Self

Return a new string without the “filename” field.

Only acts upon translated strings containing the exact contents ": {filename!r}". The specified part will be removed. This acts upon the string before translation, i.e., the string without the filename will be used as a translation base.

TranslatableStringConstructor

Bases: Protocol

Construct a TranslatableString.

__call__

__call__(
    context: str,
    single: str,
    /,
    flags: Iterable[str] = (),
    plural: str = "",
    comments: str = "",
) -> TranslatableString

Return a TranslatableString from these parts.

Usually some form of validation or normalization is performed first on these parts.

The main implementation of this is in translatable.

Label

Bases: Enum

Labels for the derivepassphrase command-line.

Includes help text (long-form and short-form), help metavar names, diagnostic labels and interactive prompts.

DEPRECATION_WARNING_LABEL class-attribute instance-attribute

DEPRECATION_WARNING_LABEL = commented(
    'This is a short label that will be prepended to a warning message, e.g., "Deprecation warning: A subcommand will be required in v1.0."'
)("Label :: Diagnostics :: Marker", "Deprecation warning")

WARNING_LABEL class-attribute instance-attribute

WARNING_LABEL = commented(
    'This is a short label that will be prepended to a warning message, e.g., "Warning: An empty service name is not supported by vault(1)."'
)("Label :: Diagnostics :: Marker", "Warning")

CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL class-attribute instance-attribute

CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL = commented(
    'This is one of two values of the settings_type metavar used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry.  It is only used there.  The full sentence then reads: "Cannot update the global settings without any given settings."'
)(
    "Label :: Error message :: Metavar", "global settings"
)

CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE class-attribute instance-attribute

CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE = commented(
    'This is one of two values of the settings_type metavar used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry.  It is only used there.  The full sentence then reads: "Cannot update the service-specific settings without any given settings."'
)(
    "Label :: Error message :: Metavar",
    "service-specific settings",
)

CONFIGURATION_EPILOG class-attribute instance-attribute

CONFIGURATION_EPILOG = commented("")(
    "Label :: Help text :: Explanation",
    "Use $VISUAL or $EDITOR to configure the spawned editor.",
)

DERIVEPASSPHRASE_02 class-attribute instance-attribute

DERIVEPASSPHRASE_02 = commented("")(
    "Label :: Help text :: Explanation",
    'The currently implemented subcommands are "vault" (for the scheme used by vault) and "export" (for exporting foreign configuration data).  See the respective `--help` output for instructions.  If no subcommand is given, we default to "vault".',
)

DERIVEPASSPHRASE_03 class-attribute instance-attribute

DERIVEPASSPHRASE_03 = commented("")(
    "Label :: Help text :: Explanation",
    'Deprecation notice: Defaulting to "vault" is deprecated.  Starting in v1.0, the subcommand must be specified explicitly.',
)

DERIVEPASSPHRASE_EPILOG_01 class-attribute instance-attribute

DERIVEPASSPHRASE_EPILOG_01 = commented("")(
    "Label :: Help text :: Explanation",
    "Configuration is stored in a directory according to the `DERIVEPASSPHRASE_PATH` variable, which defaults to `~/.derivepassphrase` on UNIX-like systems and `C:\\Users\\<user>\\AppData\\Roaming\\Derivepassphrase` on Windows.",
)

DERIVEPASSPHRASE_EXPORT_02 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_02 = commented("")(
    "Label :: Help text :: Explanation",
    'The only available subcommand is "vault", which implements the vault-native configuration scheme.  If no subcommand is given, we default to "vault".',
)

DERIVEPASSPHRASE_EXPORT_03 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_03 = DERIVEPASSPHRASE_03

DERIVEPASSPHRASE_EXPORT_VAULT_02 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_VAULT_02 = commented(
    "The metavar is Label.EXPORT_VAULT_METAVAR_PATH."
)(
    "Label :: Help text :: Explanation",
    'Depending on the configuration format, {path_metavar} may either be a file or a directory.  We support the vault "v0.2", "v0.3" and "storeroom" formats.',
    flags="python-brace-format",
)

DERIVEPASSPHRASE_EXPORT_VAULT_03 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_VAULT_03 = commented(
    "The metavar is Label.EXPORT_VAULT_METAVAR_PATH."
)(
    "Label :: Help text :: Explanation",
    "If {path_metavar} is explicitly given as `VAULT_PATH`, then use the `VAULT_PATH` environment variable to determine the correct path.  (Use `./VAULT_PATH` or similar to indicate a file/directory actually named `VAULT_PATH`.)",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_02 class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_02 = commented(
    "The metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Label :: Help text :: Explanation",
    "If operating on global settings, or importing/exporting settings, then {service_metavar} must be omitted.  Otherwise it is required.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_EPILOG_01 class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_EPILOG_01 = commented("")(
    "Label :: Help text :: Explanation",
    "WARNING: There is NO WAY to retrieve the generated passphrases if the master passphrase, the SSH key, or the exact passphrase settings are lost, short of trying out all possible combinations.  You are STRONGLY advised to keep independent backups of the settings and the SSH key, if any.",
)

DERIVEPASSPHRASE_VAULT_EPILOG_02 class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_EPILOG_02 = commented("")(
    "Label :: Help text :: Explanation",
    "The configuration is NOT encrypted, and you are STRONGLY discouraged from using a stored passphrase.",
)

DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT = commented(
    'This instruction text is shown above the user\'s old stored notes for this service, if any, if the recommended "modern" editor interface is used.  The next line is the cut marking defined in Label.DERIVEPASSPHRASE_VAULT_NOTES_MARKER.'
)(
    "Label :: Help text :: Explanation",
    "\x08\n# Enter notes below the line with the cut mark (ASCII scissors and\n# dashes).  Lines above the cut mark (such as this one) will be ignored.\n#\n# If you wish to clear the notes, leave everything beyond the cut mark\n# blank.  However, if you leave the *entire* file blank, also removing\n# the cut mark, then the edit is aborted, and the old notes contents are\n# retained.\n#\n",
)

DERIVEPASSPHRASE_VAULT_NOTES_LEGACY_INSTRUCTION_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_NOTES_LEGACY_INSTRUCTION_TEXT = commented(
    'This instruction text is shown if the vault(1)-compatible "legacy" editor interface is used and no previous notes exist.  The interface does not support commentary in the notes, so we fill this with obvious placeholder text instead.  (Please replace this with what *your* language/culture would obviously recognize as placeholder text.)'
)(
    "Label :: Help text :: Explanation", "INSERT NOTES HERE"
)

PASSPHRASE_GENERATION_EPILOG class-attribute instance-attribute

PASSPHRASE_GENERATION_EPILOG = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: Explanation",
    "Use {metavar}=0 to exclude a character type from the output.",
    flags="python-brace-format",
)

STORAGE_MANAGEMENT_EPILOG class-attribute instance-attribute

STORAGE_MANAGEMENT_EPILOG = commented(
    "The metavar is Label.STORAGE_MANAGEMENT_METAVAR_PATH."
)(
    "Label :: Help text :: Explanation",
    'Using "-" as {metavar} for standard input/standard output is supported.',
    flags="python-brace-format",
)

DEPRECATED_COMMAND_LABEL class-attribute instance-attribute

DEPRECATED_COMMAND_LABEL = commented(
    "We use this format string to indicate, at the beginning of a command's help text, that this command is deprecated."
)(
    "Label :: Help text :: Marker",
    "(Deprecated) {text}",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_NOTES_MARKER class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_NOTES_MARKER = commented(
    "The marker for separating the text from Label.DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT from the user's input (below the marker).  The first line starting with this label marks the separation point."
)(
    "Label :: Help text :: Marker",
    "# - - - - - >8 - - - - - >8 - - - - - >8 - - - - - >8 - - - - -",
)

EXPORT_VAULT_FORMAT_METAVAR_FMT class-attribute instance-attribute

EXPORT_VAULT_FORMAT_METAVAR_FMT = commented(
    'This text is used as {metavar} in Label.EXPORT_VAULT_FORMAT_HELP_TEXT, yielding e.g. "Try the following storage format FMT."'
)("Label :: Help text :: Metavar :: export vault", "FMT")

EXPORT_VAULT_KEY_METAVAR_K class-attribute instance-attribute

EXPORT_VAULT_KEY_METAVAR_K = commented(
    'This text is used as {metavar} in Label.EXPORT_VAULT_KEY_HELP_TEXT, yielding e.g. "Use K as the storage master key."'
)("Label :: Help text :: Metavar :: export vault", "K")

EXPORT_VAULT_METAVAR_PATH class-attribute instance-attribute

EXPORT_VAULT_METAVAR_PATH = commented(
    'Used as "path_metavar" in Label.DERIVEPASSPHRASE_EXPORT_VAULT_02 and others, yielding e.g. "Depending on the configuration format, PATH may either be a file or a directory."'
)("Label :: Help text :: Metavar :: export vault", "PATH")

PASSPHRASE_GENERATION_METAVAR_NUMBER class-attribute instance-attribute

PASSPHRASE_GENERATION_METAVAR_NUMBER = commented(
    'This metavar is used in Label.PASSPHRASE_GENERATION_EPILOG, Label.DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT and others, yielding e.g. "Ensure a passphrase length of NUMBER characters.".  '
)("Label :: Help text :: Metavar :: vault", "NUMBER")

STORAGE_MANAGEMENT_METAVAR_PATH class-attribute instance-attribute

STORAGE_MANAGEMENT_METAVAR_PATH = commented(
    'This metavar is used in Label.STORAGE_MANAGEMENT_EPILOG, Label.DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT and others, yielding e.g. "Ensure a passphrase length of NUMBER characters.".  '
)("Label :: Help text :: Metavar :: vault", "PATH")

VAULT_METAVAR_SERVICE class-attribute instance-attribute

VAULT_METAVAR_SERVICE = commented(
    'This metavar is used as "service_metavar" in multiple help texts, such as Label.DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT, Label.DERIVEPASSPHRASE_VAULT_02, ErrMsgTemplate.SERVICE_REQUIRED, etc.  Sample texts are "Deriving a passphrase requires a SERVICE.", "save the given settings for SERVICE, or global" and "If operating on global settings, or importing/exporting settings, then SERVICE must be omitted."'
)("Label :: Help text :: Metavar :: vault", "SERVICE")

DEBUG_OPTION_HELP_TEXT class-attribute instance-attribute

DEBUG_OPTION_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Also emit debug information.  Implies --verbose.",
)

DERIVEPASSPHRASE_01 class-attribute instance-attribute

DERIVEPASSPHRASE_01 = commented(
    "This is the first paragraph of the command help text, but it also appears (in truncated form, if necessary) as one-line help text for this command.  The translation should thus be as meaningful as possible even if truncated."
)(
    "Label :: Help text :: One-line description",
    "Derive a strong passphrase, deterministically, from a master secret.",
)

DERIVEPASSPHRASE_EXPORT_01 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_01 = commented(
    "This is the first paragraph of the command help text, but it also appears (in truncated form, if necessary) as one-line help text for this command.  The translation should thus be as meaningful as possible even if truncated."
)(
    "Label :: Help text :: One-line description",
    "Export a foreign configuration to standard output.",
)

DERIVEPASSPHRASE_EXPORT_VAULT_01 class-attribute instance-attribute

DERIVEPASSPHRASE_EXPORT_VAULT_01 = commented(
    "This is the first paragraph of the command help text, but it also appears (in truncated form, if necessary) as one-line help text for this command.  The translation should thus be as meaningful as possible even if truncated."
)(
    "Label :: Help text :: One-line description",
    "Export a vault-native configuration to standard output.",
)

DERIVEPASSPHRASE_VAULT_01 class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_01 = commented(
    "This is the first paragraph of the command help text, but it also appears (in truncated form, if necessary) as one-line help text for this command.  The translation should thus be as meaningful as possible even if truncated."
)(
    "Label :: Help text :: One-line description",
    "Derive a passphrase using the vault derivation scheme.",
)

DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT = commented(
    "The metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Label :: Help text :: One-line description",
    "Save the given settings for {service_metavar}, or global.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_DASH_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_DASH_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    'Ensure at least {metavar} "-" or "_" characters.',
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_DELETE_ALL_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_DELETE_ALL_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Delete all settings.",
)

DERIVEPASSPHRASE_VAULT_DELETE_GLOBALS_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_DELETE_GLOBALS_HELP_TEXT = commented(
    ""
)(
    "Label :: Help text :: One-line description",
    "Delete the global settings.",
)

DERIVEPASSPHRASE_VAULT_DELETE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_DELETE_HELP_TEXT = commented(
    "The metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Label :: Help text :: One-line description",
    "Delete the settings for {service_metavar}.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_EDITOR_INTERFACE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_EDITOR_INTERFACE_HELP_TEXT = commented(
    'The corresponding option is displayed as "--modern-editor-interface / --vault-legacy-editor-interface", so you may want to hint that the default (legacy) is the second of those options.  Though the vault(1) legacy editor interface clearly has deficiencies and (in my opinion) should only be used for compatibility purposes, the one-line help text should try not to sound too judgmental, if possible.'
)(
    "Label :: Help text :: One-line description",
    "Edit notes using the modern editor interface or the vault-like legacy one (default).",
)

DERIVEPASSPHRASE_VAULT_EXPORT_AS_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_EXPORT_AS_HELP_TEXT = commented(
    'The corresponding option is displayed as "--export-as=json|sh", so json refers to the JSON format (default) and sh refers to the POSIX sh format.  Please ensure that it is clear what the "json" and "sh" refer to in your translation... even if you cannot use texutal correspondence like the English text does.'
)(
    "Label :: Help text :: One-line description",
    "When exporting, export as JSON (default) or as POSIX sh.",
)

DERIVEPASSPHRASE_VAULT_EXPORT_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_EXPORT_HELP_TEXT = commented(
    "The metavar is Label.STORAGE_MANAGEMENT_METAVAR_PATH."
)(
    "Label :: Help text :: One-line description",
    "Export all saved settings to {metavar}.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT = commented(
    "The metavar is Label.STORAGE_MANAGEMENT_METAVAR_PATH."
)(
    "Label :: Help text :: One-line description",
    "Import saved settings from {metavar}.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_KEY_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_KEY_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Select a suitable SSH key from the SSH agent.",
)

DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure a passphrase length of {metavar} characters.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_LOWER_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_LOWER_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure at least {metavar} lowercase characters.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_NOTES_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_NOTES_HELP_TEXT = commented(
    "The metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Label :: Help text :: One-line description",
    "With --config and {service_metavar}, spawn an editor to edit notes.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_NUMBER_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_NUMBER_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure at least {metavar} digits.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_OVERWRITE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_OVERWRITE_HELP_TEXT = commented(
    'The corresponding option is displayed as "--overwrite-existing / --merge-existing", so you may want to hint that the default (merge) is the second of those options.'
)(
    "Label :: Help text :: One-line description",
    "Overwrite or merge (default) the existing configuration.",
)

DERIVEPASSPHRASE_VAULT_PHRASE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_PHRASE_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Prompt for a master passphrase.",
)

DERIVEPASSPHRASE_VAULT_PRINT_NOTES_BEFORE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_PRINT_NOTES_BEFORE_HELP_TEXT = commented(
    'The corresponding option is displayed as "--print-notes-before / --print-notes-after", so you may want to hint that the default (after) is the second of those options.'
)(
    "Label :: Help text :: One-line description",
    "Print the notes for {service_metavar} (if any) before or after (default) the derived passphrase.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_REPEAT_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_REPEAT_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Restrict runs of identical characters to at most {metavar} characters.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_SPACE_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_SPACE_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure at least {metavar} spaces.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_SYMBOL_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_SYMBOL_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure at least {metavar} symbol characters.",
    flags="python-brace-format",
)

DERIVEPASSPHRASE_VAULT_UNSET_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_UNSET_HELP_TEXT = commented(
    'The corresponding option is displayed as "--unset=phrase|key|...|symbol", so the "given setting" is referring to "phrase", "key", "lower", ..., or "symbol", respectively.  "with --config" here means that the user must also specify "--config" for this option to have any effect.'
)(
    "Label :: Help text :: One-line description",
    "With --config, also unset the given setting.  May be specified multiple times.",
)

DERIVEPASSPHRASE_VAULT_UPPER_HELP_TEXT class-attribute instance-attribute

DERIVEPASSPHRASE_VAULT_UPPER_HELP_TEXT = commented(
    "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER."
)(
    "Label :: Help text :: One-line description",
    "Ensure at least {metavar} uppercase characters.",
    flags="python-brace-format",
)

EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT class-attribute instance-attribute

EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT = commented(
    'See EXPORT_VAULT_FORMAT_HELP_TEXT.  The format names/labels "v0.3", "v0.2" and "storeroom" should not be translated.'
)(
    "Label :: Help text :: One-line description",
    "Default: v0.3, v0.2, storeroom.",
)

EXPORT_VAULT_FORMAT_HELP_TEXT class-attribute instance-attribute

EXPORT_VAULT_FORMAT_HELP_TEXT = commented(
    "The defaults_hint is Label.EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT, the metavar is Label.EXPORT_VAULT_FORMAT_METAVAR_FMT."
)(
    "Label :: Help text :: One-line description",
    "Try the following storage format {metavar}.  If specified multiple times, the formats will be tried in order.  {defaults_hint}",
    flags="python-brace-format",
)

EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT class-attribute instance-attribute

EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT = commented(
    "See EXPORT_VAULT_KEY_HELP_TEXT."
)(
    "Label :: Help text :: One-line description",
    "Default: check the VAULT_KEY, LOGNAME, USER, or USERNAME environment variables.",
)

EXPORT_VAULT_KEY_HELP_TEXT class-attribute instance-attribute

EXPORT_VAULT_KEY_HELP_TEXT = commented(
    "The defaults_hint is Label.EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT, the metavar is Label.EXPORT_VAULT_KEY_METAVAR_K."
)(
    "Label :: Help text :: One-line description",
    "Use {metavar} as the storage master key.  {defaults_hint}",
    flags="python-brace-format",
)

HELP_OPTION_HELP_TEXT class-attribute instance-attribute

HELP_OPTION_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Show this help text, then exit.",
)

QUIET_OPTION_HELP_TEXT class-attribute instance-attribute

QUIET_OPTION_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Suppress even warnings; emit only errors.",
)

VERBOSE_OPTION_HELP_TEXT class-attribute instance-attribute

VERBOSE_OPTION_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Emit extra/progress information to standard error.",
)

VERSION_OPTION_HELP_TEXT class-attribute instance-attribute

VERSION_OPTION_HELP_TEXT = commented("")(
    "Label :: Help text :: One-line description",
    "Show version and feature information, then exit.",
)

COMMANDS_LABEL class-attribute instance-attribute

COMMANDS_LABEL = commented("")(
    "Label :: Help text :: Option group name", "Commands"
)

COMPATIBILITY_OPTION_LABEL class-attribute instance-attribute

COMPATIBILITY_OPTION_LABEL = commented("")(
    "Label :: Help text :: Option group name",
    "Compatibility and extension options",
)

CONFIGURATION_LABEL class-attribute instance-attribute

CONFIGURATION_LABEL = commented("")(
    "Label :: Help text :: Option group name",
    "Configuration",
)

LOGGING_LABEL class-attribute instance-attribute

LOGGING_LABEL = commented("")(
    "Label :: Help text :: Option group name", "Logging"
)

OPTIONS_LABEL class-attribute instance-attribute

OPTIONS_LABEL = commented("")(
    "Label :: Help text :: Option group name", "Options"
)

OTHER_OPTIONS_LABEL class-attribute instance-attribute

OTHER_OPTIONS_LABEL = commented("")(
    "Label :: Help text :: Option group name",
    "Other options",
)

PASSPHRASE_GENERATION_LABEL class-attribute instance-attribute

PASSPHRASE_GENERATION_LABEL = commented("")(
    "Label :: Help text :: Option group name",
    "Passphrase generation",
)

STORAGE_MANAGEMENT_LABEL class-attribute instance-attribute

STORAGE_MANAGEMENT_LABEL = commented("")(
    "Label :: Help text :: Option group name",
    "Storage management",
)

VERSION_INFO_MAJOR_LIBRARY_TEXT class-attribute instance-attribute

VERSION_INFO_MAJOR_LIBRARY_TEXT = commented(
    'This message reports on the version of a major library currently in use, such as "cryptography".'
)(
    "Label :: Info Message",
    "Using {dependency_name_and_version}",
    flags="python-brace-format",
)

ENABLED_PEP508_EXTRAS class-attribute instance-attribute

ENABLED_PEP508_EXTRAS = commented(
    "This is part of the version output, emitting lists of enabled PEP 508 extras.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "PEP 508 extras:",
)

SUPPORTED_DERIVATION_SCHEMES class-attribute instance-attribute

SUPPORTED_DERIVATION_SCHEMES = commented(
    "This is part of the version output, emitting lists of supported derivation schemes.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Supported derivation schemes:",
)

SUPPORTED_FEATURES class-attribute instance-attribute

SUPPORTED_FEATURES = commented(
    "This is part of the version output, emitting lists of supported features for this subcommand.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Supported features:",
)

SUPPORTED_FOREIGN_CONFIGURATION_FORMATS class-attribute instance-attribute

SUPPORTED_FOREIGN_CONFIGURATION_FORMATS = commented(
    "This is part of the version output, emitting lists of supported foreign configuration formats.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Supported foreign configuration formats:",
)

SUPPORTED_SUBCOMMANDS class-attribute instance-attribute

SUPPORTED_SUBCOMMANDS = commented(
    "This is part of the version output, emitting lists of supported subcommands.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Supported subcommands:",
)

UNAVAILABLE_DERIVATION_SCHEMES class-attribute instance-attribute

UNAVAILABLE_DERIVATION_SCHEMES = commented(
    "This is part of the version output, emitting lists of known, unavailable derivation schemes.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Known derivation schemes:",
)

UNAVAILABLE_FEATURES class-attribute instance-attribute

UNAVAILABLE_FEATURES = commented(
    "This is part of the version output, emitting lists of known, unavailable features for this subcommand.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Known features:",
)

UNAVAILABLE_FOREIGN_CONFIGURATION_FORMATS class-attribute instance-attribute

UNAVAILABLE_FOREIGN_CONFIGURATION_FORMATS = commented(
    "This is part of the version output, emitting lists of known, unavailable foreign configuration formats.  A comma-separated English list of items follows, with standard English punctuation."
)(
    "Label :: Info Message:: Table row header",
    "Known foreign configuration formats:",
)

CONFIRM_THIS_CHOICE_PROMPT_TEXT class-attribute instance-attribute

CONFIRM_THIS_CHOICE_PROMPT_TEXT = commented(
    'There is no support for "yes" or "no" in other languages than English, so it is advised that your translation makes it clear that only the strings "y", "yes", "n" or "no" are supported, even if the prompt becomes a bit longer.'
)(
    "Label :: Interactive prompt",
    "Confirm this choice? (y/N)",
)

SUITABLE_SSH_KEYS_LABEL class-attribute instance-attribute

SUITABLE_SSH_KEYS_LABEL = commented(
    "This label is the heading of the list of suitable SSH keys."
)("Label :: Interactive prompt", "Suitable SSH keys:")

YOUR_SELECTION_PROMPT_TEXT class-attribute instance-attribute

YOUR_SELECTION_PROMPT_TEXT = commented("")(
    "Label :: Interactive prompt",
    "Your selection? (1-{n}, leave empty to abort)",
    flags="python-brace-format",
)

DebugMsgTemplate

Bases: Enum

Debug messages for the derivepassphrase command-line.

BUCKET_ITEM_FOUND class-attribute instance-attribute

BUCKET_ITEM_FOUND = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories.  The system stores entries in different "buckets" of a hash table.  Here, we report on a single item (path and value) we discovered after decrypting the whole bucket.  (We ensure the path and value are printable as-is.)'
)(
    "Debug message",
    "Found bucket item: {path} -> {value}",
    flags="python-brace-format",
)

DECRYPT_BUCKET_ITEM_INFO class-attribute instance-attribute

DECRYPT_BUCKET_ITEM_INFO = commented(
    '"AES256-CBC" and "PKCS#7" are, in essence, names of formats, and should not be translated.  "IV" means "initialization vector", and is specifically a cryptographic term, as are "plaintext" and "ciphertext".'
)(
    "Debug message",
    "Decrypt bucket item contents:\n\n\x08\n  Encryption key (master key): {enc_key}\n  Encryption cipher: AES256-CBC with PKCS#7 padding\n  Encryption IV: {iv}\n  Encrypted ciphertext: {ciphertext}\n  Plaintext: {plaintext}\n",
    flags="python-brace-format",
)

DECRYPT_BUCKET_ITEM_KEY_INFO class-attribute instance-attribute

DECRYPT_BUCKET_ITEM_KEY_INFO = commented("")(
    "Debug message",
    "Decrypt bucket item:\n\n\x08\n  Plaintext: {plaintext}\n  Encryption key (master key): {enc_key}\n  Signing key (master key): {sign_key}\n",
    flags="python-brace-format",
)

DECRYPT_BUCKET_ITEM_MAC_INFO class-attribute instance-attribute

DECRYPT_BUCKET_ITEM_MAC_INFO = commented(
    'The MAC stands for "message authentication code", which guarantees the authenticity of the message to anyone who holds the corresponding key, similar to a digital signature.  The acronym "MAC" is assumed to be well-known to the English target audience, or at least discoverable by them; they *are* asking for debug output, after all.  Please use your judgement as to whether to translate this term or not, expanded or not.'
)(
    "Debug message",
    "Decrypt bucket item contents:\n\n\x08\n  MAC key: {sign_key}\n  Authenticated content: {ciphertext}\n  Claimed MAC value: {claimed_mac}\n  Computed MAC value: {actual_mac}\n",
    flags="python-brace-format",
)

DECRYPT_BUCKET_ITEM_SESSION_KEYS_INFO class-attribute instance-attribute

DECRYPT_BUCKET_ITEM_SESSION_KEYS_INFO = commented(
    '"AES256-CBC" and "PKCS#7" are, in essence, names of formats, and should not be translated.  "IV" means "initialization vector", and is specifically a cryptographic term, as are "plaintext" and "ciphertext".'
)(
    "Debug message",
    "Decrypt bucket item session keys:\n\n\x08\n  Encryption key (master key): {enc_key}\n  Encryption cipher: AES256-CBC with PKCS#7 padding\n  Encryption IV: {iv}\n  Encrypted ciphertext: {ciphertext}\n  Plaintext: {plaintext}\n  Parsed plaintext: {code}\n",
    flags="python-brace-format",
)

DECRYPT_BUCKET_ITEM_SESSION_KEYS_MAC_INFO class-attribute instance-attribute

DECRYPT_BUCKET_ITEM_SESSION_KEYS_MAC_INFO = commented(
    'The MAC stands for "message authentication code", which guarantees the authenticity of the message to anyone who holds the corresponding key, similar to a digital signature.  The acronym "MAC" is assumed to be well-known to the English target audience, or at least discoverable by them; they *are* asking for debug output, after all.  Please use your judgement as to whether to translate this term or not, expanded or not.'
)(
    "Debug message",
    "Decrypt bucket item session keys:\n\n\x08\n  MAC key (master key): {sign_key}\n  Authenticated content: {ciphertext}\n  Claimed MAC value: {claimed_mac}\n  Computed MAC value: {actual_mac}\n",
    flags="python-brace-format",
)

DERIVED_MASTER_KEYS_KEYS class-attribute instance-attribute

DERIVED_MASTER_KEYS_KEYS = commented("")(
    "Debug message",
    "Derived master keys' keys:\n\n\x08\n  Encryption key: {enc_key}\n  Signing key: {sign_key}\n  Password: {pw_bytes}\n  Function call: pbkdf2(algorithm={algorithm!r}, length={length!r}, salt={salt!r}, iterations={iterations!r})\n",
    flags="python-brace-format",
)

DIRECTORY_CONTENTS_CHECK_OK class-attribute instance-attribute

DIRECTORY_CONTENTS_CHECK_OK = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories, while "assembling" the items stored in the configuration according to the item\'s "path".  Each "directory" in the path contains a list of children it claims to contain, and this list must be matched against the actual discovered items.  Now, at the end, we actually confirm the claim.  (We would have already thrown an error here otherwise.)'
)(
    "Debug message",
    "Directory contents check OK: {path} -> {contents}",
    flags="python-brace-format",
)

MASTER_KEYS_DATA_MAC_INFO class-attribute instance-attribute

MASTER_KEYS_DATA_MAC_INFO = commented(
    'The MAC stands for "message authentication code", which guarantees the authenticity of the message to anyone who holds the corresponding key, similar to a digital signature.  The acronym "MAC" is assumed to be well-known to the English target audience, or at least discoverable by them; they *are* asking for debug output, after all.  Please use your judgement as to whether to translate this term or not, expanded or not.'
)(
    "Debug message",
    "Master keys data:\n\n\x08\n  MAC key: {sign_key}\n  Authenticated content: {ciphertext}\n  Claimed MAC value: {claimed_mac}\n  Computed MAC value: {actual_mac}\n",
    flags="python-brace-format",
)

POSTPONING_DIRECTORY_CONTENTS_CHECK class-attribute instance-attribute

POSTPONING_DIRECTORY_CONTENTS_CHECK = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories, while "assembling" the items stored in the configuration according to the item\'s "path".  Each "directory" in the path contains a list of children it claims to contain, and this list must be matched against the actual discovered items.  When emitting this message, we merely indicate that we saved the "claimed" list for this directory for later.'
)(
    "Debug message",
    "Postponing directory contents check: {path} -> {contents}",
    flags="python-brace-format",
)

SETTING_CONFIG_STRUCTURE_CONTENTS class-attribute instance-attribute

SETTING_CONFIG_STRUCTURE_CONTENTS = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories, while "assembling" the items stored in the configuration according to the item\'s "path".  We confirm that we set the entry at the given path to the given value.'
)(
    "Debug message",
    "Setting contents: {path} -> {value}",
    flags="python-brace-format",
)

SETTING_CONFIG_STRUCTURE_CONTENTS_EMPTY_DIRECTORY class-attribute instance-attribute

SETTING_CONFIG_STRUCTURE_CONTENTS_EMPTY_DIRECTORY = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories, while "assembling" the items stored in the configuration according to the item\'s "path".  We confirm that we set up a currently empty directory at the given path.'
)(
    "Debug message",
    "Setting contents (empty directory): {path}",
    flags="python-brace-format",
)

VAULT_NATIVE_CHECKING_MAC_DETAILS class-attribute instance-attribute

VAULT_NATIVE_CHECKING_MAC_DETAILS = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  It is preceded by the info message VAULT_NATIVE_PARSING_IV_PAYLOAD_MAC; see the commentary there concerning the terms and thoughts on translating them.'
)(
    "Debug message",
    "MAC details:\n\n\x08\n  MAC input: {mac_input}\n  Expected MAC: {mac}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_EVP_BYTESTOKEY_INIT class-attribute instance-attribute

VAULT_NATIVE_EVP_BYTESTOKEY_INIT = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories: in v0.2, the non-standard and deprecated "EVP_bytestokey" function from OpenSSL must be reimplemented from scratch.  The terms "salt" and "IV" (initialization vector) are cryptographic terms.'
)(
    "Debug message",
    "evp_bytestokey_md5 (initialization):\n\n\x08\n  Input: {data}\n  Salt: {salt}\n  Key size: {key_size}\n  IV size: {iv_size}\n  Buffer length: {buffer_length}\n  Buffer: {buffer}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_EVP_BYTESTOKEY_RESULT class-attribute instance-attribute

VAULT_NATIVE_EVP_BYTESTOKEY_RESULT = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories: in v0.2, the non-standard and deprecated "EVP_bytestokey" function from OpenSSL must be reimplemented from scratch.  The terms "salt" and "IV" (initialization vector) are cryptographic terms.This function reports on the final results.'
)(
    "Debug message",
    "evp_bytestokey_md5 (result):\n\n\x08\n  Encryption key: {enc_key}\n  IV: {iv}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_EVP_BYTESTOKEY_ROUND class-attribute instance-attribute

VAULT_NATIVE_EVP_BYTESTOKEY_ROUND = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories: in v0.2, the non-standard and deprecated "EVP_bytestokey" function from OpenSSL must be reimplemented from scratch.  The terms "salt" and "IV" (initialization vector) are cryptographic terms.This function reports on the updated buffer length and contents after executing one round of hashing.'
)(
    "Debug message",
    "evp_bytestokey_md5 (round update):\n\n\x08\n  Buffer length: {buffer_length}\n  Buffer: {buffer}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_PADDED_PLAINTEXT class-attribute instance-attribute

VAULT_NATIVE_PADDED_PLAINTEXT = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  "padding" and "plaintext" are cryptographic terms.'
)(
    "Debug message",
    "Padded plaintext: {contents}",
    flags="python-brace-format",
)

VAULT_NATIVE_PARSE_BUFFER class-attribute instance-attribute

VAULT_NATIVE_PARSE_BUFFER = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  It is preceded by the info message VAULT_NATIVE_PARSING_IV_PAYLOAD_MAC; see the commentary there concerning the terms and thoughts on translating them.'
)(
    "Debug message",
    "Buffer: {contents}\n\n\x08\n  IV: {iv}\n  Payload (ciphertext): {payload}\n  MAC: {mac}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_PBKDF2_CALL class-attribute instance-attribute

VAULT_NATIVE_PBKDF2_CALL = commented("")(
    "Debug message",
    "Master key derivation:\n\n\x08\n  PBKDF2 call: PBKDF2-HMAC(password={password!r}, salt={salt!r}, iterations={iterations!r}, key_size={key_size!r}, algorithm={algorithm!r})\n  Result (binary): {raw_result}\n  Result (hex key): {result_key!r}\n",
    flags="python-brace-format",
)

VAULT_NATIVE_PLAINTEXT class-attribute instance-attribute

VAULT_NATIVE_PLAINTEXT = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  "plaintext" is a cryptographic term.'
)(
    "Debug message",
    "Plaintext: {contents}",
    flags="python-brace-format",
)

VAULT_NATIVE_V02_PAYLOAD_MAC_POSTPROCESSING class-attribute instance-attribute

VAULT_NATIVE_V02_PAYLOAD_MAC_POSTPROCESSING = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  It is preceded by the info message VAULT_NATIVE_PARSING_IV_PAYLOAD_MAC and the debug message PARSING_NATIVE_PARSE_BUFFER; see the commentary there concerning the terms and thoughts on translating them.'
)(
    "Debug message",
    "Postprocessing buffer (v0.2):\n\n\x08\n  Payload: {payload} (decoded from base64)\n  MAC: {mac} (decoded from hex)\n",
    flags="python-brace-format",
)

InfoMsgTemplate

Bases: Enum

Info messages for the derivepassphrase command-line.

ASSEMBLING_CONFIG_STRUCTURE class-attribute instance-attribute

ASSEMBLING_CONFIG_STRUCTURE = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories.  The system stores entries in different "buckets" of a hash table.  After the respective items in the buckets have been decrypted, we then have a list of item paths plus contents to populate.  This must be done in a certain order (we don\'t yet have an existing directory tree to rely on, but rather must build it on-the-fly), hence the term "assembling".'
)("Info message", "Assembling config structure.")

CANNOT_LOAD_AS_VAULT_CONFIG class-attribute instance-attribute

CANNOT_LOAD_AS_VAULT_CONFIG = commented(
    '"fmt" is a string such as "v0.2" or "storeroom", indicating the format which we tried to load the vault configuration as.'
)(
    "Info message",
    "Cannot load {path!r} as a {fmt} vault configuration.",
    flags="python-brace-format",
)

CHECKING_CONFIG_STRUCTURE_CONSISTENCY class-attribute instance-attribute

CHECKING_CONFIG_STRUCTURE_CONSISTENCY = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories.  Having "assembled" the configuration items according to their claimed paths and contents, we then check if the assembled structure is internally consistent.'
)("Info message", "Checking config structure consistency.")

DECRYPTING_BUCKET class-attribute instance-attribute

DECRYPTING_BUCKET = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories.  The system stores entries in different "buckets" of a hash table.  We parse the directory bucket by bucket.  All buckets are numbered in hexadecimal, and typically there are 32 buckets, so 2-digit hex numbers.'
)(
    "Info message",
    "Decrypting bucket {bucket_number}.",
    flags="python-brace-format",
)

PARSING_MASTER_KEYS_DATA class-attribute instance-attribute

PARSING_MASTER_KEYS_DATA = commented(
    'This message is emitted by the vault configuration exporter for "storeroom"-type configuration directories.  `.keys` is a filename, from which data about the master keys for this configuration are loaded.'
)("Info message", "Parsing master keys data from `.keys`.")

PIP_INSTALL_EXTRA class-attribute instance-attribute

PIP_INSTALL_EXTRA = commented(
    'This message immediately follows an error message about a missing library that needs to be installed.  The Python Package Index (PyPI) supports declaring sets of optional dependencies as "extras", so users installing from PyPI can request reinstallation with a named "extra" being enabled.  This would then let the installer take care of the missing libraries automatically, hence this suggestion to PyPI users.'
)(
    "Info message",
    "For users installing from PyPI, see the {extra_name!r} extra.",
    flags="python-brace-format",
)

SUCCESSFULLY_MIGRATED class-attribute instance-attribute

SUCCESSFULLY_MIGRATED = commented(
    'This info message immediately follows the "Using deprecated v0.1-style ..." deprecation warning.'
)(
    "Info message",
    "Successfully migrated to {path!r}.",
    flags="python-brace-format",
)

VAULT_NATIVE_CHECKING_MAC class-attribute instance-attribute

VAULT_NATIVE_CHECKING_MAC = commented("")(
    "Info message", "Checking MAC."
)

VAULT_NATIVE_DECRYPTING_CONTENTS class-attribute instance-attribute

VAULT_NATIVE_DECRYPTING_CONTENTS = commented("")(
    "Info message", "Decrypting contents."
)

VAULT_NATIVE_DERIVING_KEYS class-attribute instance-attribute

VAULT_NATIVE_DERIVING_KEYS = commented("")(
    "Info message",
    "Deriving an encryption and signing key.",
)

VAULT_NATIVE_PARSING_IV_PAYLOAD_MAC class-attribute instance-attribute

VAULT_NATIVE_PARSING_IV_PAYLOAD_MAC = commented(
    'This message is emitted by the vault configuration exporter for "native"-type configuration directories.  "IV" means "initialization vector", and "MAC" means "message authentication code".  They are specifically cryptographic terms, as is "payload".  The acronyms "IV" and "MAC" are assumed to be well-known to the English target audience, or at least discoverable by them; they *are* asking for debug output, after all.  Please use your judgement as to whether to translate these terms or not, expanded or not.'
)(
    "Info message",
    "Parsing IV, payload and MAC from the file contents.",
)

WarnMsgTemplate

Bases: Enum

Warning messages for the derivepassphrase command-line.

EMPTY_SERVICE_NOT_SUPPORTED class-attribute instance-attribute

EMPTY_SERVICE_NOT_SUPPORTED = commented("")(
    "Warning message",
    "An empty {service_metavar} is not supported by vault(1).  For compatibility, this will be treated as if {service_metavar} was not supplied, i.e., it will error out, or operate on global settings.",
    flags="python-brace-format",
)

EMPTY_SERVICE_SETTINGS_INACCESSIBLE class-attribute instance-attribute

EMPTY_SERVICE_SETTINGS_INACCESSIBLE = commented("")(
    "Warning message",
    'An empty {service_metavar} is not supported by vault(1).  The empty-string service settings will be inaccessible and ineffective.  To ensure that vault(1) and {PROG_NAME} see the settings, move them into the "global" section.',
    flags="python-brace-format",
)

FAILED_TO_MIGRATE_CONFIG class-attribute instance-attribute

FAILED_TO_MIGRATE_CONFIG = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Warning message",
    "Failed to migrate to {path!r}: {error}: {filename!r}.",
    flags="python-brace-format",
)

GLOBAL_PASSPHRASE_INEFFECTIVE class-attribute instance-attribute

GLOBAL_PASSPHRASE_INEFFECTIVE = commented("")(
    "Warning message",
    "Setting a global passphrase is ineffective because a key is also set.",
)

PASSPHRASE_NOT_NORMALIZED class-attribute instance-attribute

PASSPHRASE_NOT_NORMALIZED = commented(
    'The key is a (vault) configuration key, in JSONPath syntax, typically "$.global" for the global passphrase or "$.services.service_name" or "$.services["service with spaces"]" for the services "service_name" and "service with spaces", respectively.  Alternatively, it may be the value of Label.SETTINGS_ORIGIN_INTERACTIVE if the passphrase was entered interactively.  The form is one of the four Unicode normalization forms: NFC, NFD, NFKC, NFKD.  The asterisks are not special.  Please feel free to substitute any other appropriate way to mark up emphasis of the word "displays".'
)(
    "Warning message",
    "The {key} passphrase is not {form}-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.",
    flags="python-brace-format",
)

SERVICE_NAME_INCOMPLETABLE class-attribute instance-attribute

SERVICE_NAME_INCOMPLETABLE = commented("")(
    "Warning message",
    "The service name {service!r} contains an ASCII control character, which is not supported by our shell completion code.  This service name will therefore not be available for completion on the command-line.  You may of course still type it in manually in whatever format your shell accepts, but we highly recommend choosing a different service name instead.",
    flags="python-brace-format",
)

SERVICE_PASSPHRASE_INEFFECTIVE class-attribute instance-attribute

SERVICE_PASSPHRASE_INEFFECTIVE = commented(
    "The key that is set need not necessarily be set at the service level; it may be a global key as well."
)(
    "Warning message",
    "Setting a service passphrase is ineffective because a key is also set: {service}.",
    flags="python-brace-format",
)

STEP_REMOVE_INEFFECTIVE_VALUE class-attribute instance-attribute

STEP_REMOVE_INEFFECTIVE_VALUE = commented("")(
    "Warning message",
    "Removing ineffective setting {path} = {old}.",
    flags="python-brace-format",
)

STEP_REPLACE_INVALID_VALUE class-attribute instance-attribute

STEP_REPLACE_INVALID_VALUE = commented("")(
    "Warning message",
    "Replacing invalid value {old} for key {path} with {new}.",
    flags="python-brace-format",
)

V01_STYLE_CONFIG class-attribute instance-attribute

V01_STYLE_CONFIG = commented("")(
    "Warning message :: Deprecation",
    "Using deprecated v0.1-style config file {old!r}, instead of v0.2-style {new!r}.  Support for v0.1-style config filenames will be removed in v1.0.",
    flags="python-brace-format",
)

V10_SUBCOMMAND_REQUIRED class-attribute instance-attribute

V10_SUBCOMMAND_REQUIRED = commented(
    'This deprecation warning may be issued at any level, i.e. we may actually be talking about subcommands, or sub-subcommands, or sub-sub-subcommands, etc., which is what the "here" is supposed to indicate.'
)(
    "Warning message :: Deprecation",
    'A subcommand will be required here in v1.0.  See --help for available subcommands.  Defaulting to subcommand "vault".',
)

ErrMsgTemplate

Bases: Enum

Error messages for the derivepassphrase command-line.

AGENT_REFUSED_LIST_KEYS class-attribute instance-attribute

AGENT_REFUSED_LIST_KEYS = commented(
    '"loaded keys" being keys loaded into the agent.'
)(
    "Error message",
    "The SSH agent failed to or refused to supply a list of loaded keys.",
)

AGENT_REFUSED_SIGNATURE class-attribute instance-attribute

AGENT_REFUSED_SIGNATURE = commented(
    "The message to be signed is the vault UUID, but there's no space to explain that here, so ideally the error message does not go into detail."
)(
    "Error message",
    "The SSH agent failed to or refused to issue a signature with the selected key, necessary for deriving a service passphrase.",
)

CANNOT_CONNECT_TO_AGENT class-attribute instance-attribute

CANNOT_CONNECT_TO_AGENT = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot connect to the SSH agent: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_DECODEIMPORT_VAULT_SETTINGS class-attribute instance-attribute

CANNOT_DECODEIMPORT_VAULT_SETTINGS = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot import vault settings: cannot decode JSON: {error}.",
    flags="python-brace-format",
)

CANNOT_EXPORT_VAULT_SETTINGS class-attribute instance-attribute

CANNOT_EXPORT_VAULT_SETTINGS = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot export vault settings: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_IMPORT_VAULT_SETTINGS class-attribute instance-attribute

CANNOT_IMPORT_VAULT_SETTINGS = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot import vault settings: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_LOAD_USER_CONFIG class-attribute instance-attribute

CANNOT_LOAD_USER_CONFIG = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot load user config: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_LOAD_VAULT_SETTINGS class-attribute instance-attribute

CANNOT_LOAD_VAULT_SETTINGS = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot load vault settings: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_PARSE_AS_VAULT_CONFIG class-attribute instance-attribute

CANNOT_PARSE_AS_VAULT_CONFIG = commented(
    'Unlike the "Cannot load {path!r} as a {fmt} vault configuration." message, *this* error message is emitted when we have tried loading the path in each of our supported formats, and failed.  The user will thus see the above "Cannot load ..." warning message potentially multiple times, and this error message at the very bottom.'
)(
    "Error message",
    "Cannot parse {path!r} as a valid vault-native configuration file/directory.",
    flags="python-brace-format",
)

CANNOT_PARSE_AS_VAULT_CONFIG_OSERROR class-attribute instance-attribute

CANNOT_PARSE_AS_VAULT_CONFIG_OSERROR = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot parse {path!r} as a valid vault-native configuration file/directory: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_STORE_VAULT_SETTINGS class-attribute instance-attribute

CANNOT_STORE_VAULT_SETTINGS = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "Cannot store vault settings: {error}: {filename!r}.",
    flags="python-brace-format",
)

CANNOT_UNDERSTAND_AGENT class-attribute instance-attribute

CANNOT_UNDERSTAND_AGENT = commented(
    "This error message is used whenever we cannot make any sense of a response from the SSH agent because the response is ill-formed (truncated, improperly encoded, etc.) or otherwise violates the communications protocol.  Well-formed responses that adhere to the protocol, even if they indicate that the requested operation failed, are handled with a different error message."
)(
    "Error message",
    "Cannot understand the SSH agent's response because it violates the communication protocol.",
)

CANNOT_UPDATE_SETTINGS_NO_SETTINGS class-attribute instance-attribute

CANNOT_UPDATE_SETTINGS_NO_SETTINGS = commented(
    'The settings_type metavar contains translations for either "global settings" or "service-specific settings"; see the CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL and CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE entries.  The first sentence will thus read either "Cannot update the global settings without any given settings." or "Cannot update the service-specific settings without any given settings.".  You may update this entry, and the two metavar entries, in any way you see fit that achieves the desired translations of the first sentence.'
)(
    "Error message",
    "Cannot update the {settings_type} without any given settings.  You must specify at least one of --lower, ..., --symbol, --notes, or --phrase or --key.",
    flags="python-brace-format",
)

INVALID_USER_CONFIG class-attribute instance-attribute

INVALID_USER_CONFIG = commented(
    '"error" is supplied by the operating system (errno/strerror).'
)(
    "Error message",
    "The user configuration file is invalid.  {error}: {filename!r}.",
    flags="python-brace-format",
)

INVALID_VAULT_CONFIG class-attribute instance-attribute

INVALID_VAULT_CONFIG = commented(
    "This error message is a reaction to a validator function saying *that* the configuration is not valid, but not *how* it is not valid.  The configuration file is principally parsable, however."
)(
    "Error message",
    "Invalid vault config: {config!r}.",
    flags="python-brace-format",
)

MISSING_MODULE class-attribute instance-attribute

MISSING_MODULE = commented("")(
    "Error message",
    "Cannot load the required Python module {module!r}.",
    flags="python-brace-format",
)

NO_AF_UNIX class-attribute instance-attribute

NO_AF_UNIX = commented("")(
    "Error message",
    "Cannot connect to an SSH agent because this Python version does not support UNIX domain sockets.",
)

NO_KEY_OR_PHRASE class-attribute instance-attribute

NO_KEY_OR_PHRASE = commented("")(
    "Error message",
    "No passphrase or key was given in the configuration.  In this case, the --phrase or --key argument is required.",
)

NO_SSH_AGENT_FOUND class-attribute instance-attribute

NO_SSH_AGENT_FOUND = commented("")(
    "Error message",
    "Cannot find any running SSH agent because SSH_AUTH_SOCK is not set.",
)

NO_SUITABLE_SSH_KEYS class-attribute instance-attribute

NO_SUITABLE_SSH_KEYS = commented("")(
    "Error message",
    "The SSH agent contains no keys suitable for {PROG_NAME}.",
    flags="python-brace-format",
)

PARAMS_MUTUALLY_EXCLUSIVE class-attribute instance-attribute

PARAMS_MUTUALLY_EXCLUSIVE = commented(
    'The params are long-form command-line option names.  Typical example: "--key is mutually exclusive with --phrase."'
)(
    "Error message",
    "{param1} is mutually exclusive with {param2}.",
    flags="python-brace-format",
)

PARAMS_NEEDS_SERVICE class-attribute instance-attribute

PARAMS_NEEDS_SERVICE = commented(
    "The param is a long-form command-line option name, the metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Error message",
    "{param} requires a {service_metavar}.",
    flags="python-brace-format",
)

PARAMS_NEEDS_SERVICE_OR_CONFIG class-attribute instance-attribute

PARAMS_NEEDS_SERVICE_OR_CONFIG = commented(
    "The param is a long-form command-line option name, the metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Error message",
    "{param} requires a {service_metavar} or --config.",
    flags="python-brace-format",
)

PARAMS_NO_SERVICE class-attribute instance-attribute

PARAMS_NO_SERVICE = commented(
    "The param is a long-form command-line option name, the metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Error message",
    "{param} does not take a {service_metavar} argument.",
    flags="python-brace-format",
)

SERVICE_REQUIRED class-attribute instance-attribute

SERVICE_REQUIRED = commented(
    "The metavar is Label.VAULT_METAVAR_SERVICE."
)(
    "Error message",
    "Deriving a passphrase requires a {service_metavar}.",
    flags="python-brace-format",
)

SET_AND_UNSET_SAME_SETTING class-attribute instance-attribute

SET_AND_UNSET_SAME_SETTING = commented(
    'The rephrasing "Attempted to unset and set the same setting (--unset={setting} --{setting}=...) at the same time."may or may not be more suitable as a basis for translation instead.'
)(
    "Error message",
    "Attempted to unset and set --{setting} at the same time.",
    flags="python-brace-format",
)

SSH_KEY_NOT_LOADED class-attribute instance-attribute

SSH_KEY_NOT_LOADED = commented("")(
    "Error message",
    "The requested SSH key is not loaded into the agent.",
)

USER_ABORTED_EDIT class-attribute instance-attribute

USER_ABORTED_EDIT = commented(
    "The user requested to edit the notes for a service, but aborted the request mid-editing."
)(
    "Error message",
    "Not saving any new notes: the user aborted the request.",
)

USER_ABORTED_PASSPHRASE class-attribute instance-attribute

USER_ABORTED_PASSPHRASE = commented(
    "The user was prompted for a master passphrase, but aborted the request."
)(
    "Error message",
    "No passphrase was given; the user aborted the request.",
)

USER_ABORTED_SSH_KEY_SELECTION class-attribute instance-attribute

USER_ABORTED_SSH_KEY_SELECTION = commented(
    "The user was prompted to select a master SSH key, but aborted the request."
)(
    "Error message",
    "No SSH key was selected; the user aborted the request.",
)

load_translations

load_translations(
    localedirs: list[str | bytes | PathLike] | None = None,
    languages: Sequence[str] | None = None,
    class_: type[NullTranslations] | None = None,
) -> NullTranslations

Load a translation catalog for derivepassphrase.

Runs gettext.translation under the hood for multiple locale directories. fallback=True is implied.

Parameters:

Name Type Description Default
localedirs list[str | bytes | PathLike] | None

A list of directories to run gettext.translation against. Defaults to $XDG_DATA_HOME/locale (usually ~/.local/share/locale), {sys.prefix}/share/locale and {sys.base_prefix}/share/locale if not given.

None
languages Sequence[str] | None

Passed directly to gettext.translation.

None
class_ type[NullTranslations] | None

Passed directly to gettext.translation.

None

Returns:

Type Description
NullTranslations

A (potentially dummy) translation catalog.

Raises:

Type Description
RuntimeError

APPDATA (on Windows) or XDG_DATA_HOME (otherwise) is not set. We attempted to compute the default value, but failed to determine the home directory.

translatable

translatable(
    context: str,
    single: str,
    /,
    flags: Iterable[str] = (),
    plural: str = "",
    comments: str = "",
) -> TranslatableString

Return a TranslatableString with validated parts.

This factory function is really only there to make the enum definitions more readable. It is the main implementation of the TranslatableStringConstructor.

commented

commented(
    comments: str = "",
) -> TranslatableStringConstructor

A “decorator” for readably constructing commented enum values.

Returns a partial application of translatable with the comments argument pre-filled.

This is geared towards the quirks of the API documentation extractor mkdocstrings-python/griffe, which reformat and trim enum value declarations in predictable but somewhat weird ways. Chains of function calls are preserved, though, so use this to our advantage to suggest a specific formatting.

This is not necessarily good code style, nor is it a lightweight solution.