[Python] pysetup3のご紹介
python2ではsetuptoolsやdistutilsがありますが、python3では “packaging” という新しいパッケージ用ライブラリが搭載されます。
pysetup3はこのpackagingを使うためのコマンドです。これは、setuptoolsやdistutilsを使うためのコマンドがpipやeasy_installである、という関係と同じです。
まとめるとこういう関係になります。(正確にはちょっとずれていますがまあこんなものかと)
|*python3.2まで|distutils/setuptools/distribute|easy_install/pip/buildout| |*python3.3～|packaging|pysetup3|
なお、packagingはpython2.4～3.2ではdistutils2という名前でバックポートされ、サードパーティパッケージとして配布されます。
pysetup3のドキュメントはこちらです。 http://docs.python.org/dev/install/pysetup.html
使い方
pysetup3はpython3.3から標準搭載されます。python 3.3はまだリリースされていないので、使うには http://hg.python.org/cpython/ から開発版を取得してくる必要があります。あるいは、python2～3.2で使うにはhttps://bitbucket.org/tarek/distutils2/wiki/Home からソースをとってくる必要があります。なお、distutils2の場合、listコマンドが使えないなどの制限がありますのでご注意ください。
さて、pysetup3の使い方です。まずはhelpを見ます。
% pysetup3 --help
Usage: pysetup [options] action [action_options]
Actions:
run: Run one or several commands
metadata: Display the metadata of a project
install: Install a project
remove: Remove a project
search: Search for a project in the indexes
list: List installed projects
graph: Display a graph
create: Create a project
generate-setup: Generate a backward-compatible setup.py
ちなみに、distutils2ではこうなります。
Actions:
run: Run one or several commands
metadata: Display the metadata of a project
install: Install a project
remove: Remove a project
search: Search for a project
graph: Display a graph
create: Create a Project
listがないのはどういうことだって言う感じですが…
検索 (search)
ということで、まずはbuchoパッケージを検索してみます。
% pysetup3 search bucho
not implemented
%
...
えーっと。実装されてないって…
気を取り直して次行きましょう。
インストール (install)
落としてきたtar.gzを使って install してみます。
% pysetup3 install bucho-0.1.1.tar.gz
Installing from archive: '/home/prosou/shirou/bucho-0.1.1.tar.gz'
Traceback (most recent call last):
File "setup.py", line 2, in <module>
import setuptools
ImportError: No module named 'setuptools'
failed to install
あー、buchoはsetuptoolsに依存しているのですね。pysetup3 install distribute をしたらこのエラーは出なくなりましたが、代わりに
option --single-version-externally-managed not recognized
と言われてしまいました。よく分かりません…
pysetup3の作者、tarekのパッケージなら平気だと思います。
% pysetup3.3 install flake8-1.0.tar.gz
.....
% pysetup3.3 list
'flake8' 1.0 (from '/home/rudi/local/lib/python3.3/site-packages/flake8-1.0-py3.3.dist-info')
Found 1 projects installed.
うまくインストールできたようです。
なお、インストールは
- pypi * 検索はできなくてもインストールはできます。 pysetup3 install flake8としてください
- tar.gzへのURL (http://host/packages/project-1.0.tar.gz)
- setup.pyかsetup.cfgが含まれたディレクトリ
からもインストールできます。また、
% pysetup3 install project==1.0
というようにすることで、インストールするバージョンを決めることもできます。
インストール済みのパッケージリスト (list)
listで今インストールされているパッケージのリストが出ます。
% pysetup3.3 list
'flake8' 1.0 (from '/home/rudi/local/lib/python3.3/site-packages/flake8-1.0-py3.3.dist-info')
Found 1 projects installed.
情報の表示 (metadata)
パッケージの情報を得るにはmetadataを使います。
% pysetup3.3 metadata flake8
Metadata-Version:
1.1
Name:
flake8
Version:
1.0
Platform:
UNKNOWN
Supported-Platform:
Summary:
code checking using pep8 and pyflakes
Description:
======
(以下省略)
また、-fをつけることにより、表示される情報を制限することも出来ます。
% pysetup3 metadata -f name -f version flake8
Name:
flake8
Version:
1.0
インストールされているものにしか使えないようです。
グラフの表示 (graph)
% pysetup3.3 graph flake8
'flake8' 1.0
依存するパッケージのグラフを表示してくれるそうです。
アンインストール (remove)
% pysetup3.3 remove flake8
'flake8' cannot be removed.
Error: [Errno 18] Cross-device link
what? …ちょっと今回は追いませんが、これがきちんと出来るのがいいところなのに…
プロジェクトを作成する (create)
createコマンドを打つと、setup.cfgを対話型で作ってくれます。途中でyを答えると今のディレクトリをチェックして全部含めてくれますので便利です。
ちなみに、pysetupはsetup.pyではなく、setup.cfgを使うようになることに注意してください。 (このあたりはpycon 2011 JPのtarekの講演を参考にしてください。)
% pysetup3.3 create
Project name [setup]: test
Current version number [1.0.0]:
Project description summary:
> Thi is test
Author name: shirou
Author email address: rudy@example.com
Project home page: test
Do you want me to automatically build the file list with everything I
can find in the current directory? If you say no, you will have to
define them manually. (y/n): y
Do you want to set Trove classifiers? (y/n): y
Please select the project status:
0 - Planning
1 - Pre-Alpha
2 - Alpha
3 - Beta
4 - Production/Stable
5 - Mature
6 - Inactive
Status: 1
What license do you use?: BSD
Matching licenses:
1) License :: OSI Approved :: BSD License
Type the number of the license you wish to use or ? to try again:: 1
What license do you use?:
Do you want to set other trove identifiers? (y/n) [n]: n
Wrote "setup.cfg".
また、setup.pyがあると
% pysetup3 create
A legacy setup.py has been found.
Would you like to convert it to a setup.cfg? (y/n)
[y]: y
と聞いてくれます。でもsphinxを試したら ImportError: No module named ‘sphinx’ と言われてしまいました。
互換性のためにsetup.pyを作る (genearte-setup)
% generate-setup
The setup.py was generated
とすると、setup.pyが出来上がります。でも、現段階では別にディレクトリの内容を読んでくれるわけではなく、単にsetup.pyのひな形ができるだけです。
コマンド (run)
pysetup3には今まで述べてきたコマンドの他にも setup.py 相当コマンドがあります。 setup.pyが使われなくなる代わりに、今までsetup.pyで行ってきたことがここに入っているという感じですね。
% pysetup3 run --list-commands
List of available commands:
bdist: create a built (binary) distribution
bdist_dumb: create a "dumb" built distribution
bdist_wininst: create an executable installer for Windows
build: build everything needed to install
build_clib: build C/C++ libraries used by extension modules
build_ext: build C/C++ extension modules (compile/link to build
directory)
build_py: build pure Python modules (copy to build directory)
build_scripts: build scripts (copy and fix up shebang line)
check: check PEP compliance of metadata
clean: clean up temporary files from 'build' command
install_data: install platform-independent data files
install_dist: install everything from build directory
install_distinfo: create a .dist-info directory for the distribution
install_headers: install C/C++ header files
install_lib: install all modules (extensions and pure Python)
install_scripts: install scripts (Python or otherwise)
register: register a release with PyPI
sdist: create a source distribution (tarball, zip file, etc.)
test: run the project's test suite
upload: upload distribution to PyPI
upload_docs: upload HTML documentation to PyPI
まとめ
というわけで、python3.3から使えるようになるpysetupコマンドについて述べてきました。正直まだ使えないなというレベルではありますが、3.3リリースが予定されているのは来年8月ですし、これからどんどん良くなっていくと思います。
明日は初心者向けのエントリを書いてくださる @takanory さんにお願いします。
[Sphinx]reSTおよびSphinxで文章を書く際のtips
Sphinxを使って論文っぽい文章を書くときのtipsをまとめておきます。
<span class=”deco” style=”font-weight:bold;”>追記: この内容は Sphinx逆引き辞典 により詳細にして載っています。</span>
用語を書く際はreplaceを使う
.. |hoge| replace:: ほげら
こう定義しておくと次からは |hoge| とするだけで、ほげらと自動的に展開してくれます。つまり、あとからこの用語名を変えたいな、と思ったときにはこの定義のところだけを変えれば勝手に全部入れ替えてくれる、というわけです。
ただし、複数のrstファイルに分けている場合には使えないので、別のファイル(例えばdefinition.txt)に replace を書いておき、
.. include:: definition.txt
と各rstファイルの先頭に書いておきます。この時、.rstではなく.txtなど他の拡張子のファイルに書いていることに注意してください。そうしない、Sphinxがどこからも参照されてない.rstファイルがあるーって怒っちゃいます。
version 1.0以降であれば、rst_prologを使う方法もあります。rst_prologとは各rstファイルの先頭に追加するものを記載する変数です。これを利用する場合、conf.pyに以下のように書きます。
rst_prolog= u"""
.. |hoge| replace:: ほげら
"""
あるいは、includeと組み合わせて
rst_prolog= u"""
.. include:: definition.txt
"""
とか書いてもいいかもしれませんね。
図にキャプションをつける
figureを使います。figureはimageディレクティブに、キャプションなどを付け加えます。
.. figure:: ファイル名
:scale: 40%
:alt: Alternate Text (キャプションじゃないよ)
一行あけてここに書いたものがキャプションになります。
と書けばいいのですが、HTMLに書きだした場合,
<p class="caption">
となるにも関わらず、captionというCSSが定義されていないので、普通の文章と同じようになってしまいます。(shimizukawaさん、takanoryさん、ありがとうございます)
章や節に番号を振りたい
1 章、1.1節などのように番号を振りたい場合、toctreeに:numberd:を加えます。
.. toctree::
:maxdepth: 2
:numbered:
overview
design
implementation
ただし、章や節に文中から 「1.1節で述べたように」 などとはしてくれないみたいです。(後述の「表に番号を自動で振りたい」も参考のこと)
表
標準の–や+を使って書くグリッドテーブル方式は非常に書くのが大変です。 csvテーブル や Listテーブル を使った方が楽です。
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
表に番号を自動で振りたい
表に自動で番号を割り振って、文中からその番号で参照したい、ということがあります。(例: 図1では…)しかし、
を見ると、その機能はまだ実装されていないそうです。残念。
一応やる方法はあって、http://article.gmane.org/gmane.text.docutils.user/5623 によると、refロールとlabelロール、そしてlatexを直接使うそうです。ただし、ぼくの環境(TeXLive2010 on Mac)では、platex的にエラーになりました。
.. role:: ref
.. role:: label
.. raw:: latex
\newcommand*{\docutilsroleref}{\ref}
\newcommand*{\docutilsrolelabel}{\label}
.. figure:: mc.png
:width: 50
:label:`mc` Midnight Commander icon enlarged
citation
.. [CITE2011] 出典元
とどこかに書いておき、
[CITE2011]_ とか書いて参照
replace と異なり、複数のrstファイルに分散していても、そのうちの一つのrstファイルで一度定義しておけば大丈夫です。というより、replaceと同じようにincludeしてしまうと、重複して定義していると怒られてしまいます。
refer (Internal Hyperlink)
同じ文書中の他の項や節を参照するには、Internal Hyperlinkを使います。
.. _ex-hoge:
---------------
ほげほげ
---------------
このように、章や節の上に記述して定義する。
--------
他の場所
--------
ほげほげに関しては :ref:`ほげほげ<ex-hoge>` として任意のテキストで参照します。
TODO
conf.pyに
extensions = ['sphinx.ext.todo', 'とかその他の' ]
[extensions]
todo_include_todos=True
としておき、
.. todo:: ブロック図を書く
と書くと、TODOがわかりやすく表示されるようになります。
また、
.. todolist::
とすると、全部のrstファイル(というか、TOC Tree)からTODOを探してきて、一覧表示してくれます。TODOを定義したところに飛べたりしますので便利です。index.rstなど目立つところに書いておきましょう。
文章の途中に画像を埋め込む
ymotongpooさんの 文章の途中に画像を埋め込む を参考に、imageとreplaceを組み合わせます。
An example of set notation would be |comprehension|.That set notation
tells you the results you want will be all real numbers who are equal
to their own square.
.. |comprehension| image:: img/comprehension.png