pysoroush 0.1.0__tar.gz

pysoroush-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Ali VEX
+
+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.
+PYEOF

pysoroush-0.1.0/MANIFEST.in

@@ -0,0 +1,21 @@
+# Include only what is needed for the package
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Include only the package's Python files
+recursive-include pysoroush *.py
+
+# Explicitly exclude anything sensitive or unnecessary
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude *.session
+global-exclude *.session-journal
+global-exclude *.log
+global-exclude *.db
+global-exclude *.sqlite
+global-exclude .env
+global-exclude *.pem
+global-exclude *.key
+global-exclude example*.py
+global-exclude test_*.py

pysoroush-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: pysoroush
+Version: 0.1.0
+Summary: A modern, simple, and powerful Python library for the Soroush Plus messenger.
+Author-email: Ali VEX <lyrdaadhrpyk802@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lyrdaadhrpyk802-ux/pysoroush
+Project-URL: Repository, https://github.com/lyrdaadhrpyk802-ux/pysoroush
+Keywords: soroush,soroush-plus,bot,api,userbot,messenger
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: splusthon>=1.1.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# PySoroush
+
+A modern, simple, and powerful Python library for the Soroush Plus messenger.
+
+Designed with an intuitive API so that even beginners can build bots and user-automation scripts with just a few lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/pysoroush.svg)](https://pypi.org/project/pysoroush/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pysoroush.svg)](https://pypi.org/project/pysoroush/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+### Bot API (Synchronous & Asynchronous)
+- Full support for the official Soroush Plus Bot API
+- Both Sync (requests) and Async (aiohttp) clients
+- Auto-Retry with exponential backoff on network failures
+- Rate Limit handling (automatic sleeping when hitting 429)
+- Fluent Keyboard Builder for building complex keyboards easily
+- Filters for routing messages (Text, Photo, Private, StateFilter, etc.)
+- FSM (Finite State Machine) for multi-step conversations
+- Media support (photos, videos, documents, audio, media groups)
+- WebApp data validation (HMAC-SHA-256)
+
+### Account API (Self / Userbot)
+- Login with phone number + OTP
+- Two-Step Verification support
+- Send and receive messages as your own user
+- Send media (photos, files, etc.)
+- Read message history, edit, delete, forward
+- Download media
+- Get dialogs and participants
+- Event handlers (on_message, on_callback, on_edited_message, etc.)
+- Raw TL API access for advanced use cases
+- Sync and Async interfaces
+
+---
+
+## Installation
+
+pip install pysoroush
+---
+
+Quick Start
+
+1. Bot API (Simple Polling)
+
+from pysoroush.bot import Bot
+
+bot = Bot("YOUR_BOT_TOKEN")
+
+@bot.command("start")
+def start_handler(msg):
+    return bot.reply(msg, "Hello! I am a bot.")
+
+@bot.on_message()
+def echo_handler(msg):
+    bot.reply(msg, f"You said: {msg.text}")
+    return True
+
+bot.run()  # Start polling
+2. Bot API with Inline Keyboards
+
+from pysoroush.bot import Bot
+from pysoroush.bot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+bot = Bot("YOUR_BOT_TOKEN")
+
+@bot.command("menu")
+def menu_handler(msg):
+    kb = InlineKeyboardMarkup().row(
+        InlineKeyboardButton(text="Option 1", callback_data="opt1"),
+        InlineKeyboardButton(text="Open Website", url="https://splus.ir")
+    )
+    bot.reply(msg, "Choose an option:", reply_markup=kb)
+    return True
+
+@bot.on_callback()
+def handle_callback(callback):
+    bot.answer_callback_query(callback.id, text=f"You clicked: {callback.data}")
+    return True
+
+bot.run()
+3. Async Bot
+
+import asyncio
+from pysoroush.bot import AsyncBot
+
+bot = AsyncBot("YOUR_BOT_TOKEN")
+
+@bot.command("start")
+async def start_handler(msg):
+    await bot.reply(msg, "Hello async world!")
+    return True
+
+async def main():
+    await bot.run()
+
+asyncio.run(main())
+4. Account API (Userbot)
+
+import asyncio
+from pysoroush.account import AsyncClient
+
+async def main():
+    # The first run will prompt for phone number and OTP
+    async with AsyncClient(session_file="my_account") as client:
+        if not await client.is_authorized():
+            phone = input("Phone number (e.g., 989123456789): ")
+            await client.start(phone=phone, code_callback=lambda: input("OTP: "))
+
+        me = await client.get_me()
+        print(f"Logged in as {me.first_name}")
+
+        await client.send_message("me", "Hello from my own account!")
+        await client.send_photo("me", "/path/to/photo.jpg", caption="Check this out!")
+
+        dialogs = await client.get_dialogs(limit=10)
+        for dialog in dialogs:
+            print(f"- {dialog.name}")
+
+asyncio.run(main())
+5. Account API with Event Handlers
+
+import asyncio
+from pysoroush.account import AsyncClient
+
+async def main():
+    async with AsyncClient(session_file="my_account") as client:
+        if not await client.is_authorized():
+            phone = input("Phone: ")
+            await client.start(phone=phone, code_callback=lambda: input("OTP: "))
+
+        @client.on_message()
+        async def auto_reply(message):
+            if message.text == "ping":
+                await message.reply("pong!")
+
+        print("Listening for messages...")
+        await client.run_until_disconnected()
+
+asyncio.run(main())
+---
+
+Security Notes
+
+· Never commit your *.session files to GitHub. These files contain your authentication tokens.
+· Use environment variables to store bot tokens in production.
+· The Account API is based on the MTProto protocol and is provided for automation purposes only. Please respect Soroush Plus's Terms of Service.
+
+---
+
+Contributing
+
+Contributions, issues, and feature requests are welcome!
+Feel free to check the issues page.
+
+---
+
+License
+
+This project is licensed under the MIT License.
+See the LICENSE file for details.
+
+---
+
+Author
+
+Ali VEX
+
+· GitHub: @lyrdaadhrpyk802-ux
+· Email: lyrdaadhrpyk802@gmail.com

pysoroush-0.1.0/README.md

@@ -0,0 +1,173 @@
+# PySoroush
+
+A modern, simple, and powerful Python library for the Soroush Plus messenger.
+
+Designed with an intuitive API so that even beginners can build bots and user-automation scripts with just a few lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/pysoroush.svg)](https://pypi.org/project/pysoroush/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pysoroush.svg)](https://pypi.org/project/pysoroush/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+### Bot API (Synchronous & Asynchronous)
+- Full support for the official Soroush Plus Bot API
+- Both Sync (requests) and Async (aiohttp) clients
+- Auto-Retry with exponential backoff on network failures
+- Rate Limit handling (automatic sleeping when hitting 429)
+- Fluent Keyboard Builder for building complex keyboards easily
+- Filters for routing messages (Text, Photo, Private, StateFilter, etc.)
+- FSM (Finite State Machine) for multi-step conversations
+- Media support (photos, videos, documents, audio, media groups)
+- WebApp data validation (HMAC-SHA-256)
+
+### Account API (Self / Userbot)
+- Login with phone number + OTP
+- Two-Step Verification support
+- Send and receive messages as your own user
+- Send media (photos, files, etc.)
+- Read message history, edit, delete, forward
+- Download media
+- Get dialogs and participants
+- Event handlers (on_message, on_callback, on_edited_message, etc.)
+- Raw TL API access for advanced use cases
+- Sync and Async interfaces
+
+---
+
+## Installation
+
+pip install pysoroush
+---
+
+Quick Start
+
+1. Bot API (Simple Polling)
+
+from pysoroush.bot import Bot
+
+bot = Bot("YOUR_BOT_TOKEN")
+
+@bot.command("start")
+def start_handler(msg):
+    return bot.reply(msg, "Hello! I am a bot.")
+
+@bot.on_message()
+def echo_handler(msg):
+    bot.reply(msg, f"You said: {msg.text}")
+    return True
+
+bot.run()  # Start polling
+2. Bot API with Inline Keyboards
+
+from pysoroush.bot import Bot
+from pysoroush.bot.types import InlineKeyboardMarkup, InlineKeyboardButton
+
+bot = Bot("YOUR_BOT_TOKEN")
+
+@bot.command("menu")
+def menu_handler(msg):
+    kb = InlineKeyboardMarkup().row(
+        InlineKeyboardButton(text="Option 1", callback_data="opt1"),
+        InlineKeyboardButton(text="Open Website", url="https://splus.ir")
+    )
+    bot.reply(msg, "Choose an option:", reply_markup=kb)
+    return True
+
+@bot.on_callback()
+def handle_callback(callback):
+    bot.answer_callback_query(callback.id, text=f"You clicked: {callback.data}")
+    return True
+
+bot.run()
+3. Async Bot
+
+import asyncio
+from pysoroush.bot import AsyncBot
+
+bot = AsyncBot("YOUR_BOT_TOKEN")
+
+@bot.command("start")
+async def start_handler(msg):
+    await bot.reply(msg, "Hello async world!")
+    return True
+
+async def main():
+    await bot.run()
+
+asyncio.run(main())
+4. Account API (Userbot)
+
+import asyncio
+from pysoroush.account import AsyncClient
+
+async def main():
+    # The first run will prompt for phone number and OTP
+    async with AsyncClient(session_file="my_account") as client:
+        if not await client.is_authorized():
+            phone = input("Phone number (e.g., 989123456789): ")
+            await client.start(phone=phone, code_callback=lambda: input("OTP: "))
+
+        me = await client.get_me()
+        print(f"Logged in as {me.first_name}")
+
+        await client.send_message("me", "Hello from my own account!")
+        await client.send_photo("me", "/path/to/photo.jpg", caption="Check this out!")
+
+        dialogs = await client.get_dialogs(limit=10)
+        for dialog in dialogs:
+            print(f"- {dialog.name}")
+
+asyncio.run(main())
+5. Account API with Event Handlers
+
+import asyncio
+from pysoroush.account import AsyncClient
+
+async def main():
+    async with AsyncClient(session_file="my_account") as client:
+        if not await client.is_authorized():
+            phone = input("Phone: ")
+            await client.start(phone=phone, code_callback=lambda: input("OTP: "))
+
+        @client.on_message()
+        async def auto_reply(message):
+            if message.text == "ping":
+                await message.reply("pong!")
+
+        print("Listening for messages...")
+        await client.run_until_disconnected()
+
+asyncio.run(main())
+---
+
+Security Notes
+
+· Never commit your *.session files to GitHub. These files contain your authentication tokens.
+· Use environment variables to store bot tokens in production.
+· The Account API is based on the MTProto protocol and is provided for automation purposes only. Please respect Soroush Plus's Terms of Service.
+
+---
+
+Contributing
+
+Contributions, issues, and feature requests are welcome!
+Feel free to check the issues page.
+
+---
+
+License
+
+This project is licensed under the MIT License.
+See the LICENSE file for details.
+
+---
+
+Author
+
+Ali VEX
+
+· GitHub: @lyrdaadhrpyk802-ux
+· Email: lyrdaadhrpyk802@gmail.com

pysoroush-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pysoroush"
+version = "0.1.0"
+description = "A modern, simple, and powerful Python library for the Soroush Plus messenger."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Ali VEX", email = "lyrdaadhrpyk802@gmail.com" }
+]
+keywords = ["soroush", "soroush-plus", "bot", "api", "userbot", "messenger"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "aiohttp>=3.8.0",
+    "splusthon>=1.1.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lyrdaadhrpyk802-ux/pysoroush"
+Repository = "https://github.com/lyrdaadhrpyk802-ux/pysoroush"
+
+[tool.setuptools.packages.find]
+include = ["pysoroush*"]

pysoroush-0.1.0/pysoroush/__init__.py

@@ -0,0 +1,30 @@
+"""
+PySoroush - A modern Python library for the Soroush Plus messenger.
+
+This package contains two independent sub-packages:
+
+* ``pysoroush.bot``      - Bot API client (sync & async).
+* ``pysoroush.account``  - User account (Self) API client (async).
+
+Example usage for bots::
+
+    from pysoroush.bot import Bot
+
+Example usage for accounts::
+
+    from pysoroush.account import AsyncClient
+"""
+
+__version__ = "0.1.0"
+__author__ = "Ali VEX"
+__author_email__ = "lyrdaadhrpyk802@gmail.com"
+__url__ = "https://github.com/lyrdaadhrpyk802-ux/pysoroush"
+__license__ = "MIT"
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__author_email__",
+    "__url__",
+    "__license__",
+]

pysoroush-0.1.0/pysoroush/account/__init__.py

@@ -0,0 +1,15 @@
+"""
+pysoroush.account - Soroush Plus User Account (Self) API client.
+"""
+
+from .client import Client
+from .async_client import AsyncClient
+from .exceptions import SoroushAccountError, AuthError, PasswordRequiredError
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "SoroushAccountError",
+    "AuthError",
+    "PasswordRequiredError",
+]