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) 
src/derivepassphrase/types.py   54)     """

src/derivepassphrase/types.py   55) 

src/derivepassphrase/types.py   56)     key: NotRequired[str]

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

src/derivepassphrase/types.py   58)     phrase: NotRequired[str]

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

src/derivepassphrase/_types.py  60)     unicode_normalization_form: NotRequired[
src/derivepassphrase/_types.py  61)         Literal['NFC', 'NFD', 'NFKC', 'NFKD']
src/derivepassphrase/_types.py  62)     ]

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

src/derivepassphrase/types.py   64) 
src/derivepassphrase/types.py   65) 
src/derivepassphrase/types.py   66) class VaultConfigServicesSettings(VaultConfigGlobalSettings, total=False):
src/derivepassphrase/types.py   67)     r"""Configuration for vault: services settings.
src/derivepassphrase/types.py   68) 
src/derivepassphrase/types.py   69)     Attributes:
src/derivepassphrase/types.py   70)         notes:
src/derivepassphrase/types.py   71)             Optional notes for this service, to display to the user when
src/derivepassphrase/types.py   72)             generating the passphrase.
src/derivepassphrase/types.py   73)         length:
src/derivepassphrase/types.py   74)             Desired passphrase length.
src/derivepassphrase/types.py   75)         repeat:
src/derivepassphrase/types.py   76)             The maximum number of immediate character repetitions
src/derivepassphrase/types.py   77)             allowed in the passphrase.  Disabled if set to 0.
src/derivepassphrase/types.py   78)         lower:
src/derivepassphrase/types.py   79)             Optional constraint on ASCII lowercase characters.  If
src/derivepassphrase/types.py   80)             positive, include this many lowercase characters
src/derivepassphrase/types.py   81)             somewhere in the passphrase.  If 0, avoid lowercase
src/derivepassphrase/types.py   82)             characters altogether.
src/derivepassphrase/types.py   83)         upper:
src/derivepassphrase/types.py   84)             Same as `lower`, but for ASCII uppercase characters.
src/derivepassphrase/types.py   85)         number:
src/derivepassphrase/types.py   86)             Same as `lower`, but for ASCII digits.
src/derivepassphrase/types.py   87)         space:
src/derivepassphrase/types.py   88)             Same as `lower`, but for the space character.
src/derivepassphrase/types.py   89)         dash:
src/derivepassphrase/types.py   90)             Same as `lower`, but for the hyphen-minus and underscore
src/derivepassphrase/types.py   91)             characters.
src/derivepassphrase/types.py   92)         symbol:
src/derivepassphrase/types.py   93)             Same as `lower`, but for all other hitherto unlisted
src/derivepassphrase/types.py   94)             ASCII printable characters (except backquote).
src/derivepassphrase/types.py   95) 
src/derivepassphrase/types.py   96)     """

src/derivepassphrase/types.py   97) 

src/derivepassphrase/types.py   98)     notes: NotRequired[str]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/derivepassphrase/types.py  116) 
src/derivepassphrase/types.py  117) 

src/derivepassphrase/types.py  118) _VaultConfig = TypedDict(
src/derivepassphrase/types.py  119)     '_VaultConfig',
src/derivepassphrase/types.py  120)     {'global': NotRequired[VaultConfigGlobalSettings]},
src/derivepassphrase/types.py  121)     total=False,
src/derivepassphrase/types.py  122) )
src/derivepassphrase/types.py  123) 
src/derivepassphrase/types.py  124) 

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

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

src/derivepassphrase/types.py  127) 
src/derivepassphrase/types.py  128)     Usually stored as JSON.
src/derivepassphrase/types.py  129) 
src/derivepassphrase/types.py  130)     Attributes:
src/derivepassphrase/types.py  131)         global (NotRequired[VaultConfigGlobalSettings]):
src/derivepassphrase/types.py  132)             Global settings.
src/derivepassphrase/types.py  133)         services (Required[dict[str, VaultConfigServicesSettings]]):
src/derivepassphrase/types.py  134)             Service-specific settings.
src/derivepassphrase/types.py  135) 
src/derivepassphrase/types.py  136)     """

src/derivepassphrase/types.py  137) 

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

src/derivepassphrase/types.py  140) 

src/derivepassphrase/_types.py 141) def json_path(path: Sequence[str | int], /) -> str:
src/derivepassphrase/_types.py 142)     r"""Transform a series of keys and indices into a JSONPath selector.
src/derivepassphrase/_types.py 143) 
src/derivepassphrase/_types.py 144)     The resulting JSONPath selector conforms to RFC 9535, is always
src/derivepassphrase/_types.py 145)     rooted at the JSON root node (i.e., starts with `$`), and only
src/derivepassphrase/_types.py 146)     contains name and index selectors (in shorthand dot notation, where
src/derivepassphrase/_types.py 147)     possible).
src/derivepassphrase/_types.py 148) 
src/derivepassphrase/_types.py 149)     Args:
src/derivepassphrase/_types.py 150)         path:
src/derivepassphrase/_types.py 151)             A sequence of object keys or array indices to navigate to
src/derivepassphrase/_types.py 152)             the desired JSON value, starting from the root node.
src/derivepassphrase/_types.py 153) 
src/derivepassphrase/_types.py 154)     Returns:
src/derivepassphrase/_types.py 155)         A valid JSONPath selector (a string) identifying the desired
src/derivepassphrase/_types.py 156)         JSON value.
src/derivepassphrase/_types.py 157) 
src/derivepassphrase/_types.py 158)     Examples:
src/derivepassphrase/_types.py 159)         >>> json_path(['global', 'phrase'])
src/derivepassphrase/_types.py 160)         '$.global.phrase'
src/derivepassphrase/_types.py 161)         >>> json_path(['services', 'service name with spaces', 'length'])
src/derivepassphrase/_types.py 162)         '$.services["service name with spaces"].length'
src/derivepassphrase/_types.py 163)         >>> json_path(['services', 'special\u000acharacters', 'notes'])
src/derivepassphrase/_types.py 164)         '$.services["special\\ncharacters"].notes'
src/derivepassphrase/_types.py 165)         >>> print(json_path(['services', 'special\u000acharacters', 'notes']))
src/derivepassphrase/_types.py 166)         $.services["special\ncharacters"].notes
src/derivepassphrase/_types.py 167)         >>> json_path(['custom_array', 2, 0])
src/derivepassphrase/_types.py 168)         '$.custom_array[2][0]'
src/derivepassphrase/_types.py 169) 
src/derivepassphrase/_types.py 170)     """
src/derivepassphrase/_types.py 171) 
src/derivepassphrase/_types.py 172)     def needs_longhand(x: str | int) -> bool:
src/derivepassphrase/_types.py 173)         initial = (
src/derivepassphrase/_types.py 174)             frozenset('abcdefghijklmnopqrstuvwxyz')
src/derivepassphrase/_types.py 175)             | frozenset('ABCDEFGHIJKLMNOPQRSTUVWXYZ')
src/derivepassphrase/_types.py 176)             | frozenset('_')
src/derivepassphrase/_types.py 177)         )
src/derivepassphrase/_types.py 178)         chars = initial | frozenset('0123456789')
src/derivepassphrase/_types.py 179)         return not (
src/derivepassphrase/_types.py 180)             isinstance(x, str)
src/derivepassphrase/_types.py 181)             and x
src/derivepassphrase/_types.py 182)             and set(x).issubset(chars)
src/derivepassphrase/_types.py 183)             and x[:1] in initial
src/derivepassphrase/_types.py 184)         )
src/derivepassphrase/_types.py 185) 
src/derivepassphrase/_types.py 186)     chunks = ['$']
src/derivepassphrase/_types.py 187)     chunks.extend(
src/derivepassphrase/_types.py 188)         f'[{json.dumps(x)}]' if needs_longhand(x) else f'.{x}' for x in path
src/derivepassphrase/_types.py 189)     )
src/derivepassphrase/_types.py 190)     return ''.join(chunks)
src/derivepassphrase/_types.py 191) 
src/derivepassphrase/_types.py 192) 

src/derivepassphrase/_types.py 193) def validate_vault_config(  # noqa: C901,PLR0912,PLR0915
src/derivepassphrase/_types.py 194)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 195)     /,
src/derivepassphrase/_types.py 196)     *,
src/derivepassphrase/_types.py 197)     allow_unknown_settings: bool = False,
src/derivepassphrase/_types.py 198)     allow_derivepassphrase_extensions: bool = False,
src/derivepassphrase/_types.py 199) ) -> None:
src/derivepassphrase/_types.py 200)     """Check that `obj` is a valid vault config.

src/derivepassphrase/types.py  201) 
src/derivepassphrase/types.py  202)     Args:

src/derivepassphrase/_types.py 203)         obj:
src/derivepassphrase/_types.py 204)             The object to test.
src/derivepassphrase/_types.py 205)         allow_unknown_settings:
src/derivepassphrase/_types.py 206)             If false, abort on unknown settings.
src/derivepassphrase/_types.py 207)         allow_derivepassphrase_extensions:
src/derivepassphrase/_types.py 208)             If true, allow `derivepassphrase` extensions.
src/derivepassphrase/_types.py 209) 
src/derivepassphrase/_types.py 210)     Raises:
src/derivepassphrase/_types.py 211)         TypeError:
src/derivepassphrase/_types.py 212)             An entry in the vault config, or the vault config itself,
src/derivepassphrase/_types.py 213)             has the wrong type.
src/derivepassphrase/_types.py 214)         ValueError:
src/derivepassphrase/_types.py 215)             An entry in the vault config is not allowed, or has a
src/derivepassphrase/_types.py 216)             disallowed value.

src/derivepassphrase/types.py  217) 
src/derivepassphrase/types.py  218)     """

src/derivepassphrase/_types.py 219)     err_obj_not_a_dict = 'vault config is not a dict'
src/derivepassphrase/_types.py 220)     err_non_str_service_name = (
src/derivepassphrase/_types.py 221)         'vault config contains non-string service name {!r}'
src/derivepassphrase/_types.py 222)     )
src/derivepassphrase/_types.py 223) 

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

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

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

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

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

src/derivepassphrase/_types.py 234)         return f'vault config entry {json_path_str} is not an integer'
src/derivepassphrase/_types.py 235) 
src/derivepassphrase/_types.py 236)     def err_derivepassphrase_extension(

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

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

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

src/derivepassphrase/_types.py 240)         return (
src/derivepassphrase/_types.py 241)             f'vault config entry {json_path_str} uses '
src/derivepassphrase/_types.py 242)             f'`derivepassphrase` extension {key!r}'
src/derivepassphrase/_types.py 243)         )
src/derivepassphrase/_types.py 244) 

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

src/derivepassphrase/_types.py 247)         return (
src/derivepassphrase/_types.py 248)             f'vault config entry {json_path_str} uses '
src/derivepassphrase/_types.py 249)             f'unknown setting {key!r}'
src/derivepassphrase/_types.py 250)         )
src/derivepassphrase/_types.py 251) 
src/derivepassphrase/_types.py 252)     def err_bad_number(
src/derivepassphrase/_types.py 253)         key: str,

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

src/derivepassphrase/_types.py 255)         /,
src/derivepassphrase/_types.py 256)         *,
src/derivepassphrase/_types.py 257)         strictly_positive: bool = False,
src/derivepassphrase/_types.py 258)     ) -> str:

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

src/derivepassphrase/_types.py 260)         return f'vault config entry {json_path_str} is ' + (
src/derivepassphrase/_types.py 261)             'not positive' if strictly_positive else 'negative'
src/derivepassphrase/_types.py 262)         )
src/derivepassphrase/_types.py 263) 

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

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

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

src/derivepassphrase/types.py  267)     if 'global' in obj:
src/derivepassphrase/types.py  268)         o_global = obj['global']
src/derivepassphrase/types.py  269)         if not isinstance(o_global, dict):

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 279)         queue_to_check.append((service, ('services', sv_name)))
src/derivepassphrase/_types.py 280)     for settings, path in queue_to_check:
src/derivepassphrase/_types.py 281)         for key, value in settings.items():

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

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

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

src/derivepassphrase/_types.py 285)                     raise TypeError(err_not_a_string((*path, key)))
src/derivepassphrase/_types.py 286)             elif key == 'unicode_normalization_form' and path == ('global',):
src/derivepassphrase/_types.py 287)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 288)                     raise TypeError(err_not_a_string((*path, key)))
src/derivepassphrase/_types.py 289)                 if not allow_derivepassphrase_extensions:
src/derivepassphrase/_types.py 290)                     raise ValueError(err_derivepassphrase_extension(key, path))
src/derivepassphrase/_types.py 291)             elif key == 'notes' and path != ('global',):
src/derivepassphrase/_types.py 292)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 293)                     raise TypeError(err_not_a_string((*path, key)))

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

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

src/derivepassphrase/_types.py 297)                 if value < 1:
src/derivepassphrase/_types.py 298)                     raise ValueError(

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

src/derivepassphrase/_types.py 300)                     )
src/derivepassphrase/_types.py 301)             elif key in {
src/derivepassphrase/_types.py 302)                 'repeat',
src/derivepassphrase/_types.py 303)                 'lower',
src/derivepassphrase/_types.py 304)                 'upper',
src/derivepassphrase/_types.py 305)                 'number',
src/derivepassphrase/_types.py 306)                 'space',
src/derivepassphrase/_types.py 307)                 'dash',
src/derivepassphrase/_types.py 308)                 'symbol',
src/derivepassphrase/_types.py 309)             }:
src/derivepassphrase/_types.py 310)                 if not isinstance(value, int):

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

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

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

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

src/derivepassphrase/_types.py 315)                     )

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

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

src/derivepassphrase/_types.py 318) 
src/derivepassphrase/_types.py 319) 
src/derivepassphrase/_types.py 320) def is_vault_config(obj: Any) -> TypeIs[VaultConfig]:  # noqa: ANN401
src/derivepassphrase/_types.py 321)     """Check if `obj` is a valid vault config, according to typing.
src/derivepassphrase/_types.py 322) 
src/derivepassphrase/_types.py 323)     Args:
src/derivepassphrase/_types.py 324)         obj: The object to test.
src/derivepassphrase/_types.py 325) 
src/derivepassphrase/_types.py 326)     Returns:
src/derivepassphrase/_types.py 327)         True if this is a vault config, false otherwise.
src/derivepassphrase/_types.py 328) 
src/derivepassphrase/_types.py 329)     """
src/derivepassphrase/_types.py 330)     try:
src/derivepassphrase/_types.py 331)         validate_vault_config(
src/derivepassphrase/_types.py 332)             obj,
src/derivepassphrase/_types.py 333)             allow_unknown_settings=True,
src/derivepassphrase/_types.py 334)             allow_derivepassphrase_extensions=True,
src/derivepassphrase/_types.py 335)         )
src/derivepassphrase/_types.py 336)     except (TypeError, ValueError) as exc:
src/derivepassphrase/_types.py 337)         if 'vault config ' not in str(exc):  # pragma: no cover
src/derivepassphrase/_types.py 338)             raise  # noqa: DOC501
src/derivepassphrase/_types.py 339)         return False

src/derivepassphrase/types.py  340)     return True

src/derivepassphrase/_types.py 341) 
src/derivepassphrase/_types.py 342) 

src/derivepassphrase/_types.py 343) def js_truthiness(value: Any, /) -> bool:  # noqa: ANN401
src/derivepassphrase/_types.py 344)     """Return the truthiness of the value, according to JavaScript/ECMAScript.
src/derivepassphrase/_types.py 345) 
src/derivepassphrase/_types.py 346)     Like Python, ECMAScript considers certain values to be false in
src/derivepassphrase/_types.py 347)     a boolean context, and every other value to be true.  These
src/derivepassphrase/_types.py 348)     considerations do not agree: ECMAScript considers [`math.nan`][] to
src/derivepassphrase/_types.py 349)     be false too, and empty arrays and objects/dicts to be true,
src/derivepassphrase/_types.py 350)     contrary to Python.  Because of these discrepancies, we cannot defer
src/derivepassphrase/_types.py 351)     to [`bool`][] for ECMAScript truthiness checking, and need
src/derivepassphrase/_types.py 352)     a separate, explicit predicate.
src/derivepassphrase/_types.py 353) 
src/derivepassphrase/_types.py 354)     (Some falsy values in ECMAScript aren't defined in Python:
src/derivepassphrase/_types.py 355)     `undefined`, and `document.all`.  We do not implement support for
src/derivepassphrase/_types.py 356)     those.)
src/derivepassphrase/_types.py 357) 
src/derivepassphrase/_types.py 358)     !!! note
src/derivepassphrase/_types.py 359) 
src/derivepassphrase/_types.py 360)         We cannot use a simple `value not in falsy_values` check,
src/derivepassphrase/_types.py 361)         because [`math.nan`][] behaves in annoying and obstructive ways.
src/derivepassphrase/_types.py 362)         In general, `float('NaN') == float('NaN')` is false, and
src/derivepassphrase/_types.py 363)         `float('NaN') != math.nan` and `math.nan != math.nan` are true.
src/derivepassphrase/_types.py 364)         CPython says `float('NaN') in [math.nan]` is false, PyPy3 says
src/derivepassphrase/_types.py 365)         it is true.  Seemingly the only reliable and portable way to
src/derivepassphrase/_types.py 366)         check for [`math.nan`][] is to use [`math.isnan`][] directly.
src/derivepassphrase/_types.py 367) 
src/derivepassphrase/_types.py 368)     Args:
src/derivepassphrase/_types.py 369)         value: The value to test.
src/derivepassphrase/_types.py 370) 
src/derivepassphrase/_types.py 371)     """  # noqa: RUF002
src/derivepassphrase/_types.py 372)     try:
src/derivepassphrase/_types.py 373)         if value in {None, False, 0, 0.0, ''}:
src/derivepassphrase/_types.py 374)             return False
src/derivepassphrase/_types.py 375)     except TypeError:
src/derivepassphrase/_types.py 376)         # All falsy values are hashable, so this can't be falsy.
src/derivepassphrase/_types.py 377)         return True
src/derivepassphrase/_types.py 378)     return not (isinstance(value, float) and math.isnan(value))
src/derivepassphrase/_types.py 379) 
src/derivepassphrase/_types.py 380) 

src/derivepassphrase/_types.py 381) class CleanupStep(NamedTuple):
src/derivepassphrase/_types.py 382)     """A single executed step during vault config cleanup.
src/derivepassphrase/_types.py 383) 
src/derivepassphrase/_types.py 384)     Attributes:
src/derivepassphrase/_types.py 385)         path:
src/derivepassphrase/_types.py 386)             A sequence of object keys or array indices to navigate to
src/derivepassphrase/_types.py 387)             the JSON value that was cleaned up.
src/derivepassphrase/_types.py 388)         old_value:
src/derivepassphrase/_types.py 389)             The old value.
src/derivepassphrase/_types.py 390)         action:
src/derivepassphrase/_types.py 391)             Either `'replace'` if `old_value` was replaced with
src/derivepassphrase/_types.py 392)             `new_value`, or `'remove'` if `old_value` was removed.
src/derivepassphrase/_types.py 393)         new_value:
src/derivepassphrase/_types.py 394)             The new value.
src/derivepassphrase/_types.py 395) 
src/derivepassphrase/_types.py 396)     """
src/derivepassphrase/_types.py 397) 
src/derivepassphrase/_types.py 398)     path: Sequence[str | int]
src/derivepassphrase/_types.py 399)     """"""
src/derivepassphrase/_types.py 400)     old_value: Any
src/derivepassphrase/_types.py 401)     """"""
src/derivepassphrase/_types.py 402)     action: Literal['replace', 'remove']
src/derivepassphrase/_types.py 403)     """"""
src/derivepassphrase/_types.py 404)     new_value: Any
src/derivepassphrase/_types.py 405)     """"""
src/derivepassphrase/_types.py 406) 
src/derivepassphrase/_types.py 407) 
src/derivepassphrase/_types.py 408) def clean_up_falsy_vault_config_values(  # noqa: C901,PLR0912
src/derivepassphrase/_types.py 409)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 410) ) -> Sequence[CleanupStep] | None:

src/derivepassphrase/_types.py 411)     """Convert falsy values in a vault config to correct types, in-place.
src/derivepassphrase/_types.py 412) 
src/derivepassphrase/_types.py 413)     Needed for compatibility with vault(1), which sometimes uses only
src/derivepassphrase/_types.py 414)     truthiness checks.
src/derivepassphrase/_types.py 415) 
src/derivepassphrase/_types.py 416)     If vault(1) considered `obj` to be valid, then after clean up,
src/derivepassphrase/_types.py 417)     `obj` will be valid as per [`validate_vault_config`][].
src/derivepassphrase/_types.py 418) 
src/derivepassphrase/_types.py 419)     Args:
src/derivepassphrase/_types.py 420)         obj:
src/derivepassphrase/_types.py 421)             A presumed valid vault configuration save for using falsy
src/derivepassphrase/_types.py 422)             values of the wrong type.
src/derivepassphrase/_types.py 423) 

src/derivepassphrase/_types.py 424)     Returns:
src/derivepassphrase/_types.py 425)         A list of 4-tuples `(key_tup, old_value, action, new_value)`,
src/derivepassphrase/_types.py 426)         indicating the cleanup actions performed.  `key_tup` is
src/derivepassphrase/_types.py 427)         a sequence of object keys and/or array indices indicating the
src/derivepassphrase/_types.py 428)         JSON path to the leaf value that was cleaned up, `old_value` is
src/derivepassphrase/_types.py 429)         the old value, `new_value` is the new value, and `action` is
src/derivepassphrase/_types.py 430)         either `replace` (`old_value` was replaced with `new_value`) or
src/derivepassphrase/_types.py 431)         `remove` (`old_value` was removed, and `new_value` is
src/derivepassphrase/_types.py 432)         meaningless).
src/derivepassphrase/_types.py 433) 
src/derivepassphrase/_types.py 434)         If cleanup was never attempted because of an obviously invalid
src/derivepassphrase/_types.py 435)         vault configuration, then `None` is returned, directly.
src/derivepassphrase/_types.py 436) 

src/derivepassphrase/_types.py 437)     """
src/derivepassphrase/_types.py 438)     if (  # pragma: no cover
src/derivepassphrase/_types.py 439)         not isinstance(obj, dict)
src/derivepassphrase/_types.py 440)         or 'services' not in obj
src/derivepassphrase/_types.py 441)         or not isinstance(obj['services'], dict)
src/derivepassphrase/_types.py 442)     ):
src/derivepassphrase/_types.py 443)         # config is invalid

src/derivepassphrase/_types.py 444)         return None
src/derivepassphrase/_types.py 445)     service_objects: MutableSequence[
src/derivepassphrase/_types.py 446)         tuple[Sequence[str | int], dict[str, Any]]
src/derivepassphrase/_types.py 447)     ] = collections.deque()

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

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

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

src/derivepassphrase/_types.py 453)             return None
src/derivepassphrase/_types.py 454)     service_objects.extend(
src/derivepassphrase/_types.py 455)         (['services', sv], val) for sv, val in obj['services'].items()
src/derivepassphrase/_types.py 456)     )
src/derivepassphrase/_types.py 457)     if not all(  # pragma: no cover
src/derivepassphrase/_types.py 458)         isinstance(service_obj, dict) for _, service_obj in service_objects
src/derivepassphrase/_types.py 459)     ):
src/derivepassphrase/_types.py 460)         # config is invalid
src/derivepassphrase/_types.py 461)         return None
src/derivepassphrase/_types.py 462)     cleanup_completed: MutableSequence[CleanupStep] = collections.deque()
src/derivepassphrase/_types.py 463)     for path, service_obj in service_objects:

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

src/derivepassphrase/_types.py 467)                 if not js_truthiness(value) and value != '':  # noqa: PLC1901
src/derivepassphrase/_types.py 468)                     cleanup_completed.append(
src/derivepassphrase/_types.py 469)                         CleanupStep(
src/derivepassphrase/_types.py 470)                             (*path, key), service_obj[key], 'replace', ''
src/derivepassphrase/_types.py 471)                         )
src/derivepassphrase/_types.py 472)                     )

src/derivepassphrase/_types.py 473)                     service_obj[key] = ''
src/derivepassphrase/_types.py 474)             elif key in {'notes', 'key', 'length', 'repeat'}:
src/derivepassphrase/_types.py 475)                 if not js_truthiness(value):

src/derivepassphrase/_types.py 476)                     cleanup_completed.append(
src/derivepassphrase/_types.py 477)                         CleanupStep(
src/derivepassphrase/_types.py 478)                             (*path, key), service_obj[key], 'remove', None
src/derivepassphrase/_types.py 479)                         )
src/derivepassphrase/_types.py 480)                     )

src/derivepassphrase/_types.py 481)                     service_obj.pop(key)
src/derivepassphrase/_types.py 482)             elif key in {  # noqa: SIM102
src/derivepassphrase/_types.py 483)                 'lower',
src/derivepassphrase/_types.py 484)                 'upper',
src/derivepassphrase/_types.py 485)                 'number',
src/derivepassphrase/_types.py 486)                 'space',
src/derivepassphrase/_types.py 487)                 'dash',
src/derivepassphrase/_types.py 488)                 'symbol',
src/derivepassphrase/_types.py 489)             }:
src/derivepassphrase/_types.py 490)                 if not js_truthiness(value) and value != 0:

src/derivepassphrase/_types.py 491)                     cleanup_completed.append(
src/derivepassphrase/_types.py 492)                         CleanupStep(
src/derivepassphrase/_types.py 493)                             (*path, key), service_obj[key], 'replace', 0
src/derivepassphrase/_types.py 494)                         )
src/derivepassphrase/_types.py 495)                     )

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

src/derivepassphrase/_types.py 497)     return cleanup_completed

src/derivepassphrase/_types.py 498) 
src/derivepassphrase/_types.py 499) 

src/derivepassphrase/_types.py 500) class KeyCommentPair(NamedTuple):
src/derivepassphrase/_types.py 501)     """SSH key plus comment pair.  For typing purposes.
src/derivepassphrase/_types.py 502) 
src/derivepassphrase/_types.py 503)     Attributes:
src/derivepassphrase/_types.py 504)         key: SSH key.
src/derivepassphrase/_types.py 505)         comment: SSH key comment.
src/derivepassphrase/_types.py 506) 
src/derivepassphrase/_types.py 507)     """
src/derivepassphrase/_types.py 508) 
src/derivepassphrase/_types.py 509)     key: bytes | bytearray

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

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

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

src/derivepassphrase/_types.py 513) 
src/derivepassphrase/_types.py 514) 
src/derivepassphrase/_types.py 515) class SSH_AGENTC(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 516)     """SSH agent protocol numbers: client requests.
src/derivepassphrase/_types.py 517) 
src/derivepassphrase/_types.py 518)     Attributes:
src/derivepassphrase/_types.py 519)         REQUEST_IDENTITIES:

src/derivepassphrase/_types.py 520)             List identities.  Expecting
src/derivepassphrase/_types.py 521)             [`SSH_AGENT.IDENTITIES_ANSWER`][].

src/derivepassphrase/_types.py 522)         SIGN_REQUEST:

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

src/derivepassphrase/_types.py 524)         ADD_IDENTITY:
src/derivepassphrase/_types.py 525)             Add an (SSH2) identity.
src/derivepassphrase/_types.py 526)         REMOVE_IDENTITY:
src/derivepassphrase/_types.py 527)             Remove an (SSH2) identity.
src/derivepassphrase/_types.py 528)         ADD_ID_CONSTRAINED:
src/derivepassphrase/_types.py 529)             Add an (SSH2) identity, including key constraints.

src/derivepassphrase/_types.py 530) 
src/derivepassphrase/_types.py 531)     """
src/derivepassphrase/_types.py 532) 
src/derivepassphrase/_types.py 533)     REQUEST_IDENTITIES: int = 11

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

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 543) 
src/derivepassphrase/_types.py 544) 
src/derivepassphrase/_types.py 545) class SSH_AGENT(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 546)     """SSH agent protocol numbers: server replies.
src/derivepassphrase/_types.py 547) 
src/derivepassphrase/_types.py 548)     Attributes:

src/derivepassphrase/_types.py 549)         FAILURE:
src/derivepassphrase/_types.py 550)             Generic failure code.
src/derivepassphrase/_types.py 551)         SUCCESS:
src/derivepassphrase/_types.py 552)             Generic success code.

src/derivepassphrase/_types.py 553)         IDENTITIES_ANSWER:

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

src/derivepassphrase/_types.py 555)         SIGN_RESPONSE:

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

src/derivepassphrase/_types.py 557) 
src/derivepassphrase/_types.py 558)     """
src/derivepassphrase/_types.py 559) 

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

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

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

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

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

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

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