HTTP-запросы, venv и упаковка

HTTP через requests: четыре вещи, которые нельзя пропускать

requests — де-факто HTTP-клиент Python: для Python он то же, что fetch для браузера, только синхронный и куда удобнее стандартного urllib. GET с query-параметрами и JSON-ответом — это три строки:

import requests

resp = requests.get(
    "https://api.example.com/search",
    params={"q": "python", "limit": 10},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()          # превратить 4xx/5xx в исключение
data = resp.json()               # разобранный dict, как await resp.json() у fetch

POST с JSON — той же формы: передаёшь json=, и requests сериализует тело и сам ставит Content-Type: application/json:

resp = requests.post(url, json={"name": "ada"}, timeout=10)

Две привычки отличают скрипт, который выживает в проде, от того, что виснет или врёт:

• Всегда передавай timeout=. Это сеньорский момент и тот, что упускают новички. По умолчанию requests ждёт вечно. Один медленный или мёртвый апстрим заморозит весь твой скрипт — или каждый воркер в пуле — без ошибки и без восстановления. У fetch тот же пробел (нужен AbortController); в Python ты просто передаёшь число.
• Вызывай raise_for_status(). В отличие от fetch, который отклоняется только при сетевом сбое и спокойно резолвит 500, requests по умолчанию не бросает исключение на 4xx/5xx — resp выглядит нормально, а resp.json() может вернуть тело с ошибкой, которое ты примешь за данные. raise_for_status() превращает плохой статус в HTTPError, который можно поймать. (fetch — зеркало: там ты сам проверяешь resp.ok.)

Для множества параллельных вызовов или async-приложения бери httpx — та же поверхность API, что у requests, но с async/await и HTTP/2. Retry с backoff стоит завести для любого реального апстрима: на 429 или 503 подожди 0.5с, 1с, 2с… и повтори несколько раз, а не падай на первом же сбое. (Библиотеки вроде tenacity или адаптер Retry из urllib3 делают это за тебя.)

Выигрыш для AI-склейки: безопасный вызов LLM HTTP API

Бо́льшая часть «AI-интеграции» — ровно этот паттерн: POST JSON-тела на эндпоинт провайдера с заголовком авторизации, затем разбор JSON, который вернулся. Сеньорская деталь — где живёт ключ: никогда в исходниках.

import os
import requests

api_key = os.environ.get("LLM_API_KEY")  # читаем из окружения, не из файла
if not api_key:
    raise RuntimeError("LLM_API_KEY не задан")

resp = requests.post(
    "https://api.provider.example/v1/chat/completions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "some-model",
        "messages": [{"role": "user", "content": "Суммируй этот тикет: ..."}],
    },
    timeout=30,                          # LLM медленные; дай им запас, но ограничь
)
resp.raise_for_status()
reply = resp.json()["choices"][0]["message"]["content"]

os.environ["LLM_API_KEY"] — это Python-аналог process.env.LLM_API_KEY. Ты задаёшь его в shell, в .env, загружаемом через python-dotenv, или в хранилище секретов деплой-платформы — и ключ никогда не появляется в репозитории, в git history или при демонстрации экрана. Хардкод ключа — самый частый способ утечки учётных данных. Щедрый timeout=30 тут тоже важен: ответы модели медленные, поэтому тесный таймаут отменяет хорошие запросы, а отсутствие таймаута означает, что одна застрявшая генерация вешает твой инструмент бесконечно.

Окружения и упаковка: зачем нужен venv

Спроси себя: сколько Python-проектов у тебя или коллег на одной машине? Каждый предъявляет свои требования к версиям библиотек — а по умолчанию Python позволяет им всем делить одну глобальную папку установки. Вот провал коллеги из хука. Python по умолчанию ставит пакеты в один глобальный site-packages, общий для каждого проекта на машине. Проекту A нужен urllib3==1.26; проекту B нужен urllib3==2.x. При глобальной установке второй pip install перезаписывает первый — и теперь тот проект, что загрузит неверную версию, ломается. Нет node_modules на проект, чтобы их развести.

Виртуальное окружение (venv) — и есть эта граница на проект. Это лёгкая изолированная копия интерпретатора со своим site-packages, поэтому зависимости каждого проекта живут в своей папке и никогда не сталкиваются:

python -m venv .venv          # создать изолированное окружение в ./.venv
source .venv/bin/activate     # macOS/Linux  (Windows: .venv\Scripts\activate)
pip install requests httpx    # ставит В .venv, не глобально

Пока окружение активно, python и pip указывают на .venv — аналогично тому, как node_modules ограничивает пакеты одним проектом, только venv изолирует сам интерпретатор, а не одни библиотеки. Папку .venv/ добавляешь в .gitignore (как node_modules/), а вместо неё коммитишь манифест, чтобы кто угодно мог её пересоздать.

Пиннинг: requirements.txt и переход к pyproject.toml

Изоляция — половина истории; вторая половина — воспроизводимость. Если ты pip install requests сегодня, а коллега через месяц, вы можете получить разные версии. Пинни их. Классический файл — requirements.txt:

requests==2.32.3
httpx==0.27.2

Воссоздаёшь точный набор через pip install -r requirements.txt внутри свежего venv. Это package.json + lock-файл, разнесённые по соглашению, а не в один файл. Современный стандартизированный дом для метаданных и зависимостей проекта — pyproject.toml (PEP 621): объявление зависимостей там плюс быстрый резолвер вроде uv или poetry даёт настоящий lock-файл и настройку одной командой, гораздо ближе к опыту npm install. Для быстрого скрипта requirements.txt сойдёт; для всего, что ты отгружаешь или делишь, предпочитай pyproject.toml.