Удалить все

ЗАГРУЗКА ...

Содержание

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

22.10.2025

8 минут

149

Теги:

Питон

Баш

Сервер

О чём статья и почему она существует

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

Я не говорю, что статья плохая — она отличная, всеобъемлющая. В обязательном порядке прочитайте её.

А ещё, мне показалось, что для новичка эта статья немного перегружена и было бы не плохо разделить её на две части:

Быстрый старт с минимально-необходимыми действиями.
Полное и углублённое руководство уже для тех кто в теме. (В разработке)

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

Вступление

Для чего вообще заниматься этой упаковкой, кому это нужно и что такое PyPI? Давай начнём с начала.

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

PyPI пакет — это формат хранения исходного кода для Python кода. В современном варианте создающиеся при помощи pyproject.toml файла конфигурации. Раньше использовали setup.py скрипт + setup.cfg.

Дальше, я буду использовать вместо PyPI пакет(Python-пакет), просто пакет. Так будет проще для меня и для читателя.

Весь этот переход был совершён относительно недавно - 2016 год. Когда вышел PEP 518 - тогда и появился единый, стандартный способ публикации и упаковки пакетов через pyproject.toml.

Для кого это вообще нужно? Ну вообще, для разработчиков, тестировщиков и других ребят, которые так или иначе связаны с Python. Чтобы облегчить им жизнь и стандартизировать процесс деплоя всех пакетов на PyPI.

Хорошо, а зачем нам PyPI? Почему бы не использовать тот же GitHub, или Bitbucket для хранения исходного кода? На эти вопросы можно дать различные ответы в зависимости от того, с какой стороны посмотреть. Так например, Python очень отличен от тех же самых C++ или JS. C++, вообще не имеет официального индекса библиотек и пакетов как Python. У JS он есть - Node Package Manager (NPM).

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

Так например, если хочется создавать web-приложения или целый сайт, просто установи django, и ты готов:

pip install django

Пример установки пакета из PyPI

Или если ты хочешь добавить поддержку HTMx-библиотеки для своих шаблонов(html-страниц), просто установи соответствующий node-модуль:

npm i htmx

Пример установки пакета из NPM

Сравните это с установкой библиотек для C++. Мало того, что ты должен найти подходящую библиотеку, ты должен будешь ещё подключить заголовки (в нужных тебе местах), плюс сделать линковку (динамическую или статическую). Да, конечно, есть CMake, есть Make, есть ещё большая куча различных систем сборок - но отсутствует единый (официальный) хаб для всех возможных библиотек.

Вот почему нужен PyPI, и почему он нужен именно стандартизированный. Это просто делает жизнь проще.

Настраиваем необходимый минимум

Для того чтобы создать собственный пакет для PyPI, необходимо будет установить pip и python соответственно. Так же нужно будет создать виртуальное окружение как для создаваемого нами пакета для PyPI, так и для проекта, где мы будем использовать наш пакет.

PIP (Package Installer for Python) - утилита командной строки которая позволяет скачивать пакеты из индекса пакетов на PyPI.

Шаги, которые необходимо пройти:

С официального сайта, устанавливаем python - https://www.python.org/downloads/. Вместе с python будет установлен и pip
Создаём директорию и виртуальное окружение, где будем создавать пакет. Для этого назовём директорию UsefulPackage.
Регистрируемся на pypi.org (и на test.pypi.org, если только начинаешь и нужно освоиться)

Зачем мне регистрироваться на test.pypi.org, если можно сразу перейти к публикации на pypi.org? Это вопрос скорее манер и воспитания, чем практики. Да, ты можешь так сделать, тебя никто не остановит. Но с целью не допущения засорения публичного индекса, "тестовыми" пакетами и существует тестовый индекс, где ты можешь отработать все нюансы публикации и развития своих python-пакетов.

Кто не знает как создать виртуальное окружение, это делается через следующую команду, где:

python - имя версии питона, для которой ты хочешь собрать виртуальное окружение
-m venv - имя используемого модуля, в данном случае этот модуль для создания виртуального окружения
.venv - позиционный аргумент модуля виртуального окружения, говорит в какую директорию сохранить виртуальное окружение

python -m venv .venv

Это всё что нам потребуется для дальнейшего. Итак, на данный момент, структура пакета у нас следующая:

UsefulPackage
.venv

Дополнительно, тестовый проект

Дополнительно можно создать тестовый проект, куда и будем устанавливать недавно созданный пакет, для того чтобы просто убедиться, что мы всё сделали правильно и пакет действительно работает как надо. Для этого создадим директорию UsefulProgram. И там создадим виртуальное окружение, как это было описанно выше.

Нам ещё потребуется файл main.py, который мы и будем пропускать через интерпретатор.

Создай его и вставь следующий тестовый код:

from useful_package_YOURNAME.main import isWork if __name__ == "__main__": isWork()

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

Это всё что нам потребуется для дальнейшего. Итак, на данный момент, структура проекта у нас следующая:

UsefulProgram
.venv
main.py

Если запустить его сейчас, то ты получишь ошибку не правильного импорта пакетов, такого пакета пока не существует.

Быстрый старт, по созданию базового пакета на Python для PyPI

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

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

И для начала потребуется создать соответствующую структуру для пакета. Она будет выглядеть вот так:

UsefulPackage/
.venv/
useful_package_timthewebmaster/
LICENSE <- Файл лицензии можно выбрать подходящую тут
pyproject.toml <- О нём поговорим чуть ниже, файл конфигурации
dist/ <- Место где будет source distribution и build distribution
src/
useful_package_timthewebmaster/ <- Место где будет исходный код вашего пакета и его логика соответственно
__init__.py
main.py

PyPI Source Distribution - Формат распространения пакетов (обычно создаваемый с помощью команды python -m build --sdist), который предоставляет метаданные и основные исходные файлы, необходимые для установки с помощью инструмента, например pip, или для создания готового пакета.

PyPI Build Distribution - Формат распространения пакетов, содержащий файлы и метаданные, которые для установки достаточно лишь переместить в нужное место в целевой системе.

В src/useful_package_timthewebmaster будут находиться наши скрипты, которые мы и хотим использовать в других проектах.

Настраиваем файл pyproject.toml

После создания структуры для пакета, необходимо прописать конфигурационный файл - pyproject.toml. Данный файл имеет всего лишь 4 обязательных параметра.

Так, в [build-system] секции мы указываем какой бэкенд (и версию ) использовать для сборки пакета. А в секции [project] мы задаём всего лишь 2 обязательных поля: имя пакета и его версию. Все остальные поля не обязательны.

[build-system] requires = ["hatchling >= 1.26"] build-backend = "hatchling.build" [project] name = "useful-package-timthewebmaster" version = "0.0.1" authors = [ { name="Tim The Webmaster", email="timachuduk@gmail.com" }, ] license = "MIT" license-files = ["LICEN[CS]E*"]

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

Я обычно отталкиваюсь от этого базового шаблона, созданного мной и для меня. И просто меняю отличающиеся поля:

[build-system] requires = ["hatchling >= 1.26"] build-backend = "hatchling.build" [project] name = "django-referer-breadcrumbs" version = "0.0.2" authors = [ { name="Tim The Webmaster", email="timachuduk@gmail.com" }, ] description = "A Django app for generating a breadcrumbs from the refferer url (previosly visited), or by using yourown list of urls. It is customizable via template variables. Easy to set up and configure" readme = "README.md" requires-python = ">=3.10" classifiers = [ "Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Operating System :: OS Independent", "Environment :: Console", "Environment :: Plugins", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Natural Language :: English", "Natural Language :: Russian", "Topic :: Internet :: WWW/HTTP :: Dynamic Content", "Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System", "Topic :: Internet :: WWW/HTTP :: WSGI", "Topic :: Software Development :: Pre-processors", ] license = "MIT" license-files = ["LICEN[CS]E*"] dependencies = [ "Django>=5.1.7", ] keywords = ["django", "django app", "breadcrumbs", "navigation", "referer", "customizable", "timthewebmaster"] [project.urls] "Homepage RU" = "https://timthewebmaster.com/ru/tools/breadcrumbs-for-django/" "Homepage EN" = "https://timthewebmaster.com/en/tools/breadcrumbs-for-django/" "Issues RU" = "https://timthewebmaster.com/ru/tools/breadcrumbs-for-django/#comments_limiter" "Issues EN" = "https://timthewebmaster.com/en/tools/breadcrumbs-for-django/#comments_limiter"

На примере одного из моих пакетов

Генерируем python-пакет

У нас есть всё необходимое, чтобы построить свой первый пакет. Но для начала установим модель для интерпретатора python в текущем виртуальном окружении (незабудь пожалуйста создать его и активировать):

pip install build

Заходим в директорию с файлом настроек python-пакета, т.е. pyproject.toml и запускаем процесс создания пакета:

cd useful_package_timthewebmaster; python -m build

И вот так будет выглядеть, результат работы модуля build. Ну а если конкретнее, то будут созданы два архива source distribution и build distribution:

У нас появятся следующие архивы: useful_package_timthewebmaster-0.0.1-py2.py3-none-any.whl и useful_package_timthewebmaster-0.0.1.tar.gz, которые уже можно отправить в индекс PyPI.

Загружаем пакет на PyPI

Для того, чтобы их отправить потребуется установть ещё один модуль, модуль twine (не забудь создать и активировать виртуальное окружение).

pip install twine

Если ты всё ещё работаешь с тестовым репозиторием то, чтобы отправить пакет на тестовый индекс необходимо его указать используя флаг --repository с аргументом testpypi. А в конце указать все архивы, которые хочешь отправить.

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

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

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

python -m twine upload ./dist/*

На этом этапе от тебя потребуют API-токен для подтверждения того, кто и куда хочет опубликовать свой пакет. Его нужно будет создать. И есть небольшой нюанс, у каждого токена есть область действия, так сказать. Можно указать область действия для всех пакетов, а можно выборочно для каждого.

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

Чтобы создать токен для тестового индекса тебе сюда https://test.pypi.org/manage/account/#api-tokens

Чтобы создать токен для публичного индекса тебе сюда https://pypi.org/manage/account/#api-tokens

Вот так будет выглядеть результат успешной публикации пакета в индекс PyPI (вне зависимости от того тестовые это сервера или нет):

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

Полный гайд по созданию пакетов на Python для PyPI

В процессе, ожидайте.

Проверка собрал ли ты работающий пакет

После успешной сборки и загрузки пакета в индекс PyPI (Или тестовый индекс), очень желательно проверить, а работает и импортируется ли твой модуль вообще. Для этого создаём простенький проект, создаём и активируем виртуальное окружение, устанавливаем наш пакет наконец:

Если пакет был загружен на тестовый индекс PyPI, то для того, чтобы его установить, надо:

pip install --index-url https://test.pypi.org/simple/ useful-package-timthewebmaster

Не забудь поменять useful-package-timthewebmaster на своё название пакета

А для того, чтобы его обновить, добавь флаг --upgrade

pip install --index-url https://test.pypi.org/simple/ useful-package-timthewebmaster --upgrade

Не забудь поменять useful-package-timthewebmaster на своё название пакета

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

pip install useful-package-timthewebmaster

Не забудь поменять useful-package-timthewebmaster на своё название пакета

Дальше нужно просто запустить проект, который использует твой пакет и проверить его работу. В нашем случае, просто запустить скрипт через терминал: