Тутор по флагам и возможность авторизации в навыках (#15)

* Актуализация документации и обновление версий линтеров * Убрал лишний __init__ в тайп-чекинг блоке * Туториал на флаги * Заготовка под авторизацию в навыках * Работоспособная авторизация через навык * Пример работы с встроенными интентами и обновлённые ссылки на официальную документацию * Проверка полей в TYPE_CHECKING'ах(ВСЁ ХОРОШО), поправка полей "session: Session..." для красоты * Pydantic v2.8 --------- Co-authored-by: Erkut <[email protected]>
K1rL3s · Jul 21, 2024 · b6e7dfd · b6e7dfd
1 parent ab3d313
commit b6e7dfd
Show file tree

Hide file tree

Showing 90 changed files with 471 additions and 145 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -66,7 +66,7 @@ jobs:
 
       - name: Lint code
         run: |
-          ruff --output-format=github aliceio examples
+          ruff check --output-format=github aliceio examples
           mypy aliceio
           black --check --diff aliceio tests
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: check-case-conflict

diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@
 </div>
 <p align="center">
     <b>
-        Асинхронный фреймворк, упрощающий разработку
+        Асинхронный фреймворк для разработки
         <a target="_blank" href="https://dialogs.yandex.ru/store">навыков Алисы</a>
         из
         <a target="_blank" href="https://dialogs.yandex.ru/development">Яндекс.Диалогов</a>

diff --git a/aliceio/client/context_controller.py b/aliceio/client/context_controller.py
@@ -10,19 +10,6 @@
 class SkillContextController(BaseModel):
     _skill: Optional["Skill"] = PrivateAttr()
 
-    if TYPE_CHECKING:
-
-        def __init__(
-            __pydantic_self__,
-            *,
-            _skill: Optional["Skill"],
-            **__pydantic_kwargs: Any,
-        ) -> None:
-            super().__init__(
-                _skill=_skill,
-                **__pydantic_kwargs,
-            )
-
     def model_post_init(self, __context: Any) -> None:
         self._skill = __context.get("skill") if __context else None
 

diff --git a/aliceio/client/session/middlewares/manager.py b/aliceio/client/session/middlewares/manager.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from functools import partial
 from typing import Any, Callable, List, Optional, Sequence, Union, cast, overload
 

diff --git a/aliceio/dispatcher/event/alice.py b/aliceio/dispatcher/event/alice.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
 
 from aliceio.dispatcher.event.bases import UNHANDLED, MiddlewareType, SkipHandler
@@ -20,7 +18,7 @@ class AliceEventObserver:
     Он остановит распространение события, когда пройдут фильтры любого обработчика.
     """
 
-    def __init__(self, router: Router, event_name: str) -> None:
+    def __init__(self, router: "Router", event_name: str) -> None:
         self.router = router
         self.event_name = event_name
 

diff --git a/aliceio/dispatcher/event/bases.py b/aliceio/dispatcher/event/bases.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import Any, Awaitable, Callable, Dict, NoReturn, Optional, TypeVar, Union
 from unittest.mock import sentinel
 

diff --git a/aliceio/dispatcher/event/event.py b/aliceio/dispatcher/event/event.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import Any, Callable, List
 
 from .handler import CallbackType, HandlerObject

diff --git a/aliceio/dispatcher/middlewares/error.py b/aliceio/dispatcher/middlewares/error.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict
 
 from aliceio.dispatcher.event.bases import UNHANDLED, CancelHandler, SkipHandler
@@ -12,7 +10,7 @@
 
 
 class ErrorsMiddleware(BaseMiddleware[Update]):
-    def __init__(self, router: Router) -> None:
+    def __init__(self, router: "Router") -> None:
         self.router = router
 
     async def __call__(

diff --git a/aliceio/dispatcher/router.py b/aliceio/dispatcher/router.py
@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Final, Generator, List, Optional
+from typing import Any, Dict, Final, FrozenSet, Generator, List, Optional
 
 from ..enums import EventType
 from ..types.base import AliceObject
 from .event.alice import AliceEventObserver
 from .event.bases import REJECTED, UNHANDLED
 from .event.event import EventObserver
 
-INTERNAL_UPDATE_TYPES: Final[frozenset[str]] = frozenset({"update", "error", "timeout"})
+INTERNAL_UPDATE_TYPES: Final[FrozenSet[str]] = frozenset({"update", "error", "timeout"})
 
 
 class Router:
@@ -43,6 +43,10 @@ def __init__(self, *, name: Optional[str] = None) -> None:
             router=self,
             event_name=EventType.AUDIO_PLAYER,
         )
+        self.account_linking_complete = AliceEventObserver(
+            router=self,
+            event_name=EventType.ACCOUNT_LINKING_COMPLETE,
+        )
         self.errors = self.error = AliceEventObserver(
             router=self,
             event_name=EventType.ERROR,
@@ -58,6 +62,7 @@ def __init__(self, *, name: Optional[str] = None) -> None:
             EventType.PURCHASE: self.purchase,
             EventType.SHOW_PULL: self.show_pull,
             EventType.AUDIO_PLAYER: self.audio_player,
+            EventType.ACCOUNT_LINKING_COMPLETE: self.account_linking_complete,
             EventType.ERROR: self.errors,
             EventType.TIMEOUT: self.timeout,
         }

diff --git a/aliceio/enums/update.py b/aliceio/enums/update.py
@@ -8,6 +8,7 @@ class EventType(StrEnum, ValuesEnum):
     MESSAGE = "message"
     SHOW_PULL = "show_pull"
     PURCHASE = "purchase"
+    ACCOUNT_LINKING_COMPLETE = "account_linking_complete_event"
     UPDATE = "update"
     TIMEOUT = "timeout"
 
@@ -22,6 +23,7 @@ class RequestType(StrEnum, ValuesEnum):
     PURCHASE_CONFIRMATION = "Purchase.Confirmation"
     SHOW_PULL = "Show.Pull"
     SIMPLE_UTTERANCE = "SimpleUtterance"
+    ACCOUNT_LINKING_COMPLETE = "AccountLinkigCompleteEvent"  # Нужен ли?
 
 
 class ShowType(StrEnum, ValuesEnum):

diff --git a/aliceio/fsm/middlewares/api_storage.py b/aliceio/fsm/middlewares/api_storage.py
@@ -14,7 +14,7 @@ class FSMApiStorageMiddleware(BaseMiddleware[Update]):
 
     Регистрируется только тогда, когда установлен флаг при создании диспетчера.
 
-    https://yandex.ru/dev/dialogs/alice/doc/session-persistence.html
+    https://yandex.ru/dev/dialogs/alice/doc/ru/session-persistence
     """
 
     def __init__(self, strategy: FSMStrategy = FSMStrategy.USER) -> None:

diff --git a/aliceio/handlers/__init__.py b/aliceio/handlers/__init__.py
@@ -1,3 +1,4 @@
+from .account_linking_complete import AccountLinkingCompleteHandler
 from .audio_player import AudioPlayerHandler
 from .base import BaseHandler, BaseHandlerMixin
 from .button_pressed import ButtonPressedHandler
@@ -8,6 +9,7 @@
 from .timeout import TimeoutHandler
 
 __all__ = (
+    "AccountLinkingCompleteHandler",
     "AudioPlayerHandler",
     "BaseHandler",
     "BaseHandlerMixin",

diff --git a/aliceio/handlers/account_linking_complete.py b/aliceio/handlers/account_linking_complete.py
@@ -0,0 +1,9 @@
+from abc import ABC
+
+from aliceio.handlers.base import BaseHandler
+from aliceio.types import AccountLinkingComplete
+
+
+# TODO: узнать, передаётся ли поле request (и с чем) при подтверждении авторизации
+class AccountLinkingCompleteHandler(BaseHandler[AccountLinkingComplete], ABC):
+    """Базовый класс для обработчиков успешной авторизации пользоватя."""
diff --git a/aliceio/handlers/base.py b/aliceio/handlers/base.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Dict, Generic, TypeVar, cast
 
@@ -21,11 +19,11 @@ class BaseHandler(BaseHandlerMixin[T], ABC):
     """Базовый класс для всех class-based обработчиков."""
 
     def __init__(self, event: T, **kwargs: Any) -> None:
-        self.event: T = event
+        self.event = event
         self.data: Dict[str, Any] = kwargs
 
     @property
-    def skill(self) -> Skill:
+    def skill(self) -> "Skill":
         from aliceio import Skill
 
         if "skill" in self.data:

diff --git a/aliceio/methods/base.py b/aliceio/methods/base.py
@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, ClassVar, Generator, Generic, Optional, TypeVar
 
@@ -48,7 +46,7 @@ def __http_method__(self) -> str:
     def api_url(self, api_server: AliceAPIServer) -> str:
         pass
 
-    async def emit(self, skill: Skill) -> AliceType:
+    async def emit(self, skill: "Skill") -> AliceType:
         if not self._skill:
             self._skill = self.skill
         return await skill(self)

diff --git a/aliceio/methods/images/delete_image.py b/aliceio/methods/images/delete_image.py
@@ -29,7 +29,7 @@ def __init__(
             )
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.delete_file_url(
             skill_id=skill.id,
             file_type=FileType.IMAGES,

diff --git a/aliceio/methods/images/get_images.py b/aliceio/methods/images/get_images.py
@@ -14,7 +14,7 @@ class GetImages(AliceMethod[UploadedImagesList]):
     __http_method__ = HttpMethod.GET
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.get_all_files_url(
             skill_id=skill.id,
             file_type=FileType.IMAGES,

diff --git a/aliceio/methods/images/upload_image.py b/aliceio/methods/images/upload_image.py
@@ -41,7 +41,7 @@ def model_post_init(self, __context: Any) -> None:
             raise AliceWrongFieldError('"file" and "url" cannot be specified together')
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.upload_file_url(
             skill_id=skill.id,
             file_type=FileType.IMAGES,

diff --git a/aliceio/methods/sounds/delete_sound.py b/aliceio/methods/sounds/delete_sound.py
@@ -29,7 +29,7 @@ def __init__(
             )
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.delete_file_url(
             skill_id=skill.id,
             file_type=FileType.SOUNDS,

diff --git a/aliceio/methods/sounds/get_sounds.py b/aliceio/methods/sounds/get_sounds.py
@@ -14,7 +14,7 @@ class GetSounds(AliceMethod[UploadedSoundsList]):
     __http_method__ = HttpMethod.GET
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.get_all_files_url(
             skill_id=skill.id,
             file_type=FileType.SOUNDS,

diff --git a/aliceio/methods/sounds/upload_sound.py b/aliceio/methods/sounds/upload_sound.py
@@ -29,7 +29,7 @@ def __init__(
             )
 
     def api_url(self, api_server: AliceAPIServer) -> str:
-        skill: "Skill" = cast("Skill", self.skill)
+        skill: Skill = cast("Skill", self.skill)
         return api_server.upload_file_url(
             skill_id=skill.id,
             file_type=FileType.SOUNDS,

diff --git a/aliceio/types/__init__.py b/aliceio/types/__init__.py
@@ -1,3 +1,4 @@
+from .account_linking_complete import AccountLinkingComplete
 from .alice_request import AliceRequest
 from .alice_response import AliceResponse
 from .analytic_event import AnalyticEvent
@@ -54,6 +55,7 @@
 from .user import User
 
 __all__ = (
+    "AccountLinkingComplete",
     "AliceRequest",
     "AliceResponse",
     "AnalyticEvent",

diff --git a/aliceio/types/account_linking_complete.py b/aliceio/types/account_linking_complete.py
@@ -0,0 +1,21 @@
+from typing import TYPE_CHECKING, Any
+
+from .base import MutableAliceObject
+
+
+class AccountLinkingComplete(MutableAliceObject):
+    """
+    Успешная авторизация пользователя в навыке.
+
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/auth/make-skill#authorization-complete)
+    """
+
+    if TYPE_CHECKING:
+
+        def __init__(
+            __pydantic_self__,
+            **__pydantic_kwargs: Any,
+        ) -> None:
+            super().__init__(
+                **__pydantic_kwargs,
+            )
diff --git a/aliceio/types/alice_request.py b/aliceio/types/alice_request.py
@@ -11,7 +11,7 @@ class AliceRequest(AliceObject):
     """
     Запрос с информацией от пользователя от API Алисы.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/request.html#request__request-desc)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/request#request-desc)
     """
 
     type: str
@@ -22,11 +22,11 @@ class AliceRequest(AliceObject):
     nlu: Optional[NLU] = None
 
     # Ошибка в аудиоплеере
-    # https://yandex.ru/dev/dialogs/alice/doc/request-audioplayer.html
+    # https://yandex.ru/dev/dialogs/alice/doc/ru/request-audioplayer
     error: Optional[AudioPlayerError] = None
 
     # not null при type == RequestType.PURCHASE_CONFIRMATION
-    # https://yandex.ru/dev/dialogs/alice/doc/request-purchase-confirmation.html
+    # https://yandex.ru/dev/dialogs/alice/doc/ru/request-purchase-confirmation
     purchase_request_id: Optional[str] = None
     purchase_token: Optional[str] = None
     order_id: Optional[str] = None
@@ -36,7 +36,7 @@ class AliceRequest(AliceObject):
     signature: Optional[str] = None
 
     # not null при запуске утреннего шоу Алисы
-    # https://yandex.ru/dev/dialogs/alice/doc/request-show-pull.html
+    # https://yandex.ru/dev/dialogs/alice/doc/ru/request-show-pull
     show_type: Optional[str] = None
 
     if TYPE_CHECKING:

diff --git a/aliceio/types/alice_response.py b/aliceio/types/alice_response.py
@@ -11,7 +11,7 @@ class AliceResponse(MutableAliceObject):
     """
     Ответ на запрос API Алисы.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/response.html)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/response)
     """
 
     response: Response

diff --git a/aliceio/types/analytic_event.py b/aliceio/types/analytic_event.py
@@ -9,7 +9,7 @@ class AnalyticEvent(MutableAliceObject):
     """
     Событие для аналитики.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/response.html#response__events-desc)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/response#events-desc)
     """
 
     name: str

diff --git a/aliceio/types/analytics.py b/aliceio/types/analytics.py
@@ -8,7 +8,7 @@ class Analytics(MutableAliceObject):
     """
     Данные для аналитики AppMetrica.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/response.html#response__analytics-desc)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/response#analytics-desc)
     """
 
     events: List[AnalyticEvent]

diff --git a/aliceio/types/api_state.py b/aliceio/types/api_state.py
@@ -6,14 +6,14 @@
 SessionState = StateDict
 UserState = StateDict
 ApplicationState = StateDict
-# https://yandex.ru/dev/dialogs/alice/doc/session-persistence.html
+# https://yandex.ru/dev/dialogs/alice/doc/ru/session-persistence
 
 
 class ApiState(AliceObject):
     """
     Данные о сохранённом состоянии на стороне API Алисы.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/request.html#request__state-desc)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/request#state-desc)
     """
 
     user: Optional[UserState] = None

diff --git a/aliceio/types/application.py b/aliceio/types/application.py
@@ -7,7 +7,7 @@ class Application(MutableAliceObject):
     """
     Приложение из :class:`Session`.
 
-    [Source](https://yandex.ru/dev/dialogs/alice/doc/request.html#request__application-desc)
+    [Source](https://yandex.ru/dev/dialogs/alice/doc/ru/request#application-desc)
     """
 
     application_id: str