Python/Refactoring

Рефакторинг модулей питона

Преамбула

Назрела необходимость в преобразовании некоторых модулей питона. Это не относится к маленьким модулям, там мало файлов и они порождают мало зависимостей. Речь идёт о крупных проектах, например, python-module-numpy, python-module-scipy, python-module-matplotlib, python-module-wx и т.п.

Устаревший Numeric

Сейчас почти все субмодули python-module-Numeric являются частью пакета python-module-numpy. Исключение составляет python2.6(arrayfns) (в NumPy он ещё сыр), являвшийся его частью, а теперь выделенный в отдельный модуль — python-module-arrayfns. На установленных модулях это сказаться не должно, но при сборке нужно учитывать: в BuildRequires заменять python-module-Numeric на libnumpy-devel и, если вдруг появится необходимость, добавить python-module-arrayfns. Здесь от меня (real@) будет полное содействие. Только заранее прошу известить, что всё будете делать сами, и тогда я Ваши пакеты трогать не буду.

python-module-numpy

Пакет разбит на несколько подпакетов:

• python-module-numpy

он тянет за собой python-module-numpy-testing, поскольку по полиси
тесты должны паковаться отдельно и с особыми названиями, а эти два пакета
связаны неразрывно.

• libnumpy

там располагаются библиотеки, на которые могут линковаться
другие библиотеки, но ставить весь python-module-numpy смысла нет.

• libnumpy-devel

это пакет для сборки зависящих пакетов. Увы, мейнтейнерам
придётся в своих спеках сделать замену в BuildRequires с python-module-numpy
на этот пакет. Также может оказаться необходимым туда же добавить пакет
python-module-numpy-tests, который может оказаться необходимым для
тестирования сборки Вашего пакета. В этом нелёгком деле я (real@) окажу
всемерную помощь, если будут запросы.

• python-module-numpy-tests

собственно тесты. Могут порождать довольно
развесистые установочные зависимости. Если будут запросы в багзиллу, и такие
пакеты можно побить на части.

• python-module-numpy-doc

документация, внедрённая внутрь %python_sitelibdir.
Частью потому, что может порождать дополнительные зависимости, частью логика
подсказывает держать документацию в отдельном пакете.

• python-module-numpy-doc-html и python-module-numpy-doc-pdf

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

• python-module-numpy-addons

дополнения, некритичные для основного пакета.
Пока отключен, нужно собрать сначала python-module-stsci, чтобы он смог
работать (помимо этого, этот пакет зависит от python-module-matplotlib и
python-module-scipy).

• python-module-numpy-pickles

пакет с файлами .pickle (см. ниже, требуется развить тему).

Кстати, не пролучится оторвать python-module-matplotlib от BuildRequires в python-module-numpy, там цикл:

• NumPy: doc/example.py:import matplotlib.pyplot as plt (boris@: эту зависимость можно и нужно поскипать. это ж example!)

real@: не example, а документация. Это BuildRequires, я документацию собираю в
хэшере, без matplotlib оно не собирается. Разумеется, рантайм-зависимости не
существует. Просто doc/example.py участвует в сборке документации. А я не хочу
ни отказываться от документации, ни кастрировать её.

• matlotlib: pyplot.py:import numpy as np

python-module-objects.inv

Пакет содержит репозиторий ("инвентарь объектов"?) для Sphinx, и если hasher или сборочница имеет доступ к интернету, в интернет без данного пакета лезут все, чья документация собирается при помощи python-module-sphinx. Чтобы этого не происходило, у python-module-sphinx в [Build]Requires прописан пакет python-module-objects.inv. Планируется еженедельное обновление этого пакета. В этом случае, думаю, еженедельное обновление будет более адекватной заменой нынешней практике, когда модули лезут в сеть при каждой сборке.

Одно исключение: при сборке самого python-module-sphinx он в сеть не лезет.

Пакет python-module-objects.inv пересобирается автоматически (благодарю viy@ за настройку робота) раз в 3 суток (с поднятием версии - на момент написания версия = 1.2.7.20100206).

python-module-sphinx

Добавлены:

• .pickle файл

нужен для оргагизации процесса генерации документации у
некоторых пакетов, в основном генерируемой пакетом
python-module-sphinx. При этом самый важный файл находится
вне каталога doc/*build; так, для python-module-sphinx файл
оказался такой:

/tmp/HASHER/chroot/usr/src/RPM/BUILD/python-module-sphinx-0.6.4/sphinx/pycode/Grammar2.6.4.final.0.pickle

и соответственно упакован в

%python_sitelibdir/sphinx/pycode/Grammar2.6.4.final.0.pickle

Для использования этого файла при сборке других пакетов
данный файл должен быть доступен на запись, поэтому его
необходимо скопировать внутрь дерева исходников,
соответственно поправив ссылки в файлах conf.py. По умолчанию
используется файл objects.inv.

Файлы .pickle в каталоге doc/*build желательно паковать в
отдельный пакет, в каталог %python_sitelibdir/%oname/pickle.
Размещение в другом каталоге крайне нежелательно.
Если есть -devel пакет, сделать в нём
Requires: python-module-%oname-pickles.
Для описания работы с файлами .pickle вне рамок генерации
документации надо будет создать отдельную страницу.

Это поможет обеспечить связь в смысле совместимости
документации пакетов друг с другом (и/или синхронизацию с
"инвентарём").

Постараюсь всю работу с .pickle-файлами разрулить без
непосредственного фигурирования в спеке (хотя в самом
python-module-sphinx этого не сделать, да и смысла нет).

Какой именно файл использовать при сборке документации,
указывается в файлах $(find ./ -name conf.py), параметр
html_use_opensearch). Здесь я использую
html_use_opensearch = 'objects.inv', но можно и
%python_sitelibdir/sphinx/pycode/Grammar2.6.4.final.0.pickle.
Также для приведения в порядок всего массива документации по
питоновским пакетам желательно файлы environment.pickle,
searchindex.pickle и globalcontext.pickle положить в каталог
doc/*build/pickle до начала генерации документации. Это
обеспечит связность документации по всему репозиторию. Вот
пример, как это сделано в NumPy (файл doc/Makefile): ищется
строка по шаблону ^pickle и после команды создания каталогов
build/pickle и build/doctrees вставляется код:

for i in environment searchindex globalcontext; do \
  cp -f /usr/lib/python@PYVER@/site-packages/sphinx/pickle/$$i.pickle \
    build/pickle; \
done

Добавлять это при использовании макроса %generate_pickles не
нужно, он делает это сам.

• Документация в PDF (python-module-sphinx-doc)

• man-страницы (python-module-sphinx)

• тесты (python-module-sphinx-tests)

• макросы (пакет rpm-macros-sphinx, вытягивается при установке python-module-sphinx):

* %sphinx_rel
  релиз непосредственно файла .pickle пакета python-module-sphinx (сейчас
  он = 2.6.4.final.0)
* %sphinx_Grammar_file
 адрес файла Sphinx Grammar
* %prepare_sphinx каталог
  эта команда настраивает окружение для работы Sphinx.
  Использовать просто: макрос нужно указать ДО первого
  обращения к функционалу Sphinx (как правило, это что-то типа
  %make -C doc ..., но главное - первой из этой серии должна
  выполниться команда %make -C doc pickle - я обычно это
  засовываю в сам Makefile, чтобы одним вызовом убить 3
  зайцев: pickle, latex и html); лично я пока предпочитаю
  секцию %prep для этого макроса
* %generate_pickles
  Генерирует pickles в пакетах, где такого функционала нет
  (настоятельно рекомендуется использовать в пакетах, у
  которых в Makefile'ах нет цели pickle: это позволит
  объединить весь разрозненный массив документации по модулям
  питона и изучать его в едином окружении (которое ещё не
  написано ;) ).
   * первый параметр - верхний каталог исходников, либо, если
     процесс установки уже прошёл,
     %buildroot%python_sitelibdir, скопировав во второй (не
     забыть после генерации удалить) conf.py
   * второй параметр - каталог с HTML файлами (из которых и
     строятся pickles)
   * третий параметр - имя модуля (например, numpy для
     python-module-numpy)
  Результатом является подкаталог pickle текущего каталога,
  готовый к упаковке

На данный момент модуль воспользуется сохранённым в python-module-objects.inv инвентарём, и никого посылать в интернет не станет.

python-module-scipy

Далее, если у подпакетов отсутствуют комментарии, семантика была раскрыта выше. В случае python-module-scipy, надеюсь, зависимым пакетам вообще ничего не грозит, если они не используют в процессе сборки тесты из этого пакета.

Модуль состоит из следующих подпакетов:

• python-module-scipy

достаточен для большинства задач

• python-module-scipy-devel

в %_includedir помещены заголовки, не входившие ранее в бинарный пакет. Может
быть, когда-нибудь и пригодится. Тянет за собой python-module-scipy-pickles

• python-module-scipy-pickles
• python-module-scipy-tests
• python-module-scipy-doc-html
• python-module-scipy-doc-pdf
• python-module-weave

дубль содержимого %python_sitelibdir/scipy/weave, но в noarch-корне каталога
модулей. Видимо, были причины устанавливать этот пакет в 2 разных места, так
что, пока не буду точно знать, что этот пакет - лишний, пусть живёт.

python-module-matplotlib

• python-module-matplotlib
• python-module-matplotlib-examples
• python-module-matplotlib-tests
• python-module-matplotlib-other-docs
• python-module-matplotlib-doc-html
• python-module-matplotlib-doc-pdf
• python-module-matplotlib-fltk
• python-module-matplotlib-qt4
• python-module-matplotlib-qt
• python-module-matplotlib-gtk
• python-module-matplotlib-wx
• python-module-matplotlib-tk
• python-module-matplotlib-pickles

python-module-pygtk_git

• python-module-pygtk_git
• python-module-pygtk_git-libglade
• python-module-pygtk_git-devel
• python-module-pygtk_git-devel-data
• python-module-pygtk_git-tests
• python-module-pygtk_git-demo
• python-module-pygtk_git-doc
• python-module-pygtk_git-pickles

python-module-wx

• python-module-wx
• python-module-wx-devel
• python-module-wx-demo
• python-module-wx-tests
• python-module-wx-docs
• python-module-wx-pickles

python-module-wx2.9

• python-module-wx2.9
• python-module-wx2.9-devel
• python-module-wx2.9-demo
• python-module-wx2.9-tests
• python-module-wx2.9-docs
• python-module-wx2.9-pickles

python-module-gist

• python-module-gist
• python-module-gist-doc
• python-module-gist-tests

python-module-fipy

• python-module-fipy
• python-module-fipy-doc
• python-module-fipy-tests
• python-module-fipy-examples

В планах

• python-module-stsci

его в Сизифе пока нет, а также нет нескольких нужных для него
пакетов, но уже есть потребность со стороны NumPy/SciPy, так
что приоритет довольно высок

Ссылки

• Python Policy