Metadata-Version: 2.4
Name: uroboros-userbot
Version: 1.0.1
Summary: Modular Telegram userbot on Telethon
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/asykixd/uroboros
Project-URL: Documentation, https://asykixd.github.io/uroboros/
Project-URL: Changelog, https://github.com/asykixd/uroboros/releases
Project-URL: Issues, https://github.com/asykixd/uroboros/issues
Keywords: telegram,userbot,telethon,hikka
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon<2,>=1.40
Requires-Dist: aiogram<4,>=3.20
Requires-Dist: qrcode>=7.4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.2; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/asykixd/uroboros/master/docs/assets/logo.svg" width="112" alt="Uroboros">
</p>

<h1 align="center">Uroboros</h1>

<p align="center">
  Modular Telegram userbot on Python and Telethon.<br>
  One-command modules, inline buttons and forms, account protection from malicious code.
</p>

<p align="center">
  <a href="https://github.com/asykixd/uroboros/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/asykixd/uroboros/ci.yml?branch=master&label=tests&style=flat-square" alt="Tests"></a>
  <a href="https://pypi.org/project/uroboros-userbot/"><img src="https://img.shields.io/pypi/v/uroboros-userbot?style=flat-square&color=14b8a6" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.10%2B-14b8a6?style=flat-square&logo=python&logoColor=white" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/telethon-1.x-0f766e?style=flat-square" alt="Telethon 1.x">
  <a href="https://github.com/asykixd/uroboros/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-2dd4bf?style=flat-square" alt="AGPL-3.0"></a>
</p>

<p align="center">
  <a href="https://asykixd.github.io/uroboros/"><b>📚 Docs</b></a> ·
  <a href="https://asykixd.github.io/uroboros/install/"><b>🚀 Install</b></a> ·
  <a href="https://asykixd.github.io/uroboros/commands/"><b>⌨️ Commands</b></a> ·
  <a href="https://asykixd.github.io/uroboros/modules/"><b>🧩 Write modules</b></a> ·
  <a href="https://github.com/asykixd/uroboros-modules"><b>📦 Modules</b></a> ·
  <a href="https://github.com/asykixd/uroboros/blob/master/README.ru.md"><b>🇷🇺 Русский</b></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/asykixd/uroboros/master/docs/assets/preview-en.svg?v=2" width="720" alt="Uroboros messages in Telegram">
</p>

## ✨ Features

|  |  |
|---|---|
| 📦 **One-command modules**: `.dlm notes`, `.search`, your own repos via `.addrepo` | 🛡 **Account protection**: code is scanned before install, and modules can't touch the session at runtime |
| 🤖 **Buttons and forms**: built-in inline bot for settings, help and confirmations | 🔁 **Hikka and FTG modules**: loaded as-is through an adapter, see [what's supported](https://asykixd.github.io/uroboros/hikka/) |
| 🌿 **Stable and dev channels**: `.dev on` / `.dev off`, `.update` with rollback | 💾 **Backups**: database and modules in one archive, on a schedule |
| 🔐 **Access levels**: `owner`, `sudo`, `support` and per-command permissions | 🐧 **Runs anywhere**: Linux and VPS, Termux, Docker, Windows, macOS |

## 🚀 Install

Linux, VPS, Termux, macOS:

```bash
curl -fsSL https://raw.githubusercontent.com/asykixd/uroboros/master/install.sh | sh
```

Or `pip install uroboros-userbot`. Docker, systemd, Termux autostart and Windows: see
[install docs](https://asykixd.github.io/uroboros/install/).

On first run Uroboros prints a link to a web login panel: enter `api_id`/`api_hash` from
[my.telegram.org/apps](https://my.telegram.org/apps), phone, code and 2FA password, or scan a QR code. The panel
shuts down after login, and Uroboros creates its inline bot via @BotFather. Console login: `--cli`.

> [!NOTE]
> The bot speaks Russian for now; the English interface is next on the roadmap.

## ⌨️ Main commands

| Command | Description |
|---|---|
| 📖 `.help [module]` | modules and help |
| 📥 `.dlm <url \| owner/repo/module \| module>` | install a module; `.dlm owner/repo` lists a repo |
| 🔃 `.uplm [module]` | update modules: diff first, then confirm |
| 🗑 `.ulm <module>` | remove a module |
| ⚙️ `.cfg [module]` | module settings, with buttons |
| 🆕 `.update` | update Uroboros: changelog, install, rollback on failure |
| 🌿 `.dev on \| off` | switch to `dev` builds or back to stable `master` |
| 🔐 `.security` | access, command permissions, flood and module protection |
| 💾 `.backup`, ♻️ `.restore` | backup and restore |
| ℹ️ `.info`, 📡 `.ping`, 📝 `.logs` | bot status |

Full list with access levels: [command reference](https://asykixd.github.io/uroboros/commands/).

## 🧩 Write a module

```python
# meta developer: @you
# meta permissions: none
# requires_uroboros: 1.0
from uroboros import Module, command, utils


class Notes(Module):
    """Notes"""

    @command("save", emoji="💾")
    async def save(self, message):
        """<name> <text> — save a note"""
        name, _, text = utils.get_args_raw(message).partition(" ")
        self.set(name, text)
        await utils.answer(
            message,
            utils.card(
                "✅ <b>Note saved</b>",
                [f"🏷 Name: <code>{utils.escape_html(name)}</code>", f"📏 Length: <code>{len(text)}</code>"],
                hint=f"show: <code>.note {utils.escape_html(name)}</code>",
            ),
        )
```

Modules get `self.client` (Telethon), storage (`self.get`/`self.set`), `self.config`, command filters, watchers,
`@loop` tasks, libraries, inline forms (`self.inline.form(...)`) and `utils` helpers. See the
[module guide](https://asykixd.github.io/uroboros/modules/); ready-made modules and a repo template:
[uroboros-modules](https://github.com/asykixd/uroboros-modules).

## 🛡 Security

> [!WARNING]
> A userbot acts as your account. Spam, mass messaging and request floods can get it banned: test on a spare
> account first.

Third-party modules run in the bot's process. Uroboros scans their code on install, shows permissions and diffs,
pins GitHub modules to a commit and blocks access to the session. It is not a sandbox: install modules you trust.
See [security](https://asykixd.github.io/uroboros/security/).

## 🛠 Development

`dev` is the development branch (`X.Y.Z-dev`), `master` is stable.

```bash
python3 -m venv .venv && .venv/bin/pip install -e '.[dev,docs]'
.venv/bin/python -m pytest
.venv/bin/mkdocs serve
```

## 🙏 Credits

The module API and adapter follow [Hikka](https://github.com/hikariatama/Hikka) (AGPL-3.0); thanks to its authors.
Built on [Telethon](https://github.com/LonamiWebs/Telethon) and [aiogram](https://github.com/aiogram/aiogram).

## 📄 License

AGPL-3.0, see [LICENSE](https://github.com/asykixd/uroboros/blob/master/LICENSE).
[Contributing](https://github.com/asykixd/uroboros/blob/master/CONTRIBUTING.md) ·
[Security policy](https://github.com/asykixd/uroboros/blob/master/SECURITY.md)
