telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/tools/formatting/html.py

@@ -0,0 +1,241 @@
+import enum
+import html
+import types
+import typing
+from string.templatelib import Template
+
+from telegrinder.tools.formatting.deep_links.links import tg_mention_link
+from telegrinder.tools.parse_mode import ParseMode
+
+type FormatString = object | Template
+type Formatter = typing.Callable[[FormatString], TagFormat]
+
+TAG_FORMAT: typing.Final = "<{tag}{data}>{content}</{tag}>"
+UNION_SPECIFIERS_SEPARATOR: typing.Final = "+"
+
+
+def blockquote(s: FormatString, /, *, expandable: bool = False) -> TagFormat:
+    return TagFormat(s, tag=Tag.BLOCK_QUOTE, **dict(expandable=None) if expandable is True else dict())
+
+
+def bold(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.BOLD)
+
+
+def code_inline(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.CODE)
+
+
+def expandable_blockquote(s: FormatString, /) -> TagFormat:
+    return blockquote(s, expandable=True)
+
+
+monospace = code_inline
+
+
+def italic(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.ITALIC)
+
+
+def link(href: FormatString, /, *, text: str | None = None) -> TagFormat:
+    return TagFormat(
+        text or href,
+        tag=Tag.HYPERLINK,
+        href=f'"{href}"',
+    )
+
+
+def pre_code(s: FormatString, /, *, lang: str | None = None) -> TagFormat:
+    if not lang:
+        return TagFormat(s, tag=Tag.PRE)
+    return pre_code(TagFormat(s, tag=Tag.CODE, **{"class": f"language-{lang}"}))
+
+
+def spoiler(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.SPOILER)
+
+
+def strike(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.STRIKE)
+
+
+def mention(s: FormatString, /, *, user_id: int) -> TagFormat:
+    text = escape(s) if isinstance(s, Template) else str(s)
+    return link(tg_mention_link(user_id=user_id), text=text)
+
+
+def tg_emoji(s: FormatString, /, *, emoji_id: int) -> TagFormat:
+    return TagFormat(s, tag=Tag.EMOJI, emoji_id=emoji_id)
+
+
+def underline(s: FormatString, /) -> TagFormat:
+    return TagFormat(s, tag=Tag.UNDERLINE)
+
+
+def _apply_formats(value: typing.Any, format_spec: str | None = None) -> str:
+    if not format_spec:
+        return html.escape(str(value))
+
+    result: FormatString = html.escape(str(value))
+
+    for fmt in (f.strip() for f in format_spec.split(UNION_SPECIFIERS_SEPARATOR)):
+        if fmt in FORMATTERS:
+            result = FORMATTERS[fmt](result)
+        else:
+            raise ValueError(f"Unknown format: `{fmt}`")
+
+    return result.formatting() if isinstance(result, TagFormat) else result
+
+
+def escape(s: FormatString, /) -> str:
+    if isinstance(s, Template):
+        parts: list[str] = []
+
+        for item in s:
+            if isinstance(item, str):
+                parts.append(html.escape(item))
+            else:
+                value = item.value
+
+                if isinstance(value, TagFormat):
+                    parts.append(value.formatting())
+                elif item.format_spec:
+                    parts.append(_apply_formats(value, item.format_spec))
+                else:
+                    parts.append(html.escape(str(value)))
+
+        return "".join(parts)
+
+    return html.escape(str(s))
+
+
+class HTMLMeta(type):
+    def __lshift__[T](cls: typing.Callable[..., T], other: object, /) -> T:
+        if not isinstance(other, str | Template | TagFormat):
+            return NotImplemented
+        return cls(other)
+
+
+class Tag(enum.StrEnum):
+    HYPERLINK = "a"
+    BOLD = "b"
+    ITALIC = "i"
+    UNDERLINE = "u"
+    STRIKE = "s"
+    CODE = "code"
+    PRE = "pre"
+    SPOILER = "tg-spoiler"
+    BLOCK_QUOTE = "blockquote"
+    EMOJI = "tg-emoji"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class TagFormat(str):
+    __slots__ = ("data", "tag")
+
+    tag: Tag
+    data: dict[str, typing.Any]
+
+    def __new__(cls, s: FormatString, /, *, tag: Tag, **data: typing.Any) -> typing.Self:
+        s = escape(s) if not isinstance(s, TagFormat) else s.formatting()
+        obj = super().__new__(cls, s)
+        obj.data = data
+        obj.tag = tag
+        return obj
+
+    def __str__(self) -> str:
+        return self.formatting()
+
+    @property
+    def content(self) -> str:
+        return super().__str__()
+
+    @property
+    def tag_data(self) -> str:
+        return "".join(f" {k}={v}" if v is not None else f" {k}" for k, v in self.data.items())
+
+    def formatting(self) -> str:
+        return TAG_FORMAT.format(
+            tag=self.tag,
+            data=self.tag_data,
+            content=self.content,
+        )
+
+
+class HTML(str, metaclass=HTMLMeta):
+    """A class for creating and formatting HTML strings.
+
+    >>> HTML << "Hello, " << bold("World!")
+    'Hello, <b>World!</b>'
+
+    >>> HTML << t"Hello, {name:underline}! " << "You are <b>{age}</b> years old."
+    'Hello, <u>Arseny</u>! You are <b>20</b> years old.'
+    """
+
+    PARSE_MODE: typing.Final = ParseMode.HTML
+
+    __slots__ = ()
+
+    def __new__(cls, s: str | Template | TagFormat, /) -> typing.Self:
+        if isinstance(s, Template):
+            content = escape(s)
+        elif isinstance(s, TagFormat):
+            content = s.formatting()
+        else:
+            content = s
+
+        return super().__new__(cls, content)
+
+    def __lshift__(self, other: object, /) -> typing.Self:
+        if isinstance(other, TagFormat):
+            addition = other.formatting()
+        elif isinstance(other, Template):
+            addition = escape(other)
+        else:
+            addition = str(other)
+
+        return self.__class__.__new__(self.__class__, self + addition)
+
+
+FORMATTERS: types.MappingProxyType[str, Formatter] = types.MappingProxyType(
+    mapping=dict(
+        bold=bold,
+        b=bold,
+        code=code_inline,
+        c=code_inline,
+        monospace=monospace,
+        italic=italic,
+        i=italic,
+        spoiler=spoiler,
+        sp=spoiler,
+        strike=strike,
+        s=strike,
+        underline=underline,
+        u=underline,
+        blockquote=blockquote,
+        expandable_blockquote=expandable_blockquote,
+    ),
+)
+
+
+__all__ = (
+    "HTML",
+    "Tag",
+    "TagFormat",
+    "blockquote",
+    "bold",
+    "code_inline",
+    "escape",
+    "expandable_blockquote",
+    "italic",
+    "link",
+    "mention",
+    "monospace",
+    "pre_code",
+    "spoiler",
+    "strike",
+    "tg_emoji",
+    "underline",
+)

telegrinder/tools/fullname.py

@@ -0,0 +1,82 @@
+import builtins
+import inspect
+import os.path
+import sys
+import types
+import 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 = "__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__", None) or 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

@@ -0,0 +1,13 @@
+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",
+    "CtxVar",
+    "GlobalContext",
+    "GlobalCtxVar",
+    "TelegrinderContext",
+    "ctx_var",
+    "runtime_init",
+)

telegrinder/tools/global_context/abc.py

@@ -0,0 +1,63 @@
+import dataclasses
+import typing
+from abc import ABC, abstractmethod
+
+type CtxVariable[T = typing.Any] = CtxVar[T] | GlobalCtxVar[T]
+
+NOVALUE: typing.Final = object()
+
+
+@dataclasses.dataclass(frozen=True)
+class CtxVar[T = typing.Any]:
+    value: T
+    factory: typing.Any = dataclasses.field(default=NOVALUE, kw_only=True)
+    const: bool = dataclasses.field(default=False, kw_only=True)
+
+
+@dataclasses.dataclass(repr=False, frozen=True)
+class GlobalCtxVar[T = typing.Any](CtxVar[T]):
+    name: str
+    value: T
+    factory: typing.Any = dataclasses.field(default=NOVALUE, kw_only=True)
+    const: bool = dataclasses.field(default=False, kw_only=True)
+
+    def __repr__(self) -> str:
+        return "<{}({}={})>".format(
+            type(self).__name__,
+            self.name,
+            repr(CtxVar(self.value, const=self.const, factory=self.factory)),
+        )
+
+    @classmethod
+    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 NOVALUE and var.factory is not NOVALUE:
+            var = dataclasses.replace(var, value=var.factory())
+        return cls(**dict(var.__dict__) | dict(name=name))
+
+
+class ABCGlobalContext[T = typing.Any](ABC):
+    @abstractmethod
+    def __getattr__(self, __name: str) -> typing.Any:
+        pass
+
+    @abstractmethod
+    def __setattr__(self, __name: str, __value: T | CtxVariable[T]) -> None:
+        pass
+
+    @abstractmethod
+    def __delattr__(self, __name: str) -> None:
+        pass
+
+
+__all__ = (
+    "ABCGlobalContext",
+    "CtxVar",
+    "CtxVariable",
+    "GlobalCtxVar",
+)

telegrinder/tools/global_context/builtin_context.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import re
+import typing
+
+from nodnod.scope import Scope
+from vbml.patcher.abc import ABCPatcher
+from vbml.patcher.patcher import Patcher
+
+from telegrinder.modules import logger
+from telegrinder.tools.global_context.global_context import GlobalContext, ctx_var, runtime_init
+from telegrinder.tools.loop_wrapper import LoopWrapper
+
+
+@runtime_init
+class TelegrinderContext(GlobalContext, thread_safe=True):
+    """The thread-safe type-hinted telegrinder context.
+
+    Example:
+    ```
+    from telegrinder.tools.global_context import GlobalContext, TelegrinderContext
+
+    telegrinder_ctx = TelegrinderContext(...)  # with type-hints
+    assert telegrinder_ctx == GlobalContext("telegrinder")  # ok
+    ```
+
+    """
+
+    __ctx_name__ = "telegrinder"
+
+    node_global_scope: typing.Final[Scope] = ctx_var(
+        default_factory=lambda: Scope(detail="global"),
+        init=False,
+        const=True,
+    )
+    vbml_pattern_flags: re.RegexFlag | None = ctx_var(default=None, init=False)
+    vbml_patcher: ABCPatcher = ctx_var(default_factory=Patcher, init=False)
+    loop_wrapper: typing.Final[LoopWrapper] = ctx_var(default_factory=LoopWrapper, init=False, const=True)
+
+    async def close_global_scope(self) -> None:
+        await self.node_global_scope.close()
+        logger.debug("Node global scope closed")
+
+
+__all__ = ("TelegrinderContext",)