1#!/usr/bin/env python3
2"""
3
4"""
5# ruff: noqa: ANN401
6##-- builtin imports
7from __future__ import annotations
8
9import datetime
10import enum
11import functools as ftz
12import itertools as itz
13import logging as logmod
14import pathlib as pl
15import re
16import time
17import types as types_
18import weakref
19from uuid import UUID, uuid1
20
21##-- end builtin imports
22
23from ..proxies.failure import GuardFailureProxy
24from ..errors import GuardedAccessError
25
26# ##-- types
27# isort: off
28import abc
29import collections.abc
30from typing import TYPE_CHECKING, cast, assert_type, assert_never
31from typing import Generic, NewType
32# Protocols:
33from typing import Protocol, runtime_checkable
34# Typing Decorators:
35from typing import no_type_check, final, override, overload
36
37if TYPE_CHECKING:
38 from ..proxies.base import GuardProxy
39 from jgdv import Maybe
40 from typing import Final
41 from typing import ClassVar, Any, LiteralString
42 from typing import Never, Self, Literal
43 from typing import TypeGuard
44 from collections.abc import Iterable, Iterator, Callable, Generator
45 from collections.abc import Sequence, Mapping, MutableMapping, Hashable
46
47 from .. import ChainGuard
48
49##--|
50
51# isort: on
52# ##-- end types
53
54##-- logging
55logging = logmod.getLogger(__name__)
56##-- end logging
57
[docs]
58class GuardProxyEntry_m:
59 """ A Mixin to add to GuardBase.
60 enables handling a number of conditions when accessing values in the underlying data.
61 eg:
62 tg.on_fail(2, int).a.value() # either get a.value, or 2. whichever returns has to be an int.
63 """
64
[docs]
65 def on_fail(self:ChainGuard, fallback:Any=(), types:Maybe=None, *, non_root:bool=False) -> GuardFailureProxy: # type: ignore[misc]
66 """
67 use a fallback value in an access chain,
68 eg: doot.config.on_fail("blah").this.doesnt.exist() -> "blah"
69
70 *without* throwing a GuardedAccessError
71 """
72 index = self._index()
73 if index != ("<root>",) and not non_root:
74 msg = "On Fail not declared at entry"
75 raise GuardedAccessError(msg, index)
76
77 return GuardFailureProxy(self, types=types, fallback=fallback)
78
[docs]
79 def first_of(self:ChainGuard, fallback:Any, types:Maybe=None) -> GuardProxy: # type: ignore[misc]
80 """
81 get the first non-None value from a index path, even across arrays of tables
82 so instead of: data.a.b.c[0].d
83 just: data.first_of().a.b.c.d()
84 """
85 raise NotImplementedError()
86
[docs]
87 def all_of(self:ChainGuard, fallback:Any, types:Maybe=None) -> GuardProxy: # type: ignore[misc]
88 raise NotImplementedError()
89
[docs]
90 def flatten_on(self:ChainGuard, fallback:Any) -> GuardProxy: # type: ignore[misc]
91 """
92 combine all dicts at the call site to form a single dict
93 """
94 raise NotImplementedError()
95
[docs]
96 def match_on(self:ChainGuard, **kwargs:tuple[str,Any]) -> GuardProxy: # type: ignore[misc]
97 raise NotImplementedError()