Пишем и публикуем свою первую библиотеку для Python

Часто в проектах на Python мы используем внешние библиотеки — уже готовые скрипты с нужными нам функциями, которые упрощают разработку. Теперь настало время сделать свою первую библиотеку на Python с нуля.

Подготовка 

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

pip install --upgrade pip

Теперь установим пакет twine — он нам поможет опубликовать свою библиотеку в сети, чтобы её мог установить любой желающий:

pip install --upgrade twine

Затем поставим hatchling — пакет для сборки серверной части библиотеки:

pip install hatchling

И наконец, установим пакет build, чтобы создать загрузочные архивы с нашей библиотекой:

pip install --upgrade build

Структура библиотеки

Библиотека в Python — это не просто один скрипт, а целый проект, в котором есть много разных файлов, каждый из которых отвечает за что-то своё. 

Первое, что делаем, — создаём папку src, в которой будет лежать наша новая библиотека. После этого внутри этой папки создаём ещё одну — с именем создаваемой библиотеки. Как мы назовём эту вложенную папку, так и будет называться наша библиотека. Для проекта мы выбрали название beginning_package.

Теперь внутри папки с названием создаём два файла:

Теперь делаем остальной обвес и внутри основной папки создаём такое:

В итоге по структуре должно получиться что-то вроде этого:

Оформляем лицензию и файл README.md

Наша библиотека будет относиться к свободному ПО, поэтому в файл с лицензией мы вставляем стандартный текст MIT License. В первой строке указываем копирайт и название проекта: 

Точно так же заполняем файл README.md. Обычно здесь показывают, какие функции доступны в пакете, причём здесь уже можно использовать маркдаун для оформления текста. У нас учебная библиотека, поэтому сделаем максимально простое описание:

This library is not that useful. Perhaps someday it will become great.

(Это не очень полезная библиотека. Возможно, когда-нибудь она станет лучше)

Заполняем pyproject.toml

Рyproject.toml — это файл, который отвечает за служебную часть библиотеки: как она называется, какая версия, какая версия Python нужна, по какой лицензии распространяется и так далее. Когда мы хотим установить новую библиотеку, система сначала смотрит в этот файл и проверяет, соответствует ли ваша версия Python той, что нужна для работы.

Файл состоит из блоков, каждый из которых отвечает за что-то своё. Начнём с блока build-system — он отвечает за параметры сборки загрузочного архива. В нашем проекте за серверную часть отвечает Hatchling, поэтому указываем его:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Дальше идут основные параметры проекта: название, выпуск, авторы, описание, имя файла readme, требования к версии Python, язык программирования, тип лицензии и совместимость с ОС:

[project]
name = ""
version = "0.0.1"
authors = [
 { name="", email="" },
]
description = ""
readme = "README.md"
requires-python = ">=3.10.0"
classifiers = [
   "Programming Language :: Python :: 3",
   "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
]

В конце можно добавить разные ссылки, например, на репозиторий в GitHub, домашнюю страницу проекта или на дополнительные материалы:

[project.urls]
Homepage = ""
Issues = ""

Пишем библиотеку

В папке с библиотекой два файла — __init.py__ и main.py. Файл __init__.py можно оставить пустым — он нужен для того, чтобы сборщик понял, что это именно цельный проект и его нужно собрать из других файлов в той же папке.

В main.py пишем сам код библиотеки. Так как это самая первая и учебная наша библиотека, сделаем там только одну функцию с приветствием:

def greeting():
   return "Hello, I'm your first library!"

Создаём загрузочные архивы

Цель этого этапа — собрать и подготовить библиотеку к загрузке в менеджер пакетов pip, откуда каждый сможет её установить. Для этого открываем командную строку, переходим в папку с проектом и собираем архив:

py -m build

Если в проводнике мы посмотрим на структуру папок, то увидим, что там появилась новая папка — dist, в которой и хранятся наши подготовленные для загрузки архивы:

Заглянем внутрь:

Создаём токен для подписи библиотеки

PyPi — это хранилище открытого программного обеспечения для Python. Чтобы опубликовать там библиотеку, нужно иметь аккаунт и получить уникальный API-токен. 

Для этого заходим на официальный сайт pypi.org, заводим новый аккаунт, привязываем Гугл-аутентификатор для безопасности и переходим в настройки аккаунта. Там прокручиваем страницу вниз до блока API tokens:

Нажимаем Add API token, придумываем имя для токена, указываем, что он будет действовать для всех проектов, и нажимаем Create token:

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

Загрузка библиотеки в PyPi

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

twine upload dist/*

Система попросит нас указать токен — вставляем то, что получили на предыдущем шаге:

После этого начинается загрузка файлов на сервер:

Нам сразу дали ссылку на нашу библиотеку в PyPi:

https://pypi.org/project/beginning-package/

Устанавливаем библиотеку и проверяем её работу

Для проверки библиотеки устанавливаем её себе на компьютер, как мы делали с любой другой библиотекой:

pip install beginning-package

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

py
from beginning_package import main
print(main.greeting())