RubigramClient 1.7.17__py3-none-any.whl

rubigram/server/__init__.py

@@ -0,0 +1,6 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .server import Server

rubigram/server/server.py

@@ -0,0 +1,245 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from aiohttp.web import Application, AppRunner, RouteTableDef, TCPSite, Request, json_response
+import asyncio
+import logging
+import rubigram
+
+
+logger = logging.getLogger(__name__)
+
+
+class Server:
+    """
+    HTTP webhook server for receiving Rubika Bot API updates.
+
+    This class implements a web server that listens for incoming updates
+    from Rubika and dispatches them to the client's handlers. It supports
+    all update types defined in the API and integrates with the client's
+    lifecycle management.
+
+    Parameters:
+        client (rubigram.Client):
+            The bot client instance that will process updates.
+        host (str, optional):
+            Host address to bind the server to. Use "0.0.0.0" to listen
+            on all interfaces. Defaults to "0.0.0.0".
+        port (int, optional):
+            Port number to listen on. Defaults to 8000.
+
+    Attributes:
+        client (rubigram.Client): The bot client instance.
+        host (str): Server host address.
+        port (int): Server port number.
+        app (Application): aiohttp web application.
+        routes (RouteTableDef): HTTP route definitions.
+        runner (Optional[AppRunner]): aiohttp application runner.
+        site (Optional[TCPSite]): TCP site for the server.
+
+    Example:
+    .. code-block:: python
+        # Create client with webhook
+        client = Client(
+            token="YOUR_BOT_TOKEN",
+            webhook="https://example.com/webhook"
+        )
+
+        # Create and start server
+        server = Server(client, host="127.0.0.1", port=8080)
+
+        # Run server (blocks until interrupted)
+        server.run_server()
+
+        # Or manage server lifecycle manually
+        await server.start()
+        # Server is now running...
+        await server.stop()
+    """
+
+    def __init__(
+        self,
+        client: "rubigram.Client",
+        host: str = "0.0.0.0",
+        port: int = 8000
+    ):
+        self.client = client
+        self.host = host
+        self.port = port
+
+        self.app = Application()
+        self.routes = RouteTableDef()
+
+        self.app.on_startup.append(self.client.startup)
+        self.app.on_cleanup.append(self.client.cleanup)
+
+        self.runner = None
+        self.site = None
+
+    async def process_update(self, data: dict):
+        """
+        Parse and dispatch an incoming update.
+
+        Parameters:
+            data (dict):
+                Raw JSON data received from Rubika API.
+
+        Note:
+            - For inline messages, creates an InlineMessage object
+            - For other updates, creates an Update object
+            - Dispatches the parsed update to client's handlers
+            - Binds the client to the parsed object
+
+        Example:
+        .. code-block:: python
+            # Manual processing (for testing)
+            await server.process_update({
+                "update": {
+                    "chat_id": "b0123456789",
+                    "new_message": {...}
+                }
+            })
+        """
+        if "inline_message" in data:
+            update = rubigram.types.InlineMessage.parse(
+                data["inline_message"], self.client
+            )
+        else:
+            update = rubigram.types.Update.parse(data["update"], self.client)
+
+        await self.client.dispatcher(update)
+
+    def receive_data(self):
+        """
+        Create a request handler for incoming webhook data.
+
+        Returns:
+            callable: An async function that handles HTTP POST requests.
+
+        Note:
+            The handler:
+            1. Parses JSON from request body
+            2. Logs the received data
+            3. Processes the update asynchronously
+            4. Returns JSON response with status
+            5. Catches and logs any processing errors
+        """
+        async def wrapper(request: Request):
+            try:
+                data = await request.json()
+                logger.debug("Receive data from webhook, data=%s", data)
+                await self.process_update(data)
+                return json_response({"status": "OK", "data": data})
+            except Exception as error:
+                logger.error(
+                    "Error receive data from webhook, error=%s", error)
+                return json_response({"status": "ERROR", "errcor": error})
+        return wrapper
+
+    def setup_routes(self):
+        """
+        Configure HTTP routes for all update types.
+
+        Creates POST endpoints for each update type defined in
+        `rubigram.enums.UpdateEndpointType`. Each endpoint uses the
+        same handler to receive and process updates.
+
+        Note:
+            Endpoint paths correspond to the enum values (e.g., "/newMessage",
+            "/updateMessage", "/inlineMessage").
+        """
+        for i in rubigram.enums.UpdateEndpointType:
+            handler = self.receive_data()
+            self.routes.post("/{}".format(i.value))(handler)
+        self.app.add_routes(self.routes)
+
+    async def start(self):
+        """
+        Start the webhook server.
+
+        This method:
+        1. Sets up all routes
+        2. Creates and configures the AppRunner
+        3. Starts the TCP site
+        4. Logs server startup information
+
+        Note:
+            Also triggers the client's startup handlers via the
+            app.on_startup callback.
+
+        Example:
+        .. code-block:: python
+            await server.start()
+            print(f"Server running on {server.host}:{server.port}")
+        """
+        self.setup_routes()
+        self.runner = AppRunner(self.app)
+        await self.runner.setup()
+        self.site = TCPSite(self.runner, self.host, self.port)
+        await self.site.start()
+
+    async def stop(self):
+        """
+        Stop the webhook server gracefully.
+
+        This method:
+        1. Cleans up the AppRunner
+        2. Logs server shutdown
+        3. Sets runner and site to None
+
+        Note:
+            Also triggers the client's cleanup handlers via the
+            app.on_cleanup callback.
+
+        Example:
+        .. code-block:: python
+            await server.stop()
+            print("Server stopped")
+        """
+        if self.runner:
+            await self.runner.cleanup()
+
+    async def run(self):
+        """
+        Run the server indefinitely until interrupted.
+
+        This method:
+        1. Starts the server
+        2. Waits on an event (blocks forever)
+        3. Handles cancellation gracefully
+        4. Ensures server is stopped on exit
+
+        Note:
+            Used internally by `run_server()`.
+        """
+        await self.start()
+        try:
+            await asyncio.Event().wait()
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.stop()
+
+    def run_server(self, set_endpoint: bool = True):
+        """
+        Run the server in the main thread (blocking call).
+
+        This method:
+        1. Creates a new asyncio event loop
+        2. Runs the server indefinitely
+        3. Handles KeyboardInterrupt for graceful shutdown
+        4. Closes the event loop on exit
+
+        Example:
+        .. code-block:: python
+            # This blocks until Ctrl+C is pressed
+            server.run_server()
+        """
+        self.client.set_new_endpoint = set_endpoint
+        try:
+            logger.info("Start server in %s", self.client.webhook)
+            asyncio.run(self.run())
+        except KeyboardInterrupt:
+            logger.info("Stop server in %s", self.client.webhook)

rubigram/state/__init__.py

@@ -0,0 +1,7 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .state import State
+from .storage import Storage

rubigram/state/state.py

@@ -0,0 +1,121 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .storage import Storage
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+class State:
+    """
+    Convenience wrapper for managing individual user conversation states.
+
+    This class provides a user-specific interface to the Storage class,
+    simplifying state management for individual users in conversation flows.
+    It automatically handles user identification and delegates operations
+    to the underlying storage system.
+
+    Parameters:
+        storage (Storage):
+            The storage instance where states are persisted.
+        user_id (str):
+            Unique identifier for the user (typically chat_id).
+
+    Attributes:
+        storage (Storage): Reference to the storage backend.
+        user_id (str): The user identifier for this state instance.
+
+    Example:
+    .. code-block:: python
+        # Get a State instance for a specific user
+        user_state = State(storage, user_id="b0123456789")
+
+        # Set the user's state with additional data
+        await user_state.set(
+            state="collecting_name",
+            attempts=2,
+            last_prompt="Please enter your full name:"
+        )
+
+        # Retrieve the user's current state
+        current_state = await user_state.get()
+
+        # Clear the user's state (e.g., after conversation completion)
+        await user_state.delete()
+    """
+
+    def __init__(
+        self,
+        storage: "Storage",
+        user_id: str
+    ):
+        self.storage = storage
+        self.user_id = user_id
+
+    async def set(self, state: str, **kwargs):
+        """
+        Set or update the conversation state for this user.
+
+        Parameters:
+            state (str):
+                The conversation state identifier (e.g., "awaiting_input",
+                "processing_data", "completed").
+            **kwargs:
+                Arbitrary key-value data to store with the state.
+
+        Returns:
+            bool: True if the state was successfully set.
+
+        Note:
+            This method overwrites any existing state for this user.
+            Use `get()` first if you need to preserve existing data.
+
+        Example:
+        .. code-block:: python
+            await user_state.set(
+                state="collecting_payment",
+                amount=10000,
+                currency="IRT",
+                invoice_id="inv_12345"
+            )
+        """
+        await self.storage.set_state(self.user_id, state, **kwargs)
+
+    async def get(self):
+        """
+        Retrieve the current conversation state and data for this user.
+
+        Returns:
+            Optional[dict]: The stored state data if found, None otherwise.
+            Structure: {"state": str, "data": dict}
+
+        Example:
+        .. code-block:: python
+            data = await user_state.get()
+            if data:
+                current_state = data["state"]  # e.g., "awaiting_confirmation"
+                user_data = data["data"]       # Additional stored data
+        """
+        return await self.storage.get_state(self.user_id)
+
+    async def delete(self):
+        """
+        Remove the conversation state for this user from storage.
+
+        Returns:
+            bool: True if the state was deleted, False if it didn't exist.
+
+        Example:
+        .. code-block:: python
+            # Reset user's conversation
+            await user_state.delete()
+
+            # Or after completing a workflow
+            if workflow_completed:
+                await user_state.delete()
+        """
+        await self.storage.delete_state(self.user_id)

rubigram/state/storage.py

@@ -0,0 +1,131 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from aiocache import Cache
+from aiocache.serializers import JsonSerializer
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+class Storage:
+    """
+    Asynchronous storage for managing user conversation states.
+
+    This class provides a simple key-value storage using aiocache to persist
+    user conversation states and associated data. States are stored with
+    configurable TTL (time-to-live) and automatically serialized to JSON.
+
+    Parameters:
+        ttl (int, optional):
+            Time-to-live for stored states in seconds. After this time,
+            states are automatically evicted from cache. Defaults to 3600
+            (1 hour).
+
+    Attributes:
+        cache (Cache):
+            The underlying aiocache instance configured for memory storage
+            with JSON serialization.
+
+    Example:
+    .. code-block:: python
+        # Create storage with custom TTL
+        storage = Storage(ttl=7200)  # 2 hours TTL
+
+        # Set user state with additional data
+        await storage.set_state(
+            user_id="b0123456789",
+            state="waiting_for_name",
+            name="John",
+            age=25
+        )
+
+        # Get user state
+        state_data = await storage.get_state("b0123456789")
+        # Returns: {"state": "waiting_for_name", "data": {"name": "John", "age": 25}}
+
+        # Delete user state
+        await storage.delete_state("b0123456789")
+    """
+
+    def __init__(self, ttl: int = 3600):
+        self.cache = Cache(
+            Cache.MEMORY,
+            serializer=JsonSerializer(),
+            ttl=ttl
+        )
+
+    async def set_state(self, user_id: str, state: str, **kwargs):
+        """
+        Set or update a user's conversation state with optional data.
+
+        Parameters:
+            user_id (str):
+                Unique identifier for the user (typically chat_id).
+            state (str):
+                The conversation state identifier (e.g., "waiting_for_name",
+                "collecting_data").
+            **kwargs:
+                Arbitrary key-value pairs to store alongside the state.
+
+        Returns:
+            bool: True if the state was successfully set.
+
+        Note:
+            The state is stored with the key format: "state:{user_id}"
+            Example: "state:b0123456789"
+
+        Example:
+        .. code-block:: python
+            await storage.set_state(
+                user_id="b0123456789",
+                state="collecting_preferences",
+                language="fa",
+                theme="dark",
+                step=3
+            )
+        """
+        payload = {"state": state, "data": kwargs}
+        return await self.cache.set("state:{}".format(user_id), payload)
+
+    async def get_state(self, user_id: str):
+        """
+        Retrieve a user's conversation state and associated data.
+
+        Parameters:
+            user_id (str):
+                Unique identifier for the user.
+
+        Returns:
+            Optional[dict]: The stored state data if found, None otherwise.
+            Structure: {"state": str, "data": dict}
+
+        Example:
+        .. code-block:: python
+            data = await storage.get_state("b0123456789")
+            if data:
+                current_state = data["state"]  # e.g., "waiting_for_name"
+                user_data = data["data"]       # e.g., {"name": "John"}
+        """
+        await self.cache.get("state:{}".format(user_id))
+
+    async def delete_state(self, user_id: str):
+        """
+        Delete a user's conversation state from storage.
+
+        Parameters:
+            user_id (str):
+                Unique identifier for the user.
+
+        Returns:
+            bool: True if the state was deleted, False if it didn't exist.
+
+        Example:
+        .. code-block:: python
+            # Clear user's conversation state
+            await storage.delete_state("b0123456789")
+        """
+        await self.cache.delete("state:{}".format(user_id))

rubigram/types/__init__.py

@@ -0,0 +1,66 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from .bot import Bot
+from .chat import Chat
+from .file import File
+from .bot_command import BotCommand
+from .keypads import Keypad, KeypadRow
+from .messages import Message, UMessage, InlineMessage
+from .contact_message import ContactMessage
+from .forwarded_from import ForwardedFrom
+from .live_location import LiveLocation
+from .location import Location
+from .payment_status import PaymentStatus
+from .poll_status import PollStatus
+from .poll import Poll
+from .sticker import Sticker
+from .aux_data import AuxData
+from .updates import Updates, Update
+from .metadata import Metadata, MetadataParts
+from .buttons import (
+    Button,
+    ButtonTextbox,
+    ButtonStringPicker,
+    ButtonSelection,
+    ButtonSelectionItem,
+    ButtonNumberPicker,
+    ButtonLocation,
+    ButtonCalendar
+)
+
+
+__all__ = [
+    "Bot",
+    "Chat",
+    "File",
+    "BotCommand",
+    "Button",
+    "ButtonCalendar",
+    "ButtonLocation",
+    "ButtonNumberPicker",
+    "ButtonSelection",
+    "ButtonSelectionItem",
+    "ButtonTextbox",
+    "ButtonStringPicker",
+    "KeypadRow",
+    "Keypad",
+    "Message",
+    "UMessage",
+    "InlineMessage",
+    "Sticker",
+    "Poll",
+    "PollStatus",
+    "PaymentStatus",
+    "Location",
+    "LiveLocation",
+    "ForwardedFrom",
+    "ContactMessage",
+    "AuxData",
+    "Updates",
+    "Update",
+    "Metadata",
+    "MetadataParts"
+]

rubigram/types/aux_data.py

@@ -0,0 +1,28 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from typing import Optional
+from dataclasses import dataclass
+from .config import Object
+
+
+@dataclass
+class AuxData(Object):
+    """
+    **Represents auxiliary data attached to a message.**
+        `from rubigram.types import AuxData`
+
+    AuxData is typically used to store metadata related to
+    buttons, interactions, or other inline components in a chat.
+
+    Attributes:
+        start_id (`Optional[str]`):
+            An identifier for the start action, if applicable.
+
+        button_id (`Optional[str]`):
+            The ID of a button that triggered this auxiliary data, if applicable.
+    """
+    start_id: Optional[str] = None
+    button_id: Optional[str] = None

rubigram/types/bot.py

@@ -0,0 +1,51 @@
+#  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
+from dataclasses import dataclass
+from .config import Object
+import rubigram
+
+
+@dataclass
+class Bot(Object):
+    """
+    **Represents a bot in Rubigram.**
+        `from rubigram.types import Bot`
+
+    Contains basic information about a bot, including its identifiers,
+    description, avatar, and sharing information.
+
+    Attributes:
+        bot_id (`str`):
+            Unique identifier for the bot.
+
+        bot_title (`str`):
+            Display title of the bot.
+
+        avatar (`Optional[rubigram.types.File]`):
+            The bot's avatar file object.
+
+        description (`Optional[str]`):
+            Description of the bot.
+
+        username (`str`):
+            The bot's username.
+
+        start_message (`Optional[str]`):
+            Default start message of the bot.
+
+        share_url (`str`):
+            Public URL for sharing the bot.
+    """
+    bot_id: str = None
+    bot_title: Optional[str] = None
+    avatar: Optional[rubigram.types.File] = None
+    description: Optional[str] = None
+    username: str = None
+    start_message: Optional[str] = None
+    share_url: str = None

rubigram/types/bot_command.py

@@ -0,0 +1,26 @@
+#  RubigramClient - Rubika API library for python
+#  Copyright (C) 2025-present Javad <https://github.com/DevJavad>
+#  Github - https://github.com/DevJavad/rubigram
+
+
+from dataclasses import dataclass
+from .config import Object
+
+
+@dataclass
+class BotCommand(Object):
+    """
+    **Represents a command for a bot in Rubigram.**
+        `from rubigram.types import Bot`
+
+    Contains the command text and its description. Typically used
+    to show available commands in the bot interface.
+
+    Attributes:
+        command (`str`):
+            The command text (e.g., '/start').
+        description (`str`):
+            Description of what the command does.
+    """
+    command: str
+    description: str

rubigram/types/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 import ButtonCalendar
+from .button_location import ButtonLocation
+from .button_number_picker import ButtonNumberPicker
+from .button_selection_item import ButtonSelectionItem
+from .button_selection import ButtonSelection
+from .button_string_picker import ButtonStringPicker
+from .button_text_box import ButtonTextbox
+from .button import Button