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

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

2# 

3# SPDX-Licence-Identifier: MIT 

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 Iterable, Iterator, 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 (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 # This function deals completely with external resources that are 

82 # hard to mock for testing, and thus is exempt from coverage. 

83 if localedirs is None: (empty)

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

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

86 # without computation. Shift the computation into a separate 

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

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

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

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

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

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

93 if sys.platform.startswith('win'): (empty)

94 xdg_data_home = ( (empty)

95 pathlib.Path(os.environ['APPDATA']) (empty)

96 if os.environ.get('APPDATA') (empty)

97 else pathlib.Path('~').expanduser() 

98 ) 

99 elif os.environ.get('XDG_DATA_HOME'): 

100 xdg_data_home = pathlib.Path(os.environ['XDG_DATA_HOME']) 

101 else: 

102 xdg_data_home = ( 

103 pathlib.Path('~').expanduser() / '.local' / '.share' 

104 ) 

105 localedirs = [ (empty)

106 pathlib.Path(xdg_data_home, 'locale'), (empty)

107 pathlib.Path(sys.prefix, 'share', 'locale'), (empty)

108 pathlib.Path(sys.base_prefix, 'share', 'locale'), (empty)

109 ] 

110 for localedir in localedirs: (empty)

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

112 return gettext.translation( (empty)

113 PROG_NAME, (empty)

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

115 languages=languages, (empty)

116 class_=class_, (empty)

117 ) 

118 return gettext.NullTranslations() (empty)

119 

120 

121translation = load_translations() (empty)

122_debug_translation_message_cache: dict[ (empty)

123 tuple[str, str], 

124 tuple[MsgTemplate, frozenset], 

125] = {} 

126 

127 

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

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

130 

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

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

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

134 

135 """ 

136 

137 @staticmethod (empty)

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

139 cache = _debug_translation_message_cache (empty)

140 for enum_class in MSG_TEMPLATE_CLASSES: (empty)

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

142 value = cast('TranslatableString', member.value) (empty)

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

144 (value, frozenset()) 

145 ] 

146 value2 = value.maybe_without_filename() (empty)

147 if value != value2: (empty)

148 queue.append((value2, frozenset({'filename'}))) (empty)

149 for v, trimmed in queue: (empty)

150 singular = v.singular (empty)

151 plural = v.plural (empty)

152 context = v.l10n_context (empty)

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

154 # Currently no translatable messages use plural forms 

155 if plural: # pragma: no cover (empty)

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

157 

158 @classmethod (empty)

159 def _locate_message( (empty)

160 cls, 

161 message: str, 

162 /, 

163 *, 

164 context: str = '', 

165 message_plural: str = '', 

166 n: int = 1, 

167 ) -> str: 

168 try: 6 ctx2qb} ~ x r b

169 enum_value, trimmed = _debug_translation_message_cache[ 6 ctx2qb} ~ x r b

170 context, message 

171 ] 

172 except KeyError: 2 ctx2qbx

173 return message if not message_plural or n == 1 else message_plural 2 ctx2qbx

174 return cls._format_enum_name_maybe_with_fields( 4 ctx1}~rb

175 enum_name=str(enum_value), 

176 ts=cast('TranslatableString', enum_value.value), 

177 trimmed=trimmed, 

178 ) 

179 

180 @staticmethod (empty)

181 def _format_enum_name_maybe_with_fields( (empty)

182 enum_name: str, 

183 ts: TranslatableString, 

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

185 ) -> str: 

186 formatted_fields = [ 4 ctx1}~rb

187 f'{f}=None' if f in trimmed else f'{f}={{{f}!r}}' 

188 for f in ts.fields() 

189 ] 

190 return ( 4 ctx1}~rb

191 '{}({})'.format(enum_name, ', '.join(formatted_fields)) 

192 if formatted_fields 

193 else str(enum_name) 

194 ) 

195 

196 @override (empty)

197 def gettext( (empty)

198 self, 

199 message: str, 

200 /, 

201 ) -> str: 

202 return self._locate_message(message) 2 ctx2qbx

203 

204 @override (empty)

205 def ngettext( (empty)

206 self, 

207 msgid1: str, (empty)

208 msgid2: str, (empty)

209 n: int, (empty)

210 /, 

211 ) -> str: # pragma: no cover (empty)

212 """""" # noqa: D419 

213 # Currently unused, so no coverage. 

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

215 

216 @override (empty)

217 def pgettext( (empty)

218 self, 

219 context: str, 

220 message: str, 

221 /, 

222 ) -> str: 

223 return self._locate_message(message, context=context) 4 ctx1}~rb

224 

225 @override (empty)

226 def npgettext( (empty)

227 self, 

228 context: str, (empty)

229 msgid1: str, (empty)

230 msgid2: str, (empty)

231 n: int, (empty)

232 /, 

233 ) -> str: # pragma: no cover (empty)

234 """""" # noqa: D419 

235 # Currently unused, so no coverage. 

236 return self._locate_message( 

237 msgid1, 

238 context=context, 

239 message_plural=msgid2, 

240 n=n, 

241 ) 

242 

243 

244class TranslatableString(NamedTuple): (empty)

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

246 

247 For typing purposes. 

248 

249 Attributes: 

250 l10n_context: 

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

252 disambiguate different uses of the same translatable string. 

253 singular: 

254 The translatable message, base case. 

255 plural: 

256 The translatable message, plural case. Usually unset. 

257 translator_comments: 

258 Explicit commentary for the translator. 

259 flags: 

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

261 string formatting style in use. 

262 

263 """ 

264 

265 l10n_context: str (empty)

266 """""" (empty)

267 singular: str (empty)

268 """""" (empty)

269 plural: str = '' (empty)

270 """""" (empty)

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

272 """""" (empty)

273 translator_comments: str = '' (empty)

274 """""" (empty)

275 

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

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

278 

279 Raises: 

280 NotImplementedError: 

281 Replacement field discovery for %-formatting is not 

282 implemented. 

283 

284 """ 

285 if 'python-format' in self.flags: # pragma: no cover 5 ctx1a}~rb

286 # Currently unused, so no coverage. 

287 err_msg = ( 

288 'Replacement field discovery for %-formatting ' 

289 'is not implemented' 

290 ) 

291 raise NotImplementedError(err_msg) 

292 if ( 5 ctx1a}~rb

293 'no-python-brace-format' in self.flags 

294 or 'python-brace-format' not in self.flags 

295 ): 

296 return [] 4 ctx1a}~r

297 formatter = string.Formatter() 4 ctx1a}~b

298 fields: dict[str, int] = {} 4 ctx1a}~b

299 for _lit, field, _spec, _conv in formatter.parse(self.singular): 4 ctx1a}~b

300 if field is not None and field not in fields: 4 ctx1a}~b

301 fields[field] = len(fields) 4 ctx1a}~b

302 return sorted(fields, key=fields.__getitem__) 4 ctx1a}~b

303 

304 @staticmethod (empty)

305 def _maybe_rewrap( (empty)

306 string: str, 

307 /, 

308 *, 

309 fix_sentence_endings: bool = True, 

310 ) -> str: 

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

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

313 string = '\n'.join( (empty)

314 textwrap.wrap( 

315 string, 

316 width=float('inf'), # type: ignore[arg-type] 

317 fix_sentence_endings=fix_sentence_endings, 

318 ) 

319 ) 

320 else: 

321 string = ''.join( (empty)

322 s 

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

324 if s.strip() != '\b' 

325 ) 

326 return string (empty)

327 

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

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

330 

331 Only acts upon translatable strings containing the exact 

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

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

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

335 necessarily in other languages. 

336 

337 """ 

338 filename_str = ': {filename!r}' 22 ctx1adefghijklmnopqstvuwbc

339 ret = self 22 ctx1adefghijklmnopqstvuwbc

340 a, sep1, b = self.singular.partition(filename_str) 22 ctx1adefghijklmnopqstvuwbc

341 c, sep2, d = self.plural.partition(filename_str) 22 ctx1adefghijklmnopqstvuwbc

342 if sep1: 22 ctx1adefghijklmnopqstvuwbc

343 ret = ret._replace(singular=(a + b)) 20 ctx1adefghijklmnopqstubc

344 # Currently no translatable messages use plural forms 

345 if sep2: # pragma: no cover 22 ctx1adefghijklmnopqstvuwbc

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

347 return ret 22 ctx1adefghijklmnopqstvuwbc

348 

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

350 """Return a rewrapped version of self. 

351 

352 Normalizes all parts assumed to contain English prose. 

353 

354 """ 

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

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

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

358 comments = self._maybe_rewrap( (empty)

359 self.translator_comments, fix_sentence_endings=False 

360 ) 

361 return self._replace( (empty)

362 singular=msg, 

363 plural=plural, 

364 l10n_context=context, 

365 translator_comments=comments, 

366 ) 

367 

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

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

370 

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

372 normalized. 

373 

374 Returns: 

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

376 

377 """ 

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

379 'TRANSLATORS:' 

380 ): # pragma: no cover 

381 # Currently unused, so no coverage. 

382 comments = 'TRANSLATORS: ' + comments.lstrip() (empty)

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

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

385 

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

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

388 

389 Returns: 

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

391 and all flags validated. 

392 

393 Raises: 

394 ValueError: 

395 The flags failed to validate. See the exact error 

396 message for details. 

397 

398 Examples: 

399 >>> TranslatableString('', 'all OK').validate_flags() 

400 ... # doctest: +NORMALIZE_WHITESPACE 

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

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

403 >>> TranslatableString('', '20% OK').validate_flags( 

404 ... 'no-python-format' 

405 ... ) 

406 ... # doctest: +NORMALIZE_WHITESPACE 

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

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

409 translator_comments='') 

410 >>> TranslatableString('', '%d items').validate_flags() 

411 ... # doctest: +ELLIPSIS 

412 Traceback (most recent call last): 

413 ... 

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

415 >>> TranslatableString('', '{braces}').validate_flags() 

416 ... # doctest: +ELLIPSIS 

417 Traceback (most recent call last): 

418 ... 

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

420 >>> TranslatableString('', 'no braces').validate_flags( 

421 ... 'python-brace-format' 

422 ... ) 

423 ... # doctest: +ELLIPSIS 

424 Traceback (most recent call last): 

425 ... 

426 ValueError: Missing format string parameters ... 

427 

428 """ 

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

430 if '{' in self.singular and not bool( (empty)

431 all_flags & {'python-brace-format', 'no-python-brace-format'} 

432 ): 

433 msg = ( (empty)

434 f'Missing flag for how to deal with brace character ' 

435 f'in {self.singular!r}' 

436 ) 

437 raise ValueError(msg) (empty)

438 if '%' in self.singular and not bool( (empty)

439 all_flags & {'python-format', 'no-python-format'} 

440 ): 

441 msg = ( (empty)

442 f'Missing flag for how to deal with percent character ' 

443 f'in {self.singular!r}' 

444 ) 

445 raise ValueError(msg) (empty)

446 if ( (empty)

447 all_flags & {'python-format', 'python-brace-format'} 

448 and '%' not in self.singular 

449 and '{' not in self.singular 

450 ): 

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

452 raise ValueError(msg) (empty)

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

454 

455 

456def translatable( (empty)

457 context: str, 

458 single: str, 

459 /, 

460 flags: Iterable[str] = (), 

461 plural: str = '', 

462 comments: str = '', 

463) -> TranslatableString: 

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

465 

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

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

468 [`TranslatableStringConstructor`][]. 

469 

470 """ 

471 flags = ( (empty)

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

473 ) 

474 return ( (empty)

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

476 .rewrapped() 

477 .with_comments(comments) 

478 .validate_flags() 

479 ) 

480 

481 

482class TranslatedString: (empty)

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

484 

485 The translation and replacement value rendering is only performed 

486 when this string object is actually stringified. 

487 

488 """ 

489 

490 def __init__( (empty)

491 self, 

492 template: str | TranslatableString | MsgTemplate, 

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

494 /, 

495 **kwargs: Any, # noqa: ANN401 

496 ) -> None: 

497 """Initializer. 

498 

499 Args: 

500 template: 

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

502 a string, use it directly. If 

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

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

505 "singular" entry. 

506 args_dict: 

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

508 kwargs: 

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

510 

511 """ 

512 if isinstance(template, MSG_TEMPLATE_CLASSES): 108 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbrbs sbobtbubvb4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

513 template = cast('TranslatableString', template.value) 104 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbrbs sbobtbubvb4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` r b c

514 self.template = template 108 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbrbs sbobtbubvb4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

515 self.kwargs = {**args_dict, **kwargs} 108 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbrbs sbobtbubvb4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

516 self._rendered: str | None = None 108 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbrbs sbobtbubvb4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

517 

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

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

520 return bool(str(self)) 6 ctx1BCDEFH

521 

522 def __eq__(self, other: object) -> bool: # pragma: no cover (empty)

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

524 # Only used interactively during debugging, so no coverage. 

525 return str(self) == other 3 ctx1rbc

526 

527 def __hash__(self) -> int: # pragma: no cover (empty)

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

529 # Only used interactively during debugging, so no coverage. 

530 return hash(str(self)) 64 ctx2a bbG I J cbdbebfbK L M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 1 2 3 q kb4 5 6 7 8 lb9 mb! # $ % ' r b c

531 

532 def __repr__(self) -> str: # pragma: no cover (empty)

533 """""" # noqa: D419 

534 # Only used interactively during debugging, so no coverage. 

535 return ( 

536 f'{self.__class__.__name__}({self.template!r}, ' 

537 f'{dict(self.kwargs)!r})' 

538 ) 

539 

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

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

542 

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

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

545 calls. 

546 

547 """ 

548 if self._rendered is None: 103 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbs ob4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

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

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

551 context = '' 6 ctx2y z A abx {

552 template = self.template 6 ctx2y z A abx {

553 else: 

554 context = self.template.l10n_context 85 ctx1aBCDEFG()*+H,IJKLMNOdPefghQRSijTUVWXYklZmnop0-.123qs456789!#$%'/:ytvuw;z=A?@[]^_`rbc|

555 template = self.template.singular 85 ctx1aBCDEFG()*+H,IJKLMNOdPefghQRSijTUVWXYklZmnop0-.123qs456789!#$%'/:ytvuw;z=A?@[]^_`rbc|

556 do_escape = 'no-python-brace-format' in self.template.flags 85 ctx1aBCDEFG()*+H,IJKLMNOdPefghQRSijTUVWXYklZmnop0-.123qs456789!#$%'/:ytvuw;z=A?@[]^_`rbc|

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

558 translation.pgettext(context, template) 

559 if context 

560 else translation.gettext(template) 

561 ) 

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

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

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

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

566 } 

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

568 return self._rendered 103 ctx2a bbB C D E F G ( ) * + H , I J cbdbebfbK nbL M N O d P e gbhbf g h Q ibR S i j T U V W X Y jbk l Z m n o p 0 - . 1 2 3 q kbs ob4 5 6 7 8 lb9 mb! # $ % ' / : y t v u w ; z = A ? @ [ ] ^ _ pb` abx r b c { |

569 

570 @staticmethod (empty)

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

572 return template.translate({ 3 ctx1x{|

573 ord('{'): '{{', 

574 ord('}'): '}}', 

575 }) 

576 

577 @classmethod (empty)

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

579 return cls(cls._escape(template)) 2 ctx1x{

580 

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

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

583 

584 Only acts upon translated strings containing the exact contents 

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

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

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

588 

589 """ 

590 new_template = ( 21 ctx1defghijklmnopqstvuwbc

591 self.template.maybe_without_filename() 

592 if not isinstance(self.template, str) 

593 else self.template 

594 ) 

595 if ( 21 ctx1defghijklmnopqstvuwbc

596 not isinstance(new_template, str) 

597 and self.kwargs.get('filename') is None 

598 and new_template != self.template 

599 ): 

600 return self.__class__(new_template, self.kwargs) 9 ctx1dfjlmnobc

601 return self 12 ctx1eghikpqstvuw

602 

603 

604class TranslatableStringConstructor(Protocol): (empty)

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

606 

607 def __call__( (empty)

608 self, 

609 context: str, (empty)

610 single: str, (empty)

611 /, 

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

613 plural: str = '', (empty)

614 comments: str = '', (empty)

615 ) -> TranslatableString: (empty)

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

617 

618 Usually some form of validation or normalization is performed 

619 first on these parts. 

620 

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

622 

623 """ 

624 

625 

626def commented(comments: str = '', /) -> TranslatableStringConstructor: (empty)

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

628 

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

630 argument pre-filled. 

631 

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

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

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

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

636 a specific formatting. 

637 

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

639 solution. 

640 

641 """ # noqa: DOC201 

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

643 

644 

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

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

647 

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

649 diagnostic labels and interactive prompts. 

650 

651 """ 

652 

653 DEPRECATION_WARNING_LABEL = commented( (empty)

654 'This is a short label that will be prepended to ' 

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

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

657 )( 

658 'Label :: Diagnostics :: Marker', 

659 'Deprecation warning', 

660 ) 

661 """""" (empty)

662 WARNING_LABEL = commented( (empty)

663 'This is a short label that will be prepended to ' 

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

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

666 )( 

667 'Label :: Diagnostics :: Marker', 

668 'Warning', 

669 ) 

670 """""" (empty)

671 CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_GLOBAL = commented( (empty)

672 'This is one of two values of the settings_type metavar ' 

673 'used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry. ' 

674 'It is only used there. ' 

675 'The full sentence then reads: ' 

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

677 )( 

678 'Label :: Error message :: Metavar', 

679 'global settings', 

680 ) 

681 """""" (empty)

682 CANNOT_UPDATE_SETTINGS_METAVAR_SETTINGS_TYPE_SERVICE = commented( (empty)

683 'This is one of two values of the settings_type metavar ' 

684 'used in the CANNOT_UPDATE_SETTINGS_NO_SETTINGS entry. ' 

685 'It is only used there. ' 

686 'The full sentence then reads: ' 

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

688 'given settings."', 

689 )( 

690 'Label :: Error message :: Metavar', 

691 'service-specific settings', 

692 ) 

693 """""" (empty)

694 SETTINGS_ORIGIN_INTERACTIVE = commented( (empty)

695 'This value is used as the {key} metavar for ' 

696 'Label.PASSPHRASE_NOT_NORMALIZED if the passphrase was ' 

697 'entered interactively.', 

698 )( 

699 'Label :: Error message :: Metavar', 

700 'interactive input', 

701 ) 

702 CONFIGURATION_EPILOG = commented( (empty)

703 '', 

704 )( 

705 'Label :: Help text :: Explanation', 

706 'Use $VISUAL or $EDITOR to configure the spawned editor.', 

707 ) 

708 """""" (empty)

709 DERIVEPASSPHRASE_02 = commented( (empty)

710 '', 

711 )( 

712 'Label :: Help text :: Explanation', 

713 'The currently implemented subcommands are "vault" ' 

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

715 '(for exporting foreign configuration data). ' 

716 'See the respective `--help` output for instructions. ' 

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

718 ) 

719 """""" (empty)

720 DERIVEPASSPHRASE_03 = commented( (empty)

721 '', 

722 )( 

723 'Label :: Help text :: Explanation', 

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

725 'Starting in v1.0, the subcommand must be specified explicitly.', 

726 ) 

727 """""" (empty)

728 DERIVEPASSPHRASE_EPILOG_01 = commented( (empty)

729 '', 

730 )( 

731 'Label :: Help text :: Explanation', 

732 'Configuration is stored in a directory according to the ' 

733 '`DERIVEPASSPHRASE_PATH` variable, which defaults to ' 

734 '`~/.derivepassphrase` on UNIX-like systems and ' 

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

736 ) 

737 """""" (empty)

738 DERIVEPASSPHRASE_EXPORT_02 = commented( (empty)

739 '', 

740 )( 

741 'Label :: Help text :: Explanation', 

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

743 'which implements the vault-native configuration scheme. ' 

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

745 ) 

746 """""" (empty)

747 DERIVEPASSPHRASE_EXPORT_03 = DERIVEPASSPHRASE_03 (empty)

748 """""" (empty)

749 DERIVEPASSPHRASE_EXPORT_VAULT_02 = commented( (empty)

750 'The metavar is Label.EXPORT_VAULT_METAVAR_PATH.', 

751 )( 

752 'Label :: Help text :: Explanation', 

753 'Depending on the configuration format, ' 

754 '{path_metavar} may either be a file or a directory. ' 

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

756 flags='python-brace-format', 

757 ) 

758 """""" (empty)

759 DERIVEPASSPHRASE_EXPORT_VAULT_03 = commented( (empty)

760 'The metavar is Label.EXPORT_VAULT_METAVAR_PATH.', 

761 )( 

762 'Label :: Help text :: Explanation', 

763 'If {path_metavar} is explicitly given as `VAULT_PATH`, ' 

764 'then use the `VAULT_PATH` environment variable to ' 

765 'determine the correct path. ' 

766 '(Use `./VAULT_PATH` or similar to indicate a file/directory ' 

767 'actually named `VAULT_PATH`.)', 

768 flags='python-brace-format', 

769 ) 

770 """""" (empty)

771 DERIVEPASSPHRASE_VAULT_02 = commented( (empty)

772 'The metavar is Label.VAULT_METAVAR_SERVICE.', 

773 )( 

774 'Label :: Help text :: Explanation', 

775 'If operating on global settings, or importing/exporting settings, ' 

776 'then {service_metavar} must be omitted. ' 

777 'Otherwise it is required.', 

778 flags='python-brace-format', 

779 ) 

780 """""" (empty)

781 DERIVEPASSPHRASE_VAULT_EPILOG_01 = commented( (empty)

782 '', 

783 )( 

784 'Label :: Help text :: Explanation', 

785 'WARNING: There is NO WAY to retrieve the generated passphrases ' 

786 'if the master passphrase, the SSH key, or the exact ' 

787 'passphrase settings are lost, ' 

788 'short of trying out all possible combinations. ' 

789 'You are STRONGLY advised to keep independent backups of ' 

790 'the settings and the SSH key, if any.', 

791 ) 

792 """""" (empty)

793 DERIVEPASSPHRASE_VAULT_EPILOG_02 = commented( (empty)

794 '', 

795 )( 

796 'Label :: Help text :: Explanation', 

797 'The configuration is NOT encrypted, and you are ' 

798 'STRONGLY discouraged from using a stored passphrase.', 

799 ) 

800 """""" (empty)

801 DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT = commented( (empty)

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

803 'for this service, if any, if the recommended ' 

804 '"modern" editor interface is used. ' 

805 'The next line is the cut marking defined in ' 

806 'Label.DERIVEPASSPHRASE_VAULT_NOTES_MARKER.' 

807 )( 

808 'Label :: Help text :: Explanation', 

809 """\ 

810\b 

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

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

813# 

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

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

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

817# retained. 

818# 

819""", 

820 ) 

821 """""" (empty)

822 DERIVEPASSPHRASE_VAULT_NOTES_LEGACY_INSTRUCTION_TEXT = commented( (empty)

823 'This instruction text is shown if the vault(1)-compatible ' 

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

825 'The interface does not support commentary in the notes, ' 

826 'so we fill this with obvious placeholder text instead. ' 

827 '(Please replace this with what *your* language/culture would ' 

828 'obviously recognize as placeholder text.)' 

829 )( 

830 'Label :: Help text :: Explanation', 

831 'INSERT NOTES HERE', 

832 ) 

833 """""" (empty)

834 PASSPHRASE_GENERATION_EPILOG = commented( (empty)

835 'The metavar is Label.PASSPHRASE_GENERATION_METAVAR_NUMBER.', 

836 )( 

837 'Label :: Help text :: Explanation', 

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

839 flags='python-brace-format', 

840 ) 

841 """""" (empty)

842 STORAGE_MANAGEMENT_EPILOG = commented( (empty)

843 'The metavar is Label.STORAGE_MANAGEMENT_METAVAR_PATH.', 

844 )( 

845 'Label :: Help text :: Explanation', 

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

847 'is supported.', 

848 flags='python-brace-format', 

849 ) 

850 """""" (empty)

851 DEPRECATED_COMMAND_LABEL = commented( (empty)

852 'We use this format string to indicate, at the beginning ' 

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

854 )( 

855 'Label :: Help text :: Marker', 

856 '(Deprecated) {text}', 

857 flags='python-brace-format', 

858 ) 

859 """""" (empty)

860 DERIVEPASSPHRASE_VAULT_NOTES_MARKER = commented( (empty)

861 'The marker for separating the text from ' 

862 'Label.DERIVEPASSPHRASE_VAULT_NOTES_INSTRUCTION_TEXT ' 

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

864 'The first line starting with this label marks the separation point.', 

865 )( 

866 'Label :: Help text :: Marker', 

867 '# - - - - - >8 - - - - - >8 - - - - - >8 - - - - - >8 - - - - -', 

868 ) 

869 """""" (empty)

870 EXPORT_VAULT_FORMAT_METAVAR_FMT = commented( (empty)

871 'This text is used as {metavar} in ' 

872 'Label.EXPORT_VAULT_FORMAT_HELP_TEXT, yielding e.g. ' 

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

874 )( 

875 'Label :: Help text :: Metavar :: export vault', 

876 'FMT', 

877 ) 

878 """""" (empty)

879 EXPORT_VAULT_KEY_METAVAR_K = commented( (empty)

880 'This text is used as {metavar} in ' 

881 'Label.EXPORT_VAULT_KEY_HELP_TEXT, yielding e.g. ' 

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

883 )( 

884 'Label :: Help text :: Metavar :: export vault', 

885 'K', 

886 ) 

887 """""" (empty)

888 EXPORT_VAULT_METAVAR_PATH = commented( (empty)

889 'Used as "path_metavar" in ' 

890 'Label.DERIVEPASSPHRASE_EXPORT_VAULT_02 and others, ' 

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

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

893 )( 

894 'Label :: Help text :: Metavar :: export vault', 

895 'PATH', 

896 ) 

897 """""" (empty)

898 PASSPHRASE_GENERATION_METAVAR_NUMBER = commented( (empty)

899 'This metavar is used in Label.PASSPHRASE_GENERATION_EPILOG, ' 

900 'Label.DERIVEPASSPHRASE_VAULT_LENGTH_HELP_TEXT and others, ' 

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

902 )( 

903 'Label :: Help text :: Metavar :: vault', 

904 'NUMBER', 

905 ) 

906 """""" (empty)

907 STORAGE_MANAGEMENT_METAVAR_PATH = commented( (empty)

908 'This metavar is used in Label.STORAGE_MANAGEMENT_EPILOG, ' 

909 'Label.DERIVEPASSPHRASE_VAULT_IMPORT_HELP_TEXT and others, ' 

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

911 )( 

912 'Label :: Help text :: Metavar :: vault', 

913 'PATH', 

914 ) 

915 """""" (empty)

916 VAULT_METAVAR_SERVICE = commented( (empty)

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

918 'such as Label.DERIVEPASSPHRASE_VAULT_CONFIG_HELP_TEXT, ' 

919 'Label.DERIVEPASSPHRASE_VAULT_02, ErrMsgTemplate.SERVICE_REQUIRED, ' 

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

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

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

923 'then SERVICE must be omitted."', 

924 )( 

925 'Label :: Help text :: Metavar :: vault', 

926 'SERVICE', 

927 ) 

928 """""" (empty)

929 DEBUG_OPTION_HELP_TEXT = commented( (empty)

930 '', 

931 )( 

932 'Label :: Help text :: One-line description', 

933 'Also emit debug information. Implies --verbose.', 

934 ) 

935 """""" (empty)

936 DERIVEPASSPHRASE_01 = commented( (empty)

937 'This is the first paragraph of the command help text, ' 

938 'but it also appears (in truncated form, if necessary) ' 

939 'as one-line help text for this command. ' 

940 'The translation should thus be as meaningful as possible ' 

941 'even if truncated.', 

942 )( 

943 'Label :: Help text :: One-line description', 

944 'Derive a strong passphrase, deterministically, from a master secret.', 

945 ) 

946 """""" (empty)

947 DERIVEPASSPHRASE_EXPORT_01 = commented( (empty)

948 'This is the first paragraph of the command help text, ' 

949 'but it also appears (in truncated form, if necessary) ' 

950 'as one-line help text for this command. ' 

951 'The translation should thus be as meaningful as possible ' 

952 'even if truncated.', 

953 )( 

954 'Label :: Help text :: One-line description', 

955 'Export a foreign configuration to standard output.', 

956 ) 

957 """""" (empty)

958 DERIVEPASSPHRASE_EXPORT_VAULT_01 = commented( (empty)