telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/msgspec_utils/encoder.py

@@ -0,0 +1,204 @@
+import datetime as dt
+import typing
+from contextlib import contextmanager
+
+import kungfu.library
+import msgspec
+
+from telegrinder.msgspec_utils.abc import SupportsCast
+from telegrinder.msgspec_utils.custom_types.datetime import datetime, timedelta
+from telegrinder.msgspec_utils.custom_types.enum_meta import BaseEnumMeta
+from telegrinder.msgspec_utils.tools import bundle, fullname, get_origin
+
+type Context = dict[str, typing.Any]
+type Order = typing.Literal["deterministic", "sorted"]
+type EncHook[T] = typing.Callable[typing.Concatenate[T, ...], typing.Any]
+
+
+def to_builtins(
+    obj: typing.Any,
+    *,
+    str_keys: bool = False,
+    builtin_types: typing.Iterable[type[typing.Any]] | None = None,
+    order: Order | None = None,
+    context: Context | None = None,
+) -> kungfu.library.Result[typing.Any, msgspec.ValidationError]:
+    try:
+        return kungfu.library.Ok(
+            encoder.to_builtins(
+                obj,
+                str_keys=str_keys,
+                builtin_types=builtin_types,
+                order=order,
+                context=context,
+            ),
+        )
+    except msgspec.ValidationError as error:
+        return kungfu.library.Error(error)
+
+
+class Encoder:
+    """Class `Encoder` for `msgspec` module with encode hooks for objects.
+
+    ```
+    from datetime import datetime
+
+    class MyDatetime(datetime):
+        ...
+
+    encoder = Encoder()
+    encoder.enc_hooks[MyDatetime] = lambda d: int(d.timestamp())
+
+    encoder.enc_hook(MyDatetime.now())  #> 1713354732
+    encoder.encode({"digit": Digit.ONE})  #> '{"digit":1}'
+    ```
+    """
+
+    cast_types: dict[type[typing.Any], type[SupportsCast]]
+    enc_hooks: dict[typing.Any, EncHook[typing.Any]]
+    abstract_enc_hooks: dict[typing.Any, EncHook[typing.Any]]
+
+    def __init__(self) -> None:
+        self.cast_types = {  # type: ignore
+            dt.datetime: datetime,
+            dt.timedelta: timedelta,
+        }
+        self.enc_hooks = {
+            kungfu.library.Some: lambda some: some.value,
+            kungfu.library.Nothing: lambda _: None,
+            kungfu.library.Sum: lambda s: s.v,
+            datetime: lambda date: int(date.timestamp()),
+            timedelta: lambda time: time.total_seconds(),
+        }
+        self.abstract_enc_hooks = {
+            BaseEnumMeta: lambda enum_member: enum_member.value,
+        }
+
+    def __repr__(self) -> str:
+        return "<{}: cast_types={!r}, enc_hooks={!r}, abstract_enc_hooks={!r}>".format(
+            type(self).__name__,
+            self.cast_types,
+            self.enc_hooks,
+            self.abstract_enc_hooks,
+        )
+
+    @contextmanager
+    def __call__(
+        self,
+        *,
+        decimal_format: typing.Literal["string", "number"] = "string",
+        uuid_format: typing.Literal["canonical", "hex"] = "canonical",
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> typing.Generator[msgspec.json.Encoder, typing.Any, None]:
+        """Context manager returns the `msgspec.json.Encoder` object with passed the `enc_hook`."""
+        yield msgspec.json.Encoder(
+            enc_hook=self.enc_hook(context),
+            decimal_format=decimal_format,
+            uuid_format=uuid_format,
+            order=order,
+        )
+
+    def add_enc_hook[T](self, t: type[T], /) -> typing.Callable[[EncHook[T]], EncHook[T]]:
+        def decorator(func: EncHook[T], /) -> EncHook[T]:
+            encode_hook = self.enc_hooks.setdefault(get_origin(t), func)
+            return func if encode_hook is not func else encode_hook
+
+        return decorator
+
+    def add_abstract_enc_hook[T](self, abstract_type: type[T], /) -> typing.Callable[[EncHook[T]], EncHook[T]]:
+        def decorator(func: EncHook[T], /) -> EncHook[T]:
+            return self.abstract_enc_hooks.setdefault(get_origin(abstract_type), func)
+
+        return decorator
+
+    def get_abstract_enc_hook(self, subtype: type[typing.Any], /) -> EncHook[typing.Any] | None:
+        for abstract, enc_hook in self.abstract_enc_hooks.items():
+            if issubclass(subtype, abstract) or issubclass(type(subtype), abstract):
+                return enc_hook
+
+        return None
+
+    def enc_hook(self, context: Context | None = None, /) -> EncHook[typing.Any]:
+        def inner(obj: typing.Any, /) -> typing.Any:
+            origin_type = get_origin(obj)
+
+            if (enc_hook_func := self.enc_hooks.get(origin_type)) is None and (
+                enc_hook_func := self.get_abstract_enc_hook(origin_type)
+            ) is None:
+                raise NotImplementedError(
+                    f"Not implemented encode hook for object of type `{fullname(origin_type)}`. "
+                    "You can implement encode hook for this object.",
+                )
+
+            return bundle(enc_hook_func, context or {}, start_idx=1)(obj)
+
+        return inner
+
+    @typing.overload
+    def encode(
+        self,
+        obj: typing.Any,
+        *,
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> str: ...
+
+    @typing.overload
+    def encode(
+        self,
+        obj: typing.Any,
+        *,
+        as_str: typing.Literal[True],
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> str: ...
+
+    @typing.overload
+    def encode(
+        self,
+        obj: typing.Any,
+        *,
+        as_str: typing.Literal[False],
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> bytes: ...
+
+    def encode(
+        self,
+        obj: typing.Any,
+        *,
+        as_str: bool = True,
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> str | bytes:
+        buf = msgspec.json.encode(obj, enc_hook=self.enc_hook(context), order=order)
+        return buf.decode() if as_str else buf
+
+    def to_builtins(
+        self,
+        obj: typing.Any,
+        *,
+        str_keys: bool = False,
+        builtin_types: typing.Iterable[type[typing.Any]] | None = None,
+        order: Order | None = None,
+        context: Context | None = None,
+    ) -> typing.Any:
+        return msgspec.to_builtins(
+            obj,
+            str_keys=str_keys,
+            builtin_types=builtin_types,
+            enc_hook=self.enc_hook(context),
+            order=order,
+        )
+
+    def cast(self, obj: typing.Any, /) -> typing.Any:
+        if (caster := self.cast_types.get(get_origin(obj))) is not None:
+            return caster.cast(obj)
+        return obj
+
+
+encoder: typing.Final = Encoder()
+
+
+__all__ = ("Encoder", "encoder", "to_builtins")

telegrinder/msgspec_utils/json.py

@@ -0,0 +1,15 @@
+import typing
+
+from telegrinder.msgspec_utils.decoder import decoder
+from telegrinder.msgspec_utils.encoder import encoder
+
+
+def dumps(o: typing.Any) -> str:
+    return encoder.encode(o)
+
+
+def loads(s: str | bytes) -> typing.Any:
+    return decoder.decode(s)
+
+
+__all__ = ("dumps", "loads")

telegrinder/msgspec_utils/tools.py

@@ -0,0 +1,80 @@
+import typing
+
+import kungfu.library
+import msgspec
+from kungfu.library.monad.option import NOTHING, Nothing
+
+if typing.TYPE_CHECKING:
+    from telegrinder.tools.fullname import fullname
+    from telegrinder.tools.magic.function import bundle
+
+    def get_class_annotations(obj: typing.Any, /) -> dict[str, typing.Any]: ...
+
+    def get_type_hints(obj: typing.Any, /) -> dict[str, typing.Any]: ...
+
+else:
+    from msgspec._utils import get_class_annotations, get_type_hints
+
+    def bundle(*args, **kwargs):
+        from telegrinder.tools.magic.function import bundle
+
+        return bundle(*args, **kwargs)
+
+    def fullname(*args, **kwargs):
+        from telegrinder.tools.fullname import fullname
+
+        return fullname(*args, **kwargs)
+
+
+_COMMON_TYPES = frozenset((str, int, float, bool, None, kungfu.library.Sum))
+
+
+def get_origin[T](t: T, /) -> type[T]:
+    t_ = typing.get_origin(t) or t
+    t_ = type(t_) if not isinstance(t_, type) else t_
+    return typing.cast("type[T]", t_)
+
+
+def is_none(obj: typing.Any, /) -> typing.TypeIs[Nothing | None]:
+    return obj is None or obj is NOTHING
+
+
+def is_common_type[T](t: T, /) -> typing.TypeGuard[type[T]]:
+    if not isinstance(t, type):
+        return False
+    return t in _COMMON_TYPES or issubclass(t, msgspec.Struct) or hasattr(t, "__dataclass_fields__")
+
+
+def struct_asdict(
+    struct: msgspec.Struct,
+    /,
+    *,
+    exclude_unset: bool = True,
+    unset_as_nothing: bool = False,
+) -> dict[str, typing.Any]:
+    return {
+        k: v if not unset_as_nothing else NOTHING if v is msgspec.UNSET else v
+        for k, v in msgspec.structs.asdict(struct).items()
+        if not (exclude_unset and (is_none(v) or v is msgspec.UNSET))
+    }
+
+
+def type_check(obj: typing.Any, t: typing.Any) -> bool:
+    return (
+        isinstance(obj, t)
+        if isinstance(t, type) and issubclass(t, msgspec.Struct)
+        else type(obj) in t
+        if isinstance(t, tuple)
+        else type(obj) is t
+    )
+
+
+__all__ = (
+    "get_class_annotations",
+    "get_origin",
+    "get_type_hints",
+    "is_common_type",
+    "is_none",
+    "struct_asdict",
+    "type_check",
+)

telegrinder/node/__init__.py

@@ -0,0 +1,80 @@
+"""`Node` module which implements [nodnod](https://github.com/timoniq/nodnod)
+integration for convenient dependency injection via `nodes`.
+
+
+```python
+from telegrinder.node import scalar_node, global_node, per_call
+
+@global_node
+@scalar_node
+class Hello:
+    @classmethod
+    def __compose__(cls) -> str:
+        return "Hello"
+
+@global_node
+@scalar_node
+class World:
+    @classmethod
+    def __compose__(cls) -> str:
+        return "World"
+
+@per_call
+@scalar_node
+class Greeter:
+    @classmethod
+    def __compose__(cls, hello: Hello, world: World) -> str:
+        return f"{hello}, {world}!"
+
+@bot.on.message()
+async def hello_world(greeter: Greeter) -> str:
+    return greeter
+```
+"""
+
+# pyright: reportUnusedImport=false, reportUnsupportedDunderAll=false
+
+from nodnod import (
+    DataNode,
+    Injection,
+    Node,
+    NodeConstructor,
+    ResultNode,
+    Scalar,
+    case,
+    generic_node,
+    polymorphic,
+    scalar_node,
+)
+
+from telegrinder.node.compose import Composable, compose, create_composable, run_agent
+from telegrinder.node.nodes import *
+from telegrinder.node.nodes import __all__ as nodes_all
+from telegrinder.node.scope import GLOBAL, PER_CALL, PER_EVENT, NodeScope, global_node, per_call, per_event
+from telegrinder.node.utils import as_node, is_node
+
+__all__ = nodes_all + (
+    "GLOBAL",
+    "PER_CALL",
+    "PER_EVENT",
+    "Composable",
+    "DataNode",
+    "NodeConstructor",
+    "NodeScope",
+    "Node",
+    "ResultNode",
+    "Injection",
+    "Scalar",
+    "as_node",
+    "compose",
+    "create_composable",
+    "run_agent",
+    "global_node",
+    "is_node",
+    "case",
+    "generic_node",
+    "polymorphic",
+    "scalar_node",
+    "per_call",
+    "per_event",
+)

telegrinder/node/compose.py

@@ -0,0 +1,193 @@
+"""Compose nodes with specific agent and context.
+
+This module provides the `compose` function for executing nodes with dependency injection.
+
+Key features:
+- Execute functions as nodes with automatic dependency resolution
+- Work with Node classes and ready-made Composable objects
+- Integration with `Context` for access to API, events, data, and other nodes
+
+```python
+# Executing a function node
+async def process_data(user_id: int, api: API) -> str:
+    user = await api.get_chat(user_id)
+    return f"Hello, {user.first_name}!"
+
+async def handler(context: Context):
+    async with compose(process_data, context) as result:
+        match result:
+            case Ok(value):
+                print(value)  # "Hello, John!"
+            case Error(error):
+                print(f"Error: {error}")
+
+# Executing a node with additional dependencies
+from telegrinder.node import per_call, scalar_node
+
+@per_call
+@scalar_node
+class Database:
+    @classmethod
+    def __compose__(cls) -> "Database":
+        return cls()
+
+async def get_user_data(db: Database, user_id: int) -> dict[str, Any]:
+    # Use db to fetch data
+    return {"id": user_id, "name": "User"}
+
+async def handler(context: Context):
+    async with compose(get_user_data, context) as result:
+        user_data = result.unwrap()
+
+# Passing additional root dependencies
+async def handler(context: Context):
+    custom_data = {"custom_key": "custom_value"}
+
+    async with compose(
+        my_node,
+        context,
+        roots={CustomType: custom_data}
+    ) as result:
+        # roots allows injecting additional dependencies
+        pass
+```
+
+The `compose` function returns an async context manager that:
+
+- Creates a local scope for node composing
+- Automatically resolves all node dependencies
+- Returns `Result[T, NodeError]` with the composed result
+"""
+
+import dataclasses
+import typing
+from contextlib import asynccontextmanager
+from functools import lru_cache
+
+from kungfu.library.monad.result import Error, Ok, Result
+from nodnod.agent.base import Agent
+from nodnod.agent.event_loop.agent import EventLoopAgent
+from nodnod.error import NodeError
+from nodnod.interface import create_agent_from_node, create_node_from_function, inject_internals
+from nodnod.interface.is_node import is_node
+from nodnod.interface.node_from_function import Externals
+from nodnod.node import Node
+from nodnod.scope import Scope
+from nodnod.utils.is_type import is_type
+
+from telegrinder.node.scope import TELEGRINDER_CONTEXT, MappedScopes, NodeScope
+from telegrinder.tools.aio import maybe_awaitable
+from telegrinder.tools.magic.function import Function
+
+if typing.TYPE_CHECKING:
+    from telegrinder.bot.dispatch.context import Context
+
+type _Composable[T: Agent] = Function[..., typing.Any] | type[Node[typing.Any, typing.Any]] | Composable[T]
+
+NODE_GLOBAL_SCOPE: typing.Final = TELEGRINDER_CONTEXT.node_global_scope
+
+
+@lru_cache(maxsize=1024 * 4)
+def create_composable[T: Agent](
+    node_or_function: type[Node[typing.Any, typing.Any]] | Function[..., typing.Any],
+    /,
+    *,
+    agent_cls: type[T] = EventLoopAgent,
+) -> Composable[T]:
+    if not isinstance(node_or_function, type):
+        node_or_function = create_node_from_function(node_or_function)
+    return Composable(node_or_function, create_agent_from_node(node_or_function, agent_cls=agent_cls))
+
+
+@asynccontextmanager
+async def run_agent(
+    agent: Agent,
+    context: Context,
+    *,
+    roots: dict[type[typing.Any], typing.Any] | None = None,
+    per_event_scope: Scope | None = None,
+) -> typing.AsyncGenerator[Result[Scope, NodeError]]:
+    event_scope = per_event_scope if per_event_scope is not None else context.per_event_scope
+    mapped_scopes = MappedScopes(global_scope=NODE_GLOBAL_SCOPE, per_event_scope=event_scope)
+    internals = {type(context): context, Externals: context}
+
+    async with event_scope.create_child(detail=NodeScope.PER_CALL) as local_scope:
+        try:
+            inject_internals(local_scope, internals | (roots or {}))
+            await maybe_awaitable(agent.run(local_scope, mapped_scopes))
+            yield Ok(local_scope.merge())
+        except NodeError as error:
+            yield Error(error)
+
+
+@typing.overload
+def compose[R](
+    function: Function[..., R],
+    /,
+    context: Context,
+    *,
+    per_event_scope: Scope | None = None,
+    agent_cls: type[Agent] | None = None,
+    roots: dict[type[typing.Any], typing.Any] | None = None,
+) -> typing.AsyncContextManager[Result[R, NodeError], None]: ...
+
+
+@typing.overload
+def compose[T: Agent](
+    composable: Composable[T],
+    /,
+    context: Context,
+    *,
+    per_event_scope: Scope | None = None,
+    roots: dict[type[typing.Any], typing.Any] | None = None,
+) -> typing.AsyncContextManager[Result[typing.Any, NodeError], None]: ...
+
+
+@typing.overload
+def compose[T](
+    node: type[Node[T, typing.Any]],
+    /,
+    context: Context,
+    *,
+    agent: Agent,
+    per_event_scope: Scope | None = None,
+    roots: dict[type[typing.Any], typing.Any] | None = None,
+) -> typing.AsyncContextManager[Result[T, NodeError], None]: ...
+
+
+@asynccontextmanager
+async def compose[T = typing.Any](
+    node: _Composable[Agent],
+    context: Context,
+    *,
+    per_event_scope: Scope | None = None,
+    agent: Agent | None = None,
+    agent_cls: type[Agent] | None = None,
+    roots: dict[type[typing.Any], typing.Any] | None = None,
+) -> typing.AsyncGenerator[Result[T, NodeError], None]:
+    composable = None
+
+    if isinstance(node, Composable):
+        composable = node
+    elif not is_node(node):
+        composable = create_composable(node, agent_cls=agent_cls or EventLoopAgent)
+
+    if composable is not None:
+        node, agent = composable.node, typing.cast("Agent", composable.agent)
+    elif not is_type(node, Node):
+        raise TypeError("Compose requires function, node, or composable.")
+
+    if agent is None:
+        raise ValueError("Agent is required.")
+
+    async with run_agent(agent, context, roots=roots, per_event_scope=per_event_scope) as result:
+        yield result.map(lambda scope: scope[node].value)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Composable[T: Agent = Agent]:
+    node: type[Node[typing.Any, typing.Any]]
+    agent: T
+
+
+__all__ = ("Composable", "compose", "create_composable", "run_agent")

telegrinder/node/nodes/__init__.py

@@ -0,0 +1,96 @@
+"""Built-in nodes."""
+
+from telegrinder.node.nodes.attachment import (
+    Animation,
+    Attachment,
+    Audio,
+    Document,
+    MediaGroup,
+    Photo,
+    Poll,
+    SuccessfulPayment,
+    Video,
+    VideoNote,
+    Voice,
+)
+from telegrinder.node.nodes.callback_query import CallbackQueryData, CallbackQueryDataJson
+from telegrinder.node.nodes.channel import (
+    Channel,
+    ChannelId,
+    ChannelPost,
+    ChannelPostId,
+    ChatMessageChannelPost,
+    ChatMessageChannelPostAuthor,
+    ChatMessageChannelPostChannel,
+    ChatMessageChannelPostChannelId,
+    ChatMessageChannelPostId,
+)
+from telegrinder.node.nodes.command import CommandInfo
+from telegrinder.node.nodes.error import Error
+from telegrinder.node.nodes.event import EventNode
+from telegrinder.node.nodes.file import File, FileId
+from telegrinder.node.nodes.global_node import GlobalNode
+from telegrinder.node.nodes.i18n import ABCTranslator, BaseTranslator, I18NConfig, KeySeparator
+from telegrinder.node.nodes.me import BotUsername, Me
+from telegrinder.node.nodes.message_entities import MessageEntities
+from telegrinder.node.nodes.payload import Payload, PayloadData, PayloadSerializer
+from telegrinder.node.nodes.reply_message import ReplyMessage
+from telegrinder.node.nodes.source import ChatId, ChatSource, Locale, Source, UserId, UserSource
+from telegrinder.node.nodes.state_mutator import State, StateMutator
+from telegrinder.node.nodes.text import Caption, HTMLCaption, HTMLText, Text, TextInteger, TextLiteral
+
+__all__ = (
+    "ABCTranslator",
+    "Animation",
+    "Attachment",
+    "Audio",
+    "BaseTranslator",
+    "BotUsername",
+    "CallbackQueryData",
+    "CallbackQueryDataJson",
+    "Caption",
+    "Channel",
+    "ChannelId",
+    "ChannelPost",
+    "ChannelPostId",
+    "ChatId",
+    "ChatMessageChannelPost",
+    "ChatMessageChannelPostAuthor",
+    "ChatMessageChannelPostChannel",
+    "ChatMessageChannelPostChannelId",
+    "ChatMessageChannelPostId",
+    "ChatSource",
+    "CommandInfo",
+    "Document",
+    "Error",
+    "EventNode",
+    "File",
+    "FileId",
+    "GlobalNode",
+    "HTMLCaption",
+    "HTMLText",
+    "I18NConfig",
+    "KeySeparator",
+    "Locale",
+    "Me",
+    "MediaGroup",
+    "MessageEntities",
+    "Payload",
+    "PayloadData",
+    "PayloadSerializer",
+    "Photo",
+    "Poll",
+    "ReplyMessage",
+    "Source",
+    "State",
+    "StateMutator",
+    "SuccessfulPayment",
+    "Text",
+    "TextInteger",
+    "TextLiteral",
+    "UserId",
+    "UserSource",
+    "Video",
+    "VideoNote",
+    "Voice",
+)