Создание Python-пакетов: от структуры до публикации в PyPI

Для кого эта статья:

• Разработчики Python, желающие усовершенствовать свои навыки организации кода
• Студенты и начинающие программисты, стремящиеся научиться создавать пакеты и библиотеки

• Профессионалы, работающие над крупными проектами, нуждающиеся в структурировании и рефакторинге кода

  Любой серьезный Python-проект рано или поздно сталкивается с проблемой организации кода. Когда количество функций и классов переваливает за несколько десятков, а число строк кода исчисляется тысячами, хаос становится неизбежным. Именно здесь на помощь приходят пакеты — элегантный и мощный способ структурировать код, сделать его многоразовым и легко распространяемым. В этой статье я пошагово расскажу, как создать свой пакет Python от простой структуры файлов до публикации в PyPI, чтобы ваш код мог использовать любой разработчик в мире. 🚀

Освоив создание собственных пакетов Python, вы поднимете свои навыки программирования на профессиональный уровень. Хотите стать востребованным разработчиком, способным создавать не только приложения, но и инструменты для других программистов? Курс Обучение Python-разработке от Skypro раскрывает все секреты модульного программирования, упаковки и распространения кода. Вы научитесь писать элегантный, масштабируемый код, который с гордостью выложите в открытый доступ.

Что такое пакеты Python и зачем их создавать

Пакет в Python — это директория, содержащая модули Python и специальный файл __init__.py, который сообщает интерпретатору, что данная директория должна рассматриваться как пакет. По сути, пакеты — это способ структурирования пространства имён Python с использованием "точечной нотации".

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

Александр Петров, Lead Python Developer

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

Решение пришло, когда мы реорганизовали весь проект в четыре основных пакета: data_processing, ui, api и utils. Время на адаптацию новичков сократилось до недели, а количество конфликтов при слиянии кода уменьшилось на 70%. Самое удивительное — мы обнаружили, что около 30% нашего кода дублировалось в разных частях проекта. После рефакторинга размер кодовой базы сократился почти на четверть без потери функциональности.

Создание собственных пакетов дает множество преимуществ:

• Организация кода — логическое разделение функциональности по модулям и подпакетам
• Повторное использование — написав код один раз, вы можете использовать его во многих проектах
• Распространение — возможность делиться своим кодом с сообществом или командой
• Управление зависимостями — четкое определение всех необходимых компонентов для работы вашего кода
• Версионность — контроль изменений и совместимости между версиями

Сравним различные способы организации кода:

Когда стоит задуматься о создании пакета? Я рекомендую переходить к пакетной структуре, как только у вас появляются:

• Несколько связанных модулей, которые логически объединены
• Код, который вы используете в нескольких проектах
• Функциональность, которой вы хотите поделиться с другими разработчиками
• Проект, который превышает ~1000 строк кода

Структура файлов для создания собственного пакета

Создание правильной структуры файлов — фундамент любого Python-пакета. Хорошо организованная структура делает ваш код понятным для других разработчиков и облегчает его поддержку. 📂

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

my_package/
├── my_package/
│ ├── __init__.py
│ ├── module1.py
│ ├── module2.py
│ └── subpackage/
│ ├── __init__.py
│ └── module3.py
├── setup.py
├── README.md
└── LICENSE

Разберем каждый элемент:

• Корневой каталог — папка верхнего уровня, обычно с именем вашего пакета
• Директория пакета — внутренняя директория, где находится сам код
• __init__.py — ключевой файл, который превращает директорию в пакет
• Модули — файлы .py с вашим кодом
• Подпакеты — вложенные пакеты со своим __init__.py
• setup.py — скрипт для установки пакета
• README.md — документация по использованию пакета
• LICENSE — лицензия, определяющая условия использования

Содержимое __init__.py может быть разным в зависимости от ваших потребностей:

# Пустой файл (делает директорию пакетом)

или

# Импорт основных компонентов для удобства использования
from .module1 import function1, Class1
from .module2 import function2

Мария Кузнецова, Python Architect

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

Переломный момент наступил, когда мы провели двухдневный рефакторинг и реорганизовали код по принципу пакетов. Вместо плоской структуры из 30+ файлов мы создали четыре ключевых пакета:

1. data_collection — всё для получения данных
2. preprocessing — очистка и подготовка данных
3. analysis — аналитические алгоритмы
4. visualization — графики и отчеты

В файлах __init__.py мы аккуратно экспортировали только нужные интерфейсы. Как результат, новый код стал писаться вдвое быстрее, а количество багов снизилось на 40%. Теперь для создания новых отчетов аналитикам требовался всего один импорт вместо десятка разрозненных функций из разных мест кодовой базы.

Для более сложных пакетов рекомендуется расширенная структура:

advanced_package/
├── advanced_package/
│ ├── __init__.py
│ ├── core/
│ │ ├── __init__.py
│ │ └── main_logic.py
│ ├── utils/
│ │ ├── __init__.py
│ │ └── helpers.py
│ └── cli/
│ ├── __init__.py
│ └── commands.py
├── tests/
│ ├── __init__.py
│ ├── test_core.py
│ └── test_utils.py
├── docs/
│ ├── usage.md
│ └── api.md
├── setup.py
├── setup.cfg
├── MANIFEST.in
├── README.md
├── LICENSE
└── requirements.txt

Дополнительные элементы включают:

• tests/ — директория с тестами для вашего пакета
• docs/ — подробная документация
• setup.cfg — дополнительные параметры установки
• MANIFEST.in — указывает, какие файлы включать помимо Python-кода
• requirements.txt — список зависимостей для разработки

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

При разработке пакета помните о принципе "Явное лучше неявного". Не заставляйте пользователей вашего пакета гадать, где найти нужную функциональность. 🔍

Настройка файла setup.py и метаданных пакета

Файл setup.py — это сердце вашего пакета, которое управляет процессом его установки, определяет зависимости и содержит всю метаинформацию. Правильная настройка этого файла критична для корректной работы и распространения вашего пакета. 📝

Минимальный пример setup.py:

from setuptools import setup, find_packages

setup(
name="my_package",
version="0.1.0",
packages=find_packages(),
install_requires=[
"requests>=2.25.1",
"numpy>=1.20.0",
],
)

Однако для серьезного пакета рекомендуется указывать больше метаданных:

from setuptools import setup, find_packages

with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()

setup(
name="my_awesome_package",
version="0.1.0",
author="Your Name",
author_email="your.email@example.com",
description="A short description of your package",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/yourusername/my_awesome_package",
packages=find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.7',
install_requires=[
"requests>=2.25.1",
"numpy>=1.20.0",
],
extras_require={
'dev': [
'pytest>=6.0.0',
'flake8>=3.9.0',
],
},
entry_points={
'console_scripts': [
'my-command=my_awesome_package.cli:main_function',
],
},
include_package_data=True,
package_data={
'my_awesome_package': ['data/*.json'],
},
)

Разберем ключевые параметры:

• name — имя пакета, которое будет использоваться при установке через pip
• version — версия пакета (рекомендуется использовать семантическое версионирование)
• author и author_email — контактная информация создателя
• description и long_description — краткое и полное описание пакета
• url — ссылка на репозиторий или документацию
• packages — список пакетов для включения (find_packages() автоматически находит все пакеты)
• classifiers — метаданные для PyPI о языке, лицензии и т.д.
• python_requires — минимальная версия Python
• install_requires — список зависимостей для работы пакета
• extras_require — опциональные зависимости для разных сценариев
• entry_points — определение консольных команд
• includepackagedata и package_data — включение неисполняемых файлов

Версионирование пакета — это отдельное искусство. Наиболее распространён подход семантического версионирования (SemVer): MAJOR.MINOR.PATCH

• MAJOR — увеличивается при несовместимых изменениях API
• MINOR — увеличивается при добавлении функциональности с сохранением обратной совместимости
• PATCH — увеличивается при исправлении ошибок с сохранением совместимости

Для динамического управления версией можно использовать файл версии или внешние инструменты:

# В файле my_package/__init__.py
__version__ = "0.1.0"

# В setup.py
import re
with open("my_package/__init__.py", "r") as f:
version = re.search(r'__version__ = "(.*)"', f.read()).group(1)

setup(
# ...
version=version,
# ...
)

Также можно использовать инструменты для автоматизации версионирования, такие как setuptools_scm, который определяет версию на основе git-тегов.

Правильные классификаторы помогают пользователям находить ваш пакет и понимать его характеристики. Основные классификаторы включают:

classifiers=[
"Development Status :: 3 – Alpha",
"Intended Audience :: Developers",
"Topic :: Software Development :: Libraries",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
]

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

entry_points={
'console_scripts': [
'my-awesome-command=my_package.cli:main',
'another-command=my_package.tools.utility:run',
],
}

После установки пакета пользователь сможет запускать команды my-awesome-command и another-command прямо из терминала.

Локальная установка и импорт собственных пакетов

После создания структуры пакета и настройки setup.py, следующий шаг — установка и тестирование пакета локально. Этот процесс позволяет убедиться, что пакет корректно устанавливается и его можно импортировать из других скриптов или проектов. 🧪

Существует несколько способов установить пакет локально:

1. Установка в режиме разработки — изменения в коде сразу доступны без переустановки
2. Установка из локальной директории — стандартная установка с локального источника
3. Установка из архива — создание и установка из архивного файла
4. Добавление пути в PYTHONPATH — без формальной установки

Рассмотрим каждый метод подробнее:

1. Установка в режиме разработки

Это самый удобный способ при активной разработке пакета:

# Перейдите в корневую директорию пакета (где находится setup.py)
pip install -e .

Флаг -e (или --editable) создает симлинк на вашу директорию разработки, поэтому любые изменения в коде сразу доступны без переустановки.

2. Установка из локальной директории

# Перейдите в корневую директорию пакета
pip install .

Этот способ полностью копирует ваш пакет в директорию site-packages Python. При изменении кода потребуется переустановка.

3. Установка из архива

# Создание дистрибутива
python setup.py sdist bdist_wheel

# Установка из созданного архива
pip install dist/my_package-0.1.0.tar.gz # или
pip install dist/my_package-0.1.0-py3-none-any.whl

Этот метод позволяет проверить, что ваш пакет корректно упаковывается и устанавливается из архива — именно так он будет устанавливаться пользователями после публикации в PyPI.

4. Добавление пути в PYTHONPATH

Временное решение без формальной установки:

# В Linux/Mac
export PYTHONPATH=$PYTHONPATH:/path/to/your/package

# В Windows (командная строка)
set PYTHONPATH=%PYTHONPATH%;C:\path\to\your\package

# Или прямо в скрипте Python
import sys
sys.path.append('/path/to/your/package')

После установки пакета его можно импортировать как любой другой пакет Python:

# Импорт всего пакета
import my_package

# Импорт конкретного модуля
from my_package import module1

# Импорт конкретной функции или класса
from my_package.module1 import MyClass, my_function

# Импорт из подпакета
from my_package.subpackage import module3

Если вы настроили __init__.py для экспорта основных компонентов, вы можете импортировать их напрямую:

# Если в __init__.py есть:
# from .module1 import MyClass, my_function

# То можно импортировать так:
from my_package import MyClass, my_function

Для проверки установки можно использовать такой скрипт:

try:
import my_package
print(f"Успешно импортирован пакет {my_package.__name__}, версия {my_package.__version__}")
print(f"Расположение пакета: {my_package.__file__}")
except ImportError:
print("Ошибка импорта. Проверьте установку пакета.")

Типичные проблемы при локальной установке и их решения:

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

# Создание виртуального окружения
python -m venv venv

# Активация в Linux/Mac
source venv/bin/activate

# Активация в Windows
venv\Scripts\activate

# Установка пакета
pip install -e .

# Тестирование
python -c "import my_package; print(my_package.__version__)"

# Деактивация окружения
deactivate

Публикация и распространение Python пакетов

После того как ваш пакет успешно работает локально, самое время поделиться им с миром. Публикация пакета в Python Package Index (PyPI) позволяет любому разработчику установить ваш пакет с помощью простой команды pip install. Это существенно упрощает распространение вашего кода и увеличивает его ценность для сообщества. 🌐

Процесс публикации включает несколько этапов:

1. Подготовка пакета к публикации
2. Регистрация на PyPI
3. Создание дистрибутивов
4. Загрузка на PyPI
5. Поддержка и обновление пакета

1. Подготовка пакета к публикации

Перед публикацией убедитесь, что ваш пакет готов:

• README.md содержит четкое описание, примеры использования и инструкцию по установке
• Документация полная и понятная
• Все тесты проходят успешно
• Код соответствует стандартам PEP 8
• Выбрана подходящая лицензия (MIT, Apache 2.0, GPL и т.д.)
• Версия пакета корректно установлена

Также рекомендуется создать файл MANIFEST.in, который определяет дополнительные файлы для включения в дистрибутив:

include LICENSE
include README.md
recursive-include my_package/data *.json *.csv
recursive-include docs *.md *.rst
global-exclude *.py[cod] __pycache__ *.so

2. Регистрация на PyPI

Для публикации пакетов вам понадобится аккаунт на PyPI. Рекомендуется начать с тестового сервера TestPyPI:

1. Зарегистрируйтесь на TestPyPI
2. Зарегистрируйтесь на PyPI для финальной публикации

Создайте файл конфигурации ~/.pypirc для хранения учетных данных:

[distutils]
index-servers =
pypi
testpypi

[pypi]
username = your_username
password = your_password

[testpypi]
repository = https://test.pypi.org/legacy/
username = your_username
password = your_password

Для более безопасного подхода рекомендуется использовать токены API вместо пароля.

3. Создание дистрибутивов

Для публикации необходимо создать дистрибутивы пакета. Рекомендуется использовать современные инструменты:

# Установка необходимых инструментов
pip install --upgrade build twine

# Создание дистрибутивов
python -m build

Эта команда создаст в директории dist/ два типа дистрибутивов:

• Source distribution (sdist) — архив исходного кода (.tar.gz)
• Wheel distribution (bdist_wheel) — предкомпилированный пакет (.whl)

4. Загрузка на PyPI

Сначала рекомендуется загрузить пакет на TestPyPI:

# Загрузка на TestPyPI
python -m twine upload --repository testpypi dist/*

# Проверка установки с TestPyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ my_package

После успешной проверки можно публиковать на основном PyPI:

# Загрузка на PyPI
python -m twine upload dist/*

Теперь ваш пакет доступен всем пользователям:

pip install my_package

5. Поддержка и обновление пакета

После публикации начинается этап поддержки:

• Отвечайте на issues и pull requests в репозитории
• Обновляйте документацию при изменении функциональности
• При выпуске новых версий следуйте семантическому версионированию
• Поддерживайте CHANGELOG.md с описанием изменений в каждой версии
• Автоматизируйте тестирование и выпуск новых версий с помощью CI/CD

Процесс обновления пакета:

1. Внесите изменения в код
2. Обновите номер версии
3. Обновите CHANGELOG.md
4. Пересоздайте дистрибутивы
5. Загрузите новую версию на PyPI

Автоматизация выпуска новых версий может существенно упростить этот процесс. Популярные инструменты включают GitHub Actions, Travis CI, и специализированные инструменты как bumpversion.

Альтернативные способы распространения пакетов:

Установка из GitHub выполняется следующим образом:

# Установка последней версии из основной ветки
pip install git+https://github.com/username/repo.git

# Установка конкретной версии (тега)
pip install git+https://github.com/username/repo.git@v1.0.0

# Установка из определенной ветки
pip install git+https://github.com/username/repo.git@develop

Для внутреннего использования в организациях можно настроить приватный PyPI сервер с помощью инструментов вроде pypiserver или использовать сервисы, предоставляющие приватные репозитории пакетов.

Создание и публикация собственных Python-пакетов — это мощный инструмент, который выводит ваши навыки программирования на новый уровень. Вы не только делаете свой код более организованным и модульным, но и открываете возможности для его повторного использования и распространения. Следуя представленным в статье рекомендациям, вы сможете превратить разрозненные скрипты в профессиональные библиотеки, которыми смогут пользоваться разработчики по всему миру. Независимо от того, разрабатываете ли вы инструменты для внутреннего использования в команде или создаёте общедоступные библиотеки, правильная организация кода в пакеты станет вашим конкурентным преимуществом в мире Python-разработки.