Coverage for src / derivepassphrase / _internals / cli_messages.py: 100.000%

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

2# 

3# SPDX-Licence-Identifier: Zlib 

4 

5"""Messages for the command-line interface of `derivepassphrase`. 

6 

7Also contains some machinery related to internationalization and 

8localization. 

9 

10!!! warning 

11 

12 Non-public module (implementation detail), provided for didactical and 

13 educational purposes only. Subject to change without notice, including 

14 removal. 

15 

16""" 

17 

18from __future__ import annotations (empty)

19 

20import contextlib (empty)

21import datetime (empty)

22import enum (empty)

23import functools (empty)

24import gettext (empty)

25import inspect (empty)

26import os (empty)

27import pathlib (empty)

28import string (empty)

29import sys (empty)

30import textwrap (empty)

31import types (empty)

32from typing import TYPE_CHECKING, NamedTuple, Protocol, TextIO, Union, cast (empty)

33 

34from typing_extensions import TypeAlias, override (empty)

35 

36from derivepassphrase import _internals (empty)

37 

38if TYPE_CHECKING: (empty)

39 from collections.abc import Generator, Iterable, Mapping, Sequence 

40 

41 from typing_extensions import Any, Self 

42 

43__all__ = ("PROG_NAME",) (empty)

44 

45PROG_NAME = _internals.PROG_NAME (empty)

46VERSION = _internals.VERSION (empty)

47AUTHOR = _internals.AUTHOR (empty)

48 

49 

50def load_translations( (empty)

51 localedirs: list[str | bytes | os.PathLike] | None = None, (empty)

52 languages: Sequence[str] | None = None, (empty)

53 class_: type[gettext.NullTranslations] | None = None, (empty)

54) -> gettext.NullTranslations: # pragma: no cover [external] (empty)

55 """Load a translation catalog for derivepassphrase. 

56 

57 Runs [`gettext.translation`][] under the hood for multiple locale 

58 directories. `fallback=True` is implied. 

59 

60 Args: 

61 localedirs: 

62 A list of directories to run [`gettext.translation`][] 

63 against. Defaults to `$XDG_DATA_HOME/locale` (usually 

64 `~/.local/share/locale`), `{sys.prefix}/share/locale` and 

65 `{sys.base_prefix}/share/locale` if not given. 

66 languages: 

67 Passed directly to [`gettext.translation`][]. 

68 class_: 

69 Passed directly to [`gettext.translation`][]. 

70 

71 Returns: 

72 A (potentially dummy) translation catalog. 

73 

74 Raises: 

75 RuntimeError: 

76 `APPDATA` (on Windows) or `XDG_DATA_HOME` (otherwise) is not 

77 set. We attempted to compute the default value, but failed 

78 to determine the home directory. 

79 

80 """ 

81 if localedirs is None: (empty)

82 # TODO(the-13th-letter): Define a public (and opaque) enum for these 

83 # special directories so that they are available to callers as well, 

84 # without computation. Shift the computation into a separate 

85 # top-level function, so that it can be stubbed during tests. 

86 # Support the `.../site-packages/share/locale` special directory via 

87 # a new enum value, because that is where the derivepassphrase wheel 

88 # stores its packaged translations. Then reimplement `gettext.find` 

89 # and `gettext.translation` with support for `importlib.resources`. 

90 # The heavy lifting is already being done by `locale.normalize`. 

91 if sys.platform.startswith("win"): (empty)

92 xdg_data_home = ( (empty)

93 pathlib.Path(os.environ["APPDATA"]) (empty)

94 if os.environ.get("APPDATA") (empty)

95 else pathlib.Path("~").expanduser() 

96 ) 

97 elif os.environ.get("XDG_DATA_HOME"): (empty)

98 xdg_data_home = pathlib.Path(os.environ["XDG_DATA_HOME"]) 

99 else: 

100 xdg_data_home = ( (empty)

101 pathlib.Path("~").expanduser() / ".local" / ".share" (empty)

102 ) 

103 localedirs = [ (empty)

104 pathlib.Path(xdg_data_home, "locale"), (empty)

105 pathlib.Path(sys.prefix, "share", "locale"), (empty)

106 pathlib.Path(sys.base_prefix, "share", "locale"), (empty)

107 ] 

108 for localedir in localedirs: (empty)

109 with contextlib.suppress(OSError): (empty)

110 return gettext.translation( (empty)

111 PROG_NAME, (empty)

112 localedir=os.fsdecode(localedir), (empty)

113 languages=languages, (empty)

114 class_=class_, (empty)

115 ) 

116 return gettext.NullTranslations() (empty)

117 

118 

119translation = load_translations() (empty)

120_debug_translation_message_cache: dict[ (empty)

121 tuple[str, str], 

122 tuple[MsgTemplate, frozenset], 

123] = {} 

124 

125 

126class DebugTranslations(gettext.NullTranslations): (empty)

127 """A debug object indicating which known message is being requested. 

128 

129 Each call to the `*gettext` methods will return the enum name if the 

130 message is a known translatable message for the `derivepassphrase` 

131 command-line interface, or the message itself otherwise. 

132 

133 """ 

134 

135 @staticmethod (empty)

136 def _load_cache() -> None: (empty)

137 cache = _debug_translation_message_cache (empty)

138 for enum_class in MSG_TEMPLATE_CLASSES: (empty)

139 for member in enum_class.__members__.values(): (empty)

140 value = member.value (empty)

141 queue: list[tuple[TranslatableString, frozenset[str]]] = [ (empty)

142 (value, frozenset()) 

143 ] 

144 value2 = value.maybe_without_filename() (empty)

145 if value != value2: (empty)

146 queue.append((value2, frozenset({"filename"}))) (empty)

147 for v, trimmed in queue: (empty)

148 singular = v.singular (empty)

149 plural = v.plural (empty)

150 context = v.l10n_context (empty)

151 cache.setdefault((context, singular), (member, trimmed)) (empty)

152 if plural: # pragma: no cover [unused] (empty)

153 cache.setdefault((context, plural), (member, trimmed)) 

154 

155 @classmethod (empty)

156 def _locate_message( (empty)

157 cls, 

158 message: str, 

159 /, 

160 *, 

161 context: str = "", 

162 message_plural: str = "", 

163 n: int = 1, 

164 ) -> str: 

165 try: 6 ctx2B rbC x r b

166 enum_value, trimmed = _debug_translation_message_cache[ 6 ctx2B rbC x r b

167 context, message 

168 ] 

169 except KeyError: 2 ctx2rbx

170 return message if not message_plural or n == 1 else message_plural 2 ctx2rbx

171 return cls._format_enum_name_maybe_with_fields( 4 ctx1BCrb

172 enum_name=str(enum_value), 

173 ts=enum_value.value, 

174 trimmed=trimmed, 

175 ) 

176 

177 @staticmethod (empty)

178 def _format_enum_name_maybe_with_fields( (empty)

179 enum_name: str, 

180 ts: TranslatableString, 

181 trimmed: frozenset[str] = frozenset(), 

182 ) -> str: 

183 formatted_fields = [ 4 ctx1BCrb

184 f"{f}=None" if f in trimmed else f"{f}={{{f}!r}}" 

185 for f in ts.fields() 

186 ] 

187 return ( 4 ctx1BCrb

188 "{}({})".format(enum_name, ", ".join(formatted_fields)) 

189 if formatted_fields 

190 else str(enum_name) 

191 ) 

192 

193 @override (empty)

194 def gettext( (empty)

195 self, 

196 message: str, 

197 ) -> str: 

198 return self._locate_message(message) 2 ctx2rbx

199 

200 @override (empty)

201 def ngettext( (empty)

202 self, 

203 msgid1: str, (empty)

204 msgid2: str, (empty)

205 n: int, (empty)

206 ) -> str: # pragma: no cover [unused] (empty)

207 """""" # noqa: D419 

208 return self._locate_message(msgid1, message_plural=msgid2, n=n) 

209 

210 @override (empty)

211 def pgettext( (empty)

212 self, 

213 context: str, 

214 message: str, 

215 ) -> str: 

216 return self._locate_message(message, context=context) 4 ctx1BCrb

217 

218 @override (empty)

219 def npgettext( (empty)

220 self, 

221 context: str, (empty)

222 msgid1: str, (empty)

223 msgid2: str, (empty)

224 n: int, (empty)

225 ) -> str: # pragma: no cover [unused] (empty)

226 """""" # noqa: D419 

227 return self._locate_message( 

228 msgid1, 

229 context=context, 

230 message_plural=msgid2, 

231 n=n, 

232 ) 

233 

234 

235class TranslatableString(NamedTuple): (empty)

236 """Translatable string as used by the `derivepassphrase` command-line. 

237 

238 For typing purposes. 

239 

240 Attributes: 

241 l10n_context: 

242 The localization context, as per [`gettext`][]. Used to 

243 disambiguate different uses of the same translatable string. 

244 singular: 

245 The translatable message, base case. 

246 plural: 

247 The translatable message, plural case. Usually unset. 

248 translator_comments: 

249 Explicit commentary for the translator. 

250 flags: 

251 `.mo` file flags for this message, e.g. to indicate the 

252 string formatting style in use. 

253 

254 """ 

255 

256 l10n_context: str (empty)

257 """""" (empty)

258 singular: str (empty)

259 """""" (empty)

260 plural: str = "" (empty)

261 """""" (empty)

262 flags: frozenset[str] = frozenset() (empty)

263 """""" (empty)

264 translator_comments: str = "" (empty)

265 """""" (empty)

266 

267 def fields(self) -> list[str]: (empty)

268 """Return the replacement fields this template requires. 

269 

270 Raises: 

271 NotImplementedError: 

272 Replacement field discovery for %-formatting is not 

273 implemented. 

274 

275 """ 

276 if "python-format" in self.flags: # pragma: no cover [unused] 5 ctx1aBCrb

277 err_msg = ( 

278 "Replacement field discovery for %-formatting " 

279 "is not implemented" 

280 ) 

281 raise NotImplementedError(err_msg) 

282 if ( 5 ctx1aBCrb

283 "no-python-brace-format" in self.flags 

284 or "python-brace-format" not in self.flags 

285 ): 

286 return [] 4 ctx1aBCr

287 formatter = string.Formatter() 4 ctx1aBCb

288 fields: dict[str, int] = {} 4 ctx1aBCb

289 for _lit, field, _spec, _conv in formatter.parse(self.singular): 4 ctx1aBCb

290 if field is not None and field not in fields: 4 ctx1aBCb

291 fields[field] = len(fields) 4 ctx1aBCb

292 return sorted(fields, key=fields.__getitem__) 4 ctx1aBCb

293 

294 @staticmethod (empty)

295 def _maybe_rewrap( (empty)

296 string: str, 

297 /, 

298 *, 

299 fix_sentence_endings: bool = True, 

300 ) -> str: 

301 string = inspect.cleandoc(string) (empty)

302 if not any(s.strip() == "\b" for s in string.splitlines()): (empty)

303 string = "\n".join( (empty)

304 textwrap.wrap( 

305 string, 

306 width=float("inf"), # type: ignore[arg-type] 

307 fix_sentence_endings=fix_sentence_endings, 

308 ) 

309 ) 

310 else: 

311 string = "".join( (empty)

312 s 

313 for s in string.splitlines(True) # noqa: FBT003 

314 if s.strip() != "\b" 

315 ) 

316 return string (empty)

317 

318 def maybe_without_filename(self) -> Self: (empty)

319 """Return a new translatable string without the "filename" field. 

320 

321 Only acts upon translatable strings containing the exact 

322 contents `": {filename!r}"`. The specified part will be 

323 removed. This is correct usage in English for messages like 

324 `"Cannot open file: {error}: {filename!r}."`, but not 

325 necessarily in other languages. 

326 

327 """ 

328 filename_str = ": {filename!r}" 22 ctx1adefgshijklmnopqvtwubc

329 ret = self 22 ctx1adefgshijklmnopqvtwubc

330 a, sep1, b = self.singular.partition(filename_str) 22 ctx1adefgshijklmnopqvtwubc

331 c, sep2, d = self.plural.partition(filename_str) 22 ctx1adefgshijklmnopqvtwubc

332 if sep1: 22 ctx1adefgshijklmnopqvtwubc

333 ret = ret._replace(singular=(a + b)) 20 ctx1adefgshijklmnopqtubc

334 if sep2: # pragma: no cover [unused] 22 ctx1adefgshijklmnopqvtwubc

335 ret = ret._replace(plural=(c + d)) 

336 return ret 22 ctx1adefgshijklmnopqvtwubc

337 

338 def rewrapped(self) -> Self: (empty)

339 """Return a rewrapped version of self. 

340 

341 Normalizes all parts assumed to contain English prose. 

342 

343 """ 

344 msg = self._maybe_rewrap(self.singular, fix_sentence_endings=True) (empty)

345 plural = self._maybe_rewrap(self.plural, fix_sentence_endings=True) (empty)

346 context = self.l10n_context.strip() (empty)

347 comments = self._maybe_rewrap( (empty)

348 self.translator_comments, fix_sentence_endings=False 

349 ) 

350 return self._replace( (empty)

351 singular=msg, 

352 plural=plural, 

353 l10n_context=context, 

354 translator_comments=comments, 

355 ) 

356 

357 def with_comments(self, comments: str, /) -> Self: (empty)

358 """Add or replace the string's translator comments. 

359 

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

361 normalized. 

362 

363 Returns: 

364 A new [`TranslatableString`][] with the specified comments. 

365 

366 """ 

367 if comments.strip() and not comments.lstrip().startswith( (empty)

368 "TRANSLATORS:" 

369 ): # pragma: no cover [unused] 

370 comments = "TRANSLATORS: " + comments.lstrip() (empty)

371 comments = self._maybe_rewrap(comments, fix_sentence_endings=False) (empty)

372 return self._replace(translator_comments=comments) (empty)

373 

374 def validate_flags(self, *extra_flags: str) -> Self: (empty)

375 """Add all flags, then validate them against the string. 

376 

377 Returns: 

378 A new [`TranslatableString`][] with the extra flags added, 

379 and all flags validated. 

380 

381 Raises: 

382 ValueError: 

383 The flags failed to validate. See the exact error 

384 message for details. 

385 

386 Examples: 

387 >>> TranslatableString("", "all OK").validate_flags() 

388 ... # doctest: +NORMALIZE_WHITESPACE 

389 TranslatableString(l10n_context='', singular='all OK', plural='', 

390 flags=frozenset(), translator_comments='') 

391 >>> TranslatableString("", "20% OK").validate_flags( 

392 ... "no-python-format" 

393 ... ) 

394 ... # doctest: +NORMALIZE_WHITESPACE 

395 TranslatableString(l10n_context='', singular='20% OK', plural='', 

396 flags=frozenset({'no-python-format'}), 

397 translator_comments='') 

398 >>> TranslatableString("", "%d items").validate_flags() 

399 ... # doctest: +ELLIPSIS 

400 Traceback (most recent call last): 

401 ... 

402 ValueError: Missing flag for how to deal with percent character ... 

403 >>> TranslatableString("", "{braces}").validate_flags() 

404 ... # doctest: +ELLIPSIS 

405 Traceback (most recent call last): 

406 ... 

407 ValueError: Missing flag for how to deal with brace character ... 

408 >>> TranslatableString("", "no braces").validate_flags( 

409 ... "python-brace-format" 

410 ... ) 

411 ... # doctest: +ELLIPSIS 

412 Traceback (most recent call last): 

413 ... 

414 ValueError: Missing format string parameters ... 

415 

416 """ 

417 all_flags = frozenset(f.strip() for f in self.flags.union(extra_flags)) (empty)

418 if "{" in self.singular and not bool( (empty)

419 all_flags & {"python-brace-format", "no-python-brace-format"} 

420 ): 

421 msg = ( (empty)

422 f"Missing flag for how to deal with brace character " 

423 f"in {self.singular!r}" 

424 ) 

425 raise ValueError(msg) (empty)

426 if "%" in self.singular and not bool( (empty)

427 all_flags & {"python-format", "no-python-format"} 

428 ): 

429 msg = ( (empty)

430 f"Missing flag for how to deal with percent character " 

431 f"in {self.singular!r}" 

432 ) 

433 raise ValueError(msg) (empty)

434 if ( (empty)

435 all_flags & {"python-format", "python-brace-format"} 

436 and "%" not in self.singular 

437 and "{" not in self.singular 

438 ): 

439 msg = f"Missing format string parameters in {self.singular!r}" (empty)

440 raise ValueError(msg) (empty)

441 return self._replace(flags=all_flags) (empty)

442 

443 

444def translatable( (empty)

445 context: str, 

446 single: str, 

447 /, 

448 flags: Iterable[str] = (), 

449 plural: str = "", 

450 comments: str = "", 

451) -> TranslatableString: 

452 """Return a [`TranslatableString`][] with validated parts. 

453 

454 This factory function is really only there to make the enum 

455 definitions more readable. It is the main implementation of the 

456 [`TranslatableStringConstructor`][]. 

457 

458 """ 

459 flags = ( (empty)

460 frozenset(flags) if not isinstance(flags, str) else frozenset({flags}) 

461 ) 

462 return ( (empty)

463 TranslatableString(context, single, plural=plural, flags=flags) 

464 .rewrapped() 

465 .with_comments(comments) 

466 .validate_flags() 

467 ) 

468 

469 

470class TranslatedString: (empty)

471 """A string object that stringifies to its translation. 

472 

473 The translation and replacement value rendering is only performed 

474 when this string object is actually stringified. 

475 

476 """ 

477 

478 def __init__( (empty)

479 self, 

480 template: str | TranslatableString | MsgTemplate, 

481 args_dict: Mapping[str, Any] = types.MappingProxyType({}), 

482 /, 

483 **kwargs: Any, # noqa: ANN401 

484 ) -> None: 

485 """Initializer. 

486 

487 Args: 

488 template: 

489 A template string, suitable for [`str.format`][]. If 

490 a string, use it directly. If 

491 a [`TranslatableString`][], or a known enum value whose 

492 value is a `TranslatableString`, then use that string's 

493 "singular" entry. 

494 args_dict: 

495 Keyword arguments to be passed to [`str.format`][]. 

496 kwargs: 

497 More keyword arguments to be passed to [`str.format`][]. 

498 

499 """ 

500 # The cast is still needed for mypy. For this use case -- 

501 # multiple related enums, all values of which share the same 

502 # type, even across enums -- mypy's type inference is 

503 # frustratingly surface-level. 

504 # 

505 # pyrefly: ignore [redundant-cast] 

506 self.template = cast( 110 ctx2a D d E F e f ^ G H I _ ` { | tbubvbJ wb} ~ abK L M g s N xbO P Q R S T U V W sbX Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

507 "str | TranslatableString", 

508 template.value 

509 if isinstance(template, MSG_TEMPLATE_CLASSES) 

510 else template, 

511 ) 

512 self.kwargs = {**args_dict, **kwargs} 110 ctx2a D d E F e f ^ G H I _ ` { | tbubvbJ wb} ~ abK L M g s N xbO P Q R S T U V W sbX Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

513 self._rendered: str | None = None 110 ctx2a D d E F e f ^ G H I _ ` { | tbubvbJ wb} ~ abK L M g s N xbO P Q R S T U V W sbX Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

514 

515 def __bool__(self) -> bool: (empty)

516 """Return true if the rendered string is truthy.""" 

517 return bool(str(self)) 3 ctx1HIU

518 

519 def __eq__(self, other: object) -> bool: # pragma: no cover [debug] (empty)

520 """Return true if the rendered string is equal to `other`.""" 

521 return str(self) == other 3 ctx1rbc

522 

523 def __hash__(self) -> int: # pragma: no cover [debug] (empty)

524 """Return the hash of the rendered string.""" 

525 return hash(str(self)) 69 ctx2a D d E F e f G J K L M g N O P Q R S T V W X Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ r b c

526 

527 def __repr__(self) -> str: # pragma: no cover [debug] (empty)

528 """""" # noqa: D419 

529 return ( 

530 f"{self.__class__.__name__}({self.template!r}, " 

531 f"{dict(self.kwargs)!r})" 

532 ) 

533 

534 def __str__(self) -> str: (empty)

535 """Return the rendered translation of this string. 

536 

537 First, look up the translation of the string's template. Then 

538 fill in the replacement fields. Cache the result for future 

539 calls. 

540 

541 """ 

542 if self._rendered is None: 105 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W sbX Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

543 do_escape = False 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

544 if isinstance(self.template, str): 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

545 context = "" 6 ctx2y z A [ x nb

546 template = self.template 6 ctx2y z A [ x nb

547 else: 

548 context = self.template.l10n_context 98 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmbr b c ]

549 template = self.template.singular 98 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmbr b c ]

550 do_escape = "no-python-brace-format" in self.template.flags 98 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmbr b c ]

551 template = ( 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

552 translation.pgettext(context, template) 

553 if context 

554 else translation.gettext(template) 

555 ) 

556 template = self._escape(template) if do_escape else template 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

557 kwargs = { 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

558 k: str(v) if isinstance(v, TranslatedString) else v 

559 for k, v in self.kwargs.items() 

560 } 

561 self._rendered = template.format(**kwargs) 101 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 h i j k 7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

562 return self._rendered 105 ctx2a D d E F e f ^ G H I _ ` { | J } ~ abK L M g s N O P Q R S T U V W sbX Y Z 0 1 2 3 obpb4 5 6 h i j k qb7 l m 8 9 n o ! # p q $ % ' ( ) * + , - . / : ; = ? @ v t bbw u cby dbebfbz A gbhbibjbkblbmb[ x r b c nb]

563 

564 @staticmethod (empty)

565 def _escape(template: str) -> str: (empty)

566 return template.translate({ 3 ctx1[x]

567 ord("{"): "{{", 

568 ord("}"): "}}", 

569 }) 

570 

571 @classmethod (empty)

572 def constant(cls, template: str) -> Self: (empty)

573 return cls(cls._escape(template)) 2 ctx1[x

574 

575 def maybe_without_filename(self) -> Self: (empty)

576 """Return a new string without the "filename" field. 

577 

578 Only acts upon translated strings containing the exact contents 

579 `": {filename!r}"`. The specified part will be removed. This 

580 acts upon the string *before* translation, i.e., the string 

581 without the filename will be used as a translation base. 

582 

583 """ 

584 new_template = ( 21 ctx1defgshijklmnopqvtwubc

585 self.template.maybe_without_filename() 

586 if not isinstance(self.template, str) 

587 else self.template 

588 ) 

589 if ( 21 ctx1defgshijklmnopqvtwubc

590 not isinstance(new_template, str) 

591 and self.kwargs.get("filename") is None 

592 and new_template != self.template 

593 ): 

594 return self.__class__(new_template, self.kwargs) 7 ctx1dehmpbc

595 return self 14 ctx1fgsijklnoqvtwu

596 

597 

598class TranslatableStringConstructor(Protocol): (empty)

599 """Construct a [`TranslatableString`][].""" (empty)

600 

601 def __call__( (empty)

602 self, 

603 context: str, (empty)

604 single: str, (empty)

605 /, 

606 flags: Iterable[str] = (), (empty)

607 plural: str = "", (empty)

608 comments: str = "", (empty)

609 ) -> TranslatableString: (empty)

610 """Return a [`TranslatableString`][] from these parts. 

611 

612 Usually some form of validation or normalization is performed 

613 first on these parts. 

614 

615 The main implementation of this is in [`translatable`][]. 

616 

617 """ 

618 

619 

620def commented(comments: str = "", /) -> TranslatableStringConstructor: (empty)

621 """A "decorator" for readably constructing commented enum values. 

622 

623 Returns a partial application of [`translatable`][] with the `comments` 

624 argument pre-filled. 

625 

626 This is geared towards the quirks of the API documentation extractor 

627 `mkdocstrings-python`/`griffe`, which reformat and trim enum value 

628 declarations in predictable but somewhat weird ways. Chains of function 

629 calls are preserved, though, so use this to our advantage to suggest 

630 a specific formatting. 

631 

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

633 solution. 

634 

635 """ # noqa: DOC201 

636 return functools.partial(translatable, comments=comments) (empty)

637 

638 

639class Label(enum.Enum): (empty)

640 """Labels for the `derivepassphrase` command-line. 

641 

642 Includes help text (long-form and short-form), help metavar names, 

643 diagnostic labels and interactive prompts. 

644 

645 """ 

646 

647 DEPRECATION_WARNING_LABEL = commented( (empty)

648 "This is a short label that will be prepended to " 

649 'a warning message, e.g., "Deprecation warning: A subcommand ' 

650 'will be required in v1.0."', 

651 )( 

652 "Label :: Diagnostics :: Marker", 

653 "Deprecation warning", 

654 ) 

655 """""" (empty)

656 WARNING_LABEL = commented( (empty)

657 "This is a short label that will be prepended to " 

658 'a warning message, e.g., "Warning: An empty service name ' 

659 'is not supported by vault(1)."', 

660 )( 

661 "Label :: Diagnostics :: Marker", 

662 "Warning", 

663 ) 

664 """""" (empty)

665 CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL = commented( (empty)

666 "This is one of two values of the settings_type metavar " 

667 "used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry. " 

668 "It is only used there. " 

669 "The full sentence then reads: " 

670 '"Cannot update the global settings without any given settings."', 

671 )( 

672 "Label :: Error message :: Metavar", 

673 "global settings", 

674 ) 

675 """""" (empty)

676 CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE = commented( (empty)

677 "This is one of two values of the settings_type metavar " 

678 "used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry. " 

679 "It is only used there. " 

680 "The full sentence then reads: " 

681 '"Cannot update the service-specific settings without any ' 

682 'given settings."', 

683 )( 

684 "Label :: Error message :: Metavar", 

685 "service-specific settings", 

686 ) 

687 """""" (empty)

688 SETTINGS_ORIGIN_INTERACTIVE = commented( (empty)

689 "This value is used as the {key} metavar for " 

690 "Label.PASSPHRASE_NOT_NORMALIZED if the passphrase was " 

691 "entered interactively.", 

692 )( 

693 "Label :: Error message :: Metavar", 

694 "interactive input", 

695 ) 

696 CONFIGURATION_EPILOG = commented( (empty)

697 "", 

698 )( 

699 "Label :: Help text :: Explanation", 

700 "Use $VISUAL or $EDITOR to configure the spawned editor.", 

701 ) 

702 """""" (empty)

703 DERIVEPASSPHRASE_02 = commented( (empty)

704 "", 

705 )( 

706 "Label :: Help text :: Explanation", 

707 'The currently implemented subcommands are "vault" ' 

708 '(for the scheme used by vault) and "export" ' 

709 "(for exporting foreign configuration data). " 

710 "See the respective `--help` output for instructions. " 

711 'If no subcommand is given, we default to "vault".', 

712 ) 

713 """""" (empty)

714 DERIVEPASSPHRASE_03 = commented( (empty)

715 "", 

716 )( 

717 "Label :: Help text :: Explanation", 

718 'Deprecation notice: Defaulting to "vault" is deprecated. ' 

719 "Starting in v1.0, the subcommand must be specified explicitly.", 

720 ) 

721 """""" (empty)

722 DERIVEPASSPHRASE_EPILOG_01 = commented( (empty)

723 "", 

724 )( 

725 "Label :: Help text :: Explanation", 

726 "Configuration is stored in a directory according to the " 

727 "`DERIVEPASSPHRASE_PATH` variable, which defaults to " 

728 "`~/.derivepassphrase` on UNIX-like systems and " 

729 r"`C:\Users\<user>\AppData\Roaming\Derivepassphrase` on Windows.", 

730 ) 

731 """""" (empty)

732 DERIVEPASSPHRASE_EXPORT_02 = commented( (empty)

733 "", 

734 )( 

735 "Label :: Help text :: Explanation", 

736 'The only available subcommand is "vault", ' 

737 "which implements the vault-native configuration scheme. " 

738 'If no subcommand is given, we default to "vault".', 

739 ) 

740 """""" (empty)

741 DERIVEPASSPHRASE_EXPORT_03 = DERIVEPASSPHRASE_03 (empty)

742 """""" (empty)

743 DERIVEPASSPHRASE_EXPORT_VAULT_02 = commented( (empty)

744 "The metavar is Label.EXPORT_VAULT_METAVAR_PATH.", 

745 )( 

746 "Label :: Help text :: Explanation", 

747 "Depending on the configuration format, " 

748 "{path_metavar} may either be a file or a directory. " 

749 'We support the vault "v0.2", "v0.3" and "storeroom" formats.', 

750 flags="python-brace-format", 

751 ) 

752 """""" (empty)

753 DERIVEPASSPHRASE_EXPORT_VAULT_03 = commented( (empty)

754 "The metavar is Label.EXPORT_VAULT_METAVAR_PATH.", 

755 )( 

756 "Label :: Help text :: Explanation", 

757 "If {path_metavar} is explicitly given as `VAULT_PATH`, " 

758 "then use the `VAULT_PATH` environment variable to " 

759 "determine the correct path. " 

760 "(Use `./VAULT_PATH` or similar to indicate a file/directory " 

761 "actually named `VAULT_PATH`.)", 

762 flags="python-brace-format", 

763 ) 

764 """""" (empty)

765 DERIVEPASSPHRASE_VAULT_02 = commented( (empty)

766 "The metavar is Label.VAULT_METAVAR_SERVICE.", 

767 )( 

768 "Label :: Help text :: Explanation", 

769 "If operating on global settings, or importing/exporting settings, " 

770 "then {service_metavar} must be omitted. " 

771 "Otherwise it is required.", 

772 flags="python-brace-format", 

773 ) 

774 """""" (empty)

775 DERIVEPASSPHRASE_VAULT_EPILOG_01 = commented( (empty)

776 "", 

777 )( 

778 "Label :: Help text :: Explanation", 

779 "WARNING: There is NO WAY to retrieve the generated passphrases " 

780 "if the master passphrase, the SSH key, or the exact " 

781 "passphrase settings are lost, " 

782 "short of trying out all possible combinations. " 

783 "You are STRONGLY advised to keep independent backups of " 

784 "the settings and the SSH key, if any.", 

785 ) 

786 """""" (empty)

787 DERIVEPASSPHRASE_VAULT_EPILOG_02 = commented( (empty)

788 "", 

789 )( 

790 "Label :: Help text :: Explanation", 

791 "The configuration is NOT encrypted, and you are " 

792 "STRONGLY discouraged from using a stored passphrase.", 

793 ) 

794 """""" (empty)

795 DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT = commented( (empty)

796 "This instruction text is shown above the user's old stored notes " 

797 "for this service, if any, if the recommended " 

798 '"modern" editor interface is used. ' 

799 "The next line is the cut marking defined in " 

800 "Label.DERIVEPASSPHRASE_VAULT_NOTES_MARKER." 

801 )( 

802 "Label :: Help text :: Explanation", 

803 """\ 

804\b 

805# Enter notes below the line with the cut mark (ASCII scissors and 

806# dashes). Lines above the cut mark (such as this one) will be ignored. 

807# 

808# If you wish to clear the notes, leave everything beyond the cut mark 

809# blank. However, if you leave the *entire* file blank, also removing 

810# the cut mark, then the edit is aborted, and the old notes contents are 

811# retained. 

812# 

813""", 

814 ) 

815 """""" (empty)

816 DERIVEPASSPHRASE_VAULT_NOTES_LEGACY_INSTRUCTION_TEXT = commented( (empty)

817 "This instruction text is shown if the vault(1)-compatible " 

818 '"legacy" editor interface is used and no previous notes exist. ' 

819 "The interface does not support commentary in the notes, " 

820 "so we fill this with obvious placeholder text instead. " 

821 "(Please replace this with what *your* language/culture would " 

822 "obviously recognize as placeholder text.)" 

823 )( 

824 "Label :: Help text :: Explanation", 

825 "INSERT NOTES HERE", 

826 ) 

827 """""" (empty)

828 PASSPHRASE_GENERATION_EPILOG = commented( (empty)

829 "The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.", 

830 )( 

831 "Label :: Help text :: Explanation", 

832 "Use {metavar}=0 to exclude a character type from the output.", 

833 flags="python-brace-format", 

834 ) 

835 """""" (empty)

836 STORAGE_MANAGEMENT_EPILOG = commented( (empty)

837 "The metavar is Label.STORAGE_MANAGEMENT_METAVAR_PATH.", 

838 )( 

839 "Label :: Help text :: Explanation", 

840 'Using "-" as {metavar} for standard input/standard output ' 

841 "is supported.", 

842 flags="python-brace-format", 

843 ) 

844 """""" (empty)

845 DEPRECATED_COMMAND_LABEL = commented( (empty)

846 "We use this format string to indicate, at the beginning " 

847 "of a command's help text, that this command is deprecated.", 

848 )( 

849 "Label :: Help text :: Marker", 

850 "(Deprecated) {text}", 

851 flags="python-brace-format", 

852 ) 

853 """""" (empty)

854 DERIVEPASSPHRASE_VAULT_NOTES_MARKER = commented( (empty)

855 "The marker for separating the text from " 

856 "Label.DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT " 

857 "from the user's input (below the marker). " 

858 "The first line starting with this label marks the separation point.", 

859 )( 

860 "Label :: Help text :: Marker", 

861 "# - - - - - >8 - - - - - >8 - - - - - >8 - - - - - >8 - - - - -", 

862 ) 

863 """""" (empty)

864 EXPORT_VAULT_FORMAT_METAVAR_FMT = commented( (empty)

865 "This text is used as {metavar} in " 

866 "Label.EXPORT_VAULT_FORMAT_HELP_TEXT, yielding e.g. " 

867 '"Try the following storage format FMT."', 

868 )( 

869 "Label :: Help text :: Metavar :: export vault", 

870 "FMT", 

871 ) 

872 """""" (empty)

873 EXPORT_VAULT_KEY_METAVAR_K = commented( (empty)

874 "This text is used as {metavar} in " 

875 "Label.EXPORT_VAULT_KEY_HELP_TEXT, yielding e.g. " 

876 '"Use K as the storage master key."', 

877 )( 

878 "Label :: Help text :: Metavar :: export vault", 

879 "K", 

880 ) 

881 """""" (empty)

882 EXPORT_VAULT_METAVAR_PATH = commented( (empty)

883 'Used as "path_metavar" in ' 

884 "Label.DERIVEPASSPHRASE_EXPORT_VAULT_02 and others, " 

885 'yielding e.g. "Depending on the configuration format, ' 

886 'PATH may either be a file or a directory."', 

887 )( 

888 "Label :: Help text :: Metavar :: export vault", 

889 "PATH", 

890 ) 

891 """""" (empty)

892 PASSPHRASE_GENERATION_METAVAR_NUMBER = commented( (empty)

893 "This metavar is used in Label.PASSPHRASE_GENERATION_EPILOG, " 

894 "Label.DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT and others, " 

895 'yielding e.g. "Ensure a passphrase length of NUMBER characters.". ', 

896 )( 

897 "Label :: Help text :: Metavar :: vault", 

898 "NUMBER", 

899 ) 

900 """""" (empty)

901 STORAGE_MANAGEMENT_METAVAR_PATH = commented( (empty)

902 "This metavar is used in Label.STORAGE_MANAGEMENT_EPILOG, " 

903 "Label.DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT and others, " 

904 'yielding e.g. "Ensure a passphrase length of NUMBER characters.". ', 

905 )( 

906 "Label :: Help text :: Metavar :: vault", 

907 "PATH", 

908 ) 

909 """""" (empty)

910 VAULT_COMPATIBILITY_METAVAR_SSH_AGENT_SOCKET_PROVIDER = commented( (empty)

911 "This metavar is used in " 

912 "Label.DERIVEPASSPHRASE_VAULT_SSH_AGENT_SOCKET_PROVIDER_HELP_TEXT, " 

913 'yielding e.g. "Use PROVIDER as the SSH agent socket provider.". ', 

914 )( 

915 "Label :: Help text :: Metavar :: vault", 

916 "PROVIDER", 

917 ) 

918 """""" (empty)

919 VAULT_METAVAR_SERVICE = commented( (empty)

920 'This metavar is used as "service_metavar" in multiple help texts, ' 

921 "such as Label.DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT, " 

922 "Label.DERIVEPASSPHRASE_VAULT_02, ErrMsgTemplate.SERVICE_REQUIRED, " 

923 'etc. Sample texts are "Deriving a passphrase requires a SERVICE.", ' 

924 '"save the given settings for SERVICE, or global" and ' 

925 '"If operating on global settings, or importing/exporting settings, ' 

926 'then SERVICE must be omitted."', 

927 )( 

928 "Label :: Help text :: Metavar :: vault", 

929 "SERVICE", 

930 ) 

931 """""" (empty)

932 DEBUG_OPTION_HELP_TEXT = commented( (empty)

933 "", 

934 )( 

935 "Label :: Help text :: One-line description", 

936 "Also emit debug information. Implies --verbose.", 

937 ) 

938 """""" (empty)

939 DERIVEPASSPHRASE_01 = commented( (empty)

940 "This is the first paragraph of the command help text, " 

941 "but it also appears (in truncated form, if necessary) " 

942 "as one-line help text for this command. " 

943 "The translation should thus be as meaningful as possible " 

944 "even if truncated.", 

945 )( 

946 "Label :: Help text :: One-line description", 

947 "Derive a strong passphrase, deterministically, from a master secret.", 

948 ) 

949 """""" (empty)

950 DERIVEPASSPHRASE_EXPORT_01 = commented( (empty)

951 "This is the first paragraph of the command help text, " 

952 "but it also appears (in truncated form, if necessary) " 

953 "as one-line help text for this command. " 

954 "The translation should thus be as meaningful as possible " 

955 "even if truncated.", 

956 )( 

957 "Label :: Help text :: One-line description", 

958 "Export a foreign configuration to standard output.", 

959 ) 

960 """""" (empty)