Библиотеки и виртуальные окружения

Даже небольшому робототехническому проекту нужны готовые инструменты: математические функции, работа с файлами, измерение времени, обмен по последовательному порту. Переписывать их в каждом скрипте не нужно. Python позволяет подключать модули через import, а сторонние пакеты устанавливать отдельно. Виртуальное окружение следит, чтобы набор пакетов одного проекта не смешивался с зависимостями другого.

Коротко

Модуль — файл с кодом Python, который можно импортировать. Пакет объединяет модули под общим именем. Часть модулей входит в стандартную библиотеку, а сторонние пакеты устанавливают, например, с помощью pip. Команда python -m venv .venv создаёт для проекта отдельное окружение со своим интерпретатором и каталогом установленных пакетов.

Зачем это нужно

Представим два проекта на одном компьютере:

• стенд считывает данные старого контроллера через определённую версию библиотеки последовательного порта;
• новый мобильный робот использует обновлённую версию той же библиотеки и другой набор инструментов.

Если устанавливать всё в одно общее место, обновление ради нового робота может сломать старый стенд. Виртуальные окружения дают каждому проекту собственный набор зависимостей. Исходный код остаётся в папке проекта, а окружение можно удалить и собрать заново по сохранённому списку.

Главная идея

Библиотека похожа на набор готовых деталей, а виртуальное окружение — на отдельный ящик инструментов для конкретной сборки:

проект A -> своё окружение -> нужные версии пакетов
проект B -> своё окружение -> другой набор пакетов

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

Модуль, пакет и библиотека

Эти слова связаны, но описывают разные уровни организации кода.

Термин	Что это	Пример
модуль	один файл Python с определениями и командами	statistics.py в стандартной библиотеке или собственный robot_math.py
пакет	каталог модулей, доступных под общим составным именем	пакет может содержать модули связи, датчиков и журналирования
стандартная библиотека	модули, поставляемые вместе с Python	math, statistics, pathlib, json
сторонний дистрибутив	устанавливаемый набор кода и метаданных	pyserial, который предоставляет импортируемый модуль serial
библиотека	общее инженерное название готового кода для повторного использования	набор функций работы с портом или данными

Имя устанавливаемого дистрибутива и имя в import иногда отличаются. Например, документация pySerial предлагает установить pyserial, а в программе используется import serial. Поэтому команду установки берут из официальной документации проекта, а не угадывают по строке импорта.

Что делает import

Оператор import загружает модуль и связывает его с именем в текущей программе. После import statistics функция среднего доступна как statistics.mean(). Префикс показывает, из какого модуля взято имя, и уменьшает риск случайного совпадения названий.

Используем стандартную библиотеку

Стандартные модули не нужно устанавливать через pip. Например, обработаем серию показаний дальномера:

import statistics

distance_samples = [31.2, 30.9, 31.5, 30.8, 31.1]

mean_distance = statistics.mean(distance_samples)
median_distance = statistics.median(distance_samples)

print(f"Среднее: {mean_distance:.1f} см")
print(f"Медиана: {median_distance:.1f} см")

Запись import statistics оставляет происхождение функций видимым. Другой допустимый вариант импортирует конкретные имена:

from statistics import mean, median

samples = [10.0, 10.2, 30.0]
print(mean(samples))
print(median(samples))

Форма from module import * для учебного интерактивного сеанса иногда сокращает набор символов, но в файлах проекта она затрудняет чтение: из строки не видно, какие имена появились и откуда они пришли. Официальный учебник Python также не рекомендует эту форму для обычного программного кода.

Создаём собственный модуль

Функции проекта тоже можно разделить между файлами. Пусть рядом лежат два файла.

robot_math.py:

def clamp(value: float, minimum: float, maximum: float) -> float:
    """Ограничить число заданным диапазоном."""
    return max(minimum, min(value, maximum))


def motor_command(error: float, gain: float = 0.04) -> float:
    """Преобразовать ошибку движения в нормированную команду мотора."""
    return clamp(error * gain, -1.0, 1.0)

main.py:

import robot_math

line_error = -8.0
command = robot_math.motor_command(line_error)

print(f"Команда: {command:.2f}")

Когда запускается main.py, Python находит соседний robot_math.py, выполняет определения модуля и связывает его с именем robot_math. Функции вызываются через точку. Не называйте собственные файлы json.py, statistics.py, serial.py или именем другого импортируемого модуля: соседний файл может перекрыть ожидаемую библиотеку.

Зачем окружение изолирует пакеты

Виртуальное окружение создаётся поверх уже установленного базового Python. Внутри него находится собственный интерпретатор и отдельный каталог сторонних пакетов. По умолчанию пакеты базового интерпретатора в окружении не видны.

Типичный порядок действий в новой папке проекта:

python -m venv .venv

Команда создаёт каталог .venv. Имя условное, но оно широко используется и сразу показывает назначение папки.

Далее окружение можно активировать:

Оболочка	Команда активации
macOS или Linux, bash/zsh	source .venv/bin/activate
Windows PowerShell	.venv\Scripts\Activate.ps1
Windows cmd.exe	.venv\Scripts\activate.bat

После активации команды python и python -m pip указывают на выбранное окружение. Проверить это можно без догадок:

import sys

print(sys.executable)
print(sys.prefix)
print(sys.base_prefix)

Внутри виртуального окружения sys.prefix обычно отличается от sys.base_prefix. Активация удобна, но не обязательна: скрипт можно запустить явным путём .venv/bin/python на macOS/Linux или .venv\Scripts\python.exe на Windows.

Для выхода из активированного окружения выполните:

deactivate

Устанавливаем пакет через выбранный Python

Используйте форму python -m pip, чтобы модуль pip запускался тем же интерпретатором, которым затем выполняется проект:

python -m pip install pyserial

pySerial даёт доступ к последовательному порту и часто применяется, когда компьютер обменивается данными с контроллером по USB-UART. Минимальная проверка импорта после установки:

import serial

print(serial.__version__)

Этот код не открывает порт и не отправляет команды роботу. Для реального соединения нужно отдельно выбрать имя порта, скорость обмена, тайм-аут и формат сообщений по документации устройства.

Перед установкой пакета проверьте точное имя в документации проекта или на его странице PyPI. Опечатка может указывать на другой дистрибутив. Не запускайте команды установки из случайной инструкции, не проверив, какой проект и код за ними стоят.

Сохраняем набор зависимостей

Окружение не следует копировать между компьютерами или добавлять в Git. Документация venv описывает его как одноразовый каталог, который можно воссоздать. Для простого учебного проекта текущее состояние часто фиксируют так:

python -m pip freeze > requirements.txt

На другом компьютере создают новое окружение и устанавливают перечисленные версии:

python -m pip install -r requirements.txt

requirements.txt — текстовый список для pip, а не само окружение. Он помогает повторить набор установленных дистрибутивов, но не заменяет описание версии Python, операционной системы и аппаратных требований проекта. Для робота стоит записать эти сведения в README рядом с командами настройки.

Пример: отдельная среда для стенда связи

Соберём рабочий порядок без привязки к конкретной IDE:

1. Создать папку проекта и перейти в неё.
2. Выполнить python -m venv .venv.
3. Активировать окружение подходящей для оболочки командой.
4. Проверить python -c "import sys; print(sys.executable)".
5. Установить pyserial командой python -m pip install pyserial.
6. Создать скрипт, который сначала только выводит список доступных портов или версию модуля.
7. После успешной проверки сохранить зависимости.
8. Добавить .venv/ в файл .gitignore, а requirements.txt оставить в проекте.

Такой порядок отделяет настройку среды от логики робота. Если импорт перестал работать, можно проверить окружение до подключения моторов и датчиков.

Частые проблемы

Симптом	Возможная причина	Что проверить
ModuleNotFoundError	пакет не установлен в выбранное окружение или неверно имя импорта	путь sys.executable, команду установки и документацию пакета
пакет установился, но скрипт его не видит	pip и python относятся к разным интерпретаторам	использовать python -m pip --version
импортируется неожиданный код	собственный файл перекрывает модуль библиотеки	имена файлов проекта и module.__file__
после обновления проект изменил поведение	версия зависимости изменилась	список установленных версий и журнал изменений пакета
окружение после переноса не запускается	каталог .venv скопировали или переместили	удалить его и создать заново в новом месте

Что запомнить о зависимостях

• import подключает модуль к текущей программе.
• Стандартная библиотека поставляется вместе с Python; сторонние дистрибутивы устанавливаются отдельно.
• Имя дистрибутива для pip может отличаться от имени модуля в import.
• Один проект — одно виртуальное окружение.
• Команда python -m pip связывает установку с выбранным интерпретатором.
• .venv не содержит исходный код проекта, не переносится как готовый комплект и не добавляется в Git.
• Версии зависимостей и версию Python нужно фиксировать рядом с проектом.

Практика

Задание 1. Собственный модуль измерений

Создайте модуль с функциями перевода сантиметров в метры и ограничения показания заданным диапазоном. Подключите его из второго файла двумя способами: через имя модуля и через импорт конкретной функции.

Задание 2. Проверка окружения

Создайте .venv, активируйте его и напишите скрипт, который выводит sys.executable, sys.prefix и sys.base_prefix. Зафиксируйте, какие значения меняются по сравнению с базовым интерпретатором.

Задание 3. Воспроизводимая установка

Установите в учебное окружение один пакет, выбранный по официальной документации наставника. Сохраните список зависимостей, создайте второе чистое окружение и проверьте восстановление списка.

Задание 4. Конфликт имён

Создайте безопасный тестовый проект и исследуйте, что произойдёт, если назвать собственный файл как модуль стандартной библиотеки. Затем переименуйте файл и удалите созданный кэш. Опишите правило именования, которое предотвращает такую ошибку.

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

• Чем модуль отличается от пакета?
• Какие модули не требуют установки через pip?
• Что происходит при выполнении import robot_math?
• Зачем каждому проекту отдельное виртуальное окружение?
• Почему предпочтительна команда python -m pip?
• Обязательно ли активировать окружение для запуска его интерпретатора?
• Почему папку .venv не следует переносить или добавлять в Git?
• Что нужно проверить при ModuleNotFoundError?

Ориентиры для самопроверки

Сначала ответьте без подсказки. Ответ можно считать полным, если вы:

• формулируете основную мысль своими словами;
• называете важные условия, ограничения или меры безопасности;
• для схемы, кода или расчёта показываете ход решения и ожидаемый результат.

Если один из пунктов объяснить не получается, найдите соответствующую главу статьи, перечитайте её и повторите ответ.

Словарь статьи

• Модуль — файл Python с определениями и выполняемыми инструкциями.
• Пакет — способ организовать связанные модули под составным именем.
• Стандартная библиотека — набор модулей, поставляемых вместе с Python.
• Дистрибутив — устанавливаемый комплект Python-кода и метаданных проекта.
• Зависимость — внешний пакет, необходимый проекту для работы.
• import — инструкция загрузки модуля или имени из модуля.
• Виртуальное окружение — изолированный интерпретатор и каталог пакетов для проекта.
• venv — модуль стандартной библиотеки для создания виртуальных окружений.
• pip — инструмент установки Python-дистрибутивов.
• PyPI — официальный индекс публикуемых Python-проектов.

Связанные темы

• Функции — как создавать операции для собственного модуля.
• Работа с файлами — как стандартные модули помогают хранить измерения и настройки.
• Первая программа — запуск скрипта и чтение сообщений интерпретатора.
• Классы — как объекты и методы помогают организовать код.

Источники

• Python 3.14. Учебник: модули и пакеты: https://docs.python.org/3/tutorial/modules.html
• Python 3.14. Справочник стандартной библиотеки: https://docs.python.org/3/library/index.html
• Python 3.14. venv — создание виртуальных окружений: https://docs.python.org/3/library/venv.html
• Python 3.14. Учебник: виртуальные окружения и пакеты: https://docs.python.org/3/tutorial/venv.html
• Python Packaging User Guide. Установка пакетов: https://packaging.python.org/en/latest/tutorials/installing-packages/
• pip User Guide: https://pip.pypa.io/en/stable/user_guide/
• pySerial. Документация и установка: https://pyserial.readthedocs.io/en/latest/pyserial.html
• PyPI. Проект pyserial: https://pypi.org/project/pyserial/