derivepassphrase.git

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

src/derivepassphrase/types.py    2) #

src/derivepassphrase/_types.py   3) # SPDX-License-Identifier: Zlib

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)     deprecated,
src/derivepassphrase/_types.py  20)     overload,

src/derivepassphrase/types.py   21) )

src/derivepassphrase/types.py   22) 

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

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

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

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

src/derivepassphrase/types.py   40) 

src/derivepassphrase/types.py   41) 

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

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

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

src/derivepassphrase/types.py   79) 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/derivepassphrase/types.py  104) 
src/derivepassphrase/types.py  105) 

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

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

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

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

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

src/derivepassphrase/types.py  161) 

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

src/derivepassphrase/types.py  164) 

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

src/derivepassphrase/_types.py 217) @overload
src/derivepassphrase/_types.py 218) @deprecated(
src/derivepassphrase/_types.py 219)     'allow_derivepassphrase_extensions argument is deprecated since v0.4.0, '
src/derivepassphrase/_types.py 220)     'to be removed in v1.0: no extensions are defined'
src/derivepassphrase/_types.py 221) )
src/derivepassphrase/_types.py 222) def validate_vault_config(
src/derivepassphrase/_types.py 223)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 224)     /,
src/derivepassphrase/_types.py 225)     *,
src/derivepassphrase/_types.py 226)     allow_derivepassphrase_extensions: bool,
src/derivepassphrase/_types.py 227)     allow_unknown_settings: bool = False,

src/derivepassphrase/_types.py 228) ) -> None: ...

src/derivepassphrase/_types.py 229) 
src/derivepassphrase/_types.py 230) 
src/derivepassphrase/_types.py 231) @overload
src/derivepassphrase/_types.py 232) def validate_vault_config(

src/derivepassphrase/_types.py 233)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 234)     /,
src/derivepassphrase/_types.py 235)     *,
src/derivepassphrase/_types.py 236)     allow_unknown_settings: bool = False,

src/derivepassphrase/_types.py 237) ) -> None: ...

src/derivepassphrase/_types.py 238) 
src/derivepassphrase/_types.py 239) 
src/derivepassphrase/_types.py 240) def validate_vault_config(  # noqa: C901,PLR0912
src/derivepassphrase/_types.py 241)     obj: Any,
src/derivepassphrase/_types.py 242)     /,
src/derivepassphrase/_types.py 243)     *,
src/derivepassphrase/_types.py 244)     allow_unknown_settings: bool = False,

src/derivepassphrase/_types.py 245)     allow_derivepassphrase_extensions: bool = False,
src/derivepassphrase/_types.py 246) ) -> None:
src/derivepassphrase/_types.py 247)     """Check that `obj` is a valid vault config.

src/derivepassphrase/types.py  248) 
src/derivepassphrase/types.py  249)     Args:

src/derivepassphrase/_types.py 250)         obj:
src/derivepassphrase/_types.py 251)             The object to test.
src/derivepassphrase/_types.py 252)         allow_unknown_settings:
src/derivepassphrase/_types.py 253)             If false, abort on unknown settings.
src/derivepassphrase/_types.py 254)         allow_derivepassphrase_extensions:

src/derivepassphrase/_types.py 255)             (Deprecated.)  Ignored since v0.4.0.

src/derivepassphrase/_types.py 256) 
src/derivepassphrase/_types.py 257)     Raises:
src/derivepassphrase/_types.py 258)         TypeError:
src/derivepassphrase/_types.py 259)             An entry in the vault config, or the vault config itself,
src/derivepassphrase/_types.py 260)             has the wrong type.
src/derivepassphrase/_types.py 261)         ValueError:
src/derivepassphrase/_types.py 262)             An entry in the vault config is not allowed, or has a
src/derivepassphrase/_types.py 263)             disallowed value.

src/derivepassphrase/types.py  264) 

src/derivepassphrase/_types.py 265)     Deprecated:
src/derivepassphrase/_types.py 266)         Since v0.4.0: The `allow_derivepassphrase_extensions` keyword
src/derivepassphrase/_types.py 267)         argument is deprecated, and will be removed in v1.0.  There are
src/derivepassphrase/_types.py 268)         no specified `derivepassphrase` extensions.
src/derivepassphrase/_types.py 269) 

src/derivepassphrase/types.py  270)     """

src/derivepassphrase/_types.py 271)     err_obj_not_a_dict = 'vault config is not a dict'
src/derivepassphrase/_types.py 272)     err_non_str_service_name = (
src/derivepassphrase/_types.py 273)         'vault config contains non-string service name {!r}'
src/derivepassphrase/_types.py 274)     )
src/derivepassphrase/_types.py 275) 

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

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

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

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

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

src/derivepassphrase/_types.py 286)         return f'vault config entry {json_path_str} is not an integer'
src/derivepassphrase/_types.py 287) 

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

src/derivepassphrase/_types.py 290)         return (
src/derivepassphrase/_types.py 291)             f'vault config entry {json_path_str} uses '
src/derivepassphrase/_types.py 292)             f'unknown setting {key!r}'
src/derivepassphrase/_types.py 293)         )
src/derivepassphrase/_types.py 294) 
src/derivepassphrase/_types.py 295)     def err_bad_number(
src/derivepassphrase/_types.py 296)         key: str,

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

src/derivepassphrase/_types.py 298)         /,
src/derivepassphrase/_types.py 299)         *,
src/derivepassphrase/_types.py 300)         strictly_positive: bool = False,
src/derivepassphrase/_types.py 301)     ) -> str:

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

src/derivepassphrase/_types.py 303)         return f'vault config entry {json_path_str} is ' + (
src/derivepassphrase/_types.py 304)             'not positive' if strictly_positive else 'negative'
src/derivepassphrase/_types.py 305)         )
src/derivepassphrase/_types.py 306) 

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

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

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

src/derivepassphrase/types.py  310)     if 'global' in obj:
src/derivepassphrase/types.py  311)         o_global = obj['global']
src/derivepassphrase/types.py  312)         if not isinstance(o_global, dict):

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 322)         queue_to_check.append((service, ('services', sv_name)))
src/derivepassphrase/_types.py 323)     for settings, path in queue_to_check:
src/derivepassphrase/_types.py 324)         for key, value in settings.items():

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

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

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

src/derivepassphrase/_types.py 328)                     raise TypeError(err_not_a_string((*path, key)))
src/derivepassphrase/_types.py 329)             elif key == 'unicode_normalization_form' and path == ('global',):
src/derivepassphrase/_types.py 330)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 331)                     raise TypeError(err_not_a_string((*path, key)))

src/derivepassphrase/_types.py 332)                 if (
src/derivepassphrase/_types.py 333)                     not allow_derivepassphrase_extensions
src/derivepassphrase/_types.py 334)                     and not allow_unknown_settings
src/derivepassphrase/_types.py 335)                 ):
src/derivepassphrase/_types.py 336)                     raise ValueError(err_unknown_setting(key, path))

src/derivepassphrase/_types.py 337)             elif key == 'notes' and path != ('global',):
src/derivepassphrase/_types.py 338)                 if not isinstance(value, str):
src/derivepassphrase/_types.py 339)                     raise TypeError(err_not_a_string((*path, key)))

src/derivepassphrase/_types.py 340)             elif key in {

src/derivepassphrase/_types.py 341)                 'length',

src/derivepassphrase/_types.py 342)                 'repeat',
src/derivepassphrase/_types.py 343)                 'lower',
src/derivepassphrase/_types.py 344)                 'upper',
src/derivepassphrase/_types.py 345)                 'number',
src/derivepassphrase/_types.py 346)                 'space',
src/derivepassphrase/_types.py 347)                 'dash',
src/derivepassphrase/_types.py 348)                 'symbol',
src/derivepassphrase/_types.py 349)             }:
src/derivepassphrase/_types.py 350)                 if not isinstance(value, int):

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

src/derivepassphrase/_types.py 352)                 if key == 'length' and value < 1:
src/derivepassphrase/_types.py 353)                     raise ValueError(
src/derivepassphrase/_types.py 354)                         err_bad_number(key, path, strictly_positive=True)
src/derivepassphrase/_types.py 355)                     )
src/derivepassphrase/_types.py 356)                 if key != 'length' and value < 0:

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

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

src/derivepassphrase/_types.py 359)                     )

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

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

src/derivepassphrase/_types.py 362) 
src/derivepassphrase/_types.py 363) 
src/derivepassphrase/_types.py 364) def is_vault_config(obj: Any) -> TypeIs[VaultConfig]:  # noqa: ANN401
src/derivepassphrase/_types.py 365)     """Check if `obj` is a valid vault config, according to typing.
src/derivepassphrase/_types.py 366) 
src/derivepassphrase/_types.py 367)     Args:
src/derivepassphrase/_types.py 368)         obj: The object to test.
src/derivepassphrase/_types.py 369) 
src/derivepassphrase/_types.py 370)     Returns:
src/derivepassphrase/_types.py 371)         True if this is a vault config, false otherwise.
src/derivepassphrase/_types.py 372) 
src/derivepassphrase/_types.py 373)     """
src/derivepassphrase/_types.py 374)     try:
src/derivepassphrase/_types.py 375)         validate_vault_config(
src/derivepassphrase/_types.py 376)             obj,
src/derivepassphrase/_types.py 377)             allow_unknown_settings=True,
src/derivepassphrase/_types.py 378)             allow_derivepassphrase_extensions=True,
src/derivepassphrase/_types.py 379)         )
src/derivepassphrase/_types.py 380)     except (TypeError, ValueError) as exc:
src/derivepassphrase/_types.py 381)         if 'vault config ' not in str(exc):  # pragma: no cover
src/derivepassphrase/_types.py 382)             raise  # noqa: DOC501
src/derivepassphrase/_types.py 383)         return False

src/derivepassphrase/types.py  384)     return True

src/derivepassphrase/_types.py 385) 
src/derivepassphrase/_types.py 386) 

src/derivepassphrase/_types.py 387) def js_truthiness(value: Any, /) -> bool:  # noqa: ANN401
src/derivepassphrase/_types.py 388)     """Return the truthiness of the value, according to JavaScript/ECMAScript.
src/derivepassphrase/_types.py 389) 
src/derivepassphrase/_types.py 390)     Like Python, ECMAScript considers certain values to be false in
src/derivepassphrase/_types.py 391)     a boolean context, and every other value to be true.  These
src/derivepassphrase/_types.py 392)     considerations do not agree: ECMAScript considers [`math.nan`][] to
src/derivepassphrase/_types.py 393)     be false too, and empty arrays and objects/dicts to be true,
src/derivepassphrase/_types.py 394)     contrary to Python.  Because of these discrepancies, we cannot defer
src/derivepassphrase/_types.py 395)     to [`bool`][] for ECMAScript truthiness checking, and need
src/derivepassphrase/_types.py 396)     a separate, explicit predicate.
src/derivepassphrase/_types.py 397) 
src/derivepassphrase/_types.py 398)     (Some falsy values in ECMAScript aren't defined in Python:
src/derivepassphrase/_types.py 399)     `undefined`, and `document.all`.  We do not implement support for
src/derivepassphrase/_types.py 400)     those.)
src/derivepassphrase/_types.py 401) 
src/derivepassphrase/_types.py 402)     !!! note
src/derivepassphrase/_types.py 403) 
src/derivepassphrase/_types.py 404)         We cannot use a simple `value not in falsy_values` check,
src/derivepassphrase/_types.py 405)         because [`math.nan`][] behaves in annoying and obstructive ways.
src/derivepassphrase/_types.py 406)         In general, `float('NaN') == float('NaN')` is false, and
src/derivepassphrase/_types.py 407)         `float('NaN') != math.nan` and `math.nan != math.nan` are true.
src/derivepassphrase/_types.py 408)         CPython says `float('NaN') in [math.nan]` is false, PyPy3 says
src/derivepassphrase/_types.py 409)         it is true.  Seemingly the only reliable and portable way to
src/derivepassphrase/_types.py 410)         check for [`math.nan`][] is to use [`math.isnan`][] directly.
src/derivepassphrase/_types.py 411) 
src/derivepassphrase/_types.py 412)     Args:
src/derivepassphrase/_types.py 413)         value: The value to test.
src/derivepassphrase/_types.py 414) 
src/derivepassphrase/_types.py 415)     """  # noqa: RUF002
src/derivepassphrase/_types.py 416)     try:
src/derivepassphrase/_types.py 417)         if value in {None, False, 0, 0.0, ''}:
src/derivepassphrase/_types.py 418)             return False
src/derivepassphrase/_types.py 419)     except TypeError:
src/derivepassphrase/_types.py 420)         # All falsy values are hashable, so this can't be falsy.
src/derivepassphrase/_types.py 421)         return True
src/derivepassphrase/_types.py 422)     return not (isinstance(value, float) and math.isnan(value))
src/derivepassphrase/_types.py 423) 
src/derivepassphrase/_types.py 424) 

src/derivepassphrase/_types.py 425) class CleanupStep(NamedTuple):
src/derivepassphrase/_types.py 426)     """A single executed step during vault config cleanup.
src/derivepassphrase/_types.py 427) 
src/derivepassphrase/_types.py 428)     Attributes:
src/derivepassphrase/_types.py 429)         path:
src/derivepassphrase/_types.py 430)             A sequence of object keys or array indices to navigate to
src/derivepassphrase/_types.py 431)             the JSON value that was cleaned up.
src/derivepassphrase/_types.py 432)         old_value:
src/derivepassphrase/_types.py 433)             The old value.
src/derivepassphrase/_types.py 434)         action:
src/derivepassphrase/_types.py 435)             Either `'replace'` if `old_value` was replaced with
src/derivepassphrase/_types.py 436)             `new_value`, or `'remove'` if `old_value` was removed.
src/derivepassphrase/_types.py 437)         new_value:
src/derivepassphrase/_types.py 438)             The new value.
src/derivepassphrase/_types.py 439) 
src/derivepassphrase/_types.py 440)     """
src/derivepassphrase/_types.py 441) 
src/derivepassphrase/_types.py 442)     path: Sequence[str | int]
src/derivepassphrase/_types.py 443)     """"""
src/derivepassphrase/_types.py 444)     old_value: Any
src/derivepassphrase/_types.py 445)     """"""
src/derivepassphrase/_types.py 446)     action: Literal['replace', 'remove']
src/derivepassphrase/_types.py 447)     """"""
src/derivepassphrase/_types.py 448)     new_value: Any
src/derivepassphrase/_types.py 449)     """"""
src/derivepassphrase/_types.py 450) 
src/derivepassphrase/_types.py 451) 
src/derivepassphrase/_types.py 452) def clean_up_falsy_vault_config_values(  # noqa: C901,PLR0912
src/derivepassphrase/_types.py 453)     obj: Any,  # noqa: ANN401
src/derivepassphrase/_types.py 454) ) -> Sequence[CleanupStep] | None:

src/derivepassphrase/_types.py 455)     """Convert falsy values in a vault config to correct types, in-place.
src/derivepassphrase/_types.py 456) 
src/derivepassphrase/_types.py 457)     Needed for compatibility with vault(1), which sometimes uses only
src/derivepassphrase/_types.py 458)     truthiness checks.
src/derivepassphrase/_types.py 459) 
src/derivepassphrase/_types.py 460)     If vault(1) considered `obj` to be valid, then after clean up,
src/derivepassphrase/_types.py 461)     `obj` will be valid as per [`validate_vault_config`][].
src/derivepassphrase/_types.py 462) 
src/derivepassphrase/_types.py 463)     Args:
src/derivepassphrase/_types.py 464)         obj:
src/derivepassphrase/_types.py 465)             A presumed valid vault configuration save for using falsy
src/derivepassphrase/_types.py 466)             values of the wrong type.
src/derivepassphrase/_types.py 467) 

src/derivepassphrase/_types.py 468)     Returns:
src/derivepassphrase/_types.py 469)         A list of 4-tuples `(key_tup, old_value, action, new_value)`,
src/derivepassphrase/_types.py 470)         indicating the cleanup actions performed.  `key_tup` is
src/derivepassphrase/_types.py 471)         a sequence of object keys and/or array indices indicating the
src/derivepassphrase/_types.py 472)         JSON path to the leaf value that was cleaned up, `old_value` is
src/derivepassphrase/_types.py 473)         the old value, `new_value` is the new value, and `action` is
src/derivepassphrase/_types.py 474)         either `replace` (`old_value` was replaced with `new_value`) or
src/derivepassphrase/_types.py 475)         `remove` (`old_value` was removed, and `new_value` is
src/derivepassphrase/_types.py 476)         meaningless).
src/derivepassphrase/_types.py 477) 
src/derivepassphrase/_types.py 478)         If cleanup was never attempted because of an obviously invalid
src/derivepassphrase/_types.py 479)         vault configuration, then `None` is returned, directly.
src/derivepassphrase/_types.py 480) 

src/derivepassphrase/_types.py 481)     """
src/derivepassphrase/_types.py 482)     if (  # pragma: no cover
src/derivepassphrase/_types.py 483)         not isinstance(obj, dict)
src/derivepassphrase/_types.py 484)         or 'services' not in obj
src/derivepassphrase/_types.py 485)         or not isinstance(obj['services'], dict)
src/derivepassphrase/_types.py 486)     ):
src/derivepassphrase/_types.py 487)         # config is invalid

src/derivepassphrase/_types.py 488)         return None
src/derivepassphrase/_types.py 489)     service_objects: MutableSequence[
src/derivepassphrase/_types.py 490)         tuple[Sequence[str | int], dict[str, Any]]
src/derivepassphrase/_types.py 491)     ] = collections.deque()

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

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

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

src/derivepassphrase/_types.py 497)             return None
src/derivepassphrase/_types.py 498)     service_objects.extend(
src/derivepassphrase/_types.py 499)         (['services', sv], val) for sv, val in obj['services'].items()
src/derivepassphrase/_types.py 500)     )
src/derivepassphrase/_types.py 501)     if not all(  # pragma: no cover
src/derivepassphrase/_types.py 502)         isinstance(service_obj, dict) for _, service_obj in service_objects
src/derivepassphrase/_types.py 503)     ):
src/derivepassphrase/_types.py 504)         # config is invalid
src/derivepassphrase/_types.py 505)         return None
src/derivepassphrase/_types.py 506)     cleanup_completed: MutableSequence[CleanupStep] = collections.deque()
src/derivepassphrase/_types.py 507)     for path, service_obj in service_objects:

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

src/derivepassphrase/_types.py 511)                 if not js_truthiness(value) and value != '':  # noqa: PLC1901
src/derivepassphrase/_types.py 512)                     cleanup_completed.append(
src/derivepassphrase/_types.py 513)                         CleanupStep(
src/derivepassphrase/_types.py 514)                             (*path, key), service_obj[key], 'replace', ''
src/derivepassphrase/_types.py 515)                         )
src/derivepassphrase/_types.py 516)                     )

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

src/derivepassphrase/_types.py 518)             elif key == 'notes':

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

src/derivepassphrase/_types.py 520)                     cleanup_completed.append(
src/derivepassphrase/_types.py 521)                         CleanupStep(
src/derivepassphrase/_types.py 522)                             (*path, key), service_obj[key], 'remove', None
src/derivepassphrase/_types.py 523)                         )
src/derivepassphrase/_types.py 524)                     )

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

src/derivepassphrase/_types.py 526)             elif key == 'key':
src/derivepassphrase/_types.py 527)                 if not js_truthiness(value):
src/derivepassphrase/_types.py 528)                     if path == ['global']:
src/derivepassphrase/_types.py 529)                         cleanup_completed.append(
src/derivepassphrase/_types.py 530)                             CleanupStep(
src/derivepassphrase/_types.py 531)                                 (*path, key), service_obj[key], 'remove', None
src/derivepassphrase/_types.py 532)                             )
src/derivepassphrase/_types.py 533)                         )
src/derivepassphrase/_types.py 534)                         service_obj.pop(key)
src/derivepassphrase/_types.py 535)                     else:
src/derivepassphrase/_types.py 536)                         cleanup_completed.append(
src/derivepassphrase/_types.py 537)                             CleanupStep(
src/derivepassphrase/_types.py 538)                                 (*path, key), service_obj[key], 'replace', ''
src/derivepassphrase/_types.py 539)                             )
src/derivepassphrase/_types.py 540)                         )
src/derivepassphrase/_types.py 541)                         service_obj[key] = ''

src/derivepassphrase/_types.py 542)             elif key == 'length':
src/derivepassphrase/_types.py 543)                 if not js_truthiness(value):
src/derivepassphrase/_types.py 544)                     cleanup_completed.append(
src/derivepassphrase/_types.py 545)                         CleanupStep(
src/derivepassphrase/_types.py 546)                             (*path, key), service_obj[key], 'replace', 20
src/derivepassphrase/_types.py 547)                         )
src/derivepassphrase/_types.py 548)                     )
src/derivepassphrase/_types.py 549)                     service_obj[key] = 20
src/derivepassphrase/_types.py 550)             elif key == 'repeat':
src/derivepassphrase/_types.py 551)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 552)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 553)                 ):
src/derivepassphrase/_types.py 554)                     cleanup_completed.append(
src/derivepassphrase/_types.py 555)                         CleanupStep(
src/derivepassphrase/_types.py 556)                             (*path, key), service_obj[key], 'replace', 0
src/derivepassphrase/_types.py 557)                         )
src/derivepassphrase/_types.py 558)                     )
src/derivepassphrase/_types.py 559)                     service_obj[key] = 0

src/derivepassphrase/_types.py 560)             elif key in {  # noqa: SIM102
src/derivepassphrase/_types.py 561)                 'lower',
src/derivepassphrase/_types.py 562)                 'upper',
src/derivepassphrase/_types.py 563)                 'number',
src/derivepassphrase/_types.py 564)                 'space',
src/derivepassphrase/_types.py 565)                 'dash',
src/derivepassphrase/_types.py 566)                 'symbol',
src/derivepassphrase/_types.py 567)             }:

src/derivepassphrase/_types.py 568)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 569)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 570)                 ):

src/derivepassphrase/_types.py 571)                     cleanup_completed.append(
src/derivepassphrase/_types.py 572)                         CleanupStep(

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

src/derivepassphrase/_types.py 574)                         )
src/derivepassphrase/_types.py 575)                     )

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

src/derivepassphrase/_types.py 577)     return cleanup_completed

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

src/derivepassphrase/_types.py 580) class KeyCommentPair(NamedTuple):
src/derivepassphrase/_types.py 581)     """SSH key plus comment pair.  For typing purposes.
src/derivepassphrase/_types.py 582) 
src/derivepassphrase/_types.py 583)     Attributes:
src/derivepassphrase/_types.py 584)         key: SSH key.
src/derivepassphrase/_types.py 585)         comment: SSH key comment.
src/derivepassphrase/_types.py 586) 
src/derivepassphrase/_types.py 587)     """
src/derivepassphrase/_types.py 588) 
src/derivepassphrase/_types.py 589)     key: bytes | bytearray

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

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

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

src/derivepassphrase/_types.py 593) 
src/derivepassphrase/_types.py 594) 
src/derivepassphrase/_types.py 595) class SSH_AGENTC(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 596)     """SSH agent protocol numbers: client requests.
src/derivepassphrase/_types.py 597) 
src/derivepassphrase/_types.py 598)     Attributes:
src/derivepassphrase/_types.py 599)         REQUEST_IDENTITIES:

src/derivepassphrase/_types.py 600)             List identities.  Expecting
src/derivepassphrase/_types.py 601)             [`SSH_AGENT.IDENTITIES_ANSWER`][].

src/derivepassphrase/_types.py 602)         SIGN_REQUEST:

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

src/derivepassphrase/_types.py 604)         ADD_IDENTITY:
src/derivepassphrase/_types.py 605)             Add an (SSH2) identity.
src/derivepassphrase/_types.py 606)         REMOVE_IDENTITY:
src/derivepassphrase/_types.py 607)             Remove an (SSH2) identity.
src/derivepassphrase/_types.py 608)         ADD_ID_CONSTRAINED:
src/derivepassphrase/_types.py 609)             Add an (SSH2) identity, including key constraints.

src/derivepassphrase/_types.py 610)         EXTENSION:
src/derivepassphrase/_types.py 611)             Issue a named request that isn't part of the core agent
src/derivepassphrase/_types.py 612)             protocol.  Expecting [`SSH_AGENT.EXTENSION_RESPONSE`][] or
src/derivepassphrase/_types.py 613)             [`SSH_AGENT.EXTENSION_FAILURE`][] if the named request is
src/derivepassphrase/_types.py 614)             supported, [`SSH_AGENT.FAILURE`][] otherwise.

src/derivepassphrase/_types.py 615) 
src/derivepassphrase/_types.py 616)     """
src/derivepassphrase/_types.py 617) 
src/derivepassphrase/_types.py 618)     REQUEST_IDENTITIES: int = 11

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

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 628)     EXTENSION: int = 27
src/derivepassphrase/_types.py 629)     """"""

src/derivepassphrase/_types.py 630) 
src/derivepassphrase/_types.py 631) 
src/derivepassphrase/_types.py 632) class SSH_AGENT(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 633)     """SSH agent protocol numbers: server replies.
src/derivepassphrase/_types.py 634) 
src/derivepassphrase/_types.py 635)     Attributes:

src/derivepassphrase/_types.py 636)         FAILURE:
src/derivepassphrase/_types.py 637)             Generic failure code.
src/derivepassphrase/_types.py 638)         SUCCESS:
src/derivepassphrase/_types.py 639)             Generic success code.

src/derivepassphrase/_types.py 640)         IDENTITIES_ANSWER:

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

src/derivepassphrase/_types.py 642)         SIGN_RESPONSE:

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

src/derivepassphrase/_types.py 644)         EXTENSION_FAILURE:
src/derivepassphrase/_types.py 645)             Unsuccessful answer to [`SSH_AGENTC.EXTENSION`][].
src/derivepassphrase/_types.py 646)         EXTENSION_RESPONSE:
src/derivepassphrase/_types.py 647)             Successful answer to [`SSH_AGENTC.EXTENSION`][].

src/derivepassphrase/_types.py 648) 
src/derivepassphrase/_types.py 649)     """
src/derivepassphrase/_types.py 650) 

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

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

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

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

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

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

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

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