Привет, Хабр!

Если вы собираете прототип на C++, то один файл с main.cpp иногда реально компилируется в рабочую утилиту. Библиотеки либо завозятся пакетным менеджером заранее, либо у вас есть header‑only зависимость и всё взлетает. В Python долгое время это было болью: любой однофайловый скрипт, который требует requests или rich, уже тянет за собой виртуальные окружения, инструкции в README и локальные фичи.

Есть рабочий стандарт для нормальных однофайловых сценариев с зависимостями — PEP 723: вы объявляете зависимости прямо в комментариях, а раннер ставит всё сам и запускает в изолированной среде. В связке с uv получается неплохой такой способ делиться скриптами, в том числе для пвспомогательных задач. И да, у этой красоты есть нюансы безопасности, о них поговорим отдельно.

Что такое PEP 723 и как это выглядит

PEP 723 определяет блок метаданных в комментариях, который парсится внешними инструментами. Формат прост: сверху и снизу маркеры, внутри TOML c полями dependencies и requires-python.

Пример минимального скрипта:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "httpx<1.0",
#   "rich>=13.7",
# ]
# ///
import httpx
from rich import print

def main() -> None:
    r = httpx.get("https://httpbin.org/json", timeout=10)
    r.raise_for_status()
    print({"status": r.status_code, "len": len(r.text)})

if __name__ == "__main__":
    main()

Запуск через uv:

uv run example.py

uv создаст изолированную среду в кеше, установит зависимости и выполнит код. Никаких ручных venv.

Добавляем и управляем зависимостями прямо из CLI

PEP 723 — это про формат, но править TOML руками быстро надоедает. uv умеет редактировать блок зависимостей в файле:

uv add --script example.py "pydantic>=2.8"
uv remove --script example.py "httpx"
uv run example.py

Если нужен исполняемый файл без явного вызова uv run, используем shebang:

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["rich"]
# ///
from rich import print
print("hello")

Ставим права и запускаем из каталога:

chmod +x greet
./greet

Лочим зависимости и делаем скрипт воспроизводимым

Одно дело установить актуальные версии, другое — зафиксировать их. uv поддерживает lock‑файл для скриптов.

uv lock --script example.py
# появится example.py.lock

# теперь любые операции будут учитывать lock:
uv run --script example.py
uv add --script example.py "rich"      # обновит lock
uv export --script example.py -o req.txt

Можно ограничить свежесть пакетов датой, чтобы избежать неожиданных апдейтов через год. В блоке [tool.uv] внутри метаданных:

# /// script
# requires-python = ">=3.11"
# dependencies = ["httpx<1.0"]
# [tool.uv]
# exclude-newer = "2025-08-01T00:00:00Z"
# ///

exclude-newer заставит резолвер игнорировать релизы, вышедшие после указанной даты.

А если нужно именно pip‑совместимое зафиксированное дерево для длительных CI‑пайплайнов, у uv есть инструменты уровня pip-tools: uv pip compile и uv pip sync. Они позволяют сгенерировать requirements.txt из исходника‑декларации и синхронизировать окружение один‑в‑один.

Контроль версии Python на рантайме

Скрипт может требовать конкретную ветку интерпретатора. В этом случае uv позволяет запросить нужную версию при запуске:

uv run --python 3.10 example.py
uv run --python 3.12 example.py

Безопасность

Однофайловые скрипты удобно запускать как есть, и именно поэтому надо быть аккуратнее обычного. Риски:

1. Подмена зависимостей. Тривиальные атаки на цепочку поставок через зарегистрированные пакеты с похожими именами.

2. Непредсказуемые апгрейды. Сегодня всё чисто, завтра новый релиз транзитивной зависимости ломает инварианты.

3. Источники пакетов. Переопределение индексов, отключение TLS‑проверок, внутренние зеркала без политики.

4. Уязвимости в уже выбранных версиях.

Конкретные меры:

Фиксация и аудит. Для скриптов создаём example.py.lock и регулярно прогоняем аудит зависимостей. В экосистеме PyPA для этого есть pip-audit, он использует базу уязвимостей PyPI и может работать поверх вашего requirements или установленной среды. Можно запускать через uvx в изолированном окружении:

uvx pip-audit -r req.txt
# или просканировать локальную среду
uvx pip-audit --local

Проект поддерживается PyPA, есть GitHub Action.

Хеши и синхронизация. Для больших пайплайнов можно генерировать requirements с хешами, а устанавливать через uv pip sync, чтобы окружение соответствовало файлу один к одному. Управление хешами и параметры компиляции конфигурируются в uv.toml/pyproject.toml для uv pip compile.

Индексы и TLS. Не используем доверенные небезопасные хосты. В справочнике CLI прямо есть предупреждение: флаг --allow-insecure-host отключает верификацию цепочки сертификатов, что делает вас уязвимыми для MITM.

Воспроизводимость по времени. Добавляем exclude-newer к скрипту, держите lock рядом с ним, а CI запускайте с uv run --script или с экспортом в requirements.txt и последующим uv pip sync.

Сценарий: маленький CLI-интеграционный скрипт

Условие: нужен однофайловый инструмент для выгрузки данных из API, с ретраями и логами, без установки проекта и с воспроизводимыми версиями.

fetch_users.py:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "httpx==0.27.2",
#   "tenacity==9.0.0",
#   "structlog==24.4.0",
# ]
# [tool.uv]
# exclude-newer = "2025-08-01T00:00:00Z"
# ///
from __future__ import annotations

import os
import sys
import json
import time
import httpx
import structlog
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type

log = structlog.get_logger()

API_URL = os.environ.get("API_URL", "https://httpbin.org/json")
TIMEOUT = httpx.Timeout(10.0, connect=5.0)

class FetchError(RuntimeError):
    pass

@retry(
    reraise=True,
    stop=stop_after_attempt(4),
    wait=wait_exponential(multiplier=0.5, min=0.5, max=5),
    retry=retry_if_exception_type((httpx.HTTPError, FetchError)),
)
def fetch_json(client: httpx.Client, url: str) -> dict:
    r = client.get(url)
    if r.status_code >= 500:
        # серверная ошибка — пробуем повторить
        raise FetchError(f"server_error={r.status_code}")
    r.raise_for_status()
    return r.json()

def main() -> int:
    structlog.configure(processors=[structlog.processors.add_log_level, structlog.processors.JSONRenderer()])
    with httpx.Client(timeout=TIMEOUT, headers={"User-Agent": "fetch-users/1.0"}) as client:
        t0 = time.perf_counter()
        data = fetch_json(client, API_URL)
        dt = time.perf_counter() - t0
        log.info("fetched", bytes=len(json.dumps(data).encode("utf-8")), seconds=round(dt, 3))
        print(json.dumps(data, ensure_ascii=False))
    return 0

if __name__ == "__main__":
    try:
        sys.exit(main())
    except httpx.RequestError as e:
        log.error("http_error", error=str(e))
        sys.exit(2)
    except Exception as e:
        log.error("unexpected", error=str(e.__class__.__name__))
        sys.exit(3)

Запуск:

uv run fetch_users.py
# закрепляем версии рядом со скриптом
uv lock --script fetch_users.py
# экспорт для CI
uv export --script fetch_users.py -o requirements.txt
uvx pip-audit -r requirements.txt

uv задокументировал и lock для скриптов, и экспорт.

Инспекция дерева зависимостей и политика источников

Перед выкладкой в хук pre‑commit можно обозреть дерево:

uv tree --script fetch_users.py

Для частных индексов и зеркал используем конфигурационные файлы uv.toml или pyproject.toml для uv pip и не раздаем --allow-insecure-host. Конфиги поддерживаются на уровне проекта и пользователя; есть и системный уровень. Путь к кешу и параметры можно контролировать через команды и переменные окружения.

Итог

PEP 723 решает рутину: однофайловые скрипты могут быть самодостаточными, без вопросов о том, как установить зависимости. uv сделал это быстрым и операционно удобным: редактирование зависимостей, shebang, lock рядом со скриптом, экспорт для CI, контроль версии интерпретатора.

Как и в случае с однофайловыми скриптами по PEP 723 и uv, которые позволяют быстро проверить идею без лишних подготовительных шагов, у вас есть возможность так же познакомиться с курсом Python Developer. Professional — через бесплатные открытые уроки, доступные по ссылке.

Кроме того, вы можете пройти бесплатное вступительное тестирование, которое позволит оценить ваши знания и навыки.

А если хотите узнать больше о самом курсе и впечатлениях участников, загляните в секцию с отзывами.