python-trueconf-bot 1.0.0__tar.gz → 1.1.1__tar.gz

python_trueconf_bot-1.1.1/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    tags:
+      - 'docs/*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements-docs.txt ]; then pip install -r requirements-docs.txt; fi
+
+      - name: Preflight check (mkdocs.yml has mike plugin)
+        run: |
+          if ! grep -q '^ *- *mike *$' mkdocs.yml && ! grep -q 'plugins:.*mike' mkdocs.yml; then
+            echo "::error::Plugin 'mike' is not enabled in mkdocs.yml (add under plugins: - mike)"
+            exit 1
+          fi
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Determine version label
+        id: ver
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          if [ -n "$INPUT_VERSION" ]; then
+            VERSION="$INPUT_VERSION"
+          else
+            # Например, docs/v1.0.0 -> v1.0.0
+            VERSION="${GITHUB_REF_NAME#docs/}"
+          fi
+          echo "Using version: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy docs with mike (update latest alias)
+        if: ${{ github.event.inputs.alias_latest != 'false' }}
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          mike deploy --push --branch gh-pages --update-aliases "$VERSION" latest
+          mike set-default --push --branch gh-pages latest
+
+      - name: Deploy docs with mike (no alias update)
+        if: ${{ github.event.inputs.alias_latest == 'false' }}
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          mike deploy --push --branch gh-pages "$VERSION"

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/.github/workflows/release.yml

@@ -22,6 +22,15 @@ jobs:
           fetch-tags: true
           ref: ${{ github.event.inputs.tag }}
 
+      - name: Show current commit
+        run: git describe --tags --always
+
+      - name: Set version from tag
+        run: |
+          TAG="${{ github.event.inputs.tag }}"
+          VERSION="${TAG#v}"
+          sed -i "s/^version = .*/version = \"${VERSION}\"/" pyproject.toml    
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-trueconf-bot
-Version: 1.0.0
+Version: 1.1.1
 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
@@ -28,6 +28,10 @@ Requires-Dist: httpx
 Requires-Dist: mashumaro
 Requires-Dist: aiofiles
 Requires-Dist: magic-filter
+Requires-Dist: aiohttp
+Requires-Dist: async-property
+Provides-Extra: python-magic
+Requires-Dist: python-magic>=0.4.27; extra == "python-magic"
 Dynamic: license-file
 
 <p align="center">
@@ -44,6 +48,12 @@ Dynamic: license-file
 <p align="center">This is a lightweight and powerful wrapper for the <a href="https://trueconf.com/docs/chatbot-connector/en/overview/">TrueConf Server Chatbot API</a> which enables quick integration of chatbots into TrueConf solutions.</p>
 
 <p align="center">
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/v/python-trueconf-bot">
+    </a>
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/pyversions/python-trueconf-bot">
+    </a>
     <a href="https://t.me/trueconf_chat" target="_blank">
         <img src="https://img.shields.io/badge/telegram-group-blue?style=flat-square&logo=telegram" />
     </a>
@@ -107,6 +117,7 @@ if __name__ == "__main__":
 
 1. [TrueConf Server Chatbot API Documentation](https://trueconf.com/docs/chatbot-connector/en/overview/)
 2. [python-trueconf-bot Documentation](https://trueconf.github.io/python-trueconf-bot/)
+3. [Examples](examples/README.md)
 
 All updates and releases are available in the repository. Track the build status and test coverage.
 

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/README-PyPI.md

@@ -12,6 +12,12 @@
 <p align="center">This is a lightweight and powerful wrapper for the <a href="https://trueconf.com/docs/chatbot-connector/en/overview/">TrueConf Server Chatbot API</a> which enables quick integration of chatbots into TrueConf solutions.</p>
 
 <p align="center">
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/v/python-trueconf-bot">
+    </a>
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/pyversions/python-trueconf-bot">
+    </a>
     <a href="https://t.me/trueconf_chat" target="_blank">
         <img src="https://img.shields.io/badge/telegram-group-blue?style=flat-square&logo=telegram" />
     </a>
@@ -75,6 +81,7 @@ if __name__ == "__main__":
 
 1. [TrueConf Server Chatbot API Documentation](https://trueconf.com/docs/chatbot-connector/en/overview/)
 2. [python-trueconf-bot Documentation](https://trueconf.github.io/python-trueconf-bot/)
+3. [Examples](examples/README.md)
 
 All updates and releases are available in the repository. Track the build status and test coverage.
 

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/README-ru.md

@@ -12,6 +12,12 @@
 <p align="center">Это легкая и мощная обертка для <a href="hhttps://trueconf.ru/docs/chatbot-connector/ru/overview/">API чат-ботов TrueConf Server</a>, позволяющая быстро интегрировать чат-ботов с API TrueConf.</p>
 
 <p align="center">
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/v/python-trueconf-bot">
+    </a>
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/pyversions/python-trueconf-bot">
+    </a>
     <a href="https://t.me/trueconf_chat" target="_blank">
         <img src="https://img.shields.io/badge/telegram-group-blue?style=flat-square&logo=telegram" />
     </a>
@@ -79,6 +85,7 @@ if __name__ == "__main__":
 
 1. [Документация API чат-ботов TrueConf Server](https://trueconf.ru/docs/chatbot-connector/ru/overview/)
 2. [Документация python-trueconf-bot](https://trueconf.github.io/python-trueconf-bot/ru/)
+3. [Примеры](examples/README-ru.md)
 
 Все обновления и релизы доступны в репозитории. Следите за статусом сборок и покрытием тестами.
 

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/README.md

@@ -12,6 +12,12 @@
 <p align="center">This is a lightweight and powerful wrapper for the <a href="https://trueconf.com/docs/chatbot-connector/en/overview/">TrueConf Server Chatbot API</a> which enables quick integration of chatbots into TrueConf solutions.</p>
 
 <p align="center">
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/v/python-trueconf-bot">
+    </a>
+    <a href="https://pypi.org/project/python-trueconf-bot/">
+        <img src="https://img.shields.io/pypi/pyversions/python-trueconf-bot">
+    </a>
     <a href="https://t.me/trueconf_chat" target="_blank">
         <img src="https://img.shields.io/badge/telegram-group-blue?style=flat-square&logo=telegram" />
     </a>
@@ -33,12 +39,11 @@
 </p>
 
 
-
----
-
 > [!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.
 
+---
+
 ## 📌 Key Features
 
 * Easy integration with the [TrueConf Server Chatbot API](https://trueconf.com/docs/chatbot-connector/en/overview/)
@@ -82,6 +87,7 @@ if __name__ == "__main__":
 
 1. [TrueConf Server Chatbot API Documentation](https://trueconf.com/docs/chatbot-connector/en/overview/)
 2. [python-trueconf-bot Documentation](https://trueconf.github.io/python-trueconf-bot/)
+3. [Examples](examples/README.md)
 
 All updates and releases are available in the repository. Track the build status and test coverage.
 

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/docs/en/examples/multibot.md

@@ -8,4 +8,4 @@ The TrueConf team has prepared an example that demonstrates the use of four bots
 - GPT bot that runs a local LLM model in the background
 
 
-[View repository :fontawesome-solid-arrow-right:](github.com/TrueConf){ .md-button }
+[View repository :fontawesome-solid-arrow-right:](https://github.com/TrueConf/trueconf-chatbot-example){ .md-button }

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/docs/en/index.md

@@ -25,7 +25,7 @@ This library is designed to simplify the development of chatbots by providing re
 ### Installation using pip
 
 ```shell
-pip install git+https://github.com/TrueConf/{{product_name}}
+pip install {{product_name}}
 ```
 
 ## Comparison with aiogram

python_trueconf_bot-1.1.1/docs/en/learn/files.md

@@ -0,0 +1,143 @@
+---
+title: Working with files
+icon:
+---
+
+# Working with Files
+
+{{product_chatbot}} does not impose any restrictions on uploading files to the
+server. However, starting from version {{product_server}} 5.5.2 and above, the
+administrator can set limits on the maximum file size and allowable formats
+(extensions).
+
+The **{{product_name}}** library offers convenient tools for file handling, both
+for sending and uploading. To send a file, use one of the InputFile subclasses,
+depending on the data source.
+
+Three built-in classes are available for file transfer:
+
+- FSInputFile — uploading a file from the local file system
+- BufferedInputFile — loading from a byte buffer
+- URLInputFile — uploading a file from a remote URL
+
+All classes are located in the [trueconf.types](../reference/Types.md) module.
+
+You can use these classes in methods:
+
+- bot.send_document(...)
+- bot.send_photo(...)
+- bot.send_sticker(...)
+
+## How to send a file?
+
+### 🗂️ FSInputFile
+
+It is used for uploading files from the local file system. It is recommended to
+use this when you have a file path.
+
+```python
+from trueconf.types import FSInputFile
+
+await bot.send_document(
+    chat_id="a1b2c3d4",
+    file=FSInputFile("docs/report.pdf"),
+    caption="📄 Annual report for **2025**",
+    parse_mode=ParseMode.MARKDOWN
+)
+
+await bot.send_sticker(
+    chat_id="a1b2c3d4",
+    file=FSInputFile("stickers/cat.webp")
+)
+```
+
+### 🧠 BufferedInputFile
+
+Used when the file is already in memory (for example, received from an API,
+loaded into RAM, or from a database).
+
+```python
+from trueconf.types import BufferedInputFile
+
+image_bytes = open("image.jpg", "rb").read()
+preview_bytes = open("preview.jpg", "rb").read()
+
+await bot.send_photo(
+    chat_id="a1b2c3d4",
+    file=BufferedInputFile(
+        file=image_bytes,
+        filename="image.jpg"
+    ),
+    preview=BufferedInputFile(
+        file=preview_bytes,
+        filename="preview.jpg"
+    ),
+    caption="This is my photo"
+)
+```
+
+The convenient method `from_file()` is also available:
+
+```python
+file = BufferedInputFile.from_file("archive.zip")
+await bot.send_document(chat_id="...", file=file)
+```
+
+### 🌐 URLInputFile
+
+If the file is available online, you can provide a link, and the bot will
+download it automatically.
+
+```python
+from trueconf.types import URLInputFile
+
+file = URLInputFile(
+    url="https://example.com/image.png",
+    filename="image.png",  # optional — it will be determined automatically
+)
+```
+
+### Recommendations
+
+- **MIME type**: determined automatically. If the
+[python-magic](https://pypi.org/project/python-magic) package is installed,
+the MIME type will be calculated based on the file's content (bytes), which is
+significantly more accurate than determining it by extension. Install it with
+dependencies as follows:
+
+```shell
+pip install python-trueconf-bot[python-magic]
+```
+
+- **clone()**: each file type supports the `.clone()` method, which creates a new
+copy of the object with a different `id(object)`.
+
+## How to download a file?
+
+To easily download incoming media files, such as images (`message.photo`) or
+documents (`message.document`), the library provides the shortcut method
+`.download()`. This is syntactic sugar over the `bot.download_file_by_id(...)`
+method, simplifying the handling of attachments.
+
+It is recommended to use `.download()` because it:
+
+- automatically retrieves file_id from the object;
+- uses the current bot instance;
+- minimizes the amount of code.
+
+```python
+@router.message(F.document)
+async def handle_doc(msg: Message):
+    await msg.document.download(dest_path="document.pdf")
+```
+
+!!! Notes The `dest_path` can be either relative or absolute.
+
+The method `download_file_by_id(...)` is also available for more flexible control:
+
+```python
+await bot.download_file_by_id(
+    file_id=msg.document.file_id, 
+    dest_path="document.pdf"
+)
+```

python_trueconf_bot-1.1.1/docs/en/learn/filters.md

@@ -0,0 +1,255 @@
+---
+title: Filters
+icon:
+---
+
+# Filters
+
+Filters are necessary for routing incoming events (updates) to the correct
+handlers. The search for a handler always stops at the first match with a set of
+filters. By default, all handlers have an empty set of filters, so all updates
+will be passed to the first handler with an empty set of filters. In the current
+implementation, two main approaches for filtering text messages are available:
+
+- **Command** — a filter for processing commands in the format /command
+\[arguments].
+- **MagicFilter** is a universal declarative filter (from the magic-filter
+library) for event field validation.
+
+These two approaches are often used together: **Command** checks the command
+format and extracts arguments, while **MagicFilter** imposes additional
+conditions on arguments or other message fields.
+
+!!! Tip 
+	Below you can find examples of using filters, but if that's not enough, check out [examples in the repository](https://github.com/TrueConf/python-trueconf-bot/tree/master/examples).
+
+## Command
+
+**Command** — a convenient filter for parsing and processing commands in message
+text.
+
+```python
+Command(*commands: str | Pattern[str], prefix: str = "/", ignore_case: bool = False, magic: MagicFilter | None = None)
+```
+
+!!! note "Capabilities" 
+	- Accept one or more commands: `Command("start")`, `Command("info", "about")`. 
+	- Support regular expression patterns: `Command(re.compile(r"echo_\d+"))`. 
+	- Support different prefixes (default is `/`), for example `prefix="!/"` — then `!cmd` and `/cmd` will be valid. 
+	- Ignore case for string commands (`ignore_case=True`). 
+	- Accept optional `magic` — **MagicFilter**, which additionally validates the `CommandObject` (see [below](#commandobject)).
+
+The **Command** filter operates as follows:
+
+1. Checks that the message is a `Message` and that it is of type `PLAIN_MESSAGE`.
+1. Checks if the text begins with the specified prefix (default is `/`).
+1. Splits the string into a command and arguments (if any).
+1. Compares the command with the specified ones (including support for
+`re.Pattern`).
+1. If `magic` is passed, `MagicFilter` is applied to the `CommandObject`.
+1. If the `magic` filter is triggered, it returns a dictionary
+`{"command": command_obj}`.
+
+### CommandObject
+
+If the filter is triggered, the handler can receive a **CommandObject** (passed
+as the `command` parameter):
+
+```python
+@dataclass(frozen=True)
+class CommandObject:
+    prefix: str
+    command: str
+    args: str | None
+    regexp_match: Match[str] | None = None
+    magic_result: Any | None = None
+```
+
+!!! Note "Fields" 
+	 - `prefix` — the prefix character (`/`, `!`, etc.). 
+	 - `command` — the command name without the prefix. 
+	 - `args` — the argument string (everything after the space). 
+	 - `regexp_match` — the result of `re.Match` if the command was specified as a regular expression. 
+	 - `magic_result` — optional data returned by `magic` (if applicable).
+
+### Examples
+
+**Basic handler:**
+
+```python
+@r.message(Command("ping"))
+async def handle_ping(message: Message):
+    await bot.send_message(chat_id=message.chat_id, text="pong")
+```
+
+**Multiple commands:**
+
+```python
+@r.message(Command("info", "about", "whoami"))
+async def handle_info(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=f"Used /{command.command}")
+```
+
+**Command with prefix:**
+
+```python
+@r.message(Command(re.compile(r"echo_\d+")))
+async def handle_echo_numbered(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=f"Echo: {command.command} {command.args or ''}")
+```
+
+## MagicFilter
+
+**MagicFilter** is a declarative, chainable filter from the **magic-filter**
+package. It allows you to express checks on event fields using chains and
+operators. Instead of manually checking update fields within the handler,
+conditions can be set directly in the decorator.
+
+The filter works "lazily": when a handler is declared, only the chain of checks
+is stored, not the result. The actual evaluation happens only when a new event
+arrives, so filters can be easily combined and remain readable. This approach
+makes the code shorter and clearer, showing exactly which updates will be
+processed by a given handler.
+
+The idea behind **MagicFilter** is simple: describe an attribute chain and a
+condition, then apply it to an object. Imagine you have an object with nested
+fields. Instead of manually checking something like
+`if obj.foo.bar.baz == "spam": ...`, you can construct the filter declaratively:
+
+```python
+F.foo.bar.baz == "spam"
+```
+
+The resulting filter is not an immediate check, but an object that "remembers"
+the condition. When processing an update, this filter is automatically applied
+to the object (the router handles the check under the hood). Technically, the
+`.resolve(obj)` method is used for this, but you don't need to call it manually
+— just define the condition in the decorator, and it will be executed during
+routing.
+
+```python
+@r.message(F.text == "ping")
+async def ping_handler(message):
+    await message.answer("pong")
+```
+
+Here, the filter `F.text == "ping"` will be automatically checked for each
+incoming message. If the condition matches, the handler will be triggered.
+
+### Examples
+
+The **MagicFilter** object supports basic logical operations on object attributes.
+
+**Existence Check:**
+
+```python
+F.photo  # lambda message: message.photo
+```
+
+**Equality:**
+
+```python
+F.text == "hello"        # lambda message: message.text == "hello"
+F.from_user.id == 42     # lambda message: message.from_user.id == 42
+F.text != "spam"         # lambda message: message.text != "spam"
+```
+
+**Set membership:**
+
+```python
+# lambda query: query.from_user.id in {42, 1000, 123123}
+F.from_user.id.in_({42, 1000, 123123})  
+
+# lambda query: query.data in {"foo", "bar", "baz"}
+F.data.in_({"foo", "bar", "baz"})
+```
+
+**Contains:**
+
+```python
+F.text.contains("foo")  # lambda message: "foo" in message.text
+```
+
+**Starts/ends with the string:**
+
+```python
+F.text.startswith("foo")  # lambda message: message.text.startswith("foo")
+F.text.endswith("bar")    # lambda message: message.text.endswith("bar")
+```
+
+**Regular Expressions:**
+
+```python
+F.text.regexp(r"Hello, .+")  # lambda message: re.match(r"Hello, .+", message.text)
+```
+
+**Custom Function:**
+
+```python
+# lambda message: (lambda chat: chat.id == -42)(message.chat)
+F.chat.func(lambda chat: chat.id == -42)
+```
+
+**Inversion of result:**
+
+```python
+~F.text # not message.text        
+~F.text.startswith("spam") #not message.text.startswith("spam")
+```
+
+**Combining conditions:**
+
+```python
+(F.from_user.id == 42) & (F.text == "admin")
+
+F.text.startswith("a") | F.text.endswith("b")
+
+(F.from_user.id.in_({42, 777, 911})) & (F.text.startswith("!") | F.text.startswith("/")) & F.text.contains("ban")
+```
+
+**Attribute Modifiers (Strings):**
+
+```python
+F.text.lower() == "test"           # message.text.lower() == "test"  
+F.text.upper().in_({"FOO", "BAR"}) # message.text.upper() in {"FOO", "BAR"}
+F.text.len() == 5                  # len(message.text) == 5
+```
+
+## Combining Filters
+
+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
+**CommandObject**.
+
+**Filter the /echo command only if arguments are present:**
+
+```python
+@r.message(Command("echo", magic=F.args.is_not(None)))
+async def handle_echo(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=command.args)
+```
+
+**Additional argument length check:**
+
+```python
+@r.message(Command("upper", magic=F.args.len() > 3))
+async def handle_upper(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=(command.args or "").upper())
+```
+
+**Check with func — single word:**
+
+```python
+@r.message(Command("repeat", magic=F.args.func(lambda x: isinstance(x, str) and len(x.split()) == 1)))
+async def handle_repeat(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=f"{command.args} {command.args}")
+```
+
+**Combining regexp and magic:**
+
+```python
+@r.message(Command(re.compile(r"echo_\\d+"), magic=F.args))
+async def handle_special_echo(message: Message, command: CommandObject):
+    await bot.send_message(chat_id=message.chat_id, text=f"Special: {command.command} -> {command.args}")
+```

{python_trueconf_bot-1.0.0 → python_trueconf_bot-1.1.1}/docs/en/learn/getting-started.md

@@ -10,18 +10,11 @@ source .venv/bin/activate   # Linux / macOS
 
 ## Installing {{product_name}}
 
-To start working with {{product_name}}, install the library using one of the following methods:
+To begin working with {{product_name}}, install the package from the global PyPI repository:
 
-1. From the global PyPI repository:
-
-   ```shell
-   pip install {{product_name}}
-   ```
-2. From a locally built package (.whl):
-
-   ```shell
-   pip install {{product_name}}.whl
-   ```
+```shell
+pip install {{product_name}}
+```
 
 !!! info
     Upon installation, dependencies will be automatically pulled in: `websockets`, `httpx`, `mashumaro`, `pillow`, `aiofiles`, `magic-filter`.