Написание скрипта установки¶Writing the Setup Script

Перечисление целых пакетов¶Listing whole packages

Параметр 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.)

Перечисление отдельных модулей¶Listing individual modules

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

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

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

Описание модулей расширения¶Describing extension modules

Так же как написание модулей расширения 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'])

Отношения между дистрибутивами и пакетами¶Relationships between Distributions and Packages

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

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

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

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

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

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

<    >    ==
<=   >=   !=

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

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

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

Несколько примеров:

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

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

Установка скриптов¶Installing Scripts

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

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

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

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

Установка данных пакета¶Installing Package Data

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

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

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

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

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']},
      )

Установка дополнительных файлов¶Installing Additional Files

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

Параметр data_files задаёт последовательность пар (directory, files) следующим образом:

setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg']),
                  ('/etc/init.d', ['init-script'])]
     )

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

Каждая пара (directory, files) в последовательности задает каталог установки и файлы для установки в нем. Если directory – относительный путь, он интерпретируется относительно префикса установки (sys.prefix для чисто Python-пакетов, sys.exec_prefix для пакетов, содержащих расширения). Каждый файл в files интерпретируется относительно скрипта setup.py из корня пакета исходного кода. Информация о каталоге из files не используется для определения конечного расположения устанавливаемого файла; используется только имя файла.

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

Дополнительные метаданные¶Additional meta-data

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

Примечания:

1. Эти поля обязательны.
2. Рекомендуется, чтобы версии имели формат major.minor[.patch[.sub]].
3. Должен быть указан либо автор, либо сопровождающий.
4. Эти поля не следует использовать, если пакет должен быть совместим с версиями Python до 2.2.3 или 2.3. Список доступен на сайте PyPI.

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

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

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

Многострочный простой текст в формате reStructuredText (см. http://docutils.sf.net/).

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

См. ниже.

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

0.1.0

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

1.0.1a2

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

Классификаторы указываются в виде списка Python:

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',
          ],
      )

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

# исправить distutils, если он не справляется с ключевыми словами "classifiers" или
# ключевые слова "download_url"
from sys import version
if version < '2.2.3':
    from distutils.dist import DistributionMetadata
    DistributionMetadata.classifiers = None
    DistributionMetadata.download_url = None

Отладка сценария установки¶Debugging the setup script

Иногда что-то идет не так, и скрипт установки делает не то, что хочет разработчик.

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

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