python-trueconf-bot 1.2.3__tar.gz → 1.3.0__tar.gz

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-trueconf-bot
-Version: 1.2.3
+Version: 1.3.0
 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
@@ -35,6 +35,7 @@ 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
+Requires-Dist: truststore
 Dynamic: license-file
 
 <p align="center">

python_trueconf_bot-1.3.0/docs/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/websites/trueconf_github_io_python-trueconf-bot",
+  "public_key": "pk_oAuw9GgMszB6caKRldtnP"
+}

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/examples/index.md

@@ -1,4 +1,9 @@
-# Examples
+---
+title: Code examples
+icon: material/console
+---
+
+# Code examples
 
 ## Echo bot
 

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/features.md

@@ -1,3 +1,8 @@
+---
+title: Features
+icon: material/feather
+---
+
 # Features
 
 ## Asyncio-based Asynchronous Architecture

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/index.md

@@ -1,3 +1,8 @@
+---
+title: Home
+icon: material/home-variant
+---
+
 # Python Library for TrueConf Chatbot Connector
 
 <img src="img/head.png" alt="">

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/learn/enums.md

@@ -1,3 +1,8 @@
+---
+title: Using enumerations
+icon: material/alphabet-latin
+---
+
 # Using enumerations
 
 In the **{{product_name}}** library, many method parameters and object fields are defined through **enums** (enumerations).

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/learn/files.md

@@ -1,6 +1,6 @@
 ---
 title: Working with files
-icon:
+icon: material/file-sync 
 ---
 
 # Working with Files

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/learn/filters.md

@@ -1,6 +1,6 @@
 ---
 title: Filters
-icon:
+icon: material/filter
 ---
 
 # Filters

python_trueconf_bot-1.3.0/docs/en/learn/getting-started.md

@@ -0,0 +1,272 @@
+---
+title: Getting Started
+icon: material/run
+---
+
+# Getting Started
+
+Before getting started, we recommend creating and activating a virtual environment to isolate your project dependencies:
+
+```shell
+python -m venv .venv
+source .venv/bin/activate   # Linux / macOS
+.venv\Scripts\activate      # Windows PowerShell
+```
+
+## Installing {{product_name}}
+
+To begin working with {{product_name}}, install the package from the global PyPI repository:
+
+```shell
+pip install {{product_name}}
+```
+
+!!! info
+    Upon installation, dependencies will be automatically pulled in: `websockets`, `httpx`, `mashumaro`, `pillow`, `aiofiles`, `magic-filter`.
+
+## Creating a Basic Echo Bot
+
+First, import the required classes:
+
+```python
+from trueconf import Bot, Dispatcher, Router, F
+from trueconf.types import Message
+```
+
+Next, create instances of `Router` and `Dispatcher` and connect them:
+
+```python
+r = Router()
+dp = Dispatcher()
+# dp.include_router(r)
+```
+
+The bot supports two types of authentication: token-based or login/password. You can choose the most convenient method.
+
+### Token-Based Authentication
+
+If you're using token-based connection, obtain the token as described in the [official API documentation](https://trueconf.ru/docs/chatbot-connector/ru/connect-and-auth/#access-token).
+
+It is recommended to store the token in an environment variable or `.env` file. Don’t forget to add `.env` to `.gitignore` if working with public repositories.
+
+```python
+from os import getenv
+
+TOKEN = getenv("TOKEN")
+bot = Bot(server="video.example.com", token=TOKEN, dispatcher=dp)
+```
+
+!!! Note
+    The token is valid for one month from the moment it is created.
+    However, an already authorized connection remains active until it is closed, even after the token has expired.
+    In theory, such a connection can persist for years.
+
+### Login/Password Authentication
+
+Use the `.from_credentials` method:
+
+```python
+bot = Bot.from_credentials(
+    username="echo_bot",
+    password="123tr",
+    server="10.110.2.240",
+    dispatcher=dp
+)
+```
+
+!!! info
+    Each time **from\_credentials()** is called, the bot requests a new token from the server.
+    The token lifespan is 1 month.
+
+### Message Handler
+
+Now let’s create a simple handler for incoming messages. It will reply with the same text (a classic "echo bot"):
+
+```python
+@r.message(F.text)
+async def echo(message: Message):
+    await message.answer(message.text)
+```
+
+### Running the Bot
+
+Run the bot inside an asynchronous `main()` function passed to `asyncio.run()`:
+
+```python
+async def main():
+    await bot.run()
+    
+import asyncio
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+!!! question "Why async/await?"
+    The **{{product_name}}** library is built on asyncio.
+
+This means that all network operations (connecting to the server, receiving and sending messages) are asynchronous and non-blocking. Therefore:
+
+* handlers are written as `async def`,
+* method calls use `await`,
+* the launch is managed via `asyncio.run(...)`.
+
+This approach allows handling multiple events and messages in parallel — without delays or blocking.
+
+### Automatic Connection Recovery
+
+If the WebSocket connection to the server is interrupted, the bot will not stop immediately. Instead, it will automatically attempt to reconnect and continue receiving events.
+
+Reconnection uses an exponential backoff strategy: after each failed attempt, the delay increases but does not exceed the `ws_max_delay` value. This helps prevent excessive requests to the server during temporary network issues.
+
+By default, the following reconnection parameters are used:
+
+```python hl_lines="5-6"
+bot = Bot(
+    server="video.example.com",
+    token=TOKEN,
+    dispatcher=dp,
+    ws_max_retries=5,
+    ws_max_delay=60,
+)
+```
+
+| Parameter        | Type  | Default | Description                                                                 |
+| ---------------- | ----- | ------- | --------------------------------------------------------------------------- |
+| `ws_max_retries` | `int` | `5`     | Maximum number of connection attempts on network/IP errors before giving up |
+| `ws_max_delay`   | `int` | `60`    | Maximum delay between reconnection attempts (in seconds)                    |
+
+If your bot runs in an unstable network environment or the server may be temporarily unavailable, you can increase these values:
+
+```python hl_lines="5-6"
+bot = Bot(
+    server="video.example.com",
+    token=TOKEN,
+    dispatcher=dp,
+    ws_max_retries=10,
+    ws_max_delay=120,
+)
+```
+
+!!! note
+    In case of a normal WebSocket disconnection, the bot will attempt to reconnect using exponential backoff.
+
+    If the server address is incorrect, the bot will not be able to establish a connection. In this case, the number of retry attempts is limited by `ws_max_retries`, after which a connection error will be raised.
+
+## Health-check
+
+{{product_name}} supports two approaches for checking bot state:
+
+- **push model** — the bot calls a callback function when the connection state changes;
+- **pull model** — the application manually requests the current state via `bot.health_check()`.
+
+### Push: callback on state changes
+
+The callback is passed via the `on_health_check` parameter when creating the bot.
+The function must be asynchronous and accept a dictionary with the current status:
+
+```python
+async def on_health_check(status: dict):
+    print("Bot status changed:", status)
+
+
+bot = Bot.from_credentials(
+    server="video.example.com",
+    username="echo_bot",
+    password="123tr",
+    dispatcher=dp,
+    on_health_check=on_health_check,
+)
+```
+
+The callback is triggered whenever the WebSocket connection or authorization state changes.
+For example, the bot may emit the following statuses:
+
+- `connected` — the WebSocket connection is established, but the bot is not authorized yet;
+- `authorized` — the bot has successfully authenticated;
+- `disconnected` — the connection has been lost.
+
+Example payload:
+
+```json
+{
+    "status": "authorized",
+    "websocket_connected": true,
+    "authorized": true,
+    "user_id": "echo_bot@video.example.com",
+    "server": "video.example.com",
+    "port": 443,
+    "protocol": "https",
+    "timestamp": "2026-05-06T12:00:00+00:00",
+}
+```
+
+The push model is useful when you need to react immediately to state changes: write logs, notify monitoring systems, update application state, or alert administrators.
+
+### Pull: manual health check
+
+The `bot.health_check()` method returns the current bot state at the moment it is called:
+
+```python
+status = bot.health_check()
+print(status)
+```
+
+Example response:
+
+```json
+{
+    "status": "authorized",
+    "websocket_connected": true,
+    "authorized": true,
+    "server": "video.example.com",
+    "port": 443,
+    "protocol": "https",
+    "timestamp": "2026-05-06T12:00:00+00:00",
+}
+```
+
+The pull model is useful for HTTP health-check endpoints, such as FastAPI, Zabbix, Kubernetes probes, or other monitoring systems:
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/health")
+def health():
+    return bot.health_check()
+```
+
+### Combining push and pull
+
+In practice, it is often convenient to use both approaches together.
+The callback updates the latest known state, while the HTTP endpoint exposes it to monitoring systems:
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+bot_status = {"status": "disconnected"}
+
+
+async def on_health_check(status: dict):
+    bot_status.update(status)
+
+
+bot = Bot.from_credentials(
+    server="video.example.com",
+    username="echo_bot",
+    password="123tr",
+    dispatcher=dp,
+    on_health_check=on_health_check,
+)
+
+
+@app.get("/health")
+def health():
+    return bot_status
+```
+
+In this setup, the bot reports state changes through the callback, while external monitoring systems retrieve the current status through HTTP requests.

{python_trueconf_bot-1.2.3 → python_trueconf_bot-1.3.0}/docs/en/learn/parse-messages.md

@@ -1,3 +1,8 @@
+---
+title: Handling Requests
+icon: material/routes
+---
+
 # Handling Requests
 
 ## Router

python_trueconf_bot-1.3.0/docs/en/learn/restrictions.md

@@ -0,0 +1,45 @@
+---
+title: Restrictions
+icon: material/alert-octagon-outline
+---
+
+# Restrictions
+
+The library performs pre-validation of certain TrueConf Server limits and raises exceptions before sending a request if a value exceeds the allowed threshold.
+
+#### Chat Title
+
+The maximum chat title length is `255` characters. If a longer title is provided, a [`GroupTitleTooLongError`](../reference/Exceptions.md/#trueconf.exceptions.GroupTitleTooLongError) or [`ChannelTitleTooLongError`](../reference/Exceptions.md/#trueconf.exceptions.ChannelTitleTooLongError) will be raised.
+
+#### Message Length
+
+The maximum length of a text message is `4096` visible characters. If this limit is exceeded, a [`TextMessageTooLongError`](../reference/Exceptions.md/#trueconf.exceptions.TextMessageTooLongError) will be raised.
+
+If you need to send a long message, for example an LLM-generated response, you can split it into multiple parts using `safe_split_text`:
+
+```python
+from trueconf.utils import safe_split_text
+
+for chunk in safe_split_text(long_text):
+    await bot.send_message(
+        chat_id=chat_id,
+        text=chunk,
+    )
+```
+
+The `safe_split_text(text)` function returns a list of chunks that can be sent sequentially.
+
+#### File Restrictions
+
+Limits on file size and allowed extensions are configured by the TrueConf Server administrator. The bot retrieves these parameters from the server and updates them when the settings change:
+
+```python
+bot.max_file_size: int | None
+bot.file_extension_filter_mode: str | None
+bot.file_extensions_list: set | None
+```
+
+When sending a file, the library checks its size and extension. If the file exceeds the allowed size, a [`FileSizeTooLargeError`](../reference/Exceptions.md/#trueconf.exceptions.FileSizeTooLargeError) will be raised. If the file extension is not allowed by server settings, an [`InvalidFileExtensionError`](../reference/Exceptions.md/#trueconf.exceptions.InvalidFileExtensionError) will be raised.
+
+!!! Note
+    File restrictions depend on the configuration of the specific TrueConf Server. If the administrator changes the maximum file size or the list of allowed extensions, the bot will automatically receive updated values on the next limits update event.

python_trueconf_bot-1.3.0/docs/en/learn/send_message.md

@@ -0,0 +1,224 @@
+---
+title: Sending messages
+icon: material/message-text-fast-outline
+---
+
+# Sending messages
+
+To send a message, the bot must know the `chat_id` of the target chat: a personal chat, group chat, or channel.
+
+## How to get `chat_id`?
+
+### Personal chats (P2P)
+
+To get the `chat_id` of a personal chat, use [`bot.create_personal_chat(user_id)`](../reference/Bot.md/#trueconf.Bot.create_personal_chat).
+If a personal chat with the user does not exist yet, the server will create it.
+If the chat already exists, the server will return the existing `chat_id`.
+
+```python
+chat = await bot.create_personal_chat(user_id="john_doe@video.example.com")
+
+await bot.send_message(
+    chat_id=chat.chat_id,
+    text="Hello!",
+)
+```
+
+### Group chats and channels
+
+Be careful with [group chats](../reference/Bot.md/#trueconf.Bot.create_group_chat) and [channels](../reference/Bot.md/#trueconf.Bot.create_channel). Methods that create group chats and channels always create a new chat:
+
+```python
+chat = await bot.create_group_chat(title="Support")
+channel = await bot.create_channel(title="News")
+```
+
+If you call such a method again with the same title, another chat or channel with the same `title` will be created.
+Therefore, after creating a group chat or channel, it is better to save its `chat_id` in a database, configuration file, or another persistent storage.
+
+!!! Question "What if the chat already exists? How do I get its `chat_id`?"
+
+### Finding an existing chat
+
+You can get the list of available chats with [`bot.get_chats()`](../reference/Bot.md/#trueconf.Bot.get_chats):
+
+```python
+response = await bot.get_chats(count=10, page=1)
+```
+
+The method returns [`GetChatsResponse`](../reference/Responses.md/#trueconf.types.responses.GetChatsResponse) with the `list` parameter containing the list of chats.
+You can find the required chat, for example by its title, and get its `chat_id`:
+
+=== "Using a generator"
+    ```python
+    response = await bot.get_chats(count=100, page=1)
+    
+    chat = next(
+        (chat for chat in response.list if chat.title == "Support"),
+        None,
+    )
+    
+    if chat is not None:
+        print(chat.chat_id)
+    ```
+
+=== "Using a loop"
+    ```python
+    response = await bot.get_chats(count=100, page=1)
+    chat = None
+
+    for item in response.list:
+        if item.title == "Support":
+            chat = item
+            break
+    
+    if chat is not None:
+        print(chat.chat_id)
+    ```
+
+After you find the required `chat_id`, it is also recommended to save it so that you do not have to search for the chat again on every application start.
+
+### Getting `chat_id` from an incoming message
+
+Another simple way is to send a message to the target chat and handle it with the bot. In the handler, you can print `message.chat_id`:
+
+```python
+from trueconf import Router
+from trueconf.types import Message
+
+router = Router()
+
+
+@router.message()
+async def print_chat_id(message: Message):
+    print(message.chat_id)
+```
+
+This approach is convenient for group chats and channels: add the bot to the required chat, send a message, and check the `chat_id` in the console.
+
+## Text messages
+
+To send a text message, use [`bot.send_message(...)`](../reference/Bot.md/#trueconf.Bot.send_message):
+
+```python
+await bot.send_message(
+    chat_id="chat_id",
+    text="Hello!",
+)
+```
+
+If you send a message from an incoming message handler, you can use `Message` shortcut methods, such as `message.answer(...)` or `message.reply(...)`.
+They automatically use `message.chat_id`, so you do not need to pass it manually. For details, see the [Shortcuts](shortcuts.md) section.
+
+### Replying to a message
+
+If you need to reply to a specific message, pass the source message identifier in the `reply_message_id` parameter:
+
+```python
+await bot.send_message(
+    chat_id="chat_id",
+    text="This is a reply",
+    reply_message_id="message_id",
+)
+```
+
+This approach allows you to send regular messages and replies through a single API.
+
+### Forwarding messages
+
+To forward an existing message, use [`bot.forward_message(...)`](../reference/Bot.md/#trueconf.Bot.forward_message):
+
+```python
+await bot.forward_message(
+    chat_id="target_chat_id",
+    message_id="source_message_id",
+)
+```
+
+Where:
+
+- `chat_id` is the identifier of the chat where the message should be forwarded;
+- `message_id` is the identifier of the message to forward.
+
+### Text formatting
+
+Messages can be sent as plain text, HTML, or Markdown by passing `parse_mode`:
+
+```python
+from trueconf.enums import ParseMode
+
+await bot.send_message(
+    chat_id="chat_id",
+    text="<b>Important</b>",
+    parse_mode=ParseMode.HTML,
+)
+```
+
+For convenient formatted text construction, the library provides the [`trueconf.utils.formatting`](../reference/Formatting.md) module.
+It lets you build a message from classes instead of writing HTML or Markdown manually:
+
+```python
+from trueconf.enums import ParseMode
+from trueconf.utils.formatting import (
+    Bold,
+    Italic,
+    Link,
+    Mention,
+    Text,
+)
+
+content = Text(
+    Bold("Important"),
+    " message for ",
+    Mention("John Doe", user_id="john_doe@video.example.com"),
+    "\n",
+    Link("Open website", url="https://trueconf.com"),
+)
+
+await bot.send_message(
+    chat_id="chat_id",
+    text=content.as_html(),
+    parse_mode=ParseMode.HTML,
+)
+```
+
+The module supports:
+
+- [`Bold(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Bold)
+- [`Italic(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Italic)
+- [`Underline(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Underline)
+- [`Strikethrough(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Strikethrough)
+- [`Link(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Link)
+- [`Mention(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Mention)
+- [`AllMention()`](../reference/Formatting.md/#trueconf.utils.formatting.AllMention)
+- [`Text(...)`](../reference/Formatting.md/#trueconf.utils.formatting.Text)
+
+### Message length limits
+
+TrueConf Server limits text messages to `4096` characters.
+
+If a message exceeds this limit, use the `safe_split_text(...)` helper function.
+It safely splits long text while preserving HTML/Markdown markup:
+
+```python
+from trueconf.utils import safe_split_text
+
+chunks = safe_split_text(long_text)
+
+for chunk in chunks:
+    await bot.send_message(
+        chat_id="chat_id",
+        text=chunk,
+        parse_mode=ParseMode.HTML,
+    )
+```
+
+For more information about limits, see the [Restrictions](restrictions.md) section.
+
+!!! Tip "Shortcut methods"
+    In message handlers, it is often more convenient to use `message.answer(...)`, `message.reply(...)`, and other shortcut methods instead of calling `bot.send_message(...)` directly.
+    For details, see the [Shortcuts](shortcuts.md) section.
+
+!!! Tip "Sending files"
+    This section covers text messages.
+    To send documents, images, videos, voice messages, and other attachments, see the [Working with files](files.md) section.