Больше примеров (#11)

* Теперь все гиперссылки открываются с новой вкладки браузера * Добавил главу про роутеры в туториал Убрал oauth_token из тех примеров, где он не нужен Добавил примеры кода в главу про методы Алисы * Подправил ссылки в доке и реадме * Пример навыка купи слона * Ещё один пример работы с FSM --------- Co-authored-by: Erkut <[email protected]>
K1rL3s · Feb 4, 2024 · 68f2f81 · 68f2f81
1 parent 75b1aaf
commit 68f2f81
Show file tree

Hide file tree

Showing 44 changed files with 471 additions and 165 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -28,7 +28,7 @@ jobs:
       matrix:
         os:
           - ubuntu-latest
-          # - macos-latest  # Открыть после окончания активной разработки, жрёт много минут
+          - macos-latest
           - windows-latest
         python-version:
           - '3.8'
@@ -97,7 +97,7 @@ jobs:
       matrix:
         os:
           - ubuntu-latest
-          # - macos-latest  # Открыть после окончания активной разработки, жрёт много минут
+          - macos-latest
           # - windows-latest
         python-version:
           - 'pypy3.8'

diff --git a/README.md b/README.md
@@ -18,13 +18,13 @@
 <p align="center">
     <b>
         Асинхронный фреймворк для
-        <a href="https://dialogs.yandex.ru/store">навыков Алисы</a>
+        <a target="_blank" href="https://dialogs.yandex.ru/store">навыков Алисы</a>
         из
-        <a href="https://dialogs.yandex.ru/development">Яндекс.Диалогов</a>
+        <a target="_blank" href="https://dialogs.yandex.ru/development">Яндекс.Диалогов</a>
     </b>
 </p>
 <p align="center">
-    Based on <a href="https://github.com/aiogram/aiogram/tree/dev-3.x">aiogram v3</a>
+    Based on <a target="_blank" href="https://github.com/aiogram/aiogram/tree/dev-3.x">aiogram v3</a>
 </p>
 
 ## Особенности
@@ -42,7 +42,9 @@
 Настоятельно рекомендуется иметь опыт работы с [asyncio](https://docs.python.org/3/library/asyncio.html) перед использование **aliceio**
 
 
-## [Быстрый старт](https://aliceio.readthedocs.io/ru/latest/tutorial/skill-settings/)
+## Быстрый старт
+
+Как получить `skill_id` и подключить навык к Алисе можно прочитать <a target="_blank" href="https://aliceio.readthedocs.io/ru/latest/tutorial/start/">тут</a>.
 
 ```python
 from aiohttp import web

diff --git a/aliceio/exceptions.py b/aliceio/exceptions.py
@@ -59,8 +59,8 @@ class AliceWrongFieldError(AliceAPIError):
 
 class ClientDecodeError(AliceioError):
     """
-    Исключение возникает, когда клиент не может декодировать ответ.
-    (Неверный ответ или запрос и тд)
+    Исключение возникает, когда клиент не может декодировать ответ
+    (неверный ответ или запрос и тд).
     """
 
     def __init__(self, message: str, original: Exception, data: Any) -> None:

diff --git a/aliceio/fsm/storage/memory.py b/aliceio/fsm/storage/memory.py
@@ -17,7 +17,7 @@ class MemoryStorage(BaseStorage):
     FSM хранилище по умолчанию,
     хранит все данные в :class:`dict` и теряет всё при выключении.
 
-    Важно!
+    !!! warning "Важно"
         Не рекомендуется использовать в проде,
         так как данные теряются при перезапуске навыка.
     """

diff --git a/aliceio/types/error_result.py b/aliceio/types/error_result.py
@@ -7,8 +7,9 @@ class ErrorResult(AliceObject):
     """
     Сообщение об ошибке при запросах к API Алисы.
 
-    Важно заметить, что если навык вернёт ответ Алисе в некорректном формате, то
-    Алиса никак не оповестит об ошибке.
+    !!! note "Примечание"
+        Если навык вернёт ответ Алисе в некорректном формате, то
+        Алиса никак не оповестит об ошибке.
     """
 
     message: str

diff --git a/docs/aliceio/dispatcher/flags.md b/docs/aliceio/dispatcher/flags.md
@@ -51,4 +51,4 @@
 
 ## Источники
 
-* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/flags.html)
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/flags.html){:target="_blank"}
diff --git a/docs/aliceio/dispatcher/router.md b/docs/aliceio/dispatcher/router.md
@@ -74,4 +74,4 @@ async def update_handler(update: Update) -> Any: pass
 
 ## Источники
 
-* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/router.html)
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/router.html){:target="_blank"}
diff --git a/docs/aliceio/filters/base.md b/docs/aliceio/filters/base.md
@@ -9,6 +9,6 @@
 
 
 ## Примеры
-1. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/filters.py)
-2. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/custom_filter.py)
-3. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/context_addition.py)
+1. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/filters.py){:target="_blank"}
+2. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/custom_filter.py){:target="_blank"}
+3. [Пример](https://github.com/K1rL3s/aliceio/blob/examples/examples/context_addition.py){:target="_blank"}
diff --git a/docs/aliceio/filters/magic-filter.md b/docs/aliceio/filters/magic-filter.md
@@ -2,7 +2,7 @@
 
 !!! note "Примечание"
     В aliceio есть небольшая надстройка над магическим фильтром.
-    Если импортировать его из [magic-filter](https://pypi.org/project/magic-filter/), то метод `.as_()` не будет доступен (о нём в главе про DI).
+    Если импортировать его из [magic-filter](https://pypi.org/project/magic-filter/){:target="_blank"}, то метод `.as_()` не будет доступен (о нём в главе про DI).
 
 `MagicFilter` можно вызвать как функцию, он поддерживает некоторые действия и запоминает цепочку атрибутов и действий, которые следует проверить.
 

diff --git a/docs/aliceio/fsm/storage/base.md b/docs/aliceio/fsm/storage/base.md
@@ -11,4 +11,5 @@
 
 
 ## Примеры
-* [finite_state_machine.py](https://github.com/K1rL3s/aliceio/blob/examples/examples/finite_state_machine.py)
+* [fsm_form](https://github.com/K1rL3s/aliceio/blob/master/examples/fsm_form.py){:target="_blank"}
+* [fsm_games](https://github.com/K1rL3s/aliceio/blob/master/examples/fsm_games.py){:target="_blank"}
diff --git a/docs/aliceio/types/api-state.md b/docs/aliceio/types/api-state.md
@@ -1,4 +1,4 @@
-## [Хранение состояния](https://yandex.ru/dev/dialogs/alice/doc/session-persistence.html)
+## [Хранение состояния](https://yandex.ru/dev/dialogs/alice/doc/session-persistence.html){:target="_blank"}
 
 ```python
 from typing import Any, Dict

diff --git a/docs/aliceio/types/number-entity.md b/docs/aliceio/types/number-entity.md
@@ -1,6 +1,6 @@
 ## NumberEntity
 
-[NLU Entity](https://yandex.ru/dev/dialogs/alice/doc/naming-entities.html#naming-entities__number) Целого или дробного числа.
+[NLU Entity](https://yandex.ru/dev/dialogs/alice/doc/naming-entities.html#naming-entities__number){:target="_blank"} Целого или дробного числа.
 ```python
 from typing import Union
 

diff --git a/docs/aliceio/types/payload.md b/docs/aliceio/types/payload.md
@@ -1,6 +1,6 @@
 ## Payload
 
-Произвольный [JSON-объект](https://yandex.ru/dev/dialogs/alice/doc/request-buttonpressed.html#request-buttonpressed__request-desc), который Яндекс Диалоги должны отправить обработчику, если данная кнопка будет нажата.
+Произвольный [JSON-объект](https://yandex.ru/dev/dialogs/alice/doc/request-buttonpressed.html#request-buttonpressed__request-desc){:target="_blank"}, который Яндекс Диалоги должны отправить обработчику, если данная кнопка будет нажата.
 
 Максимум 4096 байт.
 

diff --git a/docs/aliceio/utils/builders.md b/docs/aliceio/utils/builders.md
@@ -1,8 +1,8 @@
 ## Билдеры
 
-- [`Builder`](builders/builder.md) - Объект клавиатуры.
-- [`ImageGalleryBuilder`](builders/image-gallery-builder.md) - Билдер альбомов.
-- [`ItemsListBuilder`](builders/items-list-builder.md) - Билдер элементов списка.
-- [`TextButtonBuilder`](builders/text-button-builder.md) - Билдер текстовых кнопок.
+- [`Builder`](builders/builder.md){:target="_blank"} - Объект клавиатуры.
+- [`ImageGalleryBuilder`](builders/image-gallery-builder.md){:target="_blank"} - Билдер альбомов.
+- [`ItemsListBuilder`](builders/items-list-builder.md){:target="_blank"} - Билдер элементов списка.
+- [`TextButtonBuilder`](builders/text-button-builder.md){:target="_blank"} - Билдер текстовых кнопок.
 
-### [Примеры](https://github.com/K1rL3s/aliceio/blob/examples/examples/builders.py) использования билдеров
+### [Примеры](https://github.com/K1rL3s/aliceio/blob/master/examples/builders.py){:target="_blank"} использования билдеров
diff --git a/docs/aliceio/webhook/security.md b/docs/aliceio/webhook/security.md
@@ -1,4 +1,4 @@
-[IP-адреса Яндекса](https://yandex.ru/ips)
+[IP-адреса Яндекса](https://yandex.ru/ips){:target="_blank"}
 ```python
 from ipaddress import IPv4Network
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,9 +2,11 @@
 
 Добро пожаловать в документацию AliceIO!
 
-Начинающим рекомендуется ознакомиться с [туториалом](tutorial/index.md). Знание Python'а приветствуется и рекомендуется.
+Начинающим рекомендуется ознакомиться с [туториалом](tutorial/index.md).
+Знание Python'а приветствуется и рекомендуется.
 
-
-> Проект написан с использованием исходного кода [aiogram](https://github.com/aiogram/aiogram/), [vkbottle](https://github.com/vkbottle/vkbottle/) и [aioalice](https://github.com/mahenzon/aioalice)
+> Проект написан с использованием исходного кода [aiogram](https://github.com/aiogram/aiogram/){:target="_blank"},
+> [vkbottle](https://github.com/vkbottle/vkbottle/){:target="_blank"}
+> и [aioalice](https://github.com/mahenzon/aioalice){:target="_blank"}
 >
 > Спасибо авторам и участникам этих замечательных библиотек
diff --git a/docs/tutorial/builders.md b/docs/tutorial/builders.md
@@ -4,4 +4,4 @@
 
 ## Примеры
 
-[builders.py](https://github.com/K1rL3s/aliceio/blob/master/examples/builders.py)
+[builders.py](https://github.com/K1rL3s/aliceio/blob/master/examples/builders.py){:target="_blank"}
diff --git a/docs/tutorial/dependency-injection.md b/docs/tutorial/dependency-injection.md
@@ -2,14 +2,14 @@
 
 DI - это метод программирования, который делает класс независимым от его зависимостей.
 Это достигается путем отделения использования объекта от его создания.
-Это поможет вам следовать принципу инверсии зависимостей [SOLID](https://en.wikipedia.org/wiki/SOLID) и принципу единой ответственности.
+Это поможет вам следовать принципу инверсии зависимостей [SOLID](https://en.wikipedia.org/wiki/SOLID){:target="_blank"} и принципу единой ответственности.
 
 ## Как это работает в aliceio
 
 Для каждого события в `aliceio.dispatcher.dispatcher.Dispatcher` проходит обработка контекстных данных. Фильтры и мидлвари также могут вносить изменения в контекст.
 
 Для доступа к контекстным данным необходимо указать соответствующий ключевой параметр в хэндлере или фильтре.
-Например, чтобы получить `aliceio.fsm.context.FSMContext`, надо сделать так:
+Например, чтобы получить `aliceio.fsm.context.FSMContext`, достаточно сделать так:
 
 ```python
 @router.message(...)
@@ -94,5 +94,5 @@ async def start_handler(message: Message, real_text: str) -> str:
 
 ## Примеры
 
-* [context_addition.py](https://github.com/K1rL3s/aliceio/blob/master/examples/context_addition.py)
-* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/dependency_injection.html)
+* [context_addition.py](https://github.com/K1rL3s/aliceio/blob/master/examples/context_addition.py){:target="_blank"}
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/dependency_injection.html){:target="_blank"}
diff --git a/docs/tutorial/error-handling.md b/docs/tutorial/error-handling.md
@@ -74,4 +74,4 @@ async def error_handler(event: ErrorEvent):
 
 ## Примеры
 
-* [error_handling.py](https://github.com/K1rL3s/aliceio/blob/master/examples/error_handling.py)
+* [error_handling.py](https://github.com/K1rL3s/aliceio/blob/master/examples/error_handling.py){:target="_blank"}
diff --git a/docs/tutorial/faq.md b/docs/tutorial/faq.md
@@ -1,5 +1,5 @@
 # ЧаВо
 
 ## Маруся?
-Разработчики узнали про существование [скиллов Маруси](https://dev.vk.com/ru/guide) только во время написания туториала по aliceio.
+Разработчики узнали про существование [скиллов Маруси](https://dev.vk.com/ru/guide){:target="_blank"} только во время написания туториала по aliceio. \
 Вероятно, есть возможность переделать эту библиотеку для работы с Марусей без значительных затрат по времени :)
diff --git a/docs/tutorial/filters.md b/docs/tutorial/filters.md
@@ -2,10 +2,11 @@
 
 Чтобы не городить сотни if'ов в одном хэндлере, были придуманы фильтры (правила).
 
-Фильтры необходимы для маршрутизации событий конкретным хэндлерам. Поиск обработчика всегда останавливается при прохождении первого соответствующего набора фильтров.
+Фильтры необходимы для маршрутизации событий конкретным хэндлерам. \
+Поиск обработчика всегда останавливается при прохождении первого соответствующего набора фильтров.
 По умолчанию все хэндлеры не имеют фильтров, поэтому все события будут передаваться первому обработчику без фильтров.
 
-Основной и самый удобный фильтр - [магический](https://github.com/aiogram/magic-filter) `F`-фильтр.
+Основной и самый удобный фильтр - [магический](https://github.com/aiogram/magic-filter){:target="_blank"} `F`-фильтр. \
 Пользоваться им крайне легко - просто представьте, что вместо него стоит обрабатываемое событие, и обращайтесь к его атрибутам.
 
 ## Кастомный фильтр
@@ -18,8 +19,8 @@
 * Синхронными функциями (`#!python def my_filter(*args, **kwargs): pass`)
 * Анонимными функциями (`#!python lambda event: True`)
 * Любым awaitable объектом
-* Подклассом [`aliceio.filters.base.Filter`](../aliceio/filters/base.md)
-* Экземпляром [`Магического фильтра`](../aliceio/filters/magic-filter.md)
+* Подклассом [`aliceio.filters.base.Filter`](../aliceio/filters/base.md){:target="_blank"}
+* Экземпляром [`Магического фильтра`](../aliceio/filters/magic-filter.md){:target="_blank"}
 
 И они должны возвращать `bool` или `dict`.
 Если возвращается словарь, полученные данные будут переданы следующим фильтрам и обработчику в качестве ключевых аргументов.
@@ -53,13 +54,15 @@ async def no_message_handler(message: Message) -> str:
 
 ## Магический фильтр
 
-Для начала этот фильтр нужно импортировать из aliceio. Если импортировать его из magic-filter, то метод `.as_()` не будет доступен (о нём в главе про DI и про магический фильтр).
+Для начала этот фильтр нужно импортировать из aliceio. \
+Если импортировать его из magic-filter, то метод `.as_()` не будет доступен
+(о нём в главе про [DI](dependency-injection.md){:target="_blank"} и про [магический фильтр](../aliceio/filters/magic-filter.md){:target="_blank"}).
 
 ```python
 from aliceio import F
 ```
 
-К уже написанным обработчикам создадим ещё два, которые будут реагировать на [нажатия кнопок с payload'ом](https://yandex.ru/dev/dialogs/alice/doc/request-buttonpressed.html):
+К уже написанным обработчикам создадим ещё два, которые будут реагировать на [нажатия кнопок с payload'ом](https://yandex.ru/dev/dialogs/alice/doc/request-buttonpressed.html){:target="_blank"}:
 
 ```python
 # Один и тот же фильтр, но разная запись
@@ -135,6 +138,6 @@ async def any_message_handler(message: ...) -> Response:
 
 ## Примеры
 
-* [filters.py](https://github.com/K1rL3s/aliceio/blob/master/examples/filters.py)
-* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/index.html)
-* [aiogram-magic](https://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/magic_filters.html)
+* [filters.py](https://github.com/K1rL3s/aliceio/blob/master/examples/filters.py){:target="_blank"}
+* [aiogram](https://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/index.html){:target="_blank"}
+* [aiogram-magic](https://docs.aiogram.dev/en/dev-3.x/dispatcher/filters/magic_filters.html){:target="_blank"}