TgrEzLi 0.1.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

tgrezli-0.4.0.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.3
+Name: TgrEzLi
+Version: 0.4.0
+Summary: Telegram bot library with sync-style API, handlers for messages/commands/callbacks, and optional embedded API server.
+Author: eaannist
+Author-email: eaannist <eaannist@gmail.com>
+Requires-Dist: ezlog-py>=1.0.5
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: pycypherlib
+Requires-Dist: requests>=2.28.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# TgrEzLi
+
+Telegram bot library with a **sync-style API**, handlers for messages, commands, and callbacks, and an optional **embedded HTTP server** for custom POST endpoints. Built on [python-telegram-bot](https://pypi.org/project/python-telegram-bot/) and [ezlog](https://pypi.org/project/ezlog-py/) for logging.
+
+- **Sync-style usage**: register handlers with decorators, use `TgMsg` / `TgCmd` / `TgCb` / `TgArgs` in handlers (thread-local context).
+- **Multiple chats**: connect with a `{chat_name: chat_id}` dict; restrict handlers per chat.
+- **Optional API server**: expose custom POST routes; call them with the `TReq` client.
+- **Credential encryption**: store token and chats in an encrypted file with **PyCypherLib** (included by default).
+
+---
+
+## Install
+
+```bash
+pip install TgrEzLi
+```
+
+Dependencies: `ezlog-py`, `python-telegram-bot`, **PyCypherLib**, `requests`.
+
+---
+
+## Quick start
+
+**After `connect()`** the bot starts polling in a **background thread**, so **`send_msg()` and handlers work immediately** (no need to call `run()`). Use **`run()`** only to **block the main thread** until you press Ctrl+C or call `stop()` (e.g. in a script so the process does not exit).
+
+```python
+from TgrEzLi import TEL, TgMsg, TgCmd, TgCb, TgArgs, TReq
+
+bot = TEL()
+
+# 1) Connect: starts polling in background. send_msg() works right away.
+TOKEN = "123456789:ABCDEFGHIJKLMNO"
+CHAT_DICT = {"chat1": "123456789", "chat2": "789456123"}
+bot.connect(TOKEN, CHAT_DICT)
+
+# You can send without calling run() (e.g. from REPL)
+bot.send_msg("Ciao a tutti")
+
+# 2) Register handlers (before or after connect)
+@bot.on_message()
+def on_message():
+    bot.send_msg(f"Hi {TgMsg.userName}! You wrote: {TgMsg.text}")
+
+@bot.on_command("start")
+def on_start():
+    bot.send_msg(f"Welcome {TgCmd.userName}!")
+    if TgCmd.args:
+        bot.send_msg(f"Args: {TgCmd.args}")
+
+# 3) Optional: block main thread until Ctrl+C (so the script does not exit)
+bot.run()
+```
+
+From the **REPL**: after `connect()` you can call `bot.send_msg("...")` and it is sent; handlers are active. If you **redefine** a handler (same function name), the new one **replaces** the previous one (no duplicate execution).
+
+---
+
+## Configuration
+
+Create the bot with optional config:
+
+```python
+from TgrEzLi import TEL
+from TgrEzLi.types import TgrezliConfig
+
+config = TgrezliConfig(
+    save_log=True,
+    log_file="TgrEzLi.log",
+    api_host="localhost",
+    api_port=9999,
+)
+bot = TEL(config)
+```
+
+Or mutate after creation:
+
+- **`bot.set_save_log(flag)`** – enable/disable writing log lines to the file (console always uses ezlog).
+- **`bot.set_host(host)`** – API server host (used when the first `on_api_req` is registered).
+- **`bot.set_port(port)`** – API server port.
+
+Defaults: `save_log=True`, `log_file="TgrEzLi.log"`, `api_host="localhost"`, `api_port=9999`.
+
+---
+
+## Connecting and running
+
+- **`connect(token, chat_dict)`** – Prepares the bot and **starts polling in a background thread**. `send_msg()` and handlers work immediately (e.g. from REPL you can send without calling `run()`).
+- **`run()`** – **Optional.** Blocks the main thread until `stop()` (e.g. Ctrl+C). Use in scripts so the process does not exit. If API routes are registered, starts the API server when you call `run()`.
+- **`stop()`** – Stops polling and API server; if `run()` was waiting, it returns. Safe to call from a signal handler (Ctrl+C) or from another thread.
+
+**Direct:**
+
+```python
+bot.connect(TOKEN, {"chat1": "123456789", "chat2": "789456123"})
+bot.send_msg("Hello!")  # works immediately
+# ... register handlers ...
+bot.run()  # optional: block until Ctrl+C
+```
+
+**Encrypted storage (PyCypherLib):**
+
+```python
+# First time: save token and chats with a password (then connects)
+bot.signup(TOKEN, CHAT_DICT, "your_password")
+bot.run()
+
+# Later: load and connect
+bot.login("your_password")
+bot.send_msg("Hi from login")
+bot.run()
+```
+
+Data is stored in `tgrdata.cy` by default (PyCypherLib).
+
+---
+
+## Sending content
+
+All send methods accept an optional **`chat`**: `None` (default/first chat), a **string** (one chat name), or a **list/set** of names.
+
+| Method | Description |
+|--------|--------------|
+| **`send_msg(text, chat=None)`** | Text message |
+| **`reply_to_msg(text, msg_id, chat=None)`** | Reply to a message |
+| **`send_img(photo_path, caption=None, chat=None)`** | Photo |
+| **`send_file(file_path, caption=None, chat=None)`** | Document |
+| **`send_position(latitude, longitude, chat=None)`** | Location |
+| **`send_buttons(text, buttons, chat=None)`** | Message with inline keyboard (see below) |
+| **`send_log(limit=None, chat=None)`** | Last `limit` lines of log file (or full) |
+| **`send_info(chat=None)`** | Bot info (chats, handlers, API server) |
+| **`send_registered_handlers(chat=None)`** | List of registered handlers (debug) |
+
+**Inline buttons:** `buttons` is a list of rows; each row is a list of `{"text": "...", "value": "..."}` (value = callback_data).
+
+```python
+bot.send_buttons("Choose:", [
+    [{"text": "Red", "value": "red"}, {"text": "Blue", "value": "blue"}],
+    [{"text": "Cancel", "value": "cancel"}],
+])
+```
+
+CamelCase aliases exist: `sendMsg`, `replyToMsg`, `sendImg`, `sendFile`, `sendPosition`, `sendButtons`, `sendLog`, `sendInfo`, `sendRegisteredHandlers`.
+
+---
+
+## Handlers
+
+**Replace-by-name:** If you register a handler whose function has the same **name** as an existing one (same type: message, command, or callback), the new handler **replaces** the old one. So in the REPL you can redefine `handle_message` and only the latest version will run.
+
+Handlers run in a **background thread**; inside them use the global proxies **`TgMsg`**, **`TgCmd`**, **`TgCb`**, **`TgArgs`** to access the current payload. **`chat`** filters which chats trigger the handler: `None` = default chat, string = one chat, list/set = multiple chats.
+
+### Message handler
+
+```python
+@bot.on_message()           # default chat
+@bot.on_message("chat1")    # only chat1
+@bot.on_message(["chat1", "chat2"])
+
+def on_message():
+    # TgMsg: .text, .msgId, .chatId, .userId, .userName, .timestamp, .raw_update
+    bot.send_msg(f"Echo: {TgMsg.text}")
+```
+
+### Command handler
+
+```python
+@bot.on_command("start")
+@bot.on_command("help", "chat1")
+
+def on_start():
+    # TgCmd: .command, .args, .msgId, .chatId, .userId, .userName, .timestamp, .raw_update
+    bot.send_msg(f"Welcome {TgCmd.userName}!")
+    if TgCmd.args:
+        bot.send_msg(f"You said: {TgCmd.args}")
+```
+
+### Callback handler (inline buttons)
+
+```python
+@bot.on_callback("chat1")
+
+def on_callback():
+    # TgCb: .text, .value, .msgId, .chatId, .userId, .userName, .timestamp, .raw_update
+    if TgCb.value == "red":
+        bot.send_msg(f"You pressed {TgCb.text} -> {TgCb.value}")
+```
+
+### API request handler
+
+Register a POST route; the embedded server starts automatically when the first route is registered.
+
+```python
+@bot.on_api_req("/action", args=["chat", "msg"])
+def action():
+    # TgArgs.get(key, default)
+    chat_id = TgArgs.get("chat")
+    msg = TgArgs.get("msg")
+    bot.send_msg(msg, chat=chat_id)
+```
+
+**TReq** – client to call these endpoints:
+
+```python
+from TgrEzLi import TReq
+
+TReq("/action").host("127.0.0.1").port(9999).arg("chat", "chat1").arg("msg", "Hello!").send()
+# or
+TReq("/action").body({"chat": "chat1", "msg": "Hello!"}).send()
+```
+
+`.host()`, `.port()`, `.timeout(seconds)` are optional (defaults: localhost, 9999, 30s). `.send()` returns a `requests.Response`; on failure raises **`TgrezliRequestError`**.
+
+CamelCase decorator aliases: `onMessage`, `onCommand`, `onCallback`, `onApiReq`.
+
+---
+
+## Data interfaces (handler context)
+
+Use only **inside** the corresponding handler; otherwise `TgMsg` / `TgCmd` / `TgCb` / `TgArgs` raise if accessed.
+
+| Proxy | Handler | Main fields |
+|-------|---------|-------------|
+| **TgMsg** | `on_message` | `text`, `msgId`, `chatId`, `userId`, `userName`, `timestamp`, `raw_update` |
+| **TgCmd** | `on_command` | `command`, `args`, `msgId`, `chatId`, `userId`, `userName`, `timestamp`, `raw_update` |
+| **TgCb** | `on_callback` | `text`, `value`, `msgId`, `chatId`, `userId`, `userName`, `timestamp`, `raw_update` |
+| **TgArgs** | `on_api_req` | `TgArgs.get(key, default)` for POST body |
+
+All IDs/names are available as both **snake_case** (e.g. `msg_id`) and **camelCase** (e.g. `msgId`) on the data objects.
+
+---
+
+## Stopping
+
+**`stop()`** stops polling and the API server; if **`run()`** was blocking, it returns. Call **`stop()`** via **Ctrl+C** (SIGINT is handled) or from another thread. After that, to use the bot again you must call **`connect()`** (or **`login()`**) again.
+
+---
+
+## Project layout
+
+- **`TgrEzLi`** – main package
+  - **`TEL`** – bot class (core)
+  - **`TgMsg`, `TgCmd`, `TgCb`, `TgArgs`** – handler context proxies (from `TgrEzLi.models`)
+  - **`TReq`, `TgrezliRequestError`** – HTTP client for the embedded API
+  - **`TgrezliConfig`** – config dataclass (from `TgrEzLi.types`)
+- **`TgrEzLi.crypto`** – **`CredentialManager`** (uses PyCypherLib): `signup(token, chat_dict, password)`, `login(password)`.
+
+Logging is done with **ezlog** on the console; if `save_log` is true, the same messages are appended to the configured log file.
+
+---
+
+## Security and robustness
+
+- **API server**: POST body size limited (default 1 MiB); invalid JSON returns 400; unknown route 404. No built-in authentication – protect the server (e.g. firewall, reverse proxy, or add your own auth in routes).
+- **Credentials**: Stored in an encrypted file when using `signup`/`login` (PyCypherLib); decryption only with the correct password. Keep the file and password secure.
+- **Handlers**: User code runs in daemon threads; exceptions are logged and do not crash the bot.
+
+---
+
+## License
+
+MIT License. Copyright (c) eaannist.

tgrezli-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+TgrEzLi/__init__.py,sha256=uZ3rxEEzV3dn3Lk4gfvF1IzRlv9HpZEZWPaMEwyRpCI,731
+TgrEzLi/api_server.py,sha256=O_2oU0rs6su6IfDwYjyPm0h6BzhU6a6Qr_B1xSZJbow,5107
+TgrEzLi/config.py,sha256=iyeOUaoIlEozBDl-FNOCXE1IakQaKUrmdRu78vnrkUk,139
+TgrEzLi/core.py,sha256=VSARuDsIqFRFYgeeL8oTMe74RKrPsZiXnN8-q1ShOQI,21075
+TgrEzLi/crypto.py,sha256=UkiaNoI0ScPXBZNVQrpCfkKKs4pftody_B0groU3qfY,1492
+TgrEzLi/defaults.py,sha256=MNRbQs0BmJAd0fbWo_5I7Y5VVR02lD4rkWnqs9aHKbE,351
+TgrEzLi/handlers.py,sha256=qK_sE4BhOkSBEBGvUiJoC_jVyn1COlCVZk2593GIWvY,2939
+TgrEzLi/logger.py,sha256=n2ZiCFishdrgNTuba2ixeeCkHNWQeX3W7dfpNLGzRK8,2075
+TgrEzLi/models.py,sha256=tq8Sf8eyk_IrUC8yTt3rk5yoFGQyN4X4rTubDGgdv2M,2249
+TgrEzLi/requests.py,sha256=kOT1tre22sI8JjWWi02n5PgOrweDpOrhVSON-BACE6Y,1532
+TgrEzLi/types.py,sha256=dc_n91cwjXkPCVbA1ph68PeBJP_r3WG5iUFW6vttXWo,2427
+tgrezli-0.4.0.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+tgrezli-0.4.0.dist-info/entry_points.txt,sha256=gzH98n-evOMN1c_uOoDPPy5B4eQhFfcT6mm0ghZ7vjY,42
+tgrezli-0.4.0.dist-info/METADATA,sha256=ocKyCTPFfmq9iqdfUeCs61bMjfVX7RVzoq1n9vRm084,10472
+tgrezli-0.4.0.dist-info/RECORD,,

{tgrezli-0.1.2.dist-info → tgrezli-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.1)
+Generator: uv 0.9.27
 Root-Is-Purelib: true
 Tag: py3-none-any
-

tgrezli-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+TgrEzLi = TgrEzLi:main
+

tgrezli-0.1.2.dist-info/METADATA

@@ -1,238 +0,0 @@
-Metadata-Version: 2.2
-Name: TgrEzLi
-Version: 0.1.2
-Summary: Easy-to-use synchronous interface for telegram-bot library with async backend and intuitive handlers.
-Home-page: https://github.com/eaannist/TgrEzLi
-Author: eaannist
-Author-email: eaannist@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-Requires-Dist: python-telegram-bot>=20.0
-Requires-Dist: requests>=2.28.0
-Requires-Dist: PyCypherLib>=1.3.5
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# TgrEzLi
-
-**TgrEzLi** is a Python library based [telegram-bot](https://pypi.org/project/python-telegram-bot/) that simplifies Telegram bot development by providing a synchronous interface, runs in background with non-blocking operations and offers intuitive handlers for messages, commands, callbacks, and API requests.
-
-## Installation
-
-```bash
-pip install TgrEzLi
-
-```
-## Usage
-
-```python
-
-
-# Importing the library
-from TgrEzLi import TEL, TgMsg, TgCmd, TgCb, TgArgs, TReq
-# or
-from TgrEzLi import *
-
-# Initialization
-bot = TEL()
-
-# Some options
-# Activate/Deactivate log saving
-bot.setSaveLog(True)
-
-# Set custom HTTP host and port; by default they are "localhost" and 9999
-bot.setHost("127.0.0.1")
-bot.setPort(8080)
-
-# Connecting
-# You can connect one or multiple chats
-TOKEN = "123456789:ABCDEFGHIJKLMNO"
-CHAT_DICT = {
-    "chat1": "123456789",
-    "chat2": "789456123"
-}
-
-# You can use the .connect() method that takes token and chat dictionary as argument.
-bot.connect(TOKEN, CHAT_DICT)
-
-# You can alsouse the .signup() and .login() methods to insert token and chats only once and secure them with a password
-bot.signup(TOKEN, CHAT_DICT, 'password') # only once; it'll store encrypted data in a tgrdata.cy file
-bot.login('password') # when already 'signed up'
-
-# Basic commands to send Messages, Images, Files, Position, Log, Handlers, Bot Info
-# Each method has a chat parameter, by defailt it's set to the first chat added to the dictionary
-# You can either insert a specific chat name or a List 
-bot.sendMsg(text, chat)
-bot.sendImg(photo_path, caption, chat)
-bot.sendFile(file_path, caption, chat)
-bot.sendPosition(latitude, longitude, chat)
-bot.replyToMsg(text, msg_id, chat_id)
-bot.sendLog(limit, chat)
-bot.sendInfo(chat)
-bot.sendRegisteredHandlers(chat)
-
-# Methods to create and send Inline Keyboards (simply called Buttons)
-bot.sendButtons(text, buttons, chat)
-
-# Handlers for Messages, Commands, and Callbacks
-# Each method has a chat parameter, by defailt it's set to the first chat added to the dictionary
-# You can either insert a specific chat name or a List 
-@bot.onMessage(chat)
-@bot.onCommand(command, chat)
-@bot.onCallback(chat)
-@bot.onApiReq(endpoint, args, host, port)
-
-# Data Interfaces
-# Each Handler has it's own integrated interface to easly access received data
-
-# TgMsg gets received messages data for .onMessage() handler
-TgMsg.text
-    .msgId
-    .chatId
-    .userId
-    .userName
-    .timestamp
-    .raw_update 
-
-# TgCmd gets data and parameters for .onCommand() handler
-TgCmd.command
-    .args       # gives text outside the command
-    .msgId
-    .chatId
-    .userId
-    .userName
-    .timestamp
-    .raw_update
-
-# TgCb gets data for .onCallback() handler
-TgCb.text
-    .value
-    .msgId
-    .chatId
-    .userId
-    .userName
-    .timestamp
-    .raw_update
-
-# TgArgs gets parameters for .onApiReq() handler
-TgArgs.get(key, default)
-
-
-# Treq makes it really easy to send an api request
-# It takes the endpoint path like "\action"
-# .host and .port are optional, by default "localhost" and 9999
-# you can add multiple .arg() methods to add parameters names and values
-# or you can use .body() to send the full body
-TReq(endpoint)\
-    .host(host)\
-    .port(port)\
-    .arg(name, value)\
-    .body(body_dict)\
-    .send()
-
-## Examples ##
-
-# basic commands
-bot.sendMsg("Message Test")
-bot.sendImg("img.jpg", "Image Test", 'chat1')
-bot.sendFile("file.pdf", "File Test", ['chat1', 'chat2'])
-bot.sendPosition(45.4642, 9.1900, ['chat1', 'chat2'])
-
-
-# Message Handler
-@bot.onMessage()
-def on_message_default_chat():
-    bot.sendMsg(f"Hi {TgMsg.userName}! You wrote: {TgMsg.text}")
-    reply = f"Message Id: {TgMsg.msgId} User Id: {TgMsg.userId} Raw: {TgMsg.raw_update}"
-    bot.replyToMsg(reply, msg_id=TgMsg.msgId)
-
-
-# Command Handler
-@bot.onCommand("/start")
-def handle_start():
-    bot.sendMsg(f"Welcome to chat 1 {TgCmd.userName}!")
-    if TgCmd.args : bot.sendMsg(f"You also wrote: {TgCmd.args}!")
-
-@bot.onCommand("/start", 'chat2')
-def handle_start():
-    bot.sendMsg(f"Welcome to chat 2 {TgCmd.userName}!")
-
-
-# Buttons
-@bot.onCommand("/buttons", 'chat1')
-def show_buttons():
-    buttons = [
-        [{"text": "Button 1", "value": "red"}],
-        [{"text": "Button 2", "value": "yellow"}]
-    ]
-    bot.sendButtons("Scegli un colore:", buttons, "chat1")
-
-# Callback Handler
-@bot.onCallback("chat1")
-def on_callback_chat1():
-    match TgCb.value:
-        case "red":
-            bot.sendMsg(f"You pressed {TgCb.text} -> {TgCb.value}!", "chat1")
-        case "yellow":
-            bot.sendMsg(f"You pressed {TgCb.text} -> {TgCb.value}!", "chat1")
-
-
-# Api Requests
-@bot.onApiReq('/action', args=['chat','msg'])
-def action():
-    id = TgArgs.get('chat')
-    msg = TgArgs.get('msg')
-    bot.sendMsg(msg, id)
-
-# TReq usage
-TReq('/action')\
-    .host('127.0.0.1')\
-    .port(8080)\
-    .arg('chat_id', 'chat1')\
-    .arg('msg', 'Hello from TReq!')\
-    .send()
-
-while True:
-    pass
-
-
-```
-
-## License
-
-```txt
-MIT License
-
-Copyright (c) 2025 eaannist
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-## Development status
-
-**TgrEzLi** is a work-in-progress personal project. Suggestions, feature requests, and constructive feedback are highly welcome. Feel free to open an issue or submit a pull request.

tgrezli-0.1.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-TgrEzLi/__init__.py,sha256=JhvTNfAcvISzUb0MmLd0aKjb2F_CggnzVLpOKraoVis,153
-TgrEzLi/core.py,sha256=QowwsI4I1Pxibg8ZyDImJSc7z4yQQqRzktmKaVfs0eY,19306
-tgrezli-0.1.2.dist-info/METADATA,sha256=VGU062ETN5qs37yuqeI-DDMIeXJiuR1hd1EO3Jm8y9k,7173
-tgrezli-0.1.2.dist-info/WHEEL,sha256=nn6H5-ilmfVryoAQl3ZQ2l8SH5imPWFpm1A5FgEuFV4,91
-tgrezli-0.1.2.dist-info/top_level.txt,sha256=lkqdMjPkTomQ4pU2UGwbMrrXye2b76cJX1qc3w95skI,8
-tgrezli-0.1.2.dist-info/RECORD,,

tgrezli-0.1.2.dist-info/top_level.txt

@@ -1 +0,0 @@
-TgrEzLi