python/aiogram
1
0
Fork 0
mirror of https://github.com/aiogram/aiogram.git synced 2025-12-12 18:19:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Remove MkDocs

Browse source
This commit is contained in:
Alex Root Junior 2021-05-13 00:13:09 +03:00
parent 7dd80d281f
commit e1cd7268a1
442 changed files with 4 additions and 9429 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/dispatcher/filters/command.md
View file

@ -1,32 +0,0 @@
# Command
This filter can be helpful for handling commands from the text messages.
Works only with [Message](../../api/types/message.md) events which have the `text`.
## Specification
| Argument | Type | Description |
| --- | --- | --- |
| `commands` | `#!python3 Union[Sequence[Union[str, re.Pattern]], Union[str, re.Pattern]]` | List of commands (string or compiled regexp patterns) |
| `commands_prefix` | `#!python3 str` | Prefix for command. Prefix is always is single char but here you can pass all of allowed prefixes, for example: `"/!"` will work with commands prefixed by `"/"` or `"!"` (Default: `"/"`). |
| `commands_ignore_case` | `#!python3 bool` | Ignore case (Does not work with regexp, use flags instead. Default: `False`) |
| `commands_ignore_mention` | `#!python3 bool` | Ignore bot mention. By default bot can not handle commands intended for other bots (Default: `False`) |
## Usage
1. Filter single variant of commands: `#!python3 Command(commands=["start"])` or `#!python3 Command(commands="start")`
1. Handle command by regexp pattern: `#!python3 Command(commands=[re.compile(r"item_(\d+)")])`
1. Match command by multiple variants: `#!python3 Command(commands=["item", re.compile(r"item_(\d+)")])`
1. Handle commands in public chats intended for other bots: `#!python3 Command(commands=["command"], commands)`
1. As keyword argument in registerer: `#!python3 @router.message(commands=["help"])`
!!! warning
Command cannot include spaces or any whitespace
## Allowed handlers
Allowed update types for this filter:
- `message`
- `edited_message`

37
docs/dispatcher/filters/command.rst Normal file
View file

@ -0,0 +1,37 @@
=======
Command
=======
.. autoclass:: aiogram.dispatcher.filters.command.Command
:members:
:member-order: bysource
:undoc-members: False
When filter is passed the :class:`aiogram.dispatcher.filters.command.CommandObject` will be passed to the handler argument :code:`command`
.. autoclass:: aiogram.dispatcher.filters.command.CommandObject
:members:
:member-order: bysource
:undoc-members: False
Usage
=====
1. Filter single variant of commands: :code:`Command(commands=["start"])` or :code:`Command(commands="start")`
2. Handle command by regexp pattern: :code:`Command(commands=[re.compile(r"item_(\d+)")])`
3. Match command by multiple variants: :code:`Command(commands=["item", re.compile(r"item_(\d+)")])`
4. Handle commands in public chats intended for other bots: :code:`Command(commands=["command"], commands)`
5. As keyword argument in registerer: :code:`@router.message(commands=["help"])`
.. warning::
Command cannot include spaces or any whitespace
Allowed handlers
================
Allowed update types for this filter:
- `message`
- `edited_message`

38
docs/dispatcher/filters/content_types.md
View file

@ -1,38 +0,0 @@
# ContentTypesFilter
Is useful for handling specific types of messages (For example separate text and stickers handlers).
This is always automatically adds to the filters list for message handlers.
Can be imported:
- `#!python3 from aiogram.dispatcher.filters.content_types import ContentTypesFilter`
- `#!python3 from aiogram.dispatcher.filters import ContentTypesFilter`
- `#!python3 from aiogram.filters import ContentTypesFilter`
Or used from filters factory by passing corresponding arguments to handler registration line
!!! warning "Please be patient!"
If no one content type filter is specified the `["text"]` value is automatically will be used.
## Specification
| Argument | Type | Description |
| --- | --- | --- |
| `content_types` | `#!python3 Optional[Union[Sequence[str], str]]` | List of allowed content types |
## Usage
1. Single content type: `#!python3 ContentTypesFilter(content_types=["sticker"])` or `#!python3 ContentTypesFilter(content_types="sticker")`
1. Multiple content types: `#!python3 ContentTypesFilter(content_types=["sticker", "photo"])`
1. Recommended: With usage of `ContentType` helper: `#!python3 ContentTypesFilter(content_types=[ContentType.PHOTO])`
1. Any content type: `#!python3 ContentTypesFilter(content_types=[ContentType.ANY])`
## Allowed handlers
Allowed update types for this filter:
- `message`
- `edited_message`
- `channel_post`
- `edited_channel_post`

39
docs/dispatcher/filters/content_types.rst Normal file
View file

@ -0,0 +1,39 @@
==================
ContentTypesFilter
==================
.. autoclass:: aiogram.dispatcher.filters.content_types.ContentTypesFilter
:members:
:member-order: bysource
:undoc-members: False
Can be imported:
- :code:`from aiogram.dispatcher.filters.content_types import ContentTypesFilter`
- :code:`from aiogram.dispatcher.filters import ContentTypesFilter`
- :code:`from aiogram.filters import ContentTypesFilter`
Or used from filters factory by passing corresponding arguments to handler registration line
.. warning::
**Please be patient!**
If no one content type filter is specified the :code:`["text"]` value is automatically will be used.
Usage
=====
1. Single content type: :code:`ContentTypesFilter(content_types=["sticker"])` or :code:`ContentTypesFilter(content_types="sticker")`
2. Multiple content types: :code:`ContentTypesFilter(content_types=["sticker", "photo"])`
3. Recommended: With usage of `ContentType` helper: :code:`ContentTypesFilter(content_types=[ContentType.PHOTO])`
4. Any content type: :code:`ContentTypesFilter(content_types=[ContentType.ANY])`
Allowed handlers
================
Allowed update types for this filter:
- :code:`message`
- :code:`edited_message`
- :code:`channel_post`
- :code:`edited_channel_post`

27
docs/dispatcher/filters/exception.md
View file

@ -1,27 +0,0 @@
# Exceptions
This filters can be helpful for handling errors from the text messages.
## ExceptionTypeFilter
Allow to match exception by type
### Specification
| Argument | Type | Description |
| --- | --- | --- |
| `exception` | `#!python3 Union[Type[Exception], Tuple[Type[Exception]]]` | Exception type(s) |
## ExceptionMessageFilter
Allow to match exception by message
### Specification
| Argument | Type | Description |
| --- | --- | --- |
| `match` | `#!python3 Union[str, Pattern[str]]` | Regexp pattern |
## Allowed handlers
Allowed update types for this filters:
- `error`

22
docs/dispatcher/filters/exception.rst Normal file
View file

@ -0,0 +1,22 @@
==========
Exceptions
==========
This filters can be helpful for handling errors from the text messages.
.. autoclass:: aiogram.dispatcher.filters.exception.ExceptionTypeFilter
:members:
:member-order: bysource
:undoc-members: False
.. autoclass:: aiogram.dispatcher.filters.exception.ExceptionMessageFilter
:members:
:member-order: bysource
:undoc-members: False
Allowed handlers
================
Allowed update types for this filters:
- :code:`error`

63
docs/dispatcher/filters/index.md
View file

@ -1,63 +0,0 @@
# Basics
Filters is needed for routing updates to the specific handler.
Searching of handler is always stops on first match set of filters are pass.
`aiogram` has some builtin useful filters.
## Builtin filters
Here is list of builtin filters and event types where it can be used:
| Filter | update | message | edited_message | channel_post | edited_channel_post | inline_query | chosen_inline_result | callback_query | shipping_query | pre_checkout_query | poll |
| ----------------------------------------- |:------:|:-------:|:--------------:|:------------:|:-------------------:|:------------:|:--------------------:|:--------------:|:--------------:|:------------------:|:----:|
| [Text](text.md) | | + | + | + | + | + | | + | | | + |
| [ContentTypesFilter](content_types.md) | | + | + | + | + | | | | | | |
| [Command](command.md) | | + | | | | | | | | | |
| | | | | | | | | | | | |
## Own filters specification
Filters can be:
- Asynchronous function (`#!python3 async def my_filter(*args, **kwargs): pass`)
- Synchronous function (`#!python3 def my_filter(*args, **kwargs): pass`)
- Anonymous function (`#!python3 lambda event: True`)
- Any awaitable object
- Subclass of `BaseFilter`
Filters should return bool or dict.
If the dictionary is passed as result of filter - resulted data will be propagated to the next
filters and handler as keywords arguments.
## Writing bound filters
If you want to register own filters like builtin filters you will need to write subclass
of BaseFilter (`#!python3 from aiogram.filters import BaseFilter`) with overriding the `__call__`
method and adding filter attributes.
BaseFilter is subclass of `pydantic.BaseModel` that's mean all subclasses of BaseFilter has
the validators based on class attributes and custom validator.
For example if you need to make simple text filter:
```python3
from aiogram.filters import BaseFilter
class MyText(BaseFilter):
my_text: str
async def __call__(self, message: Message) -> bool:
return message.text == self.my_text
router.message.bind_filter(MyText)
@router.message(my_text="hello")
async def my_handler(message: Message): ...
```
!!! info
Bound filters is always recursive propagates to the nested routers.

73
docs/dispatcher/filters/index.rst Normal file
View file

@ -0,0 +1,73 @@
================
Filtering events
================
Filters is needed for routing updates to the specific handler.
Searching of handler is always stops on first match set of filters are pass.
*aiogram* has some builtin useful filters.
Builtin filters
===============
Here is list of builtin filters:
.. toctree::
:maxdepth: 1
command
content_types
text
exception
Or you can do :ref:`✨ some magic <magic-filters>`
Own filters specification
=========================
Filters can be:
- Asynchronous function (:code:`async def my_filter(*args, **kwargs): pass`)
- Synchronous function (:code:`def my_filter(*args, **kwargs): pass`)
- Anonymous function (:code:`lambda event: True`)
- Any awaitable object
- Subclass of :ref:`BaseFilter <filters-base>`
Filters should return bool or dict.
If the dictionary is passed as result of filter - resulted data will be propagated to the next
filters and handler as keywords arguments.
Writing bound filters
=====================
.. autoclass:: aiogram.dispatcher.filters.base.BaseFilter
:members: __call__
:member-order: bysource
:undoc-members: False
For example if you need to make simple text filter:
.. code-block:: python
from aiogram.filters import BaseFilter
class MyText(BaseFilter):
my_text: str
async def __call__(self, message: Message) -> bool:
return message.text == self.my_text
router.message.bind_filter(MyText)
@router.message(my_text="hello")
async def my_handler(message: Message): ...
.. note::
Bound filters is always recursive propagates to the nested routers.

146
docs/dispatcher/filters/magic_filters.rst Normal file
View file

@ -0,0 +1,146 @@
.. _magic-filters:
=============
Magic filters
=============
.. note::
This page still in progress. Has many incorrectly worded sentences.
Is external package maintained by *aiogram* core team.
By default installs with *aiogram* and also is available on `PyPi - magic-filter <https://pypi.org/project/magic-filter/>`_.
That's mean you can install it and use with any other libraries and in own projects without depending *aiogram* installed.
Usage
=====
The **magic_filter** package implements class shortly named :class:`magic_filter.F` that's mean :code:`F` can be imported from :code:`magic_filter`. :class:`F` is alias for :class:`MagicFilter`.
The :class:`MagicFilter` object is callable, supports :ref:`some actions <magic-filter-possible-actions>`
and memorize the attributes chain and the action which should be checked on demand.
So that's mean you can chain attribute getters, describe simple data validations
and then call the resulted object passing single object as argument,
for example make attributes chain :code:`F.foo.bar.baz` then add
action ':code:`F.foo.bar.baz == 'spam'` and then call the resulted object - :code:`(F.foo.bar.baz == 'spam')(obj)`
.. _magic-filter-possible-actions:
Possible actions
================
Magic filter object supports some of basic logical operations over object attributes
Exists or not None
------------------
Default actions.
.. code-block:: python
F.photo # lambda message: message.photo
Equals
------
.. code-block:: python
F.text == 'hello' # lambda message: message.text == 'hello'
F.from_user.id == 42 # lambda message: message.from_user.id == 42
Is one of
---------
Can be used as method named :code:`in_` or as matmul operator :code:`@` with any iterable
.. code-block:: python
F.from_user.id.in_(42, 1000, 123123) # lambda query: query.from_user.id in {42, 1000, 123123}
F.data.in_('foo', 'bar', 'baz') # lambda query: query.data in {'foo', 'bar', 'baz'}
F.text @ {'foo', 'bar'} # lambda message: message.text in {'foo', 'bar'}
Contains
--------
.. code-block:: python
F.text.contains('foo') # lambda message: 'foo' in message.text
String startswith/endswith
--------------------------
Can be applied only for text attributes
.. code-block:: python
F.text.startswith('foo') # lambda message: message.text.startswith('foo')
F.text.endswith('bar') # lambda message: message.text.startswith('bar')
Regexp
------
.. code-block:: python
F.text.regexp(r'Hello, .+') # lambda message: re.match(r'Hello, .+', message.text)
Custom function
---------------
Accepts any callable. Callback will be called when filter checks result
.. code-block:: python
F.chat.func(lambda chat: chat.id == -42) # lambda message: (lambda chat: chat.id == -42)(message.chat)
Inverting result
----------------
Any of available operation can be inverted by bitwise inversion - :code:`~`
.. code-block:: python
~(F.text == 'spam') # lambda message: message.text != 'spam'
~F.text.startswith('spam') # lambda message: not message.text.startswith('spam')
Combining
---------
All operations can be combined via bitwise and/or operators - :code:`&`/:code:`|`
.. code-block:: python
(F.from_user.id == 42) & (F.text == 'admin')
F.text.startswith('a') | F.text.endswith('b')
(F.from_user.id @ {42, 777, 911}) & (F.text.startswith('!') | F.text.startswith('/')) & F.text.contains('ban')
Attribute modifiers - string manipulations
------------------------------------------
Make text upper- or lower-case
Can be used only with string attributes.
.. code-block:: python
F.text__lower == 'test' # lambda message: message.text.lower() == 'test'
F.text__upper.in_('FOO', 'BAR') # lambda message: message.text.upper() in {'FOO', 'BAR'}
F.text__len == 5 # lambda message: len(message.text) == 5
Usage in *aiogram*
==================
.. code-block:: python
@router.message(F.text == 'hello')
@router.inline_query(F.data == 'button:1')
@router.message(F.text.startswith('foo'))
@router.message(F.content_type.in_('text', 'sticker'))
@router.message(F.text.regexp(r'\d+'))
...
# Many others cases when you will need to check any of available event attribute

50
docs/dispatcher/filters/text.md
View file

@ -1,50 +0,0 @@
# Text
Is useful for filtering text [Message](../../api/types/message.md),
any [CallbackQuery](../../api/types/callback_query.md) with `data`,
[InlineQuery](../../api/types/inline_query.md) or
[Poll](../../api/types/poll.md) question.
Can be imported:
- `#!python3 from aiogram.dispatcher.filters.text import Text`
- `#!python3 from aiogram.dispatcher.filters import Text`
- `#!python3 from aiogram.filters import Text`
Or used from filters factory by passing corresponding arguments to handler registration line
## Specification
| Argument | Type | Description |
| --- | --- | --- |
| `text` | `#!python3 Optional[Union[Sequence[str], str]]` | Text equals value or one of values |
| `text_contains` | `#!python3 Optional[Union[Sequence[str], str]]` | Text contains value or one of values |
| `text_startswith` | `#!python3 Optional[Union[Sequence[str], str]]` | Text starts with value or one of values |
| `text_endswith` | `#!python3 Optional[Union[Sequence[str], str]]` | Text ends with value or one of values |
| `text_ignore_case` | `#!python3 bool` | Ignore case when checks (Default: `#!python3 False`) |
!!! warning
Only one of `text`, `text_contains`, `text_startswith` or `text_endswith` argument can be used at once.
Any of that arguments can be string, list, set or tuple of strings.
## Usage
1. Text equals with the specified value: `#!python3 Text(text="text") # value == 'text'`
1. Text starts with the specified value: `#!python3 Text(text_startswith="text") # value.startswith('text')`
1. Text ends with the specified value: `#!python3 Text(text_endswith="text") # value.endswith('text')`
1. Text contains the specified value: `#!python3 Text(text_endswith="text") # value in 'text'`
1. Any of previous listed filters can be list, set or tuple of strings that's mean any of listed value should be equals/startswith/endswith/contains: `#!python3 Text(text=["text", "spam"])`
1. Ignore case can be combined with any previous listed filter: `#!python3 Text(text="Text", text_ignore_case=True) # value.lower() == 'text'.lower()`
## Allowed handlers
Allowed update types for this filter:
- `message`
- `edited_message`
- `channel_post`
- `edited_channel_post`
- `inline_query`
- `callback_query`

38
docs/dispatcher/filters/text.rst Normal file
View file

@ -0,0 +1,38 @@
====
Text
====
.. autoclass:: aiogram.dispatcher.filters.text.Text
:members:
:member-order: bysource
:undoc-members: False
Can be imported:
- :code:`from aiogram.dispatcher.filters.text import Text`
- :code:`from aiogram.dispatcher.filters import Text`
- :code:`from aiogram.filters import Text`
Or used from filters factory by passing corresponding arguments to handler registration line
Usage
=====
#. Text equals with the specified value: :code:`Text(text="text") # value == 'text'`
#. Text starts with the specified value: :code:`Text(text_startswith="text") # value.startswith('text')`
#. Text ends with the specified value: :code:`Text(text_endswith="text") # value.endswith('text')`
#. Text contains the specified value: :code:`Text(text_contains="text") # value in 'text'`
#. Any of previous listed filters can be list, set or tuple of strings that's mean any of listed value should be equals/startswith/endswith/contains: :code:`Text(text=["text", "spam"])`
#. Ignore case can be combined with any previous listed filter: :code:`Text(text="Text", text_ignore_case=True) # value.lower() == 'text'.lower()`
Allowed handlers
================
Allowed update types for this filter:
- :code:`message`
- :code:`edited_message`
- :code:`channel_post`
- :code:`edited_channel_post`
- :code:`inline_query`
- :code:`callback_query`