Запросы, ответы и авторизация

Быстрый запрос

import os
from duckonet import get

response = get(
    'https://example.com/',
    api_key=os.environ['DUCKONET_API_KEY'],
    browser='chrome',
    version='last',
)
print(response.status_code)
print(response.text)

request(method, url, *, api_key, browser='chrome', version=None, state_dir=None, client_options=None, **kwargs) открывает временный HttpClient, выполняет один запрос и закрывает клиент. Ответ остаётся доступен после закрытия. Параметры самого клиента, например прокси и ограничения, передаются словарём client_options; параметры запроса — именованными аргументами. api_key и browser нельзя дублировать в client_options. Явные version и state_dir также не должны дублироваться там.

Сокращения get, head, post, put, patch, delete, options принимают url и те же именованные аргументы. Для асинхронного кода доступны async_request, async_get, async_head, async_post, async_put, async_patch, async_delete, async_options; их результат нужно ожидать через await.

Эти функции возвращают буферизованный ответ. Потоковое чтение требует явно открытого клиента и client.stream(...). Для серии запросов также держите один клиент открытым, чтобы переиспользовать его состояние и соединения.

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

Пример с общим адресом и параметрами:

import os
from duckonet import HttpClient

with HttpClient(
    api_key=os.environ['DUCKONET_API_KEY'],
    browser='chrome',
    version='last',
    base_url='https://example.com/api/',
    params={'language': 'ru'},
    raise_for_status=True,
) as client:
    response = client.get('items', params={'page': 2})
    print(response.json())

AsyncHttpClient использует те же настройки; открывайте его через async with, запросы выполняйте через await.

Настройки соединения network, tls, rate_limit также принимают Client, AsyncClient, Distribution.session и Distribution.async_session. При прямом создании транспорта они входят в TransportConfig. Они задаются для сессии, а не меняются посреди уже работающего соединения.

Дополнительные параметры client.request и сокращений get/post/других методов:

BasicAuth(username, password, encoding='latin-1') формирует HTTP Basic. Для UTF-8 укажите encoding='utf-8'; двоеточие в имени пользователя и управляющие символы запрещены. BearerAuth(token) формирует Bearer-заголовок. Эти объекты не показывают свои секреты в repr.

Helper авторизации нельзя совмещать с явным Authorization в том же запросе. Авторизацию другого сервера задавайте отдельным клиентом либо явным параметром запроса. API-ключ DuckoNet предназначен для доступа к библиотеке; он не является Bearer-токеном вашего целевого сайта.

У обоих helper-объектов authorization() возвращает готовое секретное значение заголовка. Обычно вызывать метод вручную не требуется; не выводите его результат в журнал.

Остальные правила запросов сохраняются: json=None отправляет JSON null; body содержит bytes, data — текст, байты или поля формы; для больших тел используйте существующий upload. Общий таймаут ограничивает весь запрос, перенаправления и повторы вместе.

Ответ

cookies_received — снимок атрибутов ответа, а не контейнер действующих cookies. accepted=None означает, что снимок не содержит вердикта cookie-политики. Действующие cookies продолжает обслуживать client.cookies; повторно добавлять весь Set-Cookie из снимка не нужно.

request_info не является записью сырых пакетов. Пользовательские заголовки и путь URL могут содержать данные приложения: не публикуйте такой снимок без собственного контроля. Для журнала без заголовков и пути используйте diagnostic_hook.

Существующие content, text, decode, json, headers, history и raise_for_status сохраняют своё назначение. При автоматической ошибке HTTP-статуса ответ находится в HTTPStatusError.response.

Чтение по строкам

import os
from duckonet import HttpClient

with HttpClient(api_key=os.environ['DUCKONET_API_KEY']) as client:
    with client.stream('GET', 'https://example.com/events') as stream:
        for line in stream.iter_lines(encoding='utf-8'):
            print(line)

stream.iter_lines(*, encoding=None, errors='strict', max_line_bytes=1048576, chunk_size=65536) возвращает строки без разделителей. Поддерживаются LF, CRLF и CR, пустые строки и последняя строка без завершающего переноса. Кодировка выбирается по явному параметру, настройке потока, charset ответа, затем UTF-8. Ошибки декодирования обрабатываются согласно errors.

max_line_bytes — предел кодированного представления одной строки, от 1 до 16777216. chunk_size — порция чтения, в том же диапазоне. Превышение предела строки вызывает ValueError; неверные байты при errors='strict' — ошибку декодирования. Для AsyncHttpClient используйте async with client.stream(...) и async for line in stream.aiter_lines(...); iter_lines у асинхронного потока возвращает тот же асинхронный итератор.

При досрочном выходе закрывайте контекст потока. Если сам итератор строк закрыт до EOF, он отменяет незавершённый запрос. Все тело целиком для разделения строк не накапливается.

Выбор браузерной версии на один прогон

import os
from duckonet import HttpClient

with HttpClient(api_key=os.environ['DUCKONET_API_KEY'], version='last') as client:
    print(client.available_browser_versions(version_range=(150, 155)))
    with client.run(version_range=(150, 155), random_profile=True):
        print(client.browser_profile)
        response = client.get('https://example.com/')

available_browser_versions(*, version_range=None) возвращает кортеж доступных версий из подписанного совместимого каталога с учётом прав аккаунта и текущего протокола. Метод вызывается на открытом клиенте. Диапазон — включительно, два целых major-номера; он не создаёт отсутствующие версии.

run(*, version_range=None, random_profile=False) фиксирует профиль на полный прогон. Если задан диапазон и random_profile=False, выбирается старшая доступная версия диапазона; при True — один случайный допустимый профиль. Все запросы, перенаправления и повторы внутри прогона используют этот выбор. Вложенный прогон не может произвольно заменить уже закреплённый профиль. Диапазон несовместим с явным profile_id.

Асинхронный вариант использует async with client.run(...); список версий и свойство browser_profile читаются обычным вызовом. Cookies остаются в общем контейнере логического клиента. version='last' продолжает означать последнюю разрешённую версию, а переход на обновлённый профиль происходит между полными прогонами.

Текст страницы