Metadata-Version: 2.4
Name: telegram-group-manager
Version: 1.0.0
Summary: A reusable Python package for Telegram group moderation and management
Author: Amirali Yavari
Maintainer: Kiarash
License: MIT License
        
        Copyright (c) 2026 Amirali Yavari
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Original Source, https://github.com/AmiraliYavari/telegram-management-bot
Project-URL: Original Author, https://github.com/AmiraliYavari
Project-URL: Package Maintainer, https://github.com/Kia-ML
Keywords: telegram,telegram-bot,group-management,moderation,anti-spam,python-telegram-bot
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Other Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-telegram-bot[job-queue]<22,>=21.6
Requires-Dist: python-dotenv<2,>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Telegram Group Manager

پکیج `telegram-group-manager` یک ابزار پایتونی برای مدیریت و خودکارسازی وظایف رایج مدیریتی گروه‌های تلگرام است. این پروژه قابلیت‌هایی مانند مدیریت کاربران، کنترل پیام‌های مزاحم، خوش‌آمدگویی، ثبت آمار و زمان‌بندی وضعیت گروه را در اختیار مدیران و توسعه‌دهندگان قرار می‌دهد.

## اعتبار و منشأ پروژه

سورس اولیه ربات تلگرام توسط **امیرعلی یاوری (Amirali Yavari)** توسعه داده شده و با مجوز MIT در مخزن زیر منتشر شده است:

- مخزن سورس اصلی: [AmiraliYavari/telegram-management-bot](https://github.com/AmiraliYavari/telegram-management-bot)
- پروفایل توسعه‌دهنده سورس اصلی: [Amirali Yavari](https://github.com/AmiraliYavari)

**کیارش نوری (Kiarash Noori)** ساختار پروژه را برای استفاده مجدد در پروژه‌های پایتونی بازآرایی کرده، لایه ساخت Application و رابط خط فرمان را به نسخه پکیجی افزوده و فراداده‌های لازم برای بسته‌بندی استاندارد آن را آماده کرده است.

- پروفایل توسعه‌دهنده نسخه پکیجی: [Kia-ML](https://github.com/Kia-ML)

این پروژه مشتق‌شده از سورس اصلی است. اعتبار و حقوق سورس اولیه متعلق به توسعه‌دهنده اصلی باقی می‌ماند و متن مجوز و اعلان حق‌نشر در فایل `LICENSE` همراه پروژه ارائه شده است.

## قابلیت‌ها

- ارسال پیام خوش‌آمدگویی هنگام ورود اعضای جدید
- مدیریت تخلفات با دستورهای اخطار، لغو اخطار، مسدودسازی و رفع مسدودسازی
- محدودسازی و رفع محدودیت ارسال پیام کاربران
- فیلتر لینک و شناسایی الگوهای ساده ارسال پیام‌های پرتکرار
- ثبت آمار فعالیت گروه
- باز و بسته کردن گروه و زمان‌بندی این عملیات
- تعیین زبان گروه و شخصی‌سازی پیام خوش‌آمدگویی
- سیستم امتیازدهی XP، سطح‌بندی کاربران و جدول رتبه‌بندی
- ذخیره اطلاعات با SQLite

## نصب

پس از انتشار نسخه در PyPI، نصب پکیج و وابستگی‌های زمان اجرای آن با دستور زیر انجام می‌شود:

```bash
python -m pip install telegram-group-manager
```

وابستگی‌های زمان اجرا در `pyproject.toml` تعریف شده‌اند و pip آن‌ها را هنگام نصب پکیج نصب می‌کند:

- `python-telegram-bot[job-queue]` برای ارتباط با Telegram Bot API و اجرای وظایف زمان‌بندی‌شده
- `python-dotenv` برای خواندن تنظیمات از فایل `.env`

`sqlite3` بخشی از کتابخانه استاندارد پایتون است و به نصب جداگانه نیاز ندارد.

برای نصب مستقیم از پوشه سورس، پس از آماده‌سازی پروژه می‌توان از دستور زیر استفاده کرد:

```bash
python -m pip install .
```

## راه‌اندازی ربات

### ۱. ایجاد ربات

از طریق [@BotFather](https://t.me/BotFather) یک ربات بسازید و توکن آن را دریافت کنید. سپس ربات را به گروه اضافه کنید و دسترسی‌های لازم برای قابلیت‌های مورد استفاده را به آن بدهید.

### ۲. تنظیم متغیرهای محیطی

فایل `.env.example` را به `.env` تغییر نام دهید و توکن واقعی ربات را در آن قرار دهید:

```env
BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN
PROXY_URL=
WARN_LIMIT=3
SPAM_THRESHOLD=5
SPAM_WINDOW_SEC=10
DB_PATH=data/bot.db
XP_PER_MESSAGE=10
XP_COOLDOWN_SEC=60
```

فایل `.env` و توکن واقعی ربات را در مخزن عمومی منتشر نکنید.

### ۳. اجرای ربات

پس از نصب و تنظیم توکن، ربات را با یکی از روش‌های زیر اجرا کنید:

```bash
telegram-group-manager
```

یا:

```bash
python -m telegram_group_manager
```

## استفاده به‌عنوان کتابخانه

برای ساخت Application در برنامه پایتونی خود:

```python
from telegram_group_manager import create_application

app = create_application(token="YOUR_TELEGRAM_BOT_TOKEN")
app.run_polling()
```

همچنین می‌توانید توکن را در متغیر محیطی `BOT_TOKEN` قرار دهید:

```python
from telegram_group_manager import create_application

app = create_application()
app.run_polling()
```

تابع `create_application` یک نمونه از `Application` کتابخانه `python-telegram-bot` برمی‌گرداند و خودش polling را شروع نمی‌کند. بنابراین می‌توانید پیش از اجرای آن، handlerهای اختصاصی خود را اضافه کنید یا تنظیمات برنامه را تغییر دهید.

## تنظیمات

| متغیر | مقدار پیش‌فرض | توضیح |
|---|---:|---|
| `BOT_TOKEN` | ندارد | توکن ضروری ربات تلگرام |
| `PROXY_URL` | ندارد | آدرس پراکسی، در صورت نیاز |
| `WARN_LIMIT` | `3` | تعداد اخطار پیش از مسدودسازی خودکار |
| `SPAM_THRESHOLD` | `5` | آستانه تعداد پیام برای تشخیص اسپم |
| `SPAM_WINDOW_SEC` | `10` | بازه زمانی بررسی پیام‌های پرتکرار، بر حسب ثانیه |
| `DB_PATH` | `data/bot.db` | مسیر فایل پایگاه داده SQLite |
| `XP_PER_MESSAGE` | `10` | امتیاز هر پیام واجد شرایط |
| `XP_COOLDOWN_SEC` | `60` | فاصله زمانی بین دریافت امتیازها، بر حسب ثانیه |

## توسعه پروژه

برای نصب پروژه در حالت توسعه همراه با ابزارهای توسعه تعریف‌شده:

```bash
python -m pip install -e ".[dev]"
```

وابستگی‌های توسعه در بخش `dev` از `pyproject.toml` تعریف شده‌اند. فایل‌های انتشار و فرایند Build/Upload عمداً در این بسته آماده نشده‌اند تا توسعه‌دهنده آن‌ها را در محیط انتشار خود اجرا و کنترل کند.

## مشارکت

برای گزارش خطا، پیشنهاد قابلیت جدید یا مشارکت در توسعه، از Issues و Pull Requests مخزن نسخه پکیجی استفاده کنید. هنگام بازتوزیع یا انتشار نسخه‌های مشتق‌شده، شرایط مجوز MIT و اعلان حق‌نشر سورس اصلی را حفظ کنید.

## مجوز

این پروژه بر اساس سورس منتشرشده تحت **MIT License** آماده شده است. متن کامل مجوز و اعلان حق‌نشر سورس اصلی در فایل [`LICENSE`](LICENSE) قرار دارد.

---

**سورس اصلی:** [AmiraliYavari/telegram-management-bot](https://github.com/AmiraliYavari/telegram-management-bot)  
**توسعه نسخه پکیجی:** [Kia-ML](https://github.com/Kia-ML)
