derivepassphrase.git

1) # SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>

2) #
3) # SPDX-Licence-Identifier: MIT
4) 
5) """Internal module.  Do not use.  Contains error strings and functions."""
6) 
7) from __future__ import annotations
8) 

9) import contextlib

10) import datetime

11) import enum
12) import gettext
13) import inspect

14) import os
15) import sys

16) import textwrap

17) import types

18) from typing import TYPE_CHECKING, NamedTuple, TextIO, cast

19) 
20) import derivepassphrase as dpp
21) 
22) if TYPE_CHECKING:

23)     from collections.abc import Iterable, Mapping, Sequence

24) 
25)     from typing_extensions import Any, Self
26) 
27) __author__ = dpp.__author__
28) __version__ = dpp.__version__
29) 
30) __all__ = ('PROG_NAME',)
31) 
32) PROG_NAME = 'derivepassphrase'

33) 
34) 
35) def load_translations(
36)     localedirs: list[str] | None = None,
37)     languages: Sequence[str] | None = None,
38)     class_: type[gettext.NullTranslations] | None = None,

39) ) -> gettext.NullTranslations:  # pragma: no cover

40)     """Load a translation catalog for derivepassphrase.
41) 
42)     Runs [`gettext.translation`][] under the hood for multiple locale
43)     directories.  `fallback=True` is implied.
44) 
45)     Args:
46)         localedirs:
47)             A list of directories to run [`gettext.translation`][]
48)             against.  Defaults to `$XDG_DATA_HOME/locale` (usually
49)             `~/.local/share/locale`), `{sys.prefix}/share/locale` and
50)             `{sys.base_prefix}/share/locale` if not given.
51)         languages:
52)             Passed directly to [`gettext.translation`][].
53)         class_:
54)             Passed directly to [`gettext.translation`][].
55) 
56)     Returns:
57)         A (potentially dummy) translation catalog.
58) 
59)     """
60)     if localedirs is None:
61)         if sys.platform.startswith('win'):
62)             xdg_data_home = os.environ.get(
63)                 'APPDATA',
64)                 os.path.expanduser('~'),
65)             )
66)         elif os.environ.get('XDG_DATA_HOME'):
67)             xdg_data_home = os.environ['XDG_DATA_HOME']
68)         else:
69)             xdg_data_home = os.path.join(
70)                 os.path.expanduser('~'), '.local', 'share'
71)             )
72)         localedirs = [
73)             os.path.join(xdg_data_home, 'locale'),
74)             os.path.join(sys.prefix, 'share', 'locale'),
75)             os.path.join(sys.base_prefix, 'share', 'locale'),
76)         ]
77)     for localedir in localedirs:
78)         with contextlib.suppress(OSError):
79)             return gettext.translation(
80)                 PROG_NAME,
81)                 localedir=localedir,
82)                 languages=languages,
83)                 class_=class_,
84)             )
85)     return gettext.NullTranslations()
86) 
87) 
88) translation = load_translations()

89) 
90) 
91) class TranslatableString(NamedTuple):
92)     singular: str
93)     plural: str
94)     l10n_context: str
95)     translator_comments: str
96)     flags: frozenset[str]
97) 
98) 
99) def _prepare_translatable(
100)     msg: str,
101)     comments: str = '',
102)     context: str = '',
103)     plural_msg: str = '',
104)     *,
105)     flags: Iterable[str] = (),
106) ) -> TranslatableString:

107)     def maybe_rewrap(string: str) -> str:
108)         string = inspect.cleandoc(string)
109)         if not any(s.strip() == '\b' for s in string.splitlines()):
110)             string = '\n'.join(
111)                 textwrap.wrap(
112)                     string,
113)                     width=float('inf'),  # type: ignore[arg-type]
114)                     fix_sentence_endings=True,
115)                 )
116)             )
117)         else:  # pragma: no cover
118)             string = ''.join(
119)                 s
120)                 for s in string.splitlines(True)  # noqa: FBT003
121)                 if s.strip() == '\b'
122)             )
123)         return string
124) 
125)     msg = maybe_rewrap(msg)
126)     plural_msg = maybe_rewrap(plural_msg)

127)     context = context.strip()
128)     comments = inspect.cleandoc(comments)
129)     flags = (
130)         frozenset(f.strip() for f in flags)
131)         if not isinstance(flags, str)
132)         else frozenset({flags})
133)     )

134)     assert '{' not in msg or bool(
135)         flags & {'python-brace-format', 'no-python-brace-format'}

136)     ), f'Missing flag for how to deal with brace in {msg!r}'

137)     assert '%' not in msg or bool(
138)         flags & {'python-format', 'no-python-format'}

139)     ), f'Missing flag for how to deal with percent character in {msg!r}'

140)     assert (
141)         not flags & {'python-format', 'python-brace-format'}
142)         or '%' in msg
143)         or '{' in msg
144)     ), f'Missing format string parameters in {msg!r}'

145)     return TranslatableString(msg, plural_msg, context, comments, flags)
146) 
147) 

148) class TranslatedString:

149)     def __init__(
150)         self,

151)         template: (
152)             str
153)             | TranslatableString
154)             | Label
155)             | InfoMsgTemplate
156)             | WarnMsgTemplate
157)             | ErrMsgTemplate
158)         ),

159)         args_dict: Mapping[str, Any] = types.MappingProxyType({}),
160)         /,
161)         **kwargs: Any,  # noqa: ANN401
162)     ) -> None:

163)         if isinstance(
164)             template, (Label, InfoMsgTemplate, WarnMsgTemplate, ErrMsgTemplate)
165)         ):
166)             template = cast(TranslatableString, template.value)

167)         self.template = template
168)         self.kwargs = {**args_dict, **kwargs}
169)         self._rendered: str | None = None
170) 

171)     def __bool__(self) -> bool:
172)         return bool(str(self))
173) 
174)     def __eq__(self, other: object) -> bool:  # pragma: no cover
175)         return str(self) == other
176) 
177)     def __hash__(self) -> int:  # pragma: no cover
178)         return hash(str(self))
179) 
180)     def __repr__(self) -> str:  # pragma: no cover
181)         return (
182)             f'{self.__class__.__name__}({self.template!r}, '
183)             f'{dict(self.kwargs)!r})'
184)         )
185) 

186)     def __str__(self) -> str:
187)         if self._rendered is None:

188)             # raw str support is currently unneeded, so excluded from coverage
189)             if isinstance(self.template, str):  # pragma: no cover
190)                 context = None
191)                 template = self.template
192)             else:
193)                 context = self.template.l10n_context
194)                 template = self.template.singular

195)             if context is not None:
196)                 template = translation.pgettext(context, template)

197)             else:  # pragma: no cover

198)                 template = translation.gettext(template)
199)             self._rendered = template.format(**self.kwargs)
200)         return self._rendered
201) 
202)     def maybe_without_filename(self) -> Self:
203)         if (

204)             not isinstance(self.template, str)
205)             and self.kwargs.get('filename') is None

206)             and ': {filename!r}' in self.template.singular
207)         ):
208)             singular = ''.join(
209)                 self.template.singular.split(': {filename!r}', 1)
210)             )
211)             plural = (
212)                 ''.join(self.template.plural.split(': {filename!r}', 1))
213)                 if self.template.plural
214)                 else self.template.plural
215)             )
216)             return self.__class__(
217)                 self.template._replace(singular=singular, plural=plural),
218)                 self.kwargs,
219)             )
220)         return self
221) 
222) 

223) class Label(enum.Enum):
224)     DEPRECATION_WARNING_LABEL = _prepare_translatable(

225)         comments=r"""
226)         TRANSLATORS: This is a short label that will be prepended to
227)         a warning message, e.g., "Deprecation warning: A subcommand will
228)         be required in v1.0."
229)         """,
230)         msg='Deprecation warning',
231)         context='diagnostic label',

232)     )
233)     WARNING_LABEL = _prepare_translatable(

234)         comments=r"""
235)         TRANSLATORS: This is a short label that will be prepended to
236)         a warning message, e.g., "Warning: An empty service name is not
237)         supported by vault(1)."
238)         """,
239)         msg='Warning',
240)         context='diagnostic label',

241)     )

242)     CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL = (
243)         _prepare_translatable(
244)             comments=r"""
245)             TRANSLATORS: This is one of two values of the settings_type
246)             metavar used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS
247)             entry.  It is only used there.  The full sentence then
248)             reads: "Cannot update the global settings without any given
249)             settings."
250)             """,
251)             msg='global settings',
252)             context='diagnostic label (metavar value)',
253)         )
254)     )
255)     CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE = (
256)         _prepare_translatable(
257)             comments=r"""
258)             TRANSLATORS: This is one of two values of the settings_type
259)             metavar used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS
260)             entry.  It is only used there.  The full sentence then
261)             reads: "Cannot update the service-specific settings without
262)             any given settings."
263)             """,
264)             msg='service-specific settings',
265)             context='diagnostic label (metavar value)',
266)         )
267)     )

268)     DERIVEPASSPHRASE_01 = _prepare_translatable(

269)         comments=r"""
270)         TRANSLATORS: This is the first paragraph of the command help
271)         text, but it also appears (in truncated form, if necessary) as
272)         one-line help text for this command.  The translation should
273)         thus be as meaningful as possible even if truncated.
274)         """,

275)         msg="""
276)         Derive a strong passphrase, deterministically, from a master secret.
277)         """,
278)         context='help text (long form)',
279)     )
280)     DERIVEPASSPHRASE_02 = _prepare_translatable(
281)         msg="""
282)         The currently implemented subcommands are "vault" (for the
283)         scheme used by vault) and "export" (for exporting foreign
284)         configuration data).  See the respective `--help` output for
285)         instructions.  If no subcommand is given, we default to "vault".
286)         """,
287)         comments='',
288)         context='help text (long form)',
289)     )
290)     DERIVEPASSPHRASE_03 = _prepare_translatable(
291)         msg="""
292)         Deprecation notice: Defaulting to "vault" is deprecated.
293)         Starting in v1.0, the subcommand must be specified explicitly.
294)         """,
295)         comments='',
296)         context='help text (long form)',
297)     )
298)     DERIVEPASSPHRASE_EPILOG_01 = _prepare_translatable(
299)         msg=r"""
300)         Configuration is stored in a directory according to the
301)         `DERIVEPASSPHRASE_PATH` variable, which defaults to
302)         `~/.derivepassphrase` on UNIX-like systems and
303)         `C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.
304)         """,
305)         comments='',
306)         context='help text (long form)',
307)     )
308)     DERIVEPASSPHRASE_EXPORT_01 = _prepare_translatable(

309)         comments=r"""
310)         TRANSLATORS: This is the first paragraph of the command help
311)         text, but it also appears (in truncated form, if necessary) as
312)         one-line help text for this command.  The translation should
313)         thus be as meaningful as possible even if truncated.
314)         """,

315)         msg="""
316)         Export a foreign configuration to standard output.
317)         """,
318)         context='help text (long form)',
319)     )
320)     DERIVEPASSPHRASE_EXPORT_02 = _prepare_translatable(
321)         msg="""
322)         The only available subcommand is "vault", which implements the
323)         vault-native configuration scheme.  If no subcommand is given,
324)         we default to "vault".
325)         """,
326)         comments='',
327)         context='help text (long form)',
328)     )
329)     DERIVEPASSPHRASE_EXPORT_03 = DERIVEPASSPHRASE_03
330)     DERIVEPASSPHRASE_EXPORT_VAULT_01 = _prepare_translatable(

331)         comments=r"""
332)         TRANSLATORS: This is the first paragraph of the command help
333)         text, but it also appears (in truncated form, if necessary) as
334)         one-line help text for this command.  The translation should
335)         thus be as meaningful as possible even if truncated.
336)         """,

337)         msg="""
338)         Export a vault-native configuration to standard output.
339)         """,
340)         context='help text (long form)',
341)     )
342)     DERIVEPASSPHRASE_EXPORT_VAULT_02 = _prepare_translatable(
343)         msg="""
344)         Depending on the configuration format, {path_metavar!s} may
345)         either be a file or a directory.  We support the vault "v0.2",
346)         "v0.3" and "storeroom" formats.
347)         """,
348)         comments='',
349)         context='help text (long form)',
350)         flags='python-brace-format',
351)     )
352)     DERIVEPASSPHRASE_EXPORT_VAULT_03 = _prepare_translatable(
353)         msg="""
354)         If {path_metavar!s} is explicitly given as `VAULT_PATH`, then
355)         use the `VAULT_PATH` environment variable to determine the
356)         correct path.  (Use `./VAULT_PATH` or similar to indicate
357)         a file/directory actually named `VAULT_PATH`.)
358)         """,
359)         comments='',
360)         context='help text (long form)',
361)         flags='python-brace-format',
362)     )
363)     DERIVEPASSPHRASE_VAULT_01 = _prepare_translatable(

364)         comments=r"""
365)         TRANSLATORS: This is the first paragraph of the command help
366)         text, but it also appears (in truncated form, if necessary) as
367)         one-line help text for this command.  The translation should
368)         thus be as meaningful as possible even if truncated.
369)         """,

370)         msg="""
371)         Derive a passphrase using the vault derivation scheme.
372)         """,
373)         context='help text (long form)',
374)     )
375)     DERIVEPASSPHRASE_VAULT_02 = _prepare_translatable(
376)         msg="""
377)         If operating on global settings, or importing/exporting
378)         settings, then {service_metavar!s} must be omitted.  Otherwise
379)         it is required.
380)         """,
381)         comments='',
382)         context='help text (long form)',
383)         flags='python-brace-format',
384)     )
385)     DERIVEPASSPHRASE_VAULT_EPILOG_01 = _prepare_translatable(
386)         msg="""
387)         WARNING: There is NO WAY to retrieve the generated passphrases
388)         if the master passphrase, the SSH key, or the exact passphrase
389)         settings are lost, short of trying out all possible
390)         combinations.  You are STRONGLY advised to keep independent
391)         backups of the settings and the SSH key, if any.
392)         """,
393)         comments='',
394)         context='help text (long form)',
395)     )
396)     DERIVEPASSPHRASE_VAULT_EPILOG_02 = _prepare_translatable(
397)         msg="""
398)         The configuration is NOT encrypted, and you are STRONGLY
399)         discouraged from using a stored passphrase.
400)         """,
401)         comments='',
402)         context='help text (long form)',
403)     )
404)     DEPRECATED_COMMAND_LABEL = _prepare_translatable(

405)         comments=r"""
406)         TRANSLATORS: We use this format string to indicate, at the
407)         beginning of a command's help text, that this command is
408)         deprecated.
409)         """,

410)         msg='(Deprecated) {text}',
411)         context='help text (long form, label)',
412)         flags='python-brace-format',
413)     )
414)     DEBUG_OPTION_HELP_TEXT = _prepare_translatable(
415)         'also emit debug information (implies --verbose)',
416)         comments='',
417)         context='help text (option one-line description)',
418)     )
419)     EXPORT_VAULT_FORMAT_HELP_TEXT = _prepare_translatable(
420)         comments=r"""

421)         TRANSLATORS: The defaults_hint is
422)         Label.EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT, the metavar is
423)         Label.EXPORT_VAULT_FORMAT_METAVAR_FMT.

424)         """,
425)         msg=r"""
426)         try the following storage format {metavar!s}; may be
427)         specified multiple times, formats will be tried in order
428)         {defaults_hint!s}
429)         """,
430)         context='help text (option one-line description)',
431)         flags='python-brace-format',
432)     )
433)     EXPORT_VAULT_FORMAT_DEFAULTS_HELP_TEXT = _prepare_translatable(
434)         comments=r"""
435)         TRANSLATORS: See EXPORT_VAULT_FORMAT_HELP_TEXT.  The format
436)         names/labels "v0.3", "v0.2" and "storeroom" should not be
437)         translated.
438)         """,
439)         msg=r"""
440)         (default: v0.3, v0.2, storeroom)
441)         """,
442)         context='help text (option one-line description)',
443)     )
444)     EXPORT_VAULT_KEY_HELP_TEXT = _prepare_translatable(
445)         comments=r"""

446)         TRANSLATORS: The defaults_hint is
447)         Label.EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT, the metavar is
448)         Label.EXPORT_VAULT_KEY_METAVAR_K.

449)         """,
450)         msg=r"""
451)         use {metavar!s} as the storage master key {defaults_hint!s}
452)         """,
453)         context='help text (option one-line description)',
454)         flags='python-brace-format',
455)     )
456)     EXPORT_VAULT_KEY_DEFAULTS_HELP_TEXT = _prepare_translatable(
457)         comments=r"""
458)         TRANSLATORS: See EXPORT_VAULT_KEY_HELP_TEXT.
459)         """,
460)         msg=r"""
461)         (default: check the `VAULT_KEY`, `LOGNAME`, `USER`, or
462)         `USERNAME` environment variables)
463)         """,
464)         context='help text (option one-line description)',
465)     )

466)     HELP_OPTION_HELP_TEXT = _prepare_translatable(
467)         'show this help text, then exit',
468)         comments='',
469)         context='help text (option one-line description)',
470)     )

471)     QUIET_OPTION_HELP_TEXT = _prepare_translatable(
472)         'suppress even warnings, emit only errors',
473)         comments='',
474)         context='help text (option one-line description)',
475)     )
476)     VERBOSE_OPTION_HELP_TEXT = _prepare_translatable(
477)         'emit extra/progress information to standard error',
478)         comments='',
479)         context='help text (option one-line description)',
480)     )

481)     VERSION_OPTION_HELP_TEXT = _prepare_translatable(
482)         'show applicable version information, then exit',
483)         comments='',
484)         context='help text (option one-line description)',
485)     )

486) 

487)     DERIVEPASSPHRASE_VAULT_PHRASE_HELP_TEXT = _prepare_translatable(
488)         msg='prompt for a master passphrase',
489)         comments='',
490)         context='help text (option one-line description)',
491)     )
492)     DERIVEPASSPHRASE_VAULT_KEY_HELP_TEXT = _prepare_translatable(
493)         msg='select a suitable SSH key from the SSH agent',
494)         comments='',
495)         context='help text (option one-line description)',
496)     )
497)     DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT = _prepare_translatable(
498)         comments=r"""

499)         TRANSLATORS: The metavar is
500)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

501)         """,
502)         msg='ensure a passphrase length of {metavar!s} characters',
503)         context='help text (option one-line description)',
504)         flags='python-brace-format',
505)     )
506)     DERIVEPASSPHRASE_VAULT_REPEAT_HELP_TEXT = _prepare_translatable(
507)         comments=r"""

508)         TRANSLATORS: The metavar is
509)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

510)         """,
511)         msg='forbid any run of {metavar!s} identical characters',
512)         context='help text (option one-line description)',
513)         flags='python-brace-format',
514)     )
515)     DERIVEPASSPHRASE_VAULT_LOWER_HELP_TEXT = _prepare_translatable(
516)         comments=r"""

517)         TRANSLATORS: The metavar is
518)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

519)         """,
520)         msg='ensure at least {metavar!s} lowercase characters',
521)         context='help text (option one-line description)',
522)         flags='python-brace-format',
523)     )
524)     DERIVEPASSPHRASE_VAULT_UPPER_HELP_TEXT = _prepare_translatable(
525)         comments=r"""

526)         TRANSLATORS: The metavar is
527)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

528)         """,
529)         msg='ensure at least {metavar!s} uppercase characters',
530)         context='help text (option one-line description)',
531)         flags='python-brace-format',
532)     )
533)     DERIVEPASSPHRASE_VAULT_NUMBER_HELP_TEXT = _prepare_translatable(
534)         comments=r"""

535)         TRANSLATORS: The metavar is
536)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

537)         """,
538)         msg='ensure at least {metavar!s} digits',
539)         context='help text (option one-line description)',
540)         flags='python-brace-format',
541)     )
542)     DERIVEPASSPHRASE_VAULT_SPACE_HELP_TEXT = _prepare_translatable(
543)         comments=r"""

544)         TRANSLATORS: The metavar is
545)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

546)         """,
547)         msg='ensure at least {metavar!s} spaces',
548)         context='help text (option one-line description)',
549)         flags='python-brace-format',
550)     )
551)     DERIVEPASSPHRASE_VAULT_DASH_HELP_TEXT = _prepare_translatable(
552)         comments=r"""

553)         TRANSLATORS: The metavar is
554)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

555)         """,
556)         msg='ensure at least {metavar!s} "-" or "_" characters',
557)         context='help text (option one-line description)',
558)         flags='python-brace-format',
559)     )
560)     DERIVEPASSPHRASE_VAULT_SYMBOL_HELP_TEXT = _prepare_translatable(
561)         comments=r"""

562)         TRANSLATORS: The metavar is
563)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

564)         """,
565)         msg='ensure at least {metavar!s} symbol characters',
566)         context='help text (option one-line description)',
567)         flags='python-brace-format',
568)     )
569) 
570)     DERIVEPASSPHRASE_VAULT_NOTES_HELP_TEXT = _prepare_translatable(
571)         msg='spawn an editor to edit notes for {service_metavar!s}',
572)         comments='',
573)         context='help text (option one-line description)',
574)         flags='python-brace-format',
575)     )
576)     DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT = _prepare_translatable(
577)         msg='save the given settings for {service_metavar!s}, or global',
578)         comments='',
579)         context='help text (option one-line description)',
580)         flags='python-brace-format',
581)     )
582)     DERIVEPASSPHRASE_VAULT_DELETE_HELP_TEXT = _prepare_translatable(
583)         msg='delete the settings for {service_metavar!s}',
584)         comments='',
585)         context='help text (option one-line description)',
586)         flags='python-brace-format',
587)     )
588)     DERIVEPASSPHRASE_VAULT_DELETE_GLOBALS_HELP_TEXT = _prepare_translatable(
589)         msg='delete the global settings',
590)         comments='',
591)         context='help text (option one-line description)',
592)     )
593)     DERIVEPASSPHRASE_VAULT_DELETE_ALL_HELP_TEXT = _prepare_translatable(
594)         msg='delete all settings',
595)         comments='',
596)         context='help text (option one-line description)',
597)     )
598)     DERIVEPASSPHRASE_VAULT_EXPORT_HELP_TEXT = _prepare_translatable(
599)         comments="""

600)         TRANSLATORS: The metavar is
601)         Label.STORAGE_MANAGEMENT_METAVAR_SERVICE.

602)         """,
603)         msg='export all saved settings to {metavar!s}',
604)         context='help text (option one-line description)',
605)         flags='python-brace-format',
606)     )
607)     DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT = _prepare_translatable(
608)         comments="""

609)         TRANSLATORS: The metavar is
610)         Label.STORAGE_MANAGEMENT_METAVAR_SERVICE.

611)         """,
612)         msg='import saved settings from {metavar!s}',
613)         context='help text (option one-line description)',
614)         flags='python-brace-format',
615)     )
616)     DERIVEPASSPHRASE_VAULT_OVERWRITE_HELP_TEXT = _prepare_translatable(
617)         comments="""
618)         TRANSLATORS: The corresponding option is displayed as
619)         "--overwrite-existing / --merge-existing", so you may want to
620)         hint that the default (merge) is the second of those options.
621)         """,
622)         msg='overwrite or merge (default) the existing configuration',
623)         context='help text (option one-line description)',
624)     )
625)     DERIVEPASSPHRASE_VAULT_UNSET_HELP_TEXT = _prepare_translatable(
626)         comments="""
627)         TRANSLATORS: The corresponding option is displayed as
628)         "--unset=phrase|key|...|symbol", so the "given setting" is
629)         referring to "phrase", "key", "lower", ..., or "symbol",
630)         respectively.  "with --config" here means that the user must
631)         also specify "--config" for this option to have any effect.
632)         """,
633)         msg="""
634)         with --config, also unsets the given setting; may be specified
635)         multiple times
636)         """,
637)         context='help text (option one-line description)',
638)     )
639)     DERIVEPASSPHRASE_VAULT_EXPORT_AS_HELP_TEXT = _prepare_translatable(
640)         comments="""
641)         TRANSLATORS: The corresponding option is displayed as
642)         "--export-as=json|sh", so json refers to the JSON format
643)         (default) and sh refers to the POSIX sh format.
644)         """,
645)         msg='when exporting, export as JSON (default) or POSIX sh',
646)         context='help text (option one-line description)',
647)     )
648) 
649)     EXPORT_VAULT_FORMAT_METAVAR_FMT = _prepare_translatable(
650)         msg='FMT',
651)         comments='',
652)         context='help text, metavar (export vault subcommand)',
653)     )
654)     EXPORT_VAULT_KEY_METAVAR_K = _prepare_translatable(
655)         comments=r"""

656)         TRANSLATORS: See Label.EXPORT_VAULT_KEY_HELP_TEXT.

657)         """,
658)         msg='K',
659)         context='help text, metavar (export vault subcommand)',
660)     )
661)     EXPORT_VAULT_METAVAR_PATH = _prepare_translatable(
662)         comments=r"""

663)         TRANSLATORS: Used as "path_metavar" in
664)         Label.DERIVEPASSPHRASE_EXPORT_VAULT_02 and others.

665)         """,
666)         msg='PATH',
667)         context='help text, metavar (export vault subcommand)',
668)     )
669)     PASSPHRASE_GENERATION_METAVAR_NUMBER = _prepare_translatable(
670)         comments=r"""
671)         TRANSLATORS: This metavar is also used in a matching epilog.
672)         """,
673)         msg='NUMBER',
674)         context='help text, metavar (passphrase generation group)',
675)     )
676)     STORAGE_MANAGEMENT_METAVAR_PATH = _prepare_translatable(
677)         comments=r"""
678)         TRANSLATORS: This metavar is also used in multiple one-line help
679)         texts.
680)         """,

681)         msg='PATH',

682)         context='help text, metavar (storage management group)',
683)     )
684)     VAULT_METAVAR_SERVICE = _prepare_translatable(
685)         comments=r"""
686)         TRANSLATORS: This metavar is also used in multiple one-line help
687)         texts, as "service_metavar".
688)         """,
689)         msg='SERVICE',
690)         context='help text, metavar (vault subcommand)',
691)     )
692)     CONFIGURATION_EPILOG = _prepare_translatable(
693)         'Use $VISUAL or $EDITOR to configure the spawned editor.',
694)         comments='',
695)         context='help text, option group epilog (configuration group)',
696)     )
697)     PASSPHRASE_GENERATION_EPILOG = _prepare_translatable(
698)         comments=r"""

699)         TRANSLATORS: The metavar is
700)         Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.

701)         """,
702)         msg=r"""
703)         Use {metavar!s}=0 to exclude a character type from the output.
704)         """,
705)         context='help text, option group epilog (passphrase generation group)',
706)         flags='python-brace-format',
707)     )
708)     STORAGE_MANAGEMENT_EPILOG = _prepare_translatable(
709)         comments=r"""

710)         TRANSLATORS: The metavar is
711)         Label.STORAGE_MANAGEMENT_METAVAR_PATH.

712)         """,
713)         msg=r"""
714)         Using "-" as {metavar!s} for standard input/standard output
715)         is supported.
716)         """,
717)         context='help text, option group epilog (storage management group)',
718)         flags='python-brace-format',
719)     )
720)     COMMANDS_LABEL = _prepare_translatable(
721)         'Commands', comments='', context='help text, option group name'
722)     )
723)     COMPATIBILITY_OPTION_LABEL = _prepare_translatable(
724)         'Compatibility and extension options',
725)         comments='',
726)         context='help text, option group name',
727)     )
728)     CONFIGURATION_LABEL = _prepare_translatable(
729)         'Configuration', comments='', context='help text, option group name'
730)     )
731)     LOGGING_LABEL = _prepare_translatable(
732)         'Logging', comments='', context='help text, option group name'
733)     )
734)     OPTIONS_LABEL = _prepare_translatable(
735)         'Options', comments='', context='help text, option group name'
736)     )
737)     OTHER_OPTIONS_LABEL = _prepare_translatable(
738)         'Other options', comments='', context='help text, option group name'
739)     )
740)     PASSPHRASE_GENERATION_LABEL = _prepare_translatable(
741)         'Passphrase generation',
742)         comments='',
743)         context='help text, option group name',
744)     )
745)     STORAGE_MANAGEMENT_LABEL = _prepare_translatable(
746)         'Storage management',
747)         comments='',
748)         context='help text, option group name',
749)     )

750)     VERSION_INFO_TEXT = _prepare_translatable(
751)         msg=r"""
752)         {PROG_NAME!s} {__version__}
753)         """,  # noqa: RUF027
754)         comments='',
755)         context='help text, version info text',
756)         flags='python-brace-format',
757)     )

758)     CONFIRM_THIS_CHOICE_PROMPT_TEXT = _prepare_translatable(
759)         comments=r"""
760)         TRANSLATORS: There is no support for "yes" or "no" in other
761)         languages than English, so it is advised that your translation
762)         makes it clear that only the strings "y", "yes", "n" or "no" are
763)         supported, even if the prompt becomes a bit longer.
764)         """,
765)         msg='Confirm this choice? (y/N)',
766)         context='interactive prompt',
767)     )
768)     SUITABLE_SSH_KEYS_LABEL = _prepare_translatable(
769)         comments=r"""
770)         TRANSLATORS: This label is the heading of the list of suitable
771)         SSH keys.
772)         """,
773)         msg='Suitable SSH keys:',
774)         context='interactive prompt',
775)     )
776)     YOUR_SELECTION_PROMPT_TEXT = _prepare_translatable(
777)         'Your selection? (1-{n}, leave empty to abort)',
778)         comments='',
779)         context='interactive prompt',
780)         flags='python-brace-format',
781)     )

782) 
783) 
784) class InfoMsgTemplate(enum.Enum):
785)     CANNOT_LOAD_AS_VAULT_CONFIG = _prepare_translatable(
786)         comments=r"""
787)         TRANSLATORS: "fmt" is a string such as "v0.2" or "storeroom",
788)         indicating the format which we tried to load the vault
789)         configuration as.
790)         """,
791)         msg='Cannot load {path!r} as a {fmt!s} vault configuration.',
792)         context='info message',
793)         flags='python-brace-format',
794)     )
795)     PIP_INSTALL_EXTRA = _prepare_translatable(
796)         comments=r"""
797)         TRANSLATORS: This message immediately follows an error message
798)         about a missing library that needs to be installed.  The Python
799)         Package Index (PyPI) supports declaring sets of optional
800)         dependencies as "extras", so users installing from PyPI can
801)         request reinstallation with a named "extra" being enabled.  This
802)         would then let the installer take care of the missing libraries
803)         automatically, hence this suggestion to PyPI users.
804)         """,
805)         msg='(For users installing from PyPI, see the {extra_name!r} extra.)',
806)         context='info message',
807)         flags='python-brace-format',
808)     )
809)     SUCCESSFULLY_MIGRATED = _prepare_translatable(
810)         comments=r"""
811)         TRANSLATORS: This info message immediately follows the "Using
812)         deprecated v0.1-style ..." deprecation warning.
813)         """,
814)         msg='Successfully migrated to {path!r}.',
815)         context='info message',
816)         flags='python-brace-format',
817)     )
818) 
819) 
820) class WarnMsgTemplate(enum.Enum):
821)     EMPTY_SERVICE_NOT_SUPPORTED = _prepare_translatable(
822)         comments='',

823)         msg="""
824)         An empty {service_metavar!s} is not supported by vault(1).
825)         For compatibility, this will be treated as if SERVICE was not
826)         supplied, i.e., it will error out, or operate on global settings.
827)         """,

828)         context='warning message',

829)         flags='python-brace-format',

830)     )
831)     EMPTY_SERVICE_SETTINGS_INACCESSIBLE = _prepare_translatable(

832)         msg="""
833)         An empty {service_metavar!s} is not supported by vault(1).
834)         The empty-string service settings will be inaccessible and
835)         ineffective.  To ensure that vault(1) and {PROG_NAME!s} see the
836)         settings, move them into the "global" section.
837)         """,

838)         comments='',
839)         context='warning message',

840)         flags='python-brace-format',

841)     )
842)     FAILED_TO_MIGRATE_CONFIG = _prepare_translatable(
843)         comments=r"""

844)         TRANSLATORS: "error" is supplied by the operating system
845)         (errno/strerror).

846)         """,
847)         msg='Failed to migrate to {path!r}: {error!s}: {filename!r}.',
848)         context='warning message',
849)         flags='python-brace-format',
850)     )
851)     GLOBAL_PASSPHRASE_INEFFECTIVE = _prepare_translatable(

852)         msg=r"""
853)         Setting a global passphrase is ineffective
854)         because a key is also set.
855)         """,

856)         comments='',
857)         context='warning message',
858)     )
859)     PASSPHRASE_NOT_NORMALIZED = _prepare_translatable(
860)         comments=r"""
861)         TRANSLATORS: The key is a (vault) configuration key, in JSONPath
862)         syntax, typically "$.global" for the global passphrase or
863)         "$.services.service_name" or "$.services["service with spaces"]"
864)         for the services "service_name" and "service with spaces",
865)         respectively.  The form is one of the four Unicode normalization
866)         forms: NFC, NFD, NFKC, NFKD.
867) 
868)         The asterisks are not special.  Please feel free to substitute
869)         any other appropriate way to mark up emphasis of the word
870)         "displays".
871)         """,

872)         msg=r"""
873)         The {key!s} passphrase is not {form!s}-normalized.  Its
874)         serialization as a byte string may not be what you expect it to
875)         be, even if it *displays* correctly.  Please make sure to
876)         double-check any derived passphrases for unexpected results.
877)         """,

878)         context='warning message',
879)         flags='python-brace-format',
880)     )

881)     SERVICE_NAME_INCOMPLETABLE = _prepare_translatable(
882)         msg="""
883)         The service name {service!r} contains an ASCII control
884)         character, which is not supported by our shell completion code.
885)         This service name will therefore not be available for completion
886)         on the command-line.  You may of course still type it in
887)         manually in whatever format your shell accepts, but we highly
888)         recommend choosing a different service name instead.
889)         """,
890)         comments='',
891)         context='warning message',
892)         flags='python-brace-format',
893)     )

894)     SERVICE_PASSPHRASE_INEFFECTIVE = _prepare_translatable(
895)         comments=r"""
896)         TRANSLATORS: The key that is set need not necessarily be set at
897)         the service level; it may be a global key as well.
898)         """,

899)         msg=r"""
900)         Setting a service passphrase is ineffective because a key is
901)         also set: {service!s}.
902)         """,

903)         context='warning message',
904)         flags='python-brace-format',
905)     )
906)     STEP_REMOVE_INEFFECTIVE_VALUE = _prepare_translatable(
907)         'Removing ineffective setting {path!s} = {old!s}.',
908)         comments='',
909)         context='warning message',
910)         flags='python-brace-format',
911)     )
912)     STEP_REPLACE_INVALID_VALUE = _prepare_translatable(
913)         'Replacing invalid value {old!s} for key {path!s} with {new!s}.',
914)         comments='',
915)         context='warning message',
916)         flags='python-brace-format',
917)     )
918)     V01_STYLE_CONFIG = _prepare_translatable(

919)         msg=r"""
920)         Using deprecated v0.1-style config file {old!r}, instead of
921)         v0.2-style {new!r}.  Support for v0.1-style config filenames

922)         will be removed in v1.0.

923)         """,

924)         comments='',
925)         context='deprecation warning message',
926)         flags='python-brace-format',
927)     )
928)     V10_SUBCOMMAND_REQUIRED = _prepare_translatable(
929)         comments=r"""
930)         TRANSLATORS: This deprecation warning may be issued at any
931)         level, i.e. we may actually be talking about subcommands, or
932)         sub-subcommands, or sub-sub-subcommands, etc., which is what the
933)         "here" is supposed to indicate.
934)         """,

935)         msg="""
936)         A subcommand will be required here in v1.0.  See --help for
937)         available subcommands.  Defaulting to subcommand "vault".
938)         """,

939)         context='deprecation warning message',
940)     )
941) 
942) 
943) class ErrMsgTemplate(enum.Enum):

944)     AGENT_REFUSED_LIST_KEYS = _prepare_translatable(
945)         comments=r"""
946)         TRANSLATORS: "loaded keys" being keys loaded into the agent.
947)         """,
948)         msg="""
949)         The SSH agent failed to or refused to supply a list of loaded keys.
950)         """,
951)         context='error message',
952)     )
953)     AGENT_REFUSED_SIGNATURE = _prepare_translatable(
954)         comments=r"""
955)         TRANSLATORS: The message to be signed is the vault UUID, but
956)         there's no space to explain that here, so ideally the error
957)         message does not go into detail.
958)         """,
959)         msg="""
960)         The SSH agent failed to or refused to issue a signature with the
961)         selected key, necessary for deriving a service passphrase.
962)         """,
963)         context='error message',
964)     )

965)     CANNOT_CONNECT_TO_AGENT = _prepare_translatable(
966)         comments=r"""

967)         TRANSLATORS: "error" is supplied by the operating system
968)         (errno/strerror).

969)         """,
970)         msg='Cannot connect to the SSH agent: {error!s}: {filename!r}.',
971)         context='error message',
972)         flags='python-brace-format',
973)     )
974)     CANNOT_DECODEIMPORT_VAULT_SETTINGS = _prepare_translatable(

975)         comments=r"""
976)         TRANSLATORS: "error" is supplied by the operating system
977)         (errno/strerror).
978)         """,

979)         msg='Cannot import vault settings: cannot decode JSON: {error!s}.',
980)         context='error message',
981)         flags='python-brace-format',
982)     )
983)     CANNOT_EXPORT_VAULT_SETTINGS = _prepare_translatable(
984)         comments=r"""

985)         TRANSLATORS: "error" is supplied by the operating system
986)         (errno/strerror).

987)         """,
988)         msg='Cannot export vault settings: {error!s}: {filename!r}.',
989)         context='error message',
990)         flags='python-brace-format',
991)     )
992)     CANNOT_IMPORT_VAULT_SETTINGS = _prepare_translatable(
993)         comments=r"""

994)         TRANSLATORS: "error" is supplied by the operating system
995)         (errno/strerror).

996)         """,
997)         msg='Cannot import vault settings: {error!s}: {filename!r}.',
998)         context='error message',
999)         flags='python-brace-format',
1000)     )
1001)     CANNOT_LOAD_USER_CONFIG = _prepare_translatable(
1002)         comments=r"""

1003)         TRANSLATORS: "error" is supplied by the operating system
1004)         (errno/strerror).

1005)         """,
1006)         msg='Cannot load user config: {error!s}: {filename!r}.',
1007)         context='error message',
1008)         flags='python-brace-format',
1009)     )
1010)     CANNOT_LOAD_VAULT_SETTINGS = _prepare_translatable(
1011)         comments=r"""

1012)         TRANSLATORS: "error" is supplied by the operating system
1013)         (errno/strerror).

1014)         """,
1015)         msg='Cannot load vault settings: {error!s}: {filename!r}.',
1016)         context='error message',
1017)         flags='python-brace-format',
1018)     )
1019)     CANNOT_PARSE_AS_VAULT_CONFIG = _prepare_translatable(
1020)         comments=r"""
1021)         TRANSLATORS: Unlike the "Cannot load {path!r} as a {fmt!s} vault
1022)         configuration." message, *this* error message is emitted when we
1023)         have tried loading the path in each of our supported formats,
1024)         and failed.  The user will thus see the above "Cannot load ..."
1025)         warning message potentially multiple times, and this error
1026)         message at the very bottom.
1027)         """,

1028)         msg=r"""
1029)         Cannot parse {path!r} as a valid vault-native configuration
1030)         file/directory.
1031)         """,

1032)         context='error message',
1033)         flags='python-brace-format',
1034)     )

1035)     CANNOT_PARSE_AS_VAULT_CONFIG_OSERROR = _prepare_translatable(
1036)         comments=r"""
1037)         TRANSLATORS: "error" is supplied by the operating system
1038)         (errno/strerror).
1039)         """,
1040)         msg=r"""
1041)         Cannot parse {path!r} as a valid vault-native configuration
1042)         file/directory: {error!s}: {filename!r}.
1043)         """,
1044)         context='error message',
1045)         flags='python-brace-format',
1046)     )

1047)     CANNOT_STORE_VAULT_SETTINGS = _prepare_translatable(
1048)         comments=r"""

1049)         TRANSLATORS: "error" is supplied by the operating system
1050)         (errno/strerror).

1051)         """,
1052)         msg='Cannot store vault settings: {error!s}: {filename!r}.',
1053)         context='error message',
1054)         flags='python-brace-format',
1055)     )

1056)     CANNOT_UNDERSTAND_AGENT = _prepare_translatable(
1057)         comments=r"""
1058)         TRANSLATORS: This error message is used whenever we cannot make
1059)         any sense of a response from the SSH agent because the response
1060)         is ill-formed (truncated, improperly encoded, etc.) or otherwise
1061)         violates the communications protocol.  Well-formed responses
1062)         that adhere to the protocol, even if they indicate that the
1063)         requested operation failed, are handled with a different error
1064)         message.
1065)         """,
1066)         msg="""
1067)         Cannot understand the SSH agent's response because it violates
1068)         the communications protocol.
1069)         """,

1070)         context='error message',

1071)     )

1072)     CANNOT_UPDATE_SETTINGS_NO_SETTINGS = _prepare_translatable(

1073)         comments=r"""
1074)         TRANSLATORS: The settings_type metavar contains translations for
1075)         either "global settings" or "service-specific settings"; see the
1076)         CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL and
1077)         CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE entries.
1078)         The first sentence will thus read either "Cannot update the
1079)         global settings without any given settings." or "Cannot update
1080)         the service-specific settings without any given settings.".  You
1081)         may update this entry, and the two metavar entries, in any way
1082)         you see fit that achieves the desired translations of the first
1083)         sentence.
1084)         """,

1085)         msg=r"""

1086)         Cannot update the {settings_type!s} without any given settings.
1087)         You must specify at least one of --lower, ..., --symbol, or
1088)         --phrase or --key.

1089)         """,

1090)         context='error message',
1091)         flags='python-brace-format',
1092)     )

1093)     INVALID_USER_CONFIG = _prepare_translatable(
1094)         comments=r"""

1095)         TRANSLATORS: "error" is supplied by the operating system
1096)         (errno/strerror).

1097)         """,
1098)         msg=r"""
1099)         The user configuration file is invalid.  {error!s}: {filename!r}.
1100)         """,
1101)         context='error message',
1102)         flags='python-brace-format',
1103)     )

1104)     INVALID_VAULT_CONFIG = _prepare_translatable(
1105)         comments=r"""
1106)         TRANSLATORS: This error message is a reaction to a validator
1107)         function saying *that* the configuration is not valid, but not
1108)         *how* it is not valid.  The configuration file is principally
1109)         parsable, however.
1110)         """,
1111)         msg='Invalid vault config: {config!r}.',
1112)         context='error message',
1113)         flags='python-brace-format',
1114)     )
1115)     MISSING_MODULE = _prepare_translatable(
1116)         'Cannot load the required Python module {module!r}.',
1117)         comments='',
1118)         context='error message',
1119)         flags='python-brace-format',
1120)     )
1121)     NO_AF_UNIX = _prepare_translatable(

1122)         msg=r"""
1123)         Cannot connect to an SSH agent because this Python version does
1124)         not support UNIX domain sockets.
1125)         """,

1126)         comments='',
1127)         context='error message',
1128)     )
1129)     NO_KEY_OR_PHRASE = _prepare_translatable(

1130)         msg=r"""
1131)         No passphrase or key was given in the configuration.  In this
1132)         case, the --phrase or --key argument is required.
1133)         """,

1134)         comments='',
1135)         context='error message',
1136)     )
1137)     NO_SSH_AGENT_FOUND = _prepare_translatable(
1138)         'Cannot find any running SSH agent because SSH_AUTH_SOCK is not set.',
1139)         comments='',
1140)         context='error message',
1141)     )

1142)     NO_SUITABLE_SSH_KEYS = _prepare_translatable(
1143)         msg="""
1144)         The SSH agent contains no keys suitable for {PROG_NAME!s}.
1145)         """,  # noqa: RUF027
1146)         comments='',
1147)         context='error message',
1148)         flags='python-brace-format',
1149)     )

1150)     PARAMS_MUTUALLY_EXCLUSIVE = _prepare_translatable(
1151)         comments=r"""
1152)         TRANSLATORS: The params are long-form command-line option names.
1153)         Typical example: "--key is mutually exclusive with --phrase."
1154)         """,
1155)         msg='{param1!s} is mutually exclusive with {param2!s}.',
1156)         context='error message',
1157)         flags='python-brace-format',
1158)     )
1159)     PARAMS_NEEDS_SERVICE_OR_CONFIG = _prepare_translatable(
1160)         comments=r"""
1161)         TRANSLATORS: The param is a long-form command-line option name,

1162)         the metavar is Label.VAULT_METAVAR_SERVICE.

1163)         """,

1164)         msg='{param!s} requires a {service_metavar!s} or --config.',

1165)         context='error message',
1166)         flags='python-brace-format',
1167)     )
1168)     PARAMS_NEEDS_SERVICE = _prepare_translatable(
1169)         comments=r"""
1170)         TRANSLATORS: The param is a long-form command-line option name,

1171)         the metavar is Label.VAULT_METAVAR_SERVICE.

1172)         """,

1173)         msg='{param!s} requires a {service_metavar!s}.',

1174)         context='error message',
1175)         flags='python-brace-format',
1176)     )
1177)     PARAMS_NO_SERVICE = _prepare_translatable(
1178)         comments=r"""
1179)         TRANSLATORS: The param is a long-form command-line option name,

1180)         the metavar is Label.VAULT_METAVAR_SERVICE.

1181)         """,

1182)         msg='{param!s} does not take a {service_metavar!s} argument.',

1183)         context='error message',
1184)         flags='python-brace-format',
1185)     )
1186)     SERVICE_REQUIRED = _prepare_translatable(

1187)         comments=r"""

1188)         TRANSLATORS: The metavar is Label.VAULT_METAVAR_SERVICE.

1189)         """,
1190)         msg='Deriving a passphrase requires a {service_metavar!s}.',
1191)         context='error message',
1192)         flags='python-brace-format',
1193)     )
1194)     SET_AND_UNSET_SAME_SETTING = _prepare_translatable(
1195)         comments=r"""
1196)         TRANSLATORS: The rephrasing "Attempted to unset and set the same
1197)         setting (--unset={setting!s} --{setting!s}=...) at the same
1198)         time." may or may not be more suitable as a basis for
1199)         translation instead.
1200)         """,
1201)         msg='Attempted to unset and set --{setting!s} at the same time.',

1202)         context='error message',

1203)         flags='python-brace-format',

1204)     )
1205)     SSH_KEY_NOT_LOADED = _prepare_translatable(
1206)         'The requested SSH key is not loaded into the agent.',
1207)         comments='',
1208)         context='error message',
1209)     )
1210)     USER_ABORTED_EDIT = _prepare_translatable(

1211)         comments=r"""
1212)         TRANSLATORS: The user requested to edit the notes for a service,
1213)         but aborted the request mid-editing.
1214)         """,
1215)         msg='Not saving any new notes: the user aborted the request.',

1216)         context='error message',
1217)     )
1218)     USER_ABORTED_PASSPHRASE = _prepare_translatable(

1219)         comments=r"""
1220)         TRANSLATORS: The user was prompted for a master passphrase,
1221)         but aborted the request.
1222)         """,
1223)         msg='No passphrase was given; the user aborted the request.',

1224)         context='error message',
1225)     )
1226)     USER_ABORTED_SSH_KEY_SELECTION = _prepare_translatable(

1227)         comments=r"""
1228)         TRANSLATORS: The user was prompted to select a master SSH key,
1229)         but aborted the request.
1230)         """,
1231)         msg='No SSH key was selected; the user aborted the request.',

1232)         context='error message',
1233)     )

1234) 
1235) 

1236) def _write_pot_file(fileobj: TextIO) -> None:  # pragma: no cover

1237)     r"""Write a .po template to the given file object.
1238) 
1239)     Assumes the file object is opened for writing and accepts string
1240)     inputs.  The file will *not* be closed when writing is complete.
1241)     The file *must* be opened in UTF-8 encoding, lest the file will
1242)     declare an incorrect encoding.
1243) 
1244)     This function crucially depends on all translatable strings
1245)     appearing in the enums of this module.  Certain parts of the
1246)     .po header are hard-coded, as is the source filename.
1247) 

1248)     """  # noqa: DOC501

1249)     entries: dict[
1250)         str,
1251)         dict[
1252)             str,
1253)             Label | InfoMsgTemplate | WarnMsgTemplate | ErrMsgTemplate,
1254)         ],
1255)     ] = {}
1256)     for enum_class in (
1257)         Label,
1258)         InfoMsgTemplate,
1259)         WarnMsgTemplate,
1260)         ErrMsgTemplate,
1261)     ):
1262)         for member in enum_class.__members__.values():
1263)             ctx = member.value.l10n_context
1264)             msg = member.value.singular
1265)             if (
1266)                 msg in entries.setdefault(ctx, {})
1267)                 and entries[ctx][msg] != member
1268)             ):

1269)                 raise AssertionError(  # noqa: TRY003

1270)                     f'Duplicate entry for ({ctx!r}, {msg!r}): '  # noqa: EM102
1271)                     f'{entries[ctx][msg]!r} and {member!r}'
1272)                 )
1273)             entries[ctx][msg] = member
1274)     now = datetime.datetime.now().astimezone()
1275)     header = (
1276)         inspect.cleandoc(rf"""
1277)         # English translation for {PROG_NAME!s}.
1278)         # Copyright (C) {now.strftime('%Y')} AUTHOR
1279)         # This file is distributed under the same license as {PROG_NAME!s}.
1280)         # AUTHOR <someone@example.com>, {now.strftime('%Y')}.
1281)         #
1282)         msgid ""
1283)         msgstr ""
1284)         "Project-Id-Version: {PROG_NAME!s} {__version__!s}\n"
1285)         "Report-Msgid-Bugs-To: software@the13thletter.info\n"
1286)         "POT-Creation-Date: {now.strftime('%Y-%m-%d %H:%M%z')}\n"
1287)         "PO-Revision-Date: {now.strftime('%Y-%m-%d %H:%M%z')}\n"
1288)         "Last-Translator: AUTHOR <someone@example.com>\n"
1289)         "Language: en\n"
1290)         "MIME-Version: 1.0\n"
1291)         "Content-Type: text/plain; charset=UTF-8\n"
1292)         "Content-Transfer-Encoding: 8bit\n"
1293)         "Plural-Forms: nplurals=2; plural=(n != 1);\n"
1294)         """).removesuffix('\n')
1295)         + '\n'
1296)     )
1297)     fileobj.write(header)
1298)     for _ctx, subdict in sorted(entries.items()):
1299)         for _msg, enum_value in sorted(
1300)             subdict.items(),
1301)             key=lambda kv: str(kv[1]),
1302)         ):
1303)             fileobj.writelines(_format_po_entry(enum_value))
1304) 
1305) 
1306) def _format_po_entry(
1307)     enum_value: Label | InfoMsgTemplate | WarnMsgTemplate | ErrMsgTemplate,

1308) ) -> tuple[str, ...]:  # pragma: no cover

1309)     ret: list[str] = ['\n']
1310)     ts = enum_value.value
1311)     if ts.translator_comments:
1312)         ret.extend(
1313)             f'#. {line}\n'
1314)             for line in ts.translator_comments.splitlines(False)  # noqa: FBT003
1315)         )
1316)     ret.append(f'#: derivepassphrase/_cli_msg.py:{enum_value}\n')
1317)     if ts.flags:
1318)         ret.append(f'#, {", ".join(sorted(ts.flags))}\n')
1319)     if ts.l10n_context:
1320)         ret.append(f'msgctxt {_cstr(ts.l10n_context)}\n')
1321)     ret.append(f'msgid {_cstr(ts.singular)}\n')
1322)     if ts.plural:
1323)         ret.append(f'msgid_plural {_cstr(ts.plural)}\n')
1324)     ret.append('msgstr ""\n')
1325)     return tuple(ret)
1326) 
1327) 

1328) def _cstr(s: str) -> str:  # pragma: no cover

1329)     def escape(string: str) -> str:
1330)         return string.translate({
1331)             0: r'\000',
1332)             1: r'\001',
1333)             2: r'\002',
1334)             3: r'\003',
1335)             4: r'\004',
1336)             5: r'\005',
1337)             6: r'\006',
1338)             7: r'\007',
1339)             8: r'\b',
1340)             9: r'\t',
1341)             10: r'\n',
1342)             11: r'\013',
1343)             12: r'\f',
1344)             13: r'\r',
1345)             14: r'\016',
1346)             15: r'\017',
1347)             ord('"'): r'\"',
1348)             ord('\\'): r'\\',
1349)             127: r'\177',
1350)         })
1351) 
1352)     return '\n'.join(
1353)         f'"{escape(line)}"'
1354)         for line in s.splitlines(True)  # noqa: FBT003
1355)     )
1356) 
1357) 
1358) if __name__ == '__main__':