متدهای حساب کاربری
کلاس rubpy.Client یک کلاینت سطح بالا و ناهمزمان (async) برای تعامل مستقیم حساب کاربری با API روبیکا است. این مستند تمام متدها، پارامترها، مقدار بازگشتی، رفتار داخلی، نکات عملی و مثالها را پوشش میدهد و با ساختار واقعی rubpy.Client هماهنگ شده است.
ساخت نمونه¶
این کلاس شامل پارامترهایی برای تنظیم برخی تنظیمات است.
from rubpy import Client
app = Client("your-session-name")
پارامترهای سازنده¶
| پارامتر | نوع | پیشفرض | توضیحات |
|---|---|---|---|
name |
str | StringSession |
— | نام سشن SQLite یا سشن درونرشتهای برای ذخیرهٔ اطلاعات ورود. |
auth |
Optional[str] |
None |
کلید احراز هویت رمزگشاییشده. اگر داده شود، نیاز به ورود مجدد نیست. |
private_key |
Optional[str | bytes] |
None |
کلید خصوصی RSA؛ در صورت رشته بودن به طور خودکار با هدر/فوتر PEM تکمیل میشود. |
phone_number |
Optional[str] |
None |
شمارهٔ مورد استفاده برای ثبتنام یا ورود در زمان start. |
user_agent |
Optional[str] |
مرورگر کروم | User-Agent سفارشی برای تمام درخواستها. |
timeout |
Union[str,int,float] |
20 |
مهلت (ثانیه) برای درخواستهای شبکه؛ در صورت رشته، به عدد تبدیل میشود. |
lang_code |
str |
'fa' |
کد زبان ارسالشده برای سرور و ذخیره در DEFAULT_PLATFORM. |
parse_mode |
Optional[Literal['html','markdown','mk']] |
None → 'markdown' |
حالت پیشفرض تجزیهٔ متن؛ در صورت None به markdown تنظیم میشود. |
proxy |
Optional[str] |
None |
آدرس پروکسی (مثال: http://127.0.0.1:80). |
logger |
Optional[logging.Logger] |
لاگر ماژول | در صورت عدم ارسال، Logger داخلی ساخته میشود. |
display_welcome |
bool |
False |
در صورت True پس از مقداردهی، پیام خوشآمدگویی لاگ میشود. |
platform |
Literal['PWA','Android'] |
'PWA' |
مقداردهی اولیهٔ DEFAULT_PLATFORM (کلونشده برای هر نمونه). |
max_retries |
int |
5 |
سقف تلاش مجدد ارتباطات شبکه و دانلود/آپلود. |
sequential_handlers |
bool |
False |
در صورت True اولین هندلر که فیلترها را پاس کند اجرا شده و بقیه متوقف میشوند. |
نکات:
1. نمونههای StringSession امکان اشتراکگذاری سریع سشن بین سرویسها را فراهم میکنند.
2. هنگامی که parse_mode=None باشد، rubpy.Client آن را به markdown تبدیل میکند تا API متادیتای داخلی را دریافت کند.
3. مقدار DEFAULT_PLATFORM برای هر نمونه کپی میشود، بنابراین تغییر پلتفرم روی سایر کلاینتها اثری ندارد.
خطاها¶
ValueError: در صورت نامعتبر بودن ورودیها.TypeError: در صورت نادرست بودن نوع name.
چرخهٔ حیات¶
شروع کلاینت¶
متد: start
| پارامتر | نوع | توضیحات |
|---|---|---|
phone_number |
Optional[str] |
در صورت عدم ذخیرهٔ اعتبارسنجی، با استفاده از این شماره فرآیند ارسال کد و ورود انجام میشود. |
شرح کوتاه: اتصال به سرور، بارگذاری اطلاعات سشن (در صورت وجود)، احراز هویت کاربر و ثبت دستگاه جدید در صورت نیاز.@rubpy/methods/utilities/start.py#23-93
بازگشت: Client (async)
نکات:
1. اگر self.auth در سشن ذخیره شده باشد، start مستقیماً get_me را صدا زده و guid را مقداردهی میکند.
2. در نبود اعتبار ثبتشده، متد به طور تعاملی send_code، sign_in و register_device را اجرا میکند و پس از موفقیت، سشن SQLite یا StringSession را بهروزرسانی مینماید.@rubpy/methods/utilities/start.py#34-92
قطع ارتباط¶
متد: disconnect
| پارامتر | نوع | توضیحات |
|---|---|---|
| — | — | بستن آبجکت شبکه (connection) و آزادسازی منابع داخلی. |
شرح کوتاه: پایان دادن به ارتباط فعال و ثبت پیام در لاگر؛ در صورت عدم اتصال، استثناء NoConnection پرتاب میشود.@rubpy/methods/utilities/disconnect.py#4-20
بازگشت: None (async)
توقف ملایم¶
متد: stop
| پارامتر | نوع | توضیحات |
|---|---|---|
| — | — | تنها زمانی disconnect فراخوانی میشود که سشن شبکه هنوز باز باشد. |
شرح کوتاه: لایهٔ حفاظتی برای اسکریپتهای طولانی تا از بستن دوبارهٔ اتصال باز جلوگیری شود.@rubpy/client.py#165-168
بازگشت: None (async)
اجرای کلاینت¶
متد: run
| پارامتر | نوع | توضیحات |
|---|---|---|
coroutine |
Optional[Coroutine] |
تابعی async که پس از start اجرا شده و قبل از ورود به حلقهٔ دریافت آپدیتها خاتمه مییابد. |
phone_number |
Optional[str] |
در صورت نیاز به ورود دستی، به start پاس داده میشود. |
شرح کوتاه: در حالتهای sync/async قابل استفاده است؛ اگر هندلرها تابع همزمان باشند، run با فراخوانی مستقیم start و get_updates یک کلاینت قابل استفادهٔ همزمان برمیگرداند، در غیر این صورت روال ناهمزمان در یک loop موجود یا asyncio.run اجرا میشود.@rubpy/methods/utilities/run.py#8-37
بازگشت:
- حالت همزمان: خود کلاینت (برای زنجیرهای کردن متدها).
- حالت ناهمزمان: None یا asyncio.Task بسته به وجود حلقهٔ فعال.
نکته: run همیشه start را فراخوانی کرده و پس از اجرای coroutine اختیاری، وارد حلقهٔ get_updates میشود.
کانتکستمنیجر¶
__enter__/__exit__: نسخهٔ همزمان برای استفاده در اسکریپتهای ساده و اطمینان از قطع اتصال در پایان بلوک.@rubpy/client.py#143-163__aenter__/__aexit__: نسخهٔ async برای فریمورکهایی مثل FastAPI یا اسکریپتهای آسنکرون.
مدیریت هندلرها¶
| متد | توضیحات |
|---|---|
add_handler(func, handler) |
تابع کاربر و نمونهٔ هندلر (از rubpy.handlers) را ثبت میکند؛ اگر تابع sync باشد، self.is_sync فعال میشود تا روال اجرای همزمان فراهم شود.@rubpy/methods/utilities/add_handler.py#7-26 |
remove_handler(func) |
تابع از دیکشنری هندلرها حذف میشود (در فایل remove_handler.py). |
الگوی رایج:
client.add_handler(on_update, handlers.ChatUpdates())
await client.run()
دریافت آپدیتها¶
متد: get_updates
| پارامتر | نوع | توضیحات |
|---|---|---|
| — | — | حلقهٔ بینهایت با تلاش مجدد تا زمانی که self.connection.get_updates() نتیجه دهد. |
شرح کوتاه: لایهٔ سطح پایین برای دریافت آپدیت خام از اتصال وبسوکت/لانگپول؛ در صورت بروز خطا مجدداً تلاش میکند.@rubpy/methods/utilities/get_updates.py#3-17
بازگشت: rubpy.types.Update
اطلاعات پایهای¶
دریافت اطلاعات¶
متد: get_me
شرح کوتاه: دریافت اطلاعات حساب کاربری.
بازگشت: Dict (async)
مثال:
me = await client.get_me()
ارسال پیامها و محتوا¶
ارسال پیام¶
متد: send_message
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد (کاربر، گروه، کانال). |
text |
Optional[str] |
متن پیام؛ اگر طول >۴۲۰۰ باشد به صورت خودکار تکهتکه میشود. |
reply_to_message_id |
Optional[str] |
شناسهٔ پیام برای پاسخ. |
file_inline |
Optional[Union[Update, Path, bytes, str]] |
فایل درونخطی؛ مسیر محلی، URL یا بایت خام. |
sticker |
Optional[Union[Update, Dict]] |
آبجکت استیکر یا دیکشنری خام. |
type |
str |
نوع فایل ارسالی (File، Image، Music، Voice، Gif، Video، VideoMessage). |
is_spoil |
bool |
فلگ محتوای اسپویل (بسته به نوع فایل اثر متفاوت دارد). |
thumb |
bool |
ساخت خودکار بندانگشتی برای تصویر/ویدیو. |
audio_info |
bool |
استخراج متادیتای آهنگ/ویس هنگام آپلود باینری. |
auto_delete |
Optional[Union[int,float]] |
زمان حذف خودکار پس از ارسال (ثانیه). |
parse_mode |
Optional[str] |
نوع پارس متن؛ در صورت None از مقدار سراسری Client استفاده میشود. |
metadata |
Optional[Union[Update,dict]] |
اضافهکردن متادیتای اختصاصی (مانند قالببندی Markdown). |
شرح کوتاه: متد اصلی ارسال انواع پیام.
بازگشت: Dict (async)
مثال:
msg = await client.send_message("me", "سلام!")
ارسال داکیومنت¶
متد: send_document
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
document |
[Path, bytes] |
مسیر فایل یا بایت فایل |
caption |
Optional[str] |
کپشن فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال فایل.
بازگشت: Dict (async)
مثال:
msg = await client.send_document("me", "file.zip", "my zip file")
ارسال عکس¶
متد: send_photo
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
photo |
[Path, bytes] |
مسیر فایل یا بایت فایل |
caption |
Optional[str] |
کپشن فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال تصویر.
بازگشت: Dict (async)
مثال:
msg = await client.send_document("me", "image.jpg", "my image file")
ارسال گیف¶
متد: send_gif
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
gif |
[Path, bytes] |
مسیر فایل یا بایت فایل |
caption |
Optional[str] |
کپشن فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال گیف.
بازگشت: Dict (async)
مثال:
msg = await client.send_gif("me", "my.gif", "my gif file")
ارسال موسیقی¶
متد: send_music
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
music |
[Path, bytes] |
مسیر فایل یا بایت فایل |
caption |
Optional[str] |
کپشن فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال موسیقی.
بازگشت: Dict (async)
مثال:
msg = await client.send_music("me", "music.mp3", "my mp3 file")
ارسال استیکر¶
متد: send_sticker
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
sticker |
Dict |
اطلاعات استیکر |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال استیکر.
بازگشت: Dict (async)
مثال:
msg = await client.send_sticker("me", {})
ارسال ویدیو¶
متد: send_video
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
video |
[Path, bytes] |
مسیر فایل یا بایت فایل |
caption |
Optional[str] |
کپشن فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال ویدیو.
بازگشت: Dict (async)
مثال:
msg = await client.send_video("me", "video.mp4", "my video file")
ارسال ویدیو میسیج¶
متد: send_video_message
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
video_message |
[Path, bytes] |
مسیر فایل یا بایت فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال ویدیو میسیج.
بازگشت: Dict (async)
مثال:
msg = await client.send_video_message("me", "video.mp4")
ارسال صدا¶
متد: send_voice
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
voice |
[Path, bytes] |
مسیر فایل یا بایت فایل |
... |
... | باقی پارامترها شبیه send_message هستند |
شرح کوتاه: متد ارسال صدا.
بازگشت: Dict (async)
مثال:
msg = await client.send_voice("me", "voice.ogg")
متدهای پیام ها¶
دریافت ری اکشن های پیام¶
متد: get_message_reactions
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ مقصد |
message_id |
str |
شناسه پیام |
start_id |
Optional[str] |
شناسه اختصاصی برای ادامه دریافت ری اکشن ها |
شرح کوتاه: دریافت لیست ری اکشن های پیام.
بازگشت: Dict (async)
مثال:
reactions = await client.get_message_reactions("object_guid", "message_id")
# OR
reactions = await client.get_message_reactions("object_guid", "message_id", start_id="your-next-start-id")
نکته: پارامتر start_id به صورت پیشفرض برابر None است. این پارامتر برای دریافت ادامه ری اکشن ها نیاز است. یک next_start_id در خروجی داده میشود که برای همین مورد نیز نیاز است. همچنین یک has_continue خروجی داده میشود که یک متغیر bool است.
گرفتن وضعیت نظرسنجی¶
متد: get_poll_status
| پارامتر | نوع | توضیحات |
|---|---|---|
poll_id |
str |
شناسه نظرسنجی |
شرح کوتاه: دریافت وضعیت نظرسنجی.
بازگشت: Dict (async)
ری اکشن به پیام¶
متد: action_on_message_reaction
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
message_id |
str |
شناسه پیام |
reaction_id |
str |
آیدی ری اکشن |
action |
Literal['Add', 'Remove'] |
نوع اکشن (پیشفرض: False) |
شرح کوتاه: ری اکشن دادن به یک پیام در یک گفتگو.
بازگشت: Dict (async)
ایجاد نظرسنجی¶
متد: create_poll
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه مقصد |
question |
str |
سوال |
options |
list |
لیست سوالات |
type |
["Quiz", "Regular"] |
نوع نظرسنجی |
is_anonymous |
Optional[bool] |
آیا نظرسنجی ناشناس باشد؟ |
allows_multiple_answers |
Optional[bool] |
آیا نظرسنجی چند گزینه ای باشد؟ |
correct_option_index |
Optional[int] |
عدد ایندکس پاسخ درست |
explanation |
Optional[str] |
توضیحی برای پاسخ صحیح در نظرسنجیهای از نوع کوییز. |
reply_to_message_id |
Optional[str] |
شناسه پیام برای پاسخ |
شرح کوتاه: متد ارسال انواع نظرسنجی.
بازگشت: Dict (async)
حذف پیام¶
متد: delete_messages
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
message_ids |
list |
لیست شناسه پیام ها |
type |
Union["Global", "Local"] |
نوع حذف پیام |
شرح کوتاه: حذف تکی یا لیستی از پیام ها در یک گفتگو.
بازگشت: Dict (async)
ویرایش پیام¶
متد: edit_message
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
message_id |
str |
شناسه پیام |
text |
str |
متن جدید پیام |
parse_mode |
Optional[str] |
نوع پارس کردن پیام |
شرح کوتاه: ویرایش متن یک پیام.
بازگشت: Dict (async)
حذف خودکار پیام¶
متد: auto_delete_message
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسهٔ گفتگو. |
message_id |
str |
پیام هدف. |
time |
Union[int,float] |
تأخیر تا حذف (ثانیه). |
شرح کوتاه: پس از asyncio.sleep بهطور خودکار delete_messages را برای همان پیام فراخوانی میکند تا پاکسازی زمانبندیشده بسازد.@rubpy/methods/messages/auto_delete_message.py#1-35
بازگشت: Dict (async)
فوروارد پیام¶
متد: forward_messages
| پارامتر | نوع | توضیحات |
|---|---|---|
from_object_guid |
str |
از گفتگو |
to_object_guid |
str |
به گفتگو |
message_ids |
list |
لیست پیام ها |
شرح کوتاه: فوروارد پیام ها.
بازگشت: Dict (async)
آدرس اشتراک گذاری پیام¶
متد: get_message_url
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه کانال |
message_id |
str |
شناسه پیام |
شرح کوتاه: دریافت آدرس اشتراک گذاری عمومی پیام از کانال های عمومی.
بازگشت: Dict (async)
گرفتن پیام ها با شناسه¶
متد: get_messages_by_id
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
message_ids |
str |
شناسه پیام ها |
شرح کوتاه: دریافت پیام ها با استفاده از شناسه پیام ها.
بازگشت: Dict (async)
دریافت پیام های گفتگو¶
متد: get_messages_interval
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
middle_message_id |
str |
شناسه پیام میانی |
شرح کوتاه: دریافت 25 پیام آخر بر اساس آخرین شناسه پیام.
بازگشت: Dict (async)
گرفتن آپدیت های پیام ها¶
متد: get_messages_updates
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
state |
int |
ورودی timestamp |
شرح کوتاه: دریافت آپدیت های پیام های گفتگو.
بازگشت: Dict (async)
گرفتن رای دهندگان نظرسنجی¶
متد: get_poll_option_voters
| پارامتر | نوع | توضیحات |
|---|---|---|
poll_id |
str |
شناسه نظرسنجی |
selection_index |
int |
ایندکس انتخاب شده |
start_id |
str |
شناسه شروع |
شرح کوتاه: دریافت لیست رای دهندگان در نظرسنجی.
بازگشت: Dict (async)
سنجاق پیام¶
متد: set_pin_message
| پارامتر | نوع | توضیحات |
|---|---|---|
object_guid |
str |
شناسه گفتگو |
message_id |
str |
شناسه پیام |
action |
Literal['Pin', 'Unpin'] |
شناسه شروع |
شرح کوتاه: سنجاق کردن پیام یا حذف سنجاق پیام.
بازگشت: Dict (async)
رای دادن نظرسنجی¶
متد: vote_poll
| پارامتر | نوع | توضیحات |
|---|---|---|
poll_id |
str |
شناسه گفتگو |
selection_index |
str |
ایندکس انتخاب شده |
شرح کوتاه: رای دادن به نظرسنجی.
بازگشت: Dict (async)