python-trueconf-bot 1.2.0b3__tar.gz → 1.2.2__tar.gz

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-trueconf-bot
-Version: 1.2.0b3
+Version: 1.2.2
 Summary: Lightweight and powerful framework for the TrueConf Server Chatbot API
 Author-email: TrueConf LLC <info@trueconf.com>, Anton Baadzhi <baadzhianton@gmail.com>
 License-Expression: BSD-3-Clause-Clear
@@ -34,6 +34,7 @@ Requires-Dist: typing_extensions>=4.15.0
 Requires-Dist: python-magic>=0.4.27; sys_platform != "win32"
 Requires-Dist: python-magic-bin==0.4.14; sys_platform == "win32"
 Requires-Dist: filetype
+Requires-Dist: packaging
 Dynamic: license-file
 
 <p align="center">
@@ -77,23 +78,30 @@ Dynamic: license-file
 > 💡TIP
 > 
 > We were inspired by the popular [aiogram](https://github.com/aiogram/aiogram/) library, so, the transition will be **simple** for developers already familiar with this library.
-
 ---
 
+## ⚙️ Install
+
+You can install `python-trueconf-bot` using `pip`:
+
+```bash
+pip install python-trueconf-bot
+```
+
+Or with `uv` (recommended):
+
+```bash
+uv add python-trueconf-bot
+```
+
+
 ## 📦 Version Compatibility
 
 | TrueConf Server Version | Required Library Version |
 |:------------------------|:-------------------------|
-| < 5.5.0                 | ❌ Not supported         |
+| < 5.5.0                 | ❌ Not supported          |
 | 5.5.0 — 5.5.2           | v1.1.x                   |
-| >= 5.5.3                | **v1.2.0** (or higher)   |
-
-> ⚠️ IMPORTANT
-> 
-> If you are using server version **5.5.3** or higher, you must upgrade the library. If the stable release is not yet available, install the latest beta:
-> ```bash
-> uv pip install --pre "python-trueconf-bot>=1.2.0b0"
-> ```
+| >= 5.5.3                | **v1.2.1** (or higher)   |
 
 ## 📌 Key Features
 

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/README-PyPI.md

@@ -39,23 +39,30 @@
 > 💡TIP
 > 
 > We were inspired by the popular [aiogram](https://github.com/aiogram/aiogram/) library, so, the transition will be **simple** for developers already familiar with this library.
-
 ---
 
+## ⚙️ Install
+
+You can install `python-trueconf-bot` using `pip`:
+
+```bash
+pip install python-trueconf-bot
+```
+
+Or with `uv` (recommended):
+
+```bash
+uv add python-trueconf-bot
+```
+
+
 ## 📦 Version Compatibility
 
 | TrueConf Server Version | Required Library Version |
 |:------------------------|:-------------------------|
-| < 5.5.0                 | ❌ Not supported         |
+| < 5.5.0                 | ❌ Not supported          |
 | 5.5.0 — 5.5.2           | v1.1.x                   |
-| >= 5.5.3                | **v1.2.0** (or higher)   |
-
-> ⚠️ IMPORTANT
-> 
-> If you are using server version **5.5.3** or higher, you must upgrade the library. If the stable release is not yet available, install the latest beta:
-> ```bash
-> uv pip install --pre "python-trueconf-bot>=1.2.0b0"
-> ```
+| >= 5.5.3                | **v1.2.1** (or higher)   |
 
 ## 📌 Key Features
 

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/README-ru.md

@@ -43,19 +43,27 @@
 > знакомым с ней, переход будет **простым** и **безболезненным**.
 
 ---
+## ⚙️ Устнановка
+
+Вы можете установить `python-trueconf-bot` с помощью `pip`:
+
+```bash
+pip install python-trueconf-bot
+```
+
+или с помощью `uv` (предпочтительно):
+
+```bash
+uv add python-trueconf-bot
+```
+
 
 ## 📦 Совместимость версий
 | Версия сервера TrueConf | Требуемая версия библиотеки |
-|:------------------------|:---------------------------|
-| < 5.5.0                 | ❌ Не поддерживается                         |
-| 5.5.0 — 5.5.2           | v1.1.x                     |
-| \>= 5.5.3               | **v1.2.0** (или выше)      |
-
-> [!IMPORTANT] 
-> Если вы используете сервер версии **5.5.3** или выше, вам необходимо обновить библиотеку. Если стабильный релиз еще не доступен, установите последнюю бету:
-> ```bash
-> uv pip install --pre "python-trueconf-bot>=1.2.0b0"
-> ```
+|:------------------------|:----------------------------|
+| < 5.5.0                 | ❌ Не поддерживается         |
+| 5.5.0 — 5.5.2           | v1.1.x                      |
+| \>= 5.5.3               | **v1.2.1** (или выше)       |
 
 ## 📌 Ключевые возможности
 

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/README.md

@@ -46,20 +46,27 @@
 > We were inspired by the popular [aiogram](https://github.com/aiogram/aiogram/) library, so, the transition will be **simple** for developers already familiar with this library.
 
 ---
+## ⚙️ Install
 
-## 📦 Version Compatibility
+You can install `python-trueconf-bot` using `pip`:
+
+```bash
+pip install python-trueconf-bot
+```
+
+Or with `uv` (recommended):
+
+```bash
+uv add python-trueconf-bot
+```
+
+## 📦  Compatibility
 
 | TrueConf Server Version | Required Library Version |
 |:------------------------|:-------------------------|
-| < 5.5.0                 | ❌ Not supported         |
+| < 5.5.0                 | ❌ Not supported          |
 | 5.5.0 — 5.5.2           | v1.1.x                   |
-| >= 5.5.3                | **v1.2.0** (or higher)   |
-
-> [!IMPORTANT]
-> If you are using server version **5.5.3** or higher, you must upgrade the library. If the stable release is not yet available, install the latest beta:
-> ```bash
-> uv pip install --pre "python-trueconf-bot>=1.2.0b0"
-> ```
+| >= 5.5.3                | **v1.2.1** (or higher)   |
 
 ## 📌 Key Features
 

python_trueconf_bot-1.2.2/docs/en/examples/index.md

@@ -0,0 +1,245 @@
+# Examples
+
+## Echo bot
+
+```python
+import asyncio
+from trueconf import Bot, Dispatcher, Router, Message, F, ParseMode
+from os import getenv
+
+router = Router()
+dp = Dispatcher()
+dp.include_router(router)
+
+TOKEN = getenv("TOKEN")
+
+bot = Bot(server="video.example.com", token=TOKEN, dispatcher=dp)
+
+
+@router.message(F.text)
+async def echo(msg: Message):
+    await msg.answer(f"You says: **{msg.text}**", parse_mode=ParseMode.MARKDOWN)
+
+
+async def main():
+    await bot.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Webhook (e.g., for Zabbix)
+
+In this example, you can see how easy it is to set up a webhook using FastAPI to receive requests from external systems, such as Zabbix.
+
+You can also protect your webhook with authentication or allow requests only from specific IP addresses. All of this can be configured in [FastAPI](https://fastapi.tiangolo.com/).
+
+```python
+import asyncio
+import logging
+import os
+from typing import Any
+from trueconf import Bot
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+import uvicorn
+
+os.makedirs("logs", exist_ok=True)
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    filename="logs/bot.log",
+    encoding="utf-8",
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    bot_task = asyncio.create_task(bot.run())
+    yield
+
+app = FastAPI(lifespan=lifespan)
+bot = Bot.from_credentials(
+    server="10.140.1.255",
+    username="echo_bot",
+    password="123tr",
+    verify_ssl=False)
+
+
+@app.post("/send")
+async def read_root(data: dict[str, Any]):
+    r = await bot.create_personal_chat(user_id="user")
+    r = await bot.send_message(chat_id = r.chat_id, text=str(data))
+    print(r.message_id)
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+## Bulk add users to a channel
+
+```python
+from trueconf import Bot
+from trueconf.exceptions import ApiErrorException
+import asyncio
+import logging
+from pathlib import Path
+
+SERVER_ADDR = ""
+BOT_USERNAME = ""
+BOT_PASSWORD = ""
+PATH_LIST_USERS = ""
+CHANNEL_NAME = ""
+
+bot = Bot.from_credentials(
+    server=SERVER_ADDR,
+    username=BOT_USERNAME,
+    password=BOT_PASSWORD,
+    verify_ssl=False,
+)
+
+Path("logs").mkdir(parents=True, exist_ok=True)
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    filename="logs/bot.log",
+    encoding="utf-8",
+)
+
+async def main():
+    await bot.start()
+    await bot.connected_event.wait()
+    await bot.authorized_event.wait()
+
+    resp = await bot.create_channel(title=CHANNEL_NAME)
+    with open(PATH_LIST_USERS, "r") as file:
+        for line in file:
+            user_id = line.strip()
+            if user_id:
+                try:
+                    await bot.add_participant_to_chat(resp.chat_id, user_id=user_id, display_history=True)
+                except ApiErrorException as e:
+                    if e.code == 309:
+                        continue
+
+    await bot.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Multibot
+
+The TrueConf team has prepared an example that demonstrates the use of four bots at once (all-in-one):
+
+- Echo bot
+- Sick-leave bot that forwards messages to an HR group
+- Monitoring bot for external service statistics (TrueConf Server)
+- GPT bot that runs a local LLM model in the background
+
+
+[View repository :fontawesome-solid-arrow-right:](https://github.com/TrueConf/trueconf-chatbot-example){ .md-button }
+
+## Support Reporting Bot
+
+```python
+"""
+Below is the initial scaffold for a bot that collects support reports.
+
+- /report creates a router/state to capture and parse messages from a specific user.
+- /cancel cancels the ticket and removes the user from this state.
+- /send emails the collected messages — this is where you implement the logic to assemble the email (body + attachments) and send it.
+You can use built-in modules, and third-party libraries if needed.
+"""
+
+import asyncio
+import uuid
+import trueconf
+from trueconf import *
+from trueconf.filters import Command
+
+r1 = Router()
+dp = Dispatcher()
+dp.include_router(r1)
+
+router_list_for_report = {}
+list_message_for_report = {}
+
+bot = trueconf.Bot.from_credentials(
+    server="10.110.2.241",
+    username="report_bot",
+    password="123tr",
+    dispatcher=dp,
+    https=True,
+    verify_ssl=False)
+
+async def handle_report(msg: Message):
+    if msg.from_user.id in router_list_for_report.keys():
+        list_message_for_report[msg.from_user.id].append(msg)
+        await msg.answer("The message has been added to the report.")
+
+
+@r1.message(Command("report"))
+async def on_report(msg: Message):
+    number = uuid.uuid4() # генерация номера обращения с помощью uuid
+    await msg.answer(f"Your ticket number is {number}. All subsequent messages will be added to this ticket.")
+    r = Router(name=str(number))
+    dp.include_router(r)
+    r.message(F.from_user.id == msg.from_user.id)(handle_report)
+    router_list_for_report.update({msg.from_user.id: r})
+    list_message_for_report.update({msg.from_user.id: []})
+
+
+@r1.message(Command("cancel"))
+async def on_cancel(msg: Message):
+    if msg.from_user.id in router_list_for_report.keys():
+        for router in dp.routers:
+            if router.name == router_list_for_report[msg.from_user.id].name:
+                dp.routers.remove(router)
+                router_list_for_report.pop(msg.from_user.id)
+                list_message_for_report.pop(msg.from_user.id)
+                await msg.answer("The report has been cancelled.")
+                break
+    else:
+        await msg.answer("You don’t have an active report.")
+
+
+def build_message_and_send_email(messages:list):
+    """
+    In Python, there are built-in libraries for working with email messages:
+    https://docs.python.org/3/library/email.examples.html
+
+    Here, you need to take the data from list_message_for_report[msg.from_user.id]
+    and build an email-ready representation:
+
+    for msg in message:
+        match msg.content_type:
+            case MessageType.TEXT:
+                # You can put the text into the email body
+            case MessageType.ATTACHMENT:
+                # Download the files from TrueConf Server via:
+                # msg.download(dest_path="path/to/file")
+
+    Once the email is assembled correctly, send it using the smtplib module:
+    https://docs.python.org/3/library/smtplib.html#smtp-example
+    """
+
+@r1.message(Command("send"))
+async def send_report(msg: Message):
+    if msg.from_user.id in router_list_for_report.keys():
+        if build_message_and_send_email(list_message_for_report[msg.from_user.id]):
+            await msg.answer("Your request has been successfully submitted to Technical Support.")
+        else:
+            await msg.answer("An error occurred. Please contact the bot developer.")
+    else:
+        await msg.answer("You don’t have an active report.")
+        return
+
+if __name__ == "__main__":
+    asyncio.run(bot.run())
+```
+
+
+

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/docs/en/index.md

@@ -41,3 +41,8 @@ pip install {{product_name}}
 | JSON → Python       | Pydantic models                                | Mashumaro dataclasses                                                                     |
 | Transport           | HTTPS + long polling / webhook                 | Asynchronous WebSocket                                                                    |
 | Working with files  | `bot.get_file(...)` + `bot.download_file(...)` | `message.photo.download()`, `message.document.download()`, `bot.download_file_by_id(...)` |
+
+## LLM Files
+
+- [llms.txt](llms.txt)
+- [llms-full.txt](llms-full.txt)

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/docs/en/learn/files.md

@@ -141,3 +141,49 @@ await bot.download_file_by_id(
     dest_path="document.pdf"
 )
 ```
+
+## MIME Type Detection with python-magic
+
+A file’s MIME type can be detected automatically. The library supports two approaches:
+
+* **By file extension** — works without additional dependencies, but may be inaccurate.
+* **By file content (bytes)** — significantly more accurate, but requires `python-magic`.
+
+### How It Works
+
+The `python-magic` package does not determine MIME types on its own. It is a Python wrapper around the native **libmagic** library written in C, which is what actually identifies a file type based on its contents.
+
+That is why `python-magic` may not work out of the box on some systems: the Python package is installed via `pip`, but the system library `libmagic` must be installed separately.
+
+If `libmagic` is missing, importing `magic` may fail with an error such as:
+
+* `ImportError: failed to find libmagic. Check your installation`
+
+### Installation
+
+Install the system dependencies:
+
+* **macOS (Homebrew):**
+
+  ```bash
+  brew install libmagic
+  ```
+
+* **Linux (Debian/Ubuntu):**
+
+  ```bash
+  sudo apt install libmagic1
+  ```
+
+* **Windows:**
+
+  ```bash
+  pip install python-magic-bin
+  ```
+
+We also recommend reviewing the repository: [https://github.com/ahupp/python-magic](https://github.com/ahupp/python-magic).
+
+### Notes
+
+* When `python-magic` is available, the MIME type is detected **from the file bytes**, which is usually more accurate than detecting it by filename or extension.
+

{python_trueconf_bot-1.2.0b3 → python_trueconf_bot-1.2.2}/docs/en/learn/filters.md

@@ -215,8 +215,90 @@ F.text.upper().in_({"FOO", "BAR"}) # message.text.upper() in {"FOO", "BAR"}
 F.text.len() == 5                  # len(message.text) == 5
 ```
 
+## Building Custom Filters
+
+You can build custom filters to fine-tune your event-handling logic. This allows you to move condition checks—such as verifying whether a user exists in the database or checking access permissions—into a separate, reusable component.
+
+**Implementation requirements:**
+
+* **Class-based structure:** A custom filter must be implemented as a class. This makes it possible to preserve state, such as filter settings, when the filter is initialized.
+* **`__call__` method:** The class must implement a `__call__` method. Without it, the class instance will not be considered callable, and the filter will not work.
+* **Return value:** The `__call__` method must return `True` if the event matches the filter conditions, or `False` if the event should be ignored by the handler.
+
+```python
+from typing import Any
+
+class MyFilter:
+    """
+    This filter checks whether a user belongs 
+    to the specified group via the server API.
+    """
+
+    def __init__(self, target_group: str):
+        # Store the required group when creating the instance
+        self.target_group = target_group
+
+    async def __call__(self, event: Any) -> bool:
+        user = getattr(event, "from_user", None)
+        if not user:
+            return False
+
+        user_id = user.id
+        # Perform the check, for example via an API call
+        user_info: dict = await server_api.get_user(user_id)
+        groups = user_info.get("groups", [])
+
+        # Make sure to return True or False
+        return any(group.get("id") == self.target_group for group in groups)
+```
+
+Once the filter class is defined, you can use it in handler decorators exactly the same way as the built-in **Command** or **F** filters. When registering a handler, simply pass an instance of your class as an argument.
+
+```python hl_lines="8"
+from aiogram import Router, Message
+# Import your filter class
+from my_filters import MyFilter
+
+router = Router()
+
+# Attach the filter in the same way as Command or F
+@router.message(MyFilter(target_group="0032"))
+async def my_handler(message: Message):
+    await message.answer("Access granted: you belong to the required group!")
+```
+
+When a message is received, the bot will use the class instance, call its `__call__` method, and, if it returns `True`, execute the handler code.
+
 ## Combining Filters
 
+In **python-trueconf-bot**, you can combine multiple filters within a single handler. By default, when filters are separated by commas, they use **AND** logic—the handler will run only if **all** filters return `True`.
+
+**Command and a custom filter**
+
+You can restrict access to a specific command by using your own filter. The handler will run only if the message is the specified command **and** your filter returns `True`.
+
+```python
+# Triggers if the /admin command is received 
+# AND the user belongs to group "0032"
+@r.message(Command("admin"), InGroupFilter(target_group="0032"))
+async def admin_panel(message: Message):
+    await message.answer("Welcome to the admin panel!")
+```
+
+**MagicFilter (F) and a custom filter**
+
+Combine message-content checks with your own access rules. For example, you can react to a specific word in the text only for users from certain groups:
+
+```python
+# Triggers if the text contains "help"
+# AND the user belongs to the "support" group
+@r.message(F.text.contains("help"), InGroupFilter(target_group="0003"))
+async def support_handler(message: Message):
+    await message.answer("The support team has been notified of your request.")
+```
+
+### Combining Command Arguments and MagicFilter
+
 Combining **Command** and **MagicFilter** is a common and recommended practice:
 **Command** parses the command and creates a **CommandObject**, while `magic`
 allows you to impose additional conditions on `args` or other parts of the