soroushthon 0.2.21__tar.gz

soroushthon-0.2.21/.github/workflows/check.yml

@@ -0,0 +1,27 @@
+name: Check Python package
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install test and build tools
+        run: python -m pip install -e '.[test]' build twine
+      - name: Test
+        run: python -m pytest -q
+      - name: Build and check metadata
+        run: |
+          python -m build
+          python -m twine check dist/*
+          python tools/check_release.py dist

soroushthon-0.2.21/.gitignore

@@ -0,0 +1,81 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+dist-*/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.pyi
+
+# Virtual Environment
+venv/
+.venv/
+env/
+ENV/
+
+# Package managers
+poetry.lock
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Linting / Type checking
+.mypy_cache/
+.ruff_cache/
+
+# Environment variables
+.env
+.env.*
+.pypirc
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Documentation
+docs/site/
+
+# Testing scripts
+speedtest.py
+test.py
+
+*.session
+*.session-journal
+*.session-*
+pytest-of-root/
+pip-ephem-wheel-cache-*/
+pip-unpack-*/
+readthedocs/
+.readthedocs.yaml
+tests/readthedocs/
+.mimocode/

soroushthon-0.2.21/AUDIT.md

@@ -0,0 +1,92 @@
+# گزارش بررسی معماری Soroushthon، SPlusthon و Telethon
+
+این گزارش برای ساخت یک **کتابخانهٔ عمومی حساب کاربری** است. هیچ بخش آن به ربات مدیریت گروه وابسته نیست. نسخهٔ مبنا: SPlusthon در commit `cad975488c66f91e4548c7fd4c255b4f787f9b0e`؛ مرجع مقایسه: شاخهٔ v1 کتابخانهٔ Telethon در commit `dab6bc4d4fc0c7815f6f19c6f643d9f75d2d930c`. مقایسه و آزمون‌های این گزارش در ۲۷ سپتامبر ۲۰۲۶ انجام شده‌اند. این بررسی جایگزین آزمایش همهٔ قابلیت‌ها روی سرور زندهٔ سروش نیست.
+
+## Telethon چه چیزی را فراهم می‌کند؟
+
+Telethon چند لایه دارد: تعریف‌های [زبان TL](https://docs.telethon.dev/en/stable/developing/understanding-the-type-language.html) برای ساخت کلاس‌های درخواست و پاسخ؛ موتور شبکه، رمزنگاری و نشست؛ و متدهای ساده‌تر کلاینت. مولد، تعریف‌های TL را به کلاس‌های پایتون تبدیل می‌کند و کلاس‌های `*Methods` رابط کاربردی هستند. [ساختار پروژهٔ Telethon](https://docs.telethon.dev/en/stable/developing/project-structure.html) و [راهنمای Raw API](https://docs.telethon.dev/en/stable/concepts/full-api.html) این تفکیک را توضیح می‌دهند. SPlusthon این لایه‌ها را از Telethon گرفته و طرح TL، WebSocket، کلیدها و پیش‌فرض‌های اتصال را برای سروش تغییر داده است. از روی کد هیچ شاهدی برای «نفوذ به سرور» به دست نمی‌آید؛ منشأ دقیق همهٔ تعریف‌های TL را نیز نمی‌توان با مشاهدهٔ مخزن تعیین کرد.
+
+کپی کردن متدهای Telethon به‌تنهایی کافی نیست: درخواست خام باید در طرح **خود سروش** وجود داشته باشد، شناسه و امضایش مطابق سرور باشد و پاسخ و خطا واقعاً آزموده شوند. تفاوت لایهٔ طرح تلگرام و سروش دلیل کافی برای نتیجه‌گیری دربارهٔ پشتیبانی سرور از هر درخواست منفرد نیست.
+
+## دامنهٔ قابلیت‌های خود سروش
+
+[وب‌سایت رسمی سروش‌پلاس](https://sapp.ir/) گفتگوی شخصی و گروهی، کانال، فایل، فضای ذخیره‌سازی و تماس صوتی/تصویری را معرفی می‌کند. در طرح TL فعلی بسته نام‌های مربوط به پیام، حساب، کانال، تماس، کنفرانس، داستان، پرداخت و سایر حوزه‌ها دیده می‌شود (شمارش هر حوزه در `CAPABILITIES.md`). این دو مشاهده **به‌تنهایی** اثبات نمی‌کنند که تمام امکانات برنامه با همین WebSocket و یک حساب، یا با یک فراخوانی TL، قابل پیاده‌سازی هستند. برای تماس زنده، پرداخت و امکانات تازه ممکن است جریان‌ها و سرویس‌های دیگری نیز لازم باشد. در منابع عمومی بررسی‌شده، مرجع معتبر و کاملِ شناسه و امضای همهٔ درخواست‌های حساب کاربریِ سروش به دست نیامد؛ بنابراین درخواست‌های غایب را با شناسهٔ تلگرام پر نکرده‌ایم.
+
+## نتیجهٔ قابل تکرارِ مقایسهٔ کل طرح
+
+در ریشهٔ پروژه، کنار یک checkout از Telethon v1، اجرا کن:
+
+```sh
+python tools/audit_upstreams.py --telethon ../telethon_reference
+```
+
+| گروه | SPlusthon/Soroushthon | Telethon v1 | نام مشترک | شناسهٔ یکسان | تعریف کاملاً یکسان | فقط سروش | فقط Telethon |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| نوع‌های TL | ۱۲۷۰ | ۱۵۴۱ | ۱۲۲۵ | ۱۱۲۱ | ۱۱۱۱ | ۴۵ | ۳۱۶ |
+| تابع‌های TL | ۳۶۶ | ۷۵۴ | ۳۳۶ | ۳۰۲ | ۲۹۶ | ۳۰ | ۴۱۸ |
+
+طرح بستهٔ سروش `LAYER 182` و طرح checkout تلگرام `LAYER 222` است. این شمارش فقط تعریف‌های یک‌خطی معتبر در دو فایل `api.tl` را مقایسه می‌کند. برای مثال بعضی سازنده‌ها با نام مشترک، شناسه یا امضای متفاوت دارند؛ `messages.deleteMessages` از این دسته است. انتقال خودکار درخواست‌های غایب Telethon به سروش اشتباه است.
+
+در کلاس‌های `*Methods`، ۵۹ نام عمومی Telethon در فورک هم یافت شد و پنج نام دیگر برای پروفایل در Soroushthon وجود دارد؛ **اشتراک نام به معنی کارکرد ۵۹ قابلیت نیست**. بررسی اولیه ۱۲ نام کلاس خامِ غایب یافت؛ پس از حذف استفادهٔ نامعتبر `InvokeWithoutUpdatesRequest` در 0.2.13، ۱۱ نام در ارجاع‌های کد باقی‌اند و شاخه‌های عمومی وابسته به آن‌ها خطای مشخص می‌دهند. مسیر پیش‌نویس‌های همهٔ گفتگوها از ارجاع به درخواست غایب به بازیابی از فهرست گفتگوها تغییر کرده است؛ این تغییر هنوز روی سرور زنده آزموده نشده است.
+
+## درخواست‌های غایب و اثرشان
+
+| حوزه | نام‌های غایب در طرحِ بسته | مسیر استفادهٔ احتمالی |
+| --- | --- | --- |
+| ورود ربات | `auth.ImportBotAuthorizationRequest` | شاخهٔ `sign_in(bot_token=...)`؛ اکنون پیام واضح `NotImplementedError` می‌دهد |
+| نشست takeout | `account.InitTakeoutSessionRequest`, `account.FinishTakeoutSessionRequest`, `InvokeWithTakeoutRequest` | آغاز، درخواست درون نشست، پایان |
+| بدون رویداد | `InvokeWithoutUpdatesRequest` | گزینهٔ `receive_updates=False` و مسیر ارسال درخواست |
+| گفتگو و رسانه | `messages.EditInlineBotMessageRequest`, `upload.GetCdnFileRequest`, `upload.ReuploadCdnFileRequest` | ویرایش inline، مسیر CDN؛ پیش‌نویس‌ها اکنون مسیر جایگزین دارند |
+| مدیریت و پوشه‌ها | `channels.GetAdminLogRequest`, `messages.EditChatAdminRequest`, `folders.DeleteFolderRequest` | مسیرهای متناظر متدهای سطح‌بالا |
+| پیکربندی CDN | `help.GetCdnConfigRequest` | مسیر دریافت کلید/پیکربندی CDN |
+
+این‌ها ارجاع‌های **ایستا** هستند. بعضی فقط در یک شاخهٔ شرطی یا برای نوع خاصی از ورودی اجرا می‌شوند. وجودشان به معنای خراب بودن تمام تابع `send_file` یا `sign_in` نیست؛ برای نمونه ورود با شمارهٔ تلفن قبلاً روی گوشی اجرا شده، ولی ورود با توکن ربات در طرح فعلی تعریف نشده است. بدون تعریف تأییدشدهٔ سروش، ساختن کلاس TL با شناسهٔ تلگرام راه‌حل معتبر نیست.
+
+## مرور لایه‌ها
+
+| لایه | شواهد در کد | وضعیت/کار بعدی |
+| --- | --- | --- |
+| اتصال و رمزنگاری | `network/connection/websocket.py`، `network/mtprotosender.py`، `crypto/`، `client/telegrambaseclient.py` | WebSocket پیش‌فرض سروش به مسیر `/apiws` می‌رود. گزینه‌های proxy و local_addr در این مسیر اعمال نمی‌شدند؛ اکنون به‌جای اتصال مستقیم ناخواسته، خطای صریح می‌دهند. پایداری اتصال طولانی و مسیرهای جایگزین نیازمند آزمون زنده‌اند. |
+| نشست و بازیابی | `sessions/memory.py`، `sessions/sqlite.py`، `sessions/string.py` | خطای setter کلید موقت و ترتیب بازیابی ستون‌های SQLite اصلاح شد؛ حفظ مقدارها بعد از بستن و بازکردن با آزمون محلی بررسی شد. بازیابی نشست واقعی پس از قطعی طولانی نیازمند آزمون گوشی است. |
+| احراز هویت | `client/auth.py` و `tl/functions/auth.py` | ورود با شماره/کد در نسخه‌های قبلی توسط کاربر اجرا شده است. مسیر bot-token کلاس خام ندارد؛ بعضی متن‌های مستنداتِ منتقل‌شده از تلگرام هنوز باید بازبینی شوند. |
+| موجودیت‌ها و آدرس‌دهی | `client/users.py`، `sessions/`، `utils.py` | پردازش موجودیت‌ها اکنون قبل از برگشت RPC منتظر می‌ماند؛ تبدیل لینک عمومی و دریافت بیوی خود/کاربر دیگر روی گوشی گزارش شده‌اند. |
+| پیام، گفتگو و رویداد | `client/messages.py`، `client/dialogs.py`، `client/updates.py`، `events/` | کاربر خواندن سه گفتگو و سه پیام از تاریخچه را روی گوشی تأیید کرد. مسیر همهٔ پیش‌نویس‌ها از گفتگوها بازسازی شده و آزمون محلی دارد. برای حذف پیام، اگر مقصد داده شده باشد، اکنون فیلد `peer` طرح سروش فرستاده می‌شود. دریافت رویداد، پیش‌نویس، ویرایش، حذف و شاخه‌های پیشرفته هنوز نیازمند آزمون زنده‌اند. |
+| فایل و رسانه | `client/uploads.py`، `client/downloads.py`، `tl/custom/` | کد سطح‌بالا موجود است؛ شاخه‌های CDN به کلاس‌های غایب اشاره می‌کنند. آپلود/دانلود عادی، انواع فایل و انقضا نیازمند آزمون واقعی و گزارش خطا هستند. |
+| تولید کد TL | `soroushthon_generator/data/api.tl`، `tools/generate.py` | مولد و ۳۶۶ تعریف درخواست بسته شده‌اند. برای هر قابلیت تازه باید ابتدا تعریف معتبر همان سرویس به دست آید، بعد کلاس تولید و درخواست/پاسخ آزموده شود. |
+| ابزار و آزمون | `tests/`، `tools/audit_upstreams.py` | آزمون‌های محلی مسیرهای مشخص هسته را می‌سنجند؛ آزمون خودکار محلی نمی‌تواند پشتیبانی سرور را ثابت کند. |
+
+نسخهٔ 0.2.4 متد `SoroushClient.for_account('test')` را برای نشست مستقلِ حساب آزمایشی اضافه کرده است. نام `main` به فایل نشست قدیمی اشاره می‌کند؛ نام‌های دیگر فایل جدا در پوشهٔ خانگی می‌سازند. آزمون رسانه در `examples/media_coverage.py` برای پنج قالب کوچک، مراحل ارسال، بازیابی، دانلود و حذف پیام تازهٔ همان حساب را ثبت می‌کند. مسیر ساخت محلیِ عکس، ویدئو، صوت و سند آزمایش شده است. شرح نتیجهٔ سرور در `MEDIA.md` آمده است.
+
+آزمون زندهٔ حساب دوم در نسخهٔ 0.2.4 نشان داد ارسال متن، ویرایش و حذف پیام تازه موفق‌اند، ولی پنج بار `upload.SaveFilePartRequest` و یک بار `upload.GetFileRequest` با `FILE_REQUEST_RECEIVED_ON_CONNECTION_SERVER` رد شدند. نسخهٔ 0.2.5 اتصال مستقل و `InitConnection(params.connection=upload)` را روی همان میزبان عمومی امتحان کرد؛ نتیجهٔ زندهٔ هر پنج آپلود همچنان خطای ۴۲۲ بود. این روش رد شده است. بررسی [بستهٔ وب رسمی](https://web.splus.ir/main.69cb2ff17c22724308b0.js) نشان داد sender فایل به میزبان جایگزین DC متصل می‌شود و RPC فایل را مستقیم می‌فرستد. نسخهٔ 0.2.6 مسیر آپلود و دانلود را بر این اساس عوض کرده است. آزمون‌های محلی مسیریابی، درخواست خام، کلید DC دیگر و بستن اتصال را بررسی کرده‌اند. جدول دقیق میزبان‌ها در [PROTOCOL.md](PROTOCOL.md) آمده است.
+
+پس از انتشار 0.2.6، کاربر روی حساب آزمایشی `70012182` برای هر پنج قالب کوچک، ارسال، بازیابی، دانلود و حذف را موفق گزارش کرد. مجموعاً ۲۰ مرحلهٔ `PASS` ثبت شد. این نتیجه، مسیر رسانه را برای همین حساب و همین اندازه‌ها تأیید می‌کند؛ اندازهٔ نمونه‌ها کمتر از ۱۰ کیلوبایت است و شاخهٔ چندبخشی و `SaveBigFilePart` را پوشش نمی‌دهد. نسخهٔ 0.2.7 آزمون جداگانهٔ سند حدود ۲ مگابایتی و مسیر اختیاری بالای ۱۰ مگابایت با بررسی تطابق بایت‌ها اضافه می‌کند. دانلود عکس پروفایل و انتقال فایل از DC متفاوت همچنان نیازمند آزمون زنده‌اند.
+
+اجرای زندهٔ نخست آزمون ۲ مگابایتی در نسخهٔ 0.2.7 با `TimeoutError` در ارسال شکست خورد؛ اتصال WebSocket چند بار timeout شد و یک `aiohttp.ClientSession` باز ماند. تعداد بخش‌های پذیرفته‌شده در خروجی معلوم نبود، بنابراین این مشاهده به‌تنهایی مشکل سرور یا محدودیت اندازهٔ فایل را ثابت نمی‌کند. نسخهٔ 0.2.8 نشست را هنگام لغو/شکست handshake و راه‌اندازی WebSocket می‌بندد و آزمون تشخیصی دو بخشی با شمارش زندهٔ بخش‌ها اضافه می‌کند. علت اصلی timeout همچنان نیازمند گزارش شمارش بخش‌ها و آزمون شبکهٔ حساب آزمایشی است.
+
+گزارش 0.2.7 بعداً نشان داد ۵ بخش از ۱۷ بخش پذیرفته شدند؛ اجرای زندهٔ `--probe` در 0.2.8 با دو بخش، بازیابی و تطابق کامل بایت‌ها موفق بود. در آزمون 0.2.7 `asyncio.wait_for(send_file, timeout=180)` سقف را روی کل ارسال گذاشته بود. نسخهٔ 0.2.9 آن را به وقفهٔ بدون پیشرفت تغییر می‌دهد و زمان تأیید هر بخش را گزارش می‌کند تا کندی CPU/شبکه از خطای سرور جدا شود. هنوز آزمون زندهٔ دوبارهٔ فایل ۲ مگابایتی انجام نشده است.
+
+آزمون زندهٔ 0.2.9 روی حساب دوم هر ۱۷ بخش فایل `2097169` بایتی را در حدود ۹۱ ثانیه آپلود کرد و پیام را بازیافت و حذف کرد. دانلود در **اولین** `GetFileRequest` با `ServerError` ۵۰۰ شکست خورد؛ شمار بخش‌های دریافتی صفر و زمان خطا ۰٫۴ ثانیه بود. کلاینت وب رسمی برای این اندازه درخواست ۱۲۸ کیلوبایتی دارد و خطای داخلی فایل را چند بار تکرار می‌کند. مسیر نخستین فایل در 0.2.9 مستقیم با `sender.send` می‌رفت و برخلاف درخواست‌های بعدی، حلقهٔ retry نداشت. نسخهٔ 0.2.10 حداکثر سه تکرار محدود برای `ServerError` در درخواست نخست اضافه کرد. آزمون زندهٔ 0.2.10 روی همان حساب، ارسال، بازیابی، دریافت ۱۷ بخش، تطابق کامل محتوا و حذف سند را تأیید کرد. از گزارش نمی‌توان فهمید در آن اجرای موفق، retry لازم شده بود یا نه.
+
+کد وب رسمی برای آپلود بر حسب اندازهٔ فایل، بخش ۳۲/۲۵۶/۵۱۲ کیلوبایتی به کار می‌برد؛ کد قبلی کتابخانه تا ۱۰۰ مگابایت همیشه ۱۲۸ کیلوبایت انتخاب می‌کرد. در 0.2.11 اندازهٔ پیش‌فرض آپلود با این رفتار هماهنگ شد و آزمون محلی ۲ مگابایت + ۱۷ بایت (۹ بخش کوچک) و ۱۰ مگابایت + ۱ کیلوبایت (۲۱ بخش بزرگ) افزوده شد. نتیجهٔ آزمون زندهٔ بعدی در بند زیر ثبت شده است.
+
+آزمون زندهٔ 0.2.11 آپلود ۹ بخشی و دانلود ۱۷ بخشی سند ۲ مگابایتی را با تطابق محتوا تأیید کرد. سند بالای ۱۰ مگابایت نیز در ۲۱ بخش ارسال و پیام آن بازیافت شد. دانلود پس از دریافت ۱۶ بخش به سقف ۹۰ ثانیهٔ کل دانلود برخورد؛ آن سقف در ابزار آزمون بود. نسخهٔ 0.2.12 سقف را برای هر وقفهٔ بدون دریافت بخش جداگانه می‌سنجد و امکان نگهداری پیام پس از شکست و تلاش دوبارهٔ دانلود با هش ثبت‌شده را به ابزار آزمون افزود. دریافت و تطابق کامل سند بزرگ هنوز روی سرور تأیید نشده است.
+
+در 0.2.13 تمام ۵۹ نام متد Telethon v1 با رابط بسته و تعریف‌های خامِ SPlusthon مقایسه شدند؛ جدول تفکیک آزمون زنده، مسیر غیرمستقیم، آزمون محلی و شاخهٔ مسدود در `PARITY.md` است. بررسی دوبارهٔ ارجاع‌های خام، ۱۱ نام کلاس غایب را در کد به‌جا نشان می‌دهد. مسیرهای takeout، گزارش مدیران، unpack پوشه، ویرایش مدیر گروه کوچک، ویرایش پیام inline، CDN redirect و خاموش‌کردن رویداد، در نبود طرح سروش خطای روشن می‌دهند؛ اصلاح درصد پیشرفت `action` برای فایل نیز آزمون محلی دارد. این تغییرها به معنی اجرای موفق شاخه‌های مسدود روی سرور نیستند.
+
+## تغییرهای عملی این مرحله
+
+1. پردازش موجودیت‌های RPC تک‌درخواستی و دسته‌ای قبل از بازگشت پاسخ انجام می‌شود؛ مصرف‌کننده فوراً به موجودیت‌های ذخیره‌شده دسترسی دارد.
+2. کلید موقت نشست از کلید اصلی جدا می‌ماند و SQLite ترتیب ستون‌های ذخیره‌شده را درست بازمی‌خواند؛ نشست‌های قدیمی با کلید موقت خالی هم پوشش داده می‌شوند.
+3. WebSocket گزینهٔ proxy/local_addr را دیگر بی‌صدا نادیده نمی‌گیرد؛ پشتیبانی واقعی این گزینه‌ها هنوز باید پیاده‌سازی شود.
+4. مسیر ورود با توکن ربات به جای خطای مبهم AttributeError دلیل روشن می‌دهد.
+5. اسکریپت بررسی مستقل برای مقایسهٔ تمام تعریف‌های TL و کشف ارجاع‌های خام غایب اضافه شد.
+6. فهرست ماشینی ۶۴ متد عمومی و ۳۶۶ درخواست خام در `CAPABILITIES.json` و مرور آن در `CAPABILITIES.md` تولید شد؛ `examples/coverage.py` در یک اجرا برای همهٔ متدهای عمومی نتیجهٔ `PASS`، `FAIL` یا `SKIP` ثبت می‌کند. `SKIP` با `PASS` یکسان نیست و نبود دادهٔ آزمایشی را پنهان نمی‌کند.
+
+## ترتیب کار برای رسیدن به کتابخانهٔ قوی
+
+1. برای هر قابلیت، نمونهٔ ورودی/پاسخ **بدون شماره، کد ورود یا فایل نشست** تهیه و نسخهٔ کلاینت رسمی/طرح متناظر را مشخص کن. از حساب آزمایشی خودت استفاده کن.
+2. ابتدا مسیرهای پرکاربرد کتابخانه را روی گوشی در سناریوهای کوچک بیازما: ورود دوباره، فهرست گفتگو، دریافت رویداد، ارسال/ویرایش/حذف پیام خود، آپلود/دانلود فایل. نتیجهٔ هر مسیر را با خطا و نوع پاسخ ثبت کن.
+3. اگر کلاس خام موجود است، ناسازگاری تبدیل ورودی/پاسخ را در متد سطح‌بالا اصلاح کن. اگر نیست، فقط با شناسه و امضای معتبر سروش آن را به `api.tl` اضافه و مولد را اجرا کن.
+4. برای هر اصلاح مسیر موفق، خطا، نشست و اتصال مجدد را جداگانه آزمایش کن. یک جدول پوشش بر اساس **رفتار واقعی** نگهدار؛ تعداد نام متدها معیار پوشش نیست.
+
+هیچ کلید نشست، شماره یا کد تأییدی را برای بررسی این پروژه منتشر نکن. گزارش خطا با نوع درخواست و متن پاک‌سازی‌شده کافی است.