From ea5f3f0448c69bef78369cc63423a3ff9868085d Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Wed, 16 Feb 2022 23:59:35 +0200 Subject: [PATCH] Added docs for chat_member_updated filter --- .../dispatcher/filters/chat_member_updated.py | 1 + .../filters/chat_member_updated.rst | 103 ++++++++++++++++++ docs/dispatcher/filters/index.rst | 3 +- 3 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 docs/dispatcher/filters/chat_member_updated.rst diff --git a/aiogram/dispatcher/filters/chat_member_updated.py b/aiogram/dispatcher/filters/chat_member_updated.py index b9812640..3f520cb4 100644 --- a/aiogram/dispatcher/filters/chat_member_updated.py +++ b/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 diff --git a/docs/dispatcher/filters/chat_member_updated.rst b/docs/dispatcher/filters/chat_member_updated.rst new file mode 100644 index 00000000..d02313f4 --- /dev/null +++ b/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` diff --git a/docs/dispatcher/filters/index.rst b/docs/dispatcher/filters/index.rst index a94636e6..106e0b0c 100644 --- a/docs/dispatcher/filters/index.rst +++ b/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