Как создать библиотеку Python

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

Но прежде чем создавать свою библиотеку, разберемся с определениями.

Что такое библиотека, модуль и пакет в Python

Если коротко, то модуль — это файл, пакет — это папка с модулями, а библиотека — это упакованный и публикуемый набор модулей и пакетов.

Модуль

Модуль — это один .py-файл с кодом. В нем лежат функции, классы и константы. Такой файл можно импортировать и использовать в другом месте проекта. 

Пример модуля: 

math_utils.py

В модуле могут содержаться:

• функции и небольшие утилиты;
• классы и @dataclass;
• константы и настройки;
• собственные исключения;
• импорты других модулей;
• строка документации модуля (docstring);
• аннотации типов;
• «точка входа» для быстрого запуска через if __name__ == «__main__» и т. д.

Примеры импорта:

Импорт модуля целиком 

import math_utils

Импорт отдельных объектов из модуля

from math_utils import double, RangeError

Пакет

Пакет — это папка с файлом __init__.py. Внутри нее лежат модули и подпакеты. Импортировать можно как весь пакет сразу, так и отдельные его модули. Импорт включает путь к модулю и выглядит как «папка.папка.файл», где точки разделяют уровни структуры.

Пример структуры пакета:

mypkg/
    __init__.py
    core.py
    helpers/
        __init__.py
        io.py

Здесь:

• mypkg/ — корневая папка пакета. Имя этой папки пишем при импорте:

import mypkg

• mypkg/core.py — модуль с основной логикой. В данном случае — с функцией run():

def run():
    print("ok")

• mypkg/__init__.py — файл инициализации пакета. Здесь можно прописывать инструкции для импорта. Например, инструкцию для импорта функции run():

from .core import run
__version__ = "0.1.0"

Тогда импорт функции run() из модуля core будет работать так:

from mypkg import run

• mypkg/helpers/ — подпакет со вспомогательным кодом. 

Импорт подпакета будет выглядеть так: 

import mypkg.helpers.io 

• mypkg/helpers/io.py — модуль с функциями ввода-вывода. Пример:

def load_text(path: str) -> str:
    return open(path, "r", encoding="utf-8").read()

• mypkg/helpers/__init__.py — файл инициализации подпакета helpers. Его можно оставить пустым или сократить пути импорта для функции load_text(), прописав:

from .io import load_text

Тогда импорт будет работать так:

from mypkg.helpers import load_text

Пример импорта функций без настройки в __init__.py:

from mypkg.core import run
from mypkg.helpers.io import load_text

Уточнение про __init__.py и «пространства имен»

Библиотека

Библиотека — это набор модулей и пакетов. Ее оформляют как отдельный продукт, устанавливают в проект и повторно используют. Библиотеку публикуют в каталоге PyPI, откуда ее можно «забрать» в свой проект через pip.

Примеры популярных библиотек:

• requests — для работы с HTTP-запросами;
• NumPy — быстрые массивы и базовая математика;
• pandas — таблицы и анализ данных.

Какие инструменты нужны для создания библиотеки

Python

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

Менеджер пакетов pip

Это стандартный инструмент для установки, обновления и удаления сторонних библиотек. Через pip вы будете ставить как свои сборки, так и чужие пакеты с PyPI.

Виртуальное окружение venv

Виртуальное окружение изолирует зависимости проекта. В одной папке можно держать одну версию библиотеки, в другой — другую, и они не будут конфликтовать. Модуль venv входит в стандартную библиотеку Python (с версии 3.3).

Подготовка рабочего окружения с venv

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

1. Перейдите в папку проекта 

В командной строке (например, в терминале или консоли) введите:

cd путь/к/проекту

2. Создайте виртуальное окружение с помощью модуля venv

python -m venv .venv

Здесь .venv — это имя папки с окружением. Можно выбрать и другое имя, но .venv обычно удобно «прятать» от Git через .gitignore.

3. Активируйте окружение

Windows (в cmd):

.venv\Scripts\activate

Windows (в PowerShell):

.venv\Scripts\Activate.ps1

macOS и Linux:

source .venv/bin/activate

После активации в начале строки терминала обычно появляется префикс вида venv или .venv.

4. Проверьте, что pip работает внутри этой среды

python -m pip --version

Эта команда показывает версию pip и путь до нее. 

Структура проекта

Структура папок влияет на удобство разработки и импорта библиотеки. Есть два популярных варианта структурирования — плоская структура и через src/.

Плоская структура (flat layout)

Для разработки вашей первой библиотеки такой вариант будет проще и понятнее.

Пример:

my-lib/
    pyproject.toml
    README.md
    mylib/
        __init__.py
        core.py
        helpers.py
    tests/
        test_core.py

Здесь:

• my-lib — корневая папка проекта;
• pyproject.toml — конфигурация сборки и метаданных пакета. Ниже мы отдельно разберем, что указывать в этом файле. Также можно почитать про него в Python Packaging User Guide;
• README.md — краткое описание проекта. Этот файл попадет на страницу пакета на PyPI;
• mylib — папка с кодом библиотеки. При импорте этого пакета нужно будет прописать:

import mylib

• mylib/__init__.py — файл инициализации пакета. Этот файл мы также разберем ниже; 
• mylib/core.py, mylib/helpers.py — модули с функциями и классами;
• tests/ — тесты, которые проверяют работу библиотеки.

Импорт в тестах выглядит так:

from mylib.core import run

Преимущества: простой старт для быстрого создания библиотеки.

Недостатки: может привести к «случайным импортам». Интерпретатор Python добавляет корень проекта в путь импорта, из-за чего скрипты или тесты иногда берут код прямо из исходного кода, а не из установленного пакета.

Структура с папкой src/

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

Пример:

my-lib/
    pyproject.toml
    README.md
    src/
        mylib/
            __init__.py
            core.py
            helpers.py
    tests/
        test_core.py

Папка src/ хранит исходный код пакета.

Преимущества:

• Ниже риск «случайных импортов» из корня проекта.
• Код библиотеки лежит отдельно от тестов, скриптов и конфигов, поэтому проект проще расширять.

Недостатки: требует начальной настройки и структурно выглядит сложнее.

Файл __init__.py

Ранее мы не раз упоминали файл __init__.py, который находится внутри папки, пакета или подпакета. Он ведет себя как обычный модуль Python и нужен, чтобы:

1. Отметить папку как пакет

Когда интерпретатор видит __init__.py внутри папки, он воспринимает ее как обычный пакет и разрешает импорт по типу:

import mylib
from mylib import something

2. Подготовить пакет при первом импорте

При первом импорте пакета интерпретатор запускает код из __init__.py.

Здесь можно:

• задать переменные пакета (версию, настройки и т. д.);
• выполнить простую инициализацию (например, настроить логгер или подготовить кэш для работы пакета);
• подтянуть нужные объекты из внутренних модулей.

3. Собрать удобный публичный API

Публичный API библиотеки — это список функций и классов, которые вы хотите показать пользователю. Остальная часть кода может остаться скрытой. Например, в src/mylib/__init__.py прописываем:

from .core import run, configure
from .helpers import load_text

__all__ = ["run", "configure", "load_text"]
__version__ = "0.1.0"

То есть:

Импортируем из внутренних модулей только нужные функции (run, configure, load_text), затем складываем их в список __all__, добавляем служебную информацию, например __version__.

Тот, кто установит вашу библиотеку, сможет писать так:

from mylib import run, load_text

run()
text = load_text("data.txt")

Ему не важно, лежит run() в core.py или в другом модуле. Он видит простое и короткое API: mylib.run, mylib.load_text.

Когда можно оставить __init__.py пустым

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

from mylib.core import run
from mylib.helpers import load_text

Для чего нужен pyproject.toml

Файл pyproject.toml лежит в корне проекта и содержит список инструментов упаковки и сборки проекта.

С помощью этого файла вы:

• выбираете, чем собирать пакет;
• описываете проект и его зависимости;
• храните настройки вспомогательных инструментов;
• делаете проект понятным для всей экосистемы: сборка, установка и публикация идут по одним и тем же правилам.

Дальше нам важны три блока: [build-system], [project] и при необходимости [tool…].

Блок [build-system]

Здесь вы указываете, каким инструментом нужно собрать проект и какие пакеты нужны для сборки.

Пример:

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

Про setuptools и другие системы сборки проекта поговорим ниже. Сейчас важно понять, что, когда вы запускаете команду

python -m build

утилита build читает pyproject.toml, смотрит в [build-system], ставит указанные пакеты из requires и затем использует build-backend, чтобы собрать вашу библиотеку.

Блок [project]

Блок [project] хранит основные сведения о библиотеке (метаданные):

• имя пакета;
• версию;
• описание;
• список зависимостей;
• минимальную версию Python;
• путь к README, информацию о лицензии;
• точки входа для CLI (если библиотека дает консольную команду).

Эти поля и их формат описывает стандарт PEP 621.

Пример:

[project]
name = "mylib"
version = "0.1.0"
description = "Пример учебной библиотеки"
readme = "README.md"
requires-python = ">=3.11"

authors = [
  { name = "Иван Иванов", email = "ivan@example.com" }
]

dependencies = [
  "requests>=2.31"
]

Эти данные попадают в метаданные пакета и на страницу проекта в PyPI. По ним пользователи видят, что за библиотека, кто автор и какие зависимости нужны.

Блоки [tool…]

Блоки [tool…] нужны для настроек сторонних утилит. Вместо нескольких отдельных файлов вы складываете конфигурации в один pyproject.toml. Например:

• форматтер кода: [tool.black]
• линтер: [tool.ruff] или [tool.flake8]
• тестовый фреймворк: [tool.pytest.ini_options]
• дополнительные настройки системы сборки или своих скриптов

В итоге и код, и метаданные пакета, и конфигурация инструментов лежат в одном месте. Работать с проектом будет проще и вам, и тем, кто подключится к разработке позже.

Выбор системы сборки

Система сборки — это библиотека для упрощения упаковки Python-проектов. Она собирает ваш проект в дистрибутивы (sdist и wheel) для установки через pip.

В блоке [build-system] в файле pyproject.toml мы уже использовали setuptools. Теперь разберем подробнее, что это такое и какие еще системы можно выбрать.

setuptools

Классический инструмент, который подойдет для сборки первого проекта. Он отличается своей простотой и лаконичностью.

hatch (hatchling)

Это более современный подход. Hatchling выступает как инструмент сборки, а hatch помогает управлять версиями, окружениями и релизами из одной утилиты.

Пример:

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

Poetry

Утилита, включающая в себя управление зависимостями, сборку и публикацию. В этом случае вы настраиваете проект через Poetry, а он сам пишет поля в pyproject.toml и собирает дистрибутив.

README, лицензия и метаданные

Перед сборкой дистрибутива нужно привести в порядок описание проекта.

Что положить в README.md

• одно-два предложения, что делает библиотека;
• как ее установить:

pip install mylib

• простой пример кода с использованием;
• список основных возможностей;
• раздел «ограничения» или «когда не стоит использовать»;
• ссылки на документацию или репозиторий.

В pyproject.toml нужно связать README с проектом:

[project]
name = "mylib"
description = "Пример учебной библиотеки"
readme = "README.md"

Лицензия

Определитесь с лицензией и добавьте файл LICENSE в корень проекта.

В pyproject.toml можно указать:

[project]
license = { file = "LICENSE" }

Дополнительно можно прописать классификаторы:

[project]
classifiers = [
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.11",
  "Operating System :: OS Independent",
]

Классификаторы помогают пользователям на PyPI фильтровать пакеты по версии Python, типу лицензии и платформе.

Тесты

Даже для маленькой библиотеки стоит завести пару тестов. Это защитит от случайных поломок перед публикацией.

Минимальные автотесты

В папке tests/ создайте простой тест с pytest, например test_core.py:

from mylib import run

def test_run_does_not_crash():
    run()

Установите pytest в виртуальное окружение:

python -m pip install pytest
python -m pytest

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

Сборка дистрибутивов

Когда структура проекта готова, pyproject.toml настроен, а тесты пройдены, можно собрать дистрибутивы (архивы с вашей библиотекой). Для этого используйте утилиту build.

Сначала установите ее в виртуальное окружение:

python -m pip install build

Затем в корне проекта выполните:

python -m build

• build прочитает pyproject.toml;
• посмотрит в блок [build-system];
• поставит нужные пакеты для сборки;
• вызовет указанный build-backend.

В результате в папке dist/ появятся два типа файлов:

• *.tar.gz — исходный архив (sdist)

Это архив с исходниками проекта: кодом, pyproject.toml, дополнительными файлами. Иначе говоря, это аккуратно упакованная версия вашей папки с проектом.

• *.whl — wheel, готовый дистрибутив. Внутри лежат файлы так, чтобы pip мог разложить их по нужным папкам. Установка из wheel обычно идет быстрее, чем из sdist.

Эти файлы затем можно использовать для локальной установки (pip install dist/имя.whl) и загрузки на TestPyPI или PyPI. Уже сейчас мы получили настоящую библиотеку, которую можно опубликовать в общий каталог и установить как обычный пакет.

Локальная установка для разработки

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

В корне проекта выполните:

pip install -e .

Точка в конце означает «установить пакет из текущей папки». Флаг -e включает режим разработки:

1. Pip не копирует файлы библиотеки, а создает ссылку на исходники.
2. Вы меняете код в mylib/ или src/mylib/
3. При импорте import mylib код уже добавляется с обновлениями.

Публикация библиотеки Python

Тестовый TestPyPI

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

1. Создайте аккаунт на TestPyPI
   Перейдите на https://test.pypi.org/ и заведите учетную запись. Она не будет связана с основным PyPI.

Порядок регистрации и создание токена описаны в гайде.

2. Установите twine
   Twine — это утилита для загрузки пакетов на PyPI и TestPyPI. Используйте команду для установки:

python -m pip install twine

3. Загрузите дистрибутивы на TestPyPI

В корне проекта, после вызова python -m build, у вас есть папка dist/ с sdist и wheel. Отправим их:

python -m twine upload --repository testpypi dist/*

Twine спросит логин и пароль (или токен) от TestPyPI и после подтверждения выложит файлы на тестовый сервер.

4. Проверьте страницу пакета

Перейдите по адресу вида https://test.pypi.org/project/имя-пакета/

Там будет показано описание, версия и файлы проекта, который вы загрузили.

5. Проверьте установку с TestPyPI

Установка только из TestPyPI:

python -m pip install --index-url https://test.pypi.org/simple/ your-package

Если на TestPyPI все работает (пакет ставится, импорт проходит, описание на странице выглядит нормально), можно переходить к настоящей публикации.

Публикация на PyPI

PyPI — это основной каталог пакетов. По умолчанию pip берет пакеты именно отсюда. Пошаговый туториал есть в разделе Packaging Python Projects. Если в общих чертах, то алгоритм работы с PyPI такой:

1. Создайте аккаунт на PyPI
   Перейдите на https://pypi.org/ и зарегистрируйтесь. Лучше сразу создать API-токен в настройках аккаунта, чтобы не вводить пароль в терминале.
2. Убедитесь, что дистрибутивы свежие

python -m build

В папке dist/ должны лежать актуальные файлы с нужным номером версии.

3. Установите и настройте twine, если еще не поставили

python -m pip install twine

4. Загрузите пакет на PyPI

В отличие от TestPyPI, здесь флаг —repository не нужен:

python -m twine upload dist/*

Twine отправит архивы в основной PyPI.

5. Проверьте страницу пакета и установку

Страница проекта: https://pypi.org/project/имя-пакета/

Установка из PyPI в чистое виртуальное окружение:

python -m pip install your-package

После этих шагов библиотекой можно пользоваться. Ее можно ставить в другие проекты, а также обновлять: повышать версию в pyproject.toml и заново выполнять шаги сборки и загрузки через twine upload dist/*.

Версионирование по PEP 440

PyPI не даст загрузить один и тот же архив с тем же номером версии. Каждый релиз должен иметь новую строку версии.

Чаще всего используют схему наподобие MAJOR.MINOR.PATCH, например:

• 0.1.0 первая рабочая версия;
• 0.2.0 добавили заметные фичи;
• 0.2.1 исправили баги без больших изменений;

PEP 440 описывает, какие строки версий считаются корректными. Важно запомнить несколько типов:

• стабильный релиз
  1.0.0, 2.3.4
• предварительные версии (pre-release)
  1.0.0a1 alpha
  1.0.0b1 beta
  1.0.0rc1 release candidate
• dev-версии
  1.0.0.dev1
  1.0.0.dev2
• пост-релиз
  1.0.0.post1
  1.0.0.post2

Где лежат установленные библиотеки

Когда вы ставите библиотеку через pip, она попадает в специальную папку site-packages внутри текущего окружения. 

Посмотреть список установленных библиотек

Самый простой способ — ввести:

pip list

Команда выведет таблицу с именами пакетов и их версиями.

Если список слишком длинный, можно отфильтровать по имени:

Windows (cmd):

pip list | find "mylib" 

Windows (PowerShell)

pip list | Select-String "mylib"

macOS и Linux

pip list | grep "mylib"

Получить информацию о конкретной библиотеке

Чтобы посмотреть детали по одному пакету, используйте:

pip show mylib

Результат покажет версию, краткое описание, зависимости и путь, куда установлен пакет. Особенно полезно поле Location. Там указан путь до папки site-packages текущего окружения.

Пример:

на Windows

Location: C:\Users\you\project\.venv\Lib\site-packages

на Linux и macOS

Location: /home/you/project/.venv/lib/python3.11/site-packages

Внутри site-packages лежит папка mylib и служебные файлы, которые создал pip.

Как удалить библиотеку

Если пакет больше не нужен, его можно убрать:

pip uninstall mylib

Тогда pip попросит подтверждение. После этого библиотека исчезнет из site-packages, а pip list больше не покажет ее в списке.

Чек-лист разработки и публикации библиотеки

1. Написать код для библиотеки в пакете mylib (или src/mylib).
2. Добавить базовые тесты в tests/.
3. Написать простой README.md (что делает библиотека, как ее ставить, как импортировать).
4. Настроить pyproject.toml ([build-system] и [project]).
5. Поставить библиотеку локально в режиме разработки:

pip install -e .

и убедиться, что импорт работает:

import mylib

6. После этого собрать дистрибутивы:

python -m build

7. Проверить установку из dist/ или через TestPyPI.
8. Уже потом выкладывать пакет на PyPI.