فیلترها (Filters)

سیستم فیلترگذاری قدرتمند برای هندلرها — با قابلیت ترکیب و عملگرهای منطقی

کلاس‌های پایه
class Filter
کلاس پایه برای همه فیلترها با پشتیبانی از عملگرها
class Filter:
    def __init__(self, func: Callable):
        self.func = func

    def __call__(self, message):
        return self.func(message)

    # عملگرهای منطقی
    def __and__(self, other):  # and
    def __or__(self, other):   # or
    def __invert__(self):      # not
    def __xor__(self, other):  # xor
class TextFilter
فیلتر مخصوص پیام‌های متنی
class TextFilter:
    def __call__(self, keyword=None):
        if keyword is None:
            return Filter(lambda m: getattr(m, "is_text", False))
        else:
            return Filter(lambda m: getattr(m, "is_text", False) and 
                         keyword in getattr(m, "text", ""))
class IsCommand
فیلتر تشخیص دستورات (/start, /help و...)
class IsCommand(Filter):
    def __init__(self, commands=None):
        if commands is None:
            func = lambda m: getattr(m, "is_command", False)
        else:
            func = lambda m: getattr(m, "is_command", False) and \
                   getattr(m, "text", "").lstrip("/").split()[0] in commands

    def __getattr__(self, name: str):
        return IsCommand([name])
فیلترهای اصلی (Base Filters)
is_text
تشخیص پیام متنی
@bot.on_message(filters.is_text)
async def handler(bot, message):
    await message.reply("این یک پیام متنی است")
is_file
تشخیص پیام حاوی فایل
@bot.on_message(filters.is_file)
async def handler(bot, message):
    await message.reply("فایل دریافت شد")
is_command
تشخیص دستورات (با / شروع می‌شوند)
@bot.on_message(filters.is_command.start)
async def start(bot, message):
    await message.reply("دستور استارت دریافت شد")

@bot.on_message(filters.is_command.help)
async def help(bot, message):
    await message.reply("راهنمای ربات")
is_private / is_group / is_channel
تشخیص نوع چت
@bot.on_message(filters.is_private)
async def private(bot, message):
    await message.reply("پیام خصوصی")

@bot.on_message(filters.is_group)
async def group(bot, message):
    await message.reply("پیام گروهی")
is_reply / is_forwarded / is_edited
تشخیص وضعیت پیام
@bot.on_message(filters.is_reply)
async def reply(bot, message):
    await message.reply("این پیام پاسخ به پیام دیگری است")
is_sticker / is_contact / is_poll / is_location
تشخیص انواع خاص پیام
@bot.on_message(filters.is_sticker)
async def sticker(bot, message):
    await message.reply("استیکر دریافت شد")
فیلترهای متنی (Text Filters)
text_contains(substring, case_sensitive=False)
بررسی وجود کلمه در متن
@bot.on_message(filters.text_contains("سلام"))
async def handler(bot, message):
    await message.reply("شما سلام گفتید")
text_length(min_len, max_len)
بررسی طول متن
@bot.on_message(filters.text_length(min_len=10, max_len=100))
async def handler(bot, message):
    await message.reply("طول متن بین 10 تا 100 کاراکتر است")
text_regex(pattern) / regex(pattern)
بررسی متن با عبارت منظم
@bot.on_message(filters.regex(r'\d{4}-\d{2}-\d{2}'))
async def handler(bot, message):
    await message.reply("تاریخ تشخیص داده شد")
text_startswith / text_endswith
بررسی شروع یا پایان متن
@bot.on_message(filters.text_startswith("سلام"))
async def handler(bot, message):
    await message.reply("پیام با سلام شروع شده")
text_upper / text_lower / text_digit
بررسی حالت متن
@bot.on_message(filters.text_upper())
async def handler(bot, message):
    await message.reply("متن با حروف بزرگ است")
text_word_count(min_words, max_words)
بررسی تعداد کلمات متن
@bot.on_message(filters.text_word_count(min_words=5))
async def handler(bot, message):
    await message.reply("متن حداقل 5 کلمه دارد")
فیلترهای فایل (File Filters)
file_size_gt(size) / file_size_lt(size)
بررسی حجم فایل
@bot.on_message(filters.file_size_gt(1024*1024))
async def handler(bot, message):
    await message.reply("حجم فایل بیشتر از 1 مگابایت است")
file_extension(ext)
بررسی پسوند فایل
@bot.on_message(filters.file_extension(".py"))
async def handler(bot, message):
    await message.reply("فایل پایتون دریافت شد")
file_name_contains(substring)
بررسی وجود کلمه در نام فایل
@bot.on_message(filters.file_name_contains("ربات"))
async def handler(bot, message):
    await message.reply("فایل مربوط به ربات است")
فیلترهای چت و کاربر (Chat & User Filters)
sender_id_is(id) / chat_id_is(id)
فیلتر بر اساس شناسه فرستنده یا چت
@bot.on_message(filters.sender_id_is("user_id_here"))
async def handler(bot, message):
    await message.reply("پیام از کاربر خاص")
senders_id(list) / chat_ids(list)
فیلتر بر اساس لیست شناسه‌ها
@bot.on_message(filters.senders_id(["id1", "id2"]))
async def handler(bot, message):
    await message.reply("پیام از کاربران مجاز")
chat_title_contains / chat_title_equals
فیلتر بر اساس عنوان چت
@bot.on_message(filters.chat_title_contains("ربات"))
async def handler(bot, message):
    await message.reply("پیام از گروه ربات")
ترکیب فیلترها (Combining Filters)
& (and) | (or) ~ (not)
ترکیب فیلترها با عملگرهای منطقی
# AND - هر دو شرط باید برقرار باشد
@bot.on_message(filters.is_private & filters.is_command.start)
async def handler(bot, message):
    await message.reply("دستور start در پی وی")

# OR - حداقل یکی از شرایط
@bot.on_message(filters.is_private | filters.is_group)
async def handler(bot, message):
    await message.reply("پیام از پی وی یا گروه")

# NOT - شرط مخالف
@bot.on_message(~filters.is_private)
async def handler(bot, message):
    await message.reply("پیام از گروه یا کانال")
and_(*filters) / or_(*filters)
ترکیب چند فیلتر با هم
from rubka import filters

my_filter = filters.and_(
    filters.is_private,
    filters.is_command.start,
    filters.text_length(min_len=5)
)

@bot.on_message(my_filter)
async def handler(bot, message):
    await message.reply("همه شرایط برقرار است")
فیلترهای سفارشی (Custom Filters)
@filters.custom(name)
ساخت فیلترهای سفارشی با دکوریتور
from rubka import filters

@filters.custom("admin_only")
def admin_only(message):
    return message.sender_id in admin_list

@bot.on_message(filters.get_custom("admin_only"))
async def admin_handler(bot, message):
    await message.reply("فقط برای ادمین‌ها")
ساخت فیلتر مستقیم
ساخت فیلتر با lambda یا تابع معمولی
@bot.on_message(filters.Filter(lambda m: len(m.text) > 50))
async def handler(bot, message):
    await message.reply("متن طولانی است")
مثال کامل
نمونه کد کامل
استفاده از فیلترها در یک ربات
from rubka import Robot, Message, filters

bot = Robot("YOUR_TOKEN")

@bot.on_message(filters.is_private & filters.is_command.start)
async def start(bot: Robot, message: Message):
    await message.reply("سلام! به ربات خوش آمدید")

@bot.on_message(filters.is_group and filters.text_contains("سلام"))
async def hello_group(bot: Robot, message: Message):
    await message.reply("سلام به گروه!")

@bot.on_message(filters.is_file and filters.file_extension(".py"))
async def python_file(bot: Robot, message: Message):
    await message.reply("فایل پایتون دریافت شد!")

complex_filter = filters.and_(
    filters.is_group,
    filters.is_text
    filters.text_contains("ربات")
)

@bot.on_message(complex_filter)
async def complex_handler(bot: Robot, message: Message):
    await message.reply("شرایط پیچیده برقرار است")

bot.run()