Added docs for chat_member_updated filter

aiogram/dispatcher/filters/chat_member_updated.py

@@ -160,6 +160,7 @@ class ChatMemberUpdatedFilter(BaseFilter):
         _MemberStatusGroupMarker,
         _MemberStatusTransition,
     ]
+    """Accepts the status transition or new status of the member (see usage in docs)"""
 
     class Config:
         arbitrary_types_allowed = True

docs/dispatcher/filters/chat_member_updated.rst

@@ -0,0 +1,103 @@
+=================
+ChatMemberUpdated
+=================
+
+.. autoclass:: aiogram.dispatcher.filters.chat_member_updated.ChatMemberUpdatedFilter
+    :members:
+    :member-order: bysource
+    :undoc-members: False
+
+You can import from :code:`aiogram.dispatcher.filters` all available
+variants of `statuses`_, `status groups`_ or `transitions`_:
+
+Statuses
+========
+
++-------------------------+--------------------------------------+
+| name                    | Description                          |
++=========================+======================================+
+| :code:`CREATOR`         | Chat owner                           |
++-------------------------+--------------------------------------+
+| :code:`ADMINISTRATOR`   | Chat administrator                   |
++-------------------------+--------------------------------------+
+| :code:`MEMBER`          | Member of the chat                   |
++-------------------------+--------------------------------------+
+| :code:`RESTRICTED`      | Restricted user (can be not member)  |
++-------------------------+--------------------------------------+
+| :code:`LEFT`            | Isn't member of the chat             |
++-------------------------+--------------------------------------+
+| :code:`KICKED`          | Kicked member by administrators      |
++-------------------------+--------------------------------------+
+
+Statuses can be extended with `is_member` flag by prefixing with
+:code:`+` (for :code:`is_member == True)` or :code:`-` (for :code:`is_member == False`) symbol,
+like :code:`+RESTRICTED` or :code:`-RESTRICTED`
+
+Status groups
+=============
+
+The particular statuses can be combined via bitwise :code:`or` operator, like :code:`CREATOR | ADMINISTRATOR`
+
++-------------------------+-----------------------------------------------------------------------------------+
+| name                    | Description                                                                       |
++=========================+===================================================================================+
+| :code:`IS_MEMBER`       | Combination of :code:`(CREATOR | ADMINISTRATOR | MEMBER | +RESTRICTED)` statuses. |
++-------------------------+-----------------------------------------------------------------------------------+
+| :code:`IS_ADMIN`        | Combination of :code:`(CREATOR | ADMINISTRATOR)` statuses.                        |
++-------------------------+-----------------------------------------------------------------------------------+
+| :code:`IS_NOT_MEMBER`   | Combination of :code:`(LEFT | KICKED | -RESTRICTED)` statuses.                    |
++-------------------------+-----------------------------------------------------------------------------------+
+
+Transitions
+===========
+
+Transitions can be defined via bitwise shift operators :code:`>>` and :code:`<<`.
+Old chat member status should be defined in the left side for :code:`>>` operator (right side for :code:`<<`)
+and new status should be specified on the right side for :code:`>>` operator (left side for :code:`<<`)
+
+The direction of transition can be changed via bitwise inversion operator: :code:`~JOIN_TRANSITION`
+will produce swap of old and new statuses.
+
++-----------------------------+-----------------------------------------------------------------------+
+| name                        | Description                                                           |
++=============================+=======================================================================+
+| :code:`JOIN_TRANSITION`     | Means status changed from :code:`IS_NOT_MEMBER` to :code:`IS_MEMBER`  |
+|                             | (:code:`IS_NOT_MEMBER >> IS_MEMBER`)                                  |
++-----------------------------+-----------------------------------------------------------------------+
+| :code:`LEAVE_TRANSITION`    | Means status changed from :code:`IS_MEMBER` to :code:`IS_NOT_MEMBER`  |
+|                             | (:code:`~JOIN_TRANSITION`)                                            |
++-----------------------------+-----------------------------------------------------------------------+
+| :code:`PROMOTED_TRANSITION` | Means status changed from                                             |
+|                             | :code:`(MEMBER | RESTRICTED | LEFT | KICKED) >> ADMINISTRATOR`        |
+|                             | (:code:`(MEMBER | RESTRICTED | LEFT | KICKED) >> ADMINISTRATOR`)      |
++-----------------------------+-----------------------------------------------------------------------+
+
+.. note::
+
+    Note that if you define the status unions (via :code:`|`) you will need to add brackets for the statement
+    before use shift operator in due to operator priorities.
+
+Usage
+=====
+
+Handle user leave or join events
+
+.. code-block:: python
+
+    from aiogram.dispatcher.filters import IS_MEMBER, IS_NOT_MEMBER
+
+    @router.chat_member(chat_member_updated=IS_MEMBER >> IS_NOT_MEMBER)
+    async def on_user_leave(event: ChatMemberUpdated): ...
+
+    @router.chat_member(chat_member_updated=IS_NOT_MEMBER >> IS_MEMBER)
+    async def on_user_join(event: ChatMemberUpdated): ...
+
+Or construct your own terms via using pre-defined set of statuses and transitions.
+
+Allowed handlers
+================
+
+Allowed update types for this filter:
+
+- `my_chat_member`
+- `chat_member`

docs/dispatcher/filters/index.rst

@@ -18,6 +18,7 @@ Here is list of builtin filters:
     command
     content_types
     text
+    chat_member_updated
     exception
     magic_filters
     magic_data
@@ -83,7 +84,7 @@ Bound Filters with only default arguments will be automatically applied with def
 to each handler in the router and nested routers to which this filter is bound.
 
 For example, although we do not specify :code:`chat_type` in the handler filters,
-but since the filter has a default value, the filter will be applied to the handler 
+but since the filter has a default value, the filter will be applied to the handler
 with a default value :code:`private`:
 
 .. code-block:: python