🤖 soroush-bot

soroush-bot یک کتابخانه‌ی پایتون برای ساخت ربات‌های پیام‌رسان سروش پلاس است. این کتابخانه با الهام از python-telegram-bot نسخه ۲۲ به بالا طراحی شده تا توسعه‌دهندگان بتوانند به‌راحتی و با کمترین تغییرات، ربات‌های خود را برای سروش بسازند.

✨ ویژگی‌ها

• سینتکس آشنا – مشابه python-telegram-bot v22+
• کاملاً ناهمگام (Async) – مبتنی بر asyncio و aiohttp
• پشتیبانی از تمام متدهای API سروش پلاس – ارسال پیام، عکس، صدا، ویدئو، استیکر، فایل، ویرایش، حذف و ...
• هندلرهای قدرتمند – CommandHandler, MessageHandler, CallbackQueryHandler
• فیلترهای انعطاف‌پذیر – ترکیب با &, |, ~
• مدیریت خودکار offset – بدون نگرانی از دریافت پیام‌های تکراری
• بستن صحیح session – جلوگیری از خطای "Unclosed client session"

📦 نصب

pip install soroush-bot

یا مستقیماً از گیت‌هاب:

pip install git+https://github.com/AmirrezaJalilian/soroush-bot.git

توصیه: از یک محیط مجازی (venv) استفاده کنید.

🚀 شروع سریع

یک ربات ساده با دستور /start:

from soroush_bot import Application, CommandHandler

async def start(update, context):
    await update.message.reply_text("سلام! به ربات سروش خوش آمدید.")

def main():
    app = Application("YOUR_BOT_TOKEN")
    app.add_handler(CommandHandler("start", start))
    app.run_polling()

if __name__ == "__main__":
    main()

برای دریافت توکن، به ربات @BotFather در سروش مراجعه کنید.

📁 ساختار پروژه

soroush_bot/
├── __init__.py          # صادرات عمومی
├── application.py       # کلاس Application
├── handlers.py          # هندلرها
├── filters.py           # فیلترها
├── types.py             # انواع داده (Message, User, ...)
├── context.py           # Context
└── client.py            # کلاینت کامل API سروش
example_bot.py           # نمونه ربات ساده
README.md                # این فایل
LICENSE                  # مجوز MIT
pyproject.toml           # تنظیمات PyPI

🤝 مشارکت

ما خوشحال می‌شویم که شما در بهبود این پروژه مشارکت کنید! لطفاً مراحل زیر را دنبال کنید:

1. فورک (Fork) مخزن
2. یک برنچ جدید ایجاد کنید (git checkout -b feature/amazing-feature)
3. تغییرات خود را کامیت کنید (git commit -m 'Add some amazing feature')
4. پوش کنید (git push origin feature/amazing-feature)
5. یک Pull Request باز کنید

📜 مجوز

این پروژه تحت مجوز MIT منتشر شده است. برای جزئیات بیشتر به فایل LICENSE مراجعه کنید.

💬 ارتباط با ما

• گیت‌هاب: https://github.com/AmirrezaJalilian/soroush-bot
• PyPI: https://pypi.org/project/soroush-bot/
• سروش پلاس: https://soroushplus.com

ساخته شده با ❤️ برای جامعه سروش پلاس