derivepassphrase.git

src/derivepassphrase/_types.py   1) # SPDX-FileCopyrightText: 2024 Marco Ricci <software@the13thletter.info>

src/derivepassphrase/types.py    2) #
src/derivepassphrase/types.py    3) # SPDX-License-Identifier: MIT
src/derivepassphrase/types.py    4) 

src/derivepassphrase/_types.py   5) """Types used by derivepassphrase."""

src/derivepassphrase/types.py    6) 
src/derivepassphrase/types.py    7) from __future__ import annotations
src/derivepassphrase/types.py    8) 

src/derivepassphrase/_types.py   9) import collections

src/derivepassphrase/_types.py  10) import enum

src/derivepassphrase/_types.py  11) import json

src/derivepassphrase/_types.py  12) import math

src/derivepassphrase/_types.py  13) from typing import TYPE_CHECKING

src/derivepassphrase/types.py   14) 

src/derivepassphrase/types.py   15) from typing_extensions import (

src/derivepassphrase/_types.py  16)     NamedTuple,

src/derivepassphrase/types.py   17)     NotRequired,
src/derivepassphrase/types.py   18)     TypedDict,

src/derivepassphrase/types.py   19) )

src/derivepassphrase/types.py   20) 

src/derivepassphrase/_types.py  21) if TYPE_CHECKING:

src/derivepassphrase/_types.py  22)     from collections.abc import MutableSequence, Sequence

src/derivepassphrase/_types.py  23)     from typing import Literal
src/derivepassphrase/_types.py  24) 
src/derivepassphrase/_types.py  25)     from typing_extensions import (
src/derivepassphrase/_types.py  26)         Any,
src/derivepassphrase/_types.py  27)         Required,
src/derivepassphrase/_types.py  28)         TypeIs,
src/derivepassphrase/_types.py  29)     )
src/derivepassphrase/_types.py  30) 

src/derivepassphrase/_types.py  31) __all__ = (
src/derivepassphrase/_types.py  32)     'SSH_AGENT',
src/derivepassphrase/_types.py  33)     'SSH_AGENTC',
src/derivepassphrase/_types.py  34)     'KeyCommentPair',
src/derivepassphrase/_types.py  35)     'VaultConfig',
src/derivepassphrase/_types.py  36)     'is_vault_config',
src/derivepassphrase/_types.py  37) )

src/derivepassphrase/types.py   38) 

src/derivepassphrase/types.py   39) 

src/derivepassphrase/types.py   40) class VaultConfigGlobalSettings(TypedDict, total=False):
src/derivepassphrase/types.py   41)     r"""Configuration for vault: global settings.
src/derivepassphrase/types.py   42) 
src/derivepassphrase/types.py   43)     Attributes:
src/derivepassphrase/types.py   44)         key:
src/derivepassphrase/types.py   45)             The base64-encoded ssh public key to use, overriding the
src/derivepassphrase/types.py   46)             master passphrase. Optional.
src/derivepassphrase/types.py   47)         phrase:
src/derivepassphrase/types.py   48)             The master passphrase. Optional.

src/derivepassphrase/_types.py  49)         unicode_normalization_form:
src/derivepassphrase/_types.py  50)             The preferred Unicode normalization form; we warn the user
src/derivepassphrase/_types.py  51)             if textual passphrases do not match their normalized forms.
src/derivepassphrase/_types.py  52)             Optional, and a `derivepassphrase` extension.

src/derivepassphrase/types.py   53)         length:
src/derivepassphrase/types.py   54)             Desired passphrase length.
src/derivepassphrase/types.py   55)         repeat:
src/derivepassphrase/types.py   56)             The maximum number of immediate character repetitions
src/derivepassphrase/types.py   57)             allowed in the passphrase.  Disabled if set to 0.
src/derivepassphrase/types.py   58)         lower:
src/derivepassphrase/types.py   59)             Optional constraint on ASCII lowercase characters.  If
src/derivepassphrase/types.py   60)             positive, include this many lowercase characters
src/derivepassphrase/types.py   61)             somewhere in the passphrase.  If 0, avoid lowercase
src/derivepassphrase/types.py   62)             characters altogether.
src/derivepassphrase/types.py   63)         upper:
src/derivepassphrase/types.py   64)             Same as `lower`, but for ASCII uppercase characters.
src/derivepassphrase/types.py   65)         number:
src/derivepassphrase/types.py   66)             Same as `lower`, but for ASCII digits.
src/derivepassphrase/types.py   67)         space:
src/derivepassphrase/types.py   68)             Same as `lower`, but for the space character.
src/derivepassphrase/types.py   69)         dash:
src/derivepassphrase/types.py   70)             Same as `lower`, but for the hyphen-minus and underscore
src/derivepassphrase/types.py   71)             characters.
src/derivepassphrase/types.py   72)         symbol:
src/derivepassphrase/types.py   73)             Same as `lower`, but for all other hitherto unlisted
src/derivepassphrase/types.py   74)             ASCII printable characters (except backquote).
src/derivepassphrase/types.py   75) 
src/derivepassphrase/types.py   76)     """

src/derivepassphrase/types.py   77) 

src/derivepassphrase/_types.py  78)     key: NotRequired[str]
src/derivepassphrase/_types.py  79)     """"""
src/derivepassphrase/_types.py  80)     phrase: NotRequired[str]
src/derivepassphrase/_types.py  81)     """"""
src/derivepassphrase/_types.py  82)     unicode_normalization_form: NotRequired[
src/derivepassphrase/_types.py  83)         Literal['NFC', 'NFD', 'NFKC', 'NFKD']
src/derivepassphrase/_types.py  84)     ]

src/derivepassphrase/_types.py  85)     """"""

src/derivepassphrase/types.py   86)     length: NotRequired[int]

src/derivepassphrase/_types.py  87)     """"""

src/derivepassphrase/types.py   88)     repeat: NotRequired[int]

src/derivepassphrase/_types.py  89)     """"""

src/derivepassphrase/types.py   90)     lower: NotRequired[int]

src/derivepassphrase/_types.py  91)     """"""

src/derivepassphrase/types.py   92)     upper: NotRequired[int]

src/derivepassphrase/_types.py  93)     """"""

src/derivepassphrase/types.py   94)     number: NotRequired[int]

src/derivepassphrase/_types.py  95)     """"""

src/derivepassphrase/types.py   96)     space: NotRequired[int]

src/derivepassphrase/_types.py  97)     """"""

src/derivepassphrase/types.py   98)     dash: NotRequired[int]

src/derivepassphrase/_types.py  99)     """"""

src/derivepassphrase/types.py  100)     symbol: NotRequired[int]

src/derivepassphrase/_types.py 101)     """"""

src/derivepassphrase/types.py  102) 
src/derivepassphrase/types.py  103) 

src/derivepassphrase/_types.py 104) class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
src/derivepassphrase/_types.py 105)     r"""Configuration for vault: services settings.
src/derivepassphrase/_types.py 106) 
src/derivepassphrase/_types.py 107)     Attributes:
src/derivepassphrase/_types.py 108)         notes:
src/derivepassphrase/_types.py 109)             Optional notes for this service, to display to the user when
src/derivepassphrase/_types.py 110)             generating the passphrase.
src/derivepassphrase/_types.py 111)         key:
src/derivepassphrase/_types.py 112)             As per the global settings.
src/derivepassphrase/_types.py 113)         phrase:
src/derivepassphrase/_types.py 114)             As per the global settings.
src/derivepassphrase/_types.py 115)         unicode_normalization_form:
src/derivepassphrase/_types.py 116)             As per the global settings.
src/derivepassphrase/_types.py 117)         length:
src/derivepassphrase/_types.py 118)             As per the global settings.
src/derivepassphrase/_types.py 119)         repeat:
src/derivepassphrase/_types.py 120)             As per the global settings.
src/derivepassphrase/_types.py 121)         lower:
src/derivepassphrase/_types.py 122)             As per the global settings.
src/derivepassphrase/_types.py 123)         upper:
src/derivepassphrase/_types.py 124)             As per the global settings.
src/derivepassphrase/_types.py 125)         number:
src/derivepassphrase/_types.py 126)             As per the global settings.
src/derivepassphrase/_types.py 127)         space:
src/derivepassphrase/_types.py 128)             As per the global settings.
src/derivepassphrase/_types.py 129)         dash:
src/derivepassphrase/_types.py 130)             As per the global settings.
src/derivepassphrase/_types.py 131)         symbol:
src/derivepassphrase/_types.py 132)             As per the global settings.
src/derivepassphrase/_types.py 133) 
src/derivepassphrase/_types.py 134)     """
src/derivepassphrase/_types.py 135) 
src/derivepassphrase/_types.py 136)     notes: NotRequired[str]
src/derivepassphrase/_types.py 137)     """"""
src/derivepassphrase/_types.py 138) 
src/derivepassphrase/_types.py 139) 

src/derivepassphrase/types.py  140) _VaultConfig = TypedDict(
src/derivepassphrase/types.py  141)     '_VaultConfig',
src/derivepassphrase/types.py  142)     {'global': NotRequired[VaultConfigGlobalSettings]},
src/derivepassphrase/types.py  143)     total=False,
src/derivepassphrase/types.py  144) )
src/derivepassphrase/types.py  145) 
src/derivepassphrase/types.py  146) 

src/derivepassphrase/types.py  147) class VaultConfig(TypedDict, _VaultConfig, total=False):

src/derivepassphrase/_types.py 148)     r"""Configuration for vault.  For typing purposes.

src/derivepassphrase/types.py  149) 
src/derivepassphrase/types.py  150)     Usually stored as JSON.
src/derivepassphrase/types.py  151) 
src/derivepassphrase/types.py  152)     Attributes:
src/derivepassphrase/types.py  153)         global (NotRequired[VaultConfigGlobalSettings]):
src/derivepassphrase/types.py  154)             Global settings.
src/derivepassphrase/types.py  155)         services (Required[dict[str, VaultConfigServicesSettings]]):
src/derivepassphrase/types.py  156)             Service-specific settings.
src/derivepassphrase/types.py  157) 
src/derivepassphrase/types.py  158)     """

src/derivepassphrase/types.py  159) 

src/derivepassphrase/types.py  160)     services: Required[dict[str, VaultConfigServicesSettings]]
src/derivepassphrase/types.py  161) 

src/derivepassphrase/types.py  162) 

src/derivepassphrase/_types.py 163) def json_path(path: Sequence[str | int], /) -> str:
src/derivepassphrase/_types.py 164)     r"""Transform a series of keys and indices into a JSONPath selector.
src/derivepassphrase/_types.py 165) 
src/derivepassphrase/_types.py 166)     The resulting JSONPath selector conforms to RFC 9535, is always
src/derivepassphrase/_types.py 167)     rooted at the JSON root node (i.e., starts with `$`), and only
src/derivepassphrase/_types.py 168)     contains name and index selectors (in shorthand dot notation, where
src/derivepassphrase/_types.py 169)     possible).
src/derivepassphrase/_types.py 170) 
src/derivepassphrase/_types.py 171)     Args:
src/derivepassphrase/_types.py 172)         path:
src/derivepassphrase/_types.py 173)             A sequence of object keys or array indices to navigate to
src/derivepassphrase/_types.py 174)             the desired JSON value, starting from the root node.
src/derivepassphrase/_types.py 175) 
src/derivepassphrase/_types.py 176)     Returns:
src/derivepassphrase/_types.py 177)         A valid JSONPath selector (a string) identifying the desired
src/derivepassphrase/_types.py 178)         JSON value.
src/derivepassphrase/_types.py 179) 
src/derivepassphrase/_types.py 180)     Examples:
src/derivepassphrase/_types.py 181)         >>> json_path(['global', 'phrase'])
src/derivepassphrase/_types.py 182)         '$.global.phrase'
src/derivepassphrase/_types.py 183)         >>> json_path(['services', 'service name with spaces', 'length'])
src/derivepassphrase/_types.py 184)         '$.services["service name with spaces"].length'
src/derivepassphrase/_types.py 185)         >>> json_path(['services', 'special\u000acharacters', 'notes'])
src/derivepassphrase/_types.py 186)         '$.services["special\\ncharacters"].notes'
src/derivepassphrase/_types.py 187)         >>> print(json_path(['services', 'special\u000acharacters', 'notes']))
src/derivepassphrase/_types.py 188)         $.services["special\ncharacters"].notes
src/derivepassphrase/_types.py 189)         >>> json_path(['custom_array', 2, 0])
src/derivepassphrase/_types.py 190)         '$.custom_array[2][0]'
src/derivepassphrase/_types.py 191) 
src/derivepassphrase/_types.py 192)     """
src/derivepassphrase/_types.py 193) 
src/derivepassphrase/_types.py 194)     def needs_longhand(x: str | int) -> bool:
src/derivepassphrase/_types.py 195)         initial = (
src/derivepassphrase/_types.py 196)             frozenset('abcdefghijklmnopqrstuvwxyz')
src/derivepassphrase/_types.py 197)             | frozenset('ABCDEFGHIJKLMNOPQRSTUVWXYZ')
src/derivepassphrase/_types.py 198)             | frozenset('_')
src/derivepassphrase/_types.py 199)         )
src/derivepassphrase/_types.py 200)         chars = initial | frozenset('0123456789')
src/derivepassphrase/_types.py 201)         return not (
src/derivepassphrase/_types.py 202)             isinstance(x, str)
src/derivepassphrase/_types.py 203)             and x
src/derivepassphrase/_types.py 204)             and set(x).issubset(chars)
src/derivepassphrase/_types.py 205)             and x[:1] in initial
src/derivepassphrase/_types.py 206)         )
src/derivepassphrase/_types.py 207) 
src/derivepassphrase/_types.py 208)     chunks = ['$']
src/derivepassphrase/_types.py 209)     chunks.extend(
src/derivepassphrase/_types.py 210)         f'[{json.dumps(x)}]' if needs_longhand(x) else f'.{x}' for x in path
src/derivepassphrase/_types.py 211)     )
src/derivepassphrase/_types.py 212)     return ''.join(chunks)
src/derivepassphrase/_types.py 213) 
src/derivepassphrase/_types.py 214) 

src/derivepassphrase/_types.py 215) def validate_vault_config(  # noqa: C901,PLR0912,PLR0915
src/derivepassphrase/_types.py 216)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 217)     /,
src/derivepassphrase/_types.py 218)     *,
src/derivepassphrase/_types.py 219)     allow_unknown_settings: bool = False,
src/derivepassphrase/_types.py 220)     allow_derivepassphrase_extensions: bool = False,
src/derivepassphrase/_types.py 221) ) -> None:
src/derivepassphrase/_types.py 222)     """Check that `obj` is a valid vault config.

src/derivepassphrase/types.py  223) 
src/derivepassphrase/types.py  224)     Args:

src/derivepassphrase/_types.py 225)         obj:
src/derivepassphrase/_types.py 226)             The object to test.
src/derivepassphrase/_types.py 227)         allow_unknown_settings:
src/derivepassphrase/_types.py 228)             If false, abort on unknown settings.
src/derivepassphrase/_types.py 229)         allow_derivepassphrase_extensions:
src/derivepassphrase/_types.py 230)             If true, allow `derivepassphrase` extensions.
src/derivepassphrase/_types.py 231) 
src/derivepassphrase/_types.py 232)     Raises:
src/derivepassphrase/_types.py 233)         TypeError:
src/derivepassphrase/_types.py 234)             An entry in the vault config, or the vault config itself,
src/derivepassphrase/_types.py 235)             has the wrong type.
src/derivepassphrase/_types.py 236)         ValueError:
src/derivepassphrase/_types.py 237)             An entry in the vault config is not allowed, or has a
src/derivepassphrase/_types.py 238)             disallowed value.

src/derivepassphrase/types.py  239) 
src/derivepassphrase/types.py  240)     """

src/derivepassphrase/_types.py 241)     err_obj_not_a_dict = 'vault config is not a dict'
src/derivepassphrase/_types.py 242)     err_non_str_service_name = (
src/derivepassphrase/_types.py 243)         'vault config contains non-string service name {!r}'
src/derivepassphrase/_types.py 244)     )
src/derivepassphrase/_types.py 245) 

src/derivepassphrase/_types.py 246)     def err_not_a_dict(path: Sequence[str], /) -> str:
src/derivepassphrase/_types.py 247)         json_path_str = json_path(path)

src/derivepassphrase/_types.py 248)         return f'vault config entry {json_path_str} is not a dict'
src/derivepassphrase/_types.py 249) 

src/derivepassphrase/_types.py 250)     def err_not_a_string(path: Sequence[str], /) -> str:
src/derivepassphrase/_types.py 251)         json_path_str = json_path(path)

src/derivepassphrase/_types.py 252)         return f'vault config entry {json_path_str} is not a string'
src/derivepassphrase/_types.py 253) 

src/derivepassphrase/_types.py 254)     def err_not_an_int(path: Sequence[str], /) -> str:
src/derivepassphrase/_types.py 255)         json_path_str = json_path(path)

src/derivepassphrase/_types.py 256)         return f'vault config entry {json_path_str} is not an integer'
src/derivepassphrase/_types.py 257) 
src/derivepassphrase/_types.py 258)     def err_derivepassphrase_extension(

src/derivepassphrase/_types.py 259)         key: str, path: Sequence[str], /

src/derivepassphrase/_types.py 260)     ) -> str:

src/derivepassphrase/_types.py 261)         json_path_str = json_path(path)

src/derivepassphrase/_types.py 262)         return (
src/derivepassphrase/_types.py 263)             f'vault config entry {json_path_str} uses '
src/derivepassphrase/_types.py 264)             f'`derivepassphrase` extension {key!r}'
src/derivepassphrase/_types.py 265)         )
src/derivepassphrase/_types.py 266) 

src/derivepassphrase/_types.py 267)     def err_unknown_setting(key: str, path: Sequence[str], /) -> str:
src/derivepassphrase/_types.py 268)         json_path_str = json_path(path)

src/derivepassphrase/_types.py 269)         return (
src/derivepassphrase/_types.py 270)             f'vault config entry {json_path_str} uses '
src/derivepassphrase/_types.py 271)             f'unknown setting {key!r}'
src/derivepassphrase/_types.py 272)         )
src/derivepassphrase/_types.py 273) 
src/derivepassphrase/_types.py 274)     def err_bad_number(
src/derivepassphrase/_types.py 275)         key: str,

src/derivepassphrase/_types.py 276)         path: Sequence[str],

src/derivepassphrase/_types.py 277)         /,
src/derivepassphrase/_types.py 278)         *,
src/derivepassphrase/_types.py 279)         strictly_positive: bool = False,
src/derivepassphrase/_types.py 280)     ) -> str:

src/derivepassphrase/_types.py 281)         json_path_str = json_path((*path, key))

src/derivepassphrase/_types.py 282)         return f'vault config entry {json_path_str} is ' + (
src/derivepassphrase/_types.py 283)             'not positive' if strictly_positive else 'negative'
src/derivepassphrase/_types.py 284)         )
src/derivepassphrase/_types.py 285) 

src/derivepassphrase/types.py  286)     if not isinstance(obj, dict):

src/derivepassphrase/_types.py 287)         raise TypeError(err_obj_not_a_dict)

src/derivepassphrase/_types.py 288)     queue_to_check: list[tuple[dict[str, Any], tuple[str, ...]]] = []

src/derivepassphrase/types.py  289)     if 'global' in obj:
src/derivepassphrase/types.py  290)         o_global = obj['global']
src/derivepassphrase/types.py  291)         if not isinstance(o_global, dict):

src/derivepassphrase/_types.py 292)             raise TypeError(err_not_a_dict(['global']))

src/derivepassphrase/_types.py 293)         queue_to_check.append((o_global, ('global',)))

src/derivepassphrase/types.py  294)     if not isinstance(obj.get('services'), dict):

src/derivepassphrase/_types.py 295)         raise TypeError(err_not_a_dict(['services']))

src/derivepassphrase/types.py  296)     for sv_name, service in obj['services'].items():
src/derivepassphrase/types.py  297)         if not isinstance(sv_name, str):

src/derivepassphrase/_types.py 298)             raise TypeError(err_non_str_service_name.format(sv_name))

src/derivepassphrase/types.py  299)         if not isinstance(service, dict):

src/derivepassphrase/_types.py 300)             raise TypeError(err_not_a_dict(['services', sv_name]))

src/derivepassphrase/_types.py 301)         queue_to_check.append((service, ('services', sv_name)))
src/derivepassphrase/_types.py 302)     for settings, path in queue_to_check:
src/derivepassphrase/_types.py 303)         for key, value in settings.items():

src/derivepassphrase/_types.py 304)             # Use match/case here once Python 3.9 becomes unsupported.

src/derivepassphrase/_types.py 305)             if key in {'key', 'phrase'}:

src/derivepassphrase/_types.py 306)                 if not isinstance(value, str):

src/derivepassphrase/_types.py 307)                     raise TypeError(err_not_a_string((*path, key)))
src/derivepassphrase/_types.py 308)             elif key == 'unicode_normalization_form' and path == ('global',):
src/derivepassphrase/_types.py 309)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 310)                     raise TypeError(err_not_a_string((*path, key)))
src/derivepassphrase/_types.py 311)                 if not allow_derivepassphrase_extensions:
src/derivepassphrase/_types.py 312)                     raise ValueError(err_derivepassphrase_extension(key, path))
src/derivepassphrase/_types.py 313)             elif key == 'notes' and path != ('global',):
src/derivepassphrase/_types.py 314)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 315)                     raise TypeError(err_not_a_string((*path, key)))

src/derivepassphrase/_types.py 316)             elif key == 'length':
src/derivepassphrase/_types.py 317)                 if not isinstance(value, int):

src/derivepassphrase/_types.py 318)                     raise TypeError(err_not_an_int((*path, key)))

src/derivepassphrase/_types.py 319)                 if value < 1:
src/derivepassphrase/_types.py 320)                     raise ValueError(

src/derivepassphrase/_types.py 321)                         err_bad_number(key, path, strictly_positive=True)

src/derivepassphrase/_types.py 322)                     )
src/derivepassphrase/_types.py 323)             elif key in {
src/derivepassphrase/_types.py 324)                 'repeat',
src/derivepassphrase/_types.py 325)                 'lower',
src/derivepassphrase/_types.py 326)                 'upper',
src/derivepassphrase/_types.py 327)                 'number',
src/derivepassphrase/_types.py 328)                 'space',
src/derivepassphrase/_types.py 329)                 'dash',
src/derivepassphrase/_types.py 330)                 'symbol',
src/derivepassphrase/_types.py 331)             }:
src/derivepassphrase/_types.py 332)                 if not isinstance(value, int):

src/derivepassphrase/_types.py 333)                     raise TypeError(err_not_an_int((*path, key)))

src/derivepassphrase/_types.py 334)                 if value < 0:

src/derivepassphrase/_types.py 335)                     raise ValueError(

src/derivepassphrase/_types.py 336)                         err_bad_number(key, path, strictly_positive=False)

src/derivepassphrase/_types.py 337)                     )

src/derivepassphrase/_types.py 338)             elif not allow_unknown_settings:

src/derivepassphrase/_types.py 339)                 raise ValueError(err_unknown_setting(key, path))

src/derivepassphrase/_types.py 340) 
src/derivepassphrase/_types.py 341) 
src/derivepassphrase/_types.py 342) def is_vault_config(obj: Any) -> TypeIs[VaultConfig]:  # noqa: ANN401
src/derivepassphrase/_types.py 343)     """Check if `obj` is a valid vault config, according to typing.
src/derivepassphrase/_types.py 344) 
src/derivepassphrase/_types.py 345)     Args:
src/derivepassphrase/_types.py 346)         obj: The object to test.
src/derivepassphrase/_types.py 347) 
src/derivepassphrase/_types.py 348)     Returns:
src/derivepassphrase/_types.py 349)         True if this is a vault config, false otherwise.
src/derivepassphrase/_types.py 350) 
src/derivepassphrase/_types.py 351)     """
src/derivepassphrase/_types.py 352)     try:
src/derivepassphrase/_types.py 353)         validate_vault_config(
src/derivepassphrase/_types.py 354)             obj,
src/derivepassphrase/_types.py 355)             allow_unknown_settings=True,
src/derivepassphrase/_types.py 356)             allow_derivepassphrase_extensions=True,
src/derivepassphrase/_types.py 357)         )
src/derivepassphrase/_types.py 358)     except (TypeError, ValueError) as exc:
src/derivepassphrase/_types.py 359)         if 'vault config ' not in str(exc):  # pragma: no cover
src/derivepassphrase/_types.py 360)             raise  # noqa: DOC501
src/derivepassphrase/_types.py 361)         return False

src/derivepassphrase/types.py  362)     return True

src/derivepassphrase/_types.py 363) 
src/derivepassphrase/_types.py 364) 

src/derivepassphrase/_types.py 365) def js_truthiness(value: Any, /) -> bool:  # noqa: ANN401
src/derivepassphrase/_types.py 366)     """Return the truthiness of the value, according to JavaScript/ECMAScript.
src/derivepassphrase/_types.py 367) 
src/derivepassphrase/_types.py 368)     Like Python, ECMAScript considers certain values to be false in
src/derivepassphrase/_types.py 369)     a boolean context, and every other value to be true.  These
src/derivepassphrase/_types.py 370)     considerations do not agree: ECMAScript considers [`math.nan`][] to
src/derivepassphrase/_types.py 371)     be false too, and empty arrays and objects/dicts to be true,
src/derivepassphrase/_types.py 372)     contrary to Python.  Because of these discrepancies, we cannot defer
src/derivepassphrase/_types.py 373)     to [`bool`][] for ECMAScript truthiness checking, and need
src/derivepassphrase/_types.py 374)     a separate, explicit predicate.
src/derivepassphrase/_types.py 375) 
src/derivepassphrase/_types.py 376)     (Some falsy values in ECMAScript aren't defined in Python:
src/derivepassphrase/_types.py 377)     `undefined`, and `document.all`.  We do not implement support for
src/derivepassphrase/_types.py 378)     those.)
src/derivepassphrase/_types.py 379) 
src/derivepassphrase/_types.py 380)     !!! note
src/derivepassphrase/_types.py 381) 
src/derivepassphrase/_types.py 382)         We cannot use a simple `value not in falsy_values` check,
src/derivepassphrase/_types.py 383)         because [`math.nan`][] behaves in annoying and obstructive ways.
src/derivepassphrase/_types.py 384)         In general, `float('NaN') == float('NaN')` is false, and
src/derivepassphrase/_types.py 385)         `float('NaN') != math.nan` and `math.nan != math.nan` are true.
src/derivepassphrase/_types.py 386)         CPython says `float('NaN') in [math.nan]` is false, PyPy3 says
src/derivepassphrase/_types.py 387)         it is true.  Seemingly the only reliable and portable way to
src/derivepassphrase/_types.py 388)         check for [`math.nan`][] is to use [`math.isnan`][] directly.
src/derivepassphrase/_types.py 389) 
src/derivepassphrase/_types.py 390)     Args:
src/derivepassphrase/_types.py 391)         value: The value to test.
src/derivepassphrase/_types.py 392) 
src/derivepassphrase/_types.py 393)     """  # noqa: RUF002
src/derivepassphrase/_types.py 394)     try:
src/derivepassphrase/_types.py 395)         if value in {None, False, 0, 0.0, ''}:
src/derivepassphrase/_types.py 396)             return False
src/derivepassphrase/_types.py 397)     except TypeError:
src/derivepassphrase/_types.py 398)         # All falsy values are hashable, so this can't be falsy.
src/derivepassphrase/_types.py 399)         return True
src/derivepassphrase/_types.py 400)     return not (isinstance(value, float) and math.isnan(value))
src/derivepassphrase/_types.py 401) 
src/derivepassphrase/_types.py 402) 

src/derivepassphrase/_types.py 403) class CleanupStep(NamedTuple):
src/derivepassphrase/_types.py 404)     """A single executed step during vault config cleanup.
src/derivepassphrase/_types.py 405) 
src/derivepassphrase/_types.py 406)     Attributes:
src/derivepassphrase/_types.py 407)         path:
src/derivepassphrase/_types.py 408)             A sequence of object keys or array indices to navigate to
src/derivepassphrase/_types.py 409)             the JSON value that was cleaned up.
src/derivepassphrase/_types.py 410)         old_value:
src/derivepassphrase/_types.py 411)             The old value.
src/derivepassphrase/_types.py 412)         action:
src/derivepassphrase/_types.py 413)             Either `'replace'` if `old_value` was replaced with
src/derivepassphrase/_types.py 414)             `new_value`, or `'remove'` if `old_value` was removed.
src/derivepassphrase/_types.py 415)         new_value:
src/derivepassphrase/_types.py 416)             The new value.
src/derivepassphrase/_types.py 417) 
src/derivepassphrase/_types.py 418)     """
src/derivepassphrase/_types.py 419) 
src/derivepassphrase/_types.py 420)     path: Sequence[str | int]
src/derivepassphrase/_types.py 421)     """"""
src/derivepassphrase/_types.py 422)     old_value: Any
src/derivepassphrase/_types.py 423)     """"""
src/derivepassphrase/_types.py 424)     action: Literal['replace', 'remove']
src/derivepassphrase/_types.py 425)     """"""
src/derivepassphrase/_types.py 426)     new_value: Any
src/derivepassphrase/_types.py 427)     """"""
src/derivepassphrase/_types.py 428) 
src/derivepassphrase/_types.py 429) 
src/derivepassphrase/_types.py 430) def clean_up_falsy_vault_config_values(  # noqa: C901,PLR0912
src/derivepassphrase/_types.py 431)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 432) ) -> Sequence[CleanupStep] | None:

src/derivepassphrase/_types.py 433)     """Convert falsy values in a vault config to correct types, in-place.
src/derivepassphrase/_types.py 434) 
src/derivepassphrase/_types.py 435)     Needed for compatibility with vault(1), which sometimes uses only
src/derivepassphrase/_types.py 436)     truthiness checks.
src/derivepassphrase/_types.py 437) 
src/derivepassphrase/_types.py 438)     If vault(1) considered `obj` to be valid, then after clean up,
src/derivepassphrase/_types.py 439)     `obj` will be valid as per [`validate_vault_config`][].
src/derivepassphrase/_types.py 440) 
src/derivepassphrase/_types.py 441)     Args:
src/derivepassphrase/_types.py 442)         obj:
src/derivepassphrase/_types.py 443)             A presumed valid vault configuration save for using falsy
src/derivepassphrase/_types.py 444)             values of the wrong type.
src/derivepassphrase/_types.py 445) 

src/derivepassphrase/_types.py 446)     Returns:
src/derivepassphrase/_types.py 447)         A list of 4-tuples `(key_tup, old_value, action, new_value)`,
src/derivepassphrase/_types.py 448)         indicating the cleanup actions performed.  `key_tup` is
src/derivepassphrase/_types.py 449)         a sequence of object keys and/or array indices indicating the
src/derivepassphrase/_types.py 450)         JSON path to the leaf value that was cleaned up, `old_value` is
src/derivepassphrase/_types.py 451)         the old value, `new_value` is the new value, and `action` is
src/derivepassphrase/_types.py 452)         either `replace` (`old_value` was replaced with `new_value`) or
src/derivepassphrase/_types.py 453)         `remove` (`old_value` was removed, and `new_value` is
src/derivepassphrase/_types.py 454)         meaningless).
src/derivepassphrase/_types.py 455) 
src/derivepassphrase/_types.py 456)         If cleanup was never attempted because of an obviously invalid
src/derivepassphrase/_types.py 457)         vault configuration, then `None` is returned, directly.
src/derivepassphrase/_types.py 458) 

src/derivepassphrase/_types.py 459)     """
src/derivepassphrase/_types.py 460)     if (  # pragma: no cover
src/derivepassphrase/_types.py 461)         not isinstance(obj, dict)
src/derivepassphrase/_types.py 462)         or 'services' not in obj
src/derivepassphrase/_types.py 463)         or not isinstance(obj['services'], dict)
src/derivepassphrase/_types.py 464)     ):
src/derivepassphrase/_types.py 465)         # config is invalid

src/derivepassphrase/_types.py 466)         return None
src/derivepassphrase/_types.py 467)     service_objects: MutableSequence[
src/derivepassphrase/_types.py 468)         tuple[Sequence[str | int], dict[str, Any]]
src/derivepassphrase/_types.py 469)     ] = collections.deque()

src/derivepassphrase/_types.py 470)     if 'global' in obj:
src/derivepassphrase/_types.py 471)         if isinstance(obj['global'], dict):

src/derivepassphrase/_types.py 472)             service_objects.append((['global'], obj['global']))

src/derivepassphrase/_types.py 473)         else:  # pragma: no cover
src/derivepassphrase/_types.py 474)             # config is invalid

src/derivepassphrase/_types.py 475)             return None
src/derivepassphrase/_types.py 476)     service_objects.extend(
src/derivepassphrase/_types.py 477)         (['services', sv], val) for sv, val in obj['services'].items()
src/derivepassphrase/_types.py 478)     )
src/derivepassphrase/_types.py 479)     if not all(  # pragma: no cover
src/derivepassphrase/_types.py 480)         isinstance(service_obj, dict) for _, service_obj in service_objects
src/derivepassphrase/_types.py 481)     ):
src/derivepassphrase/_types.py 482)         # config is invalid
src/derivepassphrase/_types.py 483)         return None
src/derivepassphrase/_types.py 484)     cleanup_completed: MutableSequence[CleanupStep] = collections.deque()
src/derivepassphrase/_types.py 485)     for path, service_obj in service_objects:

src/derivepassphrase/_types.py 486)         for key, value in list(service_obj.items()):
src/derivepassphrase/_types.py 487)             # Use match/case here once Python 3.9 becomes unsupported.
src/derivepassphrase/_types.py 488)             if key == 'phrase':

src/derivepassphrase/_types.py 489)                 if not js_truthiness(value) and value != '':  # noqa: PLC1901
src/derivepassphrase/_types.py 490)                     cleanup_completed.append(
src/derivepassphrase/_types.py 491)                         CleanupStep(
src/derivepassphrase/_types.py 492)                             (*path, key), service_obj[key], 'replace', ''
src/derivepassphrase/_types.py 493)                         )
src/derivepassphrase/_types.py 494)                     )

src/derivepassphrase/_types.py 495)                     service_obj[key] = ''

src/derivepassphrase/_types.py 496)             elif key in {'notes', 'key'}:

src/derivepassphrase/_types.py 497)                 if not js_truthiness(value):

src/derivepassphrase/_types.py 498)                     cleanup_completed.append(
src/derivepassphrase/_types.py 499)                         CleanupStep(
src/derivepassphrase/_types.py 500)                             (*path, key), service_obj[key], 'remove', None
src/derivepassphrase/_types.py 501)                         )
src/derivepassphrase/_types.py 502)                     )

src/derivepassphrase/_types.py 503)                     service_obj.pop(key)

src/derivepassphrase/_types.py 504)             elif key == 'length':
src/derivepassphrase/_types.py 505)                 if not js_truthiness(value):
src/derivepassphrase/_types.py 506)                     cleanup_completed.append(
src/derivepassphrase/_types.py 507)                         CleanupStep(
src/derivepassphrase/_types.py 508)                             (*path, key), service_obj[key], 'replace', 20
src/derivepassphrase/_types.py 509)                         )
src/derivepassphrase/_types.py 510)                     )
src/derivepassphrase/_types.py 511)                     service_obj[key] = 20
src/derivepassphrase/_types.py 512)             elif key == 'repeat':
src/derivepassphrase/_types.py 513)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 514)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 515)                 ):
src/derivepassphrase/_types.py 516)                     cleanup_completed.append(
src/derivepassphrase/_types.py 517)                         CleanupStep(
src/derivepassphrase/_types.py 518)                             (*path, key), service_obj[key], 'replace', 0
src/derivepassphrase/_types.py 519)                         )
src/derivepassphrase/_types.py 520)                     )
src/derivepassphrase/_types.py 521)                     service_obj[key] = 0

src/derivepassphrase/_types.py 522)             elif key in {  # noqa: SIM102
src/derivepassphrase/_types.py 523)                 'lower',
src/derivepassphrase/_types.py 524)                 'upper',
src/derivepassphrase/_types.py 525)                 'number',
src/derivepassphrase/_types.py 526)                 'space',
src/derivepassphrase/_types.py 527)                 'dash',
src/derivepassphrase/_types.py 528)                 'symbol',
src/derivepassphrase/_types.py 529)             }:

src/derivepassphrase/_types.py 530)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 531)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 532)                 ):

src/derivepassphrase/_types.py 533)                     cleanup_completed.append(
src/derivepassphrase/_types.py 534)                         CleanupStep(

src/derivepassphrase/_types.py 535)                             (*path, key), service_obj[key], 'remove', None

src/derivepassphrase/_types.py 536)                         )
src/derivepassphrase/_types.py 537)                     )

src/derivepassphrase/_types.py 538)                     service_obj.pop(key)

src/derivepassphrase/_types.py 539)     return cleanup_completed

src/derivepassphrase/_types.py 540) 
src/derivepassphrase/_types.py 541) 

src/derivepassphrase/_types.py 542) class KeyCommentPair(NamedTuple):
src/derivepassphrase/_types.py 543)     """SSH key plus comment pair.  For typing purposes.
src/derivepassphrase/_types.py 544) 
src/derivepassphrase/_types.py 545)     Attributes:
src/derivepassphrase/_types.py 546)         key: SSH key.
src/derivepassphrase/_types.py 547)         comment: SSH key comment.
src/derivepassphrase/_types.py 548) 
src/derivepassphrase/_types.py 549)     """
src/derivepassphrase/_types.py 550) 
src/derivepassphrase/_types.py 551)     key: bytes | bytearray

src/derivepassphrase/_types.py 552)     """"""

src/derivepassphrase/_types.py 553)     comment: bytes | bytearray

src/derivepassphrase/_types.py 554)     """"""

src/derivepassphrase/_types.py 555) 
src/derivepassphrase/_types.py 556) 
src/derivepassphrase/_types.py 557) class SSH_AGENTC(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 558)     """SSH agent protocol numbers: client requests.
src/derivepassphrase/_types.py 559) 
src/derivepassphrase/_types.py 560)     Attributes:
src/derivepassphrase/_types.py 561)         REQUEST_IDENTITIES:

src/derivepassphrase/_types.py 562)             List identities.  Expecting
src/derivepassphrase/_types.py 563)             [`SSH_AGENT.IDENTITIES_ANSWER`][].

src/derivepassphrase/_types.py 564)         SIGN_REQUEST:

src/derivepassphrase/_types.py 565)             Sign data.  Expecting [`SSH_AGENT.SIGN_RESPONSE`][].

src/derivepassphrase/_types.py 566)         ADD_IDENTITY:
src/derivepassphrase/_types.py 567)             Add an (SSH2) identity.
src/derivepassphrase/_types.py 568)         REMOVE_IDENTITY:
src/derivepassphrase/_types.py 569)             Remove an (SSH2) identity.
src/derivepassphrase/_types.py 570)         ADD_ID_CONSTRAINED:
src/derivepassphrase/_types.py 571)             Add an (SSH2) identity, including key constraints.

src/derivepassphrase/_types.py 572) 
src/derivepassphrase/_types.py 573)     """
src/derivepassphrase/_types.py 574) 
src/derivepassphrase/_types.py 575)     REQUEST_IDENTITIES: int = 11

src/derivepassphrase/_types.py 576)     """"""

src/derivepassphrase/_types.py 577)     SIGN_REQUEST: int = 13

src/derivepassphrase/_types.py 578)     """"""

src/derivepassphrase/_types.py 579)     ADD_IDENTITY: int = 17

src/derivepassphrase/_types.py 580)     """"""

src/derivepassphrase/_types.py 581)     REMOVE_IDENTITY: int = 18

src/derivepassphrase/_types.py 582)     """"""

src/derivepassphrase/_types.py 583)     ADD_ID_CONSTRAINED: int = 25

src/derivepassphrase/_types.py 584)     """"""

src/derivepassphrase/_types.py 585) 
src/derivepassphrase/_types.py 586) 
src/derivepassphrase/_types.py 587) class SSH_AGENT(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 588)     """SSH agent protocol numbers: server replies.
src/derivepassphrase/_types.py 589) 
src/derivepassphrase/_types.py 590)     Attributes:

src/derivepassphrase/_types.py 591)         FAILURE:
src/derivepassphrase/_types.py 592)             Generic failure code.
src/derivepassphrase/_types.py 593)         SUCCESS:
src/derivepassphrase/_types.py 594)             Generic success code.

src/derivepassphrase/_types.py 595)         IDENTITIES_ANSWER:

src/derivepassphrase/_types.py 596)             Successful answer to [`SSH_AGENTC.REQUEST_IDENTITIES`][].

src/derivepassphrase/_types.py 597)         SIGN_RESPONSE:

src/derivepassphrase/_types.py 598)             Successful answer to [`SSH_AGENTC.SIGN_REQUEST`][].

src/derivepassphrase/_types.py 599) 
src/derivepassphrase/_types.py 600)     """
src/derivepassphrase/_types.py 601) 

src/derivepassphrase/_types.py 602)     FAILURE: int = 5

src/derivepassphrase/_types.py 603)     """"""

src/derivepassphrase/_types.py 604)     SUCCESS: int = 6

src/derivepassphrase/_types.py 605)     """"""

src/derivepassphrase/_types.py 606)     IDENTITIES_ANSWER: int = 12

src/derivepassphrase/_types.py 607)     """"""

src/derivepassphrase/_types.py 608)     SIGN_RESPONSE: int = 14