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

Материал из ALT Linux Wiki
(python-module-sphinx: размещение pickles)
м (→‎python-module-sphinx: форматирование)
Строка 69: Строка 69:
* .pickle файл
* .pickle файл
  нужен для оргагизации процесса генерации документации у
  нужен для оргагизации процесса генерации документации у
  некоторых пакетов, в основном генерируемой пакетом python-module-sphinx. При
  некоторых пакетов, в основном генерируемой пакетом
этом самый важный файл находится вне каталога doc/*build; так, для
python-module-sphinx. При этом самый важный файл находится
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
/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
%python_sitelibdir/sphinx/pycode/Grammar2.6.4.final.0.pickle
  Для использования этого файла при сборке других пакетов данный файл должен
  Для использования этого файла при сборке других пакетов
быть доступен на запись, поэтому его необходимо скопировать внутрь дерева
данный файл должен быть доступен на запись, поэтому его
  исходников, соответственно поправив ссылки в файлах conf.py.
необходимо скопировать внутрь дерева исходников,
  соответственно поправив ссылки в файлах conf.py.


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


  Точно пока не скажу, но это может помочь обеспечить связь в смысле
  Точно пока не скажу, но это может помочь обеспечить связь в смысле

Версия от 15:15, 25 февраля 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
Добавлять это при использовании макроса %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-stsci
его в Сизифе пока нет, а также нет нескольких нужных для него пакетов, но уже
есть потребность со стороны NumPy/SciPy, так что приоритет довольно высок
  • python-module-gist
  • python-module-fipy
  • python-module-wx

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

Ссылки