کیت کار با API ایتا در پایتون

ایتاپای‌کیت یک ابزار غیررسمی به زبان پایتون است که راهکار هایی برای استفاده از API های این پیامرسان را ارائه می‌دهد.

نکته: برای آنکه بتوانید در کانال‌ها و گروه‌ها پیغام یا فایل ارسال کنید، قبل از هرکاری لازم است، کاربر @sender را در کانال یا گروه خود به عنوان مدیر اضافه کنید. نکته: با توجه به آپدیت مداوم نسخه وب ایتا توسط شرکت سازنده ممکن است برخی از ویژگی های این کتابخانه موقتا از کار بیوفتد، اگر با چنین چیزی مواجه شدید، می‌توانید با ایجاد issue در مخزن گیت‌هاب، ما را مطلع کنید تا هرچه سریع‌تر مشکل را برطرف سازیم.

نصب

شما می‌توانید با دستور زیر آخرین نسخۀ eitaapykit را برای پایتون دریافت نمایید:

pip install eitaa

همچنین نسخه درحال توسعه نیز از طریق دستور زیر قابل نصب است:

pip install git+https://github.com/bistcuite/eitaapykit.git

کلاس پایۀ Eitaa

برای اینکه بتوانید پیغام یا فایل ارسال کنید، لازم است ابتدا به صورت زیر یک نمونه(instance) از آن ایجاد کنید و سپس توکنی را که از سایت ایتایار دریافت کرده‌اید را به عنوان پارامتر به کلاس Eitaa بدهید:

from eitaa import Eitaa
token = "your eitaayar.ir token"
e = Eitaa(token)

ارسال پیغام

برای ارسال پیغام(پیام به صورت متن) کافی است از متد send_message در کلاس Eitaa استفاده کنید.

پارامتر های متد send_message:

• chat_id : شناسۀ یکتای کانال یا گروه.

- برای ارسال پیغام به کانال، کافی است آیدی کانال خود را بدون @ به آن نسبت بدهید.

- اگر کانال شما خصوصی است و یا قصد ارسال پیغام به یک گروه را دارید، کافی است لینک آن را نسبت بدهید.

• text : str : متن پیغامی که قصد ارسال آن را دارید.

• pin : bool(اختیاری) : با تغییر آن به True پیغام ارسالی در چت پین می‌شود، به صورت پیشفرض False است.

• view_to_delete : int(اختیاری) : اگر تعداد بازدید های پیغام به این عدد برسد، به صورت خودکار حذف خواهد شد.

• disable_notification : bool(اختیاری): با تنظیم آن بر روی True هیچگونه اعلانی برای مخاطبان ارسال نمی‌شود، به صورت پیشفرض روی False تنظیم شده است.

• reply_to_message_id : int(اختیاری): شناسۀ پیامی که می‌خواهید پیغام بر روی آن پاسخ داده شود.

• date(اختیاری) : فرمت زمانی Unix که می‌تواند زمانی در آینده را برای ارسال پیام مشخص کند.

مثال:

print(e.send_message("chat id","message text",pin=True))

تابع یک پاسخ JSON حاوی اطلاعاتی در مورد پیام ارسال شده برمی گرداند که حاوی فیلد های زیر است:

• ok (بولین):

- True: به معنی این است پیغام با موفقیت ارسال شده است.

- False: به معنی عدم موفقیت در ارسال پیام است.

• description (رشته‌ای، اختیاری): (تنها در صورتی ظاهر می‌شود که فیلد ok برابر با False باشد) این فیلد توضیحی دربارۀ علت ارسال نشدن پیام ارائه می‌دهد.

ارسال فایل

برای ارسال فایل به یک کانال یا گروه کافی است از متد send_file در کلاس Eitaa استفاده کنید.

پارامتر های متد send_file:

• chat_id : شناسۀ یکتای کانال یا گروه.

- برای ارسال پیغام به کانال، کافی است آیدی کانال خود را بدون @ به آن نسبت بدهید.

- اگر کانال شما خصوصی است و یا قصد ارسال پیغام به یک گروه را دارید، کافی است لینک آن را نسبت بدهید. - file: str: مسیر فایلی که می‌خواهید ارسال کنید. - text : str : متن پیغامی که قصد ارسال آن را دارید.

• pin : bool(اختیاری) : با تغییر آن به True پیغام ارسالی در چت پین می‌شود، به صورت پیشفرض False است.

• view_to_delete : int(اختیاری) : اگر تعداد بازدید های پیغام به این عدد برسد، به صورت خودکار حذف خواهد شد.

• disable_notification : bool(اختیاری): با تنظیم آن بر روی True هیچگونه اعلانی برای مخاطبان ارسال نمی‌شود، به صورت پیشفرض روی False تنظیم شده است.

• reply_to_message_id : int(اختیاری): شناسۀ پیامی که می‌خواهید پیغام بر روی آن پاسخ داده شود.

• date(اختیاری) : فرمت زمانی Unix که می‌تواند زمانی در آینده را برای ارسال پیام مشخص کند.

مثال:

print(e.send_file("chat id","caption","README.txt",pin=True))

تابع یک پاسخ JSON حاوی اطلاعاتی در مورد پیام ارسال شده برمی گرداند که حاوی فیلد های زیر است:

• ok (بولین):

- True: به معنی این است پیغام با موفقیت ارسال شده است.

- False: به معنی عدم موفقیت در ارسال پیام است.

• description (رشته‌ای، اختیاری): (تنها در صورتی ظاهر می‌شود که فیلد ok برابر با False باشد) این فیلد توضیحی دربارۀ علت ارسال نشدن پیام ارائه می‌دهد.

دریافت اطلاعات یک کانال یا کاربر

شما می‌توانید با استفاده از متد get_info اطلاعات عمومی یک کانال و یا کاربر را بدست بیاورید.

پارامتر های متد get_info : - channel_or_user_id: str: شناسۀ عمومی کانال یا کاربر

مثال:

from eitaa import Eitaa
info = Eitaa.get_info("eitaa_faq")
print(info)

نمونه اطلاعات دریافتی:

{

    "name": "راهنمای جامع ایتا",

    "image_url": "will contains a url",

    "users": "205.9K",

    "description": "پاسخ به پرسش\u200cهای متداول کاربران ایتا\n\nپشتیبانی کاربران:\n@support\n\nکانال اطلاع\u200cرسانی رسمی:\n@eitaa\n\nوبسایت رسمی برنامه:\nhttps://eitaa.com", "is_verified": true,

    "is_channel": true

}

دریافت آخرین پیام های یک کانال عمومی

متد get_latest_messages که یک متد ایستا(static method) است، می‌تواند برای دریافت چند پیام آخر یک کانال(معمولا ده پیام) استفاده شود. مقدار خروجی این متد یک لیست متشکل از dictهایی خواهد بود که هر یک حاوی اطلاعات هر پیام است و فیلد هایی به شکل زیر دارد: - text : متن پیام

• image_link : آدرس اینترنتی تصویر پیام(اگر پیام به صورت کاملا متنی باشد، خالی خواهد بود)

• views : تعداد بازدید های پیام

• iso_time : زمان ارسال پیام به فرمت ISO

• message_number: شمارۀ پیام مثال:

from eitaa import Eitaa
messages = Eitaa.get_latest_messages('eitaa_faq')

دریافت هشتگ های ترندشده

متد get_trends که یک متد ایستا(static method) در کلاس پایۀ Eitaa است، می‌تواند برای استخراج هشتگ های ترندشده در ایتا، در بازه های زمانی متفاوت استفاده شود. این متد یک لیست متشکل از چهار dict یا دیکشنری برمی‌گرداند:

• last_12_hours: لیست هشتگ های ترند شده در 12 ساعت گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_24_hours: لیست هشتگ های ترند شده در 24 ساعت گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_7_days: لیست هشتگ های ترند شده در 7 روز گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

• last_30_days: لیست هشتگ های ترند شده در 30 روز گذشته همراه با تعداد هشتگ‌ها(که خودش متشکل از لیست از دیکشنری‌ها است که دارای دو فیلد name و count هستند، که شامل نام هشتگ و تعداد آن می‌شود).

مثال:

from eitaa import Eitaa
trends = Eitaa.get_trends()

خروجی نمونه:

{

    "last_12_hours": [

        {"name": "#اربعین", "count": "+1500"},

        {"name": "#امام_حسین", "count": "+500"},

        {"name": "#امام_زمان", "count": "+500"},

        {"name": "#شب_جمعه", "count": "+400"},

        {"name": "#کربلا", "count": "+300"}

    ],

    "last_24_hours": [

        {"name": "#اربعین", "count": "+3000"},

        {"name": "#امام_حسین", "count": "+1000"},

        {"name": "#امام_زمان", "count": "+700"},

        {"name": "#کربلا", "count": "+600"},

        {"name": "#شب_جمعه", "count": "+400"}

    ],

    ...

}

خاتمه

من bistcuite هستم، امیدوارم که این پکیج بدردتون خورده باشه، می‌تونید برای حمایت از پروژه، به مخزن کتابخانه در گیت‌هاب ستاره بدهید و چه بهتر که با ارسال pull request به ما در بهتر شدن این پکیج کمک کنید.