Туториал (#8)

* Начало туториала * Ещё чуть туториала * Туториал по методам, фильтрам, мидлварям, fsm и di * Туториал доделан Переименовал файлы доки в cebab-case, указал конкретные members в автогенерации * Изменения pre-commit хука * Проверка на корректность документации и туториала, небольшие правки + изменение цветы главных заголовков. --------- Co-authored-by: Erkut <ZloyBarcyk@yandex.ru>
K1rL3s · Feb 1, 2024 · 408eaeb · 408eaeb
1 parent d2816c8
commit 408eaeb
Show file tree

Hide file tree

Showing 173 changed files with 1,760 additions and 401 deletions.
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@
 - Роутеры (Blueprints)
 - Машина состояний (Finite State Machine)
 - Мидлвари (для входящих событий и вызовов API)
-- Использует мощные [магические фильтры](https://github.com/aiogram/magic-filter)
+- Мощные [магические фильтры](https://github.com/aiogram/magic-filter)
 
 
 ### Важно!

diff --git a/aliceio/types/directives.py b/aliceio/types/directives.py
@@ -13,7 +13,7 @@ class Directives(MutableAliceObject):
     Директивы.
 
     [Source 1](https://yandex.ru/dev/dialogs/alice/doc/response-audio-player.html)
-    [Source 2](https://yandex.ru/dev/dialogs/alice/doc/response-start-account-linking.html_
+    [Source 2](https://yandex.ru/dev/dialogs/alice/doc/response-start-account-linking.html)
     """  # noqa: E501
 
     audio_player: Optional[AudioPlayerDirective] = None

diff --git a/aliceio/types/media_button.py b/aliceio/types/media_button.py
@@ -6,7 +6,7 @@
 
 class MediaButton(MutableAliceObject):
     """
-    Кнопка на изображении для :class:`ImageGallery` и :class:[`ItemsList`]
+    Кнопка на изображении для :class:`ImageGallery` и :class:`ItemsList`
 
     [Source 1](https://yandex.ru/dev/dialogs/alice/doc/response-card-imagegallery.html#response-card-imagegallery__items-button-desc)
     [Source 2](https://yandex.ru/dev/dialogs/alice/doc/response-card-itemslist.html#response-card-itemslist__items-button-desc)

diff --git a/aliceio/types/space_status.py b/aliceio/types/space_status.py
@@ -8,7 +8,7 @@ class SpaceStatus(AliceObject):
     """
     Оставшееся место в байтах для изображений и звуков.
 
-    [Source]https://yandex.ru/dev/dialogs/alice/doc/resource-upload.html#http-images-load__quota
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/resource-upload.html#http-images-load__quota)
     """  # noqa: E501
 
     images: PreQuota

diff --git a/aliceio/types/uploaded_image.py b/aliceio/types/uploaded_image.py
@@ -15,14 +15,14 @@ class UploadedImage(AliceObject):
     """  # noqa: E501
 
     id: str
+    size: int
     origUrl: Optional[str] = None
     # origUrl будет None если изображение загружено через файл, то есть не через url.
-    size: int
     createdAt: str
 
     if TYPE_CHECKING:
         orig_url: ClassVar[Optional[str]]
-        created_at: ClassVar[Optional[str]]
+        created_at: ClassVar[str]
 
         def __init__(
             __pydantic_self__,

diff --git a/docs/_css/style.css b/docs/_css/style.css
@@ -67,6 +67,10 @@ html {
   }
 }
 
+.md-nav__item--section>.md-nav>.md-nav__list>.md-nav__item>.md-nav__link{
+  color: var(--md-typeset-a-color) !important;
+}
+
 @media screen and (max-width:76.1875em) {
   [data-md-color-scheme="slate"] .md-nav--primary .md-nav__title {
     background-color: var(--vkbottle-bg-darker);
@@ -92,3 +96,10 @@ html {
 .injected {
   display: none;
 }
+
+.md-typeset h1 {
+    color: var(--md-default-fg-color--light);
+    font-size: 2em;
+    line-height: 1.3;
+    margin: 1em 0 0.5em
+}
diff --git a/docs/_static/middleware_dark.png b/docs/_static/middleware_dark.png
diff --git a/docs/_static/middleware_light.png b/docs/_static/middleware_light.png
diff --git a/docs/client/alice.md → docs/aliceio/client/alice.md b/docs/client/alice.md → docs/aliceio/client/alice.md
diff --git a/docs/client/context_controller.md → docs/aliceio/client/context-controller.md b/docs/client/context_controller.md → docs/aliceio/client/context-controller.md
diff --git a/docs/client/session/aiohttp.md → docs/aliceio/client/session/aiohttp.md b/docs/client/session/aiohttp.md → docs/aliceio/client/session/aiohttp.md
diff --git a/docs/client/session/base.md → docs/aliceio/client/session/base.md b/docs/client/session/base.md → docs/aliceio/client/session/base.md
diff --git a/docs/client/session/middlewares/base.md → ...liceio/client/session/middlewares/base.md b/docs/client/session/middlewares/base.md → ...liceio/client/session/middlewares/base.md
diff --git a/docs/client/session/middlewares/manager.md → ...eio/client/session/middlewares/manager.md b/docs/client/session/middlewares/manager.md → ...eio/client/session/middlewares/manager.md
diff --git a/...nt/session/middlewares/request_logging.md → ...nt/session/middlewares/request-logging.md b/...nt/session/middlewares/request_logging.md → ...nt/session/middlewares/request-logging.md
diff --git a/docs/aliceio/client/skill.md b/docs/aliceio/client/skill.md
@@ -0,0 +1,17 @@
+::: aliceio.client.skill.Skill
+    handler: python
+    options:
+      members:
+        - id
+        - skill_id
+        - token
+        - oauth_token
+        - __init__
+        - __call__
+        - context
+        - upload_image
+        - get_images
+        - delete_image
+        - upload_sound
+        - get_sounds
+        - delete_sound
diff --git a/docs/dispatcher/dispatcher.md → docs/aliceio/dispatcher/dispatcher.md b/docs/dispatcher/dispatcher.md → docs/aliceio/dispatcher/dispatcher.md
diff --git a/docs/dispatcher/event/alice.md → docs/aliceio/dispatcher/event/alice.md b/docs/dispatcher/event/alice.md → docs/aliceio/dispatcher/event/alice.md
diff --git a/docs/dispatcher/event/bases.md → docs/aliceio/dispatcher/event/bases.md b/docs/dispatcher/event/bases.md → docs/aliceio/dispatcher/event/bases.md
diff --git a/docs/dispatcher/event/event.md → docs/aliceio/dispatcher/event/event.md b/docs/dispatcher/event/event.md → docs/aliceio/dispatcher/event/event.md
diff --git a/docs/dispatcher/event/handler.md → docs/aliceio/dispatcher/event/handler.md b/docs/dispatcher/event/handler.md → docs/aliceio/dispatcher/event/handler.md
diff --git a/docs/dispatcher/flags.md → docs/aliceio/dispatcher/flags.md b/docs/dispatcher/flags.md → docs/aliceio/dispatcher/flags.md
@@ -47,3 +47,8 @@
     handler: python
     options:
       members: true
+
+
+## Источники
+
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/flags.html)
diff --git a/docs/dispatcher/middlewares/base.md → docs/aliceio/dispatcher/middlewares/base.md b/docs/dispatcher/middlewares/base.md → docs/aliceio/dispatcher/middlewares/base.md
@@ -3,4 +3,3 @@
     options:
       merge_init_into_class: true
       members: true
-
diff --git a/docs/dispatcher/middlewares/error.md → docs/aliceio/dispatcher/middlewares/error.md b/docs/dispatcher/middlewares/error.md → docs/aliceio/dispatcher/middlewares/error.md
diff --git a/docs/dispatcher/middlewares/manager.md → ...aliceio/dispatcher/middlewares/manager.md b/docs/dispatcher/middlewares/manager.md → ...aliceio/dispatcher/middlewares/manager.md
diff --git a/...ispatcher/middlewares/response_convert.md → ...ispatcher/middlewares/response-convert.md b/...ispatcher/middlewares/response_convert.md → ...ispatcher/middlewares/response-convert.md
@@ -1,4 +1,4 @@
-::: aliceio.dispatcher.middlewares.response_convert
+::: aliceio.dispatcher.middlewares.response_convert.ResponseConvertMiddleware
     handler: python
     options:
       members:

diff --git a/docs/dispatcher/middlewares/user_context.md → ...io/dispatcher/middlewares/user-context.md b/docs/dispatcher/middlewares/user_context.md → ...io/dispatcher/middlewares/user-context.md
diff --git a/docs/aliceio/dispatcher/router.md b/docs/aliceio/dispatcher/router.md
@@ -0,0 +1,77 @@
+::: aliceio.dispatcher.router.Router
+    handler: python
+    options:
+      merge_init_into_class: false
+      members:
+        - __init__
+        - include_router
+        - include_routers
+
+
+## Наблюдатели
+
+!!! warning "Важно"
+    Все хэндлеры всегда должны быть асинхронными. Имя функции-обработчика не имеет значения.
+    Имя аргумента события также не важно, но рекомендуется не перекрывать имя контекстными данными, поскольку функция не может принимать два аргумента с одинаковым именем.
+
+Вот список всех доступных наблюдателей и примеры регистрации хэндлеров.
+
+В этих примерах используется только регистрация через декоратор, но вы всегда можете использовать метод `<router>.<event_type>.register(...)`
+
+### Сообщение (SimpleUtterance)
+```python
+@router.message()
+async def message_handler(message: Message) -> Any: pass
+```
+
+### Нажатие на кнопку
+```python
+@router.button_pressed()
+async def button_pressed_handler(button: ButtonPressed) -> Any: pass
+```
+
+### Аудиоплеер
+```python
+@router.audio_player()
+async def audio_player_handler(audio_player: AudioPlayer) -> Any: pass
+```
+
+
+### Покупка
+```python
+@router.purchase()
+async def purchase_handler(purchase: Purchase) -> Any: pass
+```
+
+### Показ шоу
+```python
+@router.show_pull()
+async def show_pull_handler(pull: ShowPull) -> Any: pass
+```
+
+## Вложенные роутеры
+
+Событие будет распространять по роутерам и хэндлерам согласно порядку их добавления.
+
+!!! warning "Важно"
+    Роутеры могут быть включены в другие роутеры с некоторыми ограничениями:
+
+    1. Роутер не может подключить сам себя
+    2. Роутеры не могут составлять цикл (р1 содержит р2, р2 содержит р3, р3 содерит р1)
+
+## Update
+```python
+@dispatcher.update()
+async def update_handler(update: Update) -> Any: pass
+```
+
+!!! warning "Предупреждение"
+    Только диспетчер может обрабатывать события с типом `Update`.
+
+!!! note "Примечание"
+    В диспетчере уже есть обработчик этого типа событий, поэтому вы можете использовать его для обработки всех обновлений, которые не обработались другими хэндлерами.
+
+
+## Источники
+
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/router.html)
diff --git a/docs/enums/all_enums.md → docs/aliceio/enums/all-enums.md b/docs/enums/all_enums.md → docs/aliceio/enums/all-enums.md
@@ -3,14 +3,16 @@
 ::: aliceio.enums.base.ValuesEnum
     handler: python
     options:
-      members: true
+      members:
+        - values
 
 <br/>
 
 ::: aliceio.enums.base.StrEnum
     handler: python
     options:
-      members: true
+      members:
+        - __str__
 
 <br/>
 

diff --git a/docs/filters/base.md → docs/aliceio/filters/base.md b/docs/filters/base.md → docs/aliceio/filters/base.md
diff --git a/docs/filters/exception.md → docs/aliceio/filters/exception.md b/docs/filters/exception.md → docs/aliceio/filters/exception.md
diff --git a/docs/filters/logic.md → docs/aliceio/filters/logic.md b/docs/filters/logic.md → docs/aliceio/filters/logic.md
diff --git a/docs/filters/magic_data.md → docs/aliceio/filters/magic-data.md b/docs/filters/magic_data.md → docs/aliceio/filters/magic-data.md
diff --git a/docs/aliceio/filters/magic-filter.md b/docs/aliceio/filters/magic-filter.md
@@ -0,0 +1,86 @@
+# Магический фильтр
+
+!!! note "Примечание"
+    В aliceio есть небольшая надстройка над магическим фильтром.
+    Если импортировать его из [magic-filter](https://pypi.org/project/magic-filter/), то метод `.as_()` не будет доступен (о нём в главе про DI).
+
+`MagicFilter` можно вызвать как функцию, он поддерживает некоторые действия и запоминает цепочку атрибутов и действий, которые следует проверить.
+
+Это означает, что вы можете связать методы получения атрибутов в цепочку, описать простые проверки данных, а затем вызвать полученный объект, передав один объект в качестве аргумента.
+Например, можно создать цепочку атрибутов `F.foo.bar.baz`, затем добавить действие `F.foo.bar.baz == 'spam'`, а затем вызвать полученный объект `(F.foo.bar.baz == 'spam').resolve(obj)`
+
+### Возможные действия
+
+Магический фильтр поддерживает некоторые логические операции над атрбитуами объекта.
+
+#### Существует ли
+```python
+F.text  # эквивалент `lambda message: message.text`
+```
+
+#### Входит ли в коллекцию
+```python
+F.from_user.id.in_({42, 1000, 123123})  # lambda event: event.from_user.id in {42, 1000, 123123}
+F.event_type.in_({'foo', 'bar', 'baz'})  # lambda update: update.event_type in {'foo', 'bar', 'baz'}
+```
+
+#### Содержит ли
+```python
+F.text.contains('foo')  # lambda message: 'foo' in message.text
+```
+
+#### Regexp
+```python
+F.text.regexp(r'Hello, .+')  # lambda message: re.match(r'Hello, .+', message.text)
+```
+
+#### Свои функции
+
+Принимает любой вызываемый объект. Объект будет вызван когда фильтр проверяет результат.
+```python
+F.chat.func(lambda chat: chat.id == -42)  # lambda message: (lambda chat: chat.id == -42)(message.chat)
+```
+
+#### Инверсия
+Любая доступная операция может быть инвертирована с помощью оператора `~`
+```python
+~(F.text == 'spam')  # lambda message: message.text != 'spam'
+~F.text.startswith('spam')  # lambda message: not message.text.startswith('spam')
+```
+
+#### Комбинация
+Все операции могут быть скомбинированы с помощью `&`и `|`
+```python
+(F.from_user.id == 42) & (F.text == 'admin')
+F.text.startswith('a') | F.text.endswith('b')
+(F.from_user.id.in_({42, 777, 911})) & (F.text.startswith('!') | F.text.startswith('/')) & F.text.contains('ban')
+```
+
+#### Строковые методы
+Могут быть использованы только с строковыми атрибутами
+```python
+F.text.startswith('foo')  # lambda message: message.text.startswith('foo')
+F.text.endswith('bar')  # lambda message: message.text.startswith('bar')
+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
+```
+
+### Использование в aliceio
+```python
+@router.message(F.text == "привет")
+@router.button_pressed(F.payload["yes"])
+...
+```
+
+::: aliceio.utils.magic_filter.MagicFilter
+    handler: python
+    options:
+      members: true
+
+<br/>
+
+::: aliceio.utils.magic_filter.AsFilterResultOperation
+    handler: python
+    options:
+      members: true
diff --git a/docs/filters/state.md → docs/aliceio/filters/state.md b/docs/filters/state.md → docs/aliceio/filters/state.md
diff --git a/docs/fsm/context.md → docs/aliceio/fsm/context.md b/docs/fsm/context.md → docs/aliceio/fsm/context.md
diff --git a/docs/fsm/middlewares/api_storage.md → docs/aliceio/fsm/middlewares/api-storage.md b/docs/fsm/middlewares/api_storage.md → docs/aliceio/fsm/middlewares/api-storage.md
diff --git a/docs/fsm/middlewares/fsm_context.md → docs/aliceio/fsm/middlewares/fsm-context.md b/docs/fsm/middlewares/fsm_context.md → docs/aliceio/fsm/middlewares/fsm-context.md
diff --git a/docs/fsm/state.md → docs/aliceio/fsm/state.md b/docs/fsm/state.md → docs/aliceio/fsm/state.md
diff --git a/docs/fsm/storage/api.md → docs/aliceio/fsm/storage/api.md b/docs/fsm/storage/api.md → docs/aliceio/fsm/storage/api.md
diff --git a/docs/fsm/storage/base.md → docs/aliceio/fsm/storage/base.md b/docs/fsm/storage/base.md → docs/aliceio/fsm/storage/base.md
diff --git a/docs/fsm/storage/memory.md → docs/aliceio/fsm/storage/memory.md b/docs/fsm/storage/memory.md → docs/aliceio/fsm/storage/memory.md
diff --git a/.../fsm/storage/redis/default_key_builder.md → .../fsm/storage/redis/default-key-builder.md b/.../fsm/storage/redis/default_key_builder.md → .../fsm/storage/redis/default-key-builder.md
diff --git a/docs/fsm/storage/redis/key_builder.md → .../aliceio/fsm/storage/redis/key-builder.md b/docs/fsm/storage/redis/key_builder.md → .../aliceio/fsm/storage/redis/key-builder.md
diff --git a/docs/fsm/storage/redis/redis.md → docs/aliceio/fsm/storage/redis/redis.md b/docs/fsm/storage/redis/redis.md → docs/aliceio/fsm/storage/redis/redis.md
diff --git a/docs/fsm/strategy.md → docs/aliceio/fsm/strategy.md b/docs/fsm/strategy.md → docs/aliceio/fsm/strategy.md
diff --git a/docs/handlers/audio_player.md → docs/aliceio/handlers/audio-player.md b/docs/handlers/audio_player.md → docs/aliceio/handlers/audio-player.md
diff --git a/docs/handlers/base.md → docs/aliceio/handlers/base.md b/docs/handlers/base.md → docs/aliceio/handlers/base.md
diff --git a/docs/handlers/button_pressed.md → docs/aliceio/handlers/button-pressed.md b/docs/handlers/button_pressed.md → docs/aliceio/handlers/button-pressed.md
diff --git a/docs/handlers/error.md → docs/aliceio/handlers/error.md b/docs/handlers/error.md → docs/aliceio/handlers/error.md
diff --git a/docs/handlers/message.md → docs/aliceio/handlers/message.md b/docs/handlers/message.md → docs/aliceio/handlers/message.md
diff --git a/docs/handlers/purchase.md → docs/aliceio/handlers/purchase.md b/docs/handlers/purchase.md → docs/aliceio/handlers/purchase.md
diff --git a/docs/handlers/show_pull.md → docs/aliceio/handlers/show-pull.md b/docs/handlers/show_pull.md → docs/aliceio/handlers/show-pull.md
diff --git a/docs/handlers/timeout.md → docs/aliceio/handlers/timeout.md b/docs/handlers/timeout.md → docs/aliceio/handlers/timeout.md
diff --git a/docs/methods/base.md → docs/aliceio/methods/base.md b/docs/methods/base.md → docs/aliceio/methods/base.md
diff --git a/docs/methods/images/delete_image.md → docs/aliceio/methods/images/delete-image.md b/docs/methods/images/delete_image.md → docs/aliceio/methods/images/delete-image.md
diff --git a/docs/methods/images/get_images.md → docs/aliceio/methods/images/get-images.md b/docs/methods/images/get_images.md → docs/aliceio/methods/images/get-images.md
diff --git a/docs/methods/images/upload_image.md → docs/aliceio/methods/images/upload-image.md b/docs/methods/images/upload_image.md → docs/aliceio/methods/images/upload-image.md
diff --git a/docs/methods/sounds/delete_sound.md → docs/aliceio/methods/sounds/delete-sound.md b/docs/methods/sounds/delete_sound.md → docs/aliceio/methods/sounds/delete-sound.md
diff --git a/docs/methods/sounds/get_sounds.md → docs/aliceio/methods/sounds/get-sounds.md b/docs/methods/sounds/get_sounds.md → docs/aliceio/methods/sounds/get-sounds.md
diff --git a/docs/methods/sounds/upload_sound.md → docs/aliceio/methods/sounds/upload-sound.md b/docs/methods/sounds/upload_sound.md → docs/aliceio/methods/sounds/upload-sound.md
diff --git a/docs/methods/status.md → docs/aliceio/methods/status.md b/docs/methods/status.md → docs/aliceio/methods/status.md
diff --git a/docs/types/alice_event.md → docs/aliceio/types/alice-event.md b/docs/types/alice_event.md → docs/aliceio/types/alice-event.md
@@ -1,4 +1,7 @@
 ::: aliceio.types.alice_event.AliceEvent
     handler: python
     options:
-      members: true
+      members:
+        - user
+        - from_user
+        - session
diff --git a/docs/aliceio/types/alice-request.md b/docs/aliceio/types/alice-request.md
@@ -0,0 +1,19 @@
+::: aliceio.types.alice_request.AliceRequest
+    handler: python
+    options:
+      members:
+        - type
+        - payload
+        - command
+        - original_utterance
+        - markup
+        - nlu
+        - error
+        - purchase_request_id
+        - purchase_token
+        - order_id
+        - purchase_timestamp
+        - purchase_payload
+        - signed_data
+        - signature
+        - show_type
diff --git a/docs/aliceio/types/alice-response.md b/docs/aliceio/types/alice-response.md
@@ -0,0 +1,10 @@
+::: aliceio.types.alice_response.AliceResponse
+    handler: python
+    options:
+      members:
+        - response
+        - session_state
+        - user_state_update
+        - application_state
+        - analytics
+        - version
diff --git a/docs/types/analytic_event.md → docs/aliceio/types/analytic-event.md b/docs/types/analytic_event.md → docs/aliceio/types/analytic-event.md
@@ -1,4 +1,6 @@
 ::: aliceio.types.analytic_event.AnalyticEvent
     handler: python
     options:
-      members: true
+      members:
+        - name
+        - value
diff --git a/docs/types/analytics.md → docs/aliceio/types/analytics.md b/docs/types/analytics.md → docs/aliceio/types/analytics.md
@@ -1,4 +1,5 @@
 ::: aliceio.types.analytics.Analytics
     handler: python
     options:
-      members: true
+      members:
+        - events
diff --git a/docs/types/api_state.md → docs/aliceio/types/api-state.md b/docs/types/api_state.md → docs/aliceio/types/api-state.md
@@ -12,4 +12,7 @@ ApplicationState = StateDict
 ::: aliceio.types.api_state.ApiState
     handler: python
     options:
-      members: true
+      members:
+        - user
+        - session
+        - application
diff --git a/docs/types/application.md → docs/aliceio/types/application.md b/docs/types/application.md → docs/aliceio/types/application.md
@@ -1,4 +1,5 @@
 ::: aliceio.types.application.Application
     handler: python
     options:
-      members: true
+      members:
+        - application_id
diff --git a/docs/types/audio_player_directive.md → docs/aliceio/types/audio-player-directive.md b/docs/types/audio_player_directive.md → docs/aliceio/types/audio-player-directive.md
@@ -1,7 +1,9 @@
 ::: aliceio.types.audio_player_directive.AudioPlayerDirective
     handler: python
     options:
-      members: true
+      members:
+        - action
+        - item
 
 <br/>
 

diff --git a/docs/types/audio_player_error.md → docs/aliceio/types/audio-player-error.md b/docs/types/audio_player_error.md → docs/aliceio/types/audio-player-error.md
@@ -1,4 +1,6 @@
 ::: aliceio.types.audio_player_error.AudioPlayerError
     handler: python
     options:
-      members: true
+      members:
+        - message
+        - type
diff --git a/docs/types/audio_player_item.md → docs/aliceio/types/audio-player-item.md b/docs/types/audio_player_item.md → docs/aliceio/types/audio-player-item.md
@@ -1,4 +1,6 @@
 ::: aliceio.types.audio_player_item.AudioPlayerItem
     handler: python
     options:
-      members: true
+      members:
+        - stream
+        - metadata