Как написать и опубликовать свою библиотеку Python

Расширенные примеры создания и публикации библиотеки

Пример 1. Полный пакет с несколькими модулями и тестами

Создадим библиотеку для работы с числами Фибоначчи.

Файловая структура:

fiblib/
├── pyproject.toml
├── README.md
├── src/
│   └── fiblib/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
└── tests/
    ├── __init__.py
    ├── test_core.py
    └── test_utils.py

Содержимое pyproject.toml:

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "fiblib"
version = "0.2.0"
description = "Библиотека для работы с числами Фибоначчи"
readme = "README.md"
license = { text = "MIT" }
dependencies = []

[tool.setuptools.packages.find]
where = ["src"]

Файл src/fiblib/core.py:

from functools import lru_cache

@lru_cache(maxsize=None)
def fibonacci(n: int) -> int:
    """Возвращает n-е число Фибоначчи."""
    if n < 0:
        raise ValueError("n must be non-negative")
    if n == 0:
        return 0
    if n == 1:
        return 1
    return fibonacci(n-1) + fibonacci(n-2)

Файл src/fiblib/utils.py:

def is_fibonacci(x: int) -> bool:
    """Проверяет, является ли число x числом Фибоначчи."""
    import math
    if x < 0:
        return False
    a = 5*x*x + 4
    b = 5*x*x - 4
    s1 = int(math.isqrt(a))
    s2 = int(math.isqrt(b))
    return s1*s1 == a or s2*s2 == b

Файл src/fiblib/__init__.py:

from .core import fibonacci
from .utils import is_fibonacci

Файл tests/test_core.py:

import pytest
from fiblib import fibonacci

def test_fibonacci_0():
    assert fibonacci(0) == 0

def test_fibonacci_1():
    assert fibonacci(1) == 1

def test_fibonacci_10():
    assert fibonacci(10) == 55

def test_fibonacci_negative():
    with pytest.raises(ValueError):
        fibonacci(-1)

Файл tests/test_utils.py:

from fiblib import is_fibonacci

def test_is_fibonacci_positive():
    assert is_fibonacci(21) == True
    assert is_fibonacci(22) == False

def test_is_fibonacci_zero():
    assert is_fibonacci(0) == True

def test_is_fibonacci_negative():
    assert is_fibonacci(-5) == False

Установка в редактируемом режиме и запуск тестов:

pip install -e .
pytest -v

Результат вывода pytest (усечённый):

============================= test session starts ==============================
collected 6 items

tests/test_core.py ....                                                   [ 66%]
tests/test_utils.py ..                                                    [100%]

============================== 6 passed in 0.12s ===============================

Пример 2. Публикация на PyPI с помощью twine

После сборки пакета (python -m build) создаются файлы в dist/. Загрузить их на PyPI можно через twine:

pip install twine
twine upload dist/*

При этом потребуется токен из аккаунта PyPI. Для тестирования используют TestPyPI: twine upload --repository testpypi dist/*.

Пример 3. Автоматизация версионирования с setuptools_scm

Чтобы версия бралась из Git-тегов, добавьте в pyproject.toml:

[build-system]
requires = ["setuptools>=68", "wheel", "setuptools_scm>=6"]

[project]
dynamic = ["version"]

[tool.setuptools_scm]

Теперь при каждом коммите с тегом вида v0.1.0 версия обновится автоматически. Без тега будет сформирована версия на основе dev.

Пример 4. Добавление документации с помощью Sphinx

Создайте папку docs/ и выполните:

sphinx-quickstart

Настройте docs/conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

extensions = ['sphinx.ext.autodoc']

Сгенерируйте документацию по докстрингам:

sphinx-apidoc -o docs/source ../src/my_library
make html

Пример 5. Создание пакета с C-расширением через setuptools

Для производительности можно добавить модуль на Cython или C++. Пример с Cython:

# src/my_library/fast_math.pyx
def fast_square(int x):
    return x * x

В pyproject.toml укажите:

[build-system]
requires = ["setuptools", "cython", "wheel"]

[tool.setuptools]
package-data = {"my_library": ["*.so"]}

Сборка скомпилирует .so файл автоматически. Пример результата:

>>> from my_library.fast_math import fast_square
>>> fast_square(5)
25

Пример 6. Логирование и конфигурация в библиотеке

Добавьте в __init__.py:

import logging
logging.getLogger(__name__).addHandler(logging.NullHandler())

Это позволяет пользователю настраивать логирование без появления лишних сообщений.

Пример 7. Обработка ошибок при несовместимости Python

В pyproject.toml укажите:

[project]
requires-python = ">=3.8"

Если пользователь попытается установить на более старую версию, pip выдаст ошибку совместимости.