Python/Refactoring: различия между версиями

Версия от 17:46, 22 февраля 2010

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

Преамбула

Назрела необходимость в преобразовании некоторых модулей питона. Это не относится к маленьким модулям, там мало файлов и они порождают мало зависимостей. Речь идёт о крупных проектах, например, 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.

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

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

Постараюсь всю работу с .pickle-файлами разрулить без непосредственного
фигурирования в спеке (хотя в самом python-module-sphinx этого не сделать, да
и смысла нет). Какой именно .pickle-файл использовать, указывается в файлах
$(find ./ -name conf.py), параметр html_use_opensearch). Здесь я использовал
html_use_opensearch = 'Grammar@SPHINXREL@.pickle', где @SPHINXREL@ при помощи
sed заменял на значение макроса %sphinx_rel. Также для приведения в порядок
всего массива документации по питоновским пакетам желательно файлы
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

Документация в 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)
  Результатом является подкаталог 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-stsci

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

python-module-gist
python-module-fipy
python-module-wx

Далее уже буду работать с opencascade и free-cad. Именно после выше перечисленного, чтобы не повторять одну и ту же работу дважды.

Ссылки

Python Policy