Русский · English

telemt-sdk

Асинхронный типизированный Python SDK для Telemt Control API.

Быстрый старт · Справочник API · Участие в разработке · Сообщить об ошибке

🤝 Спонсор проекта — Peakora VPN

Защищённый доступ в интернет и к AI-сервисам с подключением через Telegram.
Подробнее о Peakora →

Управляйте пользователями прокси, квотами, конфигурацией, диагностикой и WEB-сессиями из Python. TelemtClient объединяет операции в ресурсные объекты, переиспользует HTTP-соединения и возвращает Pydantic-модели с конкретными аннотациями типов, включая вложенные данные.

• 48 операций API: пользователи, состояние сервиса, статистика, перезагрузка и управление WEB runtime.
• Полностью асинхронный интерфейс: async with, await и параллельное чтение через asyncio.gather.
• Типизированные запросы и ответы: валидация входных данных, подсказки IDE и маркер py.typed.
• Контроль конкурентных изменений: передача ревизии ответа для защиты обновлений конфигурации.
• Понятные ошибки: отдельные классы исключений сохраняют HTTP-статус, код Telemt и идентификатор запроса.

SDK работает с HTTP API управления Telemt. Передачу MTProto-трафика и подключения клиентов Telegram обеспечивает сам Telemt.

Установка

Требуется Python 3.13, 3.14 или 3.15. Имя пакета — telemt-sdk, имя импорта — telemt.

После появления релиза в PyPI:

uv add telemt-sdk

Или через pip:

python -m pip install telemt-sdk

До первого релиза можно работать из клонированного репозитория: выполните uv sync --locked в его каталоге. Зависимости SDK — HTTPX и Pydantic.

Быстрый старт

Включите Control API в конфигурации Telemt и задайте TELEMT_AUTH_HEADER равным точному значению server.api.auth_header. Этот пример читает состояние сервера:

import asyncio
import os

from telemt import TelemtClient


async def main() -> None:
    async with TelemtClient(
        "http://127.0.0.1:9091",
        auth_header=os.environ["TELEMT_AUTH_HEADER"],
    ) as client:
        health = await client.health.get()
        print(health.data.status)

        users = await client.users.list()
        for user in users.data:
            print(user.username, user.enabled, user.current_connections)


asyncio.run(main())

SDK передаёт auth_header в заголовке Authorization без изменений и не добавляет Bearer. Если на сервере настроено значение Bearer ..., передавайте строку целиком. Если авторизация не настроена, аргумент можно опустить. Используйте адрес слушателя Control API, а не порт MTProto или WEB ingress.

Настройка клиента

Адреса https://proxy.example.com/control и https://proxy.example.com/control/v1 оба направляют запросы в /control/v1/.... Учётные данные, query-параметры и фрагменты в base_url не допускаются.

Используйте один клиент для нескольких запросов в пределах одного event loop:

health, stats = await asyncio.gather(client.health.get(), client.stats.summary())
print(stats.data.connections_total)

Закрывайте соединения через async with или await client.aclose(). Закрытый клиент нельзя использовать повторно. Если вы передаёте собственный HTTPX-клиент, его временем жизни управляете вы:

import httpx

async with httpx.AsyncClient(limits=httpx.Limits(max_connections=20)) as http:
    async with TelemtClient(
        "https://proxy.example.com",
        auth_header=auth_header,
        timeout=httpx.Timeout(30.0, connect=5.0),
        http_client=http,
    ) as client:
        info = await client.system.info()

Параметры SDK и явно переданная авторизация имеют приоритет над настройками HTTPX. Редиректы и автоматические повторы запросов отключены: изменение могло дойти до сервера до истечения тайм-аута.

Пользователи и квоты

from telemt.models import CreateUserRequest, PatchUserRequest, RotateSecretRequest

created = await client.users.create(
    CreateUserRequest(
        username="alice",
        max_tcp_conns=10,
        data_quota_bytes=10_000_000_000,
        quota_period="monthly",
    )
)
# created.data.secret содержит сгенерированный секрет; не записывайте его в логи.
print(created.data.user.username)

updated = await client.users.update(
    "alice",
    PatchUserRequest(max_tcp_conns=20, expiration_rfc3339="2027-01-01T00:00:00Z"),
    revision=created.revision,
)

rotated = await client.users.rotate_secret("alice", RotateSecretRequest())
await client.users.reset_quota("alice")
await client.users.disable("alice")
await client.users.enable("alice")
# Удаляйте пользователя явно, когда учётная запись больше не нужна:
# await client.users.delete("alice")

Секреты и рекламные теги состоят из 32 шестнадцатеричных символов. Имя пользователя содержит от 1 до 64 латинских букв, цифр, точек, дефисов или подчёркиваний. Имена . и .. отклоняются, поскольку HTTPX нормализует такие сегменты пути. Для периодического сброса квоты доступны daily, weekly и monthly; при создании пользователя требуется положительное значение data_quota_bytes.

Семантика PATCH

Пропущенное поле, None и ноль имеют разное значение:

Для генерации нового секрета используйте rotate_secret(). Модели запросов отклоняют неизвестные поля и недопустимые значения. Проверки, зависящие от состояния сервера, например существование пользователя, выполняет Telemt и возвращает соответствующую ошибку API.

Ответы и ревизии

Каждый метод возвращает APIResponse[T]:

Вложенные данные тоже представлены моделями: user.links.tls_domains[0].domain и status.runtime.manager.issuance_enabled доступны проверке типов после проверки nullable-полей на None. Модели импортируются из telemt.models.

current = await client.users.get("alice")
await client.users.update(
    "alice",
    PatchUserRequest(max_tcp_conns=30),
    revision=current.revision,
)

Аргумент revision= передаётся в заголовок If-Match. Устаревшая ревизия вызывает ConflictError. Перечитайте состояние и проверьте, остаётся ли изменение актуальным, прежде чем повторять запрос. Клиент не хранит общую ревизию и не подставляет её автоматически, поэтому параллельные ответы независимы. WEB-операции используют runtime_instance.

Новые поля сервера сохраняются в model_extra. Для представления, совместимого с JSON, используйте model_dump(mode="json", by_alias=True). Разделы конфигурации остаются dict[str, JsonValue], поскольку это расширяемые конфигурационные данные; известные структуры телеметрии и WEB описаны отдельными моделями.

Конфигурация и перезагрузка

from telemt.models import PatchConfigRequest, ReloadRequest

current = await client.config.get()
changed = await client.config.update(
    PatchConfigRequest(censorship={"tls_domain": "front.example.com"}),
    revision=current.revision,
    reload=ReloadRequest(mode="drain", timeout_secs=30, failure_policy="rollback"),
)
if changed.data.reload is not None:
    progress = await client.system.reload_status(changed.data.reload.reload_id)
    print(progress.data.state)

Для изменения доступны general, timeouts, censorship, upstreams, dc_overrides, web и server.listeners. Проверка на стороне сервера определяет, какие вложенные параметры можно изменить и каким требуется перезапуск процесса.

HTTP 202 означает принятие операции, а не её завершение. Опрашивайте system.reload_status(id) с интервалом и общим тайм-аутом, подходящими вашему приложению, до состояния succeeded, rolled_back или failed. Проверяйте warnings, deferred_process_fields и error в результате. Для отдельной перезагрузки вызовите system.reload(ReloadRequest(...)). Режим drain требует timeout_secs от 1 до 3600; режим instant не принимает этот параметр.

WEB-сессии и жизненный цикл

from telemt.models import CloseRequest, RefsSelector, SessionQuery

status = await client.runtime.web.status()
if status.data.runtime is not None:
    page = await client.runtime.web.sessions(SessionQuery(user="alice", limit=50))
    if page.data.sessions:
        accepted = await client.runtime.web.close_sessions(
            CloseRequest(
                runtime_instance=status.data.runtime.runtime_instance,
                selector=RefsSelector(session_refs=[row.session_ref for row in page.data.sessions]),
            )
        )
        progress = await client.runtime.web.operation(accepted.data.operation_id)
        print(progress.data.state)

Страница сессий содержит до 200 записей. Для следующей страницы передайте SessionQuery(cursor=page.data.next_cursor, ...) с теми же фильтрами. Завершайте обход, когда next_cursor равен None. Поля scan_truncated, partial_sessions и partial описывают ограничения снимка состояния.

Для pause, resume, clear_debug и reset_carrier_learning используется RuntimeInstanceRequest, для drain — DrainRequest. FilterSelector выбирает сессии по фильтрам. AllSelector требует, чтобы runtime.manager.issuance_enabled был равен False; операторский pause() управляет отдельным механизмом допуска. Перед выбором всех сессий проверьте состояние runtime. Для управляемого завершения текущей работы используйте drain().

Ссылки на сессии и операции действуют в пределах текущего процесса сервера. Опрашивайте возвращённый идентификатор операции, чтобы узнать результат: принятие запроса само по себе не означает завершения.

Обработка ошибок

from telemt import APIError, ConflictError, TransportError

try:
    await client.users.disable("alice", revision=known_revision)
except ConflictError as error:
    print(error.code, error.request_id)
except APIError as error:
    print(error.status_code, error.code, error.message)
except TransportError:
    # Перечитайте состояние сервера перед решением о повторном изменении.
    raise

Все исключения SDK наследуются от TelemtError. Ошибки моделей запросов вызывают pydantic.ValidationError; недопустимые аргументы маршрутов — ValueError, включая его подкласс ValidationError. Отмена асинхронной задачи распространяется без обёртки.

Два HTTP-статуса могут содержать штатный результат: health.ready() возвращает данные готовности при HTTP 503, а runtime.web.session() — GoneSessionData при HTTP 410. Ответ с ошибкой API на этих маршрутах по-прежнему вызывает исключение. Используйте isinstance(result.data, GoneSessionData), чтобы отличить закрытую сессию от SessionRow.

Совместимость

SDK следует проекту Telemt и его Control API. Модели сверяются со спецификацией API и типами сериализации в Rust-коде сервера. Клиент охватывает 48 основных операций Control API. HTML-страница /web-status и транспортные WEB-эндпоинты находятся за пределами этого API-клиента.

Python 3.13, 3.14 и 3.15 входят в обязательную матрицу CI под Linux и Windows. Необязательные возможности Telemt могут возвращать данные об отключённой или недоступной функции: проверяйте enabled, reason, data и partial, когда они присутствуют. Сохранение новых полей помогает при расширении ответов сервера, но не означает гарантированную совместимость со всеми прошлыми и будущими изменениями API.

Полный перечень методов, типов запросов и ответов доступен в справочнике API.

Участие в разработке и поддержка

Сообщения об ошибках и pull request приветствуются. В issue укажите версии Python, SDK и Telemt, минимальный пример и тип исключения или код ошибки Telemt. Удалите заголовки авторизации, секреты и приватные настройки из публикуемых материалов.

Настройка окружения uv, линтер, проверка типов и тесты описаны в CONTRIBUTING.md.

Лицензия

MIT © 2026 Peakora-VPN.