00-tools.tex

\section{Лекция 1. Инструментарий разработчика}

\subsection*{Синопсис}
\paragraph*{Цель}

Настроить рабочее место, понять, что Python-код живёт в экосистеме.
\paragraph*{Длительность}

3–5 дней.
\paragraph*{Теория (минимум)}
\begin{itemize}
\item Что такое интерпретатор, REPL, байт-код, \_\_pycache\_\_.
\item Версии Python: 3.10+, почему не 2.x.
\item python, python3, pip, pipx, uv, poetry.
\item venv: зачем изоляция зависимостей.
\item pyproject.toml vs requirements.txt vs setup.py.
\item Git, .gitignore для Python (.venv, \verb| __pycache__|,  \verb|.pytest_cache|).
\item Редактор: VS Code + Python extension или PyCharm.
\item Terminal: bash/zsh, базовые командыю.
\end{itemize}

\subsection{Что такое интерпретатор, REPL, байт-код , \_\_pycache\_\_ }
\subsubsection{Интерпретатор}

\paragraph*{Python - интерпретируемый язык}
Это значит, что исходный код \texttt{.py} \textbf{не компилируется} в машинный код (python3) напрямую,  а \textbf{выполняется} специальной программой --- \linebreak интерпретатором.
Но это упрощение. На самом деле путь такой: (см. Рис.1).
То есть Python сначала компилирует исходник в байт-код, а потом интерпретирует байт-код виртуальной машиной.
Поэтому Python иногда называют \textbf{«компилируемо-интерпретируемым»} языком.

Что нужно понимать:
\begin{itemize}
\item \textbf{Интерпретатор} — это программа \texttt{python3}, которая читает \texttt{.py}, компилирует в байт-код и выполняет.
\item \textbf{Интерпретатор} не создаёт \texttt{.exe}/бинарник. Чтобы запустить программу, нужен \linebreak  установленный Python.
\item \textbf{Python-код} \underline{медленнее} C, потому что каждая операция проходит через PVM.
\end{itemize}

\begin{figure}[htbp]
  \centering
  \resizebox{0.65\textwidth}{!}{\input{./figures/01.fig.tex}}
  \caption{Схема обработки и выполнения программы на Python}
  \label{fig:python-pipeline}
\end{figure}

\begin{warningbox2}
\texttt{Интерпретатор} --- Исходный код \texttt{.py} компилируется в байт-код.
\end{warningbox2}

\subsubsection{REPL}

\textbf{REPL = Read-Eval-Print Loop}. Это интерактивный режим интерпретатора.

\begin{lstlisting}
$ python3
Python 3.12.0 (main, ...)
>>> 2 + 2
4
>>> name = "world"
>>> print(f"hello, {name}")
hello, world
>>> exit()
\end{lstlisting}

\textbf{Цикл:}
\begin{itemize}
\item Read — читает строку.
\item Eval — вычисляет.
\item Print — печатает результат.
\item Loop — возвращается к началу.
\end{itemize}

\textbf{Зачем нужен:}
\begin{itemize}
\item Быстро проверить идею.
\item Изучить поведение функции/метода.
\item Отладка маленьких фрагментов.
\item Прототипирование.
\end{itemize}

\textbf{Улучшенные REPL:}
\begin{itemize}
\item ipython — подсветка, автодополнение, ?, ??, \%timeit.
\item bpython, ptpython.
\item Jupyter Notebook — REPL в браузере с сохранением состояния и визуализацией.
\end{itemize}

\textbf{Что нужно понимать:}
\begin{itemize}
\item \textbf{REPL} — не для продакшена, а для экспериментов.
\item В \textbf{REPL} переменные живут до выхода.
\item  \textbf{\_} хранит последний результат.
\end{itemize}

\subsubsection{Байт-код}

\textbf{Байт-код} — промежуточное представление между исходником и машинным кодом. Это инструкции для виртуальной машины Python.

Посмотреть байт-код:
\begin{lstlisting}
import dis

def add(a, b):
    return a + b

dis.dis(add)
\end{lstlisting}

Вывод:
\begin{lstlisting}
  2           0 RESUME                   0
  3           2 LOAD_FAST                0 (a)
              4 LOAD_FAST                1 (b)
              6 BINARY_OP                0 (+)
             10 RETURN_VALUE
\end{lstlisting}

\textbf{Что нужно понимать}:
\begin{itemize}
\item Байт-код — платформо-независимый (один и тот же на Linux/Windows/macOS).
\item Его можно дизассемблировать через dis.
\item Байт-код не является машинным кодом и не переносится между версиями Python (.pyc для 3.11 не подойдёт для 3.12).
\end{itemize}

\subsubsection{\_\_pycache\_\_ и .pyc}

Когда Python импортирует модуль, он кэширует скомпилированный байт-код в файлы .pyc, чтобы не компилировать заново при следующем запуске
\begin{figure}[htbp]
  \centering
  \resizebox{0.65\textwidth}{!}{\input{./figures/02.fig.tex}}
  \caption{байт-код \_\_pycache\_\_ и .pyc}
  \label{fig:.байт-код и .pyc}
\end{figure}

Имя \texttt{.pyc: module.<interpreter>-<version>.pyc}, 

например \texttt{ module.cpython-312.pyc}.

\textbf{Когда создаётся:}
\begin{itemize}
\item При import module.
\item Не создаётся для скрипта, запущенного как python script.py (главный модуль не кэшируется).
\item Можно отключить: python -B script.py или PYTHONDONTWRITEBYTECODE=1.
\end{itemize}

\textbf{Что нужно понимать:}
\begin{itemize}
\item \texttt{ \_\_pycache\_\_} — артефакт, его не коммитят в git.
\item \texttt{.pyc} ускоряет повторные импорты.
\item Если исходник изменился, .pyc перекомпилируется.
\item Удалять \texttt{ \_\_pycache\_\_} безопасно.
\end{itemize}

\subsubsection{ Что проверить руками}
\begin{lstlisting}
# REPL
python3
>>> import this          # Zen of Python
>>> import dis; dis.dis(lambda x: x+1)
>>> exit()

# Байт-код
python3 -c "import dis; dis.dis(compile('a+b', '<s>', 'eval'))"

# __pycache__
mkdir /tmp/pycache-test && cd /tmp/pycache-test
echo "x = 42" > mod.py
python3 -c "import mod; print(mod.x)"
ls -la __pycache__/
\end{lstlisting}

\subsection{ Версии Python: 3.10+, почему не 2.x2.1.}
 
\subsubsection{Python 2 vs Python 3}

Python 2 вышел в 2000, Python 3 — в 2008. Это несовместимые языки. Python 2 официально мёртв с 1 января 2020 (EOL — End of Life).

\textbf{Ключевые различия:}
\begin{table}[h]
\centering
\begin{tabular}{|l|l|l|}
\hline
\textbf{Аспект}& \textbf{Python 2} & \textbf{Python 3} \\
\hline
print & оператор print "hi" & функция print("hi") \\
Строки & str (bytes) + unicode & str (unicode) + bytes \\
Деление & 5/2 == 2 & 5/2 == 2.5, 5//2 == 2 \\
range & список & ленивый объект \\
input & eval ввода & строка \\
Unicode & по умолчанию нет & по умолчанию да \\
Поддержка & EOL 2020 & активная \\
\hline
\end{tabular}
\caption{Ключевый различия}
\end{table}

\textbf{Почему не 2.x:}
\begin{itemize}
\item Нет обновлений безопасности.
\item Большинство библиотек (numpy, pandas, fastapi, requests) уже не поддерживают 2.x.
\item Синтаксис 3 чище.
\item Python 2 несовместим с современным тулингом.
\end{itemize}

\subsubsection{ Какие версии актуальны}
\begin{itemize}
\item 3.10 — минимум для большинства современных проектов (match/case, X | Y в типах).
\item 3.11 — быстрее (~10–60%), TaskGroup, tomllib, лучшие сообщения об ошибках.
\item 3.12 — ещё быстрее, type statement, улучшенный f-string.
\item 3.13 — экспериментальный JIT, улучшенный REPL, free-threaded (без GIL) — пока не для продакшена.
\end{itemize}

\begin{warningbox2}
Рекомендация: целевая версия — 3.11 или 3.12. Минимум — 3.10.
\end{warningbox2}

\subsubsection{Что нужно понимать}
\begin{itemize}
\item Указывай requires-python = ">=3.11" в pyproject.toml.
\item Используй python3.12 явно, если нужно.
\item Не пиши код, который работает только на одной версии, без причины.
\item Проверяй версию: python3 --version.
\end{itemize}
\subsubsection{Что проверить руками}
\begin{lstlisting}
python3 --version
python3 -c "import sys; print(sys.version_info)"
# Проверка  новых  фич

python3 -c "match 1:
    case 1: print('one')"
\end{lstlisting}

%3 part
\subsection{ python, python3, pip, pipx, uv, poetry}
\subsubsection{python vs python3}
\begin{itemize}
\item python3 — гарантированно Python 3 на Linux/macOS.
\item python — может быть Python 2, а может не быть вообще.
\item На Windows python — обычно Python 3 (если установлен).
\item Правило: всегда используй python3 в скриптах и документации для Linux/macOS.
\end{itemize}

\textbf{Проверка:}
\begin{lstlisting}
which python3
which python
python3 --version
\end{lstlisting}

\subsubsection{pip}

pip = Pip Installs Packages. Менеджер пакетов Python.

\begin{lstlisting}
pip install requests
pip install "requests>=2.31,<3"
pip install -e .                    # editable install
pip install -r requirements.txt
pip list
pip show requests
pip uninstall requests
pip freeze > requirements.txt
\end{lstlisting}

\begin{warningbox2}
\textbf{Важно}: pip — это не «системный» установщик. Он ставит пакеты в текущее окружение. Без venv — в глобальное, что плохо.
\end{warningbox2}

\textbf{Правило}: всегда активируй venv перед pip install.

\textbf{Альтернативы:}
\begin{itemize}
\item python3 -m pip — гарантирует, что pip от нужного Python.
\item pip3 — явный Python 3.
\end{itemize}

\subsubsection{pipx}
pipx = pip + изоляция. Устанавливает приложения (CLI-утилиты) в изолированные окружения и добавляет их в PATH.
\begin{lstlisting}
\item pipx install ruff
\item pipx install poetry
\item pipx install black
\item pipx list
\item pipx upgrade ruff
\item pipx uninstall ruff
\end{lstlisting}

\textbf{Когда использовать:}
\begin{itemize}
\item Устанавливаешь CLI-инструмент (ruff, black, poetry, httpie).
\item Не хочешь засорять глобальный site-packages.
\item Нужны разные версии инструмента в разных проектах.
\end {itemize}

\textbf {Когда не использовать:}
\begin{itemize}
\item Устанавливаешь библиотеку для проекта — тогда pip + venv.
\end{itemize}

\subsubsection{uv}
uv — сверхбыстрый менеджер пакетов и окружений от Astral (создатели ruff). Написан на Rust.
\begin{lstlisting}
# Установка
curl -LsSf https://astral.sh/uv/install.sh | sh

# Создание venv
uv venv
source .venv/bin/activate

# Установка
uv pip install requests
uv pip install -e ".[dev]"
uv pip compile requirements.in -o requirements.txt

# Управление проектом (аналог poetry)
uv init myproject
cd myproject
uv add requests
uv add --dev pytest
uv sync
uv run python main.py
uv lock
\end{lstlisting}

\textbf{Преимущества:}
\begin{itemize}
\item В 10–100 раз быстрее pip.Единый инструмент: venv + pip + lock + resolver.
\item Совместим с pyproject.toml.
\item Кэширует агрессивно.
\end{itemize}
\begin{warningbox2}
Рекомендация: для новых проектов — uv. Для legacy — pip.
\end{warningbox2}

\subsubsection{poetry}
Poetry — менеджер зависимостей и упаковки. Более старый, чем uv, но зрелый.
\begin{lstlisting}
pipx install poetry
poetry new myproject
cd myproject
poetry add requests
poetry add --group dev pytest
poetry install
poetry run python main.py
poetry build
poetry publish
\end{lstlisting}

\textbf{Плюсы:}
\begin{itemize}
\item Единый pyproject.toml + poetry.lock.
\item Хорошая работа с версиями.
\item Упаковка и публикация.
\end{itemize}

\textbf{Минусы:}
\begin{itemize}
\item Медленнее uv.
\item Свой формат секций в pyproject.toml.
\end{itemize}

\subsubsection{Сравнение}
\begin{table}[h]
\centering
\begin{tabular}{|l|l|l|l|}
\hline
Инструмент & Назначение & Скорость & Когда использовать \\
\hline
pip & установка пакетов & средняя & legacy, простые случаи\\
pipx & CLI-приложения & средняя & ruff, black, poetry\\
uv & всё & очень высокая & новые проекты\\
poetry & зависимости + упаковка & средняя & legacy, публикация\\
\hline
\end{tabular}
\caption{Сравнение}
\end{table}


\subsubsection{Что проверить руками}
\begin{lstlisting}
python3 --version
python3 -m pip --version
pipx --version
uv --version
poetry --version

# Создать проект через uv
uv init /tmp/uvtest && cd /tmp/uvtest
uv add requests
uv run python -c "import requests; print(requests.__version__)"
\end{lstlisting}

\subsection{venv: зачем изоляция зависимостей}
\subsubsection{ Проблема}

\textbf{Представь:} у тебя два проекта. Проект A требует requests==2.28.Проект B требует requests==2.31.Если ставить глобально — конфликт. Один проект сломается.
Решение: виртуальное окружение — изолированная папка с собственным site-packages.

\subsubsection{ Как работает}
\begin{lstlisting}
python3 -m venv .venv
source .venv/bin/activate 			# Linux/macOS
# или
.venv\Scripts\activate 					# Windows

#Теперь python и pip указывают  на .venv
which python 								# /path/to/.venv/bin/python
pip install requests 						# ставится в .venv/lib/.../site-packages
\end{lstlisting}
\begin{figure}[htbp]
  \resizebox{0.35\textwidth}{!}{\input{./figures/03.fig.tex}}
  \caption{Что создаётся:}
  \label{fig:python-pipeline}
\end{figure}

\textbf{Ключевое:} \texttt{activate} меняет \verb|PATH| и \verb|VIRTUAL_ENV|, чтобы python и pip указывали на \texttt{.venv.}

\subsubsection{ Правила}
\begin{itemize}
\item Один venv на проект.
\item Не коммитить .venv — добавить в .gitignore.
\item Не создавать venv внутри venv.
\item Удалять venv безопасно — просто rm -rf .venv.
\item Фиксировать зависимости — requirements.txt или uv.lock/poetry.lock.
\end{itemize}
\subsubsection{Альтернативы}
\begin{itemize}
\item virtualenv — старее, быстрее для Python 2.
\item conda — для data science, управляет и не-Python зависимостями.
\item uv venv — быстрее.
\item poetry shell — активирует venv проекта.
\end{itemize}
\newpage
\subsubsection{ Что проверить руками}

\begin{lstlisting}
mkdir /tmp/venvtest && cd /tmp/venvtest
python3 -m venv .venv
source .venv/bin/activate
which python
pip install requests
pip list
python -c "import requests; print(requests.__file__)"
deactivate
\end{lstlisting}

\subsection{ pyproject.toml vs requirements.txt vs setup.py}
\subsubsection{ setup.py (legacy)}

\textbf{Исторический способ. Исполняемый Python-файл.}
\begin{lstlisting}
from setuptools import setup, find_packages

setup(
    name="myproject",
    version="0.1.0",
    packages=find_packages(),
    install_requires=["requests>=2.31"],
)
\end{lstlisting}

\textbf{Проблемы:}
\begin{itemize}
\item Исполняемый код при установке — небезопасно.
\item Нельзя прочитать метаданные без запуска.
\item Дублирование с setup.cfg.
\end{itemize}

\textbf{Статус:} deprecated, но ещё встречается в legacy-проектах.

\subsubsection{requirements.txt}

\textbf{Простой список зависимостей.}
\begin{lstlisting}
requests==2.31.0
httpx>=0.27,<1
pydantic~=2.6
\end{lstlisting}

\textbf{Плюсы:}
\begin{itemize}
\item Просто.
\item Понятно.
\item Работает везде.
\end{itemize}

\textbf{Минусы:}
\begin{itemize}
\item Нет метаданных проекта (имя, версия, entry points).
\item Нет разделения на prod/dev (обычно делают requirements-dev.txt).
\item Нет lock-файла (нужен pip-tools или pip freeze).
\end{itemize}

\textbf{Когда использовать:}
\begin{itemize}
\item Простые проекты.
\item Legacy.
\item Docker-образы (иногда).
\end {itemize}

\subsubsection{ pyproject.toml (современный стандарт)}
\textbf{PEP 518 / PEP 621.}

\textbf{Единый файл конфигурации проекта.}
\begin{lstlisting}
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
description = "My project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [{name = "Ivan", email = "ivan@example.com"}]
dependencies = [
    "requests>=2.31",
    "pydantic>=2.6",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

[project.scripts]
myproject = "myproject.cli:main"

[tool.ruff]
line-length = 100

[tool.mypy]
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]
\end{lstlisting}

\textbf{Плюсы:}
\begin{itemize}
\item Единое место для метаданных и настроек инструментов.
\item Декларативный.
\item Совместим с pip, uv, poetry, hatch, pdm.
\item Lock-файлы (uv.lock, poetry.lock) дополняют.
\end{itemize}
\textbf{Минусы:}
\begin{itemize}
\item Сложнее для новичка.
\item Разные бэкенды (setuptools, hatchling, flit, poetry-core).
\end{itemize}
\begin{warningbox2}
\textbf{Когда использовать:} всегда в новых проектах.
\end{warningbox2}
\subsubsection{Сравнение}
\begin{table}[h]
\centering
\begin{tabular}{|l|l|l|}
\hline
\textbf{Файл} & \textbf{Назначение} & textbf{Статус}\\
\hline
setup.py & сборка/установка & legacy\\
requirements.txt & список зависимостей & актуален для простых случаев\\
pyproject.toml & всё: метаданные, зависимости, настройки & современный стандарт\\
uv.lock / poetry.lock & точные версии всех зависимостей & обязателен для воспроизводимости\\
\hline
\end{tabular}
\caption{Сравнение}
\label{tab:differents}
\end{table}
\subsubsection{Что проверить руками}
\begin{lstlisting}
mkdir /tmp/pyproj && cd /tmp/pyproj
cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["requests"]
EOF

python3 -m pip install -e .
python3 -c "import demo"  # если есть пакет
\end{lstlisting}
\newpage
\subsection{ Git, .gitignore для Python}
\subsubsection{ Базовый workflow}
\begin{lstlisting}
git init
git add .
git commit -m "Initial commit"
git status
git log --oneline
git diff
git branch feature/x
git checkout feature/x
git merge feature/x
\end{lstlisting}

\subsubsection{.gitignore для Python}

\textbf{Что не коммитить:}
\begin{lstlisting}
# Виртуальные окружения
.venv/
venv/
env/
ENV/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so

# Сборка
build/
dist/
*.egg-info/
*.egg
.eggs/

# Тесты и кэш
.pytest_cache/
.coverage
.coverage.*
htmlcov/
.tox/
.nox/
.hypothesis/

# Типы
.mypy_cache/
.pytype/
.ruff_cache/

# Jupyter
.ipynb_checkpoints/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Env-файлы (секреты!)
.env
.env.*
!.env.example

# Логи
*.log
\end{lstlisting}
\begin{warningbox2}
Важно:
\begin{itemize}
\item Секреты (\texttt{.env}, токены, ключи) — никогда в \texttt{git}.
\item Вместо \texttt{.env} коммитить \texttt{.env.example} с пустыми значениями.
\item \texttt{.venv} — всегда игнорировать.
\item \texttt{\_\_pycache\_\_} — всегда игнорировать.
\end{itemize}
\end{warningbox2}
\newpage
\subsubsection{ Проверка перед коммитом}
\begin{lstlisting}
git status --ignored
git check-ignore -v .venv/
git ls-files | grep -E "(__pycache__|\.venv|\.env$)"Если что-то лишнее попало — удалить из индекса:git rm -r --cached .venv
git rm --cached .env6.4. Полезные алиасыgit config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.lg "log --oneline --graph --all"6.5. Что проверить рукамиmkdir /tmp/gittest && cd /tmp/gittest
git init
python3 -m venv .venv
source .venv/bin/activate
python3 -c "print('hello')" > main.py
python3 main.py
python3 -c "import main" 2>/dev/null; ls __pycache__ 2>/dev/null

# Создать .gitignore, проверить
echo ".venv/" > .gitignore
echo "__pycache__/" >> .gitignore
git add .
git status
\end{lstlisting}