voidbale 1.0.0__py3-none-any.whl

voidbale/__init__.py

@@ -0,0 +1,15 @@
+from .bot import Bot, BotMessage, BotUser, BotChat, CallbackQuery, CommandInfo, Scheduler
+from .bot_manager import BotManager
+from .analytics import Analytics
+from .webhook.bot_server import AiohttpBotWebhookServer
+from .filters.bot import BotText, BotRegex
+from .utils.keyboard import InlineKeyboardBuilder, ReplyKeyboardBuilder, InlineKeyboardButton, ReplyKeyboardButton
+
+__version__ = "0.5.1"
+
+__all__ = (
+    "Bot", "BotMessage", "BotUser", "BotChat", "CallbackQuery", "CommandInfo",
+    "Scheduler", "BotManager", "Analytics", "AiohttpBotWebhookServer",
+    "BotText", "BotRegex", "InlineKeyboardBuilder", "ReplyKeyboardBuilder",
+    "InlineKeyboardButton", "ReplyKeyboardButton",
+)

voidbale/analytics.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+@dataclass
+class AnalyticsEvent:
+    name: str
+    timestamp: str
+    data: Dict[str, Any] = field(default_factory=dict)
+
+class Analytics:
+    def __init__(self, max_events: int = 10000):
+        self.max_events = max_events
+        self.events: List[AnalyticsEvent] = []
+        self.counters = Counter()
+    def track(self, name: str, **data: Any) -> AnalyticsEvent:
+        event = AnalyticsEvent(name, datetime.now(timezone.utc).isoformat(), data)
+        self.events.append(event)
+        self.counters[name] += 1
+        if len(self.events) > self.max_events:
+            self.events.pop(0)
+        return event
+    def count(self, name: str) -> int:
+        return self.counters[name]
+    def snapshot(self) -> Dict[str, int]:
+        return dict(self.counters)
+    def clear(self) -> None:
+        self.events.clear(); self.counters.clear()

voidbale/bot.py

@@ -0,0 +1,745 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Iterable, Iterator, List, Optional, Sequence, Union
+
+import aiohttp
+
+from .analytics import Analytics
+
+logger = logging.getLogger("voidbale.bot")
+
+
+@dataclass
+class BotUser:
+    raw: Dict[str, Any]
+
+    @property
+    def id(self) -> Optional[int]:
+        return self.raw.get("id")
+
+    @property
+    def username(self) -> Optional[str]:
+        return self.raw.get("username")
+
+    @property
+    def first_name(self) -> str:
+        return self.raw.get("first_name") or ""
+
+    @property
+    def last_name(self) -> str:
+        return self.raw.get("last_name") or ""
+
+    @property
+    def full_name(self) -> str:
+        return " ".join(x for x in (self.first_name, self.last_name) if x)
+
+
+@dataclass
+class BotChat:
+    raw: Dict[str, Any]
+
+    @property
+    def id(self) -> Optional[int]:
+        return self.raw.get("id")
+
+    @property
+    def type(self) -> Optional[str]:
+        return self.raw.get("type")
+
+    @property
+    def title(self) -> Optional[str]:
+        return self.raw.get("title")
+
+    @property
+    def username(self) -> Optional[str]:
+        return self.raw.get("username")
+
+
+class BotMessage:
+    def __init__(self, bot: "Bot", raw: Dict[str, Any]):
+        self.bot = bot
+        self.raw = raw if isinstance(raw, dict) else {}
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.raw
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.raw)
+
+    def __len__(self) -> int:
+        return len(self.raw)
+
+    def __repr__(self) -> str:
+        return f"BotMessage({self.raw!r})"
+
+    @property
+    def message_id(self) -> Optional[int]:
+        return self.raw.get("message_id")
+
+    @property
+    def text(self) -> str:
+        return self.raw.get("text") or self.raw.get("caption") or ""
+
+    @property
+    def caption(self) -> str:
+        return self.raw.get("caption") or ""
+
+    @property
+    def chat(self) -> BotChat:
+        return BotChat(self.raw.get("chat") or {})
+
+    @property
+    def chat_id(self) -> Optional[int]:
+        return self.chat.id
+
+    @property
+    def from_user(self) -> BotUser:
+        return BotUser(self.raw.get("from") or {})
+
+    @property
+    def user_id(self) -> Optional[int]:
+        return self.from_user.id
+
+    @property
+    def date(self) -> Optional[int]:
+        return self.raw.get("date")
+
+    @property
+    def photo(self) -> list:
+        return self.raw.get("photo") or []
+
+    @property
+    def document(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("document")
+
+    @property
+    def audio(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("audio")
+
+    @property
+    def video(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("video")
+
+    @property
+    def voice(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("voice")
+
+    @property
+    def sticker(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("sticker")
+
+    @property
+    def location(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("location")
+
+    @property
+    def contact(self) -> Optional[Dict[str, Any]]:
+        return self.raw.get("contact")
+
+    @property
+    def reply_to_message(self) -> Optional["BotMessage"]:
+        raw = self.raw.get("reply_to_message")
+        return BotMessage(self.bot, raw) if isinstance(raw, dict) else None
+
+    @property
+    def target_user_id(self) -> Optional[int]:
+        reply = self.reply_to_message
+        return reply.user_id if reply else self.user_id
+
+    async def ban(self, user_id: Any = None, **kwargs: Any) -> Any:
+        return await self.bot.ban_chat_member(self.chat_id, user_id if user_id is not None else self.target_user_id, **kwargs)
+
+    async def unban(self, user_id: Any = None, **kwargs: Any) -> Any:
+        return await self.bot.unban_chat_member(self.chat_id, user_id if user_id is not None else self.target_user_id, **kwargs)
+
+    async def mute(self, user_id: Any = None, **kwargs: Any) -> Any:
+        permissions = kwargs.pop("permissions", {"can_send_messages": False})
+        return await self.bot.restrict_chat_member(self.chat_id, user_id if user_id is not None else self.target_user_id, permissions, **kwargs)
+
+    async def promote(self, user_id: Any = None, **kwargs: Any) -> Any:
+        return await self.bot.promote_chat_member(self.chat_id, user_id if user_id is not None else self.target_user_id, **kwargs)
+
+    async def pin(self) -> Any:
+        return await self.bot.pin_chat_message(self.chat_id, self.message_id)
+
+    async def unpin(self) -> Any:
+        return await self.bot.unpin_chat_message(self.chat_id, self.message_id)
+
+    async def answer(self, text: str, **kwargs: Any) -> BotMessage:
+        return await self.bot.send_message(self.chat_id, text, **kwargs)
+
+    async def reply(self, text: str, **kwargs: Any) -> BotMessage:
+        return await self.bot.send_message(
+            self.chat_id, text, reply_to_message_id=self.message_id, **kwargs
+        )
+
+    async def edit(self, text: str, **kwargs: Any) -> BotMessage:
+        return await self.bot.edit_message(self.chat_id, self.message_id, text, **kwargs)
+
+    async def delete(self) -> Any:
+        return await self.bot.delete_message(self.chat_id, self.message_id)
+
+
+@dataclass
+class CallbackQuery:
+    bot: "Bot"
+    raw: Dict[str, Any]
+
+    @property
+    def id(self) -> Optional[str]:
+        return self.raw.get("id")
+
+    @property
+    def data(self) -> Optional[str]:
+        return self.raw.get("data")
+
+    @property
+    def message(self) -> Optional[BotMessage]:
+        raw = self.raw.get("message")
+        return BotMessage(self.bot, raw) if isinstance(raw, dict) else None
+
+    @property
+    def from_user(self) -> BotUser:
+        return BotUser(self.raw.get("from") or {})
+
+    async def answer(self, text: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
+        return await self.bot.answer_callback_query(self.id, text=text, **kwargs)
+
+
+@dataclass
+class CommandInfo:
+    command: str
+    args: str = ""
+
+    @property
+    def args_list(self) -> List[str]:
+        return self.args.split() if self.args else []
+
+
+class Scheduler:
+    def __init__(self) -> None:
+        self._tasks: set[asyncio.Task] = set()
+        self._running = True
+
+    def every(self, seconds: float, callback: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> asyncio.Task:
+        async def loop() -> None:
+            while self._running:
+                await asyncio.sleep(seconds)
+                await callback(*args, **kwargs)
+        task = asyncio.create_task(loop())
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return task
+
+    def once(self, delay: float, callback: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any) -> asyncio.Task:
+        async def run_once() -> None:
+            await asyncio.sleep(delay)
+            await callback(*args, **kwargs)
+        task = asyncio.create_task(run_once())
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return task
+
+    async def close(self) -> None:
+        self._running = False
+        for task in list(self._tasks):
+            task.cancel()
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+
+
+class Bot:
+    """Async Bale Bot API client with polling, webhooks, routing, media, keyboards and helpers."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = "https://tapi.bale.ai/bot",
+        request_timeout: float = 45.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ) -> None:
+        if not token or not isinstance(token, str):
+            raise ValueError("A valid Bale bot token is required")
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.request_timeout = request_timeout
+        self.max_retries = max(1, max_retries)
+        self.retry_delay = retry_delay
+        self._handlers: List[tuple[Callable[[Any], Any], Callable[..., Awaitable[Any]]]] = []
+        self._callback_handlers: List[tuple[Callable[[CallbackQuery], Any], Callable[..., Awaitable[Any]]]] = []
+        self._error_handlers: List[Callable[..., Awaitable[Any]]] = []
+        self._offset = 0
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._running = False
+        self.scheduler = Scheduler()
+        self.analytics = Analytics()
+        self.user: Optional[Dict[str, Any]] = None
+        self.metrics = {"updates": 0, "messages": 0, "callbacks": 0, "errors": 0, "requests": 0}
+        self._waiters: List[tuple[asyncio.Future, Optional[Callable[[Any], Any]], str]] = []
+
+    def _url(self, method: str) -> str:
+        return f"{self.base_url}{self.token}/{method}"
+
+    def on_message(self, predicate: Optional[Callable[[BotMessage], Any]] = None):
+        def decorator(func: Callable[..., Awaitable[Any]]):
+            self._handlers.append((predicate or (lambda message: True), func))
+            return func
+        return decorator
+
+    def message(self, *filters: Any):
+        def predicate(message: BotMessage) -> bool:
+            for item in filters:
+                if callable(item):
+                    result = item(message)
+                    if inspect.isawaitable(result):
+                        return False
+                    if not result:
+                        return False
+                elif isinstance(item, str) and message.text.lower() != item.lower():
+                    return False
+            return True
+        return self.on_message(predicate)
+
+    def command(self, *names: str):
+        normalized = {name.lstrip("/").lower() for name in names}
+        def predicate(message: BotMessage) -> bool:
+            text = message.text.strip()
+            if not text.startswith("/"):
+                return False
+            first = text.split(maxsplit=1)[0][1:]
+            command = first.split("@", 1)[0].lower()
+            return command in normalized
+        return self.on_message(predicate)
+
+    def text(self, value: Union[str, re.Pattern[str], Callable[[Any], bool]]):
+        def predicate(message: BotMessage) -> bool:
+            text = message.text
+            if isinstance(value, str):
+                return text.lower() == value.lower()
+            if hasattr(value, "search"):
+                return bool(value.search(text))
+            try:
+                return bool(value(message))
+            except (AttributeError, TypeError):
+                return bool(value(text))
+        return self.on_message(predicate)
+
+    def callback_query(self, predicate: Optional[Callable[[CallbackQuery], Any]] = None):
+        def decorator(func: Callable[..., Awaitable[Any]]):
+            self._callback_handlers.append((predicate or (lambda query: True), func))
+            return func
+        return decorator
+
+    async def wait_for(self, event: str = "message", *, check: Optional[Callable[[Any], Any]] = None, timeout: Optional[float] = None) -> Any:
+        future = asyncio.get_running_loop().create_future()
+        self._waiters.append((future, check, event))
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        finally:
+            self._waiters = [item for item in self._waiters if item[0] is not future]
+
+    def on_error(self, func: Callable[..., Awaitable[Any]]):
+        self._error_handlers.append(func)
+        return func
+
+    async def _request_once(self, method: str, *, payload: Optional[Dict[str, Any]] = None, form: Optional[aiohttp.FormData] = None) -> Dict[str, Any]:
+        if self._session is None or self._session.closed:
+            timeout = aiohttp.ClientTimeout(total=self.request_timeout)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+        self.metrics["requests"] += 1
+        self.analytics.track("request", method=method)
+        async with self._session.post(self._url(method), json=payload if form is None else None, data=form) as response:
+            data = await response.json(content_type=None)
+            if response.status >= 400 or not data.get("ok", False):
+                raise RuntimeError(data.get("description", f"Bale API HTTP {response.status}"))
+            return data
+
+    async def request(self, method: str, **payload: Any) -> Dict[str, Any]:
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries):
+            try:
+                return await self._request_once(method, payload=payload)
+            except (aiohttp.ClientError, asyncio.TimeoutError, RuntimeError) as exc:
+                last_error = exc
+                if attempt + 1 >= self.max_retries:
+                    break
+                await asyncio.sleep(self.retry_delay * (2 ** attempt))
+        self.metrics["errors"] += 1
+        self.analytics.track("error", error=str(last_error) if last_error else "unknown")
+        assert last_error is not None
+        raise last_error
+
+    async def request_multipart(self, method: str, fields: Dict[str, Any], files: Dict[str, Any]) -> Dict[str, Any]:
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries):
+            form = aiohttp.FormData()
+            opened = []
+            try:
+                for key, value in fields.items():
+                    form.add_field(key, str(value))
+                for key, value in files.items():
+                    if isinstance(value, (str, os.PathLike)):
+                        fp = open(value, "rb")
+                        opened.append(fp)
+                        form.add_field(key, fp, filename=Path(value).name)
+                    elif isinstance(value, tuple) and len(value) >= 2:
+                        content, filename = value[0], value[1]
+                        form.add_field(key, content, filename=filename)
+                    else:
+                        form.add_field(key, value)
+                return await self._request_once(method, form=form)
+            except (aiohttp.ClientError, asyncio.TimeoutError, RuntimeError) as exc:
+                last_error = exc
+                if attempt + 1 < self.max_retries:
+                    await asyncio.sleep(self.retry_delay * (2 ** attempt))
+            finally:
+                for fp in opened:
+                    fp.close()
+        self.metrics["errors"] += 1
+        self.analytics.track("error", error=str(last_error) if last_error else "unknown")
+        assert last_error is not None
+        raise last_error
+
+    async def get_me(self) -> Dict[str, Any]:
+        self.user = await self.request("getMe")
+        result = self.user.get("result", {})
+        self.analytics.track("get_me")
+        return result
+
+    async def get_updates(self, *, timeout: int = 30, limit: int = 100, allowed_updates: Optional[Sequence[str]] = None) -> List[Dict[str, Any]]:
+        payload: Dict[str, Any] = {"offset": self._offset, "timeout": timeout, "limit": limit}
+        if allowed_updates is not None:
+            payload["allowed_updates"] = list(allowed_updates)
+        return (await self.request("getUpdates", **payload)).get("result", [])
+
+    async def send_message(self, chat_id: Any, text: str, *, parse_mode: Optional[str] = None, reply_to_message_id: Optional[int] = None, reply_markup: Any = None, **kwargs: Any) -> BotMessage:
+        payload: Dict[str, Any] = {"chat_id": chat_id, "text": text, **kwargs}
+        if parse_mode: payload["parse_mode"] = parse_mode
+        if reply_to_message_id is not None: payload["reply_to_message_id"] = reply_to_message_id
+        if reply_markup is not None: payload["reply_markup"] = reply_markup
+        result = (await self.request("sendMessage", **payload)).get("result", {})
+        message = BotMessage(self, result)
+        self.analytics.track("send_message", chat_id=chat_id, message_id=message.message_id)
+        return message
+
+    async def edit_message(self, chat_id: Any, message_id: int, text: str, **kwargs: Any) -> BotMessage:
+        result = (await self.request("editMessageText", chat_id=chat_id, message_id=message_id, text=text, **kwargs)).get("result", {})
+        return BotMessage(self, result) if isinstance(result, dict) else BotMessage(self, {"result": result, "chat": {"id": chat_id}, "message_id": message_id, "text": text})
+
+    async def delete_message(self, chat_id: Any, message_id: int) -> Any:
+        return (await self.request("deleteMessage", chat_id=chat_id, message_id=message_id)).get("result")
+
+    async def forward_message(self, chat_id: Any, from_chat_id: Any, message_id: int, **kwargs: Any) -> BotMessage:
+        result = (await self.request("forwardMessage", chat_id=chat_id, from_chat_id=from_chat_id, message_id=message_id, **kwargs)).get("result", {})
+        return BotMessage(self, result)
+
+    async def copy_message(self, chat_id: Any, from_chat_id: Any, message_id: int, **kwargs: Any) -> BotMessage:
+        result = (await self.request("copyMessage", chat_id=chat_id, from_chat_id=from_chat_id, message_id=message_id, **kwargs)).get("result", {})
+        if isinstance(result, dict) and "message_id" in result:
+            return BotMessage(self, result)
+        return BotMessage(self, {"message_id": result, "chat": {"id": chat_id}})
+
+    async def get_chat(self, chat_id: Any) -> Dict[str, Any]:
+        return (await self.request("getChat", chat_id=chat_id)).get("result", {})
+
+    async def get_chat_member(self, chat_id: Any, user_id: Any) -> Dict[str, Any]:
+        return (await self.request("getChatMember", chat_id=chat_id, user_id=user_id)).get("result", {})
+
+    async def get_chat_administrators(self, chat_id: Any) -> List[Dict[str, Any]]:
+        return (await self.request("getChatAdministrators", chat_id=chat_id)).get("result", [])
+
+    async def get_chat_member_count(self, chat_id: Any) -> int:
+        return (await self.request("getChatMemberCount", chat_id=chat_id)).get("result", 0)
+
+    async def leave_chat(self, chat_id: Any) -> Any:
+        return (await self.request("leaveChat", chat_id=chat_id)).get("result")
+
+    async def set_webhook(self, url: str, **kwargs: Any) -> Any:
+        return (await self.request("setWebhook", url=url, **kwargs)).get("result")
+
+    async def delete_webhook(self, **kwargs: Any) -> Any:
+        return (await self.request("deleteWebhook", **kwargs)).get("result")
+
+    async def get_webhook_info(self) -> Dict[str, Any]:
+        return (await self.request("getWebhookInfo")).get("result", {})
+
+    async def send_chat_action(self, chat_id: Any, action: str) -> Any:
+        if isinstance(chat_id, BotMessage):
+            chat_id = chat_id.chat_id
+        elif isinstance(chat_id, BotChat):
+            chat_id = chat_id.id
+        elif isinstance(chat_id, dict):
+            chat_id = chat_id.get("id") or chat_id.get("chat_id")
+
+        if chat_id is None or str(chat_id).strip() == "":
+            raise ValueError("chat id is empty")
+
+        return (
+            await self.request(
+                "sendChatAction",
+                chat_id=str(chat_id),
+                action=str(action),
+            )
+        ).get("result")
+
+    async def answer_callback_query(self, callback_query_id: Any, text: Optional[str] = None, **kwargs: Any) -> Any:
+        payload = {"callback_query_id": callback_query_id, **kwargs}
+        if text is not None: payload["text"] = text
+        return (await self.request("answerCallbackQuery", **payload)).get("result")
+
+    async def send_photo(self, chat_id: Any, photo: Any, *, caption: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
+        if isinstance(photo, (str, os.PathLike)) and Path(photo).exists():
+            fields = {"chat_id": chat_id, **kwargs}
+            if caption is not None: fields["caption"] = caption
+            return (await self.request_multipart("sendPhoto", fields, {"photo": photo})).get("result", {})
+        return (await self.request("sendPhoto", chat_id=chat_id, photo=photo, caption=caption, **kwargs)).get("result", {})
+
+    async def send_document(self, chat_id: Any, document: Any, *, caption: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
+        if isinstance(document, (str, os.PathLike)) and Path(document).exists():
+            fields = {"chat_id": chat_id, **kwargs}
+            if caption is not None: fields["caption"] = caption
+            return (await self.request_multipart("sendDocument", fields, {"document": document})).get("result", {})
+        return (await self.request("sendDocument", chat_id=chat_id, document=document, caption=caption, **kwargs)).get("result", {})
+
+    async def _send_media(self, method: str, field: str, chat_id: Any, media: Any, *, caption: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
+        if isinstance(media, (str, os.PathLike)) and Path(media).exists():
+            fields = {"chat_id": chat_id, **kwargs}
+            if caption is not None: fields["caption"] = caption
+            return (await self.request_multipart(method, fields, {field: media})).get("result", {})
+        return (await self.request(method, chat_id=chat_id, **{field: media}, caption=caption, **kwargs)).get("result", {})
+
+    async def send_audio(self, chat_id: Any, audio: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendAudio", "audio", chat_id, audio, **kwargs)
+    async def send_video(self, chat_id: Any, video: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendVideo", "video", chat_id, video, **kwargs)
+    async def send_animation(self, chat_id: Any, animation: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendAnimation", "animation", chat_id, animation, **kwargs)
+    async def send_voice(self, chat_id: Any, voice: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendVoice", "voice", chat_id, voice, **kwargs)
+    async def send_video_note(self, chat_id: Any, video_note: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendVideoNote", "video_note", chat_id, video_note, **kwargs)
+    async def send_sticker(self, chat_id: Any, sticker: Any, **kwargs: Any) -> Dict[str, Any]: return await self._send_media("sendSticker", "sticker", chat_id, sticker, **kwargs)
+
+    async def send_location(self, chat_id: Any, latitude: float, longitude: float, **kwargs: Any) -> Dict[str, Any]:
+        return (await self.request("sendLocation", chat_id=chat_id, latitude=latitude, longitude=longitude, **kwargs)).get("result", {})
+
+    async def send_contact(self, chat_id: Any, phone_number: str, first_name: str, **kwargs: Any) -> Dict[str, Any]:
+        return (await self.request("sendContact", chat_id=chat_id, phone_number=phone_number, first_name=first_name, **kwargs)).get("result", {})
+
+    async def send_venue(self, chat_id: Any, latitude: float, longitude: float, title: str, address: str, **kwargs: Any) -> Dict[str, Any]:
+        return (await self.request("sendVenue", chat_id=chat_id, latitude=latitude, longitude=longitude, title=title, address=address, **kwargs)).get("result", {})
+
+    async def send_media_group(self, chat_id: Any, media: Sequence[Dict[str, Any]], **kwargs: Any) -> List[Dict[str, Any]]:
+        return (await self.request("sendMediaGroup", chat_id=chat_id, media=list(media), **kwargs)).get("result", [])
+
+    async def get_file(self, file_id: str) -> Dict[str, Any]:
+        return (await self.request("getFile", file_id=file_id)).get("result", {})
+
+    async def download_file(self, file_path: str, destination: Union[str, os.PathLike]) -> Path:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=self.request_timeout))
+        url = f"https://tapi.bale.ai/file/bot{self.token}/{file_path}"
+        target = Path(destination)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        async with self._session.get(url) as response:
+            response.raise_for_status()
+            target.write_bytes(await response.read())
+        return target
+
+    async def pin_chat_message(self, chat_id: Any, message_id: int, **kwargs: Any) -> Any:
+        return (await self.request("pinChatMessage", chat_id=chat_id, message_id=message_id, **kwargs)).get("result")
+
+    async def unpin_chat_message(self, chat_id: Any, message_id: Optional[int] = None, **kwargs: Any) -> Any:
+        payload = {"chat_id": chat_id, **kwargs}
+        if message_id is not None: payload["message_id"] = message_id
+        return (await self.request("unpinChatMessage", **payload)).get("result")
+
+    async def ban_chat_member(self, chat_id: Any, user_id: Any, **kwargs: Any) -> Any:
+        return (await self.request("banChatMember", chat_id=chat_id, user_id=user_id, **kwargs)).get("result")
+
+    async def unban_chat_member(self, chat_id: Any, user_id: Any, **kwargs: Any) -> Any:
+        return (await self.request("unbanChatMember", chat_id=chat_id, user_id=user_id, **kwargs)).get("result")
+
+    async def restrict_chat_member(self, chat_id: Any, user_id: Any, permissions: Any, **kwargs: Any) -> Any:
+        if isinstance(chat_id, BotMessage):
+            chat_id = chat_id.chat_id
+        elif isinstance(chat_id, BotChat):
+            chat_id = chat_id.id
+        elif isinstance(chat_id, dict):
+            chat_id = chat_id.get("id") or chat_id.get("chat_id")
+
+        if chat_id is None or str(chat_id).strip() == "":
+            raise ValueError("chat id is empty")
+
+        if user_id is None or str(user_id).strip() == "":
+            raise ValueError("user id is empty")
+
+        if not isinstance(permissions, dict):
+            raise TypeError("permissions must be a dictionary")
+
+        try:
+            result = await self.request(
+                "getChatMember",
+                chat_id=str(chat_id),
+                user_id=int(user_id),
+            )
+            member = result.get("result")
+            if not member:
+                raise RuntimeError("کاربر وجود ندارد")
+        except RuntimeError as exc:
+            error_text = str(exc).lower()
+            if (
+                "no such group or user" in error_text
+                or "user not found" in error_text
+                or "user does not exist" in error_text
+            ):
+                raise RuntimeError("کاربر وجود ندارد") from exc
+            raise
+
+        return (
+            await self.request(
+                "restrictChatMember",
+                chat_id=str(chat_id),
+                user_id=int(user_id),
+                permissions=permissions,
+                **kwargs,
+            )
+        ).get("result")
+
+    async def promote_chat_member(self, chat_id: Any, user_id: Any, **kwargs: Any) -> Any:
+        return (await self.request("promoteChatMember", chat_id=chat_id, user_id=user_id, **kwargs)).get("result")
+
+    async def kick_chat_member(self, chat_id: Any, user_id: Any, **kwargs: Any) -> Any:
+        return await self.ban_chat_member(chat_id, user_id, **kwargs)
+
+    async def mute_chat_member(self, chat_id: Any, user_id: Any, *, permissions: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any:
+        if permissions is None:
+            permissions = {"can_send_messages": False}
+        return await self.restrict_chat_member(chat_id, user_id, permissions, **kwargs)
+
+    async def unmute_chat_member(self, chat_id: Any, user_id: Any, *, permissions: Optional[Dict[str, Any]] = None, **kwargs: Any) -> Any:
+        if permissions is None:
+            permissions = {"can_send_messages": True}
+        return await self.restrict_chat_member(chat_id, user_id, permissions, **kwargs)
+
+    async def set_chat_title(self, chat_id: Any, title: str) -> Any:
+        return (await self.request("setChatTitle", chat_id=chat_id, title=title)).get("result")
+
+    async def set_chat_description(self, chat_id: Any, description: str = "") -> Any:
+        return (await self.request("setChatDescription", chat_id=chat_id, description=description)).get("result")
+
+    async def get_user_profile_photos(self, user_id: Any, **kwargs: Any) -> Dict[str, Any]:
+        return (await self.request("getUserProfilePhotos", user_id=user_id, **kwargs)).get("result", {})
+
+    async def edit_reply_markup(self, chat_id: Any, message_id: int, reply_markup: Any) -> Any:
+        return (await self.request("editMessageReplyMarkup", chat_id=chat_id, message_id=message_id, reply_markup=reply_markup)).get("result")
+
+    async def broadcast(self, chat_ids: Iterable[Any], text: str, *, delay: float = 0.05, concurrency: int = 1) -> Dict[str, Any]:
+        semaphore = asyncio.Semaphore(max(1, concurrency))
+        success = 0
+        failed: Dict[str, str] = {}
+        start = time.monotonic()
+
+        async def send(chat_id: Any) -> None:
+            nonlocal success
+            async with semaphore:
+                try:
+                    await self.send_message(chat_id, text)
+                    success += 1
+                except Exception as exc:
+                    failed[str(chat_id)] = str(exc)
+                if delay:
+                    await asyncio.sleep(delay)
+
+        await asyncio.gather(*(send(chat_id) for chat_id in chat_ids))
+        return {"success": success, "failed": failed, "duration": time.monotonic() - start}
+
+    async def _dispatch(self, update: Dict[str, Any]) -> None:
+        self.metrics["updates"] += 1
+        raw_message = update.get("message") or update.get("edited_message") or update.get("channel_post")
+        if isinstance(raw_message, dict):
+            self.metrics["messages"] += 1
+            message = BotMessage(self, raw_message)
+            for future, check, event_name in list(self._waiters):
+                if event_name == "message" and not future.done():
+                    try:
+                        matched = check(message) if check else True
+                        if inspect.isawaitable(matched):
+                            matched = await matched
+                        if matched:
+                            future.set_result(message)
+                    except Exception as exc:
+                        if not future.done():
+                            future.set_exception(exc)
+            for predicate, handler in list(self._handlers):
+                try:
+                    result = predicate(message)
+                    if inspect.isawaitable(result):
+                        result = await result
+                    if result:
+                        await handler(message)
+                except Exception as exc:
+                    await self._handle_error(exc, message)
+        callback = update.get("callback_query")
+        if isinstance(callback, dict):
+            self.metrics["callbacks"] += 1
+            query = CallbackQuery(self, callback)
+            for predicate, handler in list(self._callback_handlers):
+                try:
+                    result = predicate(query)
+                    if inspect.isawaitable(result): result = await result
+                    if result:
+                        await handler(query)
+                except Exception as exc:
+                    await self._handle_error(exc, query)
+
+    async def _handle_error(self, exc: Exception, event: Any) -> None:
+        self.metrics["errors"] += 1
+        if self._error_handlers:
+            for handler in self._error_handlers:
+                try:
+                    await handler(exc, event)
+                except Exception:
+                    logger.exception("VoidBale error handler failed")
+        else:
+            logger.exception("VoidBale handler error", exc_info=exc)
+
+    async def start_polling(self, *, timeout: int = 30, limit: int = 100, allowed_updates: Optional[Sequence[str]] = None) -> None:
+        self._running = True
+        if self.user is None:
+            try:
+                await self.get_me()
+            except Exception:
+                logger.warning("Could not validate bot token before polling", exc_info=True)
+        try:
+            while self._running:
+                updates = await self.get_updates(timeout=timeout, limit=limit, allowed_updates=allowed_updates)
+                for update in updates:
+                    update_id = update.get("update_id")
+                    if isinstance(update_id, int):
+                        self._offset = update_id + 1
+                    await self._dispatch(update)
+        finally:
+            await self.close()
+
+    async def close(self) -> None:
+        self._running = False
+        await self.scheduler.close()
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    def run(self, **kwargs: Any) -> None:
+        asyncio.run(self.start_polling(**kwargs))

voidbale/bot_manager.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+from typing import Dict
+from .bot import Bot
+
+class BotManager:
+    def __init__(self):
+        self.bots: Dict[str, Bot] = {}
+    def add(self, name: str, token: str, **kwargs) -> Bot:
+        bot = Bot(token, **kwargs)
+        self.bots[name] = bot
+        return bot
+    def get(self, name: str) -> Bot:
+        return self.bots[name]
+    async def close(self):
+        for bot in self.bots.values():
+            await bot.close()

voidbale/filters/__init__.py

@@ -0,0 +1,3 @@
+from .bot import BotText, BotRegex
+
+__all__ = ("BotText", "BotRegex")

voidbale/filters/bot.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from typing import Any
+import re
+
+class BotFilter:
+    def __init__(self, predicate):
+        self.predicate = predicate
+    def __call__(self, message):
+        return self.predicate(message)
+
+class BotText(BotFilter):
+    def __init__(self, text: str, ignore_case: bool = True):
+        super().__init__(lambda m: (m.text.lower() if ignore_case else m.text) == (text.lower() if ignore_case else text))
+
+class BotRegex(BotFilter):
+    def __init__(self, pattern: str, flags: int = 0):
+        rx = re.compile(pattern, flags)
+        super().__init__(lambda m: bool(rx.search(m.text)))

voidbale/utils/__init__.py

@@ -0,0 +1,3 @@
+from .keyboard import InlineKeyboardBuilder, ReplyKeyboardBuilder, InlineKeyboardButton, ReplyKeyboardButton
+
+__all__ = ("InlineKeyboardBuilder", "ReplyKeyboardBuilder", "InlineKeyboardButton", "ReplyKeyboardButton")

voidbale/utils/keyboard.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field
+
+
+class InlineKeyboardButton(BaseModel):
+    text: str
+    url: Optional[str] = None
+    callback_data: Optional[str] = None
+    copy_text: Optional[str] = None
+
+
+class ReplyKeyboardButton(BaseModel):
+    text: str
+
+
+class InlineKeyboardBuilder:
+    """
+    Fluid builder for constructing Inline Keyboards.
+
+    Example:
+        builder = InlineKeyboardBuilder()
+        builder.button(text="وبسایت", url="https://voidbale.ir")
+        builder.button(text="کلیک", callback_data="btn_click")
+        builder.button(text="کپی کد", copy_text="CODE123")
+        builder.adjust(2)
+        markup = builder.as_markup()
+    """
+
+    def __init__(self) -> None:
+        self._buttons: List[InlineKeyboardButton] = []
+        self._sizes: List[int] = []
+
+    @property
+    def buttons(self) -> List[InlineKeyboardButton]:
+        return self._buttons
+
+    def button(
+        self,
+        text: str,
+        url: Optional[str] = None,
+        callback_data: Optional[str] = None,
+        copy_text: Optional[str] = None,
+        **kwargs: Any,
+    ) -> InlineKeyboardBuilder:
+        self._buttons.append(
+            InlineKeyboardButton(
+                text=text,
+                url=url,
+                callback_data=callback_data,
+                copy_text=copy_text,
+                **kwargs,
+            )
+        )
+        return self
+
+    def add(self, *buttons: InlineKeyboardButton) -> InlineKeyboardBuilder:
+        self._buttons.extend(buttons)
+        return self
+
+    def row(self, *buttons: InlineKeyboardButton) -> InlineKeyboardBuilder:
+        self._buttons.extend(buttons)
+        return self
+
+    def attach(self, builder: InlineKeyboardBuilder) -> InlineKeyboardBuilder:
+        self._buttons.extend(builder._buttons)
+        return self
+
+    def adjust(self, *sizes: int) -> InlineKeyboardBuilder:
+        self._sizes = list(sizes) if sizes else [1]
+        return self
+
+    def export(self, *sizes: int) -> List[List[InlineKeyboardButton]]:
+        layout_sizes = list(sizes) if sizes else (self._sizes if self._sizes else [1])
+        result: List[List[InlineKeyboardButton]] = []
+        buttons_copy = self._buttons.copy()
+        size_idx = 0
+
+        while buttons_copy:
+            current_size = layout_sizes[size_idx % len(layout_sizes)]
+            chunk = buttons_copy[:current_size]
+            result.append(chunk)
+            buttons_copy = buttons_copy[current_size:]
+            size_idx += 1
+
+        return result
+
+    def as_markup(self, *sizes: int) -> List[List[Dict[str, Any]]]:
+        grid = self.export(*sizes)
+        return [[b.model_dump(exclude_none=True) for b in row] for row in grid]
+
+
+class ReplyKeyboardBuilder:
+    """
+    Fluid builder for constructing Reply/Menu Keyboards.
+
+    Example:
+        builder = ReplyKeyboardBuilder()
+        builder.button(text="ارسال موقعیت")
+        builder.button(text="تماس با پشتیبانی")
+        builder.adjust(2)
+        markup = builder.as_markup()
+    """
+
+    def __init__(self) -> None:
+        self._buttons: List[ReplyKeyboardButton] = []
+        self._sizes: List[int] = []
+
+    @property
+    def buttons(self) -> List[ReplyKeyboardButton]:
+        return self._buttons
+
+    def button(self, text: str, **kwargs: Any) -> ReplyKeyboardBuilder:
+        self._buttons.append(ReplyKeyboardButton(text=text, **kwargs))
+        return self
+
+    def add(self, *buttons: ReplyKeyboardButton) -> ReplyKeyboardBuilder:
+        self._buttons.extend(buttons)
+        return self
+
+    def row(self, *buttons: ReplyKeyboardButton) -> ReplyKeyboardBuilder:
+        self._buttons.extend(buttons)
+        return self
+
+    def attach(self, builder: ReplyKeyboardBuilder) -> ReplyKeyboardBuilder:
+        self._buttons.extend(builder._buttons)
+        return self
+
+    def adjust(self, *sizes: int) -> ReplyKeyboardBuilder:
+        self._sizes = list(sizes) if sizes else [1]
+        return self
+
+    def export(self, *sizes: int) -> List[List[ReplyKeyboardButton]]:
+        layout_sizes = list(sizes) if sizes else (self._sizes if self._sizes else [1])
+        result: List[List[ReplyKeyboardButton]] = []
+        buttons_copy = self._buttons.copy()
+        size_idx = 0
+
+        while buttons_copy:
+            current_size = layout_sizes[size_idx % len(layout_sizes)]
+            chunk = buttons_copy[:current_size]
+            result.append(chunk)
+            buttons_copy = buttons_copy[current_size:]
+            size_idx += 1
+
+        return result
+
+    def as_markup(self, *sizes: int) -> List[List[Dict[str, Any]]]:
+        grid = self.export(*sizes)
+        return [[b.model_dump(exclude_none=True) for b in row] for row in grid]

voidbale/webhook/__init__.py

@@ -0,0 +1,3 @@
+from .bot_server import AiohttpBotWebhookServer
+
+__all__ = ("AiohttpBotWebhookServer",)

voidbale/webhook/bot_server.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+import asyncio
+from aiohttp import web
+from typing import Optional
+
+class AiohttpBotWebhookServer:
+    def __init__(self, bot, path: str = "/webhook", secret_token: Optional[str] = None):
+        self.bot = bot
+        self.path = path
+        self.secret_token = secret_token
+        self.app = web.Application()
+        self.app.router.add_post(path, self.handle)
+        self.app.router.add_get("/health", self.health)
+
+    async def health(self, request):
+        return web.json_response({"ok": True, "service": "voidbale-bot-webhook"})
+
+    async def handle(self, request):
+        if self.secret_token and request.headers.get("X-Bale-Bot-Api-Secret-Token") != self.secret_token:
+            return web.Response(status=403, text="Forbidden")
+        try:
+            update = await request.json()
+        except Exception:
+            return web.Response(status=400, text="Expected JSON")
+        asyncio.create_task(self.bot._dispatch(update))
+        return web.json_response({"ok": True})
+
+    def run(self, host: str = "0.0.0.0", port: int = 8080):
+        web.run_app(self.app, host=host, port=port)

voidbale-1.0.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: voidbale
+Version: 1.0.0
+Summary: Modern, fast, fully asynchronous Python framework for Bale Messenger.
+Author-email: Amin Madani <aminmadani112@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aminmadaniofficial/aiobale
+Project-URL: Repository, https://github.com/aminmadaniofficial/aiobale
+Project-URL: Documentation, https://aminmadaniofficial.github.io/aiobale/
+Project-URL: PyPI, https://pypi.org/project/voidbale/
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0,>=3.9
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: typing_extensions<5.0,>=4.0
+Dynamic: license-file
+
+# VoidBale
+
+VoidBale یک کتابخانه پایتون برای ساخت ربات‌های Bale با Bot Token است.
+
+## Polling
+
+```python
+import asyncio
+from voidbale import Bot
+
+bot = Bot("YOUR_BALE_BOT_TOKEN")
+
+@bot.command("start")
+async def start(message):
+    await message.answer("سلام!")
+
+asyncio.run(bot.start_polling())
+```
+
+## Webhook
+
+```python
+from voidbale import AiohttpBotWebhookServer, Bot
+
+bot = Bot("YOUR_BALE_BOT_TOKEN")
+
+@bot.command("start")
+async def start(message):
+    await message.answer("سلام!")
+
+await bot.set_webhook("https://example.com/webhook")
+server = AiohttpBotWebhookServer(bot, path="/webhook")
+server.run(host="0.0.0.0", port=8080)
+```
+
+این بسته فقط برای Bale Bot API و Webhook طراحی شده است و قابلیت‌های حساب کاربری یا self-bot ندارد.

voidbale-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+voidbale/__init__.py,sha256=NlmmTYwOKCX1cRxt8ezda9AQAjr_fgFTU79g6euFs_4,688
+voidbale/analytics.py,sha256=6hJfXZnYxgMfX-U-iHyQ32hZJ9dStkLIeCWLr143-nU,1043
+voidbale/bot.py,sha256=m7I9YzLerv-mh7ogKFnS2nsGFKL2OcvoWZcZfDGwO4o,33030
+voidbale/bot_manager.py,sha256=xpZGyTPSlg6bjAyvTbmCbnOD3CfAbYEqap1oo_H5NI0,469
+voidbale/filters/__init__.py,sha256=QF5mQnK7X_Q7jH8_QIEzbVrMjRikS5UK9GuNGdALWZU,70
+voidbale/filters/bot.py,sha256=YIlIPAlmz-y6ro4s5wFXmy5FcT3ZSa0jkH9mTpUANbs,621
+voidbale/utils/__init__.py,sha256=8X-Oneqrm9_bfrKBcOLrA_JZ9C5P9oAD_HGpElJMRH0,217
+voidbale/utils/keyboard.py,sha256=vSWQQgrShYdEwFhmFulT4lCLLiWP_w1j3bVMEbTBTUU,4780
+voidbale/webhook/__init__.py,sha256=h1-VwRHK6lX42-nBXcBwfdkKjw_FGqyKLXkPZx6dslw,88
+voidbale/webhook/bot_server.py,sha256=w8-9PkqL-Ofx47s6E-usR13nqXHlnNne7JHZtgrFCew,1146
+voidbale-1.0.0.dist-info/licenses/LICENSE,sha256=qxvPB-Wx_YTI1oIVQUZvYIt7G5UlUR3ntE4PYFXTJmM,1123
+voidbale-1.0.0.dist-info/METADATA,sha256=RNoiYtD3sRlUcsiXTDqp4Kg7lH24SiPECp9Aw1B1ICs,1535
+voidbale-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+voidbale-1.0.0.dist-info/entry_points.txt,sha256=6qr1ka_7wC4FFnvTog3uegkABDRA9I1G7RF4ZYwob1g,52
+voidbale-1.0.0.dist-info/top_level.txt,sha256=lZ62KFfA3xMZ5SrkEq-FLIXAS_GjvRXe_S8dD2kyafY,9
+voidbale-1.0.0.dist-info/RECORD,,

voidbale-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

voidbale-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+voidbale = voidbale.cli.main:main

voidbale-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Alireza Jahani | Enalite LD
+Copyright (c) 2026 Mohammadamin Madani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voidbale-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+voidbale