Использование setuptools
для управления зависимостями и распространения пакетов Python
Введение
В одной из своих недавних статей я обсуждал разницу между файлами requirements.txt
и setup.py
, которая в конечном итоге может помочь разработчикам управлять зависимостями своих пакетов таким образом, чтобы им было легко их распространять.
В сегодняшней статье я сосредоточусь на пакете setuptools
и расскажу о разнице между файлами setup.py
и setup.cfg
. Кроме того, мы также обсудим, как эти файлы могут понимать requirements.txt
файл, который должен содержать список зависимостей.
Наконец, мы также обсудим назначение файла pyproject.toml
и то, как изменился ландшафт распространения пакетов после принятия PEP-517. Мы также продемонстрируем, как перейти к использованию pyproject.toml
с setuptools
таким образом, чтобы вы соответствовали требованиям PEP-517 и PEP-518.
инструменты настройки в Python
setuptools
— это библиотека, построенная поверх distutils
, которая устарела (и подлежит удалению с Python 3.12). Пакет предлагает широкий спектр функций, которые упрощают упаковку проектов Python, что представляет собой процесс, который постоянно развивается и иногда может быть довольно сложным.
Под упаковкой мы обычно подразумеваем как зависимость управление, так и пакет распространение. Другими словами, упаковка — это обработка зависимостей ваших проектов (и даже зависимостей зависимостей и т. д.), а также то, как распространять ваш пакет, чтобы сделать его широко доступным и пригодным для использования другими проектами.
Файл setup.py
Файл setup.py
, вероятно, является наиболее важным файлом, который должен быть включен в корневой каталог вашего проекта Python, и в основном он служит двум основным целям:
- Он содержит различную информацию, относящуюся к вашему пакету, включая параметры и метаданные, такие как имя пакета, версия, автор, лицензия, минимальные зависимости, точки входа, файлы данных и многое другое.
- Служит интерфейсом командной строки, позволяющим выполнять команды упаковки.
Пример файла setup.py
# setup.py placed at root directory from setuptools import setup setup( name='examplepackage' version='1.0.1', author='Giorgos Myrianthous', description='This is an example project', long_description='This is a longer description for the project', url='https://medium.com/@gmyrianthous', keywords='sample, example, setuptools', python_requires='>=3.7, <4', install_requires=['pandas'], extras_require={ 'test': ['pytest', 'coverage'], }, package_data={ 'sample': ['example_data.csv'], }, entry_points={ 'runners': [ 'sample=sample:main', ] } )
А вот объяснение ключевых слов, которые использовались при вызове метода setup()
:
name
: это строка, соответствующая имени пакетаversion
: строка, соответствующая номеру версии пакета.author
: указывает автора (авторов) пакета.description
: Это строка для краткого описания пакета (обычно однострочное описание).long_description
: строка для более подробного описания пакета.url
: строка, указывающая URL-адрес пакета (обычно это репозиторий GitHub или страница PyPI).keywords
: это строка, разделенная запятыми (также может быть списком строк), которая содержит некоторые ключевые слова, относящиеся к пакету.python_requires
: это строка с разделителями-запятыми, которая содержит спецификаторы версии для версии Python, поддерживаемой пакетом.install_requires
: список строк, содержащих минимальные зависимости, необходимые для успешного запуска пакета.extras_require
: словарь, в котором ключи соответствуют именам дополнительных режимов, а значения представляют собой списки, содержащие минимальные требуемые зависимости. Например, дополнительным режимом может бытьtest
, где список зависимостей должен включать все дополнительные пакеты, необходимые для выполнения тестов, определенных в пакете.package_data
: Это словарь, где ключи — это имена пакетов, а значения — это списки шаблонов глобусов.entry_points
: Это словарь, в котором ключи соответствуют именам точек входа и значениям фактических точек входа, определенных в исходном коде.
Более полный список доступных ключевых слов для метаданных и параметров можно найти в соответствующем разделе официальной документации.
Файл setup.cfg
Традиционно файл setup.py
использовался для сборки пакетов, например. с помощью команды build
через интерфейс командной строки.
$ python setup.py build
В примере файла setup.py
, продемонстрированном выше, мы видели, что большая часть кода просто перечисляет некоторые параметры и метаданные о проекте Python. На самом деле, это может быть не лучший подход с точки зрения качества кода и дизайна. Поэтому указание этих сведений о пакете в файле setup.cfg
может быть более подходящим.
setup.cfg
– это ini-файл, содержащий параметры по умолчанию для setup.py
команд. Вы можете в значительной степени указать каждое ключевое слово, которое мы использовали в файле setup.py
, в новом файле setup.cfg
и просто использовать файл setup.py
в качестве интерфейса командной строки.
Пример файла setup.cfg
# setup.cfg file at the root directory [metadata] name = examplepackage version = 1.0.1 author = Giorgos Myrianthous description = This is an example project long_description = This is a longer description for the project url = https://medium.com/@gmyrianthous keywords = sample, example, setuptools [options] python_requires = >=3.7, <4 install_requires = pandas [options.extras_require] test = pytest coverage [options.package_data] sample = example_data.csv'
setup.py с setup.cfg
Теперь, предположив, что вы переместили все параметры в файл setup.cfg
, как описано в предыдущем разделе, теперь вы можете создать фиктивный файл setup.py
, который будет просто вызывать метод setup()
:
from setuptools import setup if __name__ == '__main__': setup()
Более подробные примеры того, как использовать файлы setup.py
и setup.cfg
, можно найти в примере проекта PyPA на GitHub.
Файл pyproject.toml и переход на PEP-517
Начиная с PEP-517 и PEP-518 setuptools
больше не является де-факто инструментом, который предполагается использовать при упаковке проектов Python. Согласно спецификации PEP-518, системные зависимости сборки для проекта Python должны быть включены в файл с именем pyproject.toml
, соответствующий формату TOML.
Со временем setup.py
набирал популярность среди сообщества Python, но одна из самых больших проблем с setuptools
заключается в том, что использование исполняемого файла (то есть setup.py
) невозможно выполнить, не зная его зависимостей. И на самом деле нет способа узнать, что это за зависимости, если вы не запустите файл, содержащий информацию, связанную с зависимостями пакета.
Предполагается, что файл pyproject.toml
решает проблему зависимости инструмента сборки от курицы и яйца, поскольку сам pip
может читать pyproject.yoml
вместе с версией setuptools
или wheel
, необходимой для проекта. Файл ожидает таблицу [build-system]
, которая используется для хранения информации, связанной со сборкой.
Теперь давайте сложим кусочки головоломки вместе. Если вы хотите использовать setuptools
, теперь вам нужно указать файл pyproject.toml
с содержимым, показанным ниже:
# pyproject.toml file specified at the root of the directory [build-system] requires = ["setuptools>=42", "wheel"] # PEP 508 specifications. build-backend = "setuptools.build_meta"
Затем вам также необходимо указать файл setup.py
или setup.cfg
, как мы показали в предыдущих разделах руководства. Обратите внимание, что я лично предпочитаю последнее обозначение.
Наконец, вы можете создать свой проект с помощью компоновщика, такого как сборка PyPA, которую вы можете получить через pip (pip install build
) и, наконец, вызвать компоновщик.
$ python3 -m build
И вуаля! Теперь ваш дистрибутив будет готов к загрузке в PyPI, чтобы он был широко доступен.
Обратите внимание: если вы хотите установить пакеты в редактируемом режиме (т. е. запустив pip install -e .
), у вас должен быть действительный файл setup.py
, кроме setup.cfg
и pyproject.toml
. Вы можете использовать тот же фиктивный установочный файл, которым я поделился в предыдущем разделе, который делает всего один вызов метода setup()
.
Так мне все еще нужен файл requirements.txt?
Короткий ответ: скорее всего вероятно, да. Предполагается, что файлы setuptools
содержат абстрактные зависимости, а файлы requirements.txt
должны содержать конкретные зависимости.
Для более полного ознакомления с назначением requirements.txt
и setuptools
вы можете прочитать одну из моих недавних статей, опубликованных ниже.
Последние мысли
В сегодняшней статье мы обсудили пакет setuptools
и то, как использовать файлы setup.py
и setup.cfg
для управления зависимостями пакетов и упрощения распространения пакетов в Python.
Кроме того, мы обсудили различные параметры и метаданные, которые можно указать, а также различия между файлами setup.py
и setup.cfg
. Мы также обсудили файл requirements.txt
и то, как его можно использовать для решения головоломки управления зависимостями в пакетах Python. Наконец, мы представили PEP517 и назначение файла с именем pyproject.toml
.
И последнее замечание: помните, что рекомендации по распространению пакетов в Python постоянно развиваются, особенно в последние несколько лет, поэтому следите за обновлениями и время от времени следуйте рекомендациям.
Стать участником и читать все истории на Medium. Ваш членский взнос напрямую поддерживает меня и других писателей, которых вы читаете. Вы также получите полный доступ ко всем историям на Medium.
Подходящие статьи, которые могут вам понравиться