Cluster · разработчикам
Request
Подготовленный HTTP-запрос. Изменения локальные; send(), download() и upload() обращаются к ядру.
Все методы SDK · Типы и ошибки
Получение объекта
request = app.web("https://example.org/status")__init__
Создаёт Request. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
def __init__(web: Web, url: str, method: str = 'GET', headers: dict[str, str] | None = None) -> None: ...Аргументы
web: Web, обязательный. Сетевая служба текущего приложения.url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.method: str, по умолчанию'GET'. Имя метода выбранного API. Регистр значим.headers: dict[str, str] | None, по умолчаниюNone. HTTP-заголовки. Копируются в объект; None означает пустой набор.
Результат
None. Создаёт Request. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.
Пример
# Обычный способ получения объекта:
request = app.web("https://example.org/status")header
Устанавливает строковый заголовок, заменяя прежний без учёта регистра имени.
def header(name: str, value: str) -> Self: ...Аргументы
name: str, обязательный. Имя HTTP-заголовка без учёта регистра.value: str, обязательный. Строковое значение HTTP-заголовка.
Результат
Self. Тот же объект после успешной операции. Устанавливает строковый заголовок, заменяя прежний без учёта регистра имени.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
TypeError('Header names and values must be strings'): условие проверяется до продолжения операции.- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
request.header("Accept", "application/json")query
Заменяет выбранные параметры URL. None удаляет параметр, список или кортеж задаёт несколько значений.
def query(**values: JSON) -> Self: ...Аргументы
values: JSON, произвольные именованные аргументы. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.
Результат
Self. Тот же объект после успешной операции. Заменяет выбранные параметры URL. None удаляет параметр, список или кортеж задаёт несколько значений.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = request.query(count=1)json
Устанавливает JSON-тело и Content-Type application/json.
def json(value: JSON) -> Self: ...Аргументы
value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.
Результат
Self. Тот же объект после успешной операции. Устанавливает JSON-тело и Content-Type application/json.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
request.json({"count": 1})form
Кодирует поля как application/x-www-form-urlencoded, поддерживая повторяющиеся значения.
def form(**values: QueryValue) -> Self: ...Аргументы
values: QueryValue, произвольные именованные аргументы. Именованные поля form-urlencoded; списки разворачиваются в повторения.
Результат
Self. Тот же объект после успешной операции. Кодирует поля как application/x-www-form-urlencoded, поддерживая повторяющиеся значения.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
request.form(name="Example")text
Устанавливает строковое тело и выбранный Content-Type.
def text(value: str, content_type: str = 'text/plain; charset=utf-8') -> Self: ...Аргументы
value: str, обязательный. Строковое тело запроса.content_type: str, по умолчанию'text/plain; charset=utf-8'. Значение HTTP-заголовка Content-Type для строкового тела.
Результат
Self. Тот же объект после успешной операции. Устанавливает строковое тело и выбранный Content-Type.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
TypeError('A string body is required'): условие проверяется до продолжения операции.- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = request.text("Example")clone
Создаёт независимый запрос с теми же URL, методом, телом и копией заголовков.
def clone() -> Request: ...Аргументы
Нет.
Результат
Request. Создаёт независимый запрос с теми же URL, методом, телом и копией заголовков.
Права
Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.
Ошибки
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = request.clone()send
Отправляет GET, POST, PUT, PATCH, DELETE или HEAD через ядро. Другие HTTP-методы отклоняются.
async def send() -> Response: ...Аргументы
Нет.
Результат
Response. Отправляет GET, POST, PUT, PATCH, DELETE или HEAD через ядро. Другие HTTP-методы отклоняются.
Права
Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
ValueError('Invalid HTTP method'): условие проверяется до продолжения операции.- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = await request.send()download
Загружает обычный GET без заголовков и тела в файл Cluster. Не отправляет подготовленные заголовки молча.
async def download(filename: str, maximum: float | None = 10485760) -> File: ...Аргументы
filename: str, обязательный. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().maximum: float | None, по умолчанию10485760. Граница min/max поля, конечное число от -1e12 до 1e12; None снимает границу.
Результат
File. Загружает обычный GET без заголовков и тела в файл Cluster. Не отправляет подготовленные заголовки молча.
Права
Нужны web.request + files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
ValueError('Downloads require a plain GET request'): условие проверяется до продолжения операции.- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = await request.download("note.txt")upload
Передаёт файл Cluster как тело запроса с сохранением выбранных метода и заголовков. Одновременное отдельное тело запрещено. Ответ маршрута upload содержит status и body; Response создаёт пустые headers и считает body текстовым.
async def upload(file: File | str) -> Response: ...Аргументы
file: File | str, обязательный. Объект готового файла Cluster либо его ID.
Результат
Response. Передаёт файл Cluster как тело запроса с сохранением выбранных метода и заголовков. Одновременное отдельное тело запрещено.
Права
Нужны web.request + files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение. Ограничение domains проверяется при запросе; web.full может заменить web.request.
Ошибки
ValueError('An upload cannot also have a request body'): условие проверяется до продолжения операции.- Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
- UnicodeError/ValueError при неподдерживаемом адресе или кодировании; HTTP 4xx/5xx возвращаются как Response, пока не вызван raise_for_status().
Пример
result = await request.upload("file-id")