Найти в Дзене
Тим Вебмастер

Как опубликовать свой пакет Python на PyPI: Пошаговый гайд для новичков

3 мин
Эта статья является адаптированным руководством, основанным на материалах сайта: Как опубликовать свой пакет на PyPI Официальная документация по публикации пакетов Python на PyPI (Python Package Index) является всеобъемлющей, но для новичка может показаться перегруженной деталями. Цель этого руководства — предоставить вам максимально быстрый и понятный план действий с минимально необходимым набором шагов для успешной публикации вашего первого пакета. Прежде чем что-либо загружать, необходимо установить инструменты для сборки и загрузки, а также подготовить файлы, описывающие ваш проект. Вам потребуются два ключевых инструмента: Bash python -m pip install --upgrade build twine Минимальная рабочая структура должна выглядеть примерно так: my-package-name/
├── src/
│ └── my_package_name/
│ └── __init__.py # Ваш код
├── README.md # Описание пакета
├── LICENSE # Лицензия
├── pyproject.toml # Конфигурация сборки
└── setup.cfg # Метаданные пак
Оглавление

Эта статья является адаптированным руководством, основанным на материалах сайта: Как опубликовать свой пакет на PyPI

Официальная документация по публикации пакетов Python на PyPI (Python Package Index) является всеобъемлющей, но для новичка может показаться перегруженной деталями. Цель этого руководства — предоставить вам максимально быстрый и понятный план действий с минимально необходимым набором шагов для успешной публикации вашего первого пакета.

Шаг 1: Подготовка окружения и метаданных

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

1.1. Установка инструментов

Вам потребуются два ключевых инструмента:

  • build: для создания дистрибутивов пакета.
  • twine: для безопасной загрузки собранных файлов на PyPI.

Bash

python -m pip install --upgrade build twine

1.2. Создание структуры проекта

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

my-package-name/
├── src/
│ └── my_package_name/
│ └── __init__.py # Ваш код
├── README.md # Описание пакета
├── LICENSE # Лицензия
├── pyproject.toml # Конфигурация сборки
└── setup.cfg # Метаданные пакета

1.3. Файл setup.cfg (Метаданные)

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

Ключевые поля:

  • name: Название пакета, которое будет отображаться на PyPI и использоваться для установки (pip install). Оно должно быть уникальным.
  • version: Текущая версия пакета (например, 0.1.0).
  • url: Ссылка на репозиторий проекта (например, GitHub).
  • license: Тип лицензии (например, MIT).
  • classifiers: Обязательные категории, которые помогают пользователям найти ваш пакет (версия Python, лицензия, статус разработки).
  • long_description: Берется из README.md.

1.4. Файл pyproject.toml (Конфигурация сборщика)

Этот файл указывает, какой бэкенд будет использоваться для сборки вашего пакета. Для современных проектов на базе setuptools его содержимое минимально:

Ini, TOML

[build-system]
requires = [
"setuptools>=61.0.0",
"wheel"
]
build-backend = "setuptools.build_meta"

Шаг 2: Сборка дистрибутивов

После того как метаданные и структура готовы, необходимо собрать два типа дистрибутивов:

  1. sdist (Source Distribution): Исходный код.
  2. Wheel (Built Distribution): Предварительно собранный пакет, который можно установить без необходимости компиляции на стороне пользователя (предпочтительный для установки).

Команда сборки:

Запустите эту команду из корневой директории вашего проекта (my-package-name/):

Bash

python -m build

В результате выполнения этой команды в корне проекта появится новая папка dist/, содержащая два файла: [название_пакета]-[версия].tar.gz (sdist) и [название_пакета]-[версия]-py3-none-any.whl (Wheel).

Шаг 3: Загрузка на PyPI с помощью Twine

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

3.1. Загрузка на тестовый PyPI (TestPyPI)

Для первой публикации и проверки всегда рекомендуется использовать тестовый индекс TestPyPI. Это позволяет убедиться, что процесс загрузки работает, а пакет отображается корректно, без "засорения" основного индекса.

Bash

python -m twine upload --repository testpypi dist/*

Twine запросит ваше имя пользователя и пароль для TestPyPI.

3.2. Установка и проверка пакета с TestPyPI

Вы можете убедиться, что пакет установится и работает, используя специальный флаг —index-url:

Bash

pip install --index-url https://test.pypi.org/simple/ my-package-name

(Не забудьте заменить my-package-name на фактическое название вашего пакета).

3.3. Финальная загрузка на основной PyPI

Если тестирование прошло успешно, можно загружать пакет на реальный PyPI:

Bash

python -m twine upload dist/*

Twine запросит учетные данные для основного PyPI. После успешной загрузки ваш пакет станет доступен для всех пользователей через стандартную команду pip install [название_пакета].

Заключение

Публикация пакета — это ключевой момент, который превращает ваш код из личного проекта в инструмент для всего Python-сообщества. Использование современных инструментов, таких как build и twine, а также декларативное описание метаданных в setup.cfg, делает этот процесс безопасным и прямолинейным.