darkob 0.2.0__py3-none-any.whl

darkob/TheBot.py

@@ -0,0 +1,114 @@
+import re
+import asyncio
+from typing import Union, Optional
+import aiohttp
+from rich.console import Console
+
+import darkob
+from .bot import Methods
+from .bot.session import Session
+from .bot.updates import Updates
+from .bot.token import TokenString
+from .bot.exceptions import TokenError
+from .bot.registry import HandlerRegistry
+from .bot.bridge import DecoratorBridge
+from .bot.plugin import PluginManager
+
+console = Console(highlight=False)
+
+class Bot(Session, Updates, Methods):
+    TOKEN_PATTERN = re.compile(r'^[A-Z]{5}[0-9A-Z]{59}$')
+    DEFAULT_BASE_URL = "https://botapi.rubika.ir/v3"
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        token_string: Optional[str] = None,
+        password: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Union[int, float] = 30,
+        max_retries: Union[int, float] = 5,
+        verify_ssl: bool = True,
+        show_welcome: bool = True,
+        run_all_handlers: bool = True
+    ):
+        """
+        Initialize the Bot instance.
+
+        Parameters:
+            token (Optional[str]): Bot authentication token. If not provided
+                or invalid, the bot will prompt for it via console input.
+            token_string (Optional[str]): Encrypted TokenString. Takes priority over token.
+            password (Optional[str]): Password for encrypted TokenString.
+            base_url (str): Base API URL. Defaults to "https://botapi.rubika.ir/v3".
+            timeout (int): Request timeout in seconds. Defaults to 30.
+            max_retries (int): Maximum number of retry attempts on network
+                errors. Defaults to 5.
+            verify_ssl (bool): Verify TLS certificates. Defaults to True.
+                Only disable this if you understand the interception risk.
+            show_welcome (bool, optional): If True, show welcome message (default: True).
+            run_all_handlers (bool, optional): If True (default), every handler whose
+                constraints match an event is run, in registration order. If False,
+                only the first matching handler runs, so registration order decides
+                which handler wins.
+        """
+        darkob.show_welcome_message(show_welcome)
+
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._close_task: Optional["asyncio.Task"] = None
+        self._session_loop: Optional["asyncio.AbstractEventLoop"] = None
+
+        if token_string:
+            token = TokenString(token_string).to_token(password)
+            if not token:
+                raise TokenError(
+                    "Invalid token_string or wrong password.")
+        else:
+            token = (token or "").strip()
+            if not self.TOKEN_PATTERN.match(token):
+                token = self._get_token()
+
+        self.token = token
+        self.timeout = float(timeout)
+        self.max_retries = int(max_retries)
+        self.verify_ssl = bool(verify_ssl)
+        self.base_url = f"{base_url.rstrip('/')}/{token}"
+        self.run_all_handlers = bool(run_all_handlers)
+
+        self._registry = HandlerRegistry(self)
+        self._bridge = DecoratorBridge(self._registry)
+        self.plugin_manager = PluginManager(self)
+
+        for name in dir(type(self._bridge)):
+            if name.startswith('_'):
+                continue
+            attr = getattr(type(self._bridge), name, None)
+            if isinstance(attr, property):
+                setattr(self, name, getattr(self._bridge, name))
+
+    def _get_token(self) -> str:
+        while True:
+            console.print("Enter your bot token: ", style="bold yellow", end="")
+            token = input().strip()
+            if self.TOKEN_PATTERN.match(token):
+                return token
+            console.print("\nInvalid token format. Try again.\n", style="bold red")
+
+    def include_router(self, router):
+        """Register every handler declared on *router*, recursively.
+
+        Lets a bot be split into feature modules::
+
+            bot.include_router(admin_router)
+
+        Returns the router so calls can be chained.
+        """
+        from .router import Router
+
+        if not isinstance(router, Router):
+            raise TypeError(
+                f"include_router expects a Router, got {type(router).__name__}"
+            )
+
+        router.apply(self)
+        return router

darkob/TheClient.py

@@ -0,0 +1,234 @@
+from typing import Optional, Union, Literal
+import asyncio
+import os
+import logging
+import re
+from rich.console import Console
+from rich.text import Text
+import darkob
+from .client import Methods
+from .client.core.cipher import Cipher
+from .client.core.session import Session, StringSession
+from .client.exceptions import (
+    ApiVersionError,
+    PlatformError,
+    AuthError,
+    TimeoutError,
+    MaxRetriesError,
+    ProxyError,
+    SessionError
+)
+from .client.core.configs import DEFAULT_PLATFORM, PLATFORMS, VALID_PLATFORMS, USER_AGENT
+
+class Client(Methods):
+    USER_AGENT = USER_AGENT
+    API_VERSION = 6
+
+    def __init__(
+        self,
+        session: Optional[str] = None,
+        string_session: Optional[str] = None,
+        password: Optional[str] = None,
+        auth: Optional[str] = None,
+        private_key: Optional[Union[str, bytes]] = None,
+        timeout: Union[str, int, float] = 30,
+        proxy: Optional[str] = None,
+        verify_ssl: bool = True,
+        logger: Optional[logging.Logger] = None,
+        platform: Literal['web', 'pwa', 'android', 'rubx', 'rubikids', 'rubino'] = 'pwa',
+        api_version: Literal[5, 6] = 6,
+        max_retries: int = 5,
+        stop_on_first_match: bool = False,
+        continue_on_error: bool = True,
+        show_welcome: bool = True
+    ) -> None:
+        """
+        Initialize the Rubika client.
+
+        Parameters:
+            session (str, optional): Session file name or path. (api_version=6 only)
+            string_session (str, optional): StringSession string. Takes priority over 'session'.
+            password (str, optional): Password for encrypted StringSession. Required if StringSession was created with a password.
+            auth (str, optional): Authentication key.
+            private_key (str or bytes, optional): RSA private key. (api_version=6 only)
+            timeout (int or float, optional): Request timeout in seconds (default: 30).
+            proxy (str, optional): Proxy address (example: 'http://127.0.0.1:80').
+            verify_ssl (bool, optional): Verify TLS certificates (default: True).
+                Only disable this if you understand the risk; it makes the
+                connection vulnerable to interception.
+            logger (logging.Logger, optional): Logger instance.
+            platform: Literal['web', 'pwa', 'android', 'rubx', 'rubikids', 'rubino']: Client platform (default: 'pwa').
+            api_version: Literal[5, 6]: API version to use (default: 6).
+                - 6: Requires 'auth' + 'private_key' (or 'session').
+                - 5: Requires only 'auth'.
+            max_retries (int, optional): Maximum number of retries for requests (default: 5).
+            stop_on_first_match (bool, optional): If True, stop processing handlers after the first match (default: False).
+            continue_on_error (bool, optional): If True, continue trying other platforms on auth errors (default: True).
+            show_welcome (bool, optional): If True, show welcome message (default: True).
+
+        Raises:
+            ApiVersionError: If api_version is invalid.
+            PlatformError: If platform is invalid.
+            AuthError: If auth parameters are invalid.
+            TimeoutError: If timeout is invalid.
+            MaxRetriesError: If max_retries is invalid.
+            ProxyError: If proxy is invalid.
+            SessionError: If session or string_session is invalid.
+        """
+        darkob.show_welcome_message(show_welcome)
+
+        if type(self) is Client:
+            err_console = Console(stderr=True)
+            warning_msg = Text()
+            warning_msg.append("DeprecationWarning: ", style="bright_red")
+            warning_msg.append("'Client'", style="bright_red underline")
+            warning_msg.append(" is deprecated. Use ", style="bright_red")
+            warning_msg.append("'Messenger'", style="bright_green underline")
+            warning_msg.append(" instead.\n", style="bright_red")
+            err_console.print(warning_msg)
+        super().__init__()
+
+        if api_version not in (5, 6):
+            raise ApiVersionError("'api_version' must be 5 or 6.")
+
+        self.API_VERSION = api_version
+
+        if platform.lower() not in VALID_PLATFORMS:
+            raise PlatformError(
+                f"Invalid platform '{platform}'. Valid platforms are: {', '.join(VALID_PLATFORMS)}"
+            )
+
+        if api_version == 6:
+            if session is None and string_session is None and (auth is None or private_key is None):
+                raise AuthError("API v6 requires: 'session', 'string_session', OR both 'auth' and 'private_key'.")
+            if auth is not None and private_key is None:
+                raise AuthError("If 'auth' is provided, 'private_key' must also be provided.")
+            if private_key is not None and auth is None:
+                raise AuthError("If 'private_key' is provided, 'auth' must also be provided.")
+        elif api_version == 5:
+            if auth is None:
+                raise AuthError("API v5 requires: 'auth'.")
+            if private_key is not None:
+                raise AuthError("API v5 does not support 'private_key'.")
+            session = None
+            string_session = None
+
+        if auth is not None:
+            if not isinstance(auth, str):
+                raise AuthError("The 'auth' parameter must be a string.")
+            if not re.match(r'^[a-z]{32}$', auth):
+                raise AuthError("The 'auth' must be 32 lowercase letters only.")
+
+        if isinstance(timeout, bool):
+            raise TimeoutError("'timeout' must be a number, not a boolean.")
+        try:
+            timeout = float(timeout)
+        except (TypeError, ValueError):
+            raise TimeoutError("The 'timeout' parameter must be a number.")
+        if timeout <= 0:
+            raise TimeoutError("'timeout' must be greater than 0.")
+
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int):
+            raise MaxRetriesError("'max_retries' must be an integer.")
+        if max_retries < 0:
+            raise MaxRetriesError("'max_retries' must be >= 0.")
+
+        if proxy is not None and not isinstance(proxy, str):
+            raise ProxyError("'proxy' must be a string.")
+
+        if not isinstance(verify_ssl, bool):
+            raise ValueError("'verify_ssl' must be a boolean.")
+
+        self.DEFAULT_PLATFORM = DEFAULT_PLATFORM.copy()
+        self.DEFAULT_PLATFORM.update(PLATFORMS.get(platform.lower(), {}))
+        self._original_platform = platform.lower()
+
+        if session is not None:
+            if not isinstance(session, str):
+                raise SessionError("The 'session' parameter must be a string.")
+            self.session_name = os.path.basename(session)
+            self.session_path = session
+            session = Session(session)
+
+        elif string_session is not None:
+            try:
+                session = Session(string_session=string_session, password=password)
+                info = session.information()
+                if info:
+                    auth = info[1]
+                    private_key = info[4]
+                    self.session_name = f"darkob_{auth[:10]}"
+                    self.session_path = self.session_name
+            except ValueError:
+                raise SessionError(
+                    "String session is invalid or wrong password."
+                ) from None
+
+        else:
+            self.session_name = f"darkob_{auth[:10]}" if auth else None
+            self.session_path = self.session_name
+            session = Session(self.session_name) if self.session_name else None
+
+        if not isinstance(logger, logging.Logger):
+            logger = logging.getLogger(__name__)
+
+        if isinstance(private_key, str):
+            if not private_key.startswith('-----BEGIN RSA PRIVATE KEY-----'):
+                private_key = f'-----BEGIN RSA PRIVATE KEY-----\n{private_key}'
+            if not private_key.endswith('-----END RSA PRIVATE KEY-----'):
+                private_key += '\n-----END RSA PRIVATE KEY-----'
+
+        self.auth = auth
+        self.logger = logger
+        self.private_key = private_key
+        self.user_agent = self.USER_AGENT
+        self.timeout = timeout
+        self.session = session
+        self.proxy = proxy
+        self.verify_ssl = verify_ssl
+        self.decode_auth = None
+        self.import_key = None
+        self.guid = None
+        self.key = None
+        self.handlers = {}
+        self.max_retries = max_retries
+        self.stop_on_first_match = stop_on_first_match
+        self.continue_on_error = continue_on_error
+
+    def __del__(self) -> None:
+        try:
+            self.disconnect()
+        except Exception:
+            # Interpreter shutdown: nothing useful can be done here.
+            pass
+
+    def __enter__(self) -> "Client":
+        if not getattr(self, 'connection', None):
+            return self.start()
+        return self
+
+    def __exit__(self, *args, **kwargs):
+        try:
+            self.disconnect()
+        except Exception:
+            pass
+
+    async def __aenter__(self) -> "Client":
+        if not getattr(self, 'connection', None):
+            return await self.start()
+        return self
+
+    async def __aexit__(self, *args, **kwargs):
+        try:
+            await self.close()
+        except Exception:
+            pass
+
+    async def stop(self) -> None:
+        if hasattr(self, 'connection'):
+            if self.connection.session.closed:
+                return
+        await self.close()
+
+class Messenger(Client):
+    pass

darkob/__init__.py

@@ -0,0 +1,169 @@
+"""darkob — async Python library for the Rubika & Shad platforms.
+
+Derived from `maxrubika <https://github.com/MEH2RAB/maxrubika>`_ by
+MEHRAB Farahmand (MIT License), rebranded and hardened.
+
+Importing this package performs **no network I/O**. The optional update
+check is opt-in via :func:`check_for_updates`.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+from rich.console import Console
+from rich.text import Text
+
+from .TheBot import Bot
+from .TheBot import Bot as bot
+
+from .TheClient import Client, Messenger
+from .TheClient import Messenger as messenger
+
+from .shad import Shad
+from .shad import Shad as shad
+
+from .router import Router
+from .fsm import (
+    FSMContext,
+    JsonFileStorage,
+    MemoryStorage,
+    StateFilter,
+    Storage,
+)
+
+__author__ = "MEHRAB Farahmand"
+__maintainer__ = "Mani Keikhosravi"
+__version__ = "0.2.0"
+
+logger = logging.getLogger(__name__)
+
+_welcome_shown = False
+
+__all__ = [
+    "Bot",
+    "bot",
+    "Client",
+    "Messenger",
+    "messenger",
+    "Shad",
+    "shad",
+    "show_welcome_message",
+    "check_for_updates",
+    "Router",
+    "FSMContext",
+    "Storage",
+    "MemoryStorage",
+    "JsonFileStorage",
+    "StateFilter",
+    "__version__",
+]
+
+
+def show_welcome_message(show_welcome: bool = True) -> None:
+    """Print the one-time welcome banner.
+
+    This never performs network I/O. The banner is shown at most once per
+    process unless ``show_welcome`` is false.
+    """
+    global _welcome_shown
+
+    if not show_welcome or _welcome_shown:
+        return
+
+    _welcome_shown = True
+
+    console = Console()
+    text = Text()
+    text.append(
+        "Welcome to darkob — async library for Rubika & Shad",
+        style="bold magenta",
+    )
+    text.append(
+        f"\nCopyright © {datetime.now().year} darkob contributors "
+        "- All rights reserved.",
+        style="cyan",
+    )
+    text.append("\nGithub: ", style="white")
+    text.append(
+        "https://github.com/ManiTheFerfri/darkob", style="green underline"
+    )
+    text.append("\nDocument: ", style="white")
+    text.append(
+        "https://ManiTheFerfri.github.io/darkob\n", style="yellow underline"
+    )
+    console.print(text)
+
+
+def _parse_version(value: str) -> Tuple[int, ...]:
+    """Parse a version string into a comparable tuple.
+
+    Tolerates pre-release and non-numeric suffixes, e.g. ``"1.2.0rc1"``
+    becomes ``(1, 2, 1)`` rather than raising.
+    """
+    parts: List[int] = []
+    for chunk in value.split("."):
+        digits = "".join(ch for ch in chunk if ch.isdigit())
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
+
+
+def check_for_updates(
+    current_version: Optional[str] = None, *, timeout: float = 2.0
+) -> Optional[str]:
+    """Compare the installed version against the latest release on PyPI.
+
+    This is **opt-in** and is never called automatically. Call it yourself
+    if you want an update notice::
+
+        import darkob
+        darkob.check_for_updates()
+
+    Args:
+        current_version: Version to compare against; defaults to
+            :data:`__version__`.
+        timeout: Network timeout in seconds.
+
+    Returns:
+        The latest version string when an update is available, otherwise
+        ``None``. Never raises on network or parsing failures.
+    """
+    import json
+    from urllib.error import URLError
+    from urllib.request import urlopen
+
+    current_version = current_version or __version__
+
+    try:
+        with urlopen(
+            "https://pypi.org/pypi/darkob/json", timeout=timeout
+        ) as response:
+            latest = json.loads(response.read().decode("utf-8"))["info"][
+                "version"
+            ]
+    except (URLError, OSError, ValueError, KeyError) as exc:
+        logger.debug("Update check skipped: %s", exc)
+        return None
+
+    try:
+        is_newer = _parse_version(latest) > _parse_version(current_version)
+    except (TypeError, ValueError):
+        return None
+
+    if not is_newer:
+        return None
+
+    console = Console(stderr=True)
+    notice = Text()
+    notice.append(
+        f"A new version of darkob is available! "
+        f"(v{current_version} → v{latest})\n",
+        style="bold bright_red",
+    )
+    notice.append("   Run: ", style="white")
+    notice.append("pip install darkob --upgrade\n", style="gold1")
+    console.print(notice)
+
+    return latest

darkob/bot/__init__.py

@@ -0,0 +1,86 @@
+from ..hybrid import wrap_methods
+
+from .auto_delete_message import AutoDeleteMessage
+from .ban_member import BanMember
+from .delete_message import DeleteMessage
+from .download_file import DownloadFile
+from .edit_chat_keypad import EditChatKeypad
+from .edit_inline_keypad import EditInlineKeypad
+from .edit_message import EditMessage
+from .forward_message import ForwardMessage
+from .get_chat_info import GetChatInfo
+from .get_chat_member import GetChatMember
+from .get_file import GetFile
+from .get_me import GetMe
+from .get_token_string import GetTokenString
+from .get_updates import GetUpdates
+from .member_is_admin import MemberIsAdmin
+from .member_is_joined import MemberIsJoined
+from .member_is_owner import MemberIsOwner
+from .register_all_endpoints import RegisterAllEndpoints
+from .remove_chat_keypad import RemoveChatKeypad
+from .remove_member import RemoveMember
+from .request import Request
+from .request_send_file import RequestSendFile
+from .run import Run
+from .send_contact import SendContact
+from .send_file import SendFile
+from .send_gif import SendGif
+from .send_image import SendImage
+from .send_location import Sendlocation
+from .send_message import SendMessage
+from .send_music import SendMusic
+from .send_poll import SendPoll
+from .send_quiz import SendQuiz
+from .send_video import SendVideo
+from .send_voice import SendVoice
+from .set_commands import SetCommands
+from .start import Start
+from .unban_member import UnbanMember
+from .update_bot_endpoints import UpdateBotEndpoints
+from .upload_file import UploadFile
+
+class Methods(
+    AutoDeleteMessage,
+    BanMember,
+    DeleteMessage,
+    DownloadFile,
+    EditChatKeypad,
+    EditInlineKeypad,
+    EditMessage,
+    ForwardMessage,
+    GetChatInfo,
+    GetChatMember,
+    GetFile,
+    GetMe,
+    GetTokenString,
+    GetUpdates,
+    MemberIsAdmin,
+    MemberIsJoined,
+    MemberIsOwner,
+    RegisterAllEndpoints,
+    RemoveChatKeypad,
+    RemoveMember,
+    Request,
+    RequestSendFile,
+    Run,
+    SendContact,
+    SendFile,
+    SendGif,
+    SendImage,
+    Sendlocation,
+    SendMessage,
+    SendMusic,
+    SendPoll,
+    SendQuiz,
+    SendVideo,
+    SendVoice,
+    SetCommands,
+    Start,
+    UnbanMember,
+    UpdateBotEndpoints,
+    UploadFile
+):
+    pass
+
+wrap_methods(Methods)

darkob/bot/auto_delete_message.py

@@ -0,0 +1,24 @@
+from typing import Union
+import asyncio
+import darkob
+
+class AutoDeleteMessage:
+    async def auto_delete_message(
+        self: "darkob.Bot",
+        chat_id: str,
+        message_id: Union[str, int],
+        time: Union[float, int]
+    ):
+        """
+        Automatically delete a message after a specified time.
+
+        Parameters:
+            chat_id (str): chat_id of the object associated with the message (e.g., user, group, channel).
+            message_id (str): The ID of the message to be deleted.
+            time (Union[float, int]): The time delay (in seconds) before deleting the message.
+
+        Returns:
+            The updated information after deleting the message.
+        """
+        await asyncio.sleep(time)
+        return await self.delete_message(chat_id, message_id)

darkob/bot/ban_member.py

@@ -0,0 +1,37 @@
+import re
+import darkob
+from .exceptions import InvalidInput
+
+class BanMember:
+    async def ban_member(
+        self: "darkob.Bot",
+        chat_id: str,
+        sender_id: str
+    ):
+        """
+        Ban a member from a group or channel.
+
+        Parameters:
+            chat_id (str): chat_id of group (starts with 'g0') or channel (starts with 'c0').
+            sender_id (str): sender_id of member to ban (starts with 'u0').
+
+        Returns:
+            dict: API response.
+        """
+        chat_id_regex = r"^(@[a-zA-Z0-9_]{3,32}|(c0|g0|b0)[a-zA-Z0-9]{30})$"
+        sender_id_regex = r"^u0[a-zA-Z0-9]{30}$"
+
+        if not re.match(chat_id_regex, chat_id):
+            raise InvalidInput("Invalid 'chat_id' format.")
+
+        if chat_id.startswith('b0'):
+            raise InvalidInput("'chat_id' must not start with 'b0'.")
+
+        if not re.match(sender_id_regex, sender_id):
+            raise InvalidInput("Invalid 'sender_id' format.")
+
+        payload = {
+            'chat_id': chat_id,
+            'user_id': sender_id
+        }
+        return await self.request('POST', 'banChatMember', json = payload)

darkob/bot/bot_status.py

@@ -0,0 +1,31 @@
+"""Decorators for a user starting or stopping the bot."""
+from __future__ import annotations
+
+from typing import Callable
+
+from .filters import EventConstraint, IsStartedBot, IsStoppedBot
+from .registry import HandlerRegistry
+
+class BotStatusDecorators:
+    """Decorators that fire when a user starts or stops the bot."""
+
+    __slots__ = ('_registry',)
+
+    def __init__(self, registry: HandlerRegistry) -> None:
+        self._registry = registry
+
+    def on_started_bot(self, *constraints: EventConstraint) -> Callable:
+        """Handle a user starting the bot."""
+        merged = (IsStartedBot(),) + constraints
+
+        def deco(func: Callable) -> Callable:
+            return self._registry.store(func, *merged)
+        return deco
+
+    def on_stopped_bot(self, *constraints: EventConstraint) -> Callable:
+        """Handle a user stopping the bot."""
+        merged = (IsStoppedBot(),) + constraints
+
+        def deco(func: Callable) -> Callable:
+            return self._registry.store(func, *merged)
+        return deco