telebot_py.filters

Update and message filtering with boolean algebra (FR-002).

Filters compose with &, | and ~ (or the and_/or_/not_ aliases) and gate which updates reach a handler:

from telebot_py import filters
from telebot_py.routing import MessageHandler

private_text = filters.TEXT & filters.ChatType.PRIVATE
handler = MessageHandler(private_text, callback)

telebot_py.filters.base

Message filter base class with boolean-algebra composition (FR-002).

telebot_py.filters.base.FilterResult = bool | dict[str, typing.Any] | None

True/False for plain filters, or a dict of extracted data (truthy on match) for data_filter filters.

Type:

Result of evaluating a filter

class telebot_py.filters.base.MessageFilter

Bases: object

Base class for filters inspecting Message objects.

Subclass and override filter(), or combine instances with &, | and ~ (also available as and_(), or_(), not_() since and/or/not are Python keywords). Evaluation of combined filters short-circuits. Filters with data_filter set return a dict of extracted data on a match, which handlers merge into the callback context.

Variables:

data_filter (bool) – Whether the filter yields extracted data instead of a plain bool.

and_(other: MessageFilter) → MessageFilter

Combine with other via logical AND (alias of &).

Parameters:

other – The filter to combine with.

Returns:

A new composite filter matching only when both sides match.

data_filter: bool = False
filter(message: Message) → bool | dict[str, Any] | None

Evaluate this filter against message.

Parameters:

message – The message to inspect.

Returns:

True on a match and False otherwise; for data filters a non-empty dict on a match and a falsy value otherwise.

not_() → MessageFilter

Invert this filter (alias of ~).

Returns:

A new filter matching when this one does not.

or_(other: MessageFilter) → MessageFilter

Combine with other via logical OR (alias of |).

Parameters:

other – The filter to combine with.

Returns:

A new composite filter matching when either side matches.

telebot_py.filters.matchers

Built-in message filters mirroring python-telegram-bot’s filters module.

telebot_py.filters.matchers.ALL: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Matches every message unconditionally.

telebot_py.filters.matchers.COMMAND: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Messages that start with a bot command entity.

class telebot_py.filters.matchers.Chat(chat_id: int | Iterable[int] | None = None, username: str | Iterable[str] | None = None)

Bases: MessageFilter

Filter matching messages sent in a specific chat.

Variables:

  • chat_ids – Chat ids accepted by this filter.

  • usernames – Lower-cased chat usernames accepted by this filter.

filter(message: Message) → bool

Evaluate this filter against message.

Parameters:

message – The message to inspect.

Returns:

True on a match and False otherwise; for data filters a non-empty dict on a match and a falsy value otherwise.

class telebot_py.filters.matchers.ChatType

Bases: object

Filters matching the type of chat a message was sent in.

Variables:
CHANNEL: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>
GROUP: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>
GROUPS: MessageFilter = <telebot_py.filters.base._OrFilter object>
PRIVATE: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>
SUPERGROUP: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>
telebot_py.filters.matchers.DOCUMENT: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Messages that carry a document.

telebot_py.filters.matchers.NONE: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Matches no message ever.

telebot_py.filters.matchers.PHOTO: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Messages that carry a photo.

class telebot_py.filters.matchers.Regex(pattern: str | Pattern[str])

Bases: MessageFilter

Data filter matching message text (or caption) against a regular expression.

On a match the filter yields {"matches": [re.Match]}, which handlers merge onto the callback context as context.matches. The pattern is searched (re.search semantics) against message.text falling back to message.caption.

Variables:

  • pattern – The compiled regular expression to search for.

  • data_filter (bool) – Always True; this filter extracts match data.

data_filter: bool = True
filter(message: Message) → bool | dict[str, Any] | None

Evaluate this filter against message.

Parameters:

message – The message to inspect.

Returns:

True on a match and False otherwise; for data filters a non-empty dict on a match and a falsy value otherwise.

telebot_py.filters.matchers.TEXT: MessageFilter = <telebot_py.filters.matchers._PredicateFilter object>

Messages that contain non-empty text.

class telebot_py.filters.matchers.User(user_id: int | Iterable[int] | None = None, username: str | Iterable[str] | None = None)

Bases: MessageFilter

Filter matching messages sent by a specific user.

Variables:

  • user_ids – User ids accepted by this filter.

  • usernames – Lower-cased usernames accepted by this filter.

filter(message: Message) → bool

Evaluate this filter against message.

Parameters:

message – The message to inspect.

Returns:

True on a match and False otherwise; for data filters a non-empty dict on a match and a falsy value otherwise.