Асинхронная клиентская библиотека должна упрощать типовой сценарий, не превращая протокол под ней в чёрный ящик. Практичный компромисс — небольшой типизированный интерфейс поверх транспорта, который остаётся явным и заменяемым.
Не скрывайте границу транспорта
Принимайте httpx.AsyncClient (или небольшой совместимый с ним протокол), а не
создавайте незаметно новый клиент для каждого запроса. Тогда вызывающее
приложение может управлять пулом соединений, таймаутами, прокси и тестовым
транспортом.
from typing import Protocol
class AsyncTransport(Protocol):
async def get(self, url: str, **kwargs: object) -> "Response": ...
Сам протокол может быть уже, чем интерфейс полноценной HTTP-библиотеки. Важно не забирать у вызывающей стороны конфигурацию, которую библиотека не может обоснованно выбрать за неё.
Ошибки — часть контракта
У API есть не только успешные ответы. Полезная библиотека различает сетевые сбои, ответы с неподходящим статусом и некорректные данные. Сохраняйте исходный ответ или исключение: тогда вызывающая сторона сможет проверить статус, заголовки и идентификатор запроса.
Не превращайте каждую ошибку в None. Отсутствующий ресурс, недоступная сеть и
сломанный ответ сервера требуют разной обработки.
Типизируйте границу, а не каждую переменную
Задавайте точные модели там, где данные входят в библиотеку или выходят из неё; детали реализации можно оставить обычному выводу типов. Так интерфейс пакета остаётся понятным пользователям, а вспомогательный код не превращается в головоломку из аннотаций.
В результате клиент остаётся асинхронным, но его публичные методы легко тестировать, настраивать и понимать.