spluspy 2.2.10__tar.gz → 2.2.11__tar.gz

{spluspy-2.2.10/spluspy.egg-info → spluspy-2.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spluspy
-Version: 2.2.10
+Version: 2.2.11
 Summary: High-performance Python Self-Bot Framework for Soroush Plus
 Author: Ali Mirshekari
 License: MIT
@@ -26,18 +26,18 @@ Requires-Dist: rsa
 Requires-Dist: pyaes
 Dynamic: license-file
 
-# SplusPy v2.2.10
+# SplusPy v2.2.11
 
 
-**A fast, minimal, and fully-featured self-bot framework**
+**A fast, minimal, and fully-featured framework for Soroush Plus — self-bots and official bots**
 
 ---
 
 ## About
 
-SplusPy is a Python library designed specifically for building **Soroush Plus self-bots** (userbots). It provides a clean, intuitive API for automating your personal Soroush Plus account with ease.
+SplusPy is a Python library designed specifically for building **Soroush Plus self-bots** (userbots) and **official bots**. It provides a clean, intuitive API for automating your personal Soroush Plus account or building bots via the official HTTP Bot API.
 
-> ⚠️ **Note:** This is a **self-bot framework** — it operates on your personal account, not a bot account. Please adhere to Soroush's Terms of Service.
+> ⚠️ **Note:** This framework supports both **self-bot** (personal account) and **official bot** (Bot API) modes. Please adhere to Soroush's Terms of Service.
 
 ---
 
@@ -83,6 +83,30 @@ client.run_until_disconnected()
 
 ---
 
+## Official Bot (Robot)
+
+You can also build official bots using the HTTP Bot API:
+
+```python
+from spluspy import Robot, filters
+
+bot = Robot("YOUR_BOT_TOKEN")
+
+@bot.on_message(filters.text("hello"))
+async def hello_handler(client, event):
+    await event.reply("Hi there!")
+
+bot.run()
+```
+
+### How it works
+
+1. **Create a `Robot`** — pass your bot token.
+2. **Register handlers** — use `@bot.on_message()` just like the self-bot.
+3. **Run** — call `bot.run()` to start long-polling.
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

{spluspy-2.2.10 → spluspy-2.2.11}/README.md

@@ -1,15 +1,15 @@
-# SplusPy v2.2.10
+# SplusPy v2.2.11
 
 
-**A fast, minimal, and fully-featured self-bot framework**
+**A fast, minimal, and fully-featured framework for Soroush Plus — self-bots and official bots**
 
 ---
 
 ## About
 
-SplusPy is a Python library designed specifically for building **Soroush Plus self-bots** (userbots). It provides a clean, intuitive API for automating your personal Soroush Plus account with ease.
+SplusPy is a Python library designed specifically for building **Soroush Plus self-bots** (userbots) and **official bots**. It provides a clean, intuitive API for automating your personal Soroush Plus account or building bots via the official HTTP Bot API.
 
-> ⚠️ **Note:** This is a **self-bot framework** — it operates on your personal account, not a bot account. Please adhere to Soroush's Terms of Service.
+> ⚠️ **Note:** This framework supports both **self-bot** (personal account) and **official bot** (Bot API) modes. Please adhere to Soroush's Terms of Service.
 
 ---
 
@@ -55,6 +55,30 @@ client.run_until_disconnected()
 
 ---
 
+## Official Bot (Robot)
+
+You can also build official bots using the HTTP Bot API:
+
+```python
+from spluspy import Robot, filters
+
+bot = Robot("YOUR_BOT_TOKEN")
+
+@bot.on_message(filters.text("hello"))
+async def hello_handler(client, event):
+    await event.reply("Hi there!")
+
+bot.run()
+```
+
+### How it works
+
+1. **Create a `Robot`** — pass your bot token.
+2. **Register handlers** — use `@bot.on_message()` just like the self-bot.
+3. **Run** — call `bot.run()` to start long-polling.
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

{spluspy-2.2.10 → spluspy-2.2.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spluspy"
-version = "2.2.10"
+version = "2.2.11"
 description = "High-performance Python Self-Bot Framework for Soroush Plus"
 readme = "README.md"
 license = {text = "MIT"}

spluspy-2.2.11/spluspy/__init__.py

@@ -0,0 +1,20 @@
+from .client.soroushclient import SoroushClient as Client
+from .http_api import Robot
+from .http_api.types import Message, CallbackQuery
+from .http_api.keyboards import InlineKeyboardBuilder, ReplyKeyboardBuilder
+from .http_api.callbackquery import HTTPCallbackQuery
+from .network import connection
+from .tl.custom import Button
+from .tl import patched as _  # import for its side-effects
+from . import version, events, utils, errors, functions, custom
+from .filters import filters
+from .enums import MessageMediaType
+
+__version__ = version.__version__
+
+__all__ = [
+    'Client', 'Robot', 'Message', 'CallbackQuery', 'Button', 'filters',
+    'MessageMediaType', 'InlineKeyboardBuilder', 'ReplyKeyboardBuilder',
+    'HTTPCallbackQuery', 'functions', 'custom', 'errors',
+    'events', 'utils', 'connection',
+]

spluspy-2.2.11/spluspy/client/__init__.py

@@ -0,0 +1,12 @@
+"""
+This package defines clients as subclasses of others, and then a single
+`spluspy.client.soroushclient.SoroushClient` which is subclass of them
+all to provide the final unified interface while the methods can live in
+different subclasses to be more maintainable.
+
+The ABC is `spluspy.client.telegrambaseclient.SoroushPlusBaseClient` and
+methods are provided via `spluspy.methods.Methods` which aggregates all
+the individual method mixins.
+"""
+from .telegrambaseclient import SoroushPlusBaseClient
+from .soroushclient import SoroushClient

spluspy-2.2.11/spluspy/client/soroushclient.py

@@ -0,0 +1,51 @@
+import asyncio
+import typing
+from typing import Optional
+
+from ..methods import Methods
+from .telegrambaseclient import SoroushPlusBaseClient
+
+if typing.TYPE_CHECKING:
+    from ..http_api.robot import Robot
+
+
+class SoroushClient(Methods, SoroushPlusBaseClient):
+    def __init__(
+        self,
+        *args,
+        http_token: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self._http_robot: Optional["Robot"] = (
+            _create_robot(http_token) if http_token else None
+        )
+        self._http_polling_task: Optional[asyncio.Task] = None
+
+    @property
+    def http_robot(self) -> Optional["Robot"]:
+        """Direct access to the HTTP Robot instance (if ``http_token`` was provided)."""
+        return self._http_robot
+
+    async def connect(self):
+        await super().connect()
+        if self._http_robot is not None:
+            self._http_robot.loop = self.loop
+            self._http_polling_task = asyncio.create_task(
+                self._http_robot._polling_loop()
+            )
+
+    async def _disconnect_coro(self):
+        if self._http_robot is not None and self._http_polling_task is not None:
+            self._http_polling_task.cancel()
+            try:
+                await self._http_polling_task
+            except asyncio.CancelledError:
+                pass
+            await self._http_robot.close()
+        await super()._disconnect_coro()
+
+
+def _create_robot(token: str) -> "Robot":
+    from ..http_api.robot import Robot
+    return Robot(token)

{spluspy-2.2.10 → spluspy-2.2.11}/spluspy/events/__init__.py

@@ -1,3 +1,5 @@
+import typing
+
 from .raw import Raw
 from .album import Album
 from .chataction import ChatAction
@@ -7,6 +9,8 @@ from .messageread import MessageRead
 from .newmessage import NewMessage
 from .userupdate import UserUpdate
 
+if typing.TYPE_CHECKING:
+    from .common import EventBuilder, EventCommon
 
 _HANDLERS_ATTRIBUTE = '__tl.handlers'
 
@@ -38,7 +42,9 @@ class StopPropagation(Exception):
     pass
 
 
-def register(event=None):
+def register(
+    event: 'typing.Optional[typing.Union[EventBuilder, typing.Type[EventBuilder]]]' = None
+) -> 'typing.Callable':
     """
     Decorator method to *register* event handlers. This is the client-less
     `add_event_handler()
@@ -73,7 +79,7 @@ def register(event=None):
     elif not event:
         event = Raw()
 
-    def decorator(callback):
+    def decorator(callback: 'typing.Callable') -> 'typing.Callable':
         handlers = getattr(callback, _HANDLERS_ATTRIBUTE, [])
         handlers.append(event)
         setattr(callback, _HANDLERS_ATTRIBUTE, handlers)
@@ -82,7 +88,10 @@ def register(event=None):
     return decorator
 
 
-def unregister(callback, event=None):
+def unregister(
+    callback: 'typing.Callable',
+    event: 'typing.Optional[typing.Union[EventBuilder, typing.Type[EventBuilder]]]' = None
+) -> int:
     """
     Inverse operation of `register` (though not a decorator). Client-less
     `remove_event_handler
@@ -115,7 +124,7 @@ def unregister(callback, event=None):
     return found
 
 
-def is_handler(callback):
+def is_handler(callback: 'typing.Callable') -> bool:
     """
     Returns `True` if the given callback is an
     event handler (i.e. you used `register` on it).
@@ -123,7 +132,7 @@ def is_handler(callback):
     return hasattr(callback, _HANDLERS_ATTRIBUTE)
 
 
-def list(callback):
+def list(callback: 'typing.Callable') -> typing.List['EventBuilder']:
     """
     Returns a list containing the registered event
     builders inside the specified callback handler.
@@ -131,7 +140,7 @@ def list(callback):
     return getattr(callback, _HANDLERS_ATTRIBUTE, [])[:]
 
 
-def _get_handlers(callback):
+def _get_handlers(callback: 'typing.Callable') -> 'typing.Optional[typing.List[EventBuilder]]':
     """
     Like ``list`` but returns `None` if the callback was never registered.
     """

{spluspy-2.2.10 → spluspy-2.2.11}/spluspy/events/common.py

@@ -4,12 +4,14 @@ import inspect
 import typing
 import warnings
 
-from .. import utils
+from .. import utils, hints
 from ..tl import TLObject, types
 from ..tl.custom.chatgetter import ChatGetter
 
 if typing.TYPE_CHECKING:
+    from ..client.soroushclient import SoroushClient
     from ..filters import Filter
+    from ..hints import EventHandler, FilterFunc
 
 
 class _CallableWrapperFilter:
@@ -19,14 +21,14 @@ class _CallableWrapperFilter:
     where the callable receives only the event/message. Callables that
     declare two positional parameters receive ``(client, message)``.
     """
-    def __init__(self, func):
+    def __init__(self, func: 'typing.Callable[..., typing.Union[bool, typing.Awaitable[bool]]]'):
         self.func = func
         try:
             self._takes_client = len(inspect.signature(func).parameters.values()) >= 2
         except (TypeError, ValueError):
             self._takes_client = False
 
-    async def __call__(self, client, message) -> bool:
+    async def __call__(self, client: 'SoroushClient', message: 'typing.Any') -> bool:
         result = (
             self.func(client, message) if self._takes_client
             else self.func(message)
@@ -36,7 +38,7 @@ class _CallableWrapperFilter:
         return bool(result)
 
 
-def _wrap_filter(filters):
+def _wrap_filter(filters: 'typing.Optional[typing.Union[Filter, typing.Callable]]') -> 'typing.Optional[typing.Union[Filter, _CallableWrapperFilter]]':
     """Wraps plain callables into an awaitable filter, passes others through."""
     from ..filters import Filter
     if filters is None or isinstance(filters, Filter):
@@ -48,7 +50,10 @@ def _wrap_filter(filters):
         'got {}'.format(type(filters).__name__))
 
 
-async def _into_id_set(client, chats):
+async def _into_id_set(
+    client: 'SoroushClient',
+    chats: 'typing.Optional[typing.Union[hints.EntityLike, typing.Sequence[hints.EntityLike]]]'
+) -> 'typing.Optional[typing.Set[int]]':
     """Helper util to turn the input chat or chats into a set of IDs."""
     if chats is None:
         return None
@@ -112,7 +117,14 @@ class EventBuilder(abc.ABC):
                 async def handler(event):
                     pass  # code here
     """
-    def __init__(self, chats=None, *, blacklist_chats=False, func=None, filters=None):
+    def __init__(
+        self,
+        chats: 'typing.Optional[hints.EntityLike]' = None,
+        *,
+        blacklist_chats: bool = False,
+        func: 'typing.Optional[hints.FilterFunc]' = None,
+        filters: 'typing.Optional[typing.Union[Filter, typing.Callable]]' = None
+    ):
         self.chats = chats
         self.blacklist_chats = bool(blacklist_chats)
         self.resolved = False
@@ -122,7 +134,12 @@ class EventBuilder(abc.ABC):
 
     @classmethod
     @abc.abstractmethod
-    def build(cls, update, others=None, self_id=None):
+    def build(
+        cls,
+        update: 'typing.Any',
+        others: 'typing.Optional[typing.List]' = None,
+        self_id: 'typing.Optional[int]' = None
+    ) -> 'typing.Optional[EventCommon]':
         """
         Builds an event for the given update if possible, or returns None.
 
@@ -134,7 +151,7 @@ class EventBuilder(abc.ABC):
         """
         # TODO So many parameters specific to only some update types seems dirty
 
-    async def resolve(self, client):
+    async def resolve(self, client: 'SoroushClient') -> None:
         """Helper method to allow event builders to be resolved before usage"""
         if self.resolved:
             return
@@ -147,10 +164,10 @@ class EventBuilder(abc.ABC):
                 await self._resolve(client)
                 self.resolved = True
 
-    async def _resolve(self, client):
+    async def _resolve(self, client: 'SoroushClient') -> None:
         self.chats = await _into_id_set(client, self.chats)
 
-    async def filter(self, event):
+    async def filter(self, event: 'EventCommon') -> 'typing.Optional[EventCommon]':
         """
         Returns a truthy value if the event passed the filter and should be
         used, or falsy otherwise. The return value may need to be awaited.
@@ -195,14 +212,19 @@ class EventCommon(ChatGetter, abc.ABC):
     """
     _event_name = 'Event'
 
-    def __init__(self, chat_peer=None, msg_id=None, broadcast=None):
+    def __init__(
+        self,
+        chat_peer: 'typing.Optional[types.TypePeer]' = None,
+        msg_id: 'typing.Optional[int]' = None,
+        broadcast: 'typing.Optional[bool]' = None
+    ):
         super().__init__(chat_peer, broadcast=broadcast)
-        self._entities = {}
-        self._client = None
+        self._entities: 'typing.Dict[int, typing.Any]' = {}
+        self._client: 'typing.Optional[SoroushClient]' = None
         self._message_id = msg_id
-        self.original_update = None
+        self.original_update: 'typing.Optional[types.TypeUpdate]' = None
 
-    def _set_client(self, client):
+    def _set_client(self, client: 'SoroushClient') -> None:
         """
         Setter so subclasses can act accordingly when the client is set.
         """
@@ -214,7 +236,7 @@ class EventCommon(ChatGetter, abc.ABC):
             self._chat = self._input_chat = None
 
     @property
-    def client(self):
+    def client(self) -> 'SoroushClient':
         """
         The `spluspy.SoroushClient` that created this event.
         """