Написав какой-нибудь чудесный код, вам, возможно, захочется сделать его доступным для остальных. Питонский способ поделиться пакетом – это разместить его на PyPI. Давайте создадим простой пакет и попробуем пройти через весь процесс его публикации!
Наш пакет: левая панель
Разработчики JavaScript хороши в том, как нужно делиться кодом: если кто-то написал функционал, он делится им, так что никому больше не нужно изобретать велосипед (впрочем, некоторых это не останавливает). Отличный пример такой самоотверженности, это шикарная библиотека left-pad, и сегодня мы создадим клон этой библиотеки и поделимся её величием с сообществом Python! Кто-то уже послужил обществу, выпустив пакет left-pad в PyPI. Однако, этот пакет не содержит ни модульных тестов, ни репозиторий GitHub, почему мы не можем сделать лучше? Давайте создадим замену, и назовем её pad-on-left. Очень важно проверить, не занято ли название вашего пакета в данный момент на PyPI, перед тем как начать. Чтобы сделать это, просто воспользуйтесь окном поиска в правом верхнем углу страницы PyPI.
Структура пакета
Чтобы наш пакет работал с PyPI (что в целом означает, что нам нужна работа с distutils), наш пакет нуждается в нескольких файлах:
|
1 2 3 4 5 6 7 |
--- Корневая папка (имя не имеет значения) |- ваша библиотека | |- __init__.py | |- ваш_код.py |- setup.py |- README.rst |- LICENSE.txt |
Нам нужно написать файл README, по умолчанию в Python для этого используется ReStructuredText. Вы можете познакомиться с ReStructuredText в документации Sphinx. Если вы предпочитаете использовать Markdown, или любой другой файловый формат, вам нужно добавить файл setup.cfg туда, где вы определяете название файла. Более того, вам нужно подобрать лицензию для вашего кода. Люди не могут пользоваться вашим кодом без лицензии. В данном случае, мы выберем разрешительную лицензию с открытым исходным кодом, я использую лицензию Apache 2.0, но для вашего проекта вы можете использовать лицензию MIT, или любую другую. Мы создадим файл setup.py в будущем, используя PyCharm. Давайте начнем с нового, чистого проекта Python, и напишем приложение.
Написание приложения
Необходимая нам функция для написания очень проста: мы берем строку, или число, если оно меньше определенной длинны, мы должны добавить символы для заполнения левой стороны, пока не достигнем необходимой длины. В отличие от JavaScript, стандартная библиотека Python располагает специальным методом:
|
1 2 |
def left_pad(input, length, fill_character=' '): return str(input).rjust(length, str(fill_character)) |
Теперь добавим несколько тестов. Если вы перейдете на страницу npm (Node package manager, аналог pip для JavaScript) для left-pad, то увидите несколько вложенных примеров. Давайте убедимся в том, что наш код корректно выполняет эти примеры. Отличный способ модульного тестирования Python является использование doctest-ов. Они позволяют вам писать примеры в docstring-ах вашего кода, и затем doctest будет выполнять эти примеры, а также подтверждать, соответствует ли ваш код документации:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
def left_pad(input, length, fill_character=' '): """ Returns a string, which will be padded on the left with characters if necessary. If the input string is longer than the specified length, it will be returned unchanged. >>> left_pad('foo', 5) ' foo' >>> left_pad('foobar', 6) 'foobar' >>> left_pad('toolong', 2) 'toolong' >>> left_pad(1, 2, '0') '01' >>> left_pad(17, 5, 0) '00017' :param input: :param length: The return string's desired length. :param fill_character: :rtype str: """ return str(input).rjust(length, str(fill_character)) |
Для запуска теста, добавьте конфигурацию запуска doctest: перейдите в Run Configuration и добавьте конфигурации test и doctest. После этого вы можете определить путь, для этого существует несколько способов, я решил настроить его для поиска в папке моего пакета. После этого, вы можете запустить тест и проверить, проходят ли модульные тесты.
Теперь сгенерируем файл setup.py, выбрав Tools -> Create setup.py:
- Название пакета должно уже быть заполнено, оно же и является названием нашего проекта. Это название пользователи будут использовать для установки данного пакета в pip;
- Version: вам нужно предоставить начальную версию вашего пакета. Она обновляется каждый раз, когда вы нажимаете на update в PyPI. Вам следует использовать семантическое управление версиями, по возможности, в противном случае — PEP 440 описывает несколько способов управления версий пакетов.;
- URL: это должен быть URL домашней страницы вашего пакета. В большинстве случаев вы можете использовать URL-адрес репозитория GitHub;
- License: лицензия, которую вы используете для своего кода, я использую Apache 2.0;
- Author: ваше имя и фамилия:
- Author Email: ваша почта
- Description: короткое описания того, что ваш пакет такое и зачем он нужен.
Публикация кода в GitHub
Давайте создадим репозиторий git, и опубликуем код на GitHub. Используйте Ctrl+Shift+A (Cmd+Shift+A на Mac) для открытия окна Find Action и напишите «Create Git Repository».
Добавьте файл .gitignore, выделите все свои файлы и затем добавьте их в git при помощи Ctrl+Alt+A (Cmd+Alt+A). Затем зафиксируйте (Ctrl + K / Cmd + K) ваши файлы, чтобы создать первоначальную фиксацию. Теперь опубликуйте в GitHub: снова откройте Find Action (Ctrl + Shift + A) и найдите «Share Project on GitHub».
Так как мы собираемся упаковать и выпустить этот код с версией 1.0.0, мы можем также пометить этот коммит как версия 1.0.0. Мы можем сделать это, перейдя по VCS | Git | Tag (в PyCharm). Я использую v1.0.0 и как название тега, и сообщение. Рекомендуется использовать сообщения в том числе, для создания полного тега. Теги размещаются раздельно, так что нам нужно перейти по VCS | Git | Push, поставить флажок на Push Tags и Push.
Регистрация в PyPI
С этого момента, нам нужно зарегистрировать как реальный, так и тестовый PyPI.
- Регистрация тестового аккаунта
- Регистрация полноценного аккаунта
Чтобы использовать эти учетные данные, нам нужно создать файл .pypirc. Это ini файл конфигурации, так что давайте создадим скреч файл, который мы можем сохранить в надлежащем месте. Используйте Shift+Ctrl+Alt+Insert для создания скреч файла, указав ini в качестве языка.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
[distutils] index-servers= testpypi pypi [testpypi] repository = https://testpypi.python.org/pypi username = name_of_the_user password = hunter2 [pypi] repository = https://pypi.python.org/pypi username = name_of_the_user password = hunter2 |
После написания содержимого файла, используйте File | Save As, и сохраните файл как .pypirc в вашей домашней директории (/home/yourname/.pypirc для Mac и Linux, C:\Users\YourName\.pypirc для Windows). После этого, вы можете ограничить доступ к файлу только для чтения из вашей учетной записи: chmod 600 ~/.pypirc для Mac и Linux, для Windows – нажмите правой клавишей на файл, Properties | Security, затем убедитесь, что ваша учетная запись имеет полный доступ, также убедитесь в том, что свободного доступа нет у других учетных записей.
Публикуем на PyPI
Для начала нам нужно создать собственный дистрибутив. Для этого у нас в распоряжении имеется команда setup.py
|
1 |
setup.py sdist |
Буквы s в sdist означает «source». Вы можете также создать готовые колеса, используя bdist. Для дополнительной информации об этом разделе вы можете обратиться к странице, посвященной пакетам на сайте PyPA. Сегодня мы создадим только исходный дистрибутив. Мы можем запустить задачу setup.py, выбрав Tools | Run Setup.py и выбрать sdist. Так как нам не нужны дополнительные опции командной строки, мы можем отклонить диалог на этот счет. После запуска, в выдаче мы увидим, что наш пакет уже сформирован. Теперь, когда у нас есть собственный пакет, мы можем приступить к загрузке нашего кода. В PyPA рекомендуют использовать Twine, а не команды setup.py, так как setup.py может передавать ваши пароли открытым текстом. Так что нам нужно установить Twine: Settings | Project | Project Interpreter и добавить Twine. После установки Twine, мы можем открыть Terminal(Alt+F12) и запустить регистр Twine:
|
1 2 |
twine register dist/pad-on-left-1.0.0.tar.gz -r testpypi twine upload dist/* -r testpypi |
Если эти команды выполнены правильно, вы увидите, что ваш пакет находится на testpypi. Если все выглядит гладко на testpypi, вы можете запустить те же команды, но без –r testpypi:
|
1 2 |
twine register dist/pad-on-left-1.0.0.tar.gz twine upload dist/* |
Если эти команды выполнены успешно, то вы загрузите ваш пакет на PyPI! Поздравляю!
Являюсь администратором нескольких порталов по обучению языков программирования Python, Golang и Kotlin. В составе небольшой команды единомышленников, мы занимаемся популяризацией языков программирования на русскоязычную аудиторию. Большая часть статей была адаптирована нами на русский язык и распространяется бесплатно.
E-mail: vasile.buldumac@ati.utm.md
Образование
Universitatea Tehnică a Moldovei (utm.md)
- 2014 — 2018 Технический Университет Молдовы, ИТ-Инженер. Тема дипломной работы «Автоматизация покупки и продажи криптовалюты используя технический анализ»
- 2018 — 2020 Технический Университет Молдовы, Магистр, Магистерская диссертация «Идентификация человека в киберпространстве по фотографии лица»