python-zatolox-bot 0.1.0__tar.gz

python_zatolox_bot-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: python-zatolox-bot
+Version: 0.1.0
+Summary: SDK ufficiale per costruire bot su Zatolox
+Home-page: https://github.com/zatolox/python-zatolox-bot
+Author: Zatolox
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Wrapper leggero attorno al gateway HTTP dei bot di Zatolox. Registri gli handler dei comandi e delle callback, chiami start_polling(), e il resto e' gestito dall'SDK.

python_zatolox_bot-0.1.0/python_zatolox_bot.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: python-zatolox-bot
+Version: 0.1.0
+Summary: SDK ufficiale per costruire bot su Zatolox
+Home-page: https://github.com/zatolox/python-zatolox-bot
+Author: Zatolox
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Wrapper leggero attorno al gateway HTTP dei bot di Zatolox. Registri gli handler dei comandi e delle callback, chiami start_polling(), e il resto e' gestito dall'SDK.

python_zatolox_bot-0.1.0/python_zatolox_bot.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+setup.py
+python_zatolox_bot.egg-info/PKG-INFO
+python_zatolox_bot.egg-info/SOURCES.txt
+python_zatolox_bot.egg-info/dependency_links.txt
+python_zatolox_bot.egg-info/requires.txt
+python_zatolox_bot.egg-info/top_level.txt
+zatolox/__init__.py
+zatolox/bot.py
+zatolox/types.py

python_zatolox_bot-0.1.0/python_zatolox_bot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python_zatolox_bot-0.1.0/python_zatolox_bot.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25

python_zatolox_bot-0.1.0/python_zatolox_bot.egg-info/top_level.txt

@@ -0,0 +1 @@
+zatolox

python_zatolox_bot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_zatolox_bot-0.1.0/setup.py

@@ -0,0 +1,25 @@
+from setuptools import setup, find_packages
+
+# Volutamente minimale per la v1: una sola dipendenza (requests). Un SDK di un bot deve poter
+# entrare in qualsiasi progetto senza trascinarsi dietro un albero di dipendenze — meno cose ci
+# sono, meno se ne rompono.
+setup(
+    name="python-zatolox-bot",
+    version="0.1.0",
+    description="SDK ufficiale per costruire bot su Zatolox",
+    long_description=(
+        "Wrapper leggero attorno al gateway HTTP dei bot di Zatolox. "
+        "Registri gli handler dei comandi e delle callback, chiami start_polling(), "
+        "e il resto e' gestito dall'SDK."
+    ),
+    author="Zatolox",
+    url="https://github.com/zatolox/python-zatolox-bot",
+    packages=find_packages(exclude=["tests", "examples"]),
+    python_requires=">=3.8",
+    install_requires=["requests>=2.25"],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)

python_zatolox_bot-0.1.0/zatolox/__init__.py

@@ -0,0 +1,7 @@
+"""python-zatolox-bot: SDK ufficiale per costruire bot su Zatolox."""
+
+from .bot import ZatoloxBot, ZatoloxApiError
+from .types import User, Message, CallbackQuery, Update
+
+__version__ = "0.1.0"
+__all__ = ["ZatoloxBot", "ZatoloxApiError", "User", "Message", "CallbackQuery", "Update"]

python_zatolox_bot-0.1.0/zatolox/bot.py

@@ -0,0 +1,185 @@
+"""
+Il motore del bot.
+
+Un ciclo `getUpdates` -> instrada ogni aggiornamento all'handler giusto -> `sendMessage` quando
+il tuo codice risponde. L'SDK non nasconde il protocollo, lo rende comodo: puoi sempre chiamare i
+metodi grezzi (`send_message`, `get_updates`) se un handler non ti basta.
+"""
+
+import time
+from typing import Callable, Dict, List, Optional, Any
+
+import requests
+
+from .types import Update, Message, CallbackQuery
+
+
+class ZatoloxBot:
+    """
+    Un bot Zatolox.
+
+    Uso minimo::
+
+        bot = ZatoloxBot("123:ABC...", "http://207.180.237.77:4000")
+
+        @bot.command("start")
+        def start(msg):
+            bot.send_message(msg.chat_id, "Ciao! Sono vivo.")
+
+        bot.start_polling()
+    """
+
+    def __init__(self, token: str, base_url: str, timeout: int = 30):
+        # base_url senza slash finale: l'URL del gateway e' `<base>/bot<token>/<metodo>`, e uno
+        # slash di troppo produrrebbe `//bot...` — un 404 difficile da diagnosticare.
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._session = requests.Session()
+
+        # Il token viaggia nel path, come su Telegram. Costruito una volta sola qui.
+        self._api = f"{self.base_url}/bot{self.token}"
+
+        # comando (senza "/") -> funzione(Message). Un fallback opzionale per i messaggi che non
+        # sono comandi, e uno per le callback.
+        self.command_handlers: Dict[str, Callable[[Message], None]] = {}
+        self._message_handler: Optional[Callable[[Message], None]] = None
+        self._callback_handler: Optional[Callable[[CallbackQuery], None]] = None
+
+        # 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'.
+        self._offset: Optional[int] = None
+        self._running = False
+
+    # ------------------------------------------------------------------ API grezze
+
+    def _call(self, method: str, payload: Optional[dict] = None, http: str = "post") -> Any:
+        """Una chiamata al gateway. Solleva se il server risponde `ok: false`, cosi' gli errori
+        non passano inosservati come un risultato vuoto."""
+        url = f"{self._api}/{method}"
+        if http == "get":
+            resp = self._session.get(url, params=payload, timeout=self.timeout + 10)
+        else:
+            resp = self._session.post(url, json=payload, timeout=self.timeout + 10)
+        data = resp.json()
+        if not data.get("ok"):
+            raise ZatoloxApiError(data.get("error_code", resp.status_code), data.get("description", "errore sconosciuto"))
+        return data.get("result")
+
+    def get_me(self) -> dict:
+        """Info sul bot. Utile come ping per verificare che il token sia valido."""
+        return self._call("getMe", http="get")
+
+    def send_message(self, chat_id: str, text: str, reply_markup: Optional[Any] = None) -> Message:
+        """
+        Invia un messaggio di testo in una chat.
+
+        `reply_markup` e' la tastiera inline: puoi passare la forma Telegram
+        `{"inline_keyboard": [[{"text": "...", "callback_data": "..."}]]}` oppure l'array nudo
+        `[[{...}]]` — il client Zatolox accetta entrambe.
+        """
+        payload: Dict[str, Any] = {"chat_id": chat_id, "text": text}
+        if reply_markup is not None:
+            payload["reply_markup"] = reply_markup
+        return Message.from_dict(self._call("sendMessage", payload))
+
+    def get_updates(self, offset: Optional[int] = None, timeout: int = 0, limit: int = 100) -> List[Update]:
+        """Un giro di getUpdates. Di solito non serve chiamarlo a mano: lo fa start_polling()."""
+        params: Dict[str, Any] = {"limit": limit, "timeout": timeout}
+        if offset is not None:
+            params["offset"] = offset
+        result = self._call("getUpdates", params, http="get") or []
+        return [Update.from_dict(u) for u in result]
+
+    # ------------------------------------------------------------------ handler
+
+    def add_command_handler(self, command: str, callback: Callable[[Message], None]) -> None:
+        """Registra la funzione per un comando. `command` con o senza la "/" iniziale: la si
+        normalizza, cosi' 'start' e '/start' funzionano entrambi."""
+        self.command_handlers[command.lstrip("/").lower()] = callback
+
+    def add_message_handler(self, callback: Callable[[Message], None]) -> None:
+        """Fallback per i messaggi che non sono comandi (es. un echo bot)."""
+        self._message_handler = callback
+
+    def add_callback_handler(self, callback: Callable[[CallbackQuery], None]) -> None:
+        """Registra la funzione chiamata a ogni click su un pulsante inline."""
+        self._callback_handler = callback
+
+    def command(self, name: str):
+        """Decoratore comodo: `@bot.command("start")` sopra la funzione."""
+        def deco(fn: Callable[[Message], None]):
+            self.add_command_handler(name, fn)
+            return fn
+        return deco
+
+    # ------------------------------------------------------------------ instradamento
+
+    def _dispatch(self, update: Update) -> None:
+        """Manda un aggiornamento all'handler giusto. Un'eccezione nel TUO codice viene isolata:
+        stampata, non propagata, cosi' un handler difettoso non ferma il polling."""
+        try:
+            if update.callback_query is not None:
+                if self._callback_handler:
+                    self._callback_handler(update.callback_query)
+                return
+
+            msg = update.message
+            if msg is None:
+                return
+            cmd = msg.command
+            if cmd is not None and cmd in self.command_handlers:
+                self.command_handlers[cmd](msg)
+            elif self._message_handler is not None:
+                self._message_handler(msg)
+        except Exception as e:  # noqa: BLE001 — un handler dell'utente non deve abbattere il bot
+            print(f"[zatolox] handler ha sollevato: {e!r}")
+
+    def start_polling(self, poll_timeout: Optional[int] = None) -> None:
+        """
+        Il ciclo principale: chiede aggiornamenti in long-polling e li instrada finche' non si
+        chiama stop().
+
+        L'offset e' la parte importante: dopo aver elaborato un lotto, si avanza a
+        `max(update_id) + 1`. Alla chiamata seguente il server considera confermato tutto cio' che
+        precede e non lo rimanda. Se un giro fallisce (rete), NON si avanza l'offset: quegli
+        aggiornamenti tornano al tentativo dopo, invece di andare persi.
+        """
+        self._running = True
+        wait = self.timeout if poll_timeout is None else poll_timeout
+        print(f"[zatolox] polling avviato (timeout {wait}s). Ctrl-C per fermare.")
+        while self._running:
+            try:
+                updates = self.get_updates(offset=self._offset, timeout=wait)
+            except requests.RequestException as e:
+                # Errore di rete: pausa breve e riprova. L'offset resta fermo, niente va perso.
+                print(f"[zatolox] rete: {e!r}; riprovo fra 3s")
+                time.sleep(3)
+                continue
+            except ZatoloxApiError as e:
+                # 401 = token revocato o errato: inutile insistere.
+                print(f"[zatolox] API: {e!r}")
+                if e.code == 401:
+                    break
+                time.sleep(3)
+                continue
+
+            for u in updates:
+                self._dispatch(u)
+                # Si avanza update per update: se un handler fa cadere il processo, al riavvio si
+                # riparte dal PRIMO non ancora confermato, non dal lotto intero.
+                self._offset = u.update_id + 1
+
+    def stop(self) -> None:
+        """Ferma il ciclo di polling al giro successivo."""
+        self._running = False
+
+
+class ZatoloxApiError(Exception):
+    """Il gateway ha risposto `ok: false`. Porta il codice, cosi' il chiamante puo' distinguere
+    un 401 (token) da un 403 (il bot non e' nella chat) da un 500."""
+
+    def __init__(self, code: int, description: str):
+        self.code = code
+        self.description = description
+        super().__init__(f"[{code}] {description}")

python_zatolox_bot-0.1.0/zatolox/types.py

@@ -0,0 +1,112 @@
+"""
+Modelli dati dell'SDK.
+
+Rispecchiano ESATTAMENTE cio' che il gateway di Zatolox restituisce (i metodi in stile Telegram
+`getUpdates`/`sendMessage`), non un formato ideale. Ogni `from_dict` e' tollerante: i campi
+mancanti diventano None invece di sollevare un errore, cosi' una piccola differenza fra versioni
+del server non fa crollare il bot.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class User:
+    """Chi ha originato un aggiornamento: una persona o un altro bot."""
+    id: str
+    is_bot: bool = False
+    first_name: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[Dict[str, Any]]) -> Optional["User"]:
+        if not d:
+            return None
+        return cls(
+            id=str(d.get("id", "")),
+            is_bot=bool(d.get("is_bot", False)),
+            first_name=d.get("first_name"),
+        )
+
+
+@dataclass
+class Message:
+    """Un messaggio in una chat. `chat_id` e' cio' che serve per rispondere."""
+    message_id: str
+    chat_id: Optional[str]
+    text: str = ""
+    type: str = "TEXT"
+    date: Optional[int] = None
+    from_user: Optional[User] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[Dict[str, Any]]) -> Optional["Message"]:
+        if not d:
+            return None
+        return cls(
+            message_id=str(d.get("message_id", "")),
+            chat_id=d.get("chat_id"),
+            text=d.get("text", "") or "",
+            type=d.get("type", "TEXT"),
+            date=d.get("date"),
+            from_user=User.from_dict(d.get("from")),
+        )
+
+    @property
+    def command(self) -> Optional[str]:
+        """
+        Il comando in questo messaggio, senza la barra, o None.
+
+        Riconosce anche la forma `/comando@nomebot` che compare nei gruppi (dove piu' bot possono
+        rispondere e Telegram indirizza il comando col nome): la parte dopo `@` viene scartata.
+        """
+        t = self.text.strip()
+        if not t.startswith("/"):
+            return None
+        token = t.split()[0][1:]      # primo pezzo, senza la "/"
+        return token.split("@")[0] or None
+
+
+@dataclass
+class CallbackQuery:
+    """Un click su un pulsante inline. `data` e' il callback_data del pulsante toccato."""
+    id: str
+    data: str
+    from_user: Optional[User] = None
+    message: Optional[Message] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[Dict[str, Any]]) -> Optional["CallbackQuery"]:
+        if not d:
+            return None
+        return cls(
+            id=str(d.get("id", "")),
+            data=d.get("data", "") or "",
+            from_user=User.from_dict(d.get("from")),
+            message=Message.from_dict(d.get("message")),
+        )
+
+    @property
+    def chat_id(self) -> Optional[str]:
+        """Scorciatoia: la chat da cui e' arrivato il click, per rispondere sul posto."""
+        return self.message.chat_id if self.message else None
+
+
+@dataclass
+class Update:
+    """
+    Contenitore di un aggiornamento. Porta un `update_id` monotono e UNO fra `message` e
+    `callback_query`. L'`update_id` e' cio' che il polling usa come offset per confermare la
+    ricezione.
+    """
+    update_id: int
+    message: Optional[Message] = None
+    callback_query: Optional[CallbackQuery] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Update":
+        return cls(
+            update_id=int(d.get("update_id", 0)),
+            message=Message.from_dict(d.get("message")),
+            callback_query=CallbackQuery.from_dict(d.get("callback_query")),
+        )