Пошаговое руководство по упаковке Python для начинающих

Почему пакет Python?

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

Вы когда-нибудь писали несколько раз одни и те же строки кода в разных проектах? Или, возможно, вы уже написали какую-то полезную библиотеку, которую хотите сделать доступной для других? Или, может быть, вы просто заинтересованы в Python Packaging или в участии в сообществе Python?

В этой статье мы создадим небольшой пакет, а затем загрузим его в Индекс пакетов Python (PyPi), чтобы каждый мог загрузить и использовать ваш код в качестве библиотеки программного обеспечения, используя pip install.

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

Требования

Если у вас есть учетная запись GitHub и установлен Python, вы можете перейти к обзору проекта.

Репозиторий Git

Чтобы стать частью сообщества разработчиков ПО с открытым исходным кодом, вы должны публично разместить проект в службе хостинга с контролем версий. Наиболее распространенный выбор - использовать хост-репозиторий Git, который содержит виртуальное хранилище вашего проекта. Это позволяет вам координировать работу программистов и сохранять версии вашего кода, к которым вы можете получить доступ при необходимости. Самый популярный хостинг - GitHub. Если у вас еще нет учетной записи, первым делом создайте ее прямо здесь.

Python

Мы будем использовать Python 3. Для проекта можно использовать любую версию Python 3.5. Если у вас нет Python, вы можете загрузить его со страницы загрузки python.org. Я буду использовать Python 3.7 в Windows, но не имеет значения, какая у вас версия или ОС для этого проекта. Если вы новичок в Python, я могу предложить вам выполнить несколько упражнений из этого руководства.

IDE

Интегрированная среда разработки (IDE) - это редактор исходного кода, который предоставляет вам средства отладки и автоматизации. Неважно, какой редактор кода или IDE вы используете, пока вам это нравится. Я лично буду использовать легкий, но мощный редактор кода под названием Visual Studio Code.

Обзор проекта

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

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

Вот как будет выглядеть структура проекта. Вы можете создать файлы вместе со мной или напрямую загрузить весь репозиторий на GitHub.

primelib/
    primelib/
        __init__.py
        prime_numbers.py
    tests/
        test_prime.py
    .gitignore
    LICENSE
    README.md
    setup.py

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

Постройте проект шаг за шагом

Инициировать и клонировать репозиторий GitHub

Первое, что нужно сделать, это запустить репозиторий в GitHub. Войдите на GitHub и нажмите зеленую кнопку «Создать» . Вы должны попасть на страницу с заголовком «Создать новый репозиторий». Заполните пустые поля, как показано ниже, при выборе файла README, файла Python .gitignore и лицензии MIT. Когда вы будете готовы, нажмите «Создать репозиторий».

Создав репозиторий на GitHub, вы должны клонировать его локально на своем компьютере. Для этого на вашем компьютере должен быть установлен Git и терминал. В Windows я рекомендую использовать новый Терминал Windows, хотя вы определенно можете использовать командную строку. Откройте терминал и убедитесь, что git правильно установлен, запустив git --version. Затем отправляйтесь туда, где вы хотите сохранить свой проект локально, используя cd. Наконец, вы можете запустить git clone https://github.com/YOUR-USERNAME/primelib.git. Ссылка предоставляется при нажатии зеленой кнопки Код.

Теперь ваш проект должен быть скопирован на ваш компьютер. Не стесняйтесь открывать папку primelib в своем любимом редакторе кода. У вас должна получиться следующая структура.

.gitignore
LICENSE
README.md
  • Файл .gitignore позволяет игнорировать некоторые файлы при отслеживании и загрузке кода в репозиторий.
  • Файл LICENSE - это просто файл .txt, содержащий лицензию на проект. Вы можете найти свои нужды здесь, хотя лицензия MIT - хороший выбор по умолчанию для нескольких проектов.
  • Файл README.md - это файл в формате Markdown, содержащий описание проекта. Вы можете написать документацию для модулей и функций, которые будет предоставлять ваша библиотека.

Код Python

В папке primelib/ теперь вы можете добавить новую папку, также называемую primelib, которая будет содержать весь ваш код. В этой новой папке создайте 2 файла Python с именами prime_numbers.py и __init__.py (с двумя ведущими и двумя конечными символами подчеркивания).

primelib/
    __init__.py
    prime_numbers.py
.gitignore
LICENSE
README.md

Начнем с prime_numbers.py, который содержит код Python, который мы будем использовать. Вы можете просто скопировать и вставить этот код в свой prime_numbers.py файл.

Код Python содержит две функции:

  • _divides - это закрытая функция, поэтому она начинается с символа подчеркивания в начале. Он используется следующей функцией is_prime и возвращает True тогда и только тогда, когда div делит n.
  • is_prime проверяет, имеет ли число n делитель, отличный от 1, и возвращает True, если это так.

Файл __init__.py необходим для превращения primelib в пакет. Это будет файл, выполняемый вашим интерпретатором Python при запуске import primelib или from primelib import .... Чтобы сделать вашу functionis_prime напрямую доступной из вашей библиотеки с помощью команды: primelib.is_prime(n), вы должны написать следующее в вашем __init__.py файле:

Тесты

Хорошо, теперь пора создать несколько тестов, чтобы убедиться, что наши функции работают должным образом. Теперь вы можете создать папку tests в каталоге вашего проекта и добавить в нее файл test_prime.py.

primelib/
    __init__.py
    prime_numbers.py
tests/
    test_prime.py
.gitignore
LICENSE
README.md

Вы можете просто скопировать следующие тесты.

Затем вы можете использовать библиотеку Pytest, которая является частью стандартной библиотеки Python, поэтому она поставляется вместе с Python, и ее не нужно устанавливать. Pytest автоматически проверит ваши утверждения assert в любом test_*.py файле. В своем терминале вы можете просто запустить следующую команду.

python -m pytest

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

Создайте библиотеку

Мы собираемся использовать три библиотеки setuptools, wheel и twine. Убедитесь, что они доступны в вашей среде.

pip install --upgrade setuptools wheel twine

Для сборки пакета требуется один последний файл. Вы должны добавить setup.py файл в корень вашего каталога. Это говорит setuptools, как на самом деле собрать пакет. Давайте добавим этот последний файл, чтобы получить окончательную древовидную структуру.

primelib/
    primelib/
        __init__.py
        prime_numbers.py
    tests/
        test_prime.py
    .gitignore
    LICENSE
    README.md
    setup.py

Вот файл setup.py. Вы можете скопировать и вставить его, заменив YOUR-USERNAME своим именем, чтобы имя библиотеки было уникальным.

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

python setup.py sdist bdist_wheel

Это создает архивы распространения в каталоге dist/. Теперь вы можете установить библиотеку в своей локальной среде, выполнив python setup.py install. Вы можете попробовать импортировать primelib в оболочку Python.

python
>>> import primelib
>>> primelib.is_prime(13)
True

Загрузить на PyPi

Теперь, когда у вас есть рабочая библиотека, вы можете загрузить ее в Python Package Index (PyPi), чтобы поделиться ею с сообществом Python. Для целей этого руководства мы собираемся использовать TestPyPi, он работает точно так же, как PyPi, но предназначен для тестирования пакетов, чтобы реальные серверы оставались чистыми. насколько возможно.

Сначала вам нужно зарегистрировать аккаунт на TestPypi и подтвердить свой адрес электронной почты. Наконец, вы можете загрузить свой пакет в виде архивов, используя следующую строку.

python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Готово! Ваш пакет теперь доступен для сообщества. Если бы он был загружен на PyPi, вы могли бы напрямую установить пакет с pip install primelib, но, поскольку он сейчас находится на TestPyPi, вы можете установить свой пакет, используя следующее:

pip install --index-url https://test.pypi.org/simple/ primelib-YOUR-USERNAME

Если у вас возникнут проблемы с упаковкой, обратитесь к Руководству по упаковке Python.

Ваша библиотека теперь доступна в вашей среде Python. Я настоятельно рекомендую использовать virtualenv для управления различными средами.

Вывод

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

Я надеюсь, что теперь вы готовы внести свой вклад в сообщество Python и поделиться своим отличным кодом с остальным миром!

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

  • Используйте виртуальные среды (virtualenv)
  • Используйте инструмент непрерывной интеграции (Travis CI)
  • Инструменты управления версиями (SemVer)
  • Автоматизируйте тестирование с помощью nox (nox)
  • Автоматизация HTML-документации (Сфинкс)