2. Написание сценария установки¶

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

Параметр packages указывает Distutils обрабатывать (создавать, распространять, устанавливать и т.д.) все модули pure Python, найденные в каждом пакете, упомянутом в списке packages. Для этого, конечно, должно быть соответствие между именами пакетов и каталогами в файловой системе. Соответствие по умолчанию является наиболее очевидным, т.е. пакет distutils находится в каталоге distutils относительно корневого каталога дистрибутива. Таким образом, когда вы говорите packages = ['foo'] в своем сценарии установки, вы обещаете, что дистрибутивы найдут файл 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'] указывает дистрибутивам на поиск lib/__init__.py и lib/bar/__init__.py. (Имейте в виду, что, хотя package_dir применяется рекурсивно, вы должны явно перечислить все пакеты в packages: дистрибутивы не будут рекурсивно сканировать ваше дерево исходных текстов в поисках любого каталога с файлом __init__.py.)

2.2. Список отдельных модулей¶

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

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

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

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

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

Все это делается с помощью другого ключевого аргумента 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, предназначенные для запуска из командной строки. Скрипты не требуют наличия дистрибутивов для выполнения чего-либо очень сложного. Единственная полезная особенность заключается в том, что если первая строка скрипта начинается с #! и содержит слово «python», то утилита Distutils настроит первую строку так, чтобы она указывала на текущее местоположение интерпретатора. По умолчанию она заменяется на текущее местоположение интерпретатора. Параметр --executable (или -e) позволит явно переопределить путь интерпретатора.

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

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

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

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

Данные пакета могут быть добавлены к пакетам с помощью ключевого слова 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'])],
     )

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

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

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

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

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

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

Записи:

1. Эти поля обязательны для заполнения.

2. Рекомендуется, чтобы версии имели вид major.minor[.patch[.sub]].

3. Должен быть указан либо автор, либо сопровождающий. Если указан сопровождающий, в distutils он указан как автор в PKG-INFO.

4. Поле long_description используется PyPI при публикации пакета для создания страницы проекта.

5. Поле license представляет собой текст, указывающий на лицензию, охватывающую пакет, если лицензия не является выборкой из классификаторов «Лицензия». Смотрите поле Classifier. Обратите внимание, что существует параметр распространения licence, который устарел, но по-прежнему используется как псевдоним для license.

6. Это поле должно быть списком.

7. Допустимые классификаторы перечислены в PyPI.

8. Для сохранения обратной совместимости это поле также принимает строку. Если вы введете строку, разделенную запятой 'foo, bar', она будет преобразована в ['foo', 'bar'], в противном случае она будет преобразована в список из одной строки.

«короткая строка»

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

«длинная строка»

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

«список строк»

Смотреть ниже.

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

0.1.0

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

1.0.1а2

второй альфа-релиз первого патча версии 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 компилятор) завершается ошибкой.