Створення бібліотеки Python: покрокова інструкція із написання, тестування та публікації в PyPI

💡 Усі статті, обговорення, новини про Python — в одному місці. Приєднуйтесь до Python спільноти!

Привіт! Мене звати Валентин, я розробник із понад 8-річним досвідом. За ці роки мені довелося працювати з різними проєктами, стеком технологій та викликами, які допомогли не лише поглибити технічні навички, а й навчитися бачити код як інструмент вирішення реальних бізнес-задач.

У цій статті я поділюся практичним досвідом створення власної Python-бібліотеки — від ідеї до публікації. Якщо ви коли-небудь замислювалися над тим, як упакувати свій код у щось більше, ніж просто скрипт, — ця стаття саме для вас. Буде практично, зрозуміло і, сподіваюся, надихаюче 🙂

Дійсно, Python є однією з найпопулярніших мов програмування. Іноді ви дублюєте частини коду у різних проєктах. Набагато краще розробити бібліотеку, щоб заощадити час і зробити свій код упорядкованим, а також доступним для спільного використання іншими розробниками.

Ми створимо бібліотеку Python і протестуємо її, додамо документацію, версіювання та, нарешті, опублікуємо її в PyPI, щоб вона стала доступною для використання іншими розробниками. Поїхали!

Чому варто створювати бібліотеки Python

1. Повторне використання коду: припустімо, що ви використовуєте той самий код знову і знову в різних проєктах. У такому випадку визначення цього коду в одній окремій бібліотеці стане розумною інвестицією часу для майбутнього використання в інших проєктах.
2. Легкість оновлення: якщо необхідно оновити бізнес-правила. Наприклад, ви змінили код існуючої функції. То для використання нового функціоналу достатньо оновити лише версію бібліотеки.
3. Покращена якість коду: організація коду в окремі бібліотеки, переважно може похвалитися покращеною структурою з меншою кількістю повторювань.
4. Інвестуйте в спільноту: створіть відкриту бібліотеку, яка допоможе вам та всій спільноті розробників, оскільки це рішення, яке економить багато часу для інших.

Крок 1. Створення структури бібліотеки

Перш ніж почати писати будь-який код, вирішіть, що буде робити ваша бібліотека. У нашому випадку ми збираємося створити набір простих математичних функцій.

Гаразд, тепер налаштуймо структуру проєкту. Структура папок і файлів має фундаментальне значення.

dou-tools/
├── pyproject.toml
├── README.md
├── src/
│   └── dou_tools/
│       ├── __init__.py
│       └── core.py
├── tests/
│   └── test_core.py
└──gitignore

Пояснення структури:

• src/dou_tools/ — папка з вашою бібліотекою, що містить основний код.
• core.py — файл, що містить основний функціонал бібліотеки.
• tests/ — папка, що містить тести для вашої бібліотеки.
• README.md — файл для документації, де ви пояснюєте, що ваша бібліотека робить і як її використовувати.
• pyproject.toml — файл для налаштування бібліотеки.
• .gitignore — файл для виключення непотрібних файлів із системи контролю версій (наприклад, кеші, середовища).

Крок 2. Створення віртуального середовища та встановлення залежностей

Для нашого прикладу ми будемо використовувати Python3.13. Тепер створімо віртуальне середовище за допомогою наступної команди:

python3.13 -m venv venv

Активуємо наше віртуальне середовище:

source venv/bin/activate

Чудово, ми майже готові до написання функцій нашої бібліотеки. Залишилося лише встановити необхідні залежності. Зробімо це більш структурованим способом, створивши спочатку файл pyproject.toml. Він є фундаментальним. Він містить визначення самої бібліотеки, залежностей, саму назву проєкту та багато іншої важливої ​​інформації.

[build-system]
requires = ["setuptools>=61.0"]  # Потрібно для збирання пакета
build-backend = "setuptools.build_meta"  # Вказує, що саме білдить setuptools
[project]
name = "dou-tools"  # Назва пакета для PyPI
version = "0.1.0"  # Поточна версія
description = "Example DOU tools Python library"  # Короткий опис
authors = [{ name = "Valentyn Druzhynin" }]  # Автор
readme = "README.md"  # Файл, який відображається на PyPI
license = {text = "MIT"}  # Тип ліцензії
dependencies = []  # Основні залежності (для користувача пакета)
[project.optional-dependencies]
dev = [
    "pytest",  # Для запуску тестів
    "twine",  # Для публікації на PyPI
    "build"  # Для побудови дистрибутивів (.whl, .tar.gz)
]
[tool.setuptools]
package-dir = {"" = "src"}  # Вказує, що пакети лежать у каталозі src/
[tool.setuptools.packages.find]
where = ["src"]  # Пошук пакетів здійснюється у src/
[tool.pytest.ini_options]
pythonpath = ["src"]  # Додає src до PYTHONPATH для pytest

Як ми вже з’ясували, налаштувати локальні залежності тепер дуже легко:

 pip install -e “.[dev]”

Готово! Тепер перейдімо далі та, власне, напишемо сам функціонал.

Крок 3. Написання функціональності бібліотеки

І ось головну функцію можна реалізувати, адже створено структуру бібліотеки. Як ми визначили вище, буде бібліотека математичних функцій.

Файл core.py:

# dou_tools/core.py
def add(a, b):
    """Функція для додавання двох чисел"""
    return a + b

Ми створюємо функцію add(), яка приймає два аргументи a та b і повертає їх суму. Це простий код, але ви вже можете почати використовувати його в інших проєктах, якщо збережете його в окремій бібліотеці.

Ініціалізація пакета:

Щоб ваша бібліотека була доступною для імпорту в інших проєктах, додайте наступне в файл __init__.py:

from .core import add

Тепер функція add буде доступна для імпорту з вашого пакета:

from dou_tools import add
print(add(5, 7))  # Виведе: 12

Крок 4. Тестування бібліотеки

Тести є важливою частиною створення будь-якої бібліотеки, оскільки вони допомагають виявити помилки ще до того, як ваш код стане частиною іншого проєкту. Для тестування ми будемо використовувати популярний інструмент pytest.

Тепер створимо тест для нашої функції додавання в файл test_core.py у папці tests/.

Файл test_core.py:

# tests/test_core.py
from dou_tools import add

def test_add():
    """Тест для функції додавання"""
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(0, 0) == 0

Ці тести перевіряють різні варіанти функції add — додавання позитивних чисел, від’ємних і нульових значень.

Запуск тестів:

pytest

Всі тести повинні пройти успішно, і ви побачите повідомлення про це.

Крок 5. Документація

Документація — один з найбільш важливих аспектів бібліотеки. Вона дозволяє користувачам зрозуміти, як правильно використовувати нашу бібліотеку, а також дає змогу легко знайти потрібну інформацію.

У Python можна додавати документацію до функцій за допомогою докстрінгів — коментарів, що описують призначення функції, її параметри та повернуті значення. Наприклад:

def add(a, b):
    """Функція для додавання двох чисел
    Параметри:
    a (int): перше число
    b (int): друге число
    Повертає:
    int: сума двох чисел
    """
    return a + b

Крім цього, важливо написати документацію у файлі README.md.

Приклад базового опису для вашої бібліотеки:

# dou_tools
Ця бібліотека реалізує прості математичні функції.
## Встановлення
Щоб встановити бібліотеку, скористайтеся командою:
```
pip install dou-tools
```

Документація у файлі README.md. буде підхоплена pypi.org і буде відображатись на сторінці самої бібліотеки. Саме тому краще написати якомога більше прикладів і інформації щодо використання вашої бібліотеки.

Крок 6. Версіювання бібліотеки

Версіювання — це важливий процес, який допомагає підтримувати стабільність нашої бібліотеки. Рекомендується використовувати semantic versioning (семантичне версіювання), яке складається з трьох чисел: MAJOR.MINOR.PATCH.

• MAJOR: зміни, які не сумісні з попередніми версіями.
• MINOR: нові функції, що сумісні з попередніми версіями.
• PATCH: виправлення помилок.

Наприклад, якщо ви додаєте нову функціональність до бібліотеки, то збільшується мінорна версія:

version='0.2.0',  # Зміна з 0.1.0 на 0.2.0

Версія нашої бібліотеки зберігається в pyproject.toml.

Крок 7. Публікація на PyPI

Останній крок — публікація нашої бібліотеки на PyPI, щоб інші користувачі могли встановити її за допомогою pip.

Кроки для публікації:

1. Створіть обліковий запис на PyPI. Ймовірно, вам доведеться ввімкнути 2FA (аутентифікація) після реєстрації.
2. Встановіть twine. Ми вже встановили це з попередньої інсталяції pip install.
3. Згенеруйте API_TOKEN у своєму обліковому записі PyPi.

   

4. Створіть конфігурацію зі згенерованим токеном на вашому компʼютері. Більш детальні інструкції з’являться після того, як ви створите токен на сайті. Потім потрібно буде створити новий файл ~/.pypirc із нещодавно згенерованим токеном.
5. Створіть дистрибутив у своїй бібліотеці. Тобто спакуйте і підготуйте її до розгортання. Просто запустіть таку команду:

python -m build

6. Після команди збірки ми повинні мати в папці dist 2 файли дистрибутива з розширеннями: tar.gz і whl. Перевіримо, що саме було упаковано в нашій бібліотеці, перш ніж йти далі. Нас цікавлять лише файли python, які містять код, який, звісно, ​​буде імпортований на більш пізньому етапі. І це можна зробити за допомогою простої команди:

unzip -l dist/<package_name>.whl

Таким чином, у нас повинно вийти щось на зразок цього:

Archive:  dist/dou_tools-0.1.5-py3-none-any.whl
  Length      Date    Time    Name
---------  ---------- -----   ----
       33  05-04-2025 01:32   dou_tools/__init__.py
      561  05-04-2025 01:32   dou_tools/core.py
      698  05-04-2025 01:32   dou_tools-0.1.5.dist-info/METADATA
       91  05-04-2025 01:32   dou_tools-0.1.5.dist-info/WHEEL
       10  05-04-2025 01:32   dou_tools-0.1.5.dist-info/top_level.txt
      454  05-04-2025 01:32   dou_tools-0.1.5.dist-info/RECORD
---------                     -------
     1847                     6 files

Як бачимо, наш файл core.py присутній. Бібліотека правильно запакована.
7. Тепер перевіримо, як упакована наша бібліотека за допомогою twine. Навіщо взагалі все це робити? Бо ми не хотіли б помилок під час завантаження в PyPi, і ми б заощадили трохи часу в разі помилки.

twine check dist/*

8. І останнє — це просто завантаження в PyPi.

twine upload dist/*

Крок 8. Робимо pip install нашої бібліотеки

Тепер перевіримо, чи можна встановити нашу бібліотеку за допомогою pip. Для цього ми створимо окремий проєкт у новому віртуальному середовищі. Ми встановимо нашу бібліотеку:

pip install dou-tools

Бібліотека вже встановлена; перевіримо її в дії. Для цього ми імпортуємо нашу функцію та надрукуємо результат.

from dou_tools import add
print(add(3,5))

Крок 9. Оновлення версії бібліотеки

Для оновлення версії бібліотеки достатньо у файлі pyproject.toml знову пройти шлях від build до upload. Ось і все, ви можете створити свою просту бібліотеку Python і поділитися своїм чудовим кодом з іншими розробниками 🙂

Висновок

Не забувайте про тести, документацію та версіювання. Ці аспекти роблять бібліотеку зручною для використання та зменшують кількість помилок. Тому бажаю, щоб ця інструкція допомогла Вам створити вашу першу бібліотеку Python і успішно опублікувати її на PyPI 🙂

• Посилання на бібліотеку на гітхабі
• Посилання на бібліотеку на PyPi