k06. Mодули, пакеты, venv и pip.

1. Цели урока

По завершении этого занятия вы будете обладать следующими умениями.

• Вы сможете объяснить, чем модуль отличается от пакета.
• Вы научитесь импортировать собственный учебный модуль с помощью оператора import и конструкции from … import.
• Вы научитесь использовать конструкцию if __name__ == "__main__" и объяснять, для чего она предназначена.
• Вы научитесь проверять, что инструмент pip устанавливает пакеты в активное виртуальное окружение, а не в посторонний интерпретатор Python.
• Вы научитесь выполнять команду python -m pip freeze и понимать смысл файла зависимостей.
• Вы сможете описать словами структуру папок учебного проекта курса.
• Вы научитесь воздерживаться от установки библиотек в системный интерпретатор Python только потому, что такой способ кажется более быстрым.

2. Словарь урока

3. Зачем делить код на файлы

Пока размер кода составляет от тридцати до пятидесяти строк, хранение всего кода в одном файле является допустимым. Когда же в проекте появляются такие задачи, как разбор телеметрии, построение миссии, запись журналов, связь по протоколу MAVLink и обработка данных с камеры, единственный файл превращается в беспорядочный набор инструкций.

Разделение кода по файлам даёт следующие преимущества.

• Появляются понятные границы между частями программы: один файл содержит только функции перевода единиц измерения, другой файл содержит только печать отчёта.
• Появляется возможность повторного использования кода: одну функцию можно импортировать из двух различных скриптов.
• Упрощается тестирование кода и чтение изменений, которые показывает система контроля версий Git.

4. Модуль и пакет

Что такое модуль

Модуль в языке Python представляет собой, по существу, один файл с расширением .py. Когда вы записываете оператор import, интерпретатор Python загружает этот файл и делает его функции доступными для использования.

Примером из практики занятия служит файл units.py, который находится внутри учебного пакета и является модулем с функциями перевода единиц измерения.

# фрагмент sensors/units.py (полный файл находится в материалах)
def alt_cm_to_m(alt_cm: int) -＞ float:
    """Сантиметры → метры."""
    return alt_cm / 100.0

Что такое пакет

Пакет представляет собой папку, в которой расположены модули и которую интерпретатор Python может импортировать как единое пространство имён. Обычно в такой папке присутствует файл __init__.py, который может быть и пустым. Именно этот файл помечает папку как пакет.

Учебная структура, которая используется на занятии K06, выглядит следующим образом:

code/M01_python/k06_demo_package/
    sensors/
        __init__.py
        units.py

В этой структуре папка sensors является пакетом, а файл units.py является модулем, который расположен внутри данного пакета.

5. Оператор import и конструкция from … import

import — это команда, которая подключает модуль или пакет. После выполнения импорта вы можете вызывать функции либо через имя модуля, либо импортировать отдельные имена напрямую.

Рассмотрим два часто используемых способа записи.

# Способ 1: импорт модуля целиком, вызов функции через имя модуля
import math
print(math.sqrt(9))

# Способ 2: импорт конкретных имён из модуля
from math import sqrt
print(sqrt(9))

Для учебного пакета sensors, который рассматривается в задании k06_task1, применяется следующая запись:

# После настройки sys.path (в учебном файле задания это выполнено явно)
from sensors.units import alt_cm_to_m, voltage_label

print(alt_cm_to_m(2500))
print(voltage_label(15.556))

6. Конструкция if __name__ == "__main__"

У каждого файла Python имеется специальная переменная __name__. Её значение зависит от того, каким способом был запущен данный файл.

• Если файл был запущен напрямую, то есть командой Run в среде PyCharm или командой python file.py, то переменная __name__ принимает значение "__main__".
• Если файл был импортирован из другого файла, то переменная __name__ принимает значение имени этого модуля, а не строку "__main__".

Именно поэтому применяется так называемая «охрана main», то есть проверка точки входа:

def greet(name: str) -＞ str:
    return f"hello, {name}"


def main() -＞ None:
    # Код, который нужен только при запуске файла как программы
    print(greet("uav-dev"))


if __name__ == "__main__":
    main()

7. Виртуальное окружение venv и инструмент pip

venv — напоминание

venv, то есть виртуальное окружение, представляет собой отдельную изолированную среду Python для проекта: у неё собственный интерпретатор и собственный набор установленных пакетов. На занятии K01 вы уже создали такое окружение в среде PyCharm. Здесь мы закрепляем смысл этого понятия.

Виртуальное окружение необходимо по следующим причинам.

• Проект A может использовать одну версию библиотеки pymavlink, а проект B — другую версию этой библиотеки.
• Системный интерпретатор Python в операционной системе Windows не загрязняется лишними пакетами.
• На устройстве Raspberry Pi упрощается воспроизведение того же самого окружения.

Проверить, что вы работаете в виртуальном окружении проекта, можно следующим образом:

import sys
print(sys.executable)
# В пути должно присутствовать нечто вроде ...\.venv\Scripts\python.exe

Инструмент pip — установка пакетов

pip — это стандартная программа установки пакетов Python. Пакеты, как правило, располагаются в каталоге PyPI, то есть в индексе пакетов Python, который находится в интернете.

Правильная форма команды для этого курса выглядит так:

python -m pip install имя_пакета

Разберём эту команду по частям.

• python — это тот интерпретатор, который является активным в данный момент (желательно, чтобы это был интерпретатор из виртуального окружения);
• -m pip — означает «запусти модуль pip именно этим интерпретатором python»;
• благодаря такой форме снижается вероятность того, что сработает посторонний инструмент pip, который принадлежит другому интерпретатору Python и был найден в переменной PATH.

# Обновить сам инструмент pip внутри виртуального окружения (безопасно и полезно)
python -m pip install -U pip

# Посмотреть, какие пакеты уже установлены
python -m pip list

Файл requirements и команда freeze

requirements.txt — это текстовый файл, который содержит список зависимостей проекта, то есть перечень необходимых пакетов, часто с указанием номеров версий.

Команда freeze выводит на экран фактически установленные пакеты текущего окружения:

python -m pip freeze

Снимок установленных пакетов можно сохранить в файл (это действие носит учебный характер):

python -m pip freeze ＞ requirements-lock-demo.txt

8. Структура проекта курса (как поддерживать порядок)

uav-python-pro/                 ← корень репозитория Git и проекта PyCharm
  .venv/                        ← виртуальное окружение (не сохраняется в репозиторий)
  .gitignore
  code/
    M01_python/
      k03_*.py … k06_*.py       ← точки входа и практические задания
      k06_demo_package/
        sensors/
          __init__.py
          units.py              ← переиспользуемый модуль
  docs/                         ← ваши заметки (по желанию)

9. Типичные ошибки

10. Практика

git add code/M01_python/k06_*.py code/M01_python/k06_demo_package
git commit -m "K06: modules package import main guard pip freeze"

11. Проверьте себя

1. Чем модуль отличается от пакета? Приведите пример из структуры k06_demo_package.
2. Для чего нужен файл __init__.py в учебном пакете?
3. Чем запись import math отличается от записи from math import sqrt?
4. Что означает конструкция if __name__ == "__main__"? Что произойдёт, если убрать эту проверку и оставить код запуска, который выполняется при импорте?
5. Почему мы записываем команду python -m pip, а не просто pip?
6. Зачем необходимо виртуальное окружение, если «и так всё устанавливается»?
7. Что выводит на экран команда pip freeze?
8. Почему не следует устанавливать пакеты в системный интерпретатор Python «на авось»?

12. Чек-лист самопроверки

• Я объясняю своими словами, что такое модуль и что такое пакет.
• Я запустил задачу k06_task1 и увидел ожидаемый результат.
• Я понимаю смысл конструкции if __name__ == "__main__".
• Значение sys.executable указывает на каталог .venv проекта.
• Я умею выполнять команды python -m pip list и python -m pip freeze.
• Я не устанавливаю пакеты за пределами виртуального окружения.
• Я понимаю, для чего в будущем понадобится файл requirements.
• Я записал изменения по занятию K06 в репозиторий с помощью git.

13. Что дальше

• Предыдущее занятие: K05 · Циклы и функции.
• Текущее занятие: K06 · Модули, пакеты, venv, pip.
• Следующее занятие: K07 · Файлы и форматы данных.
• Горизонт модуля M1: занятие K12 «CLI Fake GCS» и контрольный рубеж G1.