PySPlusthon 0.5.0__tar.gz

pysplusthon-0.5.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Mohammad Saleh Peyravi
+
+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.

pysplusthon-0.5.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: PySPlusthon
+Version: 0.5.0
+Summary: a Python library for Soroush Plus Bot API
+Author-email: Mohammad Saleh Peyravi <akhbari87@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Msp-92/PySPlusthon
+Project-URL: SPlus News Channel, https://splus.ir/PySPlusthon
+Project-URL: PySPlusthon Developers Group, https://splus.ir/PySPlusthonDevelopers
+Keywords: splus,messenger,bot,api,client
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx==0.28.1
+Requires-Dist: grpcio-tools==1.80.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/PySPlusthon.png" alt="PySPlusthon" width="200">
+</p>
+
+# PySPlusthon
+A Python library for interacting with the Soroush Plus Bot API (Splus).
+
+## Quick Start
+```python
+
+from PySPlusthon import Client
+
+bot = Client("YOUR_BOT_TOKEN")
+
+@bot.on_message()
+async def on_message(message):
+    print(f"Received: {message.text}")
+
+if __name__ == "__main__":
+    bot.run()
+```
+
+## Key Features
+
+- **Full Bot API Support**: Send messages, photos, videos, documents, audio, voice, stickers, locations, contacts, and more
+- **Update Handling**: Polling and webhook support with `start_polling()` and `set_webhook()`
+- **Conditional Handlers**: Message filters using conditions (`text`, `command`, `document`, `photo`, `video`, `voice`, and more)
+- **Event Handlers**: Connect, disconnect, initialize, shutdown, edited messages, callback queries, errors, and custom events
+- **Object Model**: Comprehensive `Object` base class with `wrap()`/`unwrap()` for API response parsing
+- **Inline Keyboards & Keyboards**: `InlineKeyboard` and `ReplyKeyboard` with button formatting
+- **Media Groups**: Send photo/video/audio groups
+- **Referral Links**: Create referral links with `create_referral_link()`
+- **User/Chat Methods**: `get_me()`, `get_chat()`, `get_chat_member()`, `get_chat_members_count()`, and more
+- **Inline Inline Buttons & Keyboards**: Full reply markup support
+- **Protobuf & Userbot Support**: Optional userbot mode with WebSocket integration
+- **Error Handling**: Custom RPC error types (`BadRequestError`, `FloodError`, `ForbiddenError`, `NotFoundError`, `UnauthorizedError`, `InternalError`, `TooManyRequestsError`)
+
+## Installing
+
+```bash
+pip install PySPlusthon
+```
+
+## Links
+- [**PyPI**](https://pypi.org/project/PySPlusthon/)
+- [**GitHub**](https://github.com/Msp-92/PySPlusthon)
+- [**Splus News Channel**](https://splus.ir/PySPlusthon)
+- [**PySPlusthon Developers Group**](https://splus.ir/PySPlusthonDevelopers)

pysplusthon-0.5.0/PySPlusthon/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "1.0.0"
+
+from .client import Client

pysplusthon-0.5.0/PySPlusthon/client/__init__.py

@@ -0,0 +1 @@
+from .client import Client

pysplusthon-0.5.0/PySPlusthon/client/attachments/__init__.py

@@ -0,0 +1,29 @@
+from .send_photo import SendPhoto
+from .send_animation import SendAnimation
+from .send_audio import SendAudio
+from .send_document import SendDocument
+from .send_sticker import SendSticker
+from .send_video import SendVideo
+from .send_voice import SendVoice
+from .send_location import SendLocation
+from .send_contact import SendContact
+from .send_media_group import SendMediaGroup
+from .get_file import GetFile
+from .upload_file import UploadFile
+
+
+class Attachments(
+    SendPhoto,
+    SendAnimation,
+    SendAudio,
+    SendDocument,
+    SendVideo,
+    SendVoice,
+    SendSticker,
+    SendLocation,
+    SendContact,
+    SendMediaGroup,
+    GetFile,
+    UploadFile
+):
+    pass

pysplusthon-0.5.0/PySPlusthon/client/attachments/get_file.py

@@ -0,0 +1,22 @@
+import PySPlusthon
+from ...objects import File
+
+
+class GetFile:
+
+    async def get_file(
+            self: "PySPlusthon.Client",
+            file_id: str
+    ) -> File:
+        if self.is_userbot():
+            from ...proto import requests, structs
+            access_hash, file_id, file_storage_version = map(int, file_id.split(":"))
+            return await self.execute(requests.GetNasimFileUrl(
+                file=structs.FileLocation(
+                    file_id=file_id,
+                    access_hash=access_hash,
+                    file_storage_version=structs.Int32Value(value=file_storage_version)
+                )
+            ))
+
+        return await self.auto_execute("getFile", locals())

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_animation.py

@@ -0,0 +1,71 @@
+from typing import Union, BinaryIO, Optional
+import os
+
+import PySPlusthon
+from ...objects import InputMedia, resolve_media, Message, ReplyMarkup
+
+
+def _extract_filename_media(media) -> Optional[str]:
+    if isinstance(media, InputMedia):
+        return getattr(media.media, 'name', None) if hasattr(media.media, 'name') else None
+    if isinstance(media, str):
+        return os.path.basename(media)
+    return None
+
+
+class SendAnimation:
+
+    async def send_animation(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            animation: Union[str, bytes, BinaryIO, InputMedia],
+            duration: int = None,
+            width: int = None,
+            height: int = None,
+            caption: str = None,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        animation = resolve_media(animation)
+        filename = _extract_filename_media(animation)
+
+        if self.is_userbot():
+            from ...proto import requests, structs, enums
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            file = await self.upload_file(chat_id, animation, enums.SEND_TYPE_GIF)
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    document_message=structs.DocumentMessage(
+                        file_id=file.id,
+                        access_hash=peer_id,
+                        file_size=file.size,
+                        name=file.name,
+                        mime_type=file.mime_type,
+                        ext=structs.DocumentEx(
+                            document_ex_gif=structs.DocumentExGif(
+                                w=100,
+                                h=100,
+                                duration=10
+                            )
+                        ),
+                        caption=structs.TextMessage(text=caption)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        params = {"chat_id": chat_id, "animation": animation, "duration": duration, "width": width, "height": height}
+        if caption is not None:
+            params["caption"] = caption
+        if filename is not None:
+            params["filename"] = filename
+        return await self.auto_execute("sendAnimation", params, json=False)

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_audio.py

@@ -0,0 +1,54 @@
+from typing import Union, BinaryIO
+
+import PySPlusthon
+from ...objects import InputMedia, resolve_media, Message, ReplyMarkup
+
+
+class SendAudio:
+
+    async def send_audio(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            audio: Union[str, bytes, BinaryIO, InputMedia],
+            caption: str = None,
+            duration: int = None,
+            title: str = None,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        audio = resolve_media(audio)
+
+        if self.is_userbot():
+            from ...proto import requests, structs, enums
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            file = await self.upload_file(chat_id, audio, enums.SEND_TYPE_AUDIO)
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    document_message=structs.DocumentMessage(
+                        file_id=file.id,
+                        access_hash=peer_id,
+                        file_size=file.size,
+                        name=file.name,
+                        mime_type=file.mime_type,
+                        ext=structs.DocumentEx(
+                            document_ex_audio=structs.DocumentExAudio(
+                                duration=duration,
+                                track=title or file.name
+                            )
+                        ),
+                        caption=structs.TextMessage(text=caption)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        return await self.auto_execute("sendAudio", locals())

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_contact.py

@@ -0,0 +1,47 @@
+from typing import Union
+from json import dumps
+
+import PySPlusthon
+from ...objects import Message, ReplyMarkup
+
+
+class SendContact:
+
+    async def send_contact(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            phone_number: str,
+            first_name: str,
+            last_name: str = None,
+            vcard : bytes = None,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        if self.is_userbot():
+            from PySPlusthon.proto import requests, structs
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            raw_json = {
+                "dataType": "contact",
+                "data": {
+                    "contact": {"name": first_name, "emails": [""], "phones": [phone_number]},
+                }
+            }
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    json_message=structs.JsonMessage(
+                        raw_json=dumps(raw_json)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        return await self.auto_execute("sendContact", locals())

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_document.py

@@ -0,0 +1,63 @@
+from typing import Union, BinaryIO, Optional
+import os
+
+import PySPlusthon
+from ...objects import InputMedia, resolve_media, Message, ReplyMarkup
+
+
+def _extract_filename(document) -> Optional[str]:
+    if isinstance(document, InputMedia):
+        return getattr(document.media, 'name', None) if hasattr(document.media, 'name') else None
+    if isinstance(document, str):
+        return os.path.basename(document)
+    if document is not None:
+        return getattr(document, 'name', None)
+    return None
+
+
+class SendDocument:
+
+    async def send_document(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            document: Union[str, bytes, BinaryIO, InputMedia],
+            caption: str = None,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        document = resolve_media(document)
+        filename = _extract_filename(document)
+
+        if self.is_userbot():
+            from ...proto import requests, structs, enums
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            file = await self.upload_file(chat_id, document, enums.SEND_TYPE_DOCUMENT)
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    document_message=structs.DocumentMessage(
+                        file_id=file.id,
+                        access_hash=peer_id,
+                        file_size=file.size,
+                        name=file.name,
+                        mime_type=file.mime_type,
+                        caption=structs.TextMessage(text=caption)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        params = {"chat_id": chat_id, "document": document}
+        if caption is not None:
+            params["caption"] = caption
+        if filename is not None:
+            params["filename"] = filename
+        return await self.auto_execute("sendDocument", params)

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_location.py

@@ -0,0 +1,45 @@
+from typing import Union
+from json import dumps
+
+import PySPlusthon
+from ...objects import Message, ReplyMarkup
+
+
+class SendLocation:
+
+    async def send_location(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            latitude: float,
+            longitude: float,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        if self.is_userbot():
+            from PySPlusthon.proto import requests, structs
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            raw_json = {
+                "dataType": "location",
+                "data": {
+                    "location": {"latitude": latitude, "longitude": longitude}
+                }
+            }
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    json_message=structs.JsonMessage(
+                        raw_json=dumps(raw_json)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        return await self.auto_execute("sendLocation", locals())

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_media_group.py

@@ -0,0 +1,88 @@
+from typing import Union
+from json import dumps
+from typing import List
+
+import PySPlusthon
+from ...objects import Message, ReplyMarkup, InputMediaPhoto, InputMediaVideo
+from PySPlusthon import objects
+
+
+class SendMediaGroup:
+
+    async def send_media_group(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            media: List["objects.InputMedia"],
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> List[Message]:
+        if self.is_userbot():
+            from ...proto import requests, structs, enums
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            files = []
+            for content in media:
+                if isinstance(content, InputMediaPhoto):
+                    send_type = enums.SEND_TYPE_PHOTO
+                elif isinstance(content, InputMediaVideo):
+                    send_type = enums.SEND_TYPE_VIDEO
+                else:
+                    send_type = enums.SEND_TYPE_DOCUMENT
+                file = await self.upload_file(f"{peer_id}|{peer_type}", content.media, send_type)
+
+                if send_type == enums.SEND_TYPE_PHOTO:
+                    ext = structs.DocumentEx(
+                        document_ex_photo=structs.DocumentExPhoto(
+                            w=500,
+                            h=500
+                        )
+                    )
+                else:
+                    ext = structs.DocumentEx(
+                        document_ex_video=structs.DocumentExVideo(
+                            w=500,
+                            h=500,
+                            duration=10
+                        )
+                    )
+
+                single_media = structs.SingleMedia(
+                    random_id=self.ws_connection.create_rid(),
+                    media=structs.DocumentMessage(
+                        file_id=file.id,
+                        access_hash=peer_id,
+                        file_size=file.size,
+                        name=file.name,
+                        mime_type=file.mime_type,
+                        ext=ext,
+                        caption=structs.TextMessage(text=content.caption)
+                    )
+                )
+                files.append(single_media)
+
+            return await self.execute(requests.SendMultiMediaMessage(
+                peer=structs.ExPeer(
+                    type=peer_type,
+                    id=peer_id,
+                ),
+                multi_media=files,
+                grouped_id=self.ws_connection.create_rid(),
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        data = locals()
+        del data["self"]
+        if any(not m.is_json_serializable for m in data["media"]):
+            for i, m in enumerate(data["media"]):
+                data["media"][i] = m.unwrap()
+                if not m.is_json_serializable:
+                    data[f"media{i}"] = m.media
+                    data["media"][i]["media"] = f"media{i}"
+            data["media"] = dumps(data["media"])
+        else:
+            for i, m in enumerate(data["media"]):
+                data["media"][i] = m.unwrap()
+        result = await self.execute("sendMediaGroup", **data)
+        result = [Message.wrap(message) for message in result]
+        for message in result:
+            message.bind(self)
+        return result

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_photo.py

@@ -0,0 +1,67 @@
+from typing import Union, BinaryIO, Optional
+import os
+
+import PySPlusthon
+from ...objects import InputMedia, resolve_media, Message, ReplyMarkup
+
+
+def _extract_filename_media(media) -> Optional[str]:
+    if isinstance(media, InputMedia):
+        return getattr(media.media, 'name', None) if hasattr(media.media, 'name') else None
+    if isinstance(media, str):
+        return os.path.basename(media)
+    return None
+
+
+class SendPhoto:
+
+    async def send_photo(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            photo: Union[str, bytes, BinaryIO, InputMedia],
+            caption: str = None,
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        photo = resolve_media(photo)
+        filename = _extract_filename_media(photo)
+
+        if self.is_userbot():
+            from ...proto import requests, structs, enums
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            file = await self.upload_file(chat_id, photo, enums.SEND_TYPE_PHOTO)
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    document_message=structs.DocumentMessage(
+                        file_id=file.id,
+                        access_hash=peer_id,
+                        file_size=file.size,
+                        name=file.name,
+                        mime_type=file.mime_type,
+                        ext=structs.DocumentEx(
+                            document_ex_photo=structs.DocumentExPhoto(
+                                w=100,
+                                h=100
+                            )
+                        ),
+                        caption=structs.TextMessage(text=caption)
+                    )
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        params = {"chat_id": chat_id, "photo": photo}
+        if caption is not None:
+            params["caption"] = caption
+        if filename is not None:
+            params["filename"] = filename
+        return await self.auto_execute("sendPhoto", params)

pysplusthon-0.5.0/PySPlusthon/client/attachments/send_sticker.py

@@ -0,0 +1,51 @@
+from typing import Union, BinaryIO
+
+import PySPlusthon
+from ...objects import InputMedia, resolve_media, Message, ReplyMarkup
+
+
+class SendSticker:
+
+    async def send_sticker(
+            self: "PySPlusthon.Client",
+            chat_id: Union[int, str],
+            sticker: Union[str, bytes, BinaryIO, InputMedia],
+            reply_markup: ReplyMarkup = None,
+            reply_to_message_id: int = None
+    ) -> Message:
+        if self.is_userbot():
+            from ...proto import requests, structs
+            peer_id, peer_type = map(int, chat_id.split("|"))
+            file_id, access_hash, file_storage_version, sticker_id, collection_id = map(int, sticker.split(":"))
+            return await self.execute(requests.SendMessage(
+                peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                ),
+                rid=self.ws_connection.create_rid(),
+                message=structs.Message(
+                    sticker_message=structs.StickerMessage(
+                        sticker_id=structs.Int32Value(
+                            value=sticker_id,
+                        ),
+                        image512=structs.ImageLocation(
+                            file_location=structs.FileLocation(
+                                file_id=file_id,
+                                access_hash=access_hash,
+                                file_storage_version=structs.Int32Value(value=file_storage_version)
+                            )
+                        ),
+                        sticker_collection_id=structs.Int32Value(
+                            value=collection_id
+                        )
+                    ),
+                ),
+                ex_peer=structs.Peer(
+                    type=peer_type,
+                    id=peer_id
+                )
+            ))
+
+        chat_id = await self.resolve_peer_id(chat_id)
+        sticker = resolve_media(sticker)
+        return await self.auto_execute("sendSticker", locals())