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 на python-module-numpy и, если вдруг появится необходимость, добавить 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
• 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 он в сеть не лезет.

2ldv@: возможно ли устроить так, чтобы этот пакет python-module-objects.inv пересобирался автоматически раз в неделю (с поднятием версии - на момент написания версия = 1.2.7.20100129)? И ешё: может быть, срок великоват? Можен быть, раз в 3 суток было бы лучше?

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)
* %prepare_sphinx
  эта команда настраивает окружение для работы Sphinx. Похоже, его ещё пилить
  и пилить придётся. Использовать просто: макрос нужно указать ДО первого
  обращения к функционалу Sphinx (как правило, это что-то типа
* %make -C doc ..., но главное - первой из этой серии должна выполниться
  команда %make -C doc pickle - я обычно это засовываю в сам Makefile, чтобы
  одним вызовом убить 3 зайцев: pickle, latex и html), лично я пока
  предпочитаю секцию %prep для этого макроса

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

python-module-scipy

В данный момент проводится работа по вышеприведённой схеме

В планах

• python-module-matplotlib
• python-module-gist
• python-module-fipy
• python-module-wx

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

Ссылки

• Python Policy