Source code for jgdv.decorators._interface

  1## decorators.pyi -*- mode: python -*-
  2# Type Interface Specification
  3#
  4from __future__ import annotations
  5
  6import enum
  7# ##-- types
  8# isort: off
  9import inspect
 10import abc
 11import collections.abc
 12from typing import TYPE_CHECKING, cast, assert_type, assert_never
 13from typing import Generic, NewType
 14# Protocols:
 15from typing import Protocol, runtime_checkable
 16# Typing Decorators:
 17from typing import no_type_check, final, override, overload
 18
 19if TYPE_CHECKING:
 20    from jgdv._abstract.types import Func, Method
 21    from jgdv import Maybe
 22    from typing import Final
 23    from typing import ClassVar, Any, LiteralString
 24    from typing import Never, Self, Literal
 25    from typing import TypeGuard
 26    from collections.abc import Iterable, Iterator, Callable, Generator
 27    from collections.abc import Sequence, Mapping, MutableMapping, Hashable
 28
 29##--|
 30
 31# isort: on
 32# ##-- end types
 33
 34# ##-- Generated Exports
 35__all__ = ( # noqa: RUF022
 36# -- Types
 37"Decorable", "Decorated", "Signature",
 38# -- Classes
 39"DForm_e", "Decorator_p",
 40
 41)
 42# ##-- end Generated Exports
 43
 44
 45##--| Primary Types
 46type Signature          = inspect.Signature
 47type Decorable[**I, O]  = Callable[I, O]
 48type Decorated[**I, O]  = Callable[I, O]
 49
 50##--| Val
 51WRAPPED             : Final[str]  = "__wrapped__"
 52ANNOTATIONS_PREFIX  : Final[str]  = "__JGDV__"
 53MARK_SUFFIX         : Final[str]  = "_mark"
 54DATA_SUFFIX         : Final[str]  = "_data"
 55ATTR_TARGET         : Final[str]  = "__annotations__"
 56

[docs]
 57class DForm_e(enum.Enum):
 58    """ This is necessary because you can't use Callable or MethodType
 59    in match statement
 60    """
 61
 62    CLASS    = enum.auto()
 63    FUNC     = enum.auto()
 64    METHOD   = enum.auto()

 65
 66##--|
 67
 68class DecoratorHooks_p(Protocol):
 69    # TODO remove need to define an internal function
 70
 71    def _wrap_method_h[**In, Out](self, meth:Callable[In,Out]) -> Decorated[In, Out]: ...
 72
 73    def _wrap_fn_h[**In, Out](self, fn:Func[In, Out]) -> Decorated[In, Out]: ...
 74
 75    def _validate_target_h(self, target:Decorable, form:DForm_e, args:Maybe[list]=None) -> None: ...
 76
 77    def _validate_sig_h(self, sig:Signature, form:DForm_e, args:Maybe[list]=None) -> None: ...
 78
 79    def _build_annotations_h(self, target:Decorable, current:list) -> list: ...
 80
 81class DecoratorUtils_p(Protocol):
 82
 83    def _decoration_logic(self, target:Decorable) -> Decorated: ...
 84
 85    def _unwrap(self:Decorator_p, target:Decorated) -> Decorable: ...
 86
 87    def _unwrapped_depth(self:Decorator_p, target:Decorated) -> int: ...
 88
 89    def _build_wrapper(self:Decorator_p, form:DForm_e, target:Decorable) -> Maybe[Decorated]: ...
 90
 91    def _apply_onto(self:Decorator_p, wrapper:Decorated, target:Decorable) -> Decorated: ...
 92
 93    def _signature(self:Decorator_p, target:Decorable) -> Signature: ...
 94

[docs]
 95@runtime_checkable
 96class Decorator_p(DecoratorHooks_p, DecoratorUtils_p, Protocol):
 97    Form                 : ClassVar[type[DForm_e]]
 98    needs_args           : ClassVar[bool]
 99
100    _annotation_prefix   : str
101    _data_key            : Maybe[str]
102    _data_suffix         : str
103    _mark_key            : Maybe[str]
104    _mark_suffix         : str
105    _wrapper_assignments : list[str]
106    _wrapper_updates     : list[str]
107
108    def __call__[**I, O](self, target:Decorable[I, O]) -> Decorated[I, O]: ...
109

[docs]
110    def data_key(self) -> str: ...

111

[docs]
112    def mark_key(self) -> str: ...

113

[docs]
114    def dec_name(self) -> str: ...

115

[docs]
116    def apply_mark(self, *args:Decorable) -> None: ...

117

[docs]
118    def annotate_decorable(self, target:Decorable) -> list: ...

119

[docs]
120    def is_marked(self, target:Decorable) -> bool: ...

121

[docs]
122    def is_annotated(self, target:Decorable) -> bool: ...

123

[docs]
124    def get_annotations(self, target:Decorable) -> list[str]: ...


125
126##--| Interface
127
128
129class ClsDecorator_p(Protocol):
130
131    def __call__[T](self, target:type[T]) -> type[T]: ...
132
133
134    def _wrap_class_h[T](self, cls:type[T]) -> Maybe[Decorated[[], T]]: ...