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

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

В этом руководстве я проведу вас через все шаги по созданию собственного общедоступного пакета и помогу другим программистам, таким как вы.

Создать проект

Очевидно, что для публикации проекта сначала необходимо его создать. В этом руководстве я собираюсь создать проект для анализа и управления объектами TLV.

Значение длины тега (также известное как значение длины типа) - это схема кодирования, используемая для многих протоколов.

тег и длина имеют фиксированный размер (от 1 до 4 байтов), а поле значение имеет переменный размер. Более подробную информацию можно найти здесь.

Создание файлов пакета

Базовая структура вашего проекта будет содержать следующие файлы:

У нас есть две папки:

  • uttlv: папка, содержащая все файлы библиотеки. Это то же имя, что и у вашего пакета. Убедитесь, что у него есть файл с именем __init__.py, чтобы Python мог импортировать каталог как пакет. Это может быть пустой файл.
  • tests: папка со всеми вашими файлами модульного теста.

Файл LICENSE содержит срок лицензии для вашего проекта. Поскольку он будет общедоступным, важно сообщить пользователям, которые устанавливают ваш пакет, как они могут его использовать. Если вы хотите узнать больше обо всех доступных лицензиях, вы можете посетить этот сайт. В моем случае он содержит лицензию MIT.

Файл README.md содержит простое руководство по использованию вашего кода с основными командами и инструкциями. Мы можем использовать его также как контент, который отображается в URL-адресе описания проекта PyPI.

Файл setup.py содержит инструкции для setuptools по созданию вашего проекта. Он сообщает setuptools о вашем пакете, а также о том, какие файлы нужно включить. Это файл, который pip будет вызывать при выполнении команды install и должен ли иметь функцию setup().

Функция setup() принимает несколько аргументов. В этом примере у нас относительно минимальный набор:

  • name - это имя распространения вашего пакета. Это имя будет отображаться при поиске PyPI и будет использоваться пользователями для его установки. Его также нельзя размещать на pypi.org, и он может содержать только буквы, цифры, _ и -.
  • version - это версия пакета. Вы можете изменить это, когда захотите обновить свой пакет.
  • author и author_email используются для идентификации автора пакета.
  • description - это краткое изложение вашего проекта.
  • long_description - подробное описание вашего проекта. Это показано в деталях пакета на сайте PyPI. В этом случае мы используем содержимое из файла README.md.
  • url - это URL-адрес домашней страницы вашего проекта. В нашем случае это просто ссылка на страницу GitHub.
  • download_url - это ссылка для загрузки пакета исходного кода пакета. Убедитесь, что это тот же источник, что и вы отправили в PyPI. Здесь мы просто ссылаемся на страницу выпуска GitHub.
  • packages - это список всех пакетов, которые должны быть включены в дистрибутив. Здесь мы указали пакет uttlv, поскольку он единственный, который нам нужен. Вы также можете использовать find_packages() для автоматического обнаружения всех доступных пакетов и подпакетов.
  • classifiers дает индекс и pip некоторые дополнительные метаданные о нашем пакете, такие как лицензия, версия Python и Операционная система. Вы можете найти полный список здесь.

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

Создание архивов распространения

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

Убедитесь, что у вас установлены последние версии setuptools и wheel:

pip install --user --upgrade setuptools wheel

Теперь запустите эту команду из того же каталога, где находится setup.py:

python3 setup.py sdist bdist_wheel

После выполнения этой команды должны быть созданы две папки build и dist. В каталоге dist должно быть два файла.

tar.gz файл содержит исходный код, а .whl файл является встроенным дистрибутивом. Формат распространения сборки содержит все файлы и метаданные, которые нужно только переместить для установки. Если он не работает, он возвращается к исходному коду. Вы всегда должны загружать их оба в PyPI.

Загрузка вашего проекта

Наконец, пришло время загрузить ваш проект в PyPI. В Package Index есть два основных репозитория: официальный и тестовый. Test PyPI - это отдельный экземпляр индекса пакета, предназначенный для тестирования и экспериментов. Вы должны сначала использовать его, чтобы понять, как он работает, и вам не нужно загружать его в настоящий индекс. Все пакеты в тестовом индексе время от времени удаляются.

Создание учетной записи

Первое, что вам нужно сделать, это зарегистрировать учетную запись на PyPI (или Test PyPI). После регистрации вы должны подтвердить свой адрес электронной почты, чтобы иметь возможность публиковать любые пакеты в индексе. Вы получите электронное письмо с просьбой об этом.

Затем вы можете создать токен API, зайдя на страницу своей учетной записи и перейдя в раздел токенов API. Не ограничивайте его объем, поскольку вы создаете новый проект. Скопируйте токен в безопасное место, так как вы увидите его только один раз!

Теперь вы можете использовать пакет twine для загрузки пакетов распространения. Чтобы установить его:

pip install --user twine

Чтобы не вводить свои username и token каждый раз при загрузке, вы можете создать имя файла .pypirc в своем $HOME каталоге и разместить там все свои токены.

В моем случае я создал два репозитория: один для тестирования, а другой - для реального. Обратите внимание, что для реального индекса вам не нужно указывать URL репозитория, поскольку это автоматически делает twine библиотека. Не забудьте заменить <your_token> токеном, сгенерированным страницей PyPI.

Наконец, вы можете загрузить свой пакет:

python3 -m twine upload -r pypi dist/*

Или для тестового репозитория:

python3 -m twine upload -r pypitest dist/*

После того, как ваши файлы будут загружены, вы можете найти их в PyPI (или Test PyPI) по адресу https://pypi.org/project/<name> (для тестового: https://test.pypi.org/project/<name>). В моем случае вы можете найти его здесь.

Установка

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

pip install <package_name>

Если вы хотите его из тестового индекса:

pip install -i https://test.pypi.org/simple/ <package_name>

Вот и все. Теперь вы можете использовать свой пакет так же, как любой пакет Python, вызывая import package в своем коде.

Заключение

В этом руководстве мы рассмотрим, как настроить и опубликовать собственный пакет в Python Package Index и сделать его доступным для других пользователей. Это мощный инструмент Python и сообщества разработчиков ПО с открытым исходным кодом. И, возможно, кто-то еще может извлечь выгоду из вашего пакета.

Если вы хотите увидеть полный код этого руководства:



ustropo / uttlv
Значение длины тега (также известное как значение длины типа) - это схема кодирования, используемая для многих протоколов. Тег и длина… github.com