🚀 کتابخانه رسمی و مدرن پایتون برای اتوماسیون شاد

مستندات کامل و هوشمند
کتابخانه قدرتمند shadism (شادیسم)

طراحی‌شده بر پایه پروتکل بومی پیام‌رسان شاد، رمزنگاری پیشرفته دوطرفه AES/RSA، معماری تماماً ناهمگام (Async/Await) و مجهز به دیسپچر رویدادمحور و مدل‌های شیء‌گرای داده.

👨‍💻 توسعه‌دهنده: امیرعلی خسروی نژاد • کانال رسمی: ble.ir/join/8jXbafMPwL • مستندات: shadism.spark-js.ir
⚡ شروع سریع و نصب گیت‌هاب پروژه 🐙 کانال اطلاع‌رسانی 🔗
100%
ناهمگام (Asyncio Native)
E2E
رمزنگاری AES-CBC + RSA
20+
متدهای کاربردی و پیشرفته
WebRTC
پشتیبانی از ویس‌چت گروه/کانال

⚡ نصب و راه‌اندازی سریع Quickstart

CLI Terminal — Installation
bash

کتابخانه shadism به صورت مستقیم از طریق PyPI قابل نصب است و تمامی پیش‌نیازها را به صورت خودکار نصب خواهد کرد:

Bash / Terminal
pip install shadism
CLASS Client(phone_number, session_directory=".")
shadism.Client

کلاس اصلی کلاینت برای ایجاد سشن، اتصال امن، ذخیره سشن روی دیسک با فرمت .session و دریافت کد یکبار مصرف لاگین (OTP).

Python — Client Initialization
import asyncio
from shadism import Client

bot = Client("0937xxxxxxx")

@bot.on_message
async def handler(message):
    print(f"New message: {message.text}")

async def main():
    await bot.start()

asyncio.run(main())

💬 متدهای مدیریت پیام‌ها و تاریخچه چت Messages API

NEW await bot.get_chat_history(guid, limit=50)
List[Message]

متد اختصاصی و هوشمند تاریخچه پیام‌ها: این متد با ترکیب اندپوینت‌های پیام و آپدیت و با بهره‌گیری از صفحه‌بندی خودکار (Automatic Pagination)، تاریخچه یک گفتگو (کاربر، گروه یا کانال) را تا سقف مقدار درخواستی دریافت کرده و به‌صورت لیستی از اشیای کامل Message برمی‌گرداند.

نام پارامتر نوع پیش‌فرض توضیحات
guid / object_guid str اجباری شناسه اختصاصی کاربر (u0...)، گروه (g0...) یا کانال (c0...)
limit int 50 تعداد پیام‌های درخواستی (با پشتیبانی از مقادیر بزرگ و دریافت دسته‌ای)
sort str "FromMax" مرتب‌سازی پیام‌ها بر اساس شناسه ("FromMax" یا "FromMin")
Python — get_chat_history Example
from shadism import Client

bot = Client("0937xxxxxxx")

@bot.on_message
async def history_example(message):
    if message.text == "تاریخچه":
        # دریافت ۲۰ پیام اخیر با تمام امکانات شیء‌گرا
        history = await bot.get_chat_history(message.chat_guid, limit=20)
        
        for msg in history:
            print(f"[{msg.id}] {msg.author_guid}: {msg.text}")
            
            # متدهای مستقیم روی تک تک پیام‌ها
            if "سلام" in (msg.text or ""):
                await msg.reply("درود!")
METHOD await bot.send_message(object_guid, text, reply_to_message_id=None)
Message

ارسال پیام متنی به چت، گروه یا کانال با پشتیبانی از ریپلای روی پیام دیگر. خروجی این متد شیء Message است که می‌توانید بلافاصله روی آن عملیات ویرایش، ریپلای یا حذف را انجام دهید.

Python — send_message
# ارسال پیام ساده
sent_msg = await bot.send_message(
    object_guid="u0DoNvd...",
    text="سلام از کتابخانه shadism! 🚀"
)

# ارسال در پاسخ به یک پیام مشخص
reply_msg = await bot.send_message(
    object_guid="u0DoNvd...",
    text="پاسخ به پیام شما",
    reply_to_message_id=sent_msg.id
)
METHOD await bot.edit_message(object_guid, message_id, text)
Message

ویرایش متن پیامی که قبلاً ارسال شده است. هم از طریق کلاینت و هم مستقیماً با فراخوانی await message.edit("متن جدید") قابل استفاده است.

Python — edit_message
# روش ۱: از طریق شیء پیام
await message.edit("متن این پیام با موفقیت ویرایش شد ✅")

# روش ۲: از طریق ربات و شناسه پیام
await bot.edit_message(
    object_guid=chat_guid,
    message_id="6209768942",
    text="متن اصلاح‌شده"
)
METHOD await bot.delete_message(object_guid, message_id, delete_type="Global")
Dict[str, Any]

حذف پیام به صورت دوطرفه (Global) یا یکطرفه (Local). پروتکل شاد با ارسال نوع Global پیام را از دو طرف پاکسازی می‌کند.

Python — delete_message
# حذف مستقیم از روی شیء پیام
await message.delete(delete_type="Global")

# حذف دسته‌ای چندین پیام همزمان
await bot.delete_messages(
    object_guid=message.chat_guid,
    message_ids=["6209768940", "6209768941"],
    delete_type="Global"
)

📁 متدهای چندرسانه‌ای و آپلود فایل Media & Upload API

METHOD await bot.send_photo(object_guid, photo, caption=None)
Message

ارسال تصویر با فشرده‌سازی هوشمند بندانگشتی (Thumbnail)، محاسبه خودکار ابعاد طول و عرض و ارسال مستقیم به سرورهای آپلود شاد (UploadFile.ashx). ورودی تصویر می‌تواند آدرس فایل، شیء Path یا بایت‌های خام باشد.

Python — send_photo
# ارسال عکس با مسیر محلی
await bot.send_photo(
    object_guid=message.chat_guid,
    photo="banner.jpg",
    caption="بنر جدید کانال ما 🖼️"
)

# ارسال عکس با بایت‌های خام یا در پاسخ
await message.reply_photo(
    photo=raw_image_bytes,
    caption="تصویر ساخته‌شده با هوش مصنوعی"
)
METHOD await bot.send_file(object_guid, file, file_name=None, mime=None, caption=None)
Message

ارسال اسناد، فایل‌های فشرده zip، صوت، ویدیو یا هر نوع فایل دیگر با آپلود تکه‌ای (Chunked Streaming) و مقاومت بالا در برابر قطعی‌های شبکه.

Python — send_file
await bot.send_file(
    object_guid=message.chat_guid,
    file="archive.zip",
    file_name="source_code.zip",
    caption="سورس کد پروژه شادیسم 📦"
)

👥 متدهای چت‌ها، گروه‌ها و کاربران Chats & Users

METHOD await bot.get_chat_info(object_guid)
Chat

دریافت اطلاعات جامع چت (پی‌وی، گروه یا کانال). این متد به‌طور خودکار نوع چت را بر اساس پیشوند شناسه (u0/g0/c0) تشخیص داده و متد مرتبط شاد (getUserInfo, getGroupInfo, getChannelInfo) را فراخوانی می‌کند.

Python — get_chat_info
chat = await bot.get_chat_info("g0B12345...")

print(f"نام چت: {chat.title}")
print(f"نوع گفتگو: {chat.chat_type}")  # Group / Channel / User
print(f"تعداد اعضا: {chat.members_count}")
print(f"آیدی عددی: {chat.guid}")

# ارسال مستقیم پیام از روی آبجکت Chat
await chat.send_message("سلام به همه اعضای گروه!")
METHOD await bot.get_user_info(user_guid=None)
User

دریافت اطلاعات یک کاربر با شناسه او؛ یا اگر پارامتر خالی بماند، اطلاعات صاحب اکانت جاری (سلف بات) برگردانده می‌شود.

Python — get_user_info & update_profile
# دریافت اطلاعات خودمان
me = await bot.get_user_info()
print(f"نام من: {me.first_name} {me.last_name}")
print(f"بیوگرافی: {me.bio}")

# ویرایش بیوگرافی یا نام پروفایل
await bot.update_profile(
    first_name="شادیسم",
    bio="توسعه‌یافته توسط امیرعلی خسروی نژاد"
)

🎙️ متدهای ویس چت و WebRTC Voice Chat API

VOICE await bot.join_voice_chat(chat_guid, voice_chat_id)
Dict[str, Any]

پکیج کامل مدیریت صوتی گروه و کانال: ایجاد گفتگوی صوتی، ورود با SDP Offer (WebRTC)، تنظیم وضعیت میکروفون (Speaking / Mute) و خروج از ویس.

Python — Voice Chat Automation
# ۱. ایجاد ویس چت جدید در گروه
vc_info = await bot.create_voice_chat(group_guid)

# ۲. ورود به ویس چت
await bot.join_voice_chat(chat_guid=group_guid)

# ۳. تنظیم حالت صحبت کردن
await bot.methods.set_voice_chat_state(
    chat_guid=group_guid,
    voice_chat_id=vc_id,
    activity="Speaking"
)

# ۴. خروج از گفتگوی صوتی
await bot.leave_voice_chat(chat_guid=group_guid)

🎯 سیستم قدرتمند فیلترها (Event Filters) Filters

MODULE shadism.filters — Declarative Filter Engine
Filter

سیستم فیلتر ماژولار با پشتیبانی از عملگرهای منطقی & (AND)، | (OR) و ~ (NOT) برای پردازش انتخابی پیام‌ها.

فیلتر عملکرد نمونه استفاده
filters.command تشخیص دستورات با پیشوندهای دلخواه filters.command("start", prefixes=["/", "!"])
filters.regex تطبیق با الگوی منظم (Regular Expressions) filters.regex(r"^دانلود\s+(.+)")
filters.private تنها پیام‌های چت‌های خصوصی (PV) filters.private
filters.group تنها پیام‌های ارسال‌شده در گروه‌ها filters.group
filters.channel تنها پیام‌های کانال‌ها filters.channel
filters.reply پیام‌هایی که در پاسخ به پیام دیگری هستند filters.reply
filters.create ساخت فیلتر شرطی دلخواه و تابع سفارشی filters.create(lambda m: "سلام" in m.text)
Python — Filter Composition
from shadism import Client, filters

bot = Client("0937xxxxxxx")

# فقط دستور پینگ در گروه‌ها
@bot.on_message(filters.command("ping") & filters.group)
async def ping_in_group(message):
    await message.reply("پونگ در گروه! 🏓")

# ترکیب دستورات چندگانه در پی‌وی
@bot.on_message(filters.command(["help", "راهنما"]) & filters.private)
async def private_help(message):
    await message.reply("راهنمای چت خصوصی...")

🧩 مدل‌های شیء‌گرا (OOP Data Models) Data Models

DATACLASS shadism.types.Message
Message

نمایش شیء‌گرای پیام‌های شاد با اتصالات خودکار به کلاینت. علاوه بر خصوصیات معمولی، امکان دسترسی شبه‌دیکشنری نظیر msg["message_id"] و دسترسی به بایت‌های خام سرور msg.raw فراهم است.

Python — Message Model Features
# خصوصیات شیء پیام:
msg.id                    # شناسه پیام
msg.text                  # متن پیام
msg.author_guid           # فرستنده
msg.chat_guid             # چت مقصد
msg.is_edited             # آیا ادیت شده؟
msg.reply_to_message_id   # شناسه پیام ریپلای‌شده

# متدهای مستقیم پیام:
await msg.reply("متن پاسخ")
await msg.reply_photo("image.png")
await msg.reply_file("doc.pdf")
await msg.edit("متن جدید")
await msg.delete(delete_type="Global")
chat = await msg.get_chat()
author = await msg.get_author()

💡 پروژه‌ها و مثال‌های ترکیبی کامل Full Projects

APP Advanced Userbot & Cleaner — test.py
Application

نمونه واقعی و تولیدی یک یوزربات چندکاره در شاد، شامل منوی تعاملی دستور /start، آپلود تصاویر تک‌پیکسلی، پاکسازی دوطرفه خودکار با get_chat_history و هندلرهای خوش‌آمدگویی.

Python — Real-World Complete Bot
import asyncio
from shadism import Client, filters

bot = Client("0937xxxxxxx")

@bot.on_message(filters.command("start"))
async def start_cmd(message):
    await message.reply(
        "🤖 به یوزربات شادیسم خوش آمدید!\n\n"
        "1. ارسال تصویر\n"
        "2. پاکسازی دوطرفه پیام‌های من\n"
        "3. تاریخچه گفتگو"
    )

@bot.on_message(filters.command("history") | filters.command("تاریخچه"))
async def chat_history_cmd(message):
    history = await bot.get_chat_history(message.chat_guid, limit=10)
    lines = [f"📜 آخرین {len(history)} پیام چت:"]
    for i, m in enumerate(history, 1):
        lines.append(f"{i}. {m.text[:30]} | فرستنده: {m.author_guid[:8]}...")
    await message.reply("\n".join(lines))

@bot.on_message(filters.command("clean"))
async def clean_cmd(message):
    # پیدا کردن پیام‌ها با get_chat_history و پاکسازی دوطرفه
    history = await bot.get_chat_history(message.chat_guid, limit=50)
    my_messages = [m.id for m in history if m.author_guid == bot.session.user_guid]
    
    if my_messages:
        await bot.delete_messages(message.chat_guid, my_messages, delete_type="Global")
        await message.reply(f"🗑️ تعداد {len(my_messages)} پیام دوطرفه پاکسازی شد.")

async def main():
    await bot.start()

if __name__ == "__main__":
    asyncio.run(main())
✨ کد با موفقیت کپی شد!