Справочник HTTP-клиента
Основные классы импортируются из duckonet. Там, где нужен импорт из отдельного модуля, указан полный путь. Все значения по умолчанию и ограничения относятся к версии 0.11.5.
HttpClient и AsyncHttpClient
Все аргументы конструктора передаются по имени. Используйте with HttpClient(...) для синхронного кода и async with AsyncHttpClient(...) для асинхронного. Подготовка установки и проверка профиля выполняются при входе в контекст.
| Аргумент | Значение по умолчанию и назначение |
|---|---|
| api_key | Обязательная строка с API-ключом DuckoLab. Не используется для авторизации на целевом сайте. |
| browser | Семейство профиля: 'chrome' (по умолчанию) или 'edge'. Доступные версии определяются каталогом и правами API-ключа. |
| version | None — выбрать доступную версию при открытии; полная строка — закрепить её; "last" — подготавливать обновления и выбирать их между полными прогонами client.run(). |
| application | h2 — вариант сетевого профиля по умолчанию. Для обычного выбора HTTP-протокола удобнее параметр protocol. Подробнее о вариантах — в разделе Client и AsyncClient. |
| protocol | По умолчанию не задан: используется application. Принимает h1, h2, h3, auto и имеет приоритет над application. h1 выбирает HTTP/1.1; h3 и auto допускают HTTP/2 с последующим переходом на HTTP/3. Обычный proxy URL не поддерживает h3/auto. Явный MasqueProxy с protocol='h3' выбирает строгий H3 через HTTPS/H2 CONNECT-UDP; AUTO для MASQUE не предоставляется. Фактический протокол — response.protocol. |
| state_dir | None — каталог ~/.duckonet/default. Можно передать собственный постоянный путь. |
| check_interval | 300 секунд; целое число от 0 до 3600. Минимальный интервал между проверками обновлений при открытии клиента. При 0 проверка выполняется при каждом открытии нового клиента. |
| allow_offline | True — разрешить работу с ещё действительными локальными файлами при недоступности сервиса. Подписи, сроки и права продолжают проверяться. |
| channel, bundle | None — штатный подписанный канал и комплект файлов. Задаются для собственной схемы поставки. |
| profile_id | None, явный ID подписанного профиля. |
| ca_bundle | None — стандартная настройка доверенных CA. Можно указать путь к PEM-файлу сертификатов для HTTPS-соединения; это не переключатель отключения проверки. |
| proxy | None — прямое подключение; иначе URL-строка или ProxyRoute. |
| cookie_policy | None — стандартная политика; иначе CookiePolicyOptions для хранилища cookies. |
| headers | None — без собственных общих заголовков; иначе словарь, пары или Headers. |
| cookies | None — без добавочных cookies. Заданные значения применяются к каждому запросу, но не заполняют хранилище. |
| timeout_seconds | 30 секунд. Общее время подготовки и выполнения одного запроса, включая перенаправления. Число больше 0 и не больше 300. Интервал запуска клиента сюда не входит. |
| allow_redirects, max_redirects | True и 20; строго bool и целое 0..100. |
| body_limit, header_limit | 1048576 и 65536 байт. Лимит тела ответа в памяти и лимит сохраняемых заголовков. Целые числа от 1 до 67108864 (64 MiB) и от 1 до 1048576 (1 MiB) соответственно. |
| cookies_enabled, persist_cookies | True/True. Первое управляет отправкой cookies, второе — сохранением Set-Cookie из ответов в памяти клиента. На диск эти параметры cookies не сохраняют. |
| encoding | None — UTF-8 при отправке. Для ответа явно указанная кодировка имеет приоритет над charset и UTF-8. |
| preserve_url, diagnostics, allow_downgrade | False, строго bool: сохранение формы пути URL, включение диагностики и разрешение переходов HTTPS → HTTP соответственно. |
client.cookies возвращает хранилище cookies открытой сессии, client.capabilities — её возможности. distribution даёт доступ к управлению установкой. До входа в контекст startup_info равно None; после входа содержит результат подготовки. Объект открывается только один раз; после закрытия создавайте новый экземпляр. Запрос к закрытому или ещё не открытому клиенту отклоняется с кодом STARTUP_CLIENT_NOT_OPEN.
Методы
request(method, url, **kwargs) возвращает HttpResponse. Сокращённые методы get, head, post, put, patch, delete и options принимают url и те же именованные аргументы. У асинхронного клиента они вызываются с await.
Через request() допустимы стандартные методы, включая TRACE, и дополнительные методы с корректным HTTP-именем. CONNECT запрещён. Стандартные имена приводятся к верхнему регистру; регистр дополнительных имён сохраняется.
stream(method, url, **kwargs) открывает поток через with или async with. consume(method, url, consumer, *, chunk_size=65536, **kwargs) передаёт части тела обработчику consumer и возвращает HttpResponse. Размер части — целое число от 1 до 16777216 байт. Асинхронный обработчик может вернуть объект, поддерживающий await. Если обработчик вызвал исключение, оно передаётся после закрытия контекста. close() и await close() завершают работу клиента.
Клиент сохраняет до восьми сочетаний варианта профиля и прокси, включая исходный маршрут. Повторное использование сочетания не расходует новый слот. Попытка создать девятый маршрут вызывает ValueError; для другого набора маршрутов создайте отдельный клиент. Все маршруты одного клиента используют общее хранилище cookies.
Аргументы запроса
Для request() обязательны method и url. URL должен быть абсолютным адресом HTTP(S). Логин и пароль в адресе, пробелы, управляющие символы и обратная косая черта запрещены. Фрагмент после # удаляется. Порт проверяется до чтения переданных файлов. Ограничения IDNA и IPv6 приведены ниже.
| Аргумент | Назначение |
|---|---|
| params=None | Словарь или упорядоченные пары; params=None не добавляет параметры. Повторы сохраняются, значения list/tuple разворачиваются. None внутри отдельного поля означает пустое значение: params={"q": None} даёт q=. Параметры дополняют существующую строку запроса. |
| headers | Если не задано — заголовки клиента. Явные пары заменяют все его поля с теми же именами без учёта регистра; остальные сохраняются. Новые поля добавляются в переданном порядке. None очищает собственные заголовки клиента для этого запроса, пустой список — не очищает. |
| body | bytes; отсутствие отличается от b''. |
| data | bytes, str либо словарь/пары для формы URL-encoded. None означает явно присутствующее пустое тело. |
| json | Значение для сериализации: словарь, список, строка, число, bool или None. json=None отправляет JSON null. Используется UTF-8; Unicode сохраняется, NaN запрещён. |
| files=None | Словарь или пары. Значение: bytes, бинарный читаемый объект, (filename, content) или (filename, content, content_type). Тип по умолчанию — application/octet-stream. Вместе с files можно передать поля формы через data. |
| encoding | Если не задано — настройка клиента. None выбирает UTF-8 для отправки и charset либо UTF-8 для ответа. JSON требует UTF-8. |
| cookies | Если не задано — добавочные cookies клиента. None или пустые пары убирают эту добавку для запроса; автоматическое хранилище продолжает работать. |
| cookies_enabled, persist_cookies | Если не задано — настройка клиента; строго bool. |
| proxy, protocol | Если не заданы — маршрут клиента. proxy=None явно выбирает прямое соединение. protocol: h1, h2, h3 или auto. |
| timeout_seconds | Если не задано — таймаут клиента. Число больше 0 и не больше 300 секунд. |
| allow_redirects, max_redirects, allow_downgrade | Настройки клиента, bool/int 0..100/bool. |
| body_limit, header_limit | Если не заданы — настройки клиента. Размеры в байтах; диапазоны те же, что в конструкторе. |
| preserve_url, diagnostics | Настройки клиента, если не заданы; иначе bool. preserve_url не сохраняет фрагмент и не отключает проверку URL. |
| context | BrowserHopContext с исходной страницей, сайтом верхнего уровня и правилами cookies. Нужен, когда контекст отличается от URL самого запроса. Допустимы mode="cors", preflight=False; body_present должен соответствовать наличию тела. Сам контекст не запускает CORS-проверки или preflight. |
| advanced=None | Словарь только с timeout_ms, body_limit, header_limit и context. Нельзя одновременно задать тот же параметр напрямую. advanced.timeout_ms конфликтует с timeout_seconds. Неизвестные имена отклоняются. |
Приоритет настроек: аргумент запроса → настройка клиента → значение по умолчанию. advanced.timeout_ms принимает целое число от 1 до 300000 миллисекунд. timeout_seconds задаётся в секундах и округляется вверх до миллисекунд, минимум — 1 мс.
Общий таймаут начинается при подготовке HTTP-вызова. Он включает кодирование тела, чтение файлов, выбор маршрута, перенаправления, заголовки, тело ответа и обработчик consume(). Он не включает регистрацию и обновление при входе в клиент. Блокирующий Python-вызов file.read() или обработчик нельзя прервать посередине: срок проверяется после возврата управления. Отдельных таймаутов подключения и чтения в этом API пока нет.
body нельзя сочетать с data, json или files; json — с data или files. Для JSON и формы Content-Type добавляется, если вы не задали его явно. Для multipart разделитель и Content-Type выбирает библиотека; собственный Content-Type вместе с files запрещён. Максимальный размер отправляемого тела — 16777216 байт (16 MiB), включая разделители multipart.
У обычного ответа лимит тела по умолчанию — 1 MiB, максимум — 64 MiB. Например, body_limit=10*1024*1024 разрешает сохранить 10 MiB. При потоковом чтении этот параметр ограничивает внутренний буфер, а не общий объём скачивания.
Ответ gzip уже распакован в content; лимит применяется к распакованным данным. Повторно вызывать gzip.decompress() не нужно. Заголовки Content-Encoding и Content-Length могут описывать исходный сжатый ответ.
Имена заголовков должны быть допустимыми ASCII-именами HTTP; значения принимаются как str или bytes в Latin-1. Управляющие символы запрещены, кроме HTAB. Библиотека сама управляет Host, Content-Length, Transfer-Encoding, Connection, Proxy-Connection, Upgrade, Trailer, TE и псевдозаголовками HTTP/2 и HTTP/3.
Для авторизации прокси задавайте учётные данные маршрута, а не Proxy-Authorization. Заголовок Cookie проходит те же правила, что параметр cookies. Профильные User-Agent, Accept, Accept-Language и Accept-Encoding применяются к HTTP и HTTPS; защищённые Client Hints — только к HTTPS. Допустимое явно заданное значение заменяет профильное поле с тем же именем. Ответ при этом сохраняет assurance=custom-request.
Перенаправления
При allow_redirects=True клиент следует перенаправлениям 301, 302, 303, 307 и 308. При False он возвращает исходный ответ 3xx. history содержит предыдущие ответы HttpResponse; response.url — конечный URL в bytes. Ответ 3xx без Location возвращается без перехода.
HttpRedirectError содержит code и ответ текущего перехода в response. Возможные коды: HTTP_REDIRECT_LOCATION_AMBIGUOUS — несколько Location; HTTP_REDIRECT_LOCATION_INVALID — пустой или неверный адрес; HTTP_REDIRECT_LIMIT — превышен лимит; HTTP_REDIRECT_DOWNGRADE — запрещён переход HTTPS → HTTP.
301 и 302 меняют POST на GET. 303 меняет на GET любой метод, кроме GET и HEAD. При такой замене удаляются тело и заголовки content-type, content-encoding, content-language, content-location. 307 и 308 сохраняют метод и тело.
При смене origin (схемы, хоста или порта) удаляются Authorization, Cookie, Cookie2, Proxy-Authorization и одноразовые cookies запроса. Хранилище выбирает подходящие cookies для нового URL. При сохранении origin одноразовые cookies продолжают действовать. Повторный переход на тот же URL допустим: ответ мог изменить cookies. Циклы ограничивает max_redirects; список предыдущих URL в контексте выбора cookies ограничен 100 записями.
HttpResponse
HttpResponse(raw_response, history=(), encoding=None) — неизменяемая обёртка над исходным Response. history хранится как кортеж, encoding задаёт кодировку ответа. Следующие поля доступны непосредственно у ответа:
| Поле | Тип и назначение |
|---|---|
| status_code | int — HTTP-код |
| protocol | int — фактический протокол: 1, 2 или 3 |
| body, content | bytes или None — сохранённое тело. None означает, что в этом объекте тела нет, например при потоковом чтении. |
| url | bytes — конечный URL |
| blocks | tuple[ResponseBlock] — сохранённые блоки ответа |
| request_id, owner_id, epoch | int — идентификаторы запроса и владельца |
| outcome | int — результат выполнения на нативном уровне |
| body_complete | bool — получено ли тело полностью |
| body_bytes_received | int — число полученных байт |
| tls_verified | bool — признак завершённой проверки TLS. У потокового ответа итоговое значение читайте после result(). |
content возвращает raw_response.body. raw_headers — кортеж пар (bytes, bytes) финального блока, headers — объект Headers, сохраняющий повторы. reason всегда равно None: нативный ответ не содержит текстовую фразу статуса. assurance всегда равно custom-request. Поля diagnostics и timings содержат словарь либо None, если наблюдение недоступно.
text вызывает decode(). Метод decode(encoding=None, errors='strict') выбирает кодировку в порядке: аргумент метода → response.encoding → charset из Content-Type → UTF-8. При content=None методы decode(), json() и свойство text вызывают ValueError.
json(*, encoding=None, **kwargs) декодирует текст и вызывает json.loads() с переданными аргументами. Ошибки Unicode и JSON передаются вызывающему коду. raise_for_status() вызывает HTTPStatusError только для кодов 400–599; исключение содержит response и status_code.
Headers и подготовка запроса
Headers(values=()) принимает словарь, последовательность пар или другой Headers. Сохраняет регистр, порядок и повторяющиеся имена. [name] и get(name, default) ищут без учёта регистра и возвращают первое значение. get_all(name) возвращает кортеж всех значений, multi_items() — все пары в исходном порядке.
Итерация возвращает уникальные имена в первом написании; len() считает уникальные имена. Повторные Set-Cookie не склеиваются. repr() показывает количество полей, не их значения.
Если нужно подготовить запрос без отправки, используйте вспомогательные средства из duckonet.http_models306:
UNSET— отсутствие аргумента, отличное от явногоNone.MAX_REQUEST_BODY=16777216— предел тела запроса.normalize_headers(headers=None)— проверяет исходящие заголовки и возвращаетHeaders.encode_request(method, url, *, params=None, headers=None, body=UNSET, data=UNSET, json=UNSET, files=None, encoding=None)— подготавливает метод, URL, заголовки и тело без отправки. Переданные файлы читает во время вызова и оставляет открытыми.
Результат кодирования — неизменяемый EncodedRequest: method и url имеют тип str, headers — кортеж пар строк, body — bytes, body_present и custom_headers — bool, assurance — str. Значение profile-defaults означает отсутствие собственных заголовков, custom-request — их наличие. Это описание настроек, а не проверка совпадения сетевого отпечатка. У итогового HttpResponse значение остаётся custom-request.
Имена полей URL и формы принимаются как str или bytes. Значения — str, bytes, int, float, bool, None либо список или кортеж этих типов. Файловый объект должен возвращать байты. Открытие и закрытие переданного файла остаётся обязанностью приложения.
Поддержка URL
Передавайте полный URL строкой, например https://example.com/api/items. Фрагмент после # не отправляется. Параметры params дополняют существующую строку запроса; библиотека не меняет http:// на https://.
Unicode-домен не преобразуется автоматически в IDNA. IPv6-адрес непосредственно в URL, например https://[::1]/, у этого интерфейса не поддерживается: запрос завершается ошибкой возможности до подключения. Не путайте это ограничение с обработкой адреса прокси — у него отдельные правила.
HttpResponse.url возвращает конечный адрес в виде bytes. Если нужна строка, декодируйте его явно. Параметр preserve_url=True сохраняет форму пути, но не отменяет проверку адреса и удаление фрагмента.
WebSocket
client.websocket(url, **options) возвращает sync/async менеджер контекста. После открытия доступны send, recv, ping, close, abort, свойства handshake/selected_subprotocol/generation_receipt. Параметры, сроки, очереди, cookies, ошибки и примеры описаны полностью в руководстве WebSocket.
Полные прогоны и длительные соединения
run(), browser_profile и profile_update_status описаны вместе с правилами смены профиля. websocket() открывает WebSocket; MasqueProxy задаёт маршрут HTTP/3 через совместимый прокси. Эти возможности доступны синхронному и асинхронному HTTP-клиенту.