Update API

dff/messengers/common/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 
 from .interface import MessengerInterface, PollingMessengerInterface, CallbackMessengerInterface, CLIMessengerInterface
-from .types import PipelineRunnerFunction, PollingInterfaceLoopFunction
+from .types import PollingInterfaceLoopFunction

dff/messengers/common/interface.py

@@ -4,15 +4,18 @@
 The Message Interfaces module contains several basic classes that define the message interfaces.
 These classes provide a way to define the structure of the messengers that are used to communicate with the DFF.
 """
+from __future__ import annotations
 import abc
 import asyncio
 import logging
 import uuid
-from typing import Optional, Any, List, Tuple, TextIO, Hashable
+from typing import Optional, Any, List, Tuple, TextIO, Hashable, TYPE_CHECKING
 
 from dff.script import Context, Message
+from dff.messengers.common.types import PollingInterfaceLoopFunction
 
-from .types import PipelineRunnerFunction, PollingInterfaceLoopFunction
+if TYPE_CHECKING:
+    from dff.pipeline.types import PipelineRunnerFunction
 
 logger = logging.getLogger(__name__)
 
@@ -29,9 +32,8 @@ async def connect(self, pipeline_runner: PipelineRunnerFunction):
         Method invoked when message interface is instantiated and connection is established.
         May be used for sending an introduction message or displaying general bot information.
 
-        :param pipeline_runner: A function that should return pipeline response to user request;
+        :param pipeline_runner: A function that should process user request and return context;
             usually it's a :py:meth:`~dff.pipeline.pipeline.pipeline.Pipeline._run_pipeline` function.
-        :type pipeline_runner: PipelineRunnerFunction
         """
         raise NotImplementedError
 
@@ -96,12 +98,10 @@ async def connect(
         The looping behavior is determined by `loop` and `timeout`,
         for most cases the loop itself shouldn't be overridden.
 
-        :param pipeline_runner: A function that should return pipeline response to user request;
+        :param pipeline_runner: A function that should process user request and return context;
             usually it's a :py:meth:`~dff.pipeline.pipeline.pipeline.Pipeline._run_pipeline` function.
-        :type pipeline_runner: PipelineRunnerFunction
         :param loop: a function that determines whether polling should be continued;
             called in each cycle, should return `True` to continue polling or `False` to stop.
-        :type loop: PollingInterfaceLoopFunction
         :param timeout: a time interval between polls (in seconds).
         """
         while loop():
@@ -124,33 +124,23 @@ def __init__(self):
     async def connect(self, pipeline_runner: PipelineRunnerFunction):
         self._pipeline_runner = pipeline_runner
 
-    async def on_request_async(self, request: Any, ctx_id: Hashable) -> Context:
+    async def on_request_async(
+        self, request: Message, ctx_id: Optional[Hashable] = None, update_ctx_misc: Optional[dict] = None
+    ) -> Context:
         """
-        Method invoked on user input. This method works just like
-        :py:meth:`~dff.pipeline.pipeline.pipeline.Pipeline._run_pipeline`,
-        however callback message interface may contain additional functionality (e.g. for external API accessing).
-        Return context that represents dialog with the user;
-        `last_response`, `id` and some dialog info can be extracted from there.
-
-        :param request: User input.
-        :param ctx_id: Any unique id that will be associated with dialog between this user and pipeline.
-        :return: Context that represents dialog with the user.
+        Method that should be invoked on user input.
+        This method has the same signature as :py:class:`~dff.pipeline.types.PipelineRunnerFunction`.
         """
-        return await self._pipeline_runner(request, ctx_id)
+        return await self._pipeline_runner(request, ctx_id, update_ctx_misc)
 
-    def on_request(self, request: Any, ctx_id: Hashable) -> Context:
+    def on_request(
+        self, request: Any, ctx_id: Optional[Hashable] = None, update_ctx_misc: Optional[dict] = None
+    ) -> Context:
         """
-        Method invoked on user input. This method works just like
-        :py:meth:`~dff.pipeline.pipeline.pipeline.Pipeline._run_pipeline`,
-        however callback message interface may contain additional functionality (e.g. for external API accessing).
-        Return context that represents dialog with the user;
-        `last_response`, `id` and some dialog info can be extracted from there.
-
-        :param request: User input.
-        :param ctx_id: Any unique id that will be associated with dialog between this user and pipeline.
-        :return: Context that represents dialog with the user.
+        Method that should be invoked on user input.
+        This method has the same signature as :py:class:`~dff.pipeline.types.PipelineRunnerFunction`.
         """
-        return asyncio.run(self.on_request_async(request, ctx_id))
+        return asyncio.run(self.on_request_async(request, ctx_id, update_ctx_misc))
 
 
 class CLIMessengerInterface(PollingMessengerInterface):
@@ -183,9 +173,8 @@ async def connect(self, pipeline_runner: PipelineRunnerFunction, **kwargs):
         """
         The CLIProvider generates new dialog id used to user identification on each `connect` call.
 
-        :param pipeline_runner: A function that should return pipeline response to user request;
+        :param pipeline_runner: A function that should process user request and return context;
             usually it's a :py:meth:`~dff.pipeline.pipeline.pipeline.Pipeline._run_pipeline` function.
-        :type pipeline_runner: PipelineRunnerFunction
         :param \\**kwargs: argument, added for compatibility with super class, it shouldn't be used normally.
         """
         self._ctx_id = uuid.uuid4()

dff/messengers/common/types.py

@@ -1,22 +1,11 @@
 """
 Types
 -----
-The Types module contains two special types that are used throughout the `DFF Messengers`.
-The first type is used for the messenger interface to client interaction and the second one
-to control the polling loop.
+The Types module contains special types that are used throughout the `DFF Messengers`.
 """
-from typing import Callable, Any, Hashable, Awaitable
+from typing import Callable
 from typing_extensions import TypeAlias
 
-from dff.script import Context
-
-
-PipelineRunnerFunction: TypeAlias = Callable[[Any, Hashable], Awaitable[Context]]
-"""
-A function type for messenger_interface-to-client interaction.
-Accepts anything (user input) and hashable value (current context id), returns string (answer from pipeline).
-"""
-
 
 PollingInterfaceLoopFunction: TypeAlias = Callable[[], bool]
 """

dff/messengers/telegram/interface.py

@@ -10,7 +10,8 @@
 from telebot import types, logger
 
 from dff.script import Context
-from dff.messengers.common import PollingMessengerInterface, PipelineRunnerFunction, CallbackMessengerInterface
+from dff.messengers.common import PollingMessengerInterface, CallbackMessengerInterface
+from dff.pipeline.types import PipelineRunnerFunction
 from .messenger import TelegramMessenger
 from .message import TelegramMessage, Message