Make filters combinable

client/doc/concepts/updates.rst

@@ -37,7 +37,7 @@ The most common way is using the :meth:`Client.on` decorator to register your ca
 
     bot = Client(...)
 
-    @bot.on(events.NewMessage, filters.Command('/start'))
+    @bot.on(events.NewMessage, filters.Command('/start') | filters.Command('/help'))
     async def handler(event: events.NewMessage):
         await event.respond('Beep boop!')
 
@@ -46,7 +46,11 @@ The first parameter is the :class:`type` of one of the :mod:`telethon.events`, n
 The second parameter is optional.
 If provided, it must be a callable function that returns :data:`True` if the handler should run.
 Built-in filter functions are available in the :mod:`~telethon.events.filters` module.
-In this example, :class:`~events.filters.Command` means the handler will be called when the user sends */start* to the bot.
+In this example, :class:`~events.filters.Command` means the handler will be called when the user sends */start* or */help* to the bot.
+
+Built-in filter functions are also :class:`~telethon._impl.client.events.filters.combinators.Combinable`.
+This means you can use ``|``, ``&`` and the unary ``~`` to combine filters with *or*, *and*, and negate them, respectively.
+These operators correspond to :class:`events.filters.Any`, :class:`events.filters.All` and :class:`events.filters.Not`.
 
 When your ``handler`` function is called, it will receive a single parameter, the event.
 The event type is the same as the one you defined in the decorator when registering your handler.
@@ -140,7 +144,6 @@ This makes it very convenient to write custom filters using the :keyword:`lambda
         ...
 
 
-
 Setting priority on handlers
 ----------------------------
 

client/doc/developing/migration-guide.rst

@@ -345,6 +345,7 @@ There is no longer nested ``class Event`` inside them either.
 
 Instead, the event type itself is what the handler will actually be called with.
 Because filters are separate, there is no longer a need for v1 ``@events.register`` either.
+It also means you can combine filters with ``&``, ``|`` and ``~``.
 
 Filters are now normal functions that work with any event.
 Of course, this doesn't mean all filters make sense for all events.

client/doc/modules/types.rst

@@ -102,6 +102,10 @@ Private definitions
 
     Generic parameter used by :class:`AsyncList`.
 
+.. currentmodule:: telethon._impl.client.events.filters.combinators
+
+.. autoclass:: Combinable
+
 .. currentmodule:: telethon._impl.client.types.file
 
 .. autoclass:: InFileLike