python-zatolox-bot 0.1.0__tar.gz → 0.1.2__tar.gz

{python_zatolox_bot-0.1.0 → python_zatolox_bot-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zatolox-bot
-Version: 0.1.0
+Version: 0.1.2
 Summary: SDK ufficiale per costruire bot su Zatolox
 Home-page: https://github.com/zatolox/python-zatolox-bot
 Author: Zatolox

{python_zatolox_bot-0.1.0 → python_zatolox_bot-0.1.2}/python_zatolox_bot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zatolox-bot
-Version: 0.1.0
+Version: 0.1.2
 Summary: SDK ufficiale per costruire bot su Zatolox
 Home-page: https://github.com/zatolox/python-zatolox-bot
 Author: Zatolox

{python_zatolox_bot-0.1.0 → python_zatolox_bot-0.1.2}/setup.py

@@ -5,7 +5,7 @@ from setuptools import setup, find_packages
 # sono, meno se ne rompono.
 setup(
     name="python-zatolox-bot",
-    version="0.1.0",
+    version="0.1.2",
     description="SDK ufficiale per costruire bot su Zatolox",
     long_description=(
         "Wrapper leggero attorno al gateway HTTP dei bot di Zatolox. "

{python_zatolox_bot-0.1.0 → python_zatolox_bot-0.1.2}/zatolox/__init__.py

@@ -3,5 +3,5 @@
 from .bot import ZatoloxBot, ZatoloxApiError
 from .types import User, Message, CallbackQuery, Update
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __all__ = ["ZatoloxBot", "ZatoloxApiError", "User", "Message", "CallbackQuery", "Update"]

{python_zatolox_bot-0.1.0 → python_zatolox_bot-0.1.2}/zatolox/bot.py

@@ -45,6 +45,9 @@ class ZatoloxBot:
         self.command_handlers: Dict[str, Callable[[Message], None]] = {}
         self._message_handler: Optional[Callable[[Message], None]] = None
         self._callback_handler: Optional[Callable[[CallbackQuery], None]] = None
+        # Handler di callback CON PREDICATO (@bot.callback_query_handler(func=...)): coppie
+        # (predicato, funzione). Il primo il cui predicato e' vero riceve il click.
+        self._callback_query_handlers: List[tuple] = []
 
         # Offset del prossimo getUpdates. Avanza a `ultimo update_id + 1`: e' cosi' che si conferma
         # al server di aver ricevuto tutto cio' che precede, e non lo si riceve piu'.
@@ -91,6 +94,61 @@ class ZatoloxBot:
         result = self._call("getUpdates", params, http="get") or []
         return [Update.from_dict(u) for u in result]
 
+    def set_my_commands(self, commands: List[Any]) -> List[dict]:
+        """
+        Registra i comandi del bot sul server (come setMyCommands di Telegram).
+
+        Il client Zatolox li mostra nel menu "/" della barra input: senza almeno un comando quel
+        menu non compare proprio. Da chiamare una volta all'avvio.
+
+        `commands` accetta forme diverse, per comodita':
+            - dict:  {"command": "start", "description": "avvia il bot"}
+            - tupla: ("start", "avvia il bot")
+        Lo slash iniziale e' facoltativo: lo normalizza il server. Un array vuoto azzera i comandi.
+        """
+        norm: List[dict] = []
+        for c in commands:
+            if isinstance(c, dict):
+                norm.append({"command": str(c.get("command", "")), "description": str(c.get("description", ""))})
+            elif isinstance(c, (tuple, list)) and len(c) >= 2:
+                norm.append({"command": str(c[0]), "description": str(c[1])})
+        return self._call("setMyCommands", {"commands": norm})
+
+    def edit_message_text(
+        self, chat_id: str, message_id: str, text: str, reply_markup: Optional[Any] = None
+    ) -> Optional[Message]:
+        """
+        Riscrive un PROPRIO messaggio (testo + eventuali pulsanti). La via per navigare un menu:
+        clic -> callback -> edit del testo e dei pulsanti, senza inviare un nuovo messaggio.
+
+        Se passi `reply_markup` aggiorna la tastiera (None esplicito la rimuove); se lo ometti, i
+        pulsanti restano quelli di prima. Un bot puo' modificare solo i messaggi che ha inviato lui.
+        """
+        payload: Dict[str, Any] = {"chat_id": chat_id, "message_id": message_id, "text": text}
+        if reply_markup is not None:
+            payload["reply_markup"] = reply_markup
+        return Message.from_dict(self._call("editMessageText", payload))
+
+    def edit_message_reply_markup(
+        self, chat_id: str, message_id: str, reply_markup: Optional[Any] = None
+    ) -> Optional[Message]:
+        """Cambia SOLO i pulsanti di un proprio messaggio, senza toccarne il testo (utile per i
+        sottomenu). `reply_markup=None` toglie la tastiera."""
+        return Message.from_dict(self._call(
+            "editMessageReplyMarkup",
+            {"chat_id": chat_id, "message_id": message_id, "reply_markup": reply_markup}
+        ))
+
+    def answer_callback_query(self, callback_query_id: str, text: Optional[str] = None) -> Any:
+        """
+        Conferma un click su un pulsante inline. Con `text` mostra un piccolo avviso a chi ha
+        toccato; senza, e' solo un ack. Da chiamare dentro l'handler della callback.
+        """
+        payload: Dict[str, Any] = {"callback_query_id": callback_query_id}
+        if text is not None:
+            payload["text"] = text
+        return self._call("answerCallbackQuery", payload)
+
     # ------------------------------------------------------------------ handler
 
     def add_command_handler(self, command: str, callback: Callable[[Message], None]) -> None:
@@ -113,6 +171,43 @@ class ZatoloxBot:
             return fn
         return deco
 
+    def message_handler(self, fn: Optional[Callable[[Message], None]] = None):
+        """
+        Decoratore per il fallback sul testo LIBERO (i messaggi che non sono comandi) — la base per
+        un bot conversazionale (es. inoltrare il testo a un'IA). Equivale ad add_message_handler.
+
+        Funziona sia nudo sia con le parentesi::
+
+            @bot.message_handler
+            def on_text(msg): ...
+
+            @bot.message_handler()
+            def on_text(msg): ...
+        """
+        def register(f: Callable[[Message], None]) -> Callable[[Message], None]:
+            self.add_message_handler(f)
+            return f
+        # Uso nudo (@bot.message_handler): Python passa gia' la funzione qui.
+        return register(fn) if fn is not None else register
+
+    def callback_query_handler(self, func: Optional[Callable[[CallbackQuery], bool]] = None):
+        """
+        Decoratore per i click sui pulsanti inline, con un filtro:
+
+            @bot.callback_query_handler(func=lambda call: call.data == "next")
+            def on_next(call): ...
+
+        `func` e' un predicato sul CallbackQuery: il PRIMO handler il cui predicato e' vero riceve il
+        click. Ometti `func` (o passa None) per prenderli tutti. Coesiste con add_callback_handler,
+        che resta come fallback finale.
+        """
+        predicate = func if callable(func) else (lambda call: True)
+
+        def deco(fn: Callable[[CallbackQuery], None]) -> Callable[[CallbackQuery], None]:
+            self._callback_query_handlers.append((predicate, fn))
+            return fn
+        return deco
+
     # ------------------------------------------------------------------ instradamento
 
     def _dispatch(self, update: Update) -> None:
@@ -120,8 +215,16 @@ class ZatoloxBot:
         stampata, non propagata, cosi' un handler difettoso non ferma il polling."""
         try:
             if update.callback_query is not None:
+                cb = update.callback_query
+                # Prima gli handler con predicato, in ordine di registrazione: vince il primo che
+                # accetta. E' cio' che permette di smistare per callback_data (menu/sottomenu).
+                for predicate, fn in self._callback_query_handlers:
+                    if predicate(cb):
+                        fn(cb)
+                        return
+                # Nessuno ha accettato: fallback al singolo handler generico, se c'e'.
                 if self._callback_handler:
-                    self._callback_handler(update.callback_query)
+                    self._callback_handler(cb)
                 return
 
             msg = update.message