telegrinder 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

telegrinder/tools/formatting/deep_links/parsing.py

@@ -0,0 +1,90 @@
+import types
+import typing
+from collections import OrderedDict
+from datetime import timedelta
+from urllib.parse import urlencode
+
+from telegrinder.tools.magic.function import get_func_annotations
+
+type DeepLinkFunction[**P] = typing.Callable[P, str]
+type NoValue = types.EllipsisType
+
+Parameter = typing.Annotated
+
+NO_VALUE: typing.Final[NoValue] = typing.cast("NoValue", ...)
+
+
+def get_query_params(
+    func: DeepLinkFunction[...],
+    kwargs: dict[str, typing.Any],
+    order_params: set[str] | None = None,
+) -> dict[str, typing.Any]:
+    annotations = get_func_annotations(func)
+    params = OrderedDict()
+    param_names = (
+        [*order_params, *(p for p in annotations if p not in order_params)] if order_params else annotations
+    )
+
+    for param_name in param_names:
+        annotation = annotations[param_name]
+        if param_name in kwargs:
+            value = kwargs[param_name]
+            if typing.get_origin(annotation) is Parameter:
+                param_name, validator = get_parameter_metadata(annotation)
+                value = validator(value) if validator is not None else value
+
+            params[param_name] = value
+
+    return params
+
+
+def parse_query_params(
+    params: dict[str, typing.Any],
+    no_value_params: set[str] | None = None,
+    /,
+) -> tuple[set[str], dict[str, typing.Any]]:
+    no_value_params = no_value_params or set()
+    params_: dict[str, typing.Any] = {}
+
+    for key, value in params.items():
+        if value in (False, None):
+            continue
+
+        if value in (True, NO_VALUE):
+            no_value_params.add(key)
+            continue
+        if isinstance(value, timedelta):
+            value = int(value.total_seconds())
+
+        params_[key] = value
+
+    return (no_value_params, params_)
+
+
+def get_parameter_metadata(
+    parameter: typing.Any,
+) -> tuple[str, typing.Callable[[typing.Any], typing.Any] | None]:
+    meta: tuple[typing.Any, ...] = getattr(parameter, "__metadata__")
+    return meta if len(meta) == 2 else (meta[0], None)
+
+
+def parse_deep_link(
+    *,
+    link: str,
+    params: dict[str, typing.Any],
+    no_value_params: set[str] | None = None,
+) -> str:
+    no_value_params, params = parse_query_params(params, no_value_params)
+    query = urlencode(params, encoding="UTF-8") + ("&" if no_value_params else "") + "&".join(no_value_params)
+    return f"{link}?{query}"
+
+
+__all__ = (
+    "NO_VALUE",
+    "NoValue",
+    "Parameter",
+    "get_parameter_metadata",
+    "get_query_params",
+    "parse_deep_link",
+    "parse_query_params",
+)

telegrinder/tools/formatting/deep_links/validators.py

@@ -0,0 +1,8 @@
+import typing
+
+
+def separate_by_plus_char(iterable: typing.Iterable[str] | None = None, /) -> str | None:
+    return None if not iterable else "+".join(iterable)
+
+
+__all__ = ("separate_by_plus_char",)

telegrinder/tools/formatting/html_formatter.py

@@ -1,17 +1,14 @@
 from __future__ import annotations
 
-import dataclasses
 import html
 import string
 import typing
 from contextlib import suppress
 
+from telegrinder.tools.formatting.deep_links import tg_mention_link
 from telegrinder.tools.parse_mode import ParseMode
 from telegrinder.types.enums import ProgrammingLanguage
 
-from .deep_links import tg_mention_link
-from .spec_html_formats import SpecialFormat, is_spec_format
-
 type HTMLFormat = str | TagFormat
 
 HTML_UNION_SPECIFIERS_SEPARATOR: typing.Final[str] = "+"
@@ -54,18 +51,13 @@ class StringFormatter(string.Formatter):
 
         return fmt
 
-    def get_spec_formatter(self, value: SpecialFormat) -> typing.Callable[..., TagFormat]:
-        return globals()[value.__formatter_name__]
-
     def make_tag_format(self, value: typing.Any, fmts: list[HTMLFormat]) -> TagFormat:
-        if is_spec_format(value):
-            value = value.string
-
         current_format = globals()[fmts.pop(0)](
             str(value)
             if isinstance(value, TagFormat)
             else escape(FormatString(value) if not isinstance(value, str) else value)
         )
+
         for fmt in fmts:
             current_format = globals()[fmt](current_format)
 
@@ -81,20 +73,7 @@ class StringFormatter(string.Formatter):
 
     def format_field(self, value: typing.Any, fmt: str) -> HTMLFormatter:
         with suppress(ValueError):
-            return HTMLFormatter(
-                format(
-                    (
-                        value.formatting()
-                        if isinstance(value, TagFormat)
-                        else (
-                            self.get_spec_formatter(value)(**dataclasses.asdict(value)).formatting()
-                            if is_spec_format(value)
-                            else value
-                        )
-                    ),
-                    fmt,
-                )
-            )
+            return HTMLFormatter(format(value.formatting() if isinstance(value, TagFormat) else value, fmt))
 
         fmts = list(
             map(
@@ -102,13 +81,7 @@ class StringFormatter(string.Formatter):
                 fmt.split(HTML_UNION_SPECIFIERS_SEPARATOR),
             ),
         )
-        tag_format = self.make_tag_format(value, fmts)
-
-        if is_spec_format(value):
-            value.string = tag_format
-            tag_format = self.get_spec_formatter(value)(**dataclasses.asdict(value))
-
-        return tag_format.formatting()
+        return self.make_tag_format(value, fmts).formatting()
 
     def format(self, __string: str, *args: object, **kwargs: object) -> HTMLFormatter:
         return HTMLFormatter(super().format(__string, *args, **kwargs))
@@ -192,15 +165,15 @@ class TagFormat(FormatString):
 
 class HTMLFormatter(FormatString):
     """>>> HTMLFormatter(bold("Hello, World"))
-    >>> '<b>Hello, World</b>'
+    '<b>Hello, World</b>'
     >>> HTMLFormatter("Hi, {name:italic}").format(name="Max")
-    >>> 'Hi, <i>Max</i>'
+    'Hi, <i>Max</i>'
     """
 
-    PARSE_MODE = ParseMode.HTML
+    PARSE_MODE: typing.Final[str] = ParseMode.HTML
 
 
-def escape(string: str) -> EscapedString:
+def escape(string: str, /) -> EscapedString:
     if isinstance(string, EscapedString | HTMLFormatter):
         return EscapedString(string)
     return EscapedString(html.escape(string, quote=False))
@@ -226,45 +199,45 @@ def italic(string: str) -> TagFormat:
     return TagFormat(string, tag="i")
 
 
-def link(href: str, string: str | None = None) -> TagFormat:
+def link(href: str, /, *, text: str | None = None) -> TagFormat:
     return TagFormat(
-        string or href,
+        text or href,
         tag="a",
         href=QUOT_MARK + href + QUOT_MARK,
     )
 
 
-def pre_code(string: str, lang: str | ProgrammingLanguage | None = None) -> TagFormat:
+def pre_code(string: str, /, *, lang: str | ProgrammingLanguage | None = None) -> TagFormat:
     if lang is None:
         return TagFormat(string, tag="pre")
+
     lang = lang.value if isinstance(lang, ProgrammingLanguage) else lang
     return pre_code(TagFormat(string, tag="code", **{"class": f"language-{lang}"}))
 
 
-def spoiler(string: str) -> TagFormat:
+def spoiler(string: str, /) -> TagFormat:
     return TagFormat(string, tag="tg-spoiler")
 
 
-def strike(string: str) -> TagFormat:
+def strike(string: str, /) -> TagFormat:
     return TagFormat(string, tag="s")
 
 
-def mention(string: str, user_id: int) -> TagFormat:
-    return link(tg_mention_link(user_id=user_id), string)
+def mention(string: str, /, *, user_id: int) -> TagFormat:
+    return link(tg_mention_link(user_id=user_id), text=string)
 
 
-def tg_emoji(string: str, emoji_id: int) -> TagFormat:
+def tg_emoji(string: str, /, *, emoji_id: int) -> TagFormat:
     return TagFormat(string, tag="tg-emoji", emoji_id=emoji_id)
 
 
-def underline(string: str) -> TagFormat:
+def underline(string: str, /) -> TagFormat:
     return TagFormat(string, tag="u")
 
 
 __all__ = (
     "FormatString",
     "HTMLFormatter",
-    "SpecialFormat",
     "block_quote",
     "bold",
     "code_inline",

telegrinder/tools/fullname.py

@@ -0,0 +1,83 @@
+import builtins
+import inspect
+import os.path
+import sys
+import types
+
+import typing_extensions as typing
+
+type RoutineMethodType = (
+    types.MethodType | types.MethodDescriptorType | types.MethodWrapperType | types.BuiltinMethodType
+)
+type RoutineDescriptorType = types.MethodDescriptorType | types.GetSetDescriptorType
+
+_BUILTINS: typing.Final[frozenset[typing.Any]] = frozenset(
+    x for name in dir(builtins) if getattr((x := getattr(builtins, name)), "__module__", None) == "builtins"
+)
+_CACHE_KEY: typing.Final[str] = "__fullname_cache__"
+
+
+def _is_builtin(obj: typing.Any, /) -> bool:
+    return inspect.isbuiltin(obj) or obj in _BUILTINS
+
+
+def _is_routine_method(obj: typing.Any, /) -> typing.TypeIs[RoutineMethodType]:
+    return inspect.isbuiltin(obj) or inspect.ismethod(obj) or inspect.ismethodwrapper(obj)
+
+
+def _is_routine_descriptor(obj: typing.Any, /) -> typing.TypeIs[RoutineDescriptorType]:
+    return inspect.ismethoddescriptor(obj) or inspect.isgetsetdescriptor(obj)
+
+
+def _module_name(module: types.ModuleType, /) -> str:
+    if (mod_name := module.__name__) != "__main__":
+        return mod_name
+
+    mod_package = module.__package__ or ""
+    mod_file = module.__file__
+    if mod_file is None:
+        return mod_package
+
+    mod_fname = os.path.basename(mod_file).removesuffix(".py")
+    return mod_package if mod_package in ("__init__", "__main__") else mod_fname
+
+
+def fullname(obj: object, /) -> str:
+    """The full name (`__module__.__name__`) of the object."""
+
+    if isinstance(obj, staticmethod | classmethod):
+        obj = obj.__func__
+
+    elif (
+        not inspect.isroutine(obj)
+        and not inspect.isgetsetdescriptor(obj)
+        and not isinstance(obj, type)
+        and not inspect.ismodule(obj)
+    ):
+        obj = type(obj)
+
+    if (name := fullname.__dict__.setdefault(_CACHE_KEY, dict()).get(obj)) is not None:
+        return name
+
+    if inspect.ismodule(obj):
+        fullname.__dict__[_CACHE_KEY][obj] = name = _module_name(obj)
+        return name
+
+    qualname = obj.__qualname__
+    orig_obj = obj
+
+    if _is_routine_method(obj) or _is_routine_descriptor(obj):
+        obj_cls = obj.__objclass__ if _is_routine_descriptor(obj) else obj.__self__
+        obj = type(obj_cls) if not isinstance(obj_cls, type) else obj_cls
+
+    module: str = getattr(orig_obj, "__module__", obj.__module__)
+    if _is_builtin(obj) and module != builtins.__name__:
+        module = builtins.__name__
+    else:
+        module = _module_name(sys.modules[module])
+
+    fullname.__dict__[_CACHE_KEY][orig_obj] = name = ".".join((module, qualname))
+    return name
+
+
+__all__ = ("fullname",)

telegrinder/tools/global_context/__init__.py

@@ -1,6 +1,6 @@
-from .abc import ABCGlobalContext, CtxVar, GlobalCtxVar
-from .global_context import GlobalContext, ctx_var
-from .telegrinder_ctx import TelegrinderContext
+from telegrinder.tools.global_context.abc import ABCGlobalContext, CtxVar, GlobalCtxVar
+from telegrinder.tools.global_context.builtin_context import TelegrinderContext
+from telegrinder.tools.global_context.global_context import GlobalContext, ctx_var, runtime_init
 
 __all__ = (
     "ABCGlobalContext",
@@ -9,4 +9,5 @@ __all__ = (
     "GlobalCtxVar",
     "TelegrinderContext",
     "ctx_var",
+    "runtime_init",
 )

telegrinder/tools/global_context/abc.py

@@ -7,38 +7,41 @@ import typing_extensions as typing
 
 T = typing.TypeVar("T", default=typing.Any)
 
+NODEFAULT: typing.Final[object] = object()
 
-@dataclasses.dataclass(repr=False, frozen=True)
+
+@dataclasses.dataclass(frozen=True)
 class CtxVar(typing.Generic[T]):
     value: T
+    factory: typing.Any = dataclasses.field(default=NODEFAULT, kw_only=True)
     const: bool = dataclasses.field(default=False, kw_only=True)
 
-    def __repr__(self) -> str:
-        return "<{}(value={!r})>".format(
-            ("Const" if self.const else "") + CtxVar.__name__,
-            self.value,
-        )
-
 
 @dataclasses.dataclass(repr=False, frozen=True)
-class GlobalCtxVar(typing.Generic[T]):
+class GlobalCtxVar(CtxVar[T], typing.Generic[T]):
     name: str
     value: T
+    factory: typing.Any = dataclasses.field(default=NODEFAULT, kw_only=True)
     const: bool = dataclasses.field(default=False, kw_only=True)
 
     def __repr__(self) -> str:
         return "<{}({}={})>".format(
             self.__class__.__name__,
             self.name,
-            repr(CtxVar(self.value, const=self.const)),
+            repr(CtxVar(self.value, const=self.const, factory=self.factory)),
         )
 
     @classmethod
-    def collect(cls, name: str, ctx_value: T | CtxVariable[T]) -> typing.Self:
-        ctx_value = CtxVar(ctx_value) if not isinstance(ctx_value, CtxVar | GlobalCtxVar) else ctx_value
-        params = ctx_value.__dict__
-        params["name"] = name
-        return cls(**params)
+    def from_var(
+        cls,
+        name: str,
+        ctx_value: T | CtxVariable[T],
+        const: bool = False,
+    ) -> typing.Self:
+        var = CtxVar(ctx_value, const=const) if not isinstance(ctx_value, CtxVar | GlobalCtxVar) else ctx_value
+        if var.value is NODEFAULT and var.factory is not NODEFAULT:
+            var = dataclasses.replace(var, value=var.factory())
+        return cls(**dict(var.__dict__) | dict(name=name))
 
 
 class ABCGlobalContext(ABC, typing.Generic[T]):

telegrinder/tools/global_context/builtin_context.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import re
+import typing
+
+from fntypes.option import Nothing, Option
+from vbml.patcher.abc import ABCPatcher
+from vbml.patcher.patcher import Patcher
+
+from telegrinder.tools.global_context.global_context import GlobalContext, ctx_var, runtime_init
+from telegrinder.tools.loop_wrapper import LoopWrapper
+
+if typing.TYPE_CHECKING:
+    from telegrinder.node.composer import Composer
+
+
+@runtime_init
+class TelegrinderContext(GlobalContext):
+    """The type-hinted telegrinder context called `telegrinder`.
+
+    Example:
+    ```
+    from telegrinder.tools.global_context import GlobalContext, TelegrinderContext
+
+    telegrinder_ctx = TelegrinderContext(...)  # with type-hints
+    assert telegrinder_ctx == GlobalContext("telegrinder")  # ok
+    ```
+
+    """
+
+    __ctx_name__ = "telegrinder"
+
+    composer: Option[Composer] = ctx_var(default=Nothing(), init=False)
+    vbml_pattern_flags: re.RegexFlag | None = ctx_var(default=None, init=False)
+    vbml_patcher: ABCPatcher = ctx_var(default_factory=Patcher, init=False)
+    loop_wrapper: LoopWrapper = ctx_var(default_factory=LoopWrapper, init=False)
+
+
+__all__ = ("TelegrinderContext",)