Написание скрипта настройки

2.1. Перечисление целых пакетов

Опция packages сообщает Distutils обработать (построить, распространить, установить и т. д.) все чистые модули Python, найденные в каждом пакете, указанном в списке packages. Для этого, конечно, должна быть корреспонденция между именами пакетов и каталогами в файловой системе. По умолчанию корреспонденция является наиболее очевидной, т. е. пакет distutils находится в каталоге distutils относительно корня дистрибутива. Таким образом, когда вы говорите packages = ['foo'] в вашем скрипте настройки, вы обещаете, что Distutils найдёт файл foo/__init__.py (который может быть написан по-другому на вашей системе, но вы поняли суть), относительно каталога, где находится ваш скрипт настройки. Если вы нарушите это обещание, Distutils выдаст предупреждение, но всё равно обработает поврежденный пакет.

Если вы используете другое соглашение для размещения каталога исходных файлов, это не проблема: вам просто нужно указать опцию package_dir для того, чтобы сообщить Distutils о вашем соглашении. Например, предположим, что вы храните все исходные файлы Python в lib, так что модули в «корневом пакете» (т. е. не в любом пакете вообще) находятся в lib, модули в пакете foo находятся в lib/foo, и так далее. Тогда вы должны поместить

package_dir = {'': 'lib'}

в ваш скрипт настройки. Ключи этого словаря — имена пакетов, а пустое имя пакета соответствует корневому пакету. Значения — имена каталогов относительно корня вашего дистрибутива. В этом случае, когда вы говорите packages = ['foo'], вы обещаете, что файл lib/foo/__init__.py существует.

Другим возможным соглашением является размещение пакета foo прямо в lib, пакета foo.bar в lib/bar и т. д. Это будет записано в скрипте настройки как

package_dir = {'foo': 'lib'}

Элемент package: dir в словаре package_dir подразумевает применение ко всем пакетам ниже package, поэтому случай foo.bar автоматически обрабатывается здесь. В этом примере наличие packages = ['foo', 'foo.bar'] сообщает Distutils о поиске lib/__init__.py и lib/bar/__init__.py. (Помните, что хотя package_dir применяется рекурсивно, вы должны явно перечислить все пакеты в packages: Distutils не будет рекурсивно сканировать дерево ваших исходных файлов в поисках любого каталога с файлом __init__.py)

2.2. Перечисление отдельных модулей

Для небольшого распределения модулей вы можете предпочесть перечислить все модули, а не перечислять пакеты — особенно в случае одного модуля, который попадает в «корневой пакет» (т. е. без пакета вообще). Этот самый простой случай был показан в разделе Простой пример; вот немного более сложный пример:

py_modules = ['mod1', 'pkg.mod2']

Это описывает два модуля, один из которых находится в «корневом» пакете, а другой — в пакете pkg. Опять же, по умолчанию для расположения пакетов/каталогов подразумевается, что эти два модуля можно найти в mod1.py и pkg/mod2.py, и что pkg/__init__.py также существует. И снова вы можете переопределить соответствие пакет/каталог, используя опцию package_dir.

2.3. Описание модулей расширения

Так же как написание модулей расширения Python немного сложнее, чем написание чистых модулей Python, описание их для Distutils немного сложнее. В отличие от чистых модулей, недостаточно просто перечислить модули или пакеты и ожидать, что Distutils найдет нужные файлы; необходимо указать имя расширения, исходный файл(ы) и любые требования к компиляции/связыванию (каталоги включаемых файлов, библиотеки для связывания и т.д.).

Все это делается с помощью другого ключевого аргумента для setup(), опции ext_modules. ext_modules — это просто список экземпляров Extension, каждый из которых описывает один модуль расширения. Предположим, что ваш дистрибутив включает один модуль расширения, называемый foo и реализованный foo.c. Если дополнительные инструкции для компилятора/линкера не требуются, описание этого расширения довольно просто:

Extension('foo', ['foo.c'])

Класс Extension можно импортировать из distutils.core вместе с setup(). Таким образом, скрипт настройки для дистрибутива модуля, который содержит только это расширение и ничего больше, может быть:

from distutils.core import setup, Extension
setup(name='foo',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )

Класс Extension (на самом деле, лежащая в основе механизма построения расширений, реализованный командой build_ext) поддерживает значительную гибкость в описании расширений Python, что объясняется в следующих разделах.

Extension('foo', ['src/foo1.c', 'src/foo2.c'])

Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])

setup(...,
      ext_package='pkg',
      ext_modules=[Extension('foo', ['foo.c']),
                   Extension('subpkg.bar', ['bar.c'])],
     )

setup(...,
      ext_modules=[Extension('_foo', ['foo.i'],
                             swig_opts=['-modern', '-I../include'])],
      py_modules=['foo'],
     )

> python setup.py build_ext --swig-opts="-modern -I../include"

Extension('foo', ['foo.c'], include_dirs=['include'])

Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])

#include <X11/Xlib.h>

#include <Numerical/arrayobject.h>

from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
setup(...,
      Extension(..., include_dirs=[incdir]),
      )

Extension(...,
          define_macros=[('NDEBUG', '1'),
                         ('HAVE_STRFTIME', None)],
          undef_macros=['HAVE_FOO', 'HAVE_BAR'])

#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR

Extension(...,
          libraries=['gdbm', 'readline'])

Extension(...,
          library_dirs=['/usr/X11R6/lib'],
          libraries=['X11', 'Xt'])

2.4. Взаимосвязи между дистрибутивами и пакетами

Дистрибутив может быть связан с пакетами тремя способами:

1. Он может требовать пакеты или модули.
2. Он может предоставлять пакеты или модули.
3. Он может устаревать пакеты или модули.

Эти взаимосвязи могут быть заданы с помощью ключевых аргументов функции distutils.core.setup().

Зависимости от других модулей и пакетов Python могут быть указаны, используя ключевой аргумент requires для setup(). Значение должно быть списком строк. Каждая строка указывает требуемый пакет и, необязательно, допустимые версии.

Для указания требования любой версии модуля или пакета строка должна содержать только имя модуля или пакета. Примеры включают 'mymodule' и 'xml.parsers.expat'.

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

<    >    ==
<=   >=   !=

Эти квалификаторы можно объединять, используя несколько квалификаторов, разделенных запятыми (и необязательным пробелом). В этом случае все квалификаторы должны быть выполнены; для объединения используется логическое И.

Давайте рассмотрим несколько примеров:

Теперь, когда мы можем указать зависимости, нам также нужно указать, что мы предоставляем, чтобы другие дистрибутивы могли требовать этого. Это делается с помощью ключевого аргумента provides для setup(). Значение для этого ключевого аргумента — список строк, каждая из которых содержит имя модуля или пакета Python и, необязательно, идентификатор версии. Если версия не указана, считается, что она соответствует версии дистрибутива.

Примеры:

Пакет может объявить, что он устаревает другие пакеты, используя ключевой аргумент obsoletes. Значение этого аргумента аналогично значению ключевого аргумента requires: список строк, задающих спецификаторы модулей или пакетов. Каждый спецификатор состоит из имени модуля или пакета, за которым необязательно следуют один или несколько квалификаторов версии. Квалификаторы версии указываются в скобках после имени модуля или пакета.

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

2.5. Установка скриптов

До сих пор мы работали с чистыми и нечистыми модулями Python, которые обычно не запускаются сами по себе, а импортируются скриптами.

Скрипты — это файлы, содержащие исходный код Python, предназначенные для запуска из командной строки. Скриптам не требуется Distutils для выполнения сложных действий. Единственной особенностью является то, что если первая строка скрипта начинается с #! и содержит слово «python», Distutils скорректирует первую строку, чтобы она указывала на текущее местоположение интерпретатора. По умолчанию она заменяется на текущее местоположение интерпретатора. Опция --executable (или -e) позволит явно переопределить путь к интерпретатору.

Опция scripts просто представляет собой список файлов, которые нужно обработать таким образом. Из скрипта настройки PyXML:

setup(...,
      scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
      )

2.6. Установка данных пакета

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

Данные пакета могут быть добавлены в пакеты с помощью ключевого аргумента package_data к функции setup(). Значение должно быть отображением имени пакета на список имен относительных путей, которые нужно скопировать в пакет. Пути интерпретируются как относительные к каталогу, содержащему пакет (если необходимо, используется информация из отображения package_dir); то есть ожидается, что файлы являются частью пакета в исходных каталогах. Они также могут содержать шаблоны подстановок.

Имена путей могут содержать части каталогов; все необходимые каталоги будут созданы при установке.

Например, если пакет должен содержать подкаталог с несколькими файлами данных, файлы могут быть организованы в древовидной структуре исходных каталогов так:

setup.py
src/
    mypkg/
        __init__.py
        module.py
        data/
            tables.dat
            spoons.dat
            forks.dat

Соответствующий вызов setup() может быть таким:

setup(...,
      packages=['mypkg'],
      package_dir={'mypkg': 'src/mypkg'},
      package_data={'mypkg': ['data/*.dat']},
      )

2.7. Установка дополнительных файлов

Опция data_files может быть использована для указания дополнительных файлов, необходимых для дистрибутива модуля: файлы конфигурации, каталоги сообщений, файлы данных — всё, что не подходит под предыдущие категории.

data_files указывает последовательность пар (каталог, файлы) следующим образом:

setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg'])],
     )

Каждая пара (каталог, файлы) в последовательности определяет целевой каталог и файлы для установки в нём.

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

каталог должен быть относительным путём. Он интерпретируется относительно префикса установки (Python's sys.prefix для системных установок; site.USER_BASE для пользовательских установок). Distutils допускает использование абсолютного пути установки для каталога, но это не рекомендуется, так как это несовместимо с форматом упаковки wheel. Информация о каталоге из файлы не используется для определения окончательного расположения установленного файла; используется только имя файла.

Вы можете указать опции data_files как простой последовательности файлов без указания целевого каталога, но это не рекомендуется, и команда install в этом случае выведет предупреждение. Для установки файлов данных непосредственно в целевой каталог необходимо указать пустую строку в качестве каталога.

2.8. Дополнительные метаданные

Скрипт настройки может включать дополнительные метаданные помимо имени и версии. Эта информация включает:

Примечания:

1. Эти поля обязательны.
2. Рекомендуется, чтобы версии имели вид major.minor[.patch[.sub]].
3. Должен быть указан либо автор, либо сопровождающий. Если указан сопровождающий, distutils выводит его как автора в PKG-INFO.
4. Поле long_description используется PyPI при публикации пакета для создания страницы проекта.
5. Поле license — текст, указывающий лицензию, охватывающую пакет, если лицензия не выбрана из классификаторов «Лицензия» Trove. См. поле Classifier. Обратите внимание, что существует опция дистрибуции licence, которая устарела, но все еще действует как псевдоним для license.
6. Это поле должно быть списком.
7. Список допустимых классификаторов приведен на PyPI.
8. Для обеспечения обратной совместимости это поле также принимает строку. Если вы передаете строку через запятую 'foo, bar', она будет преобразована в ['foo', 'bar']. В противном случае она будет преобразована в список из одной строки.

‘короткая строка’

Одна строка текста, не более 200 символов.

‘длинная строка’

Несколько строк простого текста в формате reStructuredText (см. https://docutils.sourceforge.io/).

‘список строк’

См. ниже.

Кодирование информации о версии само по себе является искусством. Пакеты Python обычно придерживаются формата версии major.minor[.patch][sub]. Значение «major» равно 0 для начальных, экспериментальных выпусков программного обеспечения. Оно увеличивается для релизов, представляющих значительные вехи в пакете. Значение «minor» увеличивается, когда добавляются важные новые функции в пакет. Значение «patch» увеличивается при выпуске исправлений ошибок. Дополнительная информация о версии иногда используется для указания суб-выпусков. Это «a1,a2,…,aN» (для альфа-выпусков, где функциональность и API могут изменяться), «b1,b2,…,bN» (для бета-выпусков, которые исправляют только ошибки) и «pr1,pr2,…,prN» (для окончательных предварительных релизов для тестирования). Некоторые примеры:

0.1.0

первый, экспериментальный выпуск пакета

1.0.1a2

второй альфа-выпуск первой версии исправления 1.0

classifiers должно быть указано в списке:

setup(...,
      classifiers=[
          'Development Status :: 4 - Beta',
          'Environment :: Console',
          'Environment :: Web Environment',
          'Intended Audience :: End Users/Desktop',
          'Intended Audience :: Developers',
          'Intended Audience :: System Administrators',
          'License :: OSI Approved :: Python Software Foundation License',
          'Operating System :: MacOS :: MacOS X',
          'Operating System :: Microsoft :: Windows',
          'Operating System :: POSIX',
          'Programming Language :: Python',
          'Topic :: Communications :: Email',
          'Topic :: Office/Business',
          'Topic :: Software Development :: Bug Tracking',
          ],
      )

2.9. Отладка скрипта настройки

Иногда возникают проблемы, и скрипт настройки не выполняет то, что хочет разработчик.

Distutils перехватывает любые исключения при запуске скрипта настройки и выводит простое сообщение об ошибке перед завершением скрипта. Цель такого поведения — не вводить в заблуждение администраторов, которые не очень хорошо разбираются в Python и пытаются установить пакет. Если они получат длинный стек отслеживания ошибок из глубины Distutils, они могут подумать, что пакет или установка Python сломаны, потому что они не дочитают до конца и не увидят, что это проблема с правами доступа.

С другой стороны, это не помогает разработчику найти причину сбоя. Для этого переменная среды DISTUTILS_DEBUG может быть установлена на любое значение, кроме пустой строки, и distutils будет теперь выводить подробную информацию о том, что он делает, выводить полный стек отслеживания ошибок при возникновении исключения и выводить всю командную строку при сбое внешней программы (например, компилятора C).