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)     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)     ...  # pragma: no cover
src/derivepassphrase/_types.py 230) 
src/derivepassphrase/_types.py 231) 
src/derivepassphrase/_types.py 232) @overload
src/derivepassphrase/_types.py 233) def validate_vault_config(

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

src/derivepassphrase/_types.py 238) ) -> None:
src/derivepassphrase/_types.py 239)     ...  # pragma: no cover
src/derivepassphrase/_types.py 240) 
src/derivepassphrase/_types.py 241) 
src/derivepassphrase/_types.py 242) def validate_vault_config(  # noqa: C901,PLR0912
src/derivepassphrase/_types.py 243)     obj: Any,
src/derivepassphrase/_types.py 244)     /,
src/derivepassphrase/_types.py 245)     *,
src/derivepassphrase/_types.py 246)     allow_unknown_settings: bool = False,

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

src/derivepassphrase/types.py  250) 
src/derivepassphrase/types.py  251)     Args:

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

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

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

src/derivepassphrase/types.py  266) 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 361)                     )

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

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

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

src/derivepassphrase/types.py  386)     return True

src/derivepassphrase/_types.py 387) 
src/derivepassphrase/_types.py 388) 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 528)             elif key == 'length':
src/derivepassphrase/_types.py 529)                 if not js_truthiness(value):
src/derivepassphrase/_types.py 530)                     cleanup_completed.append(
src/derivepassphrase/_types.py 531)                         CleanupStep(
src/derivepassphrase/_types.py 532)                             (*path, key), service_obj[key], 'replace', 20
src/derivepassphrase/_types.py 533)                         )
src/derivepassphrase/_types.py 534)                     )
src/derivepassphrase/_types.py 535)                     service_obj[key] = 20
src/derivepassphrase/_types.py 536)             elif key == 'repeat':
src/derivepassphrase/_types.py 537)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 538)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 539)                 ):
src/derivepassphrase/_types.py 540)                     cleanup_completed.append(
src/derivepassphrase/_types.py 541)                         CleanupStep(
src/derivepassphrase/_types.py 542)                             (*path, key), service_obj[key], 'replace', 0
src/derivepassphrase/_types.py 543)                         )
src/derivepassphrase/_types.py 544)                     )
src/derivepassphrase/_types.py 545)                     service_obj[key] = 0

src/derivepassphrase/_types.py 546)             elif key in {  # noqa: SIM102
src/derivepassphrase/_types.py 547)                 'lower',
src/derivepassphrase/_types.py 548)                 'upper',
src/derivepassphrase/_types.py 549)                 'number',
src/derivepassphrase/_types.py 550)                 'space',
src/derivepassphrase/_types.py 551)                 'dash',
src/derivepassphrase/_types.py 552)                 'symbol',
src/derivepassphrase/_types.py 553)             }:

src/derivepassphrase/_types.py 554)                 if not js_truthiness(value) and not (
src/derivepassphrase/_types.py 555)                     isinstance(value, int) and value == 0
src/derivepassphrase/_types.py 556)                 ):

src/derivepassphrase/_types.py 557)                     cleanup_completed.append(
src/derivepassphrase/_types.py 558)                         CleanupStep(

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

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

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

src/derivepassphrase/_types.py 563)     return cleanup_completed

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

src/derivepassphrase/_types.py 566) class KeyCommentPair(NamedTuple):
src/derivepassphrase/_types.py 567)     """SSH key plus comment pair.  For typing purposes.
src/derivepassphrase/_types.py 568) 
src/derivepassphrase/_types.py 569)     Attributes:
src/derivepassphrase/_types.py 570)         key: SSH key.
src/derivepassphrase/_types.py 571)         comment: SSH key comment.
src/derivepassphrase/_types.py 572) 
src/derivepassphrase/_types.py 573)     """
src/derivepassphrase/_types.py 574) 
src/derivepassphrase/_types.py 575)     key: bytes | bytearray

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

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

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

src/derivepassphrase/_types.py 579) 
src/derivepassphrase/_types.py 580) 
src/derivepassphrase/_types.py 581) class SSH_AGENTC(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 582)     """SSH agent protocol numbers: client requests.
src/derivepassphrase/_types.py 583) 
src/derivepassphrase/_types.py 584)     Attributes:
src/derivepassphrase/_types.py 585)         REQUEST_IDENTITIES:

src/derivepassphrase/_types.py 586)             List identities.  Expecting
src/derivepassphrase/_types.py 587)             [`SSH_AGENT.IDENTITIES_ANSWER`][].

src/derivepassphrase/_types.py 588)         SIGN_REQUEST:

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

src/derivepassphrase/_types.py 590)         ADD_IDENTITY:
src/derivepassphrase/_types.py 591)             Add an (SSH2) identity.
src/derivepassphrase/_types.py 592)         REMOVE_IDENTITY:
src/derivepassphrase/_types.py 593)             Remove an (SSH2) identity.
src/derivepassphrase/_types.py 594)         ADD_ID_CONSTRAINED:
src/derivepassphrase/_types.py 595)             Add an (SSH2) identity, including key constraints.

src/derivepassphrase/_types.py 596)         EXTENSION:
src/derivepassphrase/_types.py 597)             Issue a named request that isn't part of the core agent
src/derivepassphrase/_types.py 598)             protocol.  Expecting [`SSH_AGENT.EXTENSION_RESPONSE`][] or
src/derivepassphrase/_types.py 599)             [`SSH_AGENT.EXTENSION_FAILURE`][] if the named request is
src/derivepassphrase/_types.py 600)             supported, [`SSH_AGENT.FAILURE`][] otherwise.

src/derivepassphrase/_types.py 601) 
src/derivepassphrase/_types.py 602)     """
src/derivepassphrase/_types.py 603) 
src/derivepassphrase/_types.py 604)     REQUEST_IDENTITIES: int = 11

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

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

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

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

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

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

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

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

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

src/derivepassphrase/_types.py 614)     EXTENSION: int = 27
src/derivepassphrase/_types.py 615)     """"""

src/derivepassphrase/_types.py 616) 
src/derivepassphrase/_types.py 617) 
src/derivepassphrase/_types.py 618) class SSH_AGENT(enum.Enum):  # noqa: N801
src/derivepassphrase/_types.py 619)     """SSH agent protocol numbers: server replies.
src/derivepassphrase/_types.py 620) 
src/derivepassphrase/_types.py 621)     Attributes:

src/derivepassphrase/_types.py 622)         FAILURE:
src/derivepassphrase/_types.py 623)             Generic failure code.
src/derivepassphrase/_types.py 624)         SUCCESS:
src/derivepassphrase/_types.py 625)             Generic success code.

src/derivepassphrase/_types.py 626)         IDENTITIES_ANSWER:

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

src/derivepassphrase/_types.py 628)         SIGN_RESPONSE:

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

src/derivepassphrase/_types.py 630)         EXTENSION_FAILURE:
src/derivepassphrase/_types.py 631)             Unsuccessful answer to [`SSH_AGENTC.EXTENSION`][].
src/derivepassphrase/_types.py 632)         EXTENSION_RESPONSE:
src/derivepassphrase/_types.py 633)             Successful answer to [`SSH_AGENTC.EXTENSION`][].

src/derivepassphrase/_types.py 634) 
src/derivepassphrase/_types.py 635)     """
src/derivepassphrase/_types.py 636) 

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

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

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

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

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

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

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

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