Source code for jgdv.structs.locator._interface

  1#!/usr/bin/env python3
  2"""
  3
  4"""
  5# Imports:
  6from __future__ import annotations
  7
  8# ##-- stdlib imports
  9import enum
 10import functools as ftz
 11import itertools as itz
 12import logging as logmod
 13import re
 14import time
 15import types
 16import collections
 17import contextlib
 18import hashlib
 19from copy import deepcopy
 20from uuid import UUID, uuid1
 21from weakref import ref
 22import atexit # for @atexit.register
 23import faulthandler
 24# ##-- end stdlib imports
 25
 26from jgdv.structs.strang import _interface as StrangAPI # noqa: N812
 27from jgdv.structs.strang._interface import Strang_p
 28
 29# ##-- types
 30# isort: off
 31import abc
 32import collections.abc
 33from typing import TYPE_CHECKING, cast, assert_type, assert_never
 34from typing import Generic, NewType
 35# Protocols:
 36from typing import Protocol, runtime_checkable
 37# Typing Decorators:
 38from typing import no_type_check, final, override, overload
 39
 40if TYPE_CHECKING:
 41    import datetime
 42    import pathlib as pl
 43    from typing import Final
 44    from typing import ClassVar, Any, LiteralString
 45    from typing import Never, Self, Literal
 46    from typing import TypeGuard
 47    from collections.abc import Iterable, Iterator, Callable, Generator
 48    from collections.abc import Sequence, Mapping, MutableMapping, Hashable
 49
 50    from jgdv import Maybe, Ident, Traceback
 51    from jgdv.structs.dkey._interface import Key_p
 52
 53    type TimeDelta = datetime.timedelta
 54    type WordDesc = tuple[StrangAPI.StrangMarkAbstract_e, str]
 55##--|
 56
 57# isort: on
 58# ##-- end types
 59
 60##-- logging
 61logging = logmod.getLogger(__name__)
 62##-- end logging
 63
 64# Vars:
 65LOC_SEP    : Final[str]   = "::>"
 66LOC_SUBSEP : Final[str]   = "/"
 67
 68# Body:
 69

[docs]
 70class WildCard_e(StrangAPI.StrangMarkAbstract_e):
 71    """ Ways a path can have a wildcard. """
 72    glob       = "*"
 73    rec_glob   = "**"
 74    select     = "?"
 75    key        = "{"

 76

[docs]
 77class LocationMeta_e(StrangAPI.StrangMarkAbstract_e):
 78    """ Available metadata attachable to a location """
 79
 80    location     = "location"
 81    directory    = "directory"
 82    file         = "file"
 83
 84    abstract     = "abstract"
 85    artifact     = "artifact"
 86    clean        = "clean"
 87    earlycwd     = "earlycwd"
 88    protect      = "protect"
 89    expand       = "expand"
 90    remote       = "remote"
 91    partial      = "partial"
 92
 93    # Aliases
 94    dir          = directory
 95    loc          = location
 96

[docs]
 97    @override
 98    @classmethod
 99    def default(cls) -> Maybe:
100        return cls.location


101
102##--|
103
104LocationSections : Final[StrangAPI.Sections_d] = StrangAPI.Sections_d(
105    StrangAPI.Sec_d("head", ".", LOC_SEP, str|LocationMeta_e, LocationMeta_e, False),  # noqa: FBT003
106    StrangAPI.Sec_d("body", LOC_SUBSEP, None, str|WildCard_e, WildCard_e, True),  # noqa: FBT003
107)
108##--|
109

[docs]
110@runtime_checkable
111class Location_p(Strang_p, Protocol):
112    """ Something which describes a file system location,
113    with a possible identifier, and metadata
114    """
115    Marks  : ClassVar[StrangAPI.StrangMarkAbstract_e]
116    Wild   : ClassVar[StrangAPI.StrangMarkAbstract_e]
117
118    @override
119    def __lt__(self, other:TimeDelta|str|pl.Path|Location_p) -> bool: ... # type: ignore[override]
120

[docs]
121    @property
122    def keys(self) -> set[str]: ...

123

[docs]
124    @property
125    def path(self) -> pl.Path: ...

126

[docs]
127    @property
128    def body_parent(self) -> list[WordDesc]: ...

129

[docs]
130    @property
131    def stem(self) -> Maybe[str|WordDesc]: ...

132

[docs]
133    @property
134    def key(self) -> Maybe[str|Key_p]: ...

135

[docs]
136    def ext(self, *, last:bool=False) -> Maybe[str|WordDesc|tuple[str|WordDesc, ...]]: ...

137

[docs]
138    def check_wildcards(self, other:pl.Path|Location_p) -> bool: ...

139

[docs]
140    def is_concrete(self) -> bool: ...


141

[docs]
142@runtime_checkable
143class Locator_p(Protocol):
144    Current : Classvar[Locator_p]
145
146    ##--| dunders
147    def __getattr__(self, key:str) -> Location_p: ...
148
149    def __getitem__(self, val:str|pl.Path|Location_p|Key_p) -> pl.Path: ...
150
151    def __contains__(self, key:str|pl.Path|Location_p|Key_p) -> bool: ...
152
153    def __bool__(self) -> bool: ...
154
155    def __len__(self) -> int: ...
156
157    def __iter__(self) -> Generator[str|Key_p]: ...
158
159    def __call__(self, new_root:Maybe[pl.Path]=None) -> Locator_p: ...
160
161    def __enter__(self) -> Locator_p: ...
162
163    def __exit__(self, etype:Maybe[type[Exception]], err:Maybe[Exception], tb:Maybe[Traceback]) -> bool: ...
164
165    ##--| methods

[docs]
166    def clear(self) -> None: ...

167

[docs]
168    def update(self, extra:dict|Location_p|Locator_p, *, strict:bool=True) -> Self: ...

169

[docs]
170    def expand(self, key:Location_p|pl.Path|Key_p|str, *, strict:bool=True, norm:bool=True) -> Maybe[pl.Path]: ...


[docs]
171    def metacheck(self, key:str|Key_p, *meta:LocationMeta_e) -> bool: ...