telekit 2.6.0a3__tar.gz → 2.6.0a4__tar.gz

{telekit-2.6.0a3 → telekit-2.6.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.6.0a3
+Version: 2.6.0a4
 Summary: Declarative, developer-friendly framework for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -471,19 +471,30 @@ Telekit focuses on one job: making Telegram bot development easier.
 
 ---
 
-# Changes in version 2.6.0a3
+# Changes in version 2.6.0a4
+
+### v2.6.0 `a4`
+- Added `handle_handoff()` to `Handler`: a shortcut for `handoff(handler).handle()` that takes the target handler as an argument, so it can be passed to `add_callback()` without an extra closure
+- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
+- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
+- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
+- Converted the `handoff()` docstring to reST
 
 ### v2.6.0 `a3`
-- Added support for Rich HTML messages (Bot API 10.1+) and enhance styles
-    - Introduced a new module `_rich.py` to handle Rich HTML parsing and serialization.
-    - Updated `styles.py` to include new rich tags for enhanced text formatting.
-    - Created `rich.py` example handler to demonstrate the usage of Rich HTML features, including inline styles, blocks, lists, tables, media, and sender integration.
+- Added support for Rich HTML messages (Bot API 10.1+)
+- Added the `_rich.py` module for Rich HTML parsing and serialization
+- Added new rich tags to `styles.py` for enhanced text formatting
+- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
 
 ### v2.6.0 `a2`
-- Reworked `.env` and token/canvas file reading in `utils`: full `.env` syntax support (comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation), a `cache` parameter (default `True`) with `clear_cache()`, detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions; `load_env` now raises `EnvFileNotFoundError` for a missing file instead of returning `{}`
+- Reworked `.env` and token/canvas file reading in `utils`
+- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
+- Added the `cache` parameter (default `True`) and `clear_cache()`
+- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
+- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
 
 ### v2.6.0 `a1`
-- Added a module-loading utility in `utils`
+- Added a module-loading utility to `utils`
 
 ### v2.6.0 `a0`
 - Improved formatting in `_on.py`

{telekit-2.6.0a3 → telekit-2.6.0a4}/telekit/_handler.py

@@ -242,10 +242,45 @@ class Handler:
     def _on_handoff(self, origin: "Handler") -> None:
         """Called when this handler is reached via handoff(). Override to customize."""
         pass
-    
+
+    def handle_handoff(self, handler: type["Handler"] | str):
+        """
+        Transfers control to another handler and immediately runs its ``handle()``.
+
+        This is a shortcut for ``self.handoff(handler).handle()``. The target
+        handler is created via :meth:`handoff`, so it inherits the same initial
+        user message and the previous chain message (which allows editing it).
+
+        Unlike ``self.handoff(handler).handle``, it takes the target handler as
+        an argument, so it can be passed directly as a callback together with
+        its arguments, without creating an extra closure::
+
+            self.chain.add_callback(
+                "Settings",
+                self.handle_handoff, [SettingsHandler],
+            )
+
+        It can also be called directly::
+
+            self.handle_handoff(SettingsHandler)
+            self.handle_handoff("SettingsHandler")
+
+        :param handler: Target handler name or ``Handler`` subclass to transfer
+            control to.
+        :type handler: str | type[Handler]
+
+        :raises NameError: If a string name is provided but no registered
+            handler exists with that name.
+        :raises TypeError: If the provided value is not a ``Handler`` subclass.
+
+        .. seealso:: :meth:`handoff`
+        """
+        self.handoff(handler).handle()
 
     def freeze(self, func, *args):
         """
+        DEPRECATED
+
         Return a zero-argument callback that invokes the given function
         with the provided arguments.
 

{telekit-2.6.0a3 → telekit-2.6.0a4}/telekit/_version.py

@@ -3,4 +3,4 @@
 # PyPI history: https://pypi.org/project/telekit/#history
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-__version__ = "2.6.0a3"
+__version__ = "2.6.0a4"

{telekit-2.6.0a3 → telekit-2.6.0a4}/telekit/traits/track_handoff_origin.py

@@ -1,7 +1,9 @@
+from functools import partial
 from typing import Callable
 
 import telekit
 
+
 class TrackHandoffOrigin(telekit.Trait):
 
     TRACK_HANDOFF_ORIGIN: bool = True
@@ -29,71 +31,107 @@ class TrackHandoffOrigin(telekit.Trait):
         - ``False`` if this handler was invoked directly.
         """
         return self.handoff_origin is not None
-    
+
     def handoff_back(self, *args, **kwargs):
         """
         Transfer control back to the handler that handed off to this one.
 
         Useful for implementing "« Back" buttons without hardcoding the
-        previous handler class:
+        previous handler class::
 
-        .. code-block:: python
             self.chain.set_inline_keyboard({
                 "« Back": self.handoff_back
             })
 
         Any positional or keyword arguments are forwarded directly to
-        ``handoff_origin.handle()``:
+        ``handoff_origin.handle()``::
 
-        .. code-block:: python
             self.handoff_back("some_arg", key="value")
             # equivalent to: handoff_origin.handle("some_arg", key="value")
 
-
-        :raises RuntimeError: If this handler was not reached via :meth:`handoff`
-                            (i.e. ``handoff_origin`` is ``None``).
+        :raises RuntimeError: If this handler was not reached via
+            :meth:`handoff` (i.e. ``handoff_origin`` is ``None``).
         """
         if self.handoff_origin is None:
             raise RuntimeError(
                 f"{type(self).__name__}().handoff_back() called, but this handler "
                 "was not reached via handoff() - handoff_origin is None."
             )
-        
         self.handoff_origin.chain._set_previous_message(self.chain.get_previous_message())
         self.handoff_origin.handle(*args, **kwargs)
 
+    def handle_handoff_back_or(
+        self,
+        handler: type[telekit.Handler] | str,
+        *args,
+        **kwargs,
+    ) -> None:
+        """
+        Transfer control back to the origin handler, or to ``handler`` if
+        this handler was invoked directly, and immediately run its ``handle()``.
+
+        Unlike :meth:`handoff_back_or`, it takes the fallback handler as an
+        argument, so it can be passed directly as a callback together with
+        its arguments, without creating an extra closure::
+
+            self.chain.add_callback(
+                "« Back",
+                self.handle_handoff_back_or,
+                [StartHandler],
+            )
+
+        It can also be called directly. Any extra positional or keyword
+        arguments are forwarded to ``handle()`` of whichever handler is
+        invoked::
+
+            self.handle_handoff_back_or(StartHandler, "some_arg", key="value")
+            # if handed off:  handoff_origin.handle("some_arg", key="value")
+            # if direct:      StartHandler.handle("some_arg", key="value")
+
+        :param handler: Fallback handler class (or name) to transfer control
+            to when ``handoff_origin`` is ``None``.
+        :type handler: type[Handler] | str
+
+        :raises NameError: If a string name is provided but no registered
+            handler exists with that name.
+        :raises TypeError: If the provided value is not a ``Handler`` subclass.
+
+        .. seealso:: :meth:`handoff_back`, :meth:`handoff_back_or`
+        """
+        if self.handoff_origin is None:
+            self.handoff(handler).handle(*args, **kwargs)
+        else:
+            self.handoff_back(*args, **kwargs)
+
     def handoff_back_or(self, handler: type[telekit.Handler] | str) -> Callable[..., None]:
         """
         Return a callable that transfers control back to the origin handler,
         or falls back to ``handler`` if this handler was invoked directly.
 
         Useful for ``« Back`` buttons in handlers that can be reached both
-        via :meth:`handoff` and directly:
+        via :meth:`handoff` and directly::
 
-        .. code-block:: python
             self.chain.set_inline_keyboard({
                 "« Back": self.handoff_back_or(StartHandler)
             })
 
         Any positional or keyword arguments passed to the returned callable
-        are forwarded to ``handle()`` of whichever handler is invoked:
+        are forwarded to ``handle()`` of whichever handler is invoked::
 
-        .. code-block:: python
             back = self.handoff_back_or(StartHandler)
             back("some_arg", key="value")
             # if handed off:  handoff_origin.handle("some_arg", key="value")
             # if direct:      StartHandler.handle("some_arg", key="value")
 
-        :param handler: Fallback handler class (or name) to transfer control to when
-                        ``handoff_origin`` is ``None``.
-        :type handler: ``type[Handler]`` | ``str``
-        :return: A zero-argument callable that performs the handoff.
-        :rtype: ``Callable[..., None]``
+        :param handler: Fallback handler class (or name) to transfer control
+            to when ``handoff_origin`` is ``None``.
+        :type handler: type[Handler] | str
+
+        :return: A callable that performs the handoff; it accepts any
+            arguments and forwards them to ``handle()``.
+        :rtype: Callable[..., None]
+
+        .. seealso:: :meth:`handle_handoff_back_or` — a closure-free
+            alternative for use as a callback.
         """
-        def handoff_invoker(*args, **kwargs):
-            if self.handoff_origin is None:
-                self.handoff(handler).handle(*args, **kwargs)
-            else:
-                self.handoff_back(*args, **kwargs)
-                    
-        return handoff_invoker
+        return partial(self.handle_handoff_back_or, handler)

{telekit-2.6.0a3 → telekit-2.6.0a4}/telekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.6.0a3
+Version: 2.6.0a4
 Summary: Declarative, developer-friendly framework for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -471,19 +471,30 @@ Telekit focuses on one job: making Telegram bot development easier.
 
 ---
 
-# Changes in version 2.6.0a3
+# Changes in version 2.6.0a4
+
+### v2.6.0 `a4`
+- Added `handle_handoff()` to `Handler`: a shortcut for `handoff(handler).handle()` that takes the target handler as an argument, so it can be passed to `add_callback()` without an extra closure
+- Added `handle_handoff_back_or()` to `TrackHandoffOrigin`: a closure-free counterpart of `handoff_back_or()`
+- Reworked `handoff_back_or()` as a thin `functools.partial` wrapper around `handle_handoff_back_or()`
+- Fixed the `handoff_back_or()` docstring: the returned callable forwards its arguments to `handle()` instead of being zero-argument
+- Converted the `handoff()` docstring to reST
 
 ### v2.6.0 `a3`
-- Added support for Rich HTML messages (Bot API 10.1+) and enhance styles
-    - Introduced a new module `_rich.py` to handle Rich HTML parsing and serialization.
-    - Updated `styles.py` to include new rich tags for enhanced text formatting.
-    - Created `rich.py` example handler to demonstrate the usage of Rich HTML features, including inline styles, blocks, lists, tables, media, and sender integration.
+- Added support for Rich HTML messages (Bot API 10.1+)
+- Added the `_rich.py` module for Rich HTML parsing and serialization
+- Added new rich tags to `styles.py` for enhanced text formatting
+- Added the `rich.py` example handler demonstrating Rich HTML: inline styles, blocks, lists, tables, media, and sender integration
 
 ### v2.6.0 `a2`
-- Reworked `.env` and token/canvas file reading in `utils`: full `.env` syntax support (comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation), a `cache` parameter (default `True`) with `clear_cache()`, detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions; `load_env` now raises `EnvFileNotFoundError` for a missing file instead of returning `{}`
+- Reworked `.env` and token/canvas file reading in `utils`
+- Added full `.env` syntax support: comments, `export`, quotes and escapes, multi-line values, `$VAR` interpolation
+- Added the `cache` parameter (default `True`) and `clear_cache()`
+- Added detailed errors with fix suggestions and creation commands, and new `Env*Error` exceptions
+- Changed `load_env()` to raise `EnvFileNotFoundError` for a missing file instead of returning `{}`
 
 ### v2.6.0 `a1`
-- Added a module-loading utility in `utils`
+- Added a module-loading utility to `utils`
 
 ### v2.6.0 `a0`
 - Improved formatting in `_on.py`