RubigramClient 1.7.17__py3-none-any.whl

rubigram/__init__.py

@@ -0,0 +1,15 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from . import errors, enums, types, filters
+from .state import State, Storage
+from .client import Client
+from .server import Server
+from .rubino import Rubino
+
+__version__ = "1.7.17"
+__author__ = "PyJavad"
+__github__ = "https://github.ocm/DevJavad/rubigram"
+__message__ = "Welcome to Rubigram Client\nYou are using version %s", __version__

rubigram/client.py

@@ -0,0 +1,294 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+from __future__ import annotations
+
+from typing import Optional, Callable, Union
+from .enums import ParseMode
+from .methods import Methods
+from .state import Storage, State
+from .http_session import HttpSession
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+class Client(Methods):
+    """
+    Main client class for interacting with the Rubika Bot API.
+
+    This class extends Methods to provide API functionality and manages
+    the bot's lifecycle, webhook configuration, message handlers, and
+    connection settings.
+
+    Parameters:
+        token (str):
+            Bot token obtained from @RubikaBot.
+
+        webhook (Optional[str], optional):
+            Webhook URL for receiving updates. If None, long polling is used.
+            Defaults to None.
+
+        parse_mode (Union[str, "ParseMode"], optional):
+            Default parse mode for text messages. Can be "markdown", "html",
+            or a ParseMode enum value. Defaults to "markdown".
+
+        storage (Optional["Storage"], optional):
+            Storage instance for persisting user states and data.
+            If None, a new Storage instance is created. Defaults to None.
+
+        proxy (Optional[str], optional):
+            Proxy URL for HTTP requests (e.g., "http://proxy.com:8080").
+            Defaults to None.
+
+        retries (int, optional):
+            Number of retries for failed HTTP requests. Defaults to 3.
+
+        delay (float, optional):
+            Initial delay between retries in seconds. Defaults to 1.0.
+
+        backoff (int, optional):
+            Exponential backoff multiplier for retries. Defaults to 2.
+
+        timeout (float, optional):
+            Total timeout for HTTP requests in seconds. Defaults to 100.0.
+
+        connect_timeout (float, optional):
+            Connection establishment timeout in seconds. Defaults to 30.0.
+
+        read_timeout (float, optional):
+            Socket read timeout in seconds. Defaults to 50.0.
+
+        max_connections (int, optional):
+            Maximum number of simultaneous HTTP connections. Defaults to 100.
+
+    Attributes:
+        token (str): Bot authentication token.
+        webhook (Optional[str]): Configured webhook URL.
+        parse_mode (Union[str, ParseMode]): Default parse mode.
+        storage (Storage): User state storage instance.
+        proxy (Optional[str]): Proxy URL for requests.
+        retries (int): Number of retry attempts.
+        delay (float): Initial retry delay.
+        backoff (int): Retry backoff multiplier.
+        http (HttpSession): HTTP session manager.
+        offset_id (Union[str, None]): Last processed update ID for polling.
+        set_new_endpoint (bool): Flag to configure endpoints on startup.
+        api (str): Base API endpoint URL.
+        new_message_handlers (list[Callable]): Handlers for new messages.
+        inline_message_handlers (list[Callable]): Handlers for inline queries.
+        update_message_handlers (list[Callable]): Handlers for message updates.
+        remove_message_handlers (list[Callable]): Handlers for message deletions.
+        started_bot_handlers (list[Callable]): Handlers for bot start events.
+        stopped_bot_handlers (list[Callable]): Handlers for bot stop events.
+        start_handlers (list[Callable]): Handlers for client start.
+        stop_handlers (list[Callable]): Handlers for client stop.
+        router_handlers (list[Callable]): Handlers for routing updates.
+
+    Example:
+    .. code-block:: python
+        # Basic client
+        client = Client(token="YOUR_BOT_TOKEN")
+
+        # Client with webhook
+        client = Client(
+            token="YOUR_BOT_TOKEN",
+            webhook="https://example.com/webhook",
+            parse_mode="html",
+            retries=5
+        )
+
+        # Client with storage and proxy
+        storage = Storage()
+        client = Client(
+            token="YOUR_BOT_TOKEN",
+            storage=storage,
+            proxy="http://proxy:8080"
+        )
+    """
+
+    def __init__(
+        self,
+        token: str,
+        webhook: Optional[str] = None,
+        parse_mode: Union[str, ParseMode] = ParseMode.MARKDOWN,
+        storage: Optional[Storage] = None,
+        proxy: Optional[str] = None,
+        retries: int = 3,
+        delay: float = 1.0,
+        backoff: int = 2,
+        max_delay: float = 5.0,
+        timeout: float = 100.0,
+        connect_timeout: float = 30.0,
+        read_timeout: float = 50.0,
+        max_connections: int = 100,
+        offset_id: Optional[str] = None
+    ):
+        self.token = token
+        self.webhook = webhook
+        self.parse_mode = parse_mode
+        self.storage = storage or Storage()
+        self.proxy = proxy
+        self.retries = retries
+        self.delay = delay
+        self.backoff = backoff
+        self.max_delay = max_delay
+        self.offset_id = offset_id
+        self.http = HttpSession(
+            timeout, connect_timeout, read_timeout, max_connections
+        )
+
+        self.set_new_endpoint: bool = True
+        self.api: str = f"https://botapi.rubika.ir/v3/{token}/"
+
+        self.new_message_handlers: list[Callable] = []
+        self.inline_message_handlers: list[Callable] = []
+        self.update_message_handlers: list[Callable] = []
+        self.remove_message_handlers: list[Callable] = []
+        self.started_bot_handlers: list[Callable] = []
+        self.stopped_bot_handlers: list[Callable] = []
+        self.start_handlers: list[Callable] = []
+        self.stop_handlers: list[Callable] = []
+        self.router_handlers: list[Callable] = []
+
+        super().__init__()
+
+    def state(self, user_id: str):
+        """
+        Get a State object for managing user conversation state.
+
+        Parameters:
+            user_id (str):
+                Unique identifier for the user (chat_id).
+
+        Returns:
+            State: A State instance bound to the specified user.
+
+        Example:
+        .. code-block:: python
+            user_state = client.state("b0123456789")
+            await user_state.update({"step": "waiting_for_name"})
+            data = await user_state.get()
+        """
+        return State(self.storage, user_id)
+
+    async def start(self):
+        """
+        Start the client and establish HTTP connections.
+
+        This method:
+        1. Connects the HTTP session
+        2. Executes all registered start handlers
+        3. Logs any handler errors
+
+        Note:
+            Called automatically when using context manager or startup().
+
+        Example:
+        .. code-block:: python
+            await client.start()
+        """
+        await self.http.connect()
+        for app in self.start_handlers:
+            try:
+                await app(self)
+            except Exception as error:
+                logger.warning("Start app, error=%s", error)
+
+    async def stop(self):
+        """
+        Stop the client and close HTTP connections.
+
+        This method:
+        1. Executes all registered stop handlers
+        2. Disconnects the HTTP session
+        3. Logs any handler errors
+
+        Note:
+            Called automatically when using context manager or cleanup().
+
+        Example:
+        .. code-block:: python
+            await client.stop()
+        """
+        await self.http.disconnect()
+        for app in self.stop_handlers:
+            try:
+                await app(self)
+            except Exception as error:
+                logger.warning("Stop app, error=%s", error)
+
+    async def startup(self, app):
+        """
+        Start the client and configure endpoints if needed.
+
+        Parameters:
+            app:
+                Application context (typically from a web framework).
+
+        Note:
+            This method is designed to be used with web frameworks
+            like FastAPI or Quart that have startup events.
+
+        Example:
+        .. code-block:: python
+            # In FastAPI
+            @app.on_event("startup")
+            async def startup_event():
+                await client.startup(app)
+        """
+        await self.start()
+        if self.set_new_endpoint:
+            await self.setup_endpoints()
+
+    async def cleanup(self, app):
+        """
+        Stop the client during application cleanup.
+
+        Parameters:
+            app:
+                Application context (typically from a web framework).
+
+        Note:
+            This method is designed to be used with web frameworks
+            like FastAPI or Quart that have shutdown events.
+
+        Example:
+        .. code-block:: python
+            # In FastAPI
+            @app.on_event("shutdown")
+            async def shutdown_event():
+                await client.cleanup(app)
+        """
+        await self.stop()
+
+    async def __aenter__(self):
+        """
+        Enter the async context manager.
+
+        Returns:
+            Client: The started client instance.
+
+        Example:
+        .. code-block:: python
+            async with Client(token="YOUR_TOKEN") as client:
+                # Client is started here
+                await client.send_message(...)
+            # Client is automatically stopped here
+        """
+        await self.start()
+        return self
+
+    async def __aexit__(self, *args):
+        """
+        Exit the async context manager.
+
+        Parameters:
+            *args: Exception information if an exception occurred.
+
+        Note:
+            Always stops the client, even if an exception occurred.
+        """
+        await self.stop()

rubigram/enums/__init__.py

@@ -0,0 +1,52 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .buttons import (
+    ButtonCalendarType,
+    ButtonLocationType,
+    ButtonSelectionGetType,
+    ButtonSelectionSearchType,
+    ButtonSelectionType,
+    ButtonTextboxTypeLine,
+    ButtonTextboxTypeKeypad,
+    ButtonType
+)
+from .chat_action_type import ChatActionType
+from .chat_keypad_type import ChatKeypadType
+from .chat_type import ChatType
+from .file_type import FileType
+from .forwarded_from_type import ForwardedFromType
+from .live_location_status import LiveLocationStatus
+from .message_sender_type import MessageSenderType
+from .parse_mode import ParseMode
+from .payment_status_type import PaymentStatusType
+from .poll_status_type import PollStatusType
+from .update_endpoint_type import UpdateEndpointType
+from .update_type import UpdateType
+from .metadata_type import MetadataType
+
+__all__ = [
+    "ButtonCalendarType",
+    "ButtonLocationType",
+    "ButtonSelectionGetType",
+    "ButtonSelectionSearchType",
+    "ButtonSelectionType",
+    "ButtonTextboxTypeLine",
+    "ButtonTextboxTypeKeypad",
+    "ButtonType",
+    "ChatActionType",
+    "ChatKeypadType",
+    "ChatType",
+    "FileType",
+    "ForwardedFromType",
+    "LiveLocationStatus",
+    "MessageSenderType",
+    "ParseMode",
+    "PaymentStatusType",
+    "PollStatusType",
+    "UpdateEndpointType",
+    "UpdateType",
+    "MetadataType"
+]

rubigram/enums/buttons/__init__.py

@@ -0,0 +1,13 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .button_calendar_type import ButtonCalendarType
+from .button_location_type import ButtonLocationType
+from .button_selection_get_type import ButtonSelectionGetType
+from .button_selection_search_type import ButtonSelectionSearchType
+from .button_selection_type import ButtonSelectionType
+from .button_textbox_type_line import ButtonTextboxTypeLine
+from .button_textbox_type_keypad import ButtonTextboxTypeKeypad
+from .button_type import ButtonType

rubigram/enums/buttons/button_calendar_type.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonCalendarType(Enum):
+    """
+    **Represents the calendar types available for calendar buttons.**
+        `from rubigram.enums import ButtonCalendarType`
+
+    Attributes:
+        DATE_PERSIAN (str): Persian (Jalali) calendar type.
+        DATE_GREGORIAN (str): Gregorian calendar type.
+    """
+
+    DATE_PERSIAN = "DatePersian"
+    DATE_GREGORIAN = "DateGregorian"

rubigram/enums/buttons/button_location_type.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonLocationType(Enum):
+    """
+    **Represents the types of location buttons.**
+        `from rubigram.enums import ButtonLocationType`
+
+    Attributes:
+        PICKER (str): A button to pick a location.
+        VIEW (str): A button to view a location.
+    """
+
+    PICKER = "Picker"
+    VIEW = "View"

rubigram/enums/buttons/button_selection_get_type.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonSelectionGetType(Enum):
+    """
+    **Represents the methods available to retrieve selection button data.**
+        `from rubigram.enums import ButtonSelectionGetType`
+
+    Attributes:
+        LOCAL (str): Retrieve data locally.
+        API (str): Retrieve data via API.
+    """
+
+    LOCAL = "Local"
+    API = "Api"

rubigram/enums/buttons/button_selection_search_type.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonSelectionSearchType(Enum):
+    """
+    **Represents the search modes available for selection buttons.**
+        `from rubigram.enums import ButtonSelectionSearchType`
+
+    Attributes:
+        LOCAL (str): Search is performed locally.
+        API (str): Search is performed via API.
+    """
+
+    LOCAL = "Local"
+    API = "Api"

rubigram/enums/buttons/button_selection_type.py

@@ -0,0 +1,22 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonSelectionType(Enum):
+    """
+    **Represents the different styles of selection buttons.**
+        `from rubigram.enums import ButtonSelectionType`
+
+    Attributes:
+        TEXT_ONLY (str): A selection button with text only.
+        TEXT_IMG_THU (str): A selection button with text and a thumbnail image.
+        TEXT_IMG_BIG (str): A selection button with text and a large image.
+    """
+
+    TEXT_ONLY = "TextOnly"
+    TEXT_IMG_THU = "TextImgThu"
+    TEXT_IMG_BIG = "TextImgBig"

rubigram/enums/buttons/button_textbox_type_keypad.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonTextboxTypeKeypad(Enum):
+    """
+    **Represents the keypad types available for textbox buttons.**
+        `from rubigram.enums import ButtonTextboxTypeKeypad`
+
+    Attributes:
+        STRING (str): Textbox accepts string input.
+        NUMBER (str): Textbox accepts numeric input.
+    """
+
+    STRING = "String"
+    NUMBER = "Number"

rubigram/enums/buttons/button_textbox_type_line.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonTextboxTypeLine(Enum):
+    """
+    **Represents the line types available for textbox buttons.**
+        `from rubigram.enums import ButtonTextboxTypeLine`
+
+    Attributes:
+        SINGLE_LINE (str): Textbox is a single-line input.
+        MULTI_LINE (str): Textbox allows multiple lines.
+    """
+
+    SINGLE_LINE = "SingleLine"
+    MULTI_LINE = "MultiLine"

rubigram/enums/buttons/button_type.py

@@ -0,0 +1,58 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from ..enum import Enum
+
+
+class ButtonType(Enum):
+    """
+    **Represents the different types of interactive buttons available in a chat.**
+        `from rubigram.enums import ButtonType`
+
+    Attributes:
+        SIMPLE (str): A simple button.
+        SELECTION (str): A selection button.
+        CALENDAR (str): A calendar picker button.
+        NUMBER_PICKER (str): A number picker button.
+        STRING_PICKER (str): A string picker button.
+        LOCATION (str): A button to share location.
+        PAYMENT (str): A payment button.
+        CAMERA_IMAGE (str): A button to capture an image via camera.
+        CAMERA_VIDEO (str): A button to record a video via camera.
+        GALLERY_IMAGE (str): A button to select an image from gallery.
+        GALLERY_VIDEO (str): A button to select a video from gallery.
+        FILE (str): A button to send a file.
+        AUDIO (str): A button to send an audio file.
+        RECORD_AUDIO (str): A button to record audio.
+        MY_PHONE_NUMBER (str): A button to share the user's phone number.
+        MY_LOCATION (str): A button to share the user's location.
+        TEXTBOX (str): A textbox input button.
+        LINK (str): A button containing a link.
+        ASK_MY_PHONE_NUMBER (str): A button that requests the user's phone number.
+        ASK_LOCATION (str): A button that requests the user's location.
+        BARCODE (str): A button to scan a barcode.
+    """
+
+    SIMPLE = "Simple"
+    SELECTION = "Selection"
+    CALENDAR = "Calendar"
+    NUMBER_PICKER = "NumberPicker"
+    STRING_PICKER = "StringPicker"
+    LOCATION = "Location"
+    PAYMENT = "Payment"
+    CAMERA_IMAGE = "CameraImage"
+    CAMERA_VIDEO = "CameraVideo"
+    GALLERY_IMAGE = "GalleryImage"
+    GALLERY_VIDEO = "GalleryVideo"
+    FILE = "File"
+    AUDIO = "Audio"
+    RECORD_AUDIO = "RecordAudio"
+    MY_PHONE_NUMBER = "MyPhoneNumber"
+    MY_LOCATION = "MyLocation"
+    TEXTBOX = "Textbox"
+    LINK = "Link"
+    ASK_MY_PHONE_NUMBER = "AskMyPhoneNumber"
+    ASK_LOCATION = "AskLocation"
+    BARCODE = "Barcode"

rubigram/enums/chat_action_type.py

@@ -0,0 +1,22 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .enum import Enum
+
+
+class ChatActionType(Enum):
+    """
+    **Represents the types of actions a user can perform in a chat.**
+        `from rubigram.enums import ChatActionType`
+
+    Attributes:
+        TYPING (str): Indicates the user is typing a message.
+        UPLOADING (str): Indicates the user is uploading a file.
+        RECORDING (str): Indicates the user is recording a voice message.
+    """
+
+    TYPING = "Typing"
+    UPLOADING = "Uploading"
+    RECORDING = "Recording"

rubigram/enums/chat_keypad_type.py

@@ -0,0 +1,20 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .enum import Enum
+
+
+class ChatKeypadType(Enum):
+    """
+    **Represents the types of keypads that can be applied to a chat.**
+        `from rubigram.enums import ChatKeypadType`
+
+    Attributes:
+        New (str): Creates and applies a new keypad to the chat.
+        Remove (str): Removes the existing keypad from the chat.
+    """
+
+    NEW = "New"
+    REMOVE = "Remove"

rubigram/enums/chat_type.py

@@ -0,0 +1,24 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .enum import Enum
+
+
+class ChatType(Enum):
+    """
+    **Represents different types of chats.**
+        `from rubigram.enums import ChatType`
+
+    Attributes:
+        User: Standard private chat with a user.
+        Bot: Chat with an automated bot.
+        Group: Multi-user group conversation.
+        Channel: One-way broadcast chat.
+    """
+
+    USER = "User"
+    BOT = "Bot"
+    GROUP = "Group"
+    CHANNEL = "Channel"

rubigram/enums/enum.py

@@ -0,0 +1,6 @@
+import enum
+
+
+class Enum(str, enum.Enum):
+    def __str__(self):
+        return f"rubigram.enums.{self.__class__.__name__}.{self.name}"