Cluster · разработчикам
app.web
HTTPS и WSS через сетевую службу ядра. Настройки профиля и ограничения разделены по экземплярам модулей.
Все методы SDK · Типы и ошибки
Получение объекта
request = app.web("https://example.org/status")__init__
Создаёт Web. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
def __init__(app: App) -> None: ...Аргументы
app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
Результат
None. Создаёт Web. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
# Обычный способ получения объекта:
request = app.web("https://example.org/status")__call__
Создаёт подготовленный HTTP-запрос без отправки.
def __call__(url: str, method: str = 'GET', headers: dict[str, str] | None = None) -> Request: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.method: str, по умолчанию'GET'. Имя метода выбранного API. Регистр значим.headers: dict[str, str] | None, по умолчаниюNone. HTTP-заголовки. Копируются в объект; None означает пустой набор.
Результат
Request. Создаёт подготовленный HTTP-запрос без отправки.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.web("https://example.org/status")session
Создаёт объект с базовым URL и общими заголовками; выход на другой origin запрещён.
def session(url: str, headers: dict[str, str] | None = None) -> Session: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.headers: dict[str, str] | None, по умолчаниюNone. HTTP-заголовки. Копируются в объект; None означает пустой набор.
Результат
Session. Создаёт объект с базовым URL и общими заголовками; выход на другой origin запрещён.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.web.session("https://example.org/status")socket
Создаёт ещё не открытое WSS-соединение.
def socket(url: str) -> Socket: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.
Результат
Socket. Создаёт ещё не открытое WSS-соединение.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
result = app.web.socket("https://example.org/status")get
Выполняет GET с параметрами строки запроса и возвращает объект ответа.
async def get(url: str, **query: QueryValue) -> Response: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.query: QueryValue, произвольные именованные аргументы. Именованные параметры URL. None удаляет параметр; список создаёт повторения.
Результат
Response. Выполняет GET с параметрами строки запроса и возвращает объект ответа.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.get("https://example.org/status", page=1)post
Выполняет POST с JSON-телом; None передаётся как JSON null.
async def post(url: str, value: JSON = None) -> Response: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.value: JSON, по умолчаниюNone. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.
Результат
Response. Выполняет POST с JSON-телом; None передаётся как JSON null.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.post("https://example.org/status")request
Выполняет HTTP-запрос и возвращает словарь ядра. Ошибочный HTTP-статус сам по себе не вызывает исключение.
async def request(url: str, **kwargs: JSON) -> HTTPResponse: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: method, body, headers, binary. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
HTTPResponse. Выполняет HTTP-запрос и возвращает словарь ядра. Ошибочный HTTP-статус сам по себе не вызывает исключение.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.request("https://example.org/status", method="GET")profile
Меняет прокси или хранение cookies сетевого профиля экземпляра. Это не профиль Telegram.
async def profile(**data: JSON) -> bool: ...Аргументы
data: JSON, произвольные именованные аргументы. proxy: str | None = None (URL http/socks4/socks5 с явным портом), cookies: bool = True, domain: str | None = None. domain задаёт область проверки права; адрес прокси также проверяется. Это не Telegram-прокси.
Результат
bool. True при успешном действии; у отзыва уже отсутствующей записи возможен False.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.profile(cookies=True)download
Загружает HTTPS-ответ в файл Cluster с заранее ограниченным размером.
async def download(url: str, filename: str, **data: JSON) -> FileInfo: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.filename: str, обязательный. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: maximum. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
FileInfo. Загружает HTTPS-ответ в файл Cluster с заранее ограниченным размером.
Права
Нужны web.request + files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.download("https://example.org/status", "note.txt", maximum=1048576)upload
Передаёт содержимое готового файла Cluster как тело HTTP-запроса. Ответ маршрута upload содержит status и body; Response создаёт пустые headers и считает body текстовым.
async def upload(url: str, file: str | bytes, **data: JSON) -> UploadResponse: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.file: str | bytes, обязательный. ID файла Cluster либо bytes только у конструкторов, которые явно поддерживают загрузку байтов. Короткие методы клиента принимают готовый ID.data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: method, headers. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
UploadResponse. Словарь {status: int, body: str}. Заголовки и binary этим маршрутом не возвращаются.
Права
Нужны web.request + files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.upload("https://example.org/status", "file-id", method="POST")open
Открывает WSS-соединение и возвращает его ID.
async def open(url: str) -> dict[str, str]: ...Аргументы
url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.
Результат
dict[str, str]. Открывает WSS-соединение и возвращает его ID.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.open("https://example.org/status")send
Отправляет текстовый кадр в уже открытое WSS-соединение.
async def send(id: str, data: JSON) -> bool: ...Аргументы
id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.data: JSON, обязательный. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.
Результат
bool. True при успешном действии; у отзыва уже отсутствующей записи возможен False.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.send("object-id", {"count": 1})receive
Ожидает кадр не дольше wait. При отсутствии кадра возвращает None; бинарные данные в словаре закодированы base64.
async def receive(id: str, **data: JSON) -> SocketFrame | None: ...Аргументы
id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: wait. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.
Результат
SocketFrame | None. Ожидает кадр не дольше wait. При отсутствии кадра возвращает None; бинарные данные в словаре закодированы base64.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.receive("object-id", wait=10)close
Закрывает WSS-соединение по ID.
async def close(id: str) -> bool: ...Аргументы
id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.
Результат
bool. True при успешном действии; у отзыва уже отсутствующей записи возможен False.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
Пример
result = await app.web.close("object-id")