Python/Refactoring
Материал из ALT Linux Wiki
Real (обсуждение | вклад) м (→python-module-sphinx: форматирование) |
(→python-module-numpy) |
||
(6 промежуточных версий не показаны.) | |||
Строка 54: | Строка 54: | ||
существует. Просто doc/example.py участвует в сборке документации. А я не хочу | существует. Просто doc/example.py участвует в сборке документации. А я не хочу | ||
ни отказываться от документации, ни кастрировать её. | ни отказываться от документации, ни кастрировать её. | ||
+ | |||
+ | а в зависимости зачем тащить? ну есть там ссылка в example.py ну и пусть будет, почему оно вдруг не собирается то 0_o | ||
+ | |||
* matlotlib: pyplot.py:import numpy as np | * matlotlib: pyplot.py:import numpy as np | ||
Строка 79: | Строка 82: | ||
данный файл должен быть доступен на запись, поэтому его | данный файл должен быть доступен на запись, поэтому его | ||
необходимо скопировать внутрь дерева исходников, | необходимо скопировать внутрь дерева исходников, | ||
- | соответственно поправив ссылки в файлах conf.py. | + | соответственно поправив ссылки в файлах conf.py. По умолчанию |
+ | используется файл objects.inv. | ||
Файлы .pickle в каталоге doc/*build желательно паковать в | Файлы .pickle в каталоге doc/*build желательно паковать в | ||
Строка 89: | Строка 93: | ||
''документации надо будет создать отдельную страницу.'' | ''документации надо будет создать отдельную страницу.'' | ||
- | + | Это поможет обеспечить связь в смысле совместимости | |
- | + | документации пакетов друг с другом (и/или синхронизацию с | |
- | + | "инвентарём"). | |
- | Постараюсь всю работу с .pickle-файлами разрулить без | + | Постараюсь всю работу с .pickle-файлами разрулить без |
- | фигурирования в спеке (хотя в самом python-module-sphinx этого не сделать, да | + | непосредственного фигурирования в спеке (хотя в самом |
- | + | python-module-sphinx этого не сделать, да и смысла нет). | |
- | + | ||
- | html_use_opensearch = ' | + | Какой именно файл использовать при сборке документации, |
- | + | указывается в файлах $(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 вставляется код: | ||
<pre> | <pre> | ||
Строка 112: | Строка 121: | ||
done | done | ||
</pre> | </pre> | ||
- | Добавлять это при использовании макроса %generate_pickles не нужно, он делает | + | Добавлять это при использовании макроса %generate_pickles не |
- | + | нужно, он делает это сам. | |
* Документация в PDF (python-module-sphinx-doc) | * Документация в PDF (python-module-sphinx-doc) | ||
Строка 127: | Строка 136: | ||
* %sphinx_Grammar_file | * %sphinx_Grammar_file | ||
адрес файла Sphinx Grammar | адрес файла Sphinx Grammar | ||
- | * %prepare_sphinx | + | * %prepare_sphinx каталог |
- | эта команда настраивает окружение для работы Sphinx. | + | эта команда настраивает окружение для работы Sphinx. |
- | + | Использовать просто: макрос нужно указать ДО первого | |
обращения к функционалу Sphinx (как правило, это что-то типа | обращения к функционалу Sphinx (как правило, это что-то типа | ||
- | %make -C doc ..., но главное - первой из этой серии должна | + | %make -C doc ..., но главное - первой из этой серии должна |
- | команда %make -C doc pickle - я обычно это засовываю в сам Makefile, чтобы | + | выполниться команда %make -C doc pickle - я обычно это |
- | + | засовываю в сам Makefile, чтобы одним вызовом убить 3 | |
- | + | зайцев: pickle, latex и html); лично я пока предпочитаю | |
+ | секцию %prep для этого макроса | ||
* %generate_pickles | * %generate_pickles | ||
- | Генерирует pickles в пакетах, где такого функционала нет | + | Генерирует pickles в пакетах, где такого функционала нет |
- | рекомендуется использовать в пакетах, у которых в Makefile'ах нет цели | + | (настоятельно рекомендуется использовать в пакетах, у |
- | + | которых в Makefile'ах нет цели pickle: это позволит | |
- | + | объединить весь разрозненный массив документации по модулям | |
- | ;) ). | + | питона и изучать его в едином окружении (которое ещё не |
- | * первый параметр - верхний каталог исходников, либо, если | + | написано ;) ). |
- | уже прошёл, %buildroot%python_sitelibdir, скопировав во второй (не | + | * первый параметр - верхний каталог исходников, либо, если |
- | после генерации удалить) conf.py | + | процесс установки уже прошёл, |
- | * второй параметр - каталог с HTML файлами (из которых и строятся pickles) | + | %buildroot%python_sitelibdir, скопировав во второй (не |
- | * третий параметр - имя модуля (например, numpy для python-module-numpy) | + | забыть после генерации удалить) conf.py |
- | Результатом является подкаталог pickle текущего каталога, готовый к упаковке | + | * второй параметр - каталог с HTML файлами (из которых и |
+ | строятся pickles) | ||
+ | * третий параметр - имя модуля (например, numpy для | ||
+ | python-module-numpy) | ||
+ | Результатом является подкаталог pickle текущего каталога, | ||
+ | готовый к упаковке | ||
На данный момент модуль воспользуется сохранённым в python-module-objects.inv инвентарём, и никого посылать в интернет не станет. | На данный момент модуль воспользуется сохранённым в python-module-objects.inv инвентарём, и никого посылать в интернет не станет. | ||
Строка 186: | Строка 201: | ||
* python-module-matplotlib-pickles | * python-module-matplotlib-pickles | ||
- | == | + | == python-module-pygtk_git == |
* python-module-pygtk_git | * python-module-pygtk_git | ||
- | * python-module- | + | * 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 | ||
+ | * python-module-gist-doc | ||
+ | * python-module-gist-tests | ||
+ | |||
+ | == python-module-fipy == | ||
+ | |||
* python-module-fipy | * python-module-fipy | ||
- | * python-module- | + | * python-module-fipy-doc |
+ | * python-module-fipy-tests | ||
+ | * python-module-fipy-examples | ||
- | + | == python-module-stsci == | |
+ | |||
+ | * python-module-stsci | ||
+ | * python-module-stsci-pickles | ||
== Ссылки == | == Ссылки == |
Текущая версия на 01:02, 9 октября 2011
Рефакторинг модулей питона
Содержание |
Преамбула
Назрела необходимость в преобразовании некоторых модулей питона. Это не относится к маленьким модулям, там мало файлов и они порождают мало зависимостей. Речь идёт о крупных проектах, например, 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 участвует в сборке документации. А я не хочу ни отказываться от документации, ни кастрировать её.
а в зависимости зачем тащить? ну есть там ссылка в example.py ну и пусть будет, почему оно вдруг не собирается то 0_o
- 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
- python-module-stsci
- python-module-stsci-pickles