` — локально установленная версия + metadata + место
(`Location: ...`).
```bash
pip index versions requests # все доступные версии
pip show --files requests # какие файлы установились
pip check # broken dependencies
```
---
## 5. Установка: `pip` vs `uv`
`pip` — это install-frontend из stdlib, работает всегда. `uv` даёт
тот же интерфейс и заметно быстрее на больших зависимостях. Учиться
командам заново не надо, `uv pip install X` делает ровно то же, что
`pip install X`.
### Сначала — виртуальное окружение
**Никогда** не ставь пакеты в системный Python (`/usr/bin/python` или
Homebrew). Причины:
- Права: `pip install` в системный Python требует `sudo` — легко
накатить что-то, что сломает утилиты системы, зависящие от Python.
- Изоляция версий: проект A хочет `requests==2.28`, B хочет
`requests==2.31`. В одном системном Python держать оба нельзя.
- Reproducibility: `pip freeze` системного Python — свалка всего когда-
либо ставленного, воспроизвести на другой машине невозможно.
Решение — **виртуальное окружение** (venv, PEP 405). Это отдельный
каталог с копией Python и своим `site-packages/`. Чтобы им
пользоваться, надо его активировать — подменить `$PATH` так, чтобы
`python` и `pip` шли из этого каталога:
```{code-cell} python
%%bash
python3 -m venv /tmp/example-venv
source /tmp/example-venv/bin/activate
which python pip
python -c "import sys; print(sys.prefix)"
```
Внутри активированного venv `pip install X` кладёт X в
`/tmp/example-venv/lib/pythonX.Y/site-packages/`, а не в системный. Всё
что ставится в venv — живёт только там, `rm -rf /tmp/example-venv/` и
всё удалено.
`uv` идёт дальше и делает venv за тебя автоматически: `uv sync` в
проекте создаёт `.venv/`, `uv run` — запускает команду в нём без явной
активации.
### pip + venv (классика)
```{code-cell} python
%%bash
rm -rf /tmp/venv-pip
python3 -m venv /tmp/venv-pip
/tmp/venv-pip/bin/pip install --quiet -e './demo-project[test,lint]'
/tmp/venv-pip/bin/pip list | head -10
```
### uv (современно)
```{code-cell} python
%%bash
rm -rf /tmp/venv-uv
uv venv /tmp/venv-uv
uv pip install --python /tmp/venv-uv/bin/python -e './demo-project[test,lint]' --quiet
uv pip list --python /tmp/venv-uv/bin/python | head -10
```
В курсе — оба
Проверяющий скрипт использует `pip install .[test]`, интерфейс общий —
подходит и pip-venv, и uv-venv. Выбирайте что удобнее; `uv` быстрее,
`pip` без внешних зависимостей.
### Editable install: зачем и почему
Показываем на живом примере что не так с обычным `pip install .` для
активной разработки.
**Шаг 1.** Копируем demo-project во временную директорию (чтобы
экспериментировать не портя оригинал), ставим обычным способом,
проверяем что работает:
```{code-cell} python
%%bash
rm -rf /tmp/greet-exp /tmp/venv-no-e
cp -r demo-project /tmp/greet-exp
python3 -m venv /tmp/venv-no-e
/tmp/venv-no-e/bin/pip install --quiet /tmp/greet-exp
/tmp/venv-no-e/bin/python -c "from greet import greet; print(greet('world'))"
```
**Шаг 2.** Правим исходник — меняем `Hello,` на `HI,`:
```{code-cell} python
!perl -i -pe 's/Hello,/HI,/' /tmp/greet-exp/src/greet/__init__.py
!cat /tmp/greet-exp/src/greet/__init__.py
```
Source изменился. Но:
```{code-cell} python
!/tmp/venv-no-e/bin/python -c "from greet import greet; print(greet('world'))"
```
**По-прежнему `Hello, world!`** — потому что `pip install .` скопировал
код в `site-packages/` при установке, там лежит **старая версия**. Наш
edit в source-каталоге к установленному пакету не относится.
**Шаг 3.** Что можно сделать — переустановить:
```{code-cell} python
%%bash
/tmp/venv-no-e/bin/pip install --quiet --force-reinstall --no-deps /tmp/greet-exp
/tmp/venv-no-e/bin/python -c "from greet import greet; print(greet('world'))"
```
Теперь `HI, world!`. Но представь что цикл «правка → тест» происходит
каждые 30 секунд — каждый раз переустанавливать невыносимо.
### Лечение — `-e`
`pip install -e /path` — **editable install**. Пакет как бы "ставится",
но `site-packages/` содержит не копию, а **ссылку** на source-каталог.
`import` идёт напрямую в твои файлы.
```{code-cell} python
%%bash
rm -rf /tmp/venv-e
python3 -m venv /tmp/venv-e
/tmp/venv-e/bin/pip install --quiet -e /tmp/greet-exp
/tmp/venv-e/bin/python -c "from greet import greet; print(greet('world'))"
```
Правим source ещё раз — теперь `HI,` -> `HEY,`:
```{code-cell} python
!perl -i -pe 's/HI,/HEY,/' /tmp/greet-exp/src/greet/__init__.py
!/tmp/venv-e/bin/python -c "from greet import greet; print(greet('world'))"
```
**Сразу видит `HEY, world!`** — никакой переустановки. Именно то что
нужно для активной разработки.
Когда использовать
- **Разработка своего пакета** — всегда `-e`, чтобы правки не требовали
переустановки.
- **Дебаг чужого форка** — `-e ~/forks/somelib` + правки прямо в клоне.
- **Не для прода** — deploy всегда обычный `pip install .` (без `-e`).
### Под капотом: `.pth` файл (PEP 660)
Механизм — файл `.pth` в `site-packages/`. Python при старте читает
все `*.pth` в этом каталоге и добавляет каждую строку как путь в
`sys.path`. У нас в venv-e:
```{code-cell} python
!find /tmp/venv-e/lib -name "__editable__*.pth" -exec cat {} \;
```
Одна строка — абсолютный путь к нашему `/tmp/greet-exp/src`. При
`import greet` Python идёт по `sys.path`, находит
`/tmp/greet-exp/src/greet/__init__.py` и импортит **оттуда** — прямо
из наших исходников. Никаких копий.
PEP 660 (2021) стандартизировал API editable install между backend'ами —
до этого каждый (setuptools, poetry, flit) реализовывал по-своему.
### Lock files
`pyproject.toml.dependencies` — **диапазоны** (`requests>=2.31`). Для
deploy нужны **точные версии** — иначе прод и dev расходятся.
Два подхода:
- **`pip freeze > requirements.txt`** — плоский `name==version`. Без
hashes, без extras, без markers.
- **`uv.lock` / `poetry.lock` / `pdm.lock`** — универсальный формат,
кросс-платформенный, с hashes, разделение direct/transitive.
```{code-cell} python
%%bash
cd demo-project
rm -f uv.lock
uv lock --quiet 2>&1 || true
head -25 uv.lock 2>/dev/null | head -20
```
Lock коммитим в git. `uv sync` на любой машине даст тот же venv.
### Полные менеджеры: poetry, hatch, pdm, uv
`pip`, `uv pip`, `venv`, `hatchling` — это **отдельные слои**. Некоторые
tools объединяют всё в один CLI: сборка + deps + venv + publish + lock +
version bump + Python-версия.
**Poetry** (2018, Sébastien Eustace) — самый популярный full-workflow.
Свой lock, до 2024 свой `[tool.poetry]` формат вместо PEP 621.
```{code-cell} python
!uv tool run --with poetry poetry --version
```
**Hatch** (2022, Ofek Lev / PSF core) — full workflow, полностью
PEP 621. Сильная сторона — **матрица окружений**: в `[tool.hatch.envs]`
описываешь несколько сред (`default`, `test`, `docs`, ...), в каждой
свой набор зависимостей и Python-версия, дальше `hatch run test:pytest`
прогоняет тесты в каждой из них. Аналог `tox` из старых времён
(старый инструмент того же класса, до сих пор используется).
```{code-cell} python
!uv tool run --with hatch hatch --version
```
**PDM** (2020, Frost Ming) — начинался с эксперимента PEP 582
(`__pypackages__` вместо venv, идея как `node_modules`). Сейчас — обычный
CLI + lock, PEP 621 native.
```{code-cell} python
!uv tool run --with pdm pdm --version
```
**uv** (2024, Astral) — новый инструмент, вобрал лучшее из остальных.
Совместим с `pip`: команды `uv pip install`, `uv pip list` работают
ровно как `pip`, без правок скриптов. Плюс полный workflow: `uv init`,
`uv add`, `uv sync`, `uv run`, `uv publish`, `uv tool install` (аналог
pipx), `uv python install` (аналог pyenv).
**Одна и та же операция в разных инструментах:**
| Действие | pip + venv | poetry | hatch | pdm | uv |
|----------|-----------|--------|-------|-----|-----|
| Init | `python -m venv .venv` | `poetry new` | `hatch new` | `pdm init` | `uv init` |
| Add dep | `pip install X` + правка `[project]` | `poetry add X` | `hatch add X` | `pdm add X` | `uv add X` |
| Install | `pip install .` | `poetry install` | `hatch install` | `pdm install` | `uv sync` |
| Lock | `pip freeze` (не PEP) | `poetry lock` | нет своего | `pdm lock` | `uv lock` |
| Run | `.venv/bin/python` | `poetry run` | `hatch run` | `pdm run` | `uv run` |
| Publish | `twine upload` | `poetry publish` | `hatch publish` | `pdm publish` | `uv publish` |
Poetry lock несовместим
`poetry.lock` — только poetry читает. `hatch`/`pdm`/`uv`/`pip` не понимают.
То же обратно — poetry не читает чужие lock. Значит перейти с poetry на
что-то другое = **потерять lock**, перегенерировать заново.
Poetry ещё встречает [tool.poetry]
Legacy poetry-проекты используют свой `[tool.poetry]` вместо стандартного
`[project]` PEP 621. Внешне похоже, но синтаксис зависимостей отличается
(`^1.0` вместо `>=1.0,<2.0` и т.п.). Poetry 2+ поддерживает `[project]`,
но старые проекты часто ещё на `[tool.poetry]`.
**Советы:**
- **Новый проект** — `uv`. Один инструмент, быстрый, совместим с `pip`.
- **Наследованный poetry** — оставайся. Миграция редко того стоит.
- **`hatch`** — хорошо для сложных проектов с несколькими environments
(dev, docs, integration test с разными Python-версиями).
- **`pdm`** — нишевый. Единственная причина брать — если уже
используешь.
Backend и manager — независимые оси
`hatchling.build` (backend, собирает wheel) и `hatch` (manager,
оркестрирует venv/deps/publish) — разные вещи, названия просто
похожие. У нас в `pyproject.toml` `hatchling.build` как backend, а
`uv` как manager — работает без проблем.
То же и с poetry: `poetry.core.masonry.api` — это только backend, его
можно использовать без CLI `poetry`. Или взять backend `flit_core`
плюс manager `uv`. Backend и manager меняются независимо, важно только
чтобы оба понимали `pyproject.toml`.
---
## 6. Static tooling
Два инструмента, оба с первого дня курса: **`ruff`** и **`mypy --strict`**.
### `ruff` — линтер + форматтер
Заменяет `black` + `isort` + `flake8` + большинство плагинов, работает
быстро на любом размере кодовой базы.
Плохой код:
```{code-cell} python
%%writefile /tmp/bad.py
import os,sys
from typing import List, Dict
def greet( name:str )->str :
result="Hello, "+name
return result
x=greet("world")
print(x)
```
Линтер:
```{code-cell} python
!uv run --no-project --with ruff ruff check /tmp/bad.py || true
```
Autofix:
```{code-cell} python
!uv run --no-project --with ruff ruff check --fix /tmp/bad.py 2>&1 | tail -3
```
Форматтер (аналог `black`):
```{code-cell} python
!uv run --no-project --with ruff ruff format /tmp/bad.py && cat /tmp/bad.py
```
Конфиг:
```toml
[tool.ruff]
line-length = 100
target-version = "py314"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM"]
ignore = ["E501"]
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"] # assert allowed в тестах
```
Не ставь `select = ["ALL"]`
Там есть правила, которые противоречат друг другу — один включённый
запрещает то, что требует другой, и линтер начинает ругаться на
любой код. Начинай с базового набора, расширяй по мере надобности.
### `mypy` strict
Без strict — mypy молчит на многом:
```{code-cell} python
%%writefile /tmp/untyped.py
def greet(name):
return "Hi " + name
greet(42) # int вместо str - но mypy без strict пропустит
```
Тихо (`--config-file=/dev/null` — чтобы не подхватил конфиг курса
`course-content/pyproject.toml`, где strict уже включён):
```{code-cell} python
!uv run --no-project --with mypy mypy --config-file=/dev/null /tmp/untyped.py 2>&1 | grep -v "No \[mypy\]" || true
```
Со strict — ловит:
```{code-cell} python
!uv run --no-project --with mypy mypy --config-file=/dev/null --strict /tmp/untyped.py 2>&1 | grep -v "No \[mypy\]" || true
```
Fix — типы:
```{code-cell} python
%%writefile /tmp/typed.py
def greet(name: str) -> str:
return "Hi " + name
greet("world")
```
```{code-cell} python
!uv run --no-project --with mypy mypy --config-file=/dev/null --strict /tmp/typed.py 2>&1 | grep -v "No \[mypy\]"
```
Конфиг:
```toml
[tool.mypy]
python_version = "3.14"
strict = true
[[tool.mypy.overrides]]
module = ["legacy.*"] # gradual: пока не готовы
ignore_errors = true
[[tool.mypy.overrides]]
module = ["some_untyped_lib.*"] # чужие либы без stubs
ignore_missing_imports = true
```
Глубоко про типы — Лекция 2.
### `pre-commit` — hooks локально (опционально)
Хочется чтобы ruff/mypy проверяли код **до** push'а, не в CI? Стандартный
инструмент — [pre-commit](https://pre-commit.com/). Ставит git-hook,
который перед `git commit` прогоняет любые проверки. Пример
`.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.8.0
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.13.0
hooks:
- id: mypy
additional_dependencies: [pytest]
```
Установка:
```bash
uv pip install pre-commit
pre-commit install
```
В курсе не требуется
Мы **не** ставим `pre-commit` как часть шаблона задач: студенту это
не обязательно. Кто хочет, настраивает у себя в форке; коммитить
`.pre-commit-config.yaml` в публичный репо не нужно, это твой личный
workflow.
---
## Материалы
- [Python Packaging User Guide](https://packaging.python.org/en/latest/)
- [PEP 517](https://peps.python.org/pep-0517/) — build backend interface
- [PEP 518](https://peps.python.org/pep-0518/) — `[build-system]`
- [PEP 621](https://peps.python.org/pep-0621/) — `[project]`
- [PEP 508](https://peps.python.org/pep-0508/) — dependency spec
- [PEP 660](https://peps.python.org/pep-0660/) — editable installs
- [uv docs](https://docs.astral.sh/uv/) · [ruff rules](https://docs.astral.sh/ruff/rules/) · [mypy docs](https://mypy.readthedocs.io/)