| Author: | Greg Ward — 日本語訳: Python ドキュメント翻訳プロジェクト |
|---|---|
| Release: | 2.7 |
| Date: | 2011年 12月 26日 |
Abstract
このドキュメントでは、 Python モジュール配布ユーティリティ (Python Distribution Utilities, “Distutils”) について、 エンドユーザの視点に立ち、サードパーティ製のモジュールや拡張モジュールの構築やインストールによって標準の Python に機能を追加する方法について述べます。
Python の広範な標準ライブラリは、プログラミングにおける多くの要求をカバーしていますが、時には何らかの新たな機能をサードパーティ製モジュールの形で追加する必要に迫られます。自分がプログラムを書くときのサポートとして必要な場合もあるし、自分が使いたいアプリケーションがたまたま Python で書かれていて、そのサポートとして必要な場合もあるでしょう。
以前は、すでにインストール済みの Python に対して、サードパーティ製モジュールを追加するためのサポートはほとんどありませんでした。しかしPython 配布ユーティリティ (Python Distribution Utilities, 略して Distutils) が Python 2.0 から取り入れられ、状況は変わりました。
このドキュメントが主要な対象としているのは、サードパーティモジュールをインストールする必要がある人たち: 単に何らかの Python アプリケーションを稼動させたいだけのエンドユーザやシステム管理者、そしてすでに Python プログラマであって、新たな道具を自分のツールキットに加えたいと思っている人たちです。このドキュメントを読むために、 Python について知っておく必要はありません; インストールしたモジュールを調べるために Python の対話モードにちょっとだけ手を出す必要がありますが、それだけです。自作の Python モジュールを他人が使えるようにするために配布する方法を探しているのなら、 Python モジュールの配布 マニュアルを参照してください。
最も楽なのは、インストールしたいモジュール配布物の特殊なバージョンをインストールしたいプラットフォーム向けに誰かがすでに用意してくれていて、他のアプリケーションと同じようにインストールするだけであるような場合です。例えば Windows ユーザ向けには実行可能形式のインストーラ、 RPM ベースの Linux システム (Red Hat, SuSE, Mandrake その他多数) 向けには RPM パッケージ、 Debian ベースの Linux システム向けには Debian パッケージといった具合に、モジュール開発者はビルド済み配布物を作成しているかもしれません。
このような場合、自分のプラットフォームに合ったインストーラをダウンロードして、実行可能形式なら実行し、RPM なら rpm --install するといった、分かりきった作業をするだけです。 Python を起動したり、 setup スクリプトを実行する必要はなく、何もコンパイルする必要はありません — 説明書きを読む必要すら全くないかもしれません (とはいえ、説明書きを読むのはよいことですが)。
もちろん、いつもこう簡単とは限りません。自分のプラットフォーム向けのお手軽なインストーラがないモジュール配布物に興味を持つこともあるでしょう。そんな場合には、モジュールの作者やメンテナがリリースしているソース配布物から作業をはじめねばなりません。ソース配布物からのインストールは、モジュールが標準的な方法でパッケージ化されている限りさほど大変ではありません。このドキュメントの大部分は、標準的なソース配布物からのビルドとインストールに関するものです。
モジュールのソースコード配布物をダウンロードしたら、配布物が標準のやり方、すなわち Distutils のやり方に従ってパッケージされて配布されているかどうかすぐに分かります。Distutils の場合、まず配布物の名前とバージョン番号が、例えば foo-1.0.tar.gz や widget-0.9.7.zip のように、ダウンロードされたアーカイブファイルの名前にはっきりと反映されます。次に、アーカイブは同様の名前のディレクトリ、例えば foo-1.0 や widget-0.9.7 に展開されます。さらに、配布物には setup スクリプト setup.py が入っています。また、 README.txt 場合によっては README という名前のファイルも入っていて、そこには、モジュール配布物の構築とインストールは簡単で、
python setup.py install
とするだけだ、という説明が書かれているはずです。
上記の全てが当てはまるなら、ダウンロードしたものをビルドしてインストールする方法はすでに知っていることになります: 上記のコマンドを実行するだけです。非標準の方法でインストールを行ったり、ビルドプロセスをカスタマイズ行いたいのでない限り、このマニュアルは必要ありません。別の言葉で言えば、上のコマンドこそが、このマニュアルから習得すべき全てということになります。
新しい標準: Distutils 節で述べたよいうに、 Distutils を使ったモジュール配布物のビルドとインストールは、通常は単純なコマンド:
python setup.py install
で行います。
Unixでは、このコマンドをシェルプロンプトで行います; Windows では、コマンドプロンプトウィンドウ (“DOS ボックス”) を開いて、そこで行います; Mac OS X の場合、 Terminal ウィンドウを開いてシェルプロンプトを出してください。
setup コマンドは常に配布物ルートディレクトリ、すなわちモジュールのソース配布物を展開した際のトップレベルのサブディレクトリ内で実行しなければなりません。例えば、あるモジュールのソース配布物 foo-1.0.tar.gz を Unix システム上にダウンロードしたなら、通常は以下の操作を行います:
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
Windows では、おそらく foo-1.0.zip をダウンロードしているでしょう。アーカイブファイルを C:\Temp にダウンロードしたのなら、(WinZip のような) グラフィカルユーザインタフェースつきのアーカイブ操作ソフトや、 (unzip や pkunzip のような) コマンドラインツールを使ってアーカイブを展開します。次に、コマンドプロンプトウィンドウ (“DOS ボックス”) を開いて、以下を実行します:
cd c:\Temp\foo-1.0
python setup.py install
setup.py install を実行すると、一度の実行で全てのモジュールをビルドしてインストールします。段階的に作業をしたい場合 — ビルドプロセスをカスタマイズしたり、作業がうまくいかない場合に特に便利です — には、setup スクリプトに一度に一つづつ作業を行わせるようにできます。この機能は、ビルドとインストールを異なるユーザで行う場合にも便利です — 例えば、モジュール配布物をビルドしておいてシステム管理者に渡して (または、自分でスーパユーザになって) 、インストールしたくなるかもしれません.
最初のステップでは全てをビルドしておき、次のステップで全てをインストールするには、 setup スクリプトを二度起動します:
python setup.py build
python setup.py install
この作業を行ってみれば、 install コマンドを実行するとまず build コマンドを実行し、さらに — この場合には — build ディレクトリの中が全て最新の状態になっているので、 build は何も行わなくてよいと判断していることがわかるでしょう。
インターネットからダウンロードしたモジュールをインストールしたいだけなら、上のように作業を分割する機能は必要ないかもしれませんが、この機能はより進んだ使い方をする際にはとても便利です。自作の Python モジュールや拡張モジュールを配布することになれば、個々の Distutils コマンドを自分で何度も実行することになるでしょう。
上で示唆したように、 build コマンドは、インストールすべきファイルを ビルドディレクトリ (build directory) に置く働きがあります。デフォルトでは、ビルドディレクトリは配布物ルート下の build になります; システムの処理速度に強いこだわりがあったり、ソースツリーに指一本触れたくないのなら、 --build-base オプションを使ってビルドディレクトリを変更できます。例えば:
python setup.py build --build-base=/tmp/pybuild/foo-1.0
(あるいは、システム全体向け、あるいは個人用の Distutils 設定ファイルにディレクティブを書いて、永続的に設定を変えられます; Distutils 設定ファイル 節を参照してください。) 通常は必要ない作業です。
ビルドツリーのデフォルトのレイアウトは以下のようになっています:
--- build/ --- lib/
または
--- build/ --- lib.<plat>/
temp.<plat>/
<plat> は、現在の OS/ハードウェアプラットフォームと Python のバージョンを記述する短い文字列に展開されます。第一の lib ディレクトリだけの形式は、 “pure モジュール配布物” — すなわち、pure Python モジュールだけの入ったモジュール配布物 — の場合に使われます。モジュール配布物に何らかの拡張モジュール (C/C++ で書かれたモジュール) が入っている場合、第二の <plat> 付きディレクトリが二つある形式が使われます。この場合、 temp.plat ディレクトリには、コンパイル/リンク過程で生成され、実際にはインストールされない一時ファイルが収められます。どちらの場合にも、 lib (または lib.plat) ディレクトリには、最終的にインストールされることになる全ての Python モジュール (pure Python モジュールおよび拡張モジュール) が入ります。
今後、 Python スクリプト、ドキュメント、バイナリ実行可能形式、その他 Python モジュールやアプリケーションのインストール作業に必要なディレクトリが追加されるかもしれません。
build コマンドを実行した後 (明示的に実行した場合も、 install コマンドが代わりに実行してくれた場合も) は、 install コマンドの仕事は比較的単純なもの: build/lib (または build/lib.plat) の下にあるもの全ての指定したインストールディレクトリへのコピー、になります。
インストールディレクトリを選ばなかった場合 — すなわち、 setup.py install を実行しただけの場合 — には、 install コマンドはサードパーティ製 Python モジュールを置くための標準の場所にインストールを行います。この場所は、プラットフォームや、Python 自体をどのようにビルド/インストールしたかで変わります。 Unix (と、Unix をベースとしたMac OS X) では、インストールしようとするモジュール配布物が pure Python なのか、拡張モジュールを含む (“非 pure”) のかによっても異なります:
| プラットフォーム | 標準のインストール場所 | デフォルト値 | 注記 |
|---|---|---|---|
| Unix (pure) | prefix/lib/pythonX.Y/site-packages | /usr/local/lib/pythonX.Y/site-packages | (1) |
| Unix (non-pure) | exec-prefix/lib/pythonX.Y/site-packages | /usr/local/lib/pythonX.Y/site-packages | (1) |
| Windows | prefix\Lib\site-packages | C:\PythonXY\Lib\site-packages | (2) |
注記:
prefix および exec-prefix は、 Python がインストールされているディレクトリと、実行時にライブラリを探しにいく場所を表します。これらのディレクトリは、Windows では常に同じで、 Unixと Mac OS X でもほぼ常に同じです。自分の Python がどんな prefix や exec-prefix を使っているかは、Python を対話モードで起動して、単純なコマンドをいくつか入力すればわかります。 Windows では、 スタート ‣ (すべての) プログラム ‣ Python X.Y ‣ Python (command line) を選びます。 Mac OS 9 では、 PythonInterpreter を起動します。インタプリタを起動すると、プロンプトに Python コードを入力できます。例えば、作者の使っている Linux システムで、三つの Python 文を以下のように入力すると、出力から作者のシステムの prefix と exec-prefix を得られます:
Python 2.4 (#26, Aug 7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'
モジュールを標準の場所にインストールしたくない場合や、標準の場所にインストールするためのファイル権限を持っていない場合、 別の場所へのインストール 節にある、別の場所へのインストール方法の説明を読んでください。インストール先のディレクトリを大幅にカスタマイズしければ、 カスタムのインストール 節のカスタムインストールに関する説明を読んでください。
しばしば、サードパーティ製 Python モジュールをインストールするための標準の場所以外にモジュールをインストールしなければならなかったり、単にそうしたくなるときがあります。例えばUnix システムでは、標準のサードパーティ製モジュールディレクトリに対する書き込み権限を持っていないかもしれません。または、あるモジュールを、ローカルで使っている Python に標準のモジュールの一部として組み込む前にテストしてみたいと思うかもしれません。既存の配布物をアップグレードする際には特にそうでしょう: 実際にアップグレードする前に、既存のスクリプトの基本となる部分が新たなバージョンでも動作するか確認したいはずです。
Distutils の install コマンドは、別の場所へ配布物をインストールする作業を単純で苦労のない作業にするように設計されています。基本的なアイデアは、インストール先のベースディレクトリを指定しておき、 install コマンドがそのベースディレクトリ下にファイル群をインストールするための一連のディレクトリ (インストールスキーム : installation scheme) を作成するというものです。詳細はプラットフォームによって異なるので、以下の節から自分のプラットフォームに当てはまるものを読んでください。
“home スキーム” の背後にある考え方は、Python モジュールを個人用のモジュール置き場でビルドし、維持するというものです。このスキームの名前は Unixの「ホーム」ディレクトリの概念からとりました。というのも、 Unixのユーザにとって、自分のホームディレクトリを /usr/ や /usr/local/ のようにレイアウトするのはよくあることだからです。とはいえ、このスキームはどのオペレーティングシステムのユーザでも使えます。新たなモジュールのインストールは単純で、
python setup.py install --home=<dir>
のようにします。このとき、 --home オプションを使ってディレクトリを指定します。面倒臭がりの人は、単にチルダ (~) をタイプするだけでかまいません; install コマンドがチルダをホームディレクトリに展開してくれます。
python setup.py install --home=~
--home オプションは、インストールのベースディレクトリを指定します。ファイルはインストールベース下の以下のディレクトリに保存されます:
| Type of file | Installation Directory | Override option |
|---|---|---|
| pure module distribution | home/lib/python | --install-purelib |
| non-pure module distribution | home/lib/python | --install-platlib |
| scripts | home/bin | --install-scripts |
| data | home/share | --install-data |
バージョン 2.4 で変更: --home は Unixでしかサポートされていませんでした。
あるインストール済みの Python を使ってモジュールのビルド/インストールを (例えば setup スクリプトを実行して) 行いたいけれども、別のインストール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見えるようなディレクトリ構造) に、ビルドされたモジュールをインストールしたい場合には、”prefix スキーム” が便利です。そんな作業はまったくありえそうにない、と思うなら、確かにその通りです — “home スキーム” を先に説明したのもそのためです。とはいえ、prefix スキームが有用なケースは少なくとも二つあります。
まず、多くの Linux ディストリビューションは、 Python を /usr/local ではなく /usr に置いていることを考えてください。この場合は、 Python はローカルの計算機ごとのアドオン (add-on) ではなく、”システム” の一部となっているので、 /usr に置くのは全く正当なことです。しかしながら、 Python モジュールをソースコードからインストールしていると、モジュールを /usr/lib/python2.X ではなく /usr/local/lib/python2.X に置きたいと思うかもしれません。これを行うには
/usr/bin/python setup.py install --prefix=/usr/local
と指定します。
もう一つありえるのは、ネットワークファイルシステムにおいて、遠隔のディレクトリに対する読み出しと書き込みの際に違う名前を使う場合です。例えば、 /usr/local/bin/python でアクセスするような Python インタプリタは、 /usr/local/lib/python2.X からモジュールを探すでしょうが、モジュールは別の場所、例えば /mnt/@server/export/lib/python2.X にインストールしなければならないかもしれません。この場合には、
/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
のようにします。
どちらの場合も、 --prefix オプションでインストールベースディレクトリを決め、 --exec-prefix でプラットフォーム固有のファイル置き場名として使う、プラットフォーム固有インストールベースディレクトリを決めます。 (プラットフォーム固有のファイルとは、現状では単に非 pure モジュール配布物のことを意味しますが、 C ライブラリやバイナリ実行可能形式などに拡張されるかもしれません。) --exec-prefix が指定されていなければ、デフォルトの --prefix になります。ファイルは以下のようにインストールされます:
| Type of file | Installation Directory | Override option |
|---|---|---|
| pure module distribution | prefix/lib/pythonX.Y/site-packages | --install-purelib |
| non-pure module distribution | exec-prefix/lib/pythonX.Y/site-packages | --install-platlib |
| scripts | prefix/bin | --install-scripts |
| data | prefix/share | --install-data |
--prefix や --exec-prefix が実際に他のインストール済み Python の場所を指している必要はありません; 上に挙げたディレクトリがまだ存在しなければ、インストール時に作成されます。
ちなみに、prefix スキームが重要な本当の理由は、単に標準の Unix インストールが prefix スキームを使っているからです。ただし、そのときには、 --prefix や --exec-prefix は Python 自体が sys.prefix や sys.exec_prefix を使って決めます。というわけで、読者は prefix スキームを決して使うことはあるまいと思っているかもしれませんが、 python setup.py install をオプションを何もつけずに実行していれば、常に prefix スキームを使っていることになるのです。
拡張モジュールを別のインストール済み Python にインストールしても、拡張モジュールのビルド方法による影響を受けることはありません: 特に、拡張モジュールをコンパイルする際には、 setup スクリプトを実行する際に使う Python インタプリタと一緒にインストールされている Python ヘッダファイル (Python.h とその仲間たち) を使います。上で述べてきたやり方でインストールされた拡張モジュールを実行するインタプリタと、インタプリタをビルドする際に用いた別のインタプリタとの互換性を保証するのはユーザの責任です。
これを行うには、二つのインタプリタが同じバージョンの Python (ビルドが違っていたり、同じビルドのコピーということもあり得ます) であるかどうかを確かめます。(もちろん、 --prefix や --exec-prefix が別のインストール済み Python の場所すら指していなければどうにもなりません。)
Windows はユーザのホームディレクトリという概念がなく、 Windows 環境下で標準的にインストールされた Python は Unixよりも単純な構成をしているので、 Windows で追加のパッケージを別の場所に入れる場合には、伝統的に --prefix が使われてきました。
python setup.py install --prefix="\Temp\Python"
とすると、モジュールを現在のドライブの \Temp\Python ディレクトリにインストールします
インストールベースディレクトリは、 --prefix オプションだけで決まります; --exec-prefix オプションは、Windows ではサポートされていません。ファイルは以下のような構成でインストールされます:
| Type of file | Installation Directory | Override option |
|---|---|---|
| pure module distribution | prefix | --install-purelib |
| non-pure module distribution | prefix | --install-platlib |
| scripts | prefix\Scripts | --install-scripts |
| data | prefix\Data | --install-data |
たまに、 別の場所へのインストール 節で述べたような別の場所へのインストールスキームが、自分のやりたいインストール方法と違うことがあります。もしかすると、同じベースディレクトリ下にあるディレクトリのうち、一つか二つだけをいじりたかったり、インストールスキームを完全に再定義したいと思うかもしれません。どちらの場合にせよ、こうした操作では カスタムのインストールスキーム を作成することになります。
別の場所へのインストールスキームに関するこれまでの説明で、 “オーバライドするためのオプション” というコラムにお気づきかもしれません。このオプションは、カスタムのインストールスキームを定義するための手段です。各オーバライドオプションには、相対パスを指定しても、絶対パスを指定しても、インストールベースディレクトリのいずれかを明示的に指定してもかまいません。 (インストールベースディレクトリは二種類あり、それら二つは通常は同じディレクトリです — Unix の “prefix スキーム” を使っていて、 --prefix と --exec-prefix オプションを使っているときだけ異なります。)
例えば、 Unix環境でモジュール配布物をホームディレクトリにインストールしたい — とはいえ、スクリプトは ~/bin ではなく ~/scripts に置きたい — とします。ご想像の通り、スクリプトを置くディレクトリは、 --install-scripts オプションで上書きできます; この場合は相対パスで指定もでき、インストールベースディレクトリ (この場合にはホームディレクトリ) からの相対パスとして解釈されます:
python setup.py install --home=~ --install-scripts=scripts
Unix 環境での例をもう一つ紹介します: インストール済みの Python が、 /usr/local/python を prefix にしてビルドされ、インストールされていて、標準のインストールスクリプトは /usr/local/python/bin に入るようになっているとします。 /usr/local/bin に入るようにしたければ、絶対パスを --install-scripts オプションに与えて上書きすることになるでしょう:
python setup.py install --install-scripts=/usr/local/bin
(この操作を行うと、 “prefix スキーム” を使ったインストールになり、 prefix は Python インタプリタがインストールされている場所 — この場合には /usr/local/python になります。)
Windows 用の Python を管理しているのなら、サードパーティ製モジュールを prefix そのものの下ではなく、 prefix の下にあるサブディレクトリに置きたいと考えるかもしれません。この作業は、インストールディレクトリのカスタマイズとほぼ同じくらい簡単です — 覚えておかねばならないのは、モジュールには二つのタイプ、 pure モジュールと非 pure モジュール (非 pure モジュール配布物内のモジュール) があるということです。例えば以下のようにします:
python setup.py install --install-purelib=Site --install-platlib=Site
指定したインストール先ディレクトリは、 prefix からの相対です。もちろん、 prefix を .pth ファイルに入れるなどして、これらのディレクトリが Python のモジュール検索パス内に入るようにしなければなりません。 Python のモジュール検索パスを修正する方法は、 Python サーチパスの変更 節を参照してください。
インストールスキーム全体を定義したいのなら、全てのインストールディレクトリオプションを指定しなければなりません。この作業には、相対パスを使った指定を勧めます; 例えば、全ての Python モジュール関連ファイルをホームディレクトリ下の python ディレクトリの下に置き、そのホームディレクトリをマウントしている各プラットフォームごとに別のディレクトリを置きたければ、以下のようにインストールスキームを定義します:
python setup.py install --home=~ \
--install-purelib=python/lib \
--install-platlib=python/lib.$PLAT \
--install-scripts=python/scripts
--install-data=python/data
また、以下のようにも指定できます:
python setup.py install --home=~/python \
--install-purelib=lib \
--install-platlib='lib.$PLAT' \
--install-scripts=scripts
--install-data=data
$PLAT は、(必ずしも) 環境変数ではありません — この表記は、 Distutils がコマンドラインオプションの解釈と同じやり方で展開します。設定ファイルを解釈する際と同じです。
言うまでもないことですが、毎回新たなモジュール配布物をインストールする度にインストールスキーム全体の指定を行っていては面倒です。そこで、オプションは Distutils 設定ファイル (Distutils 設定ファイル 参照) にも指定できます:
[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
あるいは、以下のようにも指定できます:
[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
これら二つは、 setup スクリプトを異なるインストールベースディレクトリから実行した場合には同じには ならない ので注意してください。例えば、
python setup.py install --install-base=/tmp
とすると、最初の書き方では pure モジュールが /tmp/python/lib に入り、二番目の書き方では /tmp/lib に入ります。(二番目のケースでは、インストールベースを /tmp/python に指定しようと考えるでしょう。)
読者は、設定ファイル例で、入力値に $HOME や $PLAT を使っていることに気づいているかもしれませんね。これらは Distutils の設定変数で、環境変数を彷彿とさせます。実際、この表記が使えるプラットフォーム上では、設定ファイル中に環境変数を入れられますが、 Distutils は他にも、例えば $PLAT のようにおそらくユーザの環境中にないような変数をいくつか持っています。(そしてもちろん、 Mac OS 9 のような環境変数のないシステムでは、設定ファイル中で使える変数は Distutils が提供しているものだけです。) 詳細は Distutils 設定ファイル を参照してください。
Python インタプリタが import 文を実行するとき、インタプリタは Python コードや拡張モジュールをモジュール検索パス中から探します。検索パスのデフォルト値は、インタプリタをビルドする際に Python のバイナリ内に設定されます。検索パスは、 sys を import して、 sys.path を出力すればわかります。
$ python
Python 2.2 (#11, Oct 3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
'/usr/local/lib/python2.3/site-packages']
>>>
sys.path 内の空文字列は、現在の作業ディレクトリを表します。
ローカルでインストールされるパッケージは、 .../site-packages/ ディレクトリに入るのが決まりですが、ユーザはどこか任意のディレクトリに Python モジュールをインストールしたいと思うかもしれません。例えば、自分のサイトでは、 web サーバに関連する全てのソフトウェアを /www に置くという決まりがあるかもしれません。そこで、アドオンの Python モジュールが /www/python 置かれることになると、モジュールを import するためにはディレクトリを sys.path に追加せねばなりません。ディレクトリを検索パスに追加するには、いくつかの異なる方法が存在します。
最も手軽な方法は、パス設定ファイルをすでに Python の検索パスに含まれるディレクトリ、通常は .../site-packages/ ディレクトリに置くというものです。パス設定ファイルは拡張子が .pth で、ファイルには sys.path に追加するパスを一行に一つづつ記述しなければなりません。 (新たなパスは今の sys.path の後ろに追加されるので、追加されたディレクトリ内にあるモジュールが標準のモジュールセットを上書きすることはありません。つまり、このメカニズムを使って、標準モジュールに対する修正版のインストールはできないということです。)
パスは絶対パスでも相対パスでもよく、相対パスの場合には .pth ファイルのあるパスからの相対になります。詳しくは site モジュールを参照してください。
やや便利さには欠けますが、Python の標準ライブラリ中にある site.py ファイルを編集することでも、 sys.path を変更できます。 site.py は、 -S スイッチを与えて抑制しないかぎり、Python インタプリタが実行される際に自動的に import されます。ただし、設定するには、単に site.py を編集して、例えば以下のような二行を加えます:
import sys
sys.path.append('/www/python/')
しかしながら、(例えば 2.2 から 2.2.2 にアップグレードするときのように) 同じメジャーバージョンの Python を再インストールすると、 site.py は手持ちのバージョンで上書きされてしまいます。ファイルが変更されていることを覚えておき、インストールを行う前にコピーを忘れずとっておかねばなりません。
また、 sys.path を修正できる二つの環境変数があります。 PYTHONHOME を使うと、インストールされている Python のプレフィクスを別の値に設定できます。例えば、 PYTHONHOME を /www/python に設定すると、検索パスは ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...] といった具合になります。
PYTHONPATH を使うと、 sys.path の先頭に一連のパスを追加できます。例えば、 PYTHONPATH を /www/python:/opt/py に設定すると、検索パスは ['/www/python', '/opt/py'] から始まります。 (sys.path にディレクトリを追加するには、そのディレクトリが実在しなければなりません; site は実在しないディレクトリを除去します。)
最後に、 sys.path はただの普通の Python のリストなので、どんな Python アプリケーションもエントリを追加したり除去したりといった修正を行えます。
上で述べたように、 Distutils 設定ファイルを使えば、任意の Distutils オプションに対して個人的な設定やサイト全体の設定を記録できます。すなわち、任意のコマンドの任意のオプションを二つか三つ (プラットフォームによって異なります) の設定ファイルに保存でき、コマンドラインを解釈する前にオプションを問い合わせさせるようにできます。つまり、設定ファイルはデフォルトの値を上書きし、さらにコマンドライン上で与えた値が設定ファイルの内容を上書きするわけです。さらに、複数の設定ファイルが適用されると、”先に” 適用されたファイルに指定されていた値は “後に” 適用されたファイル内の値で上書きされます。
設定ファイルの名前と場所は、非常にわずかですがプラットフォーム間で異なります。Unix と Mac OS X では、三種類の設定ファイルは以下のようになります (処理される順に並んでいます):
| 設定ファイルのタイプ | 場所とファイル名 | 注記 |
|---|---|---|
| system | prefix/lib/pythonver/distutils/distutils.cfg | (1) |
| personal | $HOME/.pydistutils.cfg | (2) |
| local | setup.cfg | (3) |
Windows では設定ファイルは以下のようになります:
| 設定ファイルのタイプ | 場所とファイル名 | 注記 |
|---|---|---|
| system | prefix\Lib\distutils\distutils.cfg | (4) |
| personal | %HOME%\pydistutils.cfg | (5) |
| local | setup.cfg | (3) |
全てのプラットフォームにおいて、”個人の” ファイルは –no-user-cfg オプションを使って一時的に無効にすることができます。
注記:
Distutils 設定ファイルは、全て同じ構文をしています。設定ファイルはセクションでグループ分けされています。各 Distutils コマンドごとにセクションがあり、それに加えて全てのコマンドに影響するグローバルオプションを設定するための global セクションがあります。各セクションには option=value の形で、一行あたり一つのオプションを指定します。
例えば、以下は全てのコマンドに対してデフォルトでメッセージを出さないよう強制するための完全な設定ファイルです:
[global]
verbose=0
この内容のファイルがシステム全体用の設定ファイルとしてインストールされていれば、そのシステムの全てのユーザによる全ての Python モジュール配布物に対する処理に影響します。ファイルが (個人用の設定をサポートしているシステムで) 個人用の設定ファイルとしてインストールされていれば、そのユーザが処理するモジュール配布物にのみ影響します。この内容を特定のモジュール配布物の setup.cfg として使えば、その配布物だけに影響します。
以下のようにして、デフォルトの “ビルドベース” ディレクトリをオーバライドしたり、 build* コマンドが常に強制的にリビルドを行うようにもできます:
[build]
build-base=blib
force=1
この設定は、コマンドライン引数の
python setup.py build --build-base=blib --force
に対応します。ただし、後者ではコマンドライン上で build コマンドを含めて、そのコマンドを実行するよう意味しているところが違います。特定のコマンドに対するオプションを設定ファイルに含めると、このような関連付けの必要はなくなります; あるコマンドが実行されると、そのコマンドに対するオプションが適用されます。 (また、設定ファイル内からオプションを取得するような他のコマンドを実行した場合、それらのコマンドもまた設定ファイル内の対応するオプションの値を使います。)
あるコマンドに対するオプションの完全なリストは、例えば以下のように、 --help を使って調べます:
python setup.py build --help
グローバルオプションの完全なリストを得るには、コマンドを指定せずに --help オプションを使います:
python setup.py --help
“Python モジュールの配布” マニュアルの、 “リファレンスマニュアル” の節も参照してください。
Distutils は、可能なときにはいつでも、 setup.py スクリプトを実行する Python インタプリタが提供する設定情報を使おうとします。例えば、拡張モジュールをコンパイルする際には、コンパイラやリンカのフラグには Python をコンパイルした際と同じものが使われます。通常、この設定はうまくいきますが、状況が複雑になると不適切な設定になることもあります。この節では、通常の Distutils の動作をオーバライドする方法について議論します。
C や C++ で書かれた Python 拡張をコンパイルする際、しばしば特定のライブラリを使ったり、特定の種類のオブジェクトコードを生成したりする上で、コンパイラやリンカに与えるフラグをカスタマイズする必要があります。ある拡張モジュールが自分のプラットフォームではテストされていなかったり、クロスコンパイルを行わねばならない場合にはこれが当てはまります。
最も一般的なケースでは、拡張モジュールの作者はすでに拡張モジュールのコンパイルが複雑になることを見越していて、 Setup ファイルを提供して編集できるようにしています。 Setup ファイルの編集は、モジュール配布物に多くの個別の拡張モジュールがあったり、コンパイラに拡張モジュールをコンパイルさせるために細かくフラグをセットする必要があるような場合にのみ行うことになるでしょう。
Setup ファイルが存在する場合、ビルドするべき拡張モジュールのリストを得るために解釈されます。 Setup ファイルの各行には単一のモジュールを書きます。各行は以下のような構造をとります:
module ... [sourcefile ...] [cpparg ...] [library ...]
次に、各フィールドについて見てみましょう。
特定のプラットフォームにおいて、プラットフォーム上の特殊なライブラリが必要な場合、 Setup ファイルを編集して python setup.py build を実行すればライブラリを追加できます。例えば、以下の行
foo foomodule.c
で定義されたモジュールを、自分のプラットフォーム上の数学ライブラリ libm.a とリンクしなければならない場合、 Setup 内の行に -lm を追加するだけです:
foo foomodule.c -lm
コンパイラやリンカ向けの任意のスイッチオプションは、 -Xcompiler arg や -Xlinker arg オプションで与えます:
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
-Xcompiler および -Xlinker の後にくるオプションは、それぞれ適切なコマンドラインに追加されます。従って、上の例では、コンパイラには -o32 オプションが渡され、リンカには -shared が渡されます。コンパイラオプションに引数が必要な場合、複数の -Xcompiler オプションを与えます; 例えば、 -x c++ を渡すには、 Setup ファイルには -Xcompiler -x -Xcompiler c++ を渡さねばなりません。
コンパイラフラグは、環境変数 CFLAGS の設定でも与えられます。 CFLAGS が設定されていれば、 Setup ファイル内で指定されているコンパイラフラグに CFLAGS の内容が追加されます。
この小節では、 Borland C++ コンパイラのバージョン 5.5 で Distutils を使うために必要な手順について述べています。 まず、 Borland のオブジェクトファイル形式 (OMF) は、Python 公式サイトや ActiveState の Web サイトからダウンロードできるバージョンの Python が使っている形式とは違うことを知っておかねばなりません (Python は通常、 Microsoft Visual C++ でビルドされています。Microsoft Visual C++ は COFF をオブジェクトファイル形式に使います。) このため、以下のようにして、 Python のライブラリ python25.lib を Borland の形式に変換する必要があります:
coff2omf python25.lib python25_bcpp.lib
coff2omf プログラムは、 Borland コンパイラに付属しています。 python25.lib は Python インストールディレクトリの Libs ディレクトリ内にあります。拡張モジュールで他のライブラリ (zlib, ...) を使っている場合、それらのライブラリも変換しなければなりません。
変換されたファイルは、通常のライブラリと同じディレクトリに置かねばなりません。
さて、 Distutils は異なる名前を持つこれらのライブラリをどのように扱うのでしょうか? 拡張モジュールで (例えば foo という名の) ライブラリが必要な場合、 Distutils はまず _bcpp が後ろに付いたライブラリ (例えば foo_bcpp.lib) が見つかるかどうか調べ、あればそのライブラリを使います。該当するライブラリがなければ、デフォルトの名前 (foo.lib) を使います [1] 。
Borland C++ を使って Distutils に拡張モジュールをコンパイルさせるには、以下のように入力します:
python setup.py build --compiler=bcpp
Borland C++ コンパイラをデフォルトにしたいなら、自分用、またはシステム全体向けに、 Distutils の設定ファイルを書くことを検討した方がよいでしょう (Distutils 設定ファイル 節を参照してください)。
参考
この節では、 Cygwin や MinGW [2] 配布物中の GNU C/C++ コンパイラで Distutils を使うために必要な手順について述べます。 Cygwin 向けにビルドされている Python インタプリタを使っているなら、以下の手順をとらなくても Distutils はまったく問題なく動作します。
全ての拡張ライブラリが MinGW や Cygwin でビルドできるわけではありませんが、多くの場合はビルドできます。ビルドできない拡張ライブラリは、大抵C++を利用していたり Microsoft Visual Cの拡張に依存していたりします。
distutils に Cygwin を使って拡張をコンパイルさせるには次のようにタイプします。
python setup.py build --compiler=cygwin
Cygwin を no-cygwin モード [3] で使うときや MinGW を使うときは次のようにします。
python setup.py build --compiler=mingw32
これらのオプションやコンパイラをデフォルトにしたい場合、 Distutils の個人用あるいはシステム全体用の設定ファイルを書くことを検討するべきです。 (Distutils 設定ファイル を参照してください)
以下の手順は Python 2.4.1 以前と MinGW 3.0.0 (binutils-2.13.90-20030111-1) 以前を利用しているときのものです。
上記のコンパイラは、いくつかの特殊なライブラリを必要とします。この作業は Borland の C++ よりもやや複雑です。というのは、ライブラリを変換するためのプログラムが存在しないからです。 まず、 Python DLL が公開している全てのシンボルからなるリストを作成しなければなりません。 (この作業むけの良いプログラムは、 http://www.emmestech.com/software/pexports-0.43/download_pexports.html から入手できます。)
pexports python25.dll >python25.def
これで、上で得られた情報をもとに、 gcc 用の import ライブラリを作成できます。
インストールされた python25.dll の位置はインストールオプションと、 Windowsのバージョンと言語に依存します。”自分だけのため”のインストールの場合には、インストールディレクトリのルートに配置されます。共有インストールの場合にはシステムディレクトリに配置されます。
dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
出来上がったライブラリは、 python25.lib と同じディレクトリ (Python インストールディレクトリの libs ディレクトリになるはずです) に置かなければなりません。
拡張モジュールが他のライブラリ (zlib, ... ) を必要とする場合、それらのライブラリも変換しなければなりません。変換されたファイルは、それぞれ通常のライブラリが置かれているのと同じディレクトリに置かねばなりません。
参考
注記
| [1] | つまり、全ての既存の COFF ライブラリを同名の OMF ライブラリに置き換えてもかまわないということです |
| [2] | 詳しくは http://sources.redhat.com/cygwin/ や http://www.mingw.org/ を参照してください |
| [3] | このモードでは POSIX エミュレーションを利用できませんが、 cygwin1.dll も必要なくなります。 |
この文書は、Pythonドキュメント翻訳プロジェクトによる Installing Python Modules の日本語訳版です。日本語訳に対する質問や提案などがありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト
http://www.python.jp/mailman/listinfo/python-doc-jp
または、Google Project Hosting 上の Issue Tracker
http://code.google.com/p/python-doc-ja/issues/entry
までご報告ください。
この章の関数は、 C で書かれたコードをプラットフォーム間で可搬性のあるものにする上で役立つものから、C から Python モジュールを使うもの、そして関数の引数を解釈したり、 C の値から Python の値を構築するものまで、様々なユーティリティ的タスクを行います。
この PyTypeObject のインスタンスは Python の (長整数でない)整数型を表現します。これは int や types.IntType と同じオブジェクトです。
o が PyInt_Type 型か PyInt_Type 型のサブタイプであるときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
o が PyInt_Type 型で、かつ PyInt_Type 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
str の文字列値に基づいて、新たな PyIntObject または PyLongObject を返します。このとき base を基数として文字列を解釈します。 pend が NULL でなければ、 *pend は str 中で数が表現されている部分以後の先頭の文字のアドレスを指しています。 base が 0 ならば、 str の先頭の文字列に基づいて基数を決定します: もし str が '0x' または '0X' で始まっていれば、基数に 16 を使います; str が '0' で始まっていれば、基数に 8 を使います; その他の場合には基数に 10 を使います。 base が 0 でなければ、 base は 2 以上 36 以下の数でなければなりません。先頭に空白がある場合は無視されます。数字が全くない場合、 ValueError が送出されます。使用しているマシンの long int 型で表現し切れないくらい大きな数が文字列に入っており、オーバフロー警告が抑制されていれば、 PyLongObject を返します。オーバフロー警告が抑制されていなければ、 NULL を返します。
ival の値を使って新たな整数オブジェクトを生成します。
現在の実装では、 -5 から 256 までの全ての整数に対する整数オブジェクトの配列を保持するようにしており、この範囲の数を生成すると、実際には既存のオブジェクトに対する参照が返るようになっています。従って、 1 の値を変えることすら可能です。変えてしまった場合の Python の挙動は未定義です :-)
ival の値を使って新たな整数オブジェクトを生成します。値が LONG_MAX を超えている場合、長整数オブジェクトを返します。
バージョン 2.5 で追加.
ival の値を使って新たな整数オブジェクトを生成します。値が LONG_MAX を超えている場合、長整数オブジェクトを返します。
バージョン 2.5 で追加.
オブジェクトがまだ PyIntObject でなければまず型キャストを試み、次にその値を返します。エラーが発生した場合、 -1 が返されます。その時呼び出し側は、 PyErr_Occurred() を使って、エラーが発生したのか、単に値が-1だったのかを判断するべきです。
オブジェクトがまだ PyIntObject または PyLongObject でなければまず型キャストを試み、次にその値を unsigned long 型で返します。この関数はオーバフローをチェックしません。
バージョン 2.3 で追加.
オブジェクトがまだ PyIntObject または PyLongObject でなければまず型キャストを試み、次にその値を unsigned long long 型で返します。オーバフローをチェックしません。
バージョン 2.3 で追加.
オブジェクトがまだ PyIntObject でなければまず型キャストを試み、次にその値を Py_ssize_t 型で返します。
バージョン 2.5 で追加.
システムの知識に基づく、扱える最大の整数値 (システムのヘッダファイルに定義されている LONG_MAX) を返します。
整数の free list をクリアします。開放できなかった要素の数を返します。
バージョン 2.6 で追加.
以下の関数では、文字列が渡されるはずのパラメタに非文字列が渡された場合に TypeError を送出します。
ノート
これらの関数群は Python 3.x では PyBytes_* へリネームされます。移植を容易にするために、特に注釈されていない限り、 3.x で利用できる PyBytes 関数群は同等の PyString_* 関数へのエイリアスにされています。
この PyTypeObject のインスタンスは Python の文字列型を表現します; このオブジェクトは Python レイヤにおける str や types.StringType と同じです。 .
o が文字列型か文字列型のサブタイプであるときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
v を値に持つ文字列オブジェクトを返します。失敗すると NULL を返します。パラメタ v は NULL であってはなりません; NULL かどうかはチェックしません。
値が v で長さが len の新たな文字列オブジェクトを返します。失敗すると NULL を返します。 v が NULL の場合、文字列の中身は未初期化の状態になります。
バージョン 2.5 で変更: この関数は以前は len の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
C 関数 printf() 形式の format 文字列と可変個の引数をとり、書式化済みの文字列長を計算した上で、書式化を行った結果を値とする Python 文字列にして返します。可変個の引数部は C のデータ型でなくてはならず、かつ format 文字列内の書式指定文字 (format character) に一致する型でなくてはなりません。利用できる書式化文字は以下の通りです:
| 書式指定文字 | 型 | コメント |
|---|---|---|
| %% | n/a | 文字 % のリテラル。 |
| %c | int | C の整数型で表現される単一の文字。 |
| %d | int | C の printf("%d") と全く同じ。 |
| %u | unsigned int | C の printf("%u") と全く同じ。 |
| %ld | long | C の printf("%ld") と全く同じ。 |
| %lu | unsigned long | C の printf("%lu") と全く同じ。 |
| %lld | long long | C の printf("%lld") と全く同じ。 |
| %llu | unsigned long long | C の printf("%llu") と全く同じ。 |
| %zd | Py_ssize_t | C の printf("%zd") と全く同じ。 |
| %zu | size_t | C の printf("%zu") と全く同じ。 |
| %i | int | C の printf("%i") と全く同じ。 |
| %x | int | C の printf("%x") と全く同じ。 |
| %s | char* | null で終端された C の文字列。 |
| %p | void* | C ポインタの 16 進表記。 printf("%p") とほとんど同じだが、プラットフォームにおける printf の定義に関わりなく先頭にリテラル 0x が付きます。 |
識別できない書式指定文字があった場合、残りの書式文字列はそのまま出力文字列にコピーされ、残りの引数は無視されます。
ノート
“%lld” と “%llu” 書式指定文字は HAVE_LONG_LONG が定義されている時だけ利用できます。
バージョン 2.7 で変更: “%lld” と “%llu” のサポートが追加されました。
PyString_FromFormat() と同じです。ただし、こちらの関数は二つしか引数をとりません。
文字列オブジェクト string 内の文字列値の長さを返します。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyString_Size() をマクロで実装したもので、エラーチェックを行いません。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
string の中身を NUL 文字終端された表現で返します。ポインタは string オブジェクトの内部バッファを指し、バッファのコピーを指すわけではありません。 PyString_FromStringAndSize(NULL, size) を使って生成した文字列でない限り、バッファ内のデータはいかなる変更もしてはなりません。この文字列をデアロケートしてはなりません。 string が Unicode オブジェクトの場合、この関数は string のデフォルトエンコーディング版を計算し、デフォルトエンコーディング版に対して操作を行います。 string が文字列オブジェクトですらない場合、 PyString_AsString() は NULL を返して TypeError を送出します。
PyString_AsString() をマクロで実装したもので、エラーチェックを行いません。文字列オブジェクトだけをサポートします; Unicode オブジェクトを渡してはなりません。
obj の中身を NUL 文字終端された表現にして、出力用の変数 buffer と length を使って返します。
この関数は文字列オブジェクトと Unicode オブジェクトのどちらも入力として受理します。 Unicode オブジェクトの場合、オブジェクトをデフォルトエンコーディングでエンコードしたバージョン (default encoded version) を返します。 length が NULL の場合、値を返させるバッファには NUL 文字を入れてはなりません; NUL 文字が入っている場合、関数は -1 を返し、 TypeError を送出します。
buffer は obj の内部文字列バッファを参照し、バッファのコピーを参照するわけではありません。 PyString_FromStringAndSize(NULL, size) を使って生成した文字列でない限り、バッファ内のデータはいかなる変更もしてはなりません。この文字列をデアロケートしてはなりません。
string が Unicode オブジェクトの場合、この関数は string のデフォルトエンコーディング版を計算し、デフォルトエンコーディング版に対して操作を行います。 string が文字列オブジェクトですらない場合、 PyString_AsStringAndSize() は -1 を返して TypeError を送出します。
バージョン 2.5 で変更: この関数は以前は length の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します; 呼び出し側は新たな参照を所有することになります。 string の以前の値に対する参照は盗み取られます。新たな文字列を生成できなければ、 string に対する古い参照は無視され、 *string の値は NULL に設定されます; その際、適切な例外情報が設定されます。
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します。こちらのバージョンの関数は newpart への参照をデクリメントします。
“変更不能” である文字列オブジェクトをサイズ変更する手段です。新たな文字列オブジェクトを作成するときにのみ使用してください; 文字列がすでにコードの他の部分で使われているかもしれない場合には、この関数を使ってはなりません。入力する文字列オブジェクトの参照カウントが 1 でない場合、この関数を呼び出すとエラーになります。左側値には、既存の文字列オブジェクトのアドレスを渡し (このアドレスには書き込み操作が起きるかもしれません)、新たなサイズを指定します。成功した場合、 *string はサイズ変更された文字列オブジェクトを保持し、 0 が返されます; *string の値は、入力したときの値と異なっているかもしれません。文字列の再アロケーションに失敗した場合、 *string に入っていた元の文字列オブジェクトを解放し、 *string を NULL にセットし、メモリ例外をセットし、 -1 を返します。
バージョン 2.5 で変更: この関数は以前は newsize の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新たな文字列オブジェクトを format と args から生成します。 format % args と似た働きです。引数 args はタプルでなければなりません。
引数 *string をインプレースで隔離 (intern) します。引数は Python 文字列オブジェクトを指すポインタへのアドレスでなくてはなりません。 *string と等しい、すでに隔離済みの文字列が存在する場合、そのオブジェクトを *string に設定します (かつ、元の文字列オブジェクトの参照カウントをデクリメントし、すでに隔離済みの文字列オブジェクトの参照カウントをインクリメントします)。 (補足: 参照カウントについては沢山説明して来ましtが、この関数は参照カウント中立 (reference-count-neutral) と考えてください; この関数では、関数の呼び出し後にオブジェクトに対して参照の所有権を持てるのは、関数を呼び出す前にすでに所有権を持っていた場合に限ります。)
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
PyString_FromString() と PyString_InternInPlace() を組み合わせたもので、隔離済みの新たな文字列オブジェクトを返すか、同じ値を持つすでに隔離済みの文字列オブジェクトに対する新たな (“所有権を得た”) 参照を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
size からなるエンコード済みのバッファ s を encoding の名前で登録されている codec に渡してデコードし、オブジェクトを生成します。 encoding および errors は組み込み関数 unicode() に与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
文字列オブジェクトを encoding の名前で登録されている codec に渡してデコードし、Python オブジェクトを返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
size で指定されたサイズの char バッファを encoding の名前で登録されている codec に渡してエンコードし、 Python オブジェクトを返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
エンコード名 encoding で登録された codec を使って文字列オブジェクトをエンコードし、その結果を Python オブジェクトとして返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
以下のルーチン群は、 marshal モジュールと同じ形式を使った整列化オブジェクトを C コードから使えるようにします。整列化形式でデータを書き出す関数に加えて、データを読み戻す関数もあります。整列化されたデータを記録するファイルはバイナリモードで開かれていなければなりません。
数値は最小桁が先にくるように記録されます。
このモジュールでは、3つのバージョンのデータ形式をサポートしています。バージョン 0 は従来のもので、(Python 2.4 で新たに追加された) バージョン 1 は intern 化された文字列をファイル内で共有し、逆マーシャル化の時にも共有されるようにします。 (Python 2.5 で新たに追加された) バージョン2は、浮動小数点数に対してバイナリフォーマットを利用します。 PY_MARSHAL_VERSION は現在のバージョン (バージョン 2) を示します。
long 型の整数値 value を file へ整列化します。この関数は value の下桁 32 ビットを書き込むだけです; ネイティブの long 型サイズには関知しません。
バージョン 2.4 で変更: ファイル形式を示す version が追加されました.
Python オブジェクト value を file へ整列化します。
バージョン 2.4 で変更: ファイル形式を示す version が追加されました.
value の整列化表現が入った文字列オブジェクトを返します。
バージョン 2.4 で変更: ファイル形式を示す version が追加されました.
以下の関数を使うと、整列化された値を読み戻せます。
読み出し用に開かれた FILE* 内のデータストリームから、 C の long 型データを読み出して返します。この関数は、ネイティブの long のサイズに関係なく、 32 ビットの値だけを読み出せます。
読み出し用に開かれた FILE* 内のデータストリームから、 C の short 型データを読み出して返します。この関数は、ネイティブの short のサイズに関係なく、 16 ビットの値だけを読み出せます。
読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULL を返します。
読み出し用に開かれた FILE* 内のデータストリームから、 Python オブジェクトを読み出して返します。 PyMarshal_ReadObjectFromFile() と違い、この関数はファイル中に後続のオブジェクトが存在しないと仮定し、ファイルからメモリ上にファイルデータを一気にメモリにロードして、逆整列化機構がファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作できるようにします。対象のファイルから他に何も読み出さないと分かっている場合にのみ、この関数を使ってください。エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULL を返します。
string が指している len バイトの文字列バッファに納められたデータストリームから Python オブジェクトを読み出して返します。エラーが生じた場合、適切な例外 (EOFError または TypeError) を送出して NULL を返します。
バージョン 2.5 で変更: この関数は以前は len の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Python の複素数オブジェクトは、 C API 側から見ると二つの別個の型として実装されています: 一方は Python プログラムに対して公開されている Python のオブジェクトで、他方は実際の複素数値を表現する C の構造体です。 API では、これら双方を扱う関数を提供しています。
複素数の C 構造体を引数として受理したり、戻り値として返したりする関数は、ポインタ渡しを行うのではなく 値渡し を行うので注意してください。これは API 全体を通して一貫しています。
Python 複素数オブジェクトの値の部分に対応する C の構造体です。複素数オブジェクトを扱うほとんどの関数は、この型の構造体を場合に応じて入力や出力として使います。構造体は以下のように定義されています:
typedef struct {
double real;
double imag;
} Py_complex;
二つの複素数の和を C の Py_complex 型で返します。
二つの複素数の差を C の Py_complex 型で返します。
複素数 complex の符号反転 C の Py_complex 型で返します。
二つの複素数の積を C の Py_complex 型で返します。
二つの複素数の商を C の Py_complex 型で返します。
指数 exp の num 乗を C の Py_complex 型で返します。
この PyTypeObject のインスタンスは Python の複素数型を表現します。 Pythonの complex や types.ComplexType と同じオブジェクトです。
引数が PyComplexObject 型か PyComplexObject 型のサブタイプのときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
引数が PyComplexObject 型で、かつ PyComplexObject 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
C の Py_complex 型から Python の複素数値を生成します。
新たな PyComplexObject オブジェクトを real と imag から生成します。
複素数値 op から Py_complex 型を生成します。
C で実装された Python オブジェクトは、”バッファインタフェース (buffer interface)” と呼ばれる一連の関数を公開していることがあります。これらの関数は、あるオブジェクトのデータを生 (raw) のバイト列形式で公開するために使います。このオブジェクトの使い手は、バッファインタフェースを使うことで、オブジェクトをあらかじめコピーしておく必要なしに、オブジェクトのデータに直接アクセスできます。
バッファインタフェースをサポートするオブジェクトの例として、文字列型とアレイ (array) 型の二つがあります。文字列オブジェクトは、その内容をバッファインタフェースのバイト単位形式で公開しています。アレイもその内容を公開していますが、注意する必要があるのはアレイの要素は複数バイトの値になりうる、ということです。
バッファインタフェースの使い手の一例として、ファイルオブジェクトの write() メソッドがあります。バッファインタフェースを介してバイト列を公開しているオブジェクトは全て、ファイルへの書き出しができます。オブジェクトのバッファインタフェースを操作し、対象となるオブジェクトからデータを返させる PyArg_ParseTuple() には数多くのデータ書式化コードがあります。
バージョン 1.6 から、Python は Python レベルのバッファオブジェクトと、 C 言語レベルのバッファ API を提供しており、任意のビルトイン型やユーザー定義型はその文字列表現を公開することができます。しかし、両方共、幾つかの欠点のために廃止予定扱いされていて、 Python 3.0 では公式に削除され、新しい C 言語レベルのバッファ API と新しい Python レベルの memoryview という名前のオブジェクトに置き換えられています。
新しいバッファ API は Python 2.6 に逆移植されており、 memoryviews オブジェクトは Python 2.7 に逆移植されています。古いバージョンとの互換性が必要なければ、古いAPIの代わりにこれらを使うことをおすすめします。
オブジェクトのメモリの開始位置へのポインタ
メモリのトータルサイズ [byte]
バッファが読み込み専用かどうかを示す
バッファを通してアクセスできる要素の形式を指定する、 struct モジュールスタイル文法の、 NULL 終端文字列。このポインタの値が NULL なら、 "B" (符号無しバイト) として扱われます。
メモリが多次元配列を表している時の次元数。 0 の場合、 strides と suboffsets は NULL でなければなりません。
メモリが多次元配列を表しているとき、その形を示す長さ ndim の Py_ssize_t の配列。 ((*shape)[0] * ... * (*shape)[ndims-1])*itemsize は len と等しくなければならないことに気をつけてください。
各次元で次の要素を得るためにスキップするバイト数を示す、長さ ndim の Py_ssize_t の配列。
長さ ndim の Py_ssize_t の配列。 suboffset の各数値が 0 以上であるとき、その次元に格納されているのはポインタで、 suboffset の値はそのポインタの参照を解決するときに何バイトのオフセットを足すかを示しています。 suboffset に負の数が格納されているときは、参照解決が不要であること (連続したメモリブロック内に直接配置されていること)を意味しています。
次の例は、 strides も suboffsets も非NULL の時に、N次元配列からN次元インデックスで示される要素のポインタを返す関数です。
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}
これは共有メモリ上の各要素のbyte単位のサイズを格納する変数です。これは PyBuffer_SizeFromFormat() を使って計算できる値なので技術的には不要なのですが、バッファを提供する側はフォーマット文字列を解析しなくてもこの情報を知っているでしょうし、バッファを受け取る側にとっては正しく解釈するのに必要な情報です。なので、要素サイズを格納するほうが便利ですし高速です。
バッファを提供する側のオブジェクトが内部的に利用するための変数です。例えば、提供側はこの変数に整数型をキャストして、 shape, strides, suboffsets といった配列をバッファを開放するときに同時に開放するべきかどうかを管理するフラグに使うことができるでしょう。バッファを受け取る側は、この値を変更してはなりません。
obj を Py_buffer view へエクスポートします。これらの引数は NULL であってはなりません。 flag 引数は呼び出し側がどんなバッファを扱おうとしているのか、バッファ提供側がどんなバッファを返すことが許されているのかを示す、ビットフィールドです。バッファインタフェースは複雑なメモリ共有を可能にしていますが、呼び出し元はすべての複雑なバッファを扱えるとは限らず、バッファ提供側がシンプルなビューを提供できるならそれを利用したいとかもしれません。
バッファ提供側はすべての方法でメモリを共有できるとは限らず、呼び出し側に何かが不可能であることを伝えるためにエラーを発生させる必要があるかもしれません。その場合のエラーは、もしその問題を実際に引き起こしているのが別のエラーだったとしても、 BufferError でなければなりません。バッファ提供側は flag の情報を使って Py_buffer 構造体のどのフィールドへの非デフォルト値の設定を省略したり、要求されたシンプルな view を提供できない場合はエラーを発生させたりすることができます。
成功したら 0 が、エラー時には -1 が返されます。
次のテーブルは、 flags 引数が取りうる値です。
| Flag | 説明 |
|---|---|
| PyBUF_SIMPLE | これはデフォルトの flag の状態です。結果のバッファは書き込み可能かもしれませんし、不可能かもしれません。データのフォーマットは unsigned byte とします。これは “スタンドアロン” のフラグ定数です。他の定数と ‘|’ を取る必要はありません。提供側はこのような連続したバイト列のバッファを提供できない場合に、エラーを発生させるかもしれません。 |
| PyBUF_WRITABLE | 結果のバッファは書込み可能でなければなりません。書き込み不可能な場合はエラーを発生させます。 |
| PyBUF_STRIDES | この値は PyBUF_ND を含みます。バッファは strides 情報を提供しなければなりません。 (言い換えると、 strides は NULL であってはいけません。) このフラグは、呼び出し元が、要素間に隙間のある不連続な配列を扱えるときに使われます。 strides を扱うことは、自動的に shape も扱えることを要求されます。提供側は stride 形式のバッファを提供できないとき(例えば、 suboffset が必要な場合)はエラーを発生させます。 |
| PyBUF_ND | バッファは shape 情報を提供しなければなりません。メモリは C スタイルの並び (最後の次元が一番高速) だと仮定されます。提供側はこの種類の連続バッファを提供できない場合はエラーを発生させます。このフラグが指定されていな場合は shape は NULL になります。 |
| PyBUF_C_CONTIGUOUS PyBUF_F_CONTIGUOUS PyBUF_ANY_CONTIGUOUS | これらのフラグは、返されるバッファの並びを指定します。それぞれ、C並び(最後の次元が一番高速)、Fortran並び(最初の次元が一番高速), そのどちらでも、を意味します。これらのフラグは PyBUF_STRIDES を含んでおり、 strides 情報が正しく格納されていることを保証します。 |
| PyBUF_INDIRECT | このフラグは、返されるバッファが suboffsets 情報を含んでいることを示します。(suboffsets が必要無いときは NULL でもかまいません。) このフラグは、バッファ利用側が suboffsets を使って参照されている間接配列を扱えるときに利用されます。このフラグは PyBUF_STRIDES を含みます。 |
| PyBUF_FORMAT | 返されるバッファは正しい format 情報を持っていなければなりません。このフラグは、バッファ利用側が実際に格納されているデータの ‘種類’ をチェックするときに利用します。バッファ提供側は、要求された場合は常にこの情報を提供できるべきです。 format が明示的に要求されていない場合は format は NULL ('B', unsigned byte を意味する)であるべきです。 |
| PyBUF_STRIDED | (PyBUF_STRIDES | PyBUF_WRITABLE) と同じ |
| PyBUF_STRIDED_RO | (PyBUF_STRIDES) と同じ |
| PyBUF_RECORDS | (PyBUF_STRIDES | PyBUF_FORMAT | PyBUF_WRITABLE) と同じ |
| PyBUF_RECORDS_RO | (PyBUF_STRIDES | PyBUF_FORMAT) と同じ |
| PyBUF_FULL | (PyBUF_INDIRECT | PyBUF_FORMAT | PyBUF_WRITABLE) と同じ |
| PyBUF_FULL_RO | (PyBUF_INDIRECT | PyBUF_FORMAT) と同じ |
| PyBUF_CONTIG | (PyBUF_ND | PyBUF_WRITABLE) と同じ |
| PyBUF_CONTIG_RO | (PyBUF_ND) と同じ |
view バッファを開放します。バッファが利用されなくなったときに、そのメモリを開放できるようにこの関数を呼び出すべきです。
view で定義されているメモリが、 C スタイル (fortran == 'C') のときか、 Fortran スタイル (fortran == 'F') のときか、そのいずれか (fortran == 'A') であれば 1 を返します。それ以外の場合は 0 を返します。
strides 配列を、 itemsize の大きさの要素がバイト単位で連続した、 shape の形をした (fortran が 'C' なら C-style, 'F' なら Fortran-style の) 多次元配列として埋める。
バージョン 2.7 で追加.
memoryview オブジェクトは、新しい、他のオブジェクトと同じように扱える Python オブジェクトの形をした C言語レベルのバッファへのインタフェースです。
新しいバッファインタフェースを定義しているオブジェクトから memoryview オブジェクトを作ります。
buffer-info 構造体 view をラップする memoryview オブジェクトを作ります。作られた memoryview オブジェクトはバッファを所有することになるので、 view を開放してはいけません。このバッファは memoryview オブジェクトが削除されるときに解放されます。
buffer インタフェースを定義しているオブジェクトから (‘C’ か ‘F’ortran の order で) 連続したメモリチャンクへの memoryview オブジェクトを作ります。メモリが連続している場合、 memoryview オブジェクトは元のメモリを参照します。それ以外の場合、メモリはコピーされて、 memoryview オブジェクトは新しい bytes オブジェクトを参照します。
obj が memoryview オブジェクトの場合に真を返します。現在のところ、 memoryview のサブクラスの作成は許可されていません。
古いバッファインタフェースに関するより詳しい情報は、 “バッファオブジェクト構造体” 節 ( バッファオブジェクト構造体 (buffer object structure) 節) の、 PyBufferProcs の説明のところにあります。
“バッファオブジェクト” はヘッダファイル bufferobject.h の中で定義されています (このファイルは Python.h がインクルードしています)。バッファオブジェクトは、 Python プログラミングのレベルからは文字列オブジェクトと非常によく似ているように見えます: スライス、インデックス指定、結合、その他標準の文字列操作をサポートしています。しかし、バッファオブジェクトのデータは二つのデータソース: 何らかのメモリブロックか、バッファインタフェースを公開している別のオブジェクト、のいずれかに由来しています。
バッファオブジェクトは、他のオブジェクトのバッファインタフェースから Python プログラマにデータを公開する方法として便利です。バッファオブジェクトはゼロコピーなスライス機構 (zero-copy slicing mechanism) としても使われます。ブロックメモリを参照するというバッファオブジェクトの機能を使うことで、任意のデータをきわめて簡単に Python プログラマに公開できます。メモリブロックは巨大でもかまいませんし、C 拡張モジュール内の定数配列でもかまいません。また、オペレーティングシステムライブラリ側に渡す前の、操作用の生のブロックメモリでもかまいませんし、構造化されたデータをネイティブのメモリ配置形式でやりとりするためにも使えます。
Python バッファ型 (buffer type) を表現する PyTypeObject です; Python レイヤにおける buffer や types.BufferType と同じオブジェクトです。
この定数は、 PyBuffer_FromObject() や PyBuffer_FromReadWriteObject() に size パラメタとして渡します。このパラメタを渡すと、 PyBufferObject は指定された offset からバッファの終わりまでを base オブジェクトとして参照します。このパラメタを使うことで、関数の呼び出し側が base オブジェクトのサイズを調べる必要がなくなります。
引数が PyBuffer_Type 型のときに真を返します。
新たな読み出し専用バッファオブジェクトを返します。 base が読み出し専用バッファに必要なバッファプロトコルをサポートしていない場合や、厳密に一つのバッファセグメントを提供していない場合には TypeError を送出し、 offset がゼロ以下の場合には ValueError を送出します。バッファオブジェクトは base オブジェクトに対する参照を保持し、バッファオブジェクトの内容は base オブジェクトの offset から size バイトのバッファインタフェースへの参照になります。 size が Py_END_OF_BUFFER の場合、新たに作成するバッファオブジェクトの内容は base から公開されているバッファの末尾までにわたります。
バージョン 2.5 で変更: この関数は以前は offset, size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新たな書き込み可能バッファオブジェクトを返します。パラメタおよび例外は PyBuffer_FromObject() と同じです。 base オブジェクトが書き込み可能バッファに必要なバッファプロトコルを公開していない場合、 TypeError を送出します。
バージョン 2.5 で変更: この関数は以前は offset, size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
メモリ上の指定された場所から指定されたサイズのデータを読み出せる、新たな読み出し専用バッファオブジェクトを返します。この関数が返すバッファオブジェクトが存続する間、 ptr で与えられたメモリバッファがデアロケートされないようにするのは呼び出し側の責任です。 size がゼロ以下の場合には ValueError を送出します。 size には Py_END_OF_BUFFER を指定しては いけません ; 指定すると、 ValueError を送出します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyBuffer_FromMemory() に似ていますが、書き込み可能なバッファを返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size バイトのメモリバッファを独自に維持する新たな書き込み可能バッファオブジェクトを返します。 size がゼロまたは正の値でない場合、 ValueError を送出します。( PyObject_AsWriteBuffer() が返すような) メモリバッファは特に整列されていないので注意して下さい。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
オブジェクト o が数値型プロトコルを提供している場合に 1 を返し、そうでないときには偽を返します。この関数呼び出しは常に成功します。
成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。 Python の式 o1 + o2 と同じです。
成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。 Python の式 o1 - o2 と同じです。
成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。 Python の式 o1 * o2 と同じです。
成功すると o1 を o2 で除算した結果を返し, 失敗すると NULL を返します。 Python の式 o1 / o2 と同じです。
成功すると o1 を o2 で除算した切捨て値を返し、失敗すると NULL を返します。 “旧仕様の” 整数間での除算と同じです。
バージョン 2.2 で追加.
成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は “近似値” しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。
バージョン 2.2 で追加.
成功すると o1 を o2 で除算した剰余を返し、失敗すると NULL を返します。 Python の式 o1 % o2 と同じです。
組み込み関数 divmod() を参照してください。失敗すると NULL を返します。 Python の式 divmod(o1, o2) と同じです。
組み込み関数 pow() を参照してください。失敗すると NULL を返します。 Python の式 pow(o1, o2, o3) と同じです。 o3 はオプションです。 o3 を無視させたいなら、 Py_None を入れてください (o3 に NULL を渡すと、不正なメモリアクセスを引き起こすことがあります)。
成功すると o の符号反転を返し、失敗すると NULL を返します。 Python の式 -o と同じです。
成功すると o を返し、失敗すると NULL を返します。 Python の式 +o と同じです。
成功すると o の絶対値を返し、失敗すると NULL を返します。 Python の式 abs(o) と同じです。
成功すると o のビット単位反転 (bitwise negation) を返し、失敗すると NULL を返します。Python の式 ~o と同じです。
成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。 Python の式 o1 << o2 と同じです。
成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。 Python の式 o1 >> o2 と同じです。
成功すると o1 と o2 の “ビット単位論理積 (bitwise and)” を返し、失敗すると NULL を返します。 Python の式 o1 & o2 と同じです。
成功すると o1 と o2 の “ビット単位排他的論理和 (bitwise exclusive or)” を返し、失敗すると NULL を返します。 Python の式 o1 ^ o2 と同じです。
成功すると o1 と o2 の “ビット単位論理和 (bitwise or)” を返し失敗すると NULL を返します。 Python の式 o1 | o2 と同じです。
成功すると o1 と o2 を加算した結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 += o2 と同じです。
成功すると o1 から o2 を減算した結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 -= o2 と同じです。
成功すると o1 と o2 を乗算した結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 *= o2 と同じです。
成功すると o1 を o2 で除算した結果を返し, 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 /= o2 と同じです。
成功すると o1 を o2 で除算した切捨て値を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 //= o2 と同じです。
バージョン 2.2 で追加.
成功すると、数学的な o1 の o2 による除算値に対する妥当な近似 (reasonable approximation) を返し、失敗すると NULL を返します。全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は “近似値” しか表現できません。このため、戻り値も近似になります。この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。
バージョン 2.2 で追加.
成功すると o1 を o2 で除算した剰余を返し、 , 失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 %= o2 と同じです。
組み込み関数 pow() を参照してください。失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。この関数は o3 が Py_None の場合は Python 文 o1 **= o2 と同じで、それ以外の場合は pow(o1, o2, o3) の in-place 版です。 o3 を無視させたいなら、 Py_None を入れてください (o3 に NULL を渡すと、不正なメモリアクセスを引き起こすことがあります)。
成功すると o1 を o2 だけ左シフトした結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 <<= o2 と同じです。
成功すると o1 を o2 だけ右シフトした結果を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 >>= o2 と同じです。
成功すると o1 と o2 の “ビット単位論理積 (bitwise and)” を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 &= o2 と同じです。
成功すると o1 と o2 の “ビット単位排他的論理和 (bitwise exclusive or)” を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 ^= o2 と同じです。
成功すると o1 と o2 の “ビット単位論理和 (bitwise or)” を返し失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の文 o1 |= o2 と同じです。
この関数は PyObject* 型の二つの変数のアドレスを引数にとります。 *p1 と *p2 が指すオブジェクトが同じ型の場合、それぞれの参照カウントをインクリメントして 0 (成功) を返します。オブジェクトを変換して共通の数値型にできる場合、 *p1 と *p2 を変換後の値に置き換えて (参照カウントを ‘新しく’ して) 、 0 を返します。変換が不可能な場合や、その他何らかのエラーが生じた場合、 -1 (失敗) を返し、参照カウントをインクリメントしません。 PyNumber_Coerce(&o1, &o2) の呼び出しは Python 文 o1, o2 = coerce(o1, o2) と同じです。
This function is similar to PyNumber_Coerce(), except that it returns 1 when the conversion is not possible and when no error is raised. Reference counts are still not increased in this case. この関数は PyNumber_Coerce() と似ていますが、変換が失敗た場合にはエラーを発生させず、 -1 を返します。この場合、参照カウントはインクリメントされません。
成功すると o を整数に変換したものを返し、失敗すると NULL を返します。引数の値が整数の範囲外の場合、長整数を代わりに返します。 Python の式 int(o) と同じです。
成功すると o を長整数に変換したものを返し、失敗すると NULL を返します。 Python の式 long(o) と同じです。
成功すると o を浮動小数点数に変換したものを返し、失敗すると NULL を返します。 Python の式 float(o) と同じです。
o をPythonのintもしくはlong型に変換し、成功したらその値を返します。失敗したら NULL が返され、 TypeError 例外が送出されます。
バージョン 2.5 で追加.
整数 n を、 base 進数の文字列に変換し、適切であれば '0b', '0o', '0x' の基数マーカーをつけます。 base が 2, 8, 10, 16 のいずれでも無い場合、フォーマットは x を基数として 'x#num' となります。もし n が整数オブジェクトでない場合、まず PyNumber_Index() を使って変換されます。
バージョン 2.6 で追加.
o を整数として解釈可能だった場合、Py_ssize_t型の値に変換して返します。もし o がPythonのintもしくはlongに変換できたのに、Py_ssize_tへの変換が OverflowError になる場合は、 exc 引数で渡された型 (普通は IndexError か OverflowError) の例外を送出します。もし、 exc が NULL なら、例外はクリアされて、値が負の場合は PY_SSIZE_T_MIN へ、正の場合は PY_SSIZE_T_MAX へと制限されます。
バージョン 2.5 で追加.
Python では、オブジェクト型を定義する上で数多くの構造体が使われます。この節では三つの構造体とその利用方法について説明します。
全ての Python オブジェクトは、オブジェクトのメモリ内表現の先頭部分にある少数のフィールドを完全に共有しています。このフィールドは PyObject および PyVarObject 型で表現されます。 PyObject 型や PyVarObject 型もまた、他の全ての Python オブジェクトを定義する上で直接的・間接的に使われているマクロを使って定義されています。
全てのオブジェクト型はこの型を拡張したものです。この型には、あるオブジェクトに対するオブジェクトとしてのポインタを Python から扱う必要がある際に必要な情報が入っています。通常に “リリースされている” ビルドでは、この構造体にはオブジェクトの参照カウントと、オブジェクトに対応する型オブジェクトだけが入っています。
PyObject_HEAD マクロ展開で定義されているフィールドに対応します。
PyObject を拡張して、 ob_size フィールドを追加したものです。この構造体は、 長さ (length) の概念を持つオブジェクトだけに対して使います。この型が Python/C API で使われることはほとんどありません。 PyObject_VAR_HEAD マクロ展開で定義されているフィールドに対応します。
PyObject および PyVarObject の定義には以下のマクロが使われています:
PyObject 型のフィールド宣言に展開されるマクロです; 可変でない長さを持つオブジェクトを表現する新たな型を宣言する場合に使います。展開によってどのフィールドが宣言されるかは、 Py_TRACE_REFS の定義に依存します。デフォルトでは、 Py_TRACE_REFS は定義されておらず、 PyObject_HEAD は以下のコードに展開されます:
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
Py_TRACE_REFS が定義されている場合、以下のように展開されます:
PyObject *_ob_next, *_ob_prev;
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
マクロです。 PyVarObject 型のフィールド宣言に展開されるマクロです; インスタンスによって可変の長さを持つオブジェクトを表現する新たな型を宣言する場合に使います。マクロは常に以下のように展開されます:
PyObject_HEAD
Py_ssize_t ob_size;
マクロ展開結果の一部に PyObject_HEAD が含まれており、 PyObject_HEAD の展開結果は Py_TRACE_REFS の定義に依存します。
新しい PyObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。
_PyObject_EXTRA_INIT
1, type,
新しい、 ob_size フィールドを含む PyVarObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。
_PyObject_EXTRA_INIT
1, type, size,
ほとんどの Python の呼び出し可能オブジェクトを C で実装する際に用いられている関数の型です。この型の関数は二つの PyObject* 型パラメタをとり、 PyObject* 型の値を返します。戻り値を NULL にする場合、例外をセットしておかなければなりません。 NULL でない値を返す場合、戻り値は Python に関数の戻り値として公開される値として解釈されます。この型の関数は新たな参照を返さなければなりません。
拡張型のメソッドを記述する際に用いる構造体です。この構造体には 4 つのフィールドがあります:
| フィールド | C データ型 | 意味 |
|---|---|---|
| ml_name | char * | メソッド名 |
| ml_meth | PyCFunction | C 実装へのポインタ |
| ml_flags | int | 呼び出しをどのように行うかを示すフラグビット |
| ml_doc | char * | docstring の内容を指すポインタ |
ml_meth は C の関数ポインタです。関数は別の型で定義されていてもかまいませんが、常に PyObject* を返します。関数が PyFunction でない場合、メソッドテーブル内でキャストを行うようコンパイラが要求することになるでしょう。 PyCFunction では最初のパラメタが PyObject* 型であると定義していますが、固有の C 型を self オブジェクトに使う実装はよく行われています。
ml_flags フィールドはビットフィールドで、以下のフラグが入ります。個々のフラグは呼び出し規約 (calling convention) や束縛規約 (binding convention) を表します。呼び出し規約フラグでは、 METH_VARARGS および METH_KEYWORDS を組み合わせられます (ただし、 METH_KEYWORDS 単体の指定を行っても METH_VARARGS | METH_KEYWORDS と同じなので注意してください)。呼び出し規約フラグは束縛フラグと組み合わせられます。
PyCFunction 型のメソッドで典型的に使われる呼び出し規約です。関数は PyObject* 型の引数値を二つ要求します。最初の引数はメソッドの self オブジェクトです; モジュール関数の場合、これはモジュールオブジェクトです。第二のパラメタ (よく args と呼ばれます) は、全ての引数を表現するタプルオブジェクトです。パラメタは通常、 PyArg_ParseTuple() や PyArg_UnpackTuple() で処理されます。
このフラグを持つメソッドは PyCFunctionWithKeywords 型でなければなりません。 PyCFunctionWithKeywords は三つのパラメタ:self 、 args 、およびキーワード引数全てからなる辞書、を要求します。このフラグは通常 METH_VARARGS と組み合わされ、パラメタは PyArg_ParseTupleAndKeywords() で処理されます。
引数のないメソッドは、 METH_NOARGS フラグをつけた場合、必要な引数が指定されているかをチェックしなくなります。こうしたメソッドは PyCFunction 型でなくてはなりません。第一のパラメタは self になり、モジュールかオブジェクトインスタンスへの参照を保持することになります。いずれにせよ、第二のパラメタは NULL になります。
単一のオブジェクト引数だけをとるメソッドは、 PyArg_ParseTuple() を引数 "O" にして呼び出す代わりに、 METH_O フラグつきで指定できます。メソッドは PyCFunction 型で、 self パラメタと単一の引数を表現する PyObject* パラメタを伴います。
この呼び出し規約は撤廃されました。メソッドは PyCFunction 型でなければなりません。第二引数は、引数がない場合には NULL 、単一の引数の場合にはその引数オブジェクト、複数個の引数の場合には引数オブジェクトからなるタプルです。この呼び出し規約を使うと、複数個の引数の場合と、単一のタプルが唯一引数の場合を区別できなくなってしまいます。
以下の二つの定数は、呼び出し規約を示すものではなく、クラスのメソッドとして使う際の束縛方式を示すものです。モジュールに対して定義された関数で用いてはなりません。メソッドに対しては、最大で一つしかこのフラグをセットできません。
メソッドの最初の引数には、型のインスタンスではなく型オブジェクトが渡されます。このフラグは組み込み関数 classmethod() を使って生成するのと同じ クラスメソッド (class method) を生成するために使われます。
バージョン 2.3 で追加.
メソッドの最初の引数には、型のインスタンスではなく NULL が渡されます。このフラグは、 staticmethod() を使って生成するのと同じ 静的メソッド (static method) を生成するために使われます。
バージョン 2.3 で追加.
もう一つの定数は、あるメソッドを同名の別のメソッド定義と置き換えるかどうかを制御します。
メソッドを既存の定義を置き換える形でロードします。 METH_COEXIST を指定しなければ、デフォルトの設定にしたがって、定義が重複しないようスキップします。スロットラッパはメソッドテーブルよりも前にロードされるので、例えば sq_contains スロットはラップしているメソッド __contains__() を生成し、同名の PyCFunction のロードを阻止します。このフラグを定義すると、 PyCFunction はラッパオブジェクトを置き換える形でロードされ、スロットと連立します。 PyCFunctions の呼び出しはラッパオブジェクトの呼び出しよりも最適化されているので、こうした仕様が便利になります。
バージョン 2.4 で追加.
type の C 構造体のメンバとして格納されている、ある型の属性を表す構造体です。この構造体のフィールドは以下のとおりです:
| フィールド | C の型 | 意味 |
|---|---|---|
| name | char * | メンバ名 |
| type | int | C 構造体の中のメンバの型 |
| offset | Py_ssize_t | そのメンバの type object 構造体中の場所の offset バイト数 |
| flags | int | フィールドが読み込み専用か書込み可能なのかを示すビットフラグ |
| doc | char * | docstring の内容へのポインタ |
type はたくさんのCの型を意味する T_ マクロのうちの1つです。メンバが Python からアクセスされるとき、そのメンバは対応する Python の型に変換されます。
| マクロ名 | Cの型 |
|---|---|
| T_SHORT | short |
| T_INT | int |
| T_LONG | long |
| T_FLOAT | float |
| T_DOUBLE | double |
| T_STRING | char * |
| T_OBJECT | PyObject * |
| T_OBJECT_EX | PyObject * |
| T_CHAR | char |
| T_BYTE | char |
| T_UBYTE | unsigned char |
| T_UINT | unsigned int |
| T_USHORT | unsigned short |
| T_ULONG | unsigned long |
| T_BOOL | char |
| T_LONGLONG | long long |
| T_ULONGLONG | unsigned long long |
| T_PYSSIZET | Py_ssize_t |
T_OBJECT と T_OBJECT_EX については、 T_OBJECT がメンバが NULL だったときに None を返すのに対し、 T_OBJECT_EX は AttributeError を発生させる点が異なります。 T_OBJECT_EX は属性に対する del 文をより正しくあつかうので、できれば T_OBJECT よりも T_OBJECT_EX を使ってください。
flags には読み書きアクセス可能なら 0 で、読み込み専用なら READONLY を設定します。 type に T_STRING を使うと、強制的に READONLY 扱いになります。 T_OBJECT and T_OBJECT_EX メンバだけが del 可能です。 (NULL が代入されます).
C で実装された拡張型の束縛メソッドオブジェクトを返します。 PyObject_GenericGetAttr() 関数を使わない tp_getattro や tp_getattr ハンドラを実装する際に便利です。
この関数は下で述べる PyImport_ImportModuleEx() を単純化したインタフェースで、 globals および locals 引数を NULL のままにし、 level を 0 にしたものです。 name 引数にドットが含まれる場合 (あるパッケージのサブモジュールを指定している場合)、 fromlist 引数がリスト ['*'] に追加され、戻り値がモジュールを含むトップレベルパッケージではなく名前つきモジュール (named module) になるようにします。 (残念ながらこのやり方には、 name が実際にはサブモジュールでなくサブパッケージを指定している場合、パッケージの __all__ 変数に指定されているサブモジュールがロードされてしまうという副作用があります。) import されたモジュールへの新たな参照を返します。失敗した場合には例外をセットし、 NULL を返します。 Python 2.4 より前のバージョンでは、失敗した場合でもモジュールは生成されていることがあります — sys.modules を使って調べてください。 Python 2.4 以降では、 import に失敗したモジュールは sys.modules に残りません。
バージョン 2.4 で変更: import に失敗した場合、不完全なモジュールを除去するようになりました。
バージョン 2.6 で変更: 常に、絶対 import を使うようになりました。
このバージョンの PyImport_ImportModule() はブロックしません。関数を実行するために他のモジュールをインポートするC関数から使われることを意図しています。インポート処理は他のスレッドがインポートロックを持っている場合はブロックします。この関数はブロックしません。まず sys.modules からモジュールのフェッチを試み、失敗したら、ロックが取られていなければ PyImport_ImportModule() を実行します。ロックが取られていた場合は ImportError を発生させます。
バージョン 2.6 で追加.
モジュールを import します。モジュールの import については組み込みの Python 関数 __import__() を読むとよく分かります。というのも、標準の __import__() はこの関数を直接呼び出しているからです。
戻り値は import されたモジュールかトップレベルパッケージへの新たな参照になります。失敗した場合には例外をセットし、 NULL を返します (Python 2.4 よりも前のバージョンでは、モジュールは生成されている場合があります) __import__() と同じく、パッケージに対してサブモジュールを要求した場合の戻り値は通常、空でない fromlist を指定しない限りトップレベルパッケージになります。
バージョン 2.4 で変更: import に失敗した場合、不完全なモジュールを除去するようになりました。
バージョン 2.6 で変更: この関数は PyImport_ImportModuleLevel() のエイリアスです。 level には相対インポートを意味する -1 が渡されます。
モジュールをインポートします。このモジュールの動作については、Python ビルトイン関数の __import__() でよく説明されています。 __import__() は直接この関数を実行します。
戻り値は、インポートされたモジュールかトップレベルパッケージへの新しい参照か、失敗した場合は例外を設定して NULL を返します。 __import__() と同じように、パッケージのサブモジュールが要求されたときは、空でない fromlist を渡された時以外は、トップレベルのパッケージを返します。
バージョン 2.5 で追加.
現在の “import フック関数” を呼び出すための高水準のインタフェースです。この関数は現在のグローバル変数辞書内の __builtins__ から __import__() 関数を呼び出します。すなわち、現在の環境にインストールされている import フック、例えば rexec や ihooks を使って import を行います。
バージョン 2.6 で変更: 常に、絶対importを使うようになりました。
モジュールを再ロード (reload) します。モジュールの再ロードについては組み込みの Python 関数 reload() を読むとよく分かります。というのも、標準の reload() はこの関数を直接呼び出しているからです。戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照になります。失敗した場合には例外をセットし、 NULL を返します (その場合でも、モジュールは生成されている場合があります)
モジュール名に対応するモジュールオブジェクトを返します。 name 引数は package.module の形式でもかまいません。まずモジュール辞書に該当するモジュールがあるかどうか調べ、なければ新たなモジュールを生成してモジュール辞書に挿入します。失敗した場合には例外をセットして NULL を返します。
ノート
この関数はモジュールの import やロードを行いません; モジュールがまだロードされていなければ、空のモジュールオブジェクトを得ることになります。 PyImport_ImportModule() やその別形式を使ってモジュールを import してください。ドット名表記で指定した name が存在しない場合、パッケージ構造は作成されません。
モジュール名 (package.module 形式でもかまいません) および Python のバイトコードファイルや組み込み関数 compile() で得られたコードオブジェクトを元にモジュールをロードします。モジュールオブジェクトへの新たな参照を返します。失敗した場合には例外をセットし、 NULL を返します。Python 2.4 以前では、失敗した場合でもモジュールは生成されていることがありました。 Python 2.4 以降では、たとえ PyImport_ExecCodeModule() の処理に入った時に name が sys.modules に入っていたとしても、 import に失敗したモジュールは sys.modules に残りません。初期化の不完全なモジュールを sys.modules に残すのは危険であり、そのようなモジュールを import するコードにとっては、モジュールの状態がわからない (モジュール作者の意図から外れた壊れた状態かもしれない) からです。
モジュールの __file__ 属性が、コードオブジェクトの co_filename に設定されます。
この関数は、すでに import されているモジュールの場合には再ロードを行います。意図的にモジュールの再ロードを行う方法は PyImport_ReloadModule() を参照してください。
name が package.module 形式のドット名表記であった場合、まだ作成されていないパッケージ構造はその作成されないままになります。
バージョン 2.4 で変更: エラーが発生した場合に name を sys.modules から除去するようになりました。
PyImport_ExecCodeModule() に似ていますが、 pathname が NULL で無い場合、モジュールオブジェクトの __file__ 属性に設定します。
Python バイトコードファイル (いわゆる .pyc および .pyo ファイル) のマジックナンバを返します。マジックナンバはバイトコードファイルの先頭 4 バイトにリトルエンディアン整列で配置されています。
モジュール管理のための辞書 (いわゆる sys.modules )を返します。この辞書はインタプリタごとに一つだけある変数なので注意してください。
sys.path/pkg.__path__ の要素 path の、 importer オブジェクトを返します。可能なら、 sys.path_importer_cache からフェッチします。まだキャッシュされていない場合、そのパスを扱える hook が見つかるまで sys.path_hooks を巡回します。 hook が見つからない場合、 None を返します。この場合、呼び出し元はビルトインの import 機構にフォールバックします。結果は sys.path_importer_cache にキャッシュされます。 importer オブジェクトへの新しい参照を返します。
バージョン 2.6 で追加.
import 機構を初期化します。内部使用だけのための関数です。
モジュールテーブルを空にします。内部使用だけのための関数です。
import 機構を終了処理します。内部使用だけのための関数です。
name という名前のフリーズ (freeze) されたモジュールをロードします。成功すると 1 を、モジュールが見つからなかった場合には 0 を、初期化が失敗した場合には例外をセットして -1 を返します。ロードに成功したモジュールにアクセスするには PyImport_ImportModule() を使ってください。 (Note この関数名はいささか誤称めいています — この関数はすでに import 済みのモジュールをリロードしてしまいます。)
freeze ユーティリティが生成するようなフリーズ化モジュールデスクリプタの構造体型定義です。 (Python ソース配布物の Tools/freeze/ を参照してください) この構造体の定義は Include/import.h にあり、以下のようになっています:
struct _frozen {
char *name;
unsigned char *code;
int size;
};
このポインタは struct _frozen のレコードからなり、終端の要素のメンバが NULL かゼロになっているような配列を指すよう初期化されます。フリーズされたモジュールを import するとき、このテーブルを検索します。サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの集合を提供するようにできます。
既存の組み込みモジュールテーブルに単一のモジュールを追加します。この関数は利便性を目的とした PyImport_ExtendInittab() のラッパ関数で、テーブルが拡張できないときには -1 を返します。新たなモジュールは name で import でき、最初に import を試みた際に呼び出される関数として initfunc を使います。 Py_Initialize() よりも前に呼び出さねばなりません。
組み込みモジュールリスト内の一つのエントリを記述している構造体です。リスト内の各構造体には、インタプリタ内に組み込まれているモジュールの名前と初期化関数が指定されています。 Python を埋め込むようなプログラムは、この構造体の配列と PyImport_ExtendInittab() を組み合わせて、追加の組み込みモジュールを提供できます。構造体は Include/import.h で以下のように定義されています:
struct _inittab {
char *name;
void (*initfunc)(void);
};
組み込みモジュールのテーブルに一群のモジュールを追加します。配列 newtab は name フィールドが NULL になっているセンチネル (sentinel) エントリで終端されていなければなりません; センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。成功すると 0 を、内部テーブルを拡張するのに十分なメモリを確保できなかった場合には -1 を返します。操作が失敗した場合、モジュールは一切内部テーブルに追加されません。 Py_Initialize() よりも前に呼び出さねばなりません。
新スタイルの型を定義する構造体: PyTypeObject 構造体は、おそらく Python オブジェクトシステムの中で最も重要な構造体の1つでしょう。型オブジェクトは PyObject_*() 系や PyType_*() 系の関数で扱えますが、ほとんどの Python アプリケーションにとって、さして面白みのある機能を提供しません。型オブジェクトはオブジェクトがどのように振舞うかを決める基盤ですから、インタプリタ自体や新たな型を定義する拡張モジュールでは非常に重要な存在です。
型オブジェクトは標準の型 (standard type) に比べるとかなり大きな構造体です。各型オブジェクトは多くの値を保持しており、そのほとんどは C 関数へのポインタで、それぞれの関数はその型の機能の小さい部分を実装しています。この節では、型オブジェクトの各フィールドについて詳細を説明します。各フィールドは、構造体内で出現する順番に説明されています。
Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, cmpfunc, reprfunc, hashfunc
PyTypeObject の構造体定義は Include/object.h で見つけられるはずです。参照の手間を省くために、ここでは定義を繰り返します:
typedef struct _typeobject {
PyObject_VAR_HEAD
char *tp_name; /* For printing, in format "<module>.<name>" */
int tp_basicsize, tp_itemsize; /* For allocation */
/* Methods to implement standard operations */
destructor tp_dealloc;
printfunc tp_print;
getattrfunc tp_getattr;
setattrfunc tp_setattr;
cmpfunc tp_compare;
reprfunc tp_repr;
/* Method suites for standard classes */
PyNumberMethods *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods *tp_as_mapping;
/* More standard operations (here for binary compatibility) */
hashfunc tp_hash;
ternaryfunc tp_call;
reprfunc tp_str;
getattrofunc tp_getattro;
setattrofunc tp_setattro;
/* Functions to access object as input/output buffer */
PyBufferProcs *tp_as_buffer;
/* Flags to define presence of optional/expanded features */
long tp_flags;
char *tp_doc; /* Documentation string */
/* Assigned meaning in release 2.0 */
/* call function for all accessible objects */
traverseproc tp_traverse;
/* delete references to contained objects */
inquiry tp_clear;
/* Assigned meaning in release 2.1 */
/* rich comparisons */
richcmpfunc tp_richcompare;
/* weak reference enabler */
long tp_weaklistoffset;
/* Added in release 2.2 */
/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;
/* Attribute descriptor and subclassing stuff */
struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
struct _typeobject *tp_base;
PyObject *tp_dict;
descrgetfunc tp_descr_get;
descrsetfunc tp_descr_set;
long tp_dictoffset;
initproc tp_init;
allocfunc tp_alloc;
newfunc tp_new;
freefunc tp_free; /* Low-level free-memory routine */
inquiry tp_is_gc; /* For PyObject_IS_GC */
PyObject *tp_bases;
PyObject *tp_mro; /* method resolution order */
PyObject *tp_cache;
PyObject *tp_subclasses;
PyObject *tp_weaklist;
} PyTypeObject;
型オブジェクト構造体は PyVarObject 構造体を拡張したものです。 ob_size フィールドは、(通常 class 文が呼び出す type_new() で生成される) 動的な型に使います。 PyType_Type (メタタイプ) は tp_itemsize を初期化するので注意してください。すなわち、インスタンス (つまり型オブジェクト) には ob_size フィールドがなければ なりません 。
これらのフィールドはマクロ Py_TRACE_REFS が定義されている場合のみ存在します。 PyObject_HEAD_INIT マクロを使うと、フィールドを NULL に初期化します。静的にメモリ確保されているオブジェクトでは、これらのフィールドは常に NULL のままです。動的にメモリ確保されるオブジェクトの場合、これら二つのフィールドは、ヒープ上の 全ての 存続中のオブジェクトからなる二重リンクリストでオブジェクトをリンクする際に使われます。このことは様々なデバッグ目的に利用できます; 現状では、環境変数 PYTHONDUMPREFS が設定されているときに、プログラムの実行終了時点で存続しているオブジェクトを出力するのが唯一の用例です。
サブタイプはこのフィールドを継承しません。
型オブジェクトの参照カウントで、 PyObject_HEAD_INIT はこの値を 1 に初期化します。静的にメモリ確保された型オブジェクトでは、型のインスタンス (ob_type が該当する型を指しているオブジェクト) は参照をカウントする対象には なりません 。動的にメモリ確保される型オブジェクトの場合、インスタンスは参照カウントの対象に なります 。
サブタイプはこのフィールドを継承しません。
バージョン 2.5 で変更: このフィールドは以前は int でした。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
型自体の型、別の言い方をするとメタタイプです。 PyObject_HEAD_INIT マクロで初期化され、通常は &PyType_Type になります。しかし、(少なくとも) Windows で利用できる動的ロード可能な拡張モジュールでは、コンパイラは有効な初期化ではないと文句をつけます。そこで、ならわしとして、 PyObject_HEAD_INIT には NULL を渡して初期化しておき、他の操作を行う前にモジュールの初期化関数で明示的にこのフィールドを初期化することになっています。この操作は以下のように行います:
Foo_Type.ob_type = &PyType_Type;
上の操作は、該当する型のいかなるインスタンス生成よりも前にしておかねばなりません。 PyType_Ready() は ob_type が NULL かどうか調べ、 NULL の場合には初期化します: Python 2.2 では、 &PyType_Type にセットします; in Python 2.2.1 およびそれ以降では基底クラスの ob_type フィールドに初期化します。 ob_type が非ゼロの場合、 PyType_Ready() はこのフィールドを変更しません。
Python 2.2 では、サブタイプはこのフィールドを継承しません。 2.2.1 と 2.3 以降では、サブタイプはこのフィールドを継承します。
静的にメモリ確保されている型オブジェクトの場合、このフィールドはゼロに初期化されます。動的にメモリ確保されている型オブジェクトの場合、このフィールドは内部使用される特殊な意味を持ちます。
サブタイプはこのフィールドを継承しません。
型の名前が入っている NUL 終端された文字列へのポインタです。モジュールのグローバル変数としてアクセスできる型の場合、この文字列は完全なモジュール名、ドット、そして型の名前と続く文字列になります; 組み込み型の場合、ただの型の名前です。モジュールがあるパッケージのサブモジュールの場合、完全なパッケージ名が完全なモジュール名の一部になっています。例えば、パッケージ P 内のサブモジュール Q に入っているモジュール M 内で定義されている T は、 tp_name を "P.Q.M.T" に初期化します。
動的にメモリ確保される型オブジェクトの場合、このフィールドは単に型の名前になり、モジュール名は型の辞書内でキー '__module__' に対する値として明示的に保存されます。
静的にメモリ確保される型オブジェクトの場合、 tp_name フィールドにはドットが入っているはずです。最後のドットよりも前にある部分文字列全体は __module__ 属性として、またドットよりも後ろにある部分は __name__ 属性としてアクセスできます。
ドットが入っていない場合、 tp_name フィールドの内容全てが __name__ 属性になり、 __module__ 属性は (前述のように型の辞書内で明示的にセットしないかぎり) 未定義になります。このため、こうした型オブジェクトは pickle 化できないことになります。
サブタイプはこのフィールドを継承しません。
これらのフィールドは、型インスタンスのバイトサイズを計算できるようにします。
型には二つの種類があります: 固定長インスタンスの型は、 tp_itemsize フィールドがゼロで、可変長インスタンスの方は tp_itemsize フィールドが非ゼロの値になります。固定長インスタンスの型の場合、全てのインスタンスは等しく tp_basicsize で与えられたサイズになります。
可変長インスタンスの型の場合、インスタンスには ob_size フィールドがなくてはならず、インスタンスのサイズは N をオブジェクトの “長さ” として、 tp_basicsize と N かける tp_itemsize の加算になります。N の値は通常、インスタンスの ob_size フィールドに記憶されます。ただし例外がいくつかあります: 例えば、長整数では負の値を ob_size に使って、インスタンスの表す値が負であることを示し、 N 自体は abs(ob_size) になります。また、 ob_size フィールドがあるからといって、必ずしもインスタンスが可変長であることを意味しません (例えば、リスト型の構造体は固定長のインスタンスになるにもかかわらず、インスタンスにはちゃんと意味を持った ob_size フィールドがあります)。
基本サイズには、 PyObject_HEAD マクロまたは PyObject_VAR_HEAD マクロ (インスタンス構造体を宣言するのに使ったどちらかのマクロ) で宣言されているフィールドが入っています。さらに、 _ob_prev および _ob_next フィールドがある場合、これらのフィールドもサイズに加算されます。
従って、 tp_basicsize の正しい初期化パラメタを得るには、インスタンスデータのレイアウトを宣言するのに使う構造体に対して sizeof 演算子を使うしかありません。基本サイズには、GC ヘッダサイズは入っていません (これは Python 2.2 からの新しい仕様です; 2.1 や 2.0 では、GC ヘッダサイズは tp_basicsize に入っていました)。
これらのフィールドはサブタイプに別々に継承されます。基底タイプが 0 でない tp_itemsize を持っていた場合、基底タイプの実装に依存しますが、一般的にはサブタイプで別の 0 で無い値を tp_itemsize に設定するのは安全ではありません。
バイト整列 (alignment) に関する注釈: 変数の各要素を配置する際に特定のバイト整列が必要となる場合、 tp_basicsize の値に気をつけなければなりません。一例: 例えばある型が double の配列を実装しているとします。 tp_itemsize は sizeof(double) です。(double のバイト整列条件に従って) tp_basicsize が sizeof(double) の個数分のサイズになるようにするのはプログラマの責任です。
インスタンスのデストラクタ関数へのポインタです。この関数は (単量子 None や Ellipsis の場合のように) インスタンスが決してメモリ解放されない型でない限り必ず定義しなければなりません。
デストラクタ関数は、 Py_DECREF() や Py_XDECREF() マクロで、操作後の参照カウントがゼロになった際に呼び出されます。呼び出された時点では、インスタンスはまだ存在しますが、インスタンスに対する参照は全くない状態です。デストラクタ関数はインスタンスが保持している全ての参照を解放し、インスタンスが確保している全てのメモリバッファを (バッファの確保時に使った関数に対応するメモリ解放関数を使って) 解放し、最後に (かならず最後に行う操作として) その型の tp_free 関数を呼び出します。ある型がサブタイプを作成できない (Py_TPFLAGS_BASETYPE フラグがセットされていない) 場合、 tp_free の代わりにオブジェクトのメモリ解放関数 (deallocator) を直接呼び出してもかまいません。オブジェクトのメモリ解放関数は、インスタンスのメモリ確保を行う際に使った関数と同じファミリでなければなりません; インスタンスを PyObject_New() や PyObject_VarNew() でメモリ確保した場合には、通常 PyObject_Del() を使い、 PyObject_GC_New() や PyObject_GC_NewVar() で確保した場合には PyObject_GC_Del() を使います。
サブタイプはこのフィールドを継承します。
オプションのフィールドで、インスタンスの出力 (print) を行う関数を指すポインタです。
出力関数は、インスタンスが 実体のある (real) ファイルに出力される場合にのみ呼び出されます; (StringIO インスタンスのような) 擬似ファイルに出力される場合には、インスタンスの tp_repr や tp_str が指す関数が呼び出され、文字列への変換を行います。また、 tp_print が NULL の場合にもこれらの関数が呼び出されます。 tp_repr や tp_str と異なる出力を生成するような tp_print は、決して型に実装してはなりません。
出力関数は PyObject_Print() と同じシグネチャ: int tp_print(PyObject *self, FILE *file, int flags) で呼び出されます。 self 引数は出力するインスタンスを指します。 file 引数は出力先となる標準入出力 (stdio) ファイルです。 flags 引数はフラグビットを組み合わせた値です。現在定義されているフラグビットは Py_PRINT_RAW のみです。 Py_PRINT_RAW フラグビットがセットされていれば、 インスタンスは tp_str と同じ書式で出力されます。 Py_PRINT_RAW フラグビットがクリアならば、インスタンスは tp_repr と同じ書式で出力されます。この関数は、操作中にエラーが生じた場合、 -1 を返して例外状態をセットしなければなりません。
tp_print フィールドは撤廃されるかもしれません。いずれにせよ、 tp_print は定義せず、代わりに tp_repr や tp_str に頼って出力を行うようにしてください。
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、 get-attribute-string を行う関数を指します。
このフィールドは撤廃されています。このフィールドを定義する場合、 tp_getattro 関数と同じように動作し、属性名は Python 文字列オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。シグネチャは PyObject_GetAttrString() と同じです。
このフィールドは tp_getattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を一緒に継承します。
オプションのフィールドです。ポインタで、 set-attribute-string を行う関数を指します。
このフィールドは撤廃されています。このフィールドを定義する場合、 tp_setattro 関数と同じように動作し、属性名は Python 文字列オブジェクトではなく C 文字列で指定するような関数を指すようにしなければなりません。シグネチャは PyObject_SetAttrString() と同じです。
このフィールドは tp_setattro と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が共に NULL の場合、サブタイプは基底タイプから tp_setattr と tp_setattro を一緒に継承します。
オプションのフィールドです。ポインタで、三値比較 (three-way comparison) を行う関数を指します。
シグネチャは PyObject_Compare() と同じです。この関数は self が other よりも大きければ 1, self と other の値が等しければ 0, self が other より小さければ -1 を返します。この関数は、比較操作中にエラーが生じた場合、例外状態をセットして -1 を返さねばなりません。
このフィールドは tp_richcompare および tp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare, tp_richcompare および tp_hash が共に NULL の場合、サブタイプは基底タイプから tp_compare, tp_richcompare, tp_hash の三つを一緒に継承します。
オプションのフィールドです。ポインタで、組み込み関数 repr() を実装している関数を指します。
シグネチャは PyObject_Repr() と同じです。この関数は文字列オブジェクトか Unicode オブジェクトを返さねばなりません。理想的には、この関数が返す文字列は、適切な環境で eval() に渡した場合、同じ値を持つオブジェクトになるような文字列でなければなりません。不可能な場合には、オブジェクトの型と値から導出した内容の入った '<' から始まって '>' で終わる文字列を返さねばなりません。
このフィールドが設定されていない場合、 <%s object at %p> の形式をとる文字列が返されます。 %s は型の名前に、 %p はオブジェクトのメモリアドレスに置き換えられます。
サブタイプはこのフィールドを継承します。
数値プロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては 数値オブジェクト構造体 で説明されています。
tp_as_number フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。
シーケンスプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては シーケンスオブジェクト構造体 で説明されています。
tp_as_sequence フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。
マッピングプロトコルを実装した追加の構造体を指すポインタです。これらのフィールドについては マップ型オブジェクト構造体 で説明されています。
tp_as_mapping フィールドは継承されませんが、そこの含まれるフィールドが個別に継承されます。
オプションのフィールドです。ポインタで、組み込み関数 hash() を実装している関数を指します。
シグネチャは PyObject_Hash() と同じです。この関数は C の long 型の値を返さねばなりません。通常時には -1 を戻り値にしてはなりません; ハッシュ値の計算中にエラーが生じた場合、関数は例外をセットして -1 を返さねばなりません。
このフィールドは明示的に PyObject_HashNotImplemented() に設定することで、親 type からのハッシュメソッドの継承をブロックすることができます。これは Python レベルでの __hash__ = None と同等に解釈され、 isinstance(o, collections.Hashable) が正しく False を返すようになります。逆もまた可能であることに注意してください - Python レベルで __hash__ = None を設定することで tp_hash スロットは PyObject_HashNotImplemented() に設定されます。
このフィールドが設定されていない場合、二つの可能性があります: tp_compare および tp_richcompare フィールドの両方が NULL の場合、オブジェクトのアドレスに基づいたデフォルトのハッシュ値が返されます; それ以外の場合、 TypeError が送出されます。
このフィールドは tp_compare および tp_richcompare と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare, tp_richcompare および tp_hash が共に NULL の場合、サブタイプは基底タイプから tp_compare, tp_richcompare, tp_hash の三つを一緒に継承します。
オプションのフィールドです。ポインタで、オブジェクトの呼び出しを実装している関数を指します。オブジェクトが呼び出し可能でない場合には NULL にしなければなりません。シグネチャは PyObject_Call() と同じです。
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、組み込みの演算 str() を実装している関数を指します。(str が型の一つになったため、 str() は str のコンストラクタを呼び出すことに注意してください。このコンストラクタは実際の処理を行う上で PyObject_Str() を呼び出し、さらに PyObject_Str() がこのハンドラを呼び出すことになります。)
シグネチャは PyObject_Str() と同じです; この関数は文字列オブジェクトか Unicode オブジェクトを返さねばなりません。また、この関数はオブジェクトを “分かりやすく (friendly)” 表現した文字列を返さねばなりません。というのは、この文字列は print 文で使われることになる表記だからです。
このフィールドが設定されていない場合、文字列表現を返すためには PyObject_Repr() が呼び出されます。
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、 get-attribute を実装している関数を指します。
シグネチャは PyObject_GetAttr() と同じです。対する通常の属性検索を実装している PyObject_GenericGetAttr() をこのフィールドに設定しておくと往々にして便利です。
このフィールドは tp_getattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_getattr および tp_getattro が共に NULL の場合、サブタイプは基底タイプから tp_getattr と tp_getattro を一緒に継承します。
オプションのフィールドです。ポインタで、 set-attribute を行う関数を指します。
シグネチャは PyObject_SetAttr() と同じです。対する通常の属性設定を実装している PyObject_GenericSetAttr() をこのフィールドに設定しておくと往々にして便利です。
このフィールドは tp_setattr と共にサブタイプに継承されます: すなわち、サブタイプの tp_setattr および tp_setattro が共に NULL の場合、サブタイプは基底タイプから tp_setattr と tp_setattro を一緒に継承します。
バッファインタフェースを実装しているオブジェクトにのみ関連する、一連のフィールド群が入った別の構造体を指すポインタです。構造体内の各フィールドは バッファオブジェクト構造体 (buffer object structure) で説明します。
tp_as_buffer フィールド自体は継承されませんが、フィールド内に入っているフィールドは個別に継承されます。
このフィールドは様々なフラグからなるビットマスクです。いくつかのフラグは、特定の状況において変則的なセマンティクスが適用されることを示します; その他のフラグは、型オブジェクト (あるいは tp_as_number, tp_as_sequence, tp_as_mapping,および tp_as_buffer が参照している拡張機能構造体: extention structure) の特定のフィールドのうち、過去から現在までずっと存在しているわけではないものが有効になっていることを示すために使われます; フラグビットがクリアであれば、フラグが保護しているフィールドにはアクセスしない代わりに、その値はゼロか NULL になっているとみなさなければなりません。
このフィールドの継承は複雑です。ほとんどのフラグビットは個別に継承されます。つまり、基底タイプであるフラグビットがセットされている場合、サブタイプはそのフラグビットを継承します。機能拡張のための構造体に関するフラグビットは、その機能拡張構造体が継承されるときに限定して継承されます。すなわち、基底タイプのフラグビットの値は、機能拡張構造体へのポインタと一緒にサブタイプにコピーされます。 Py_TPFLAGS_HAVE_GC フラグビットは、 tp_traverse および tp_clear フィールドと合わせてコピーされます。すなわち、サブタイプの Py_TPFLAGS_HAVE_GC フラグビットがクリアで、かつ (Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットの指定によって) tp_traverse および tp_clear フィールドがサブタイプ内に存在しており、かつ値が NULL の場合に基底タイプから値を継承します。
以下のビットマスクは現在定義されているものです; フラグは | 演算子で論理和を取って tp_flags フィールドの値にできます。 PyType_HasFeature() マクロは型とフラグ値、 tp および f をとり、 tp->tp_flags & f が非ゼロかどうか調べます。
このビットがセットされていれば、 tp_as_buffer が参照する PyBufferProcs 構造体には bf_getcharbuffer フィールドがあります。
このビットがセットされていれば、 tp_as_sequence が参照する PySequenceMethods 構造体には sq_contains フィールドがあります。
このビットは旧式のものです。このシンボルが指し示していたビットはもはや使われていません。シンボルの現在の定義はゼロになっています。
このビットがセットされていれば、 tp_as_sequence が参照する PySequenceMethods 構造体、および tp_as_number が参照する PyNumberMethods 構造体には in-place 演算に関するフィールドが入っています。具体的に言うと、 PyNumberMethods 構造体はフィールド nb_inplace_add, nb_inplace_subtract, nb_inplace_multiply, nb_inplace_divide, nb_inplace_remainder, nb_inplace_power, nb_inplace_lshift, nb_inplace_rshift, nb_inplace_and, nb_inplace_xor,および nb_inplace_or を持つことになります; また、 PySequenceMethods 構造体はフィールド sq_inplace_concat および sq_inplace_repeat を持つことになります。
このビットがセットされていれば、 tp_as_number が参照する PyNumberMethods 構造体内で定義されている二項演算子および三項演算子は任意のオブジェクト型を非演算子にとるようになり、必要に応じて引数の型変換を行います。このビットがクリアなら、演算子は全ての引数が現在のオブジェクト型と同じであるよう要求し、演算の呼び出し側は演算に先立って型変換を行うものと想定します。対象となる演算子は nb_add, nb_subtract, nb_multiply, nb_divide, nb_remainder, nb_divmod, nb_power, nb_lshift, nb_rshift, nb_and, nb_xor,および nb_or です。
このビットがセットされていれば、型オブジェクトには tp_richcompare フィールド、そして tp_traverse および tp_clear フィールドがあります。
このビットがセットされていれば、構造体には tp_weaklistoffset フィールドが定義されています。 tp_weaklistoffset フィールドの値がゼロより大きければ、この型のインスタンスは弱参照で参照できます。
このビットがセットされていれば、型オブジェクトには tp_iter および tp_iternext フィールドがあります。
このビットがセットされていれば、型オブジェクトは Python 2.2 以降で定義されている新たなフィールド: tp_methods, tp_members, tp_getset, tp_base, tp_dict, tp_descr_get, tp_descr_set, tp_dictoffset, tp_init, tp_alloc, tp_new, tp_free, tp_is_gc, tp_bases, tp_mro, tp_cache, tp_subclasses,および tp_weaklist があります。
型オブジェクト自体がヒープにメモリ確保される場合にセットされるビットです。型オブジェクト自体がヒープにメモリ確保される場合、インスタンスの ob_type フィールドは型オブジェクトへの参照とみなされます。この場合、新たなインスタンスを生成する度に型オブジェクトを INCREF し、インスタンスを解放するたびに DECREF します (サブタイプのインスタンスには適当されません; インスタンスが ob_type で参照している型だけが INCREF および DECREF されます)。
型を別の型の基底タイプとして使える場合にセットされるビットです。このビットがクリアならば、この型のサブタイプは生成できません (Java における “final” クラスに似たクラスになります)。
型オブジェクトが PyType_Ready() で完全に初期化されるとセットされるビットです。
PyType_Ready() による型オブジェクトの初期化処理中にセットされるビットです。
オブジェクトがガベージコレクション (GC) をサポートする場合にセットされるビットです。このビットがセットされている場合、インスタンスは PyObject_GC_New() を使って生成し、 PyObject_GC_Del() を使って破壊しなければなりません。詳しい情報は 循環参照ガベージコレクションをサポートする にあります。このビットはまた、GC に関連するフィールド tp_traverse および tp_clear が型オブジェクト内に存在することを示します; しかし、これらのフィールドは Py_TPFLAGS_HAVE_GC がクリアでも Py_TPFLAGS_HAVE_RICHCOMPARE がセットされている場合には存在します。
型オブジェクトおよび拡張機能構造体の特定のフィールドの存在の有無に関連する全てのビットからなるビットマスクです。現状では、このビットマスクには以下のビット: Py_TPFLAGS_HAVE_GETCHARBUFFER, Py_TPFLAGS_HAVE_SEQUENCE_IN, Py_TPFLAGS_HAVE_INPLACEOPS, Py_TPFLAGS_HAVE_RICHCOMPARE, Py_TPFLAGS_HAVE_WEAKREFS, Py_TPFLAGS_HAVE_ITER,および Py_TPFLAGS_HAVE_CLASS が入っています。
オプションのフィールドです。ポインタで、この型オブジェクトの docstring を与える NUL 終端された C の文字列を指します。この値は型オブジェクトと型のインスタンスにおける __doc__ 属性として公開されます。
サブタイプはこのフィールドを継承 しません 。
以下の三つのフィールドは、 Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合にのみ存在します。
オプションのフィールドです。ポインタで、ガベージコレクタのためのトラバーサル関数 (traversal function) を指します。 Py_TPFLAGS_HAVE_GC がセットされている場合にのみ使われます。Pythonのガベージコレクションの枠組みに関する詳細は 循環参照ガベージコレクションをサポートする にあります。
tp_traverse ポインタは、ガベージコレクタが循環参照を見つけるために使われます。 tp_traverse 関数の典型的な実装は、インスタンスの各メンバのうち Pythonオブジェクトに対して Py_VISIT() を呼び出します。例えば、次のコードは thread 拡張モジュールの local_traverse() 関数になります:
static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
Py_VISIT(self->args);
Py_VISIT(self->kw);
Py_VISIT(self->dict);
return 0;
}
Py_VISIT() が循環参照になる恐れのあるメンバにだけ呼び出されていることに注目してください。 self->key メンバもありますが、それは NULL か Python文字列なので、循環参照の一部になることはありません。
一方、メンバが循環参照の一部になり得ないと判っていても、デバッグ目的で巡回したい場合があるかもしれないので、 gc モジュールの get_reference() 関数は循環参照になり得ないメンバも返します。
Py_VISIT() は local_traverse() が visit と arg という決まった名前の引数を持つことを要求します。
このフィールドは tp_clear および Py_TPFLAGS_HAVE_GC フラグビットと一緒に継承されます: フラグビット、 tp_traverse,および tp_clear の値がサブタイプで全てゼロになっており、 かつ サブタイプで Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合に、基底タイプから値を継承します。
オプションのフィールドです。ポインタで、ガベージコレクタにおける消去関数 (clear function) を指します。 Py_TPFLAGS_HAVE_GC がセットされている場合にのみ使われます。
tp_clear メンバ関数はGCが見つけた循環しているゴミの循環参照を壊すために用いられます。システム内の全ての tp_clear 関数によって、全ての循環参照を破壊しなければなりません。 (訳注: ある型が tp_clear を実装しなくても全ての循環参照が破壊できるのであれば実装しなくても良い) これはとても繊細で、もし少しでも不確かな部分があるのであれば、 tp_clear 関数を提供するべきです。例えば、タプルは tp_clear を実装しません。なぜなら、タプルだけで構成された循環参照がみつかることは無いからです。したがって、タプル以外の型 tp_clear 関数たちが、タプルを含むどんな循環参照も破壊できる必要があります。これは簡単に判ることでははありません。 tp_clear の実装を避ける良い理由はめったにありません。
tp_clear の実装は、次の実装のように、インスタンスの (Pythonオブジェクト)メンバに対する参照を捨てて、メンバに対するポインタ変数を NULL にセットするべきです:
static int
local_clear(localobject *self)
{
Py_CLEAR(self->key);
Py_CLEAR(self->args);
Py_CLEAR(self->kw);
Py_CLEAR(self->dict);
return 0;
}
参照のクリアはデリケートなので、 Py_CLEAR() マクロを使うべきです: ポインタを NULL にセットするまで、そのオブジェクトの参照カウントをデクリメントしてはいけません。参照カウントのデクリメントすると、そのオブジェクトが破棄されるかもしれず、 (そのオブジェクトに関連付けられたファイナライザ、弱参照のコールバックにより) 任意のPythonコードの実行を含む後片付け処理が実行されるかもしれないからです。もしそういったコードが再び self を参照することがあれば、すでに持っていたオブジェクトへのポインタは NULL になっているので、 self は所有していたオブジェクトをもう利用できないことを認識できます。 Py_CLEAR() マクロはその手続きを安全な順番で実行します。
tp_clear 関数の目的は参照カウントを破壊することなので、Python文字列や Python整数のような、循環参照になりえないオブジェクトをクリアする必要はありません。一方、全部の所有オブジェクトをクリアするようにし、 tp_dealloc 関数が tp_clear 関数を実行するようにすると実装が楽です。
Pythonのガベージコレクションの仕組みについての詳細は、 循環参照ガベージコレクションをサポートする にあります。
このフィールドは tp_traverse および Py_TPFLAGS_HAVE_GC フラグビットと一緒に継承されます: フラグビット、 tp_traverse,および tp_clear の値がサブタイプで全てゼロになっており、 かつ サブタイプで Py_TPFLAGS_HAVE_RICHCOMPARE フラグビットがセットされている場合に、基底タイプから値を継承します。
オプションのフィールドで、拡張比較関数 (rich comparison function) を指すポインタです。拡張比較関数のシグネチャは PyObject *tp_richcompare(PyObject *a, PyObject *b, int op) です。
この関数は、比較結果を返すべきです。(普通は Py_True か Py_False です。) 比較が未定義の場合は、 Py_NotImplemented を、それ以外のエラーが発生した場合には例外状態をセットして NULL を返さねばなりません。
ノート
限られた種類の比較だけが可能 (例えば、 == と != が可能で < などが不可能) な型を実装したい場合、拡張比較関数で直接 TypeError を返します。
このフィールドは tp_compare および tp_hash と共にサブタイプに継承されます: すなわち、サブタイプの tp_compare, tp_richcompare および tp_hash が共に NULL の場合、サブタイプは基底タイプから tp_compare, tp_richcompare, tp_hash の三つを一緒に継承します。
tp_richcompare および PyObject_RichCompare() 関数の第三引数に使うための定数としては以下が定義されています:
| 定数 | 比較 |
|---|---|
| Py_LT | < |
| Py_LE | <= |
| Py_EQ | == |
| Py_NE | != |
| Py_GT | > |
| Py_GE | >= |
次のフィールドは、 Py_TPFLAGS_HAVE_WEAKREFS フラグビットがセットされている場合にのみ存在します。
型のインスタンスが弱参照可能な場合、このフィールドはゼロよりも大きな数になり、インスタンス構造体における弱参照リストの先頭を示すオフセットが入ります (GC ヘッダがある場合には無視します); このオフセット値は PyObject_ClearWeakRefs() および PyWeakref_*() 関数が利用します。インスタンス構造体には、 NULL に初期化された PyObject* 型のフィールドが入っていなければなりません。
このフィールドを tp_weaklist と混同しないようにしてください; tp_weaklist は型オブジェクト自体の弱参照リストの先頭です。
サブタイプはこのフィールドを継承しますが、以下の規則があるので読んでください。サブタイプはこのオフセット値をオーバライドできます; 従って、サブタイプでは弱参照リストの先頭が基底タイプとは異なる場合があります。リストの先頭は常に tp_weaklistoffset で分かるはずなので、このことは問題にはならないはずです。
class 文で定義された型に __slots__ 宣言が全くなく、かつ基底タイプが弱参照可能でない場合、その型を弱参照可能にするには弱参照リストの先頭を表すスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_weaklistoffset に設定します。
型の __slots__ 宣言中に __weakref__ という名前のスロットが入っている場合、スロットはその型のインスタンスにおける弱参照リストの先頭を表すスロットになり、スロットのオフセットが型の tp_weaklistoffset に入ります。
型の __slots__ 宣言に __weakref__ という名のスロットが入っていない場合、その型は基底タイプから tp_weaklistoffset を継承します。
次の二つのフィールドは、 Py_TPFLAGS_HAVE_ITER フラグビットがセットされている場合にのみ存在します。
オプションの変数で、そのオブジェクトのイテレータを返す関数へのポインタです。この値が存在することは、通常この型のインスタンスがイテレート可能であることを示しています。(しかし、シーケンスはこの関数がなくてもイテレート可能ですし、旧スタイルクラスのインスタンスは __iter__() メソッドを定義していなくてもこの関数を持っています)
この関数は PyObject_GetIter() と同じシグネチャを持っています。
サブタイプはこのフィールドを継承します。
オプションのフィールドで、イテレータにおいて次の要素を返す関数へのポインタです。イテレータの要素がなくなると、この関数は NULL を返さなければなりません。 StopIteration 例外は設定してもしなくても良いです。その他のエラーが発生したときも、 NULL を返さなければなりません。このフィールドがあると、通常この型のインスタンスがイテレータであることを示します (ただし、旧スタイルのインスタンスでは、たとえ next() メソッドが定義されていなくても常にこの関数を持っています)。
イテレータ型では、 tp_iter 関数も定義していなければならず、 tp_iter は (新たなイテレータインスタンスではなく) イテレータインスタンス自体を返さねばなりません。
この関数のシグネチャは PyIter_Next() と同じです。
サブタイプはこのフィールドを継承します。
次の tp_weaklist までのフィールドは、 Py_TPFLAGS_HAVE_CLASS フラグビットがセットされている場合にのみ存在します。
オプションのフィールドです。ポインタで、この型の正規 (regular) のメソッドを宣言している PyMethodDef 構造体からなる、 NULL で終端された静的な配列を指します。
配列の各要素ごとに、メソッドデスクリプタの入ったエントリが型辞書 (下記の tp_dict 参照) に追加されます。
サブタイプはこのフィールドを継承しません (メソッドは別個のメカニズムで継承されています)。
オプションのフィールドです。ポインタで、型の正規 (regular) のデータメンバ (フィールドおよびスロット) を宣言している PyMemberDef 構造体からなる、 NULL で終端された静的な配列を指します。
配列の各要素ごとに、メンバデスクリプタの入ったエントリが型辞書 (下記の tp_dict 参照) に追加されます。
サブタイプはこのフィールドを継承しません (メンバは別個のメカニズムで継承されています)。
オプションのフィールドです。ポインタで、インスタンスの算出属性 (computed attribute) を宣言している PyGetSetDef 構造体からなる、 NULL で終端された静的な配列を指します。
配列の各要素ごとに、getset デスクリプタの入ったエントリが型辞書 (下記の tp_dict 参照) に追加されます。
サブタイプはこのフィールドを継承しません (算出属性は別個のメカニズムで継承されています)。
PyGetSetDef のドキュメント:
typedef PyObject *(* getter)(PyObject *, void *);
typedef int (*setter)(PyObject *, PyObject *, void *);
typedef struct PyGetSetDef {
char *name; /* 属性名 */
getter get; /* 属性の get を行う C 関数 */
setter set; /* 属性の set を行う C 関数 */
char *doc; /* オプションの docstring */
void *closure; /* オプションの get/set 関数用追加データ */
} PyGetSetDef;
オプションのフィールドです。ポインタで、型に関するプロパティを継承する基底タイプへのポインタです。このフィールドのレベルでは、単継承 (single inheritance) だけがサポートされています; 多重継承はメタタイプの呼び出しによる動的な型オブジェクトの生成を必要とします。
(当たり前ですが) サブタイプはこのフィールドを継承しません。しかし、このフィールドのデフォルト値は (Python プログラマは object 型として知っている) &PyBaseObject_Type になります。 .
型の辞書は PyType_Ready() によってこのフィールドに収められます。
このフィールドは通常、 PyType_Ready() を呼び出す前に NULL に初期化しておかねばなりません; あるいは、型の初期属性の入った辞書で初期化しておいてもかまいません。 PyType_Ready() が型をひとたび初期化すると、型の新たな属性をこの辞書に追加できるのは、属性が (__add__() のような) オーバロード用演算でないときだけです。
サブタイプはこのフィールドを継承しません (が、この辞書内で定義されている属性は異なるメカニズムで継承されます)。
オプションのフィールドです。ポインタで、 “デスクリプタ get” 関数を指します。
関数のシグネチャは次のとおりです。
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、 “デスクリプタ set” 関数を指します。
関数のシグネチャは次のとおりです。
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
サブタイプはこのフィールドを継承します。
型のインスタンスにインスタンス変数の入った辞書がある場合、このフィールドは非ゼロの値になり、型のインスタンスデータ構造体におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は PyObject_GenericGetAttr() が使います。
このフィールドを tp_dict と混同しないでください; tp_dict は型オブジェクト自体の属性のための辞書です。
このフィールドの値がゼロより大きければ、値はインスタンス構造体の先頭からのオフセットを表します。値がゼロより小さければ、インスタンス構造体の 末尾 からのオフセットを表します。負のオフセットを使うコストは比較的高くつくので、インスタンス構造体に可変長の部分があるときのみ使うべきです。例えば、 str や tuple のサブタイプにインスタンス辞書を追加する場合には、負のオフセットを使います。この場合、たとえ辞書が基本のオブジェクトレイアウトに含まれていなくても、 tp_basicsize フィールドは追加された辞書を考慮にいれなければならないので注意してください。ポインタサイズが 4 バイトのシステムでは、構造体の最後尾に辞書が宣言されていることを示す場合、 tp_dictoffset を -4 にしなければなりません。
tp_dictoffset が負の場合、インスタンスにおける実際の辞書のオフセットは以下のようにして計算されます:
dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
round up to sizeof(void*)
ここで、 tp_basicsize, tp_itemsize および tp_dictoffset は型オブジェクトから取り出され、 ob_size はインスタンスから取り出されます。長整数は符号を記憶するのに ob_size の符号を使うため、 ob_size は絶対値を使います。(この計算を自分で行う必要はまったくありません; _PyObject_GetDictPtr() がやってくれます。)
サブタイプはこのフィールドを継承しますが、以下の規則があるので読んでください。サブタイプはこのオフセット値をオーバライドできます; 従って、サブタイプでは辞書のオフセットが基底タイプとは異なる場合があります。辞書へのオフセット常に tp_dictoffset で分かるはずなので、このことは問題にはならないはずです。
class 文で定義された型に __slots__ 宣言がなく、かつ基底タイプの全てにインスタンス変数辞書がない場合、辞書のスロットをインスタンスデータレイアウト構造体に追加し、スロットのオフセットを tp_dictoffset に設定します。
class 文で定義された型に __slots__ 宣言がある場合、この型は基底タイプから tp_dictoffset を継承します。
(__dict__ という名前のスロットを __slots__ 宣言に追加しても、期待どおりの効果は得られず、単に混乱を招くだけになります。とはいえ、これは将来 __weakref__ のように追加されるはずです。)
オプションのフィールドです。ポインタで、インスタンス初期化関数を指します。
この関数はクラスにおける __init__() メソッドに対応します。 __init__() と同様、 __init__() を呼び出さずにインスタンスを作成できます。また、 __init__() を再度呼び出してインスタンスの再初期化もできます。
関数のシグネチャは
int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
です。
self 引数は初期化するインスタンスです; args および kwds 引数は、 __init__() を呼び出す際の固定引数およびキーワード引数です。
tp_init 関数のフィールドが NULL でない場合、型の呼び出しで普通にインスタンスを生成する際に、型の tp_new がインスタンスを返した後に tp_init が呼び出されます。 tp_new が元の型のサブタイプでない別の型を返す場合、 tp_init は全く呼び出されません; tp_new が元の型のサブタイプのインスタンスを返す場合、サブタイプの tp_init が呼び出されます。 (VERSION NOTE: ここに書かれている内容は、Python 2.2.1 以降での実装に関するものです。Python 2.2 では、 tp_init は NULL でない限り tp_new が返す全てのオブジェクトに対して常に呼び出されます。) not NULL.)
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、インスタンスのメモリ確保関数を指します。
関数のシグネチャは
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
です。
この関数の目的は、メモリ確保をメモリ初期化から分離することにあります。この関数は、インスタンス用の的確なサイズを持ち、適切にバイト整列され、ゼロで初期化され、ただし ob_refcnt を 1 にセットされ、 ob_type が型引数 (type argument) にセットされているようなメモリブロックを返さねばなりません。型の tp_itemsize がゼロでない場合、オブジェクトの ob_size フィールドは nitems に初期化され、確保されるメモリブロックの長さは tp_basicsize + nitems *tp_itemsize を sizeof(void*) の倍数で丸めた値になるはずです; それ以外の場合、 nitems の値は使われず、メモリブロックの長さは tp_basicsize になるはずです。
この関数をインスタンス初期化の他のどの処理にも、追加でメモリ確保をする場合でさえ使ってはなりません; そうした処理は tp_new で行わねばなりません。
静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドは常に PyType_GenericAlloc() にセットされ、標準のヒープ上メモリ確保戦略が強制されます。静的に定義する型の場合でも、 PyType_GenericAlloc() を推奨します。
オプションのフィールドです。ポインタで、インスタンス生成関数を指します。
このフィールドが NULL を指している型では、型を呼び出して新たなインスタンスを生成できません; こうした型では、おそらくファクトリ関数のように、インスタンスを生成する他の方法があるはずです。
関数のシグネチャは
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
です。
引数 subtype は生成するオブジェクトの型です; args および kwds 引数は、型を呼び出すときの固定引数およびキーワード引数です。サブタイプは tp_new 関数を呼び出すときに使う型と等価というわけではないので注意してください; tp_new 関数を呼び出すときに使う型 (と無関係ではない) サブタイプのこともあります。
tp_new 関数は subtype->tp_alloc(subtype, nitems) を呼び出してオブジェクトのメモリ領域を確保し、初期化で本当に必要とされる処理だけを行います。省略したり繰り返したりしても問題のない初期化処理は tp_init ハンドラ内に配置しなければなりません。経験則からいうと、変更不能な型の場合、初期化は全て tp_new で行い、変更可能な型の場合はほとんどの初期化を tp_init に回すべきです。
サブタイプはこのフィールドを継承します。例外として、 tp_base が NULL か &PyBaseObject_Type になっている静的な型では継承しません。後者が例外になっているのは、旧式の拡張型が Python 2.2 でリンクされたときに呼び出し可能オブジェクトにならないようにするための予防措置です。
オプションのフィールドです。ポインタで、インスタンスのメモリ解放関数を指します。
この関数のシグネチャは少し変更されています; Python 2.2 および 2.2.1 では、シグネチャは destructor
void tp_free(PyObject *)
でしたが、 Python 2.3 以降では、シグネチャは freefunc:
void tp_free(void *)
になっています。
両方のバージョンと互換性のある初期値は _PyObject_Del です。 _PyObject_Del の定義は Python 2.3 で適切に対応できるよう変更されました。
静的なサブタイプはこのフィールドを継承しますが、動的なサブタイプ (class 文で生成するサブタイプ) の場合は継承しません; 後者の場合、このフィールドには PyType_GenericAlloc() と Py_TPFLAGS_HAVE_GC フラグビットの値に対応させるのにふさわしいメモリ解放関数がセットされます。
オプションのフィールドです。ポインタで、ガベージコレクタから呼び出される関数を指します。
ガベージコレクタは、オブジェクトがガベージとして収集可能かどうかを知る必要があります。これを知るには、通常はオブジェクトの型の tp_flags フィールドを見て、 Py_TPFLAGS_HAVE_GC フラグビットを調べるだけで十分です。しかし、静的なメモリ確保と動的なメモリ確保が混じっているインスタンスを持つような型や、静的にメモリ確保されたインスタンスは収集できません。こうした型では、このフィールドに関数を定義しなければなりません; 関数はインスタンスが収集可能の場合には 1 を、収集不能の場合には 0 を返さねばなりません。シグネチャは
int tp_is_gc(PyObject *self)
です。
(上記のような型の例は、型オブジェクト自体です。メタタイプ PyType_Type は、型のメモリ確保が静的か動的かを区別するためにこの関数を定義しています。)
サブタイプはこのフィールドを継承します。 (VERSION NOTE: Python 2.2 では、このフィールドは継承されませんでした。 2.2.1 以降のバージョンから継承されるようになりました。)
基底型からなるタプルです。
class 文で生成されたクラスの場合このフィールドがセットされます。静的に定義されている型の場合には、このフィールドは NULL になります。
このフィールドは継承されません。
基底クラス群を展開した集合が入っているタプルです。集合は該当する型自体からはじまり、 object で終わります。メソッド解決順 (Method Resolution Order) の順に並んでいます。
このフィールドは継承されません; フィールドの値は PyType_Ready() で毎回計算されます。
残りのフィールドは、機能テスト用のマクロである COUNT_ALLOCS が定義されている場合のみ利用でき、内部で使用するためだけのものです。これらのフィールドについて記述するのは単に完全性のためです。サブタイプはこれらのフィールドを継承しません。
メモリ確保の回数です。
メモリ解放の回数です。
同時にメモリ確保できる最大オブジェクト数です。
tp_allocs フィールドが非ゼロの、(リンクリストの) 次の型オブジェクトを指すポインタです。
また、 Python のガベージコレクションでは、 tp_dealloc を呼び出すのはオブジェクトを生成したスレッドだけではなく、任意の Python スレッドかもしれないという点にも注意して下さい。 (オブジェクトが循環参照の一部の場合、任意のスレッドのガベージコレクションによって解放されてしまうかもしれません)。Python API 側からみれば、 tp_dealloc を呼び出すスレッドはグローバルインタプリタロック (GIL: Global Interpreter Lock) を獲得するので、これは問題ではありません。しかしながら、削除されようとしているオブジェクトが何らかの C や C++ ライブラリ由来のオブジェクトを削除する場合、 tp_dealloc を呼び出すスレッドのオブジェクトを削除することで、ライブラリの仮定している何らかの規約に違反しないように気を付ける必要があります。
拡張型で数値型プロトコルを実装するために使われる関数群へのポインタを保持するために使われる構造体です。以下のほとんどすべての関数は 数値型プロトコル (number protocol) で解説されている似た名前の関数から利用されます。
以下は構造体の定義です。
typedef struct {
binaryfunc nb_add;
binaryfunc nb_subtract;
binaryfunc nb_multiply;
binaryfunc nb_divide;
binaryfunc nb_remainder;
binaryfunc nb_divmod;
ternaryfunc nb_power;
unaryfunc nb_negative;
unaryfunc nb_positive;
unaryfunc nb_absolute;
inquiry nb_nonzero; /* Used by PyObject_IsTrue */
unaryfunc nb_invert;
binaryfunc nb_lshift;
binaryfunc nb_rshift;
binaryfunc nb_and;
binaryfunc nb_xor;
binaryfunc nb_or;
coercion nb_coerce; /* Used by the coerce() function */
unaryfunc nb_int;
unaryfunc nb_long;
unaryfunc nb_float;
unaryfunc nb_oct;
unaryfunc nb_hex;
/* Added in release 2.0 */
binaryfunc nb_inplace_add;
binaryfunc nb_inplace_subtract;
binaryfunc nb_inplace_multiply;
binaryfunc nb_inplace_divide;
binaryfunc nb_inplace_remainder;
ternaryfunc nb_inplace_power;
binaryfunc nb_inplace_lshift;
binaryfunc nb_inplace_rshift;
binaryfunc nb_inplace_and;
binaryfunc nb_inplace_xor;
binaryfunc nb_inplace_or;
/* Added in release 2.2 */
binaryfunc nb_floor_divide;
binaryfunc nb_true_divide;
binaryfunc nb_inplace_floor_divide;
binaryfunc nb_inplace_true_divide;
/* Added in release 2.5 */
unaryfunc nb_index;
} PyNumberMethods;
2引数および3引数の関数は、 Py_TPFLAGS_CHECKTYPES フラグによっては、異なる種類の引数を受け取るかもしれません。
Py_TPFLAGS_CHECKTYPES がセットされていない場合、関数の引数はオブジェクトの型であることが保証されます。呼び出し側は nb_coerce メンバで指定されている型強制メソッドを呼び出して引数を変換する責任があります。
この関数は PyNumber_CoerceEx() から利用され、同じシグネチャを持ちます。最初の引数は定義された型のオブジェクトを指すポインタでなければなりません。共通の “大きな” 型への変換が可能であれば、この関数はポインタを変換後のオブジェクトへの新しい参照へ置き換えて、 0 を返します。変換ができないなら、この関数は 1 を返します。エラーが設定荒れた場合は、 -1 を返します。
Py_TPFLAGS_CHECKTYPES フラグがセットされている場合、2引数および 3引数関数はすべてのオペランドの型をチェクし、必要な変換を行わなければなりません。 (少なくとも、オペランドのうち1つは定義している型のものです) これは推奨された方式です。 Python 3.0 では型強制は完全に取り除かれています。
与えられたオペランドに対して操作が定義されていな場合は、2引数および3引数関数は Py_NotImplemented を返さなければなりません。その他のエラーが発生した場合は、例外を設定して NULL を返さなければなりません。
拡張型でマップ型プロトコルを実装するために使われる関数群へのポインタを保持するために使われる構造体です。以下の3つのメンバを持っています。
この関数は PyMapping_Length() や PyObject_Size() から利用され、それらと同じシグネチャを持っています。オブジェクトが定義された長さを持たない場合は、このスロットは NULL に設定されることがあります。
この関数は PyObject_GetItem() から利用され、同じシグネチャを持っています。このスロットは PyMapping_Check() が 1 を返すためには必要で、そうでなければ NULL の場合があります。
この関数は PyObject_SetItem() から利用され、同じシグネチャを持っています。もしこのスロットが NULL なら、このオブジェクトはアイテムの代入をサポートしません。
拡張型でシーケンス型プロトコルを実装するために使われる関数群へのポインタを保持するために使われる構造体です。
この関数は PySequence_Size() や PyObject_Size() から利用され、それらと同じシグネチャを持っています。
この関数は PySequence_Concat() から利用され、同じシグネチャを持っています。また、 + 演算からも、 tp_as_number.nb_add スロットによる数値加算を試したあとに利用されます。
この関数は PySequence_Repeat() から利用され、同じシグネチャを持っています。また、 * 演算からも、 tp_as_number.nb_mul スロットによる数値乗算を試したあとに利用されます。
この関数は PySequence_GetItem() から利用され、同じシグネチャを持っています。このスロットは PySequence_Check() が 1 を返すためには埋めなければならず、それ以外の場合は NULL の可能性があります。
負のインデックスは次のように処理されます: sq_length スロットが埋められていれば、それを呼び出してシーケンスの長さから正のインデックスを計算し、 sq_item に渡します。 sq_length が NULL の場合は、インデックスはそのままこの関数に渡されます。
この関数は PySequence_SetItem() から利用され、同じシグネチャを持っています。このスロットはオブジェクトが要素の代入をサポートしていない場合は NULL かもしれません。
この関数は PySequence_Contains() から利用され、同じシグネチャを持っています。このスロットは NULL の場合があり、その時 PySequence_Contains() はシンプルにマッチするオブジェクトを見つけるまでシーケンスを巡回します。
この関数は PySequence_InPlaceConcat() から利用され、同じシグネチャを持っています。この関数は最初のオペランドを修正してそれを返すべきです。
この関数は PySequence_InPlaceRepeat() から利用され、同じシグネチャを持っています。この関数は最初のオペランドを修正してそれを返すべきです。
バッファインタフェースは、あるオブジェクトの内部データを一連のデータチャンク (chunk) として見せるモデルを外部から利用できるようにします。各チャンクはポインタ/データ長からなるペアで指定します。チャンクはセグメント(segment) と呼ばれ、メモリ内に不連続的に配置されるものと想定されています。
バッファインタフェースを利用できるようにしたくないオブジェクトでは、 PyTypeObject 構造体の tp_as_buffer メンバを NULL にしなくてはなりません。利用できるようにする場合、 tp_as_buffer は PyBufferProcs 構造体を指さねばなりません。
ノート
PyTypeObject 構造体の tp_flags メンバの値を 0 でなく Py_TPFLAGS_DEFAULT にしておくことがとても重要です。この設定は、 PyBufferProcs 構造体に bf_getcharbuffer スロットが入っていることを Python ランタイムに教えます。 Python の古いバージョンには bf_getcharbuffer メンバが存在しないので、古い拡張モジュールを使おうとしている新しいバージョンの Python インタプリタは、このメンバがあるかどうかテストしてから使えるようにする必要があるのです。
バッファプロトコルの実装を定義している関数群へのポインタを保持するのに使われる構造体です。
最初のスロットは bf_getreadbuffer で、 getreadbufferproc 型です。このスロットが NULL の場合、オブジェクトは内部データの読み出しをサポートしません。そのような仕様には意味がないので、実装を行う側はこのスロットに値を埋めるはずですが、呼び出し側では非 NULL の値かどうかきちんと調べておくべきです。
次のスロットは bf_getwritebuffer で、 getwritebufferproc 型です。オブジェクトが返すバッファに対して書き込みを許可しない場合はこのスロットを NULL にできます。
第三のスロットは bf_getsegcount で、 getsegcountproc 型です。このスロットは NULL であってはならず、オブジェクトにいくつセグメントが入っているかを呼び出し側に教えるために使われます。 PyString_Type や PyBuffer_Type オブジェクトのような単純なオブジェクトには単一のセグメントしか入っていません。
最後のスロットは bf_getcharbuffer で、 getcharbufferproc です。オブジェクトの PyTypeObject 構造体における tp_flags フィールドに、 Py_TPFLAGS_HAVE_GETCHARBUFFER ビットフラグがセットされている場合にのみ、このスロットが存在することになります。このスロットの使用に先立って、呼び出し側は PyType_HasFeature() を使ってスロットが存在するか調べねばなりません。フラグが立っていても、 bf_getcharbuffer は NULL のときもあり、 NULL はオブジェクトの内容を 8 ビット文字列 として利用できないことを示します。このスロットに入る関数も、オブジェクトの内容を 8 ビット文字列に変換できない場合に例外を送出することがあります。例えば、オブジェクトが浮動小数点数を保持するように設定されたアレイの場合、呼び出し側が bf_getcharbuffer を使って 8 ビット文字列としてデータを取り出そうとすると例外を送出するようにできます。この、内部バッファを “テキスト” として取り出すという概念は、本質的にはバイナリで、文字ベースの内容を持ったオブジェクト間の区別に使われます。
ノート
現在のポリシでは、文字 (character) はマルチバイト文字でもかまわないと決めているように思われます。従って、サイズ N のバッファが N 個のキャラクタからなるとはかぎらないことになります。
型構造体中のフラグビットで、 bf_getcharbuffer スロットが既知の値になっていることを示します。このフラグビットがセットされていたとしても、オブジェクトがバッファインタフェースをサポートしていることや、 bf_getcharbuffer スロットが NULL でないことを示すわけではありません。
*ptrptr の中の読み出し可能なバッファセグメントへのポインタを返します。この関数は例外を送出してもよく、送出する場合には -1 を返さねばなりません。 segment に渡す値はゼロまたは正の値で、 bf_getsegcount スロット関数が返すセグメント数よりも必ず小さな値でなければなりません。成功すると、セグメントのサイズを返し、 *ptrptr をそのセグメントを指すポインタ値にセットします。
読み出し可能なバッファセグメントへのポインタを *ptrptr に返し、セグメントの長さを関数の戻り値として返します。エラーによる例外の場合には -1 を -1 を返さねばなりません。オブジェクトが呼び出し専用バッファしかサポートしていない場合には TypeError を、 segment が存在しないセグメントを指している場合には SystemError を送出しなければなりません。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新たにメモリ確保されたオブジェクト op に対し、型と初期状態での参照 (initial reference) を初期化します。初期化されたオブジェクトを返します。 type からそのオブジェクトが循環参照ガベージ検出の機能を有する場合、検出機構が監視対象とするオブジェクトのセットに追加されます。オブジェクトの他のフィールドには影響を及ぼしません。
PyObject_Init() の全ての処理を行い、可変サイズオブジェクトの場合には長さ情報も初期化します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
C 構造体型 TYPE と Python 型オブジェクト type を使って新たな Python オブジェクトをメモリ確保します。 Python オブジェクトヘッダで定義されていないフィールドは初期化されません; オブジェクトの参照カウントは 1 になります。メモリ確保のサイズは型オブジェクトの tp_basicsize で決定します。
C 構造体型 TYPE と Python 型オブジェクト type を使って新たな Python オブジェクトをメモリ確保します。 Python オブジェクトヘッダで定義されていないフィールドは初期化されません。確保されたメモリは、 TYPE 構造体に加え、vartype の tp_itemsize フィールドで指定されているサイズ中の size フィールドを収容できます。この関数は、例えばタプルのように生成時にサイズを決定できるオブジェクトを実装する際に便利です。一連の複数のフィールドに対するアロケーション操作を一つにして埋め込むと、アロケーション回数が減り、メモリ管理の処理効率が向上します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyObject_New() や PyObject_NewVar() で確保されたメモリを解放します。この関数は、通常オブジェクトの型に指定されている tp_dealloc ハンドラ内で呼び出します。この関数を呼び出した後では、オブジェクトのメモリ領域はもはや有効な Python オブジェクトを表現してはいないので、オブジェクトのフィールドに対してアクセスしてはなりません。
name と関数のテーブルに基づいて新たなモジュールオブジェクトを生成し、生成されたモジュールオブジェクトを返します。
バージョン 2.3 で変更: 以前のバージョンの Python では、 methods 引数の値として NULL をサポートしていませんでした.
name と関数のテーブルに基づいて新たなモジュールオブジェクトを生成し、生成されたモジュールオブジェクトを返します。 doc が NULL でない場合、モジュールの docstring として使われます。
バージョン 2.3 で変更: 以前のバージョンの Python では、 methods 引数の値として NULL をサポートしていませんでした.
name と関数のテーブルに基づいて新たなモジュールオブジェクトを生成し、生成されたモジュールオブジェクトを返します。 doc が NULL でない場合、モジュールの docstring として使われます。 self が NULL でない場合、モジュール内の各関数の第一引数として渡されます (NULL の時には第一引数も NULL になります)。 (この関数は実験的な機能のために追加されたもので、現在の Python のバージョンで使われてはいないはずです。) apiver に渡してよい値は、 PYTHON_API_VERSION で定義されている定数だけです。
ノート
この関数のほとんどの用途は、代わりに Py_InitModule3() を使えるはずです; 本当にこの関数を使いたいときにだけ利用してください
バージョン 2.3 で変更: 以前のバージョンの Python では、 methods 引数の値として NULL をサポートしていませんでした.
この章で説明する関数を使うと、 Python の例外の処理や送出ができるようになります。 Python の例外処理の基本をいくらか理解することが大切です。例外は Unix errno 変数にやや似た機能を果たします: 発生した中で最も新しいエラーの (スレッド毎の) グローバルなインジケータがあります。実行に成功した場合にはほとんどの関数がこれをクリアしませんが、失敗したときにはエラーの原因を示すために設定します。ほとんどの関数はエラーインジケータも返し、通常は関数がポインタを返すことになっている場合は NULL であり、関数が整数を返す場合は -1 です。(例外: PyArg_*() 関数は実行に成功したときに 1 を返し、失敗したときに 0 を返します).
ある関数が呼び出した関数がいくつか失敗したために、その関数が失敗しなければならないとき、一般的にエラーインジケータを設定しません。呼び出した関数がすでに設定しています。エラーを処理して例外をクリアするか、あるいは (オブジェクト参照またはメモリ割り当てのような)それが持つどんなリソースも取り除いた後に戻るかのどちらか一方を行う責任があります。エラーを処理する準備をしていなければ、普通に続けるべきでは ありません 。エラーのために戻る場合は、エラーが設定されていると呼び出し元に知らせることが大切です。エラーが処理されていない場合または丁寧に伝えられている場合には、 Python/C APIのさらなる呼び出しは意図した通りには動かない可能性があり、不可解な形で失敗するかもしれません。
エラーインジケータは Python変数 sys.exc_type, sys.exc_value および sys.exc_traceback に対応する三つのPythonオブジェクトからからなります。いろいろな方法でエラーインジケータとやりとりするためにAPI関数が存在します。各スレッドに別々のエラーインジケータがあります。
sys.stderr へ標準トレースバックをプリントし、エラーインジケータをクリアします。エラーインジケータが設定されているときにだけ、この関数を呼び出してください。(それ以外の場合、致命的なエラーを引き起こすでしょう!)
set_sys_last_vars が非ゼロであれば、 sys.last_type, sys.last_value, sys.last_traceback 変数が、表示される例外のタイプ、値、トレースバックそれぞれに反映されます。
PyErr_PrintEx(1) のエイリアス.
エラーインジケータが設定されているかテストします。設定されている場合は、例外の 型 (PyErr_Set*() 関数の一つあるいは PyErr_Restore() への最も新しい呼び出しに対する第一引数)を返します。設定されていない場合は NULL を返します。あなたは戻り値への参照を持っていませんので、それに Py_DECREF() する必要はありません。
ノート
戻り値を特定の例外と比較しないでください。その代わり、下に示す PyErr_ExceptionMatches() を使ってください。(比較は簡単に失敗するでしょう。なぜなら、例外はクラスではなくインスタンスかもしれないし、あるいは、クラス例外の場合は期待される例外のサブクラスかもしれないからです。)
PyErr_GivenExceptionMatches(PyErr_Occurred(), exc) と同じ。例外が実際に設定されたときにだけ、これを呼び出だすべきです。例外が発生していないならば、メモリアクセス違反が起きるでしょう。
given 例外が exc の例外と一致するなら真を返します。これは exc がクラスオブジェクトである場合も真を返します。これは given がサブクラスのインスタンスであるときも真を返します。 exc がタプルならば、タプル内(と再帰的にサブタプル内)のすべての例外が一致するか調べられます。
ある状況では、以下の PyErr_Fetch() が返す値は “正規化されていない” 可能性があります。つまり、 *exc はクラスオブジェクトだが *val は同じクラスのインスタンスではないという意味です。この関数はそのような場合にそのクラスをインスタンス化するために使われます。その値がすでに正規化されている場合は何も起きません。遅延正規化はパフォーマンスを改善するために実装されています。
エラーインジケータをクリアします。エラーインジケータが設定されていないならば、効果はありません。
エラーインジケータをアドレスを渡す三つの変数の中へ取り出します。エラーインジケータが設定されていない場合は、三つすべての変数を NULL に設定します。エラーインジケータが設定されている場合はクリアされ、あなたは取り出されたそれぞれのオブジェクトへの参照を持つことになります。型オブジェクトが NULL でないときでさえ、その値とトレースバックオブジェクトは NULL かもしれません。
ノート
通常、この関数は例外を扱う必要のあるコードあるいはエラーインジケータを一時的に保存して元に戻す必要のあるコードによってのみ使用されます。
三つのオブジェクトからエラーインジケータを設定します。エラーインジケータがすでに設定されている場合は、最初にクリアされます。オブジェクトが NULL ならば、エラーインジケータがクリアされます。 NULL のtypeと非 NULL のvalueあるいは tracebackを渡してはいけません。例外の型(type)はクラスであるべきです。無効な例外の型(type)あるいは値(value)を渡してはいけません。 (これらの規則を破ると後で気付きにくい問題の原因となるでしょう。) この呼び出しはそれぞれのオブジェクトへの参照を取り除きます: あなたは呼び出しの前にそれぞれのオブジェクトへの参照を持たなければならないのであり、また呼び出しの後にはもはやこれらの参照を持っていません。 (これを理解していない場合は、この関数を使ってはいけません。注意しておきます。)
ノート
通常この関数はエラーインジケータを一時的に保存し元に戻す必要のあるコードによってのみに使われます。現在の例外状態を保存するためには PyErr_Fetch() を使ってください。
これはエラーインジケータを設定するための最も一般的な方法です。第一引数は例外の型を指定します。通常は標準例外の一つ、例えば PyExc_RuntimeError です。その参照カウントを増加させる必要はありません。第二引数はエラーメッセージで、文字列オブジェクトへ変換されます。
この関数は PyErr_SetString() に似ていますが、例外の”値(value)”として任意のPythonオブジェクトを指定することができます。
この関数はエラーインジケータを設定し NULL を返します。 exception はPython例外クラスであるべきです。 format と以降の引数はエラーメッセージを作るためのもので, PyString_FromFormat() の引数と同じ意味を持っています。
これは PyErr_SetString(PyExc_TypeError, message) を省略したもので、ここで message は組み込み操作が不正な引数で呼び出されたということを表しています。主に内部で使用するためのものです。
これは PyErr_SetNone(PyExc_MemoryError) を省略したもので、 NULL を返します。したがって、メモリ不足になったとき、オブジェクト割り当て関数は return PyErr_NoMemory(); と書くことができます。
Cライブラリ関数がエラーを返してC変数 errno を設定したときに、これは例外を発生させるために便利な関数です。第一要素が整数 errno 値で、第二要素が (strerror() から得られる)対応するエラーメッセージであるタプルオブジェクトを構成します。それから、 PyErr_SetObject(type, object) を呼び出します。 Unixでは、 errno 値が EINTR であるとき、すなわち割り込まれたシステムコールを表しているとき、これは PyErr_CheckSignals() を呼び出し、それがエラーインジケータを設定した場合は設定されたままにしておきます。関数は常に NULL を返します。したがって、システムコールがエラーを返したとき、システムコールのラッパー関数は return PyErr_SetFromErrno(type); と書くことができます。
PyErr_SetFromErrno() に似ていて、 filename が NULL でない場合に、それが type のコンストラクタに第三引数として渡されるというふるまいが追加されています。 IOError と OSError のような例外の場合では、これが例外インスタンスの filename 属性を定義するために使われます。
これは WindowsError を発生させるために便利な関数です。 0 の ierr とともに呼び出された場合、 GetLastError() が返すエラーコードが代りに使われます。 ierr あるいは GetLastError() によって与えられるエラーコードのWindows用の説明を取り出すために、Win32関数 FormatMessage() を呼び出します。それから、第一要素が ierr 値で第二要素が(FormatMessage() から得られる) 対応するエラーメッセージであるタプルオブジェクトを構成します。そして、 PyErr_SetObject(PyExc_WindowsError, object) を呼び出します。この関数は常に NULL を返します。利用可能範囲: Windows。
PyErr_SetFromWindowsErr() に似ていて、送出する例外の型を指定する引数が追加されています。利用可能範囲: Windows。
バージョン 2.3 で追加.
PyErr_SetFromWindowsErr() に似ていて、 filename が NULL でない場合には WindowsError のコンストラクタへ第三引数として渡されるという振る舞いが追加されています。利用可能範囲: Windows。
PyErr_SetFromWindowsErrWithFilename() に似ていて、発生させる例外の型を指定する引数が追加されています。利用可能範囲: Windows。
バージョン 2.3 で追加.
PyErr_SetString(PyExc_SystemError, message) を省略したものです。ここで message は内部操作(例えば、Python/C API関数)が不正な引数とともに呼び出されたということを示しています。主に内部で使用するためのものです。
警告メッセージを出します。 category 引数は警告カテゴリ(以下を参照) かまたは NULL で、 message 引数はメッセージ文字列です。 stacklevel はフレームの数を示す正の整数です; 警告はそのスタックフレームの中の実行している行から発行されます。 stacklevel が1だと、 PyErr_WarnEx() が、2だとその上の関数が、Warningの発行元になります。
この関数は通常警告メッセージを sys.stderr へプリントします。けれども、ユーザが警告をエラーへ変更するように指定することも可能です。そのような場合には、これは例外を発生させます。警告機構がもつ問題のためにその関数が例外を発生させるということも可能です。(実装ではその厄介な仕事を行うために warnings モジュールをインポートします)。例外が発生させられなければ、戻り値は 0 です。あるいは、例外が発生させられると -1 です。(警告メッセージが実際にプリントされるかどうかを決定することはできず、また何がその例外の原因なのかを決定することもできない。これは意図的なものです。)例外が発生した場合、呼び出し元は通常の例外処理を行います(例えば、 Py_DECREF() は参照を持っており、エラー値を返します)。
警告カテゴリは Warning のサブクラスでなければならない。デフォルト警告カテゴリは RuntimeWarning です。標準Python警告カテゴリは PyExc_ にPython例外名が続く名前のグローバル変数を用いて変更できます。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。それらの名前は PyExc_Warning, PyExc_UserWarning, PyExc_UnicodeWarning, PyExc_DeprecationWarning, PyExc_SyntaxWarning, PyExc_RuntimeWarning, PyExc_FutureWarning です。 PyExc_Warning は PyExc_Exception のサブクラスです。その他の警告カテゴリは PyExc_Warning のサブクラスです。
警告をコントロールするための情報については、 warnings モジュールのドキュメンテーションとコマンドライン・ドキュメンテーションの -W オプションを参照してください。警告コントロールのためのC APIはありません。
警告メッセージを出します。 category 引数は警告カテゴリ(以下を参照) かまたは NULL で、 message 引数はメッセージ文字列です。警告は、 PyErr_WarnEx() を stacklevel に 1 を指定した時と同じく、 PyErr_Warn() を呼び出した関数から発行されます。
非推奨; PyErr_WarnEx() を使って下さい。
すべての警告の属性を明示的に制御した警告メッセージを出します。これはPython関数 warnings.warn_explicit() の直接的なラッパで、さらに情報を得るにはそちらを参照してください。そこに説明されているデフォルトの効果を得るために、 module と registry 引数は NULL に設定することができます。
Issue a DeprecationWarning with the given message and stacklevel if the Py_Py3kWarningFlag flag is enabled. Py_Py3kWarningFlag フラグが有効な場合、与えられた message と stacklevel に応じて DeprecationWarning を発生させます。
バージョン 2.6 で追加.
この関数はPythonのシグナル処理とやりとりすることができます。シグナルがそのプロセスへ送られたかどうかチェックし、そうならば対応するシグナルハンドラを呼び出します。 signal モジュールがサポートされている場合は、これはPythonで書かれたシグナルハンドラを呼び出せます。すべての場合で、 SIGINT のデフォルトの効果は KeyboardInterrupt 例外を発生させることです。例外が発生した場合、エラーインジケータが設定され、関数は -1 を返します。そうでなければ、関数は 0 を返します。エラーインジケータが以前に設定されている場合は、それがクリアされるかどうかわからない。
この関数は廃止されています。 SIGINT シグナルが到達した影響をシミュレートします — 次に PyErr_CheckSignals() が呼ばれるとき、 KeyboardInterrupt は送出されるでしょう。インタプリタロックを保持することなく呼び出すことができます。
このユーティリティ関数は、シグナルを受信したときに '\0' バイトを書き込むファイルディスクリプタを指定します。戻り値は、それまで設定されていたファイルディスクリプタです。 -1 はこの機能を無効にします。これは初期状態です。これは Python の signal.set_wakeup_fd() と同じものですが、エラーチェックを行ないません。 fd は有効なファイルディスクリプタであるべきです。この関数の呼び出しはメインスレッドのみから行われるべきです。
バージョン 2.6 で追加.
このユーティリティ関数は新しい例外オブジェクトを作成して返します。 name 引数は新しい例外の名前、 module.class 形式の C文字列でなければならない。 base と dict 引数は通常 NULL です。これはすべての例外のためのルート、組み込み名 Exception (Cでは PyExc_Exception としてアクセス可能)をルートとして派生したクラスオブジェクトを作成します。
新しいクラスの __module__ 属性は name 引数の前半部分(最後のドットまで)に設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base 引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、クラスのタプルでも構いません。 dict 引数はクラス変数とメソッドの辞書を指定するために使えます。
PyErr_NewException() とほぼ同じですが、新しい例外クラスに簡単に docstring を設定できます。 doc が NULL で無い場合、それが例外クラスの docstring になります。
バージョン 2.7 で追加.
例外が設定されているがインタプリタが実際に例外を発生させることができないときに、このユーティリティ関数は警告メッセージを sys.stderr へプリントします。例えば、例外が __del__() メソッドで発生したときに使われます。
発生させられない例外が生じたコンテキストを特定するための一つの引数 obj とともに関数が呼び出されます。 obj のreprが警告メッセージにプリントされるでしょう。
以下の関数は C言語から Unicode 例外を作ったり修正したりするために利用します。
encoding, object, length, start, end, reason 属性をもった UnicodeDecodeError オブジェクトを作成します。
encoding, object, length, start, end, reason 属性を持った UnicodeEncodeError オブジェクトを作成します。
object, length, start, end, reason 属性を持った UnicodeTranslateError オブジェクトを作成します。
与えられた例外オブジェクトの encoding 属性を返します。
与えられた例外オブジェクトの object 属性を返します。
渡された例外オブジェクトから start 属性を取得して *start に格納します。 start は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。
渡された例外オブジェクトの start 属性を start に設定します。成功したら 0 を、失敗したら -1 を返します。
渡された例外オブジェクトから end 属性を取得して *end に格納します。 end は NULL であってはなりません。成功したら 0 を、失敗したら -1 を返します。
渡された例外オブジェクトの end 属性を end に設定します。成功したら 0 を、失敗したら -1 を返します。
これら2つの関数は C レベルの再帰呼び出しを安全に実行する方法を、コアモジュールにも拡張モジュールにも提供します。再帰を使ったコードが必ずしも Python コードを実行するわけではない場合 (Python コードは再帰の深さを自動的に追跡します)、これらの関数が必要となります。
C レベルの再帰呼び出しをしようとしているところに印を付けます。
USE_STACKCHECK が定義されている場合、 OS のスタックがオーバーフローがしたかどうかを PyOS_CheckStack() を使ってチェックします。もしオーバーフローしているなら、 MemoryError をセットしゼロでない値を返します。
次にこの関数は再帰の上限に達していないかをチェックします。上限に達している場合、 RuntimeError をセットしゼロでない値を返します。そうでない場合はゼロを返します。
再帰の深さの上限に達して送出される RuntimeError のメッセージに連結できるよう where は " in instance check" のような文字列にしてください。
Py_EnterRecursiveCall() を終了させます。 Py_EnterRecursiveCall() の 成功した 呼び出しに対して必ず 1 回呼び出さなければなりません。
PyExc_ の後ろにPythonの例外名が続く名前をもつグローバル変数として、すべての標準Python例外が利用可能です。これらは型 PyObject* を持ち、すべてクラスオブジェクトです。完璧を期するために、すべての変数を以下に列挙します:
| C名 | Python名 | 注記 |
|---|---|---|
| PyExc_BaseException | BaseException | (1), (4) |
| PyExc_Exception | Exception | (1) |
| PyExc_StandardError | StandardError | (1) |
| PyExc_ArithmeticError | ArithmeticError | (1) |
| PyExc_LookupError | LookupError | (1) |
| PyExc_AssertionError | AssertionError | |
| PyExc_AttributeError | AttributeError | |
| PyExc_EOFError | EOFError | |
| PyExc_EnvironmentError | EnvironmentError | (1) |
| PyExc_FloatingPointError | FloatingPointError | |
| PyExc_IOError | IOError | |
| PyExc_ImportError | ImportError | |
| PyExc_IndexError | IndexError | |
| PyExc_KeyError | KeyError | |
| PyExc_KeyboardInterrupt | KeyboardInterrupt | |
| PyExc_MemoryError | MemoryError | |
| PyExc_NameError | NameError | |
| PyExc_NotImplementedError | NotImplementedError | |
| PyExc_OSError | OSError | |
| PyExc_OverflowError | OverflowError | |
| PyExc_ReferenceError | ReferenceError | (2) |
| PyExc_RuntimeError | RuntimeError | |
| PyExc_SyntaxError | SyntaxError | |
| PyExc_SystemError | SystemError | |
| PyExc_SystemExit | SystemExit | |
| PyExc_TypeError | TypeError | |
| PyExc_ValueError | ValueError | |
| PyExc_WindowsError | WindowsError | (3) |
| PyExc_ZeroDivisionError | ZeroDivisionError |
注記:
これは別の標準例外のためのベースクラスです。
これは weakref.ReferenceError と同じです。
Windowsでのみ定義されています。プリプロセッサマクロ MS_WINDOWS が定義されているかテストすることで、これを使うコードを保護してください。
バージョン 2.5 で追加.
バージョン 2.6 で変更: All exceptions to be raised or caught must be derived from BaseException. Trying to raise a string exception now raises TypeError. 発生したりキャッチされる全ての例外は BaseException を継承しなければなりません。 文字列例外を発生させようとすると TypeError が発生されます。
この PyTypeObject のインスタンスは Python のタプル型を表現します。これは Python レイヤにおける list と同じオブジェクトです。
引数が PyListObject である場合に真を返します。
サイズが len 新たなリストオブジェクトを返します。失敗すると NULL を返します。
ノート
len が0より大きいとき、返されるリストオブジェクトの要素には NULL がセットされています。なので、 PyList_SetItem() で本当にオブジェクトをセットするまでは、Pythonコードにこのオブジェクトを渡したり、 PySequence_SetItem() のような抽象APIを利用してはいけません。
バージョン 2.5 で変更: この関数は以前は len の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
リストオブジェクト list の長さを返します; リストオブジェクトにおける len(list) と同じです。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
マクロ形式でできた PyList_Size() で、エラーチェックをしません。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
list の指すリストオブジェクト内の、位置 index にあるオブジェクトを返します。位置は正である必要があり、リスト終端からのインデックスはサポートされていません。 index が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。
バージョン 2.5 で変更: この関数は以前は index の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
マクロ形式でできた PyList_GetItem() で、エラーチェックをしません。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
リストオブジェクト内の位置 index に、オブジェクト item を挿入します。成功した場合には 0 を返し、失敗すると -1 を返します。
ノート
この関数は item への参照を “盗み取り” ます。また、変更先のインデクスにすでに別の要素が入っている場合、その要素に対する参照を放棄します。
バージョン 2.5 で変更: この関数は以前は index の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyList_SetItem() をマクロによる実装で、エラーチェックを行いません。このマクロは、新たなリストのまだ要素を入れたことのない位置に要素を入れるときにのみ使います。
ノート
このマクロは item への参照を “盗み取り” ます。また、 PyList_SetItem() と違って、要素の置き換えが生じても置き換えられるオブジェクトへの参照を放棄 しません ; その結果、 list 中の位置 i で参照されていたオブジェクトがメモリリークを引き起こします。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
要素 item をインデックス index の前に挿入します。成功すると 0 を返します。失敗すると -1 を返し、例外をセットします。 list.insert(index, item) に類似した機能です。
バージョン 2.5 で変更: この関数は以前は index の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
オブジェクト item を list の末尾に追加します。成功すると 0 を返します; 失敗すると -1 を返し、例外をセットします。 list.append(item) に類似した機能です。
list 内の、 low から high の 間の オブジェクトからなるリストを返します。失敗すると NULL を返し、例外をセットします。 list[low:high] に類似した機能です。ただし、 Python のスライスにある負のインデックスはサポートされていません。
バージョン 2.5 で変更: この関数は以前は low, high の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
list 内の、 low から high の間のオブジェクトを、 itemlist の内容にします。 list[low:high] = itemlist と類似の機能です。 itemlist は NULL でもよく、空リストの代入 (指定スライスの削除) になります。成功した場合には 0 を、失敗した場合には -1 を返します。 Python のスライスにある負のインデックスはサポートされていません。
バージョン 2.5 で変更: この関数は以前は low, high の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
list の内容をインプレースでソートします。成功した場合には 0 を、失敗した場合には -1 を返します。 list.sort() と同じです。
filename という名前の標準 I/O ファイル fp が対話的 (interactive) であると考えられる場合に真 (非ゼロ) を返します。これは isatty(fileno(fp)) が真になるファイルの場合です。グローバルなフラグ Py_InteractiveFlag が真の場合には、 filename ポインタが NULL か、名前が '<stdin>' または '???' のいずれかに等しい場合にも真を返します。
プロセスが fork した後の内部状態を更新するための関数です; fork 後 Python インタプリタを使い続ける場合、新たなプロセス内でこの関数を呼び出さねばなりません。新たなプロセスに新たな実行可能物をロードする場合、この関数を呼び出す必要はありません。
インタプリタがスタック空間を使い尽くしたときに真を返します。このチェック関数には信頼性がありますが、 USE_STACKCHECK が定義されている場合 (現状では Microsoft Visual C++ コンパイラでビルドした Windows 版) にしか利用できません . USE_CHECKSTACK は自動的に定義されます; 自前のコードでこの定義を変更してはなりません。
シグナル i に対する現在のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。
シグナル i に対する現在のシグナルハンドラを h に設定します; 以前のシグナルハンドラを返します。この関数は sigaction() または signal() のいずれかに対する薄いラッパです。 sigaction() や signal() を直接呼び出してはなりません! PyOS_sighandler_t は void (*)(int) の typedef による別名です。
sys モジュールが提供している機能にCのコードからアクセスする関数です。すべての関数は現在のインタプリタスレッドの sys モジュールの辞書に対して動作します。この辞書は内部のスレッド状態構造体に格納されています。
sys モジュールの name に関連付けられた FILE* を返します。 name がなかった場合や FILE* に関連付けられていなかった場合は def を返します。
v が NULL で無い場合、 sys モジュールの name に v を設定します。 v が NULL なら、 sys モジュールから name を削除します。成功したら 0 を、エラー時は -1 を返します。
sys.warnoptions を、空リストにリセットします。
sys.warnoptions に s を追加します。
sys.path を path に含まれるパスの、リストオブジェクトに設定します。 path はプラットフォームの検索パスデリミタ(Unixでは :, Windows では ;) で区切られたパスのリストでなければなりません。
format で指定された出力文字列を sys.stdout に出力します。切り詰めが起こった場合を含め、例外は一切発生しません。(後述)
format は、フォーマット後の出力文字列のトータルの大きさを1000バイト以下に抑えるべきです。 – 1000 バイト以降の出力文字列は切り詰められます。特に、制限のない “%s” フォーマットを使うべきではありません。 “%.<N>s” のようにして N に10進数の値を指定し、<N> + その他のフォーマット後の最大サイズが1000を超えないように設定するべきです。同じように “%f” にも気を付ける必要があります。非常に大きい数値に対して、数百の数字を出力する可能性があります。
問題が発生したり、 sys.stdout が設定されていなかった場合、フォーマット後のメッセージは本物の(Cレベルの) stdout に出力されます。
上と同じですが、 sys.stderr か stderr に出力します。
致命的エラーメッセージ (fatal error message) を出力してプロセスを強制終了 (kill) します。後始末処理は行われません。この関数は、Python インタプリタを使い続けるのが危険であるような状況が検出されたとき; 例えば、オブジェクト管理が崩壊していると思われるときにのみ、呼び出されるようにしなければなりません。Unixでは、標準 C ライブラリ関数 abort() を呼び出して core を生成しようと試みます。
現在のプロセスを終了 (exit) します。この関数は Py_Finalize() を呼び出し、次いで標準 C ライブラリ関数 exit(status) を呼び出します。
Py_Finalize() から呼び出される後始末処理を行う関数 (cleanup function) を登録します。後始末関数は引数無しで呼び出され、値を返しません。最大で 32 の後始末処理関数を登録できます。登録に成功すると、 Py_AtExit() は 0 を返します; 失敗すると -1 を返します。最後に登録した後始末処理関数から先に呼び出されます。各関数は高々一度しか呼び出されません。 Python の内部的な終了処理は後始末処理関数より以前に完了しているので、 func からはいかなる Python API も呼び出してはなりません。
この章で説明する関数は、オブジェクトの型に依存しないような Python オブジェクトの操作や、(数値型全て、シーケンス型全てといった)大まかな型のオブジェクトに対する操作を行ないます。関数を適用対象でないオブジェクトに対して使った場合、 Python の例外が送出されることになります。
これらの関数は、 PyList_New() で作成された後に NULL 以外の値を設定されていないリストのような、適切に初期化されていないオブジェクトに対して使うことはできません。
オブジェクトがマップ型プロトコルを提供している場合に 1 を返し、そうでないときには 0 を返します。この関数呼び出しは常に成功します。
成功するとオブジェクト o 中のキーの数を返し、失敗すると -1 を返します。マップ型プロトコルを提供していないオブジェクトに対しては、 Python の式 len(o) と同じになります。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
オブジェクト o から key に関する対応付けを削除します。失敗すると -1 を返します。 Python の文 del o[key] と同じです。
オブジェクト o から key に対する対応付けを削除します。失敗すると -1 を返します。 Python の文 del o[key] と同じです。
成功すると、マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。これは、 o[key] が成功したときに True を、例外が発生したときに False を返すのと等価です。この関数呼び出しは常に成功します。
マップ型オブジェクトがキー key を持つ場合に 1 を返し、そうでないときには 0 を返します。これは、 o[key] が成功したときに True を、例外が発生したときに False を返すのと等価です。この関数呼び出しは常に成功します。
成功するとオブジェクト o のキーからなるリストを返します。失敗すると NULL を返します。 Python の式 o.keys() と同じです。
成功するとオブジェクト o のキーに対応する値からなるリストを返します。失敗すると NULL を返します。 Python の式 o.values() と同じです。
成功するとオブジェクト o の要素対、すなわちキーと値のペアが入ったタプルからなるリストを返します。失敗すると NULL を返します。 Python の式 o.items() と同じです。
この PyTypeObject のインスタンスは Python の辞書を表現します。このオブジェクトは、Python プログラムには dict および types.DictType として公開されています。
引数が PyDictObject のときに真を返します。
あるマップ型オブジェクトに対して、読み出し専用に制限されたプロキシオブジェクト (proxy object) を返します。通常、この関数は動的でないクラス型 (non-dynamic class type) のクラス辞書を変更させないためにプロキシを作成するために使われます。
バージョン 2.2 で追加.
辞書 p に key が入っているか判定します。 p の要素が key に一致した場合は 1 を返し、それ以外の場合には 0 を返します。エラーの場合 -1 を返します。この関数は Python の式 key in p と等価です。
バージョン 2.4 で追加.
p と同じキーと値のペアが入った新たな辞書を返します。
バージョン 1.6 で追加.
辞書 p に、 key をキーとして値 value を挿入します。 key はハッシュ可能(hashable)でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。
辞書 p に、 key をキーとして値 value を挿入します。 key は char* 型でなければなりません。キーオブジェクトは PyString_FromString(key) で生成されます。成功した場合には 0 を、失敗した場合には -1 を返します。
辞書 p から key をキーとするエントリを除去します。 key はハッシュ可能でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。成功した場合には 0 を、失敗した場合には -1 を返します。
辞書 p から文字列 key をキーとするエントリを除去します。成功した場合には 0 を、失敗した場合には -1 を返します。
辞書 p 内で key をキーとするオブジェクトを返します。キー key が存在しない場合には NULL を返しますが、例外をセット しません 。
PyDict_GetItem() と同じですが、 key は PyObject* ではなく char* で指定します。
辞書オブジェクトのメソッド item() のように、辞書内の全ての要素対が入った PyListObject を返します。 (items() については Python ライブラリリファレンス (XXX reference: ../lib/lib.html) を参照してください。)
辞書オブジェクトのメソッド keys() のように、辞書内の全てのキーが入った PyListObject を返します。 (keys() については Python ライブラリリファレンス (XXX reference: ../lib/lib.html) を参照してください。)
辞書オブジェクトのメソッド values() のように、辞書内の全ての値が入った PyListObject を返します。 (values() については Python ライブラリリファレンス (XXX reference: ../lib/lib.html) を参照してください。)
辞書内の要素の数を返します。辞書に対して len(p) を実行するのと同じです。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
辞書 p 内の全てのキー/値のペアにわたる反復処理を行います。 ppos が参照している Py_ssize_t 型は、この関数で反復処理を開始する際に、最初に関数を呼び出すよりも前に 0 に初期化しておかなければなりません; この関数は辞書内の各ペアを取り上げるごとに真を返し、全てのペアを取り上げたことが分かると偽を返します。パラメタ pkey および pvalue には、それぞれ辞書の各々のキーと値を指すポインタか、または NULL が入ります。この関数から返される参照はすべて借りた参照になります。反復処理中に ppos を変更してはなりません。この値は内部的な辞書構造体のオフセットを表現しており、構造体はスパースなので、オフセットの値に一貫性がないためです。
以下に例を示します:
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
/* 取り出した値で何らかの処理を行う... */
...
}
反復処理中に辞書 p を変更してはなりません。 (Python 2.1 からは) 辞書を反復処理する際に、キーに対応する値を変更しても大丈夫になりましたが、キーの集合を変更しないことが前提です。以下に例を示します:
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
int i = PyInt_AS_LONG(value) + 1;
PyObject *o = PyInt_FromLong(i);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}
バージョン 2.5 で変更: この関数は以前は ppos の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
マップ型オブジェクト b の全ての要素にわたって、反復的にキー/値のペアを辞書 a に追加します。 b は辞書か、 PyMapping_Keys() または PyObject_GetItem() をサポートする何らかのオブジェクトにできます。 override が真ならば、 a のキーと一致するキーが b にある際に、既存のペアを置き換えます。それ以外の場合は、 b のキーに一致するキーが a にないときのみ追加を行います。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。
バージョン 2.2 で追加.
C で表せば PyDict_Merge(a, b, 1) と同じ、 Python で表せば a.update(b) と同じです。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。
バージョン 2.2 で追加.
seq2 内のキー/値ペアを使って、辞書 a の内容を更新したり統合したりします。 seq2 は、キー/値のペアとみなせる長さ 2 の反復可能オブジェクト(iterable object) を生成する反復可能オブジェクトでなければなりません。重複するキーが存在する場合、 override が真ならば先に出現したキーを使い、そうでない場合は後に出現したキーを使います。成功した場合には 0 を返し、例外が送出された場合には -1 を返します。
(戻り値以外は) 等価な Python コードを書くと、以下のようになります:
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value
バージョン 2.2 で追加.
Python のアプリケーションプログラマ用インタフェース (Application Programmer’s Interface, API) は、 Python インタプリタに対する様々なレベルでのアクセス手段を C や C++ のプログラマに提供しています。この API は通常 C++ からも全く同じように利用できるのですが、簡潔な呼び名にするために Python/C API と名づけられています。根本的に異なる二つの目的から、 Python/C API が用いられます。第一は、特定用途の 拡張モジュール (extention module) 、すなわち Python インタプリタを拡張する C で書かれたモジュールを記述する、という目的です。第二は、より大規模なアプリケーション内で Python を構成要素 (component) として利用するという目的です; このテクニックは、一般的にはアプリケーションへの Python の埋め込み (embedding) と呼びます。拡張モジュールの作成は比較的わかりやすいプロセスで、 “手引書 (cookbook)” 的なアプローチでうまく実現できます。作業をある程度まで自動化してくれるツールもいくつかあります。一方、他のアプリケーションへの Python の埋め込みは、Python ができてから早い時期から行われてきましたが、拡張モジュールの作成に比べるとやや難解です。
多くの API 関数は、Python の埋め込みであるか拡張であるかに関わらず役立ちます; とはいえ、 Python を埋め込んでいるほとんどのアプリケーションは、同時に自作の拡張モジュールも提供する必要が生じることになるでしょうから、Python を実際にアプリケーションに埋め込んでみる前に拡張モジュールの書き方に詳しくなっておくのはよい考えだと思います。
Python/C API を使うために必要な、関数、型およびマクロの全ての定義をインクルードするには、以下の行:
#include "Python.h"
をソースコードに記述します。この行を記述すると、標準ヘッダ: <stdio.h>, <string.h>, <errno.h>, <limits.h>, <assert.h>, <stdlib.h> を (利用できれば) インクルードします。
ノート
システムによっては、Python の定義しているプリプロセッサ定義が標準ヘッダに影響をおよぼす可能性があるので、 Python.h は他の標準ヘッダファイルよりも前にインクルードしてください。
Python.h で定義されている、ユーザから見える名前全て (Python.h がインクルードしている標準ヘッダの名前は除きます) には、接頭文字列 Py または _Py が付きます。 _Py で始まる名前は Python 実装で内部使用するための名前で、拡張モジュールの作者は使ってはなりません。構造体のメンバには予約済みの接頭文字列はありません。
重要: API のユーザは、 Py や _Py で始まる名前を定義するようなコードを絶対に書いてはなりません。後からコードを読む人を混乱させたり、将来の Python のバージョンで同じ名前が定義されて、ユーザの書いたコードの可搬性を危うくする可能性があります。
ヘッダファイル群は通常 Python と共にインストールされます。 Unixでは prefix/include/pythonversion/ および exec_prefix/include/pythonversion/ に置かれます。 prefix と exec_prefix は Python をビルドする際の configure スクリプトに与えたパラメタに対応し、 version は sys.version[:3] に対応します。 Windows では、ヘッダは prefix/include に置かれます。 prefix はインストーラに指定したインストールディレクトリです。
ヘッダをインクルードするには、各ヘッダの入ったディレクトリ (別々のディレクトリの場合は両方) を、コンパイラがインクルードファイルを検索するためのパスに入れます。親ディレクトリをサーチパスに入れて、 #include <pythonX.Y/Python.h> のようにしては なりません ; prefix 内のプラットフォームに依存しないヘッダは、 exec_prefix からプラットフォーム依存のヘッダをインクルードしているので、このような操作を行うと複数のプラットフォームでのビルドができなくなります。
API はすべて C 言語を使って定義していますが、ヘッダファイルはエントリポイントを extern "C" で適切に宣言しているので、 C++ ユーザは、なんの問題もなく C++から API を利用できることに気づくはずです。
Python/C API 関数は、 PyObject* 型の一つ以上の引数と戻り値を持ちます。この型は、任意の Python オブジェクトを表現する不透明 (opaque) なデータ型へのポインタです。 Python 言語は、全ての Python オブジェクト型をほとんどの状況 (例えば代入、スコープ規則 (scope rule)、引数渡し) で同様に扱います。ほとんど全ての Python オブジェクトはヒープ (heap) 上に置かれます: このため、 PyObject 型のオブジェクトは、自動記憶 (automatic) としても静的記憶 (static) としても宣言できません。 PyObject* 型のポインタ変数のみ宣言できます。唯一の例外は、型オブジェクトです; 型オブジェクトはメモリ解放 (deallocate) してはならないので、通常は静的記憶の PyTypeObject オブジェクトにします。
全ての Python オブジェクトには (Python 整数型ですら) 型 (type) と参照カウント (reference count) があります。あるオブジェクトの型は、そのオブジェクトがどの種類のオブジェクトか (例えば整数、リスト、ユーザ定義関数、など; その他多数については 標準型の階層 で説明しています) を決定します。よく知られている型については、各々マクロが存在して、あるオブジェクトがその型かどうか調べられます; 例えば、 PyList_Check(a) は、 a で示されたオブジェクトが Python リスト型のとき (かつそのときに限り) 真値を返します。
今日の計算機は有限の (しばしば非常に限られた) メモリサイズしか持たないので、参照カウントは重要な概念です; 参照カウントは、あるオブジェクトに対して参照を行っている場所が何箇所あるかを数える値です。参照を行っている場所とは、別のオブジェクトであったり、グローバルな (あるいは静的な) C 変数であったり、何らかの C 関数内にあるローカルな変数だったりします。あるオブジェクトの参照カウントがゼロになると、そのオブジェクトは解放されます。そのオブジェクトに他のオブジェクトへの参照が入っていれば、他のオブジェクトの参照カウントはデクリメントされます。デクリメントの結果、他のオブジェクトの参照カウントがゼロになると、今度はそのオブジェクトが解放される、といった具合に以後続きます。(言うまでもなく、互いを参照しあうオブジェクトについて問題があります; 現状では、解決策は “何もしない” です。)
参照カウントは、常に明示的なやり方で操作されます。通常の方法では、 Py_INCREF() でオブジェクトの参照を 1 インクリメントし、 Py_DECREF() で 1 デクリメントします。 Py_DECREF() マクロは、incref よりもかなり複雑です。というのは、 Py_DECREF() マクロは参照カウントがゼロになったかどうかを調べて、なった場合にはオブジェクトのデアロケータ (deallocator) を呼び出さなければならないからです。デアロケータとは、オブジェクトの型を定義している構造体内にある関数へのポインタです。型固有のデアロケータは、その型が複合オブジェクト (compound object) 型である場合には、オブジェクト内の他のオブジェクトに対する参照カウントをデクリメントするよう気を配るとともに、その他の必要なファイナライズ (finalize) 処理を実行します。参照カウントがオーバフローすることはありません; というのも、仮想メモリ空間には、(sizeof(Py_ssize_t) >= sizeof(char*) と仮定した場合) 少なくとも参照カウントの記憶に使われるビット数と同じだけのメモリ上の位置があるからです。従って、参照カウントのインクリメントは単純な操作になります。
オブジェクトへのポインタが入っているローカルな変数全てについて、オブジェクトの参照カウントを必ずインクリメントしなければならないわけではありません。理論上は、オブジェクトの参照カウントは、オブジェクトを指し示す変数が生成されたときに 1 増やされ、その変数がスコープから出て行った際に 1 減らされます。しかしこの場合、二つの操作は互いに相殺するので、結果的に参照カウントは変化しません。参照カウントを使う真の意義とは、手持ちの何らかの変数がオブジェクトを指している間はオブジェクトがデアロケートされないようにすることにあります。オブジェクトに対して、一つでも別の参照が行われていて、その参照が手持ちの変数と同じ間維持されるのなら、参照カウントを一時的に増やす必要はありません。参照カウント操作の必要性が浮き彫りになる重要な局面とは、Python から呼び出された拡張モジュール内の C 関数にオブジェクトを引数として渡すときです; 呼び出しメカニズムは、呼び出しの間全ての引数に対する参照を保証します。
しかしながら、よく陥る過ちとして、あるオブジェクトをリストから得たときに、参照カウントをインクリメントせずにしばらく放っておくというのがあります。他の操作がオブジェクトをリストから除去してしまい、参照カウントがデクリメントされてデアロケートされてしまうことが考えられます。本当に危険なのは、まったく無害そうにみえる操作が、上記の動作を引き起こす何らかの Python コードを呼び出しかねないということです; Py_DECREF() からユーザへ制御を戻せるようなコードパスが存在するため、ほとんど全ての操作が潜在的に危険をはらむことになります。
安全に参照カウントを操作するアプローチは、汎用の操作 (関数名が PyObject_, PyNumber_, PySequence_, および PyMapping_ で始まる関数) の利用です。これらの操作は常に戻り値となるオブジェクトの参照カウントをインクリメントします。ユーザには戻り値が不要になったら Py_DECREF() を呼ぶ責任が残されています; とはいえ、すぐにその習慣は身に付くでしょう。
Python/C API の各関数における参照カウントの振る舞いは、説明するには、 参照の所有権 (ownership of references) という言葉でうまく説明できます。所有権は参照に対するもので、オブジェクトに対するものではありません (オブジェクトは誰にも所有されず、常に共有されています)。ある参照の “所有” は、その参照が必要なくなった時点で Py_DECREF() を呼び出す役割を担うことを意味します。所有権は委譲でき、あるコードが委譲によって所有権を得ると、今度はそのコードが参照が必要なくなった際に最終的に Py_DECREF() や Py_XDECREF() を呼び出して decref する役割を担います — あるいは、その役割を (通常はコードを呼び出した元に) 受け渡します。ある関数が、関数の呼び出し側に対して参照の所有権を渡すと、呼び出し側は 新たな 参照 (new reference) を得る、と言います。所有権が渡されない場合、呼び出し側は参照を 借りる (borrow) といいます。借りた参照に対しては、何もする必要はありません。
逆に、ある関数呼び出しで、あるオブジェクトへの参照を呼び出される関数に渡す際には、二つの可能性: 関数がオブジェクトへの参照を 盗み取る (steal) 場合と、そうでない場合があります。
参照を盗む とは、関数に参照を渡したときに、参照の所有者がその関数になったと仮定し、関数の呼び出し元には所有権がなくなるということです。
参照を盗み取る関数はほとんどありません; 例外としてよく知られているのは、 PyList_SetItem() と PyTuple_SetItem() で、これらはシーケンスに入れる要素に対する参照を盗み取ります (しかし、要素の入る先のタプルやリストの参照は盗み取りません!)。これらの関数は、リストやタプルの中に新たに作成されたオブジェクトを入れていく際の常套的な書き方をしやすくするために、参照を盗み取るように設計されています; 例えば、 (1, 2, "three") というタプルを生成するコードは以下のようになります (とりあえず例外処理のことは忘れておきます; もっとよい書き方を後で示します):
PyObject *t;
t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
ここで、 PyInt_FromLong() は新しい参照を返し、すぐに PyTuple_SetItem() に盗まれます。参照が盗まれた後もそのオブジェクトを利用したい場合は、参照盗む関数を呼び出す前に、 Py_INCREF() を利用してもう一つの参照を取得してください。
ちなみに、 PyTuple_SetItem() はタプルに値をセットするための 唯一の 方法です; タプルは変更不能なデータ型なので、 PySequence_SetItem() や PyObject_SetItem() を使うと上の操作は拒否されてしまいます。自分でタプルの値を入れていくつもりなら、 PyTuple_SetItem() だけしか使えません。
同じく、リストに値を入れていくコードは PyList_New() と PyList_SetItem() で書けます。
しかし実際には、タプルやリストを生成して値を入れる際には、上記のような方法はほとんど使いません。より汎用性のある関数、 Py_BuildValue() があり、ほとんどの主要なオブジェクトをフォーマット文字列 format string の指定に基づいて C の値から生成できます。例えば、上の二種類のコードブロックは、以下のように置き換えられます (エラーチェックにも配慮しています):
PyObject *tuple, *list;
tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
自作の関数に渡す引数のように、単に参照を借りるだけの要素に対しては、 PyObject_SetItem() とその仲間を使うのがはるかに一般的です。その場合、参照カウントをインクリメントする必要がなく、参照を引き渡せる (“参照を盗み取らせられる”) ので、参照カウントに関する動作はより健全になります。例えば、以下の関数は与えられた要素をリスト中の全ての要素の値にセットします:
int
set_all(PyObject *target, PyObject *item)
{
int i, n;
n = PyObject_Length(target);
if (n < 0)
return -1;
for (i = 0; i < n; i++) {
PyObject *index = PyInt_FromLong(i);
if (!index)
return -1;
if (PyObject_SetItem(target, index, item) < 0)
return -1;
Py_DECREF(index);
}
return 0;
}
関数の戻り値の場合には、状況は少し異なります。ほとんどの関数については、参照を渡してもその参照に対する所有権が変わることがない一方で、あるオブジェクトに対する参照を返すような多くの関数は、参照に対する所有権を呼び出し側に与えます。理由は簡単です: 多くの場合、関数が返すオブジェクトはその場で (on the fly) 生成されるため、呼び出し側が得る参照は生成されたオブジェクトに対する唯一の参照になるからです。従って、 PyObject_GetItem() や PySequence_GetItem() のように、オブジェクトに対する参照を返す汎用の関数は、常に新たな参照を返します (呼び出し側が参照の所有者になります)。
重要なのは、関数が返す参照の所有権を持てるかどうかは、どの関数を呼び出すかだけによる、と理解することです — 関数呼び出し時の お飾り (関数に引数として渡したオブジェクトの型) は この問題には関係ありません! 従って、 PyList_GetItem() を使ってリスト内の要素を得た場合には、参照の所有者にはなりません — が、同じ要素を同じリストから PySequence_GetItem() (図らずもこの関数は全く同じ引数をとります) を使って取り出すと、返されたオブジェクトに対する参照を得ます。
以下は、整数からなるリストに対して各要素の合計を計算する関数をどのようにして書けるかを示した例です; 一つは PyList_GetItem() を使っていて、もう一つは PySequence_GetItem() を使っています。
long
sum_list(PyObject *list)
{
int i, n;
long total = 0;
PyObject *item;
n = PyList_Size(list);
if (n < 0)
return -1; /* リストではない */
for (i = 0; i < n; i++) {
item = PyList_GetItem(list, i); /* 失敗しないはず */
if (!PyInt_Check(item)) continue; /* 整数でなければ読み飛ばす */
total += PyInt_AsLong(item);
}
return total;
}
long
sum_sequence(PyObject *sequence)
{
int i, n;
long total = 0;
PyObject *item;
n = PySequence_Length(sequence);
if (n < 0)
return -1; /* 長さの概念がない */
for (i = 0; i < n; i++) {
item = PySequence_GetItem(sequence, i);
if (item == NULL)
return -1; /* シーケンスでないか、その他の失敗 */
if (PyInt_Check(item))
total += PyInt_AsLong(item);
Py_DECREF(item); /* GetItem で得た所有権を放棄する */
}
return total;
}
Python プログラマは、特定のエラー処理が必要なときだけしか例外を扱う必要はありません; 処理しなかった例外は、処理の呼び出し側、そのまた呼び出し側、といった具合に、トップレベルのインタプリタ層まで自動的に伝播します。インタプリタ層は、スタックトレースバックと合わせて例外をユーザに報告します。
ところが、 C プログラマの場合、エラーチェックは常に明示的に行わねばなりません。 Python/C API の全ての関数は、関数のドキュメントで明確に説明がない限り例外を発行する可能性があります。一般的な話として、ある関数が何らかのエラーに遭遇すると、関数は例外を設定して、関数内における参照の所有権を全て放棄し、エラー値(error indicator)を返します。ドキュメントに書かれてない場合、このエラー値は関数の戻り値の型にによって、 NULL か -1 のどちらかになります。いくつかの関数ではブール型で真/偽を返し、偽はエラーを示します。きわめて少数の関数では明確なエラー指標を返さなかったり、あいまいな戻り値を返したりするので、 PyErr_Occurred() で明示的にエラーテストを行う必要があります。これらの例外は常に明示的にドキュメント化されます。
例外時の状態情報 (exception state)は、スレッド単位に用意された記憶領域 (per-thread storage) 内で管理されます (この記憶領域は、スレッドを使わないアプリケーションではグローバルな記憶領域と同じです)。一つのスレッドは二つの状態のどちらか: 例外が発生したか、まだ発生していないか、をとります。関数 PyErr_Occurred() を使うと、この状態を調べられます: この関数は例外が発生した際にはその例外型オブジェクトに対する借用参照 (borrowed reference) を返し、そうでないときには NULL を返します。例外状態を設定する関数は数多くあります: PyErr_SetString() はもっともよく知られている (が、もっとも汎用性のない) 例外を設定するための関数で、 PyErr_Clear() は例外状態情報を消し去る関数です。
完全な例外状態情報は、3 つのオブジェクト: 例外の型、例外の値、そしてトレースバック、からなります (どのオブジェクトも NULL を取り得ます)。これらの情報は、 Python オブジェクトの sys.exc_type, sys.exc_value, および sys.exc_traceback と同じ意味を持ちます; とはいえ、 C と Python の例外状態情報は全く同じではありません: Python における例外オブジェクトは、Python の try ... except 文で最近処理したオブジェクトを表す一方、 C レベルの例外状態情報が存続するのは、渡された例外情報を sys.exc_type その他に転送するよう取り計らう Python のバイトコードインタプリタのメインループに到達するまで、例外が関数の間で受け渡しされている間だけです。
Python 1.5 からは、Python で書かれたコードから例外状態情報にアクセスする方法として、推奨されていてスレッドセーフな方法は sys.exc_info() になっているので注意してください。この関数は Python コードの実行されているスレッドにおける例外状態情報を返します。また、これらの例外状態情報に対するアクセス手段は、両方とも意味づけ (semantics) が変更され、ある関数が例外を捕捉すると、その関数を実行しているスレッドの例外状態情報を保存して、呼び出し側の呼び出し側の例外状態情報を維持するようになりました。この変更によって、無害そうに見える関数が現在扱っている例外を上書きすることで引き起こされる、例外処理コードでよくおきていたバグを抑止しています; また、トレースバック内のスタックフレームで参照されているオブジェクトがしばしば不必要に寿命を永らえていたのをなくしています。
一般的な原理として、ある関数が別の関数を呼び出して何らかの作業をさせるとき、呼び出し先の関数が例外を送出していないか調べなくてはならず、もし送出していれば、その例外状態情報は呼び出し側に渡されなければなりません。呼び出し元の関数はオブジェクト参照の所有権をすべて放棄し、エラー指標を返さなくてはなりませんが、余計に例外を設定する必要は ありません — そんなことをすれば、たった今送出されたばかりの例外を上書きしてしまい、エラーの原因そのものに関する重要な情報を失うことになります。
例外を検出して渡す例は、上の sum_sequence() で示しています。偶然にも、この例ではエラーを検出した際に何ら参照を放棄する必要がありません。以下の関数の例では、エラーに対する後始末について示しています。まず、どうして Python で書くのが好きか思い出してもらうために、等価な Python コードを示します:
def incr_item(dict, key):
try:
item = dict[key]
except KeyError:
item = 0
dict[key] = item + 1
以下は対応するコードを C で完璧に書いたものです:
int
incr_item(PyObject *dict, PyObject *key)
{
/* Py_XDECREF 用に全てのオブジェクトを NULL で初期化 */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* 戻り値の初期値を -1 (失敗) に設定しておく */
item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* KeyError だけを処理: */
if (!PyErr_ExceptionMatches(PyExc_KeyError))
goto error;
/* エラーを無かったことに (clear) してゼロを使う: */
PyErr_Clear();
item = PyInt_FromLong(0L);
if (item == NULL)
goto error;
}
const_one = PyInt_FromLong(1L);
if (const_one == NULL)
goto error;
incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL)
goto error;
if (PyObject_SetItem(dict, key, incremented_item) < 0)
goto error;
rv = 0; /* うまくいった場合 */
/* 後始末コードに続く */
error:
/* 成功しても失敗しても使われる後始末コード */
/* NULL を参照している場合は無視するために Py_XDECREF() を使う */
Py_XDECREF(item);
Py_XDECREF(const_one);
Py_XDECREF(incremented_item);
return rv; /* エラーなら -1 、成功なら 0 */
}
なんとこの例は C で goto 文を使うお勧めの方法まで示していますね! この例では、特定の例外を処理するために PyErr_ExceptionMatches() および PyErr_Clear() をどう使うかを示しています。また、所有権を持っている参照で、値が NULL になるかもしれないものを捨てるために Py_XDECREF() をどう使うかも示しています (関数名に 'X' が付いていることに注意してください; Py_DECREF() は NULL 参照に出くわすとクラッシュします)。正しく動作させるためには、所有権を持つ参照を保持するための変数を NULL で初期化することが重要です; 同様に、あらかじめ戻り値を定義する際には値を -1 (失敗) で初期化しておいて、最後の関数呼び出しまでうまくいった場合にのみ 0 (成功) に設定します。
Python インタプリタの埋め込みを行う人 (いわば拡張モジュールの書き手の対極) が気にかけなければならない重要なタスクは、 Python インタプリタの初期化処理 (initialization)、そしておそらくは終了処理 (finalization) です。インタプリタのほとんどの機能は、インタプリタの起動後しか使えません。
基本的な初期化処理を行う関数は Py_Initialize() です。この関数はロード済みのモジュールからなるテーブルを作成し、土台となるモジュール __builtin__, __main__, sys, および exceptions を作成します。また、モジュール検索パス (sys.path) の初期化も行います。
Py_Initialize() の中では、 “スクリプトへの引数リスト” (script argument list, sys.argv のこと) を設定しません。この変数が後に実行される Python コード中で必要なら、 Py_Initialize() の後で PySys_SetArgvEx(argc, argv, updatepath) を呼び出して明示的に設定しなければなりません。
ほとんどのシステムでは (特に Unix と Windows は、詳細がわずかに異なりはしますが)、 Py_Initialize() は標準の Python インタプリタ実行形式の場所に対する推定結果に基づいて、 Python のライブラリが Python インタプリタ実行形式からの相対パスで見つかるという仮定の下にモジュール検索パスを計算します。とりわけこの検索では、シェルコマンド検索パス (環境変数 PATH) 上に見つかった python という名前の実行ファイルの置かれているディレクトリの親ディレクトリからの相対で、 lib/pythonX.Y という名前のディレクトリを探します。
例えば、 Python 実行形式が /usr/local/bin/python で見つかったとすると、 Py_Initialize() はライブラリが /usr/local/lib/pythonX.Y にあるものと仮定します。 (実際には、このパスは “フォールバック (fallback)” のライブラリ位置でもあり、 python が PATH 上にない場合に使われます。) ユーザは PYTHONHOME を設定することでこの動作をオーバライドしたり、 PYTHONPATH を設定して追加のディレクトリを標準モジュール検索パスの前に挿入したりできます。
埋め込みを行うアプリケーションでは、 Py_Initialize() を呼び出す 前に Py_SetProgramName(file) を呼び出すことで、上記の検索を操作できます。この埋め込みアプリケーションでの設定は依然として PYTHONHOME でオーバライドでき、標準のモジュール検索パスの前には以前として PYTHONPATH が挿入されるので注意してください。アプリケーションでモジュール検索パスを完全に制御したいのなら、独自に Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), および Py_GetProgramFullPath() の実装を提供しなければなりません (これらは全て Modules/getpath.c で定義されています)。
たまに、 Python を “初期化しない” ようにしたいことがあります。例えば、あるアプリケーションでは実行を最初からやりなおし (start over) させる (Py_Initialize() をもう一度呼び出させる) ようにしたいかもしれません。あるいは、アプリケーションが Python を一旦使い終えて、Python が確保したメモリを解放できるようにしたいかもしれません。 Py_Finalize() を使うと、こうした処理を実現できます。また、関数 Py_IsInitialized() は、Python が現在初期化済みの状態にある場合に真を返します。これらの関数についてのさらなる情報は、後の章で説明します。 Py_Finalize() がPythonインタプリタに確保された全てのメモリを 開放するわけではない ことに注意してください。例えば、拡張モジュールによって確保されたメモリは、現在のところ開放する事ができません。
インタプリタと拡張モジュールに対しての追加チェックをするためのいくつかのマクロを有効にしてPythonをビルドすることができます。これらのチェックは、実行時に大きなオーバーヘッドを生じる傾向があります。なので、デフォルトでは有効にされていません。
Pythonデバッグ版ビルドの全ての種類のリストが、Pythonソース配布(source distribution)の中の Misc/SpecialBuilds.txt にあります。参照カウントのトレース、メモリアロケータのデバッグ、インタプリタのメインループの低レベルプロファイリングが利用可能です。よく使われるビルドについてのみ、この節の残りの部分で説明します。
インタプリタを Py_DEBUG マクロを有効にしてコンパイルすると、一般的に「デバッグビルド」といわれるPythonができます。 Unix では、 configure コマンドに --with-pydebug を追加することで、 Py_DEBUG が有効になります。その場合、暗黙的にPython専用ではない _DEBUG も有効になります。 Unix ビルドでは、 Py_DEBUG が有効な場合、コンパイラの最適化が無効になります。
あとで説明する参照カウントデバッグの他に、以下の追加チェックも有効になります。
ここで言及されていない追加チェックもあるでしょう。
Py_TRACE_REFS を宣言すると、参照トレースが有効になります。全ての PyObject に二つのフィールドを追加することで、使用中のオブジェクトの循環二重連結リストが管理されます。全ての割り当て(allocation)がトレースされます。終了時に、全ての残っているオブジェクトが表示されます。 (インタラクティブモードでは、インタプリタによる文の実行のたびに表示されます) Py_TRACE_REFS は Py_DEBUG によって暗黙的に有効になります。
より詳しい情報については、Pythonのソース配布(source distribution)の中の Misc/SpecialBuilds.txt を参照してください。
ジェネレータ (generator) オブジェクトは、 Python がジェネレータ型イテレータを実装するために使っているオブジェクトです。ジェネレータオブジェクトは、通常、 PyGen_New() で明示的に生成されることはなく、値を逐次生成するような関数に対してイテレーションを行うときに生成されます。
ジェネレータオブジェクトに使われている C 構造体です。
ジェネレータオブジェクトに対応する型オブジェクトです。
ob がジェネレータオブジェクトの場合に真を返します。 ob が NULL であってはなりません。
ob の型が PyGen_Type の場合に真を返します。 ob が NULL であってはなりません。
警告
CObject API は Python 2.7 から非推奨になりました。新しい カプセル (Capsules) APIへ移行してください。
この PyObject のサブタイプは不透明型値 (opaque value) を表現します。C 拡張モジュールが Python コードから不透明型値を (void* ポインタで) 他の C コードに渡す必要があるときに便利です。正規の import 機構を使って動的にロードされるモジュール内で定義されている C API にアクセスするために、あるモジュール内で定義されている C 関数ポインタを別のモジュールでも利用できるようにするためによく使われます。
void* cobj から PyCObject を生成します。関数 destr が NULL でない場合、オブジェクトを再利用する際に呼び出します。
以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト型です:
この型は Unicode 序数 (Unicode ordinal) を保持するための基礎単位として、 Python が内部的に使います。 Python のデフォルトのビルドでは、 Py_UNICODE として 16-bit 型を利用し、 Unicode の値を内部では UCS-2 で保持します。 UCS4 版の Python をビルドすることもできます。(最近の多くの Linux ディストリビューションでは UCS4 版の Python がついてきます) UCS4 版ビルドでは Py_UNICODE に 32-bit 型を利用し、内部では Unicode データを UCS4 で保持します。 wchar_t が利用できて、 Python の Unicode に関するビルドオプションと一致するときは、 Py_UNICODE は wchar_t を typedef でエイリアスされ、ネイティブプラットフォームに対する互換性を高めます。それ以外のすべてのプラットフォームでは、 Py_UNICODE は unsigned short (UCS2) か unsigned long (UCS4) の typedef によるエイリアスになります。
UCS2 と UCS4 の Python ビルドの間にはバイナリ互換性がないことに注意してください。拡張やインタフェースを書くときには、このことを覚えておいてください。
この PyTypeObject のインスタンスは Python の Unicode 型を表します。 Python レイヤにおける unicode や types.UnicodeType と同じオブジェクトです。
以下の API は実際には C マクロで、Unicode オブジェクト内部の読み出し専用データに対するチェックやアクセスを高速に行います:
o が Unicode 文字列型か Unicode 文字列型のサブタイプであるときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
o が Unicode 文字列型で、かつ Unicode 文字列型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
オブジェクトのサイズを返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
オブジェクトの内部バッファのサイズをバイト数で返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
オブジェクト内部の Py_UNICODE バッファへのポインタを返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。
オブジェクト内部バッファへのポインタを返します。 o は PyUnicodeObject でなければなりません (チェックはしません)。
free list をクリアします。開放できなかった要素数を返します。
バージョン 2.6 で追加.
Unicode は数多くの異なる文字プロパティ (character property) を提供しています。よく使われる文字プロパティは、以下のマクロで利用できます。これらのマクロは Python の設定に応じて、各々 C の関数に対応付けられています。
ch が空白文字かどうかに応じて 1 または 0 を返します。
ch が小文字かどうかに応じて 1 または 0 を返します。
ch が大文字かどうかに応じて 1 または 0 を返します。
ch がタイトルケース文字 (titlecase character) かどうかに応じて 1 または 0 を返します。
ch が改行文字かどうかに応じて 1 または 0 を返します。
ch が 10 進の数字文字かどうかに応じて 1 または 0 を返します。
ch が 2 進の数字文字かどうかに応じて 1 または 0 を返します。
ch が数字文字かどうかに応じて 1 または 0 を返します。
ch がアルファベット文字かどうかに応じて 1 または 0 を返します。
ch が英数文字かどうかに応じて 1 または 0 を返します。
以下の API は、高速に直接文字変換を行うために使われます:
ch を小文字に変換したものを返します。
ch を大文字に変換したものを返します。
ch をタイトルケース文字に変換したものを返します。
ch を 10 進の正の整数に変換したものを返します。不可能ならば -1 を返します。このマクロは例外を送出しません。
ch を一桁の 2 進整数に変換したものを返します。不可能ならば -1 を返します。このマクロは例外を送出しません。
ch を double に変換したものを返します。不可能ならば -1.0 を返します。このマクロは例外を送出しません。
Unicode オブジェクトを生成したり、Unicode のシーケンスとしての基本的なプロパティにアクセスしたりするには、以下の API を使ってください:
size で指定された長さを持つ Py_UNICODE 型バッファ u から Unicode オブジェクトを生成します。 u を NULL にしてもよく、その場合オブジェクトの内容は未定義です。バッファに必要な情報を埋めるのはユーザの責任です。バッファの内容は新たなオブジェクトにコピーされます。バッファが NULL でない場合、戻り値は共有されたオブジェクトになることがあります。従って、この関数が返す Unicode オブジェクトを変更してよいのは u が NULL のときだけです。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Unicode オブジェクトの内部バッファ Py_UNICODE に対する読み出し専用のポインタを返します。 unicode が Unicode オブジェクトでなければ NULL を返します。
char 型バッファ u から Unicode オブジェクトを生成します。 u の内容は UTF-8 エンコードされているものとします。 u を NULL にしてもよく、その場合オブジェクトの内容は未定義で、バッファに必要な情報を埋めるのはユーザの責任です。バッファの内容は新たなオブジェクトにコピーされます。バッファが NULL でない場合、戻り値は共有されたオブジェクトになることがあります。従って、この関数が返す Unicode オブジェクトを変更してよいのは u が NULL のときだけです。
バージョン 2.6 で追加.
UTF-8 エンコードされたNUL文字終端のchar 型バッファ u から Unicode オブジェクトを生成します。
バージョン 2.6 で追加.
printf() スタイルの format 文字列と可変長引数を受け取り、結果の unicode 文字の長さを計算し、フォーマットされた文字列を含む unicode オブジェクトを返します。可変長引数は C の型を持っていて、 format 文字列で指定された書式指定文字に完全に従う必要があります。以下の書式指定文字が利用できます:
| 書式指定文字 | 型 | 備考 |
|---|---|---|
| %% | n/a | リテラルの % 文字 |
| %c | int | C言語のintで表現される1文字 |
| %d | int | printf("%d") と全く同じ |
| %u | unsigned int | printf("%u") と全く同じ |
| %ld | long | printf("%ld") と全く同じ |
| %lu | unsigned long | printf("%lu") と全く同じ |
| %zd | Py_ssize_t | printf("%zd") と全く同じ |
| %zu | size_t | printf("%zu") と全く同じ |
| %i | int | printf("%i") と全く同じ |
| %x | int | printf("%x") と全く同じ |
| %s | char* | NUL 文字で終わる文字列 |
| %p | void* | C ポインタの16進数表現。 printf("%p") とほぼ同じですが、プラットフォームの printf に依存せず 0x リテラルで始まることが保証されます |
| %U | PyObject* | unicode オブジェクト |
| %V | PyObject*, char * | unicode オブジェクト(NULL でも良い)と、 2つめの引数として NUL 終端の C 文字列 (2つめの引数は1つめの引数が NULL だった時にのみ利用されます) |
| %S | PyObject* | PyObject_Unicode() の戻り値 |
| %R | PyObject* | PyObject_Repr() の戻り値 |
解釈されない書式指定文字があると、それ以降のフォーマット文字列はそのまま出力の文字列にコピーされ、以降の引数は無視されます。
バージョン 2.6 で追加.
2引数であることを除いて PyUnicode_FromFormat() と同じです。
バージョン 2.6 で追加.
Unicode オブジェクトの長さを返します。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
あるエンコード方式でエンコードされたオブジェクト obj を Unicode オブジェクトに型強制して、参照カウントをインクリメントして返します。
型強制は以下のようにして行われます:
文字列やその他の char バッファ互換オブジェクトの場合、オブジェクトは encoding に従ってデコードされます。このとき error で定義されたエラー処理を用います。これら二つの引数は NULL にでき、その場合デフォルト値が使われます (詳細は次の節を参照してください)
その他のUnicodeオブジェクトを含むオブジェクトは TypeError 例外を引き起こします。
この API は、エラーが生じたときには NULL を返します。呼び出し側は返されたオブジェクトに対し参照カウンタを 1 つ減らす (decref) する責任があります。
PyUnicode_FromEncodedObject(obj, NULL, "strict") を行うショートカットで、インタプリタは Unicode への型強制が必要な際に常にこの関数を使います。
プラットフォームで wchar_t がサポートされていて、かつ wchar.h が提供されている場合、Python は以下の関数を使って wchar_t に対して直接アクセスすることができます。このアクセスは、Python 自体の Py_UNICODE 型がシステムの wchar_t と同一の場合に最適化されます。
wchar_t をサポートするプラットフォームでの wchar_t サポート:
size の wchar_t バッファ w から Unicode オブジェクトを生成します。失敗すると NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Unicode オブジェクトの内容を wchar_t バッファ w にコピーします。最大で size 個の wchar_t 文字を (末尾の 0-終端文字を除いて) コピーします。コピーした wchar_t 文字の個数を返します。エラーの時には -1 を返します。 wchar_t 文字列は 0-終端されている場合も、されていない場合もあります。関数の呼び出し側の責任で、アプリケーションの必要に応じて wchar_t 文字列を 0-終端してください。
バージョン 2.5 で変更: この関数は以前は int を返し、 size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Python には、処理速度を高めるために C で書かれた codec が揃えてあります。これら全ての codec は以下の関数を介して直接利用できます。
以下の API の多くが、 encoding と errors という二つの引数をとります。これらのパラメータは、組み込みの Unicode オブジェクトコンストラクタである unicode() における同名のパラメータと同じ意味を持ちます。
encoding を NULL にすると、デフォルトエンコーディングである ASCII を使います。ファイルシステムに関する関数の呼び出しでは、ファイル名に対するエンコーディングとして Py_FileSystemDefaultEncoding を使わねばなりません。この変数は読み出し専用の変数として扱わねばなりません: この変数は、あるシステムによっては静的な文字列に対するポインタであったり、また別のシステムでは、(アプリケーションが setlocale を読んだときなどに) 変わったりもします。
errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を意味します。全ての組み込み codec で、デフォルトのエラー処理は “strict” (ValueError を送出する) になっています。
個々の codec は全て同様のインタフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインタフェースとの違いだけを説明しています。
以下は汎用 codec の API です:
何らかのエンコード方式でエンコードされた、 size バイトの文字列 s をデコードして Unicode オブジェクトを生成します。 encoding と errors は、組み込み関数 unicode() の同名のパラメータと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定されたサイズの Py_UNICODE バッファ s をエンコードした Python 文字列オブジェクトを返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Unicode オブジェクトをエンコードし、その結果を Python 文字列オブジェクトとして返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
以下は UTF-8 codec の APIです:
UTF-8 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
consumed が NULL の場合、 PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF8Stateful() は末尾の不完全な UTF-8 バイト列をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。
バージョン 2.4 で追加.
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファ s を UTF-8 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は UTF-32 codec API です。
UTF-32 でエンコードされたバッファ文字列から size バイトをデコードし、 Unicodeオブジェクトとして返します。 errors は (NULL でないなら) エラーハンドラを指定します。デフォルトは “strict” です。
byteorder が NULL でない時、デコーダは与えられたバイトオーダーでデコードを開始します。
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: big endian
*byteorder が 0 で入力データの最初の 4 バイトがバイトオーダーマーク (BOM) だった場合、デコーダーは BOM のバイトオーダーに切り替え、 BOM は結果の unicode 文字列には含まれません。 *byteorder が -1 か 1 だった場合、すべての BOM は出力へコピーされます。
デコードが完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。
narrow build の場合、BMP 外のコードポイントはサロゲートペアとしてデコードされます。
byteorder が NULL のとき、 codec は native order モードで開始します。
codec が例外を発生させたときは NULL を返します。
バージョン 2.6 で追加.
consumed が NULL のとき、 PyUnicode_DecodeUTF32() と同じように振る舞います。 consumed が NULL でないとき、 PyUnicode_DecodeUTF32Stateful() は末尾の不完全な (4 で割り切れない長さのバイト列などの) UTF-32 バイト列をエラーとして扱いません。末尾の不完全なバイト列はデコードされず、デコードされたバイト数が consumed に格納されます。
バージョン 2.6 で追加.
s の Unicode データを UTF-32 にエンコードし、その値を Python の bytes オブジェクトに格納して返します。出力は以下のバイトオーダーで従って書かれます。
byteorder == -1: little endian
byteorder == 0: native byte order (BOM マークあり)
byteorder == 1: big endian
byteorder が 0 のとき、出力文字列は常に Unicode BOM マーク (U+FEFF) で始まります。それ以外の2つのモードでは、先頭に BOM マークは出力されません。
Py_UNICODE_WIDE が定義されていない場合は、サロゲートペアを 1 つのコードポイントとして出力します。
codec が例外を発生させた場合、 NULL を返します。
バージョン 2.6 で追加.
以下は UTF-16 codec の APIです:
UTF-16 でエンコードされたバッファ s から size バイトだけデコードして、結果を Unicode オブジェクトで返します。 errors は (NULL でない場合) エラー処理方法を定義します。デフォルト値は “strict” です。
byteorder が NULL でない場合、デコード機構は以下のように指定されたバイト整列 (byte order) に従ってデコードを開始します:
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: bit endian
*byteorder が 0 で、入力データの先頭2バイトがバイトオーダーマーク (BOM) だった場合、デコーダは BOM が示すバイトオーダーに切り替え、そのBOMを結果の Unicode 文字列にコピーしません。 *byteorder が -1 か 1 だった場合、すべてのBOMは出力へコピーされます。 (出力では \ufeff か \ufffe のどちらかになるでしょう)
デコードを完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。
byteorder が NULL の場合、 codec はネイティブバイト整列のモードで開始します。
codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
consumed が NULL の場合、 PyUnicode_DecodeUTF16() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF16Stateful() は末尾の不完全な UTF-16 バイト列 (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。
バージョン 2.4 で追加.
バージョン 2.5 で変更: この関数は以前は size の型に int を利用し、 consumed の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
s 中の Unicode データを UTF-16 でエンコードした結果が入っている Python 文字列オブジェクトを返します。出力は以下のバイトオーダーに従って書き出されます:
byteorder == -1: little endian
byteorder == 0: native byte order (BOM マークあり)
byteorder == 1: big endian
byteorder が 0 の場合、出力結果となる文字列は常に Unicode BOM マーク (U+FEFF) で始まります。それ以外のモードでは、 BOM マークを頭につけません。
Py_UNICODE_WIDE が定義されている場合、単一の Py_UNICODE 値はサロゲートペアとして表現されることがあります。 Py_UNICODE_WIDE が定義されていなければ、各 Py_UNICODE 値は UCS-2 文字として表現されます。
codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は UTF-7 codec の API です。
UTF-7 でエンコードされた size バイトの文字列 s をデコードして Unicode オブジェクトを作成します。 codec が例外を発生させたときは NULL を返します。
consumed が NULL のとき、 PyUnicode_DecodeUTF7() と同じように動作します。 consumed が NULL でないとき、末尾の不完全な UTF-7 base-64 部分をエラーとしません。不完全な部分のバイト列はデコードせずに、デコードしたバイト数を consumed に格納します。
与えられたサイズの Py_UNICODE バッファを UTF-7 でエンコードして、 Python の bytes オブジェクトとして返します。 codec が例外を発生させたときは NULL を返します。
base64SetO がゼロでないとき、 “Set O” 文字 (他の場合には何も特別な意味を持たない句読点) を base-64 エンコードします。 base64WhiteSpace がゼロでないとき、空白文字を base-64 エンコードします。 Python の “utf-7” codec では、両方ともゼロに設定されています。
以下は “Unicode Escape” codec の API です:
Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファを Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は “Raw Unicode Escape” codec の APIです:
Raw-Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファを Raw-Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、エンコード時にはこの 256 個だけを受理します。
Latin-1 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファを Latin-1 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は ASCII codec の APIです。 7 ビットの ASCII データだけを受理します。その他のコードはエラーになります。
ASCII でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファを ASCII でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
この codec は、多くの様々な codec を実装する際に使われるという点で特殊な codec です (実際、 encodings パッケージに入っている標準 codecs のほとんどは、この codec を使っています)。この codec は、文字のエンコードやデコードにマップ型 (mapping) を使います。
デコード用のマップ型は、文字列型の字列一組みを、 Unicode 型の字列一組、整数 (Unicode 序数として解釈されます) または None (“定義されていない対応付け (undefined mapping)” を意味し、エラーを引き起こします) のいずれかに対応付けなければなりません。
エンコード用のマップ型は、Unicode 型の字列一組みを、 string 型の字列一組、整数 (Latin-1 序数として解釈されます) または None (“定義されていない対応付け (undefined mapping)” を意味し、エラーを引き起こします) のいずれかに対応付けなければなりません。
マップ型オブジェクトは、 __getitem__() マップ型インタフェースをサポートしなければなりません。
ある文字の検索が LookupError によって失敗すると、その文字はそのままコピーされます。すなわち、その文字の序数値がそれぞれ Unicode または Latin-1 として解釈されます。このため、codec を実現するマップ型に入れる必要がある対応付け関係は、ある文字を別のコード点に対応付けるものだけです。
以下は mapping codec の APIです:
エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。もし、 mapping が NULL だった場合、latin-1 でデコードされます。それ以外の場合では、 mapping は byte に対する辞書マップ (訳注: s に含まれる文字の unsigned な値を int 型でキーとして、値として変換対象の Unicode 文字を表す Unicode 文字列になっているような辞書) か、ルックアップテーブルとして扱われる Unicode 文字列です。
文字列 (訳注: mapping が Unicode 文字列として渡された場合) の長さより大きい byte 値や、(訳注: mappingにしたがって変換した結果が) U+FFFE “characters” になる Byte値は、”定義されていない対応付け (undefined mapping)” として扱われます。
バージョン 2.4 で変更: mapping引数としてunicodeが使えるようになりました.
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
size で指定された長さを持つ Py_UNICODE 型バッファを mapping に指定されたオブジェクトを使ってエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Unicode オブジェクトを mapping に指定されたオブジェクトを使ってエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は “strict” です。 codec が例外を送出した場合には NULL を返します。
以下の codec API は Unicode から Unicode への対応付けを行う特殊なものです。
size で指定された長さを持つ Py_UNICODE バッファを、文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。 codec が例外を発行した場合には NULL を返します。
対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または None に対応付けます。 (None の場合にはその文字を削除します)
対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書やシーケンス型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、変換は行わず、そのままコピーします。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一のエンコード方式を表すわけでなないので注意してください。利用されるエンコード方式 (target encoding) は、 codec を動作させているマシン上のユーザ設定で定義されています。
MBCS でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
consumed が NULL のとき、 PyUnicode_DecodeMBCS() と同じ動作をします。 consumed が NULL でないとき、 PyUnicode_DecodeMBCSStateful() は文字列の最後にあるマルチバイト文字の前半バイトをデコードせず、 consumed にデコードしたバイト数を格納します。
バージョン 2.5 で追加.
size で指定された長さを持つ Py_UNICODE 型バッファを MBCS でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整数を返す機能を持っています。
これらの関数は全て、例外が発生した場合には NULL または -1 を返します。
二つの文字列を結合して、新たな Unicode 文字列を生成します。
Unicode 文字列のリストを分割して、 Unicode 文字列からなるリストを返します。 sep が NULL の場合、全ての空白文字を使って分割を行います。それ以外の場合、指定された文字を使って分割を行います。最大で maxsplit 個までの分割を行います。 maxsplit が負ならば分割数に制限を設けません。分割結果のリスト内には分割文字は含みません。
バージョン 2.5 で変更: この関数は以前は maxsplit の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Unicode 文字列を改行文字で区切り、Unicode 文字列からなるリストを返します。CRLF は一個の改行文字とみなします。 keepend が 0 の場合、分割結果のリスト内に改行文字を含めません。
文字列に文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。
対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または None に対応付けます。 (None の場合にはその文字を削除します)
対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書やシーケンス型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、変換は行わず、そのままコピーします。
errors は codecs で通常使われるのと同じ意味を持ちます。 errors は NULL にしてもよく、デフォルトエラー処理の使用を意味します。
指定した separator で文字列からなるシーケンスを連結 (join) し、連結結果を Unicode 文字列で返します。
substr が str[start:end] の末端 (direction == -1 は先頭一致、 direction == 1 は末尾一致) でとマッチする場合に 1 を返し、それ以外の場合には 0 を返します。エラーが発生した時は -1 を返します。
バージョン 2.5 で変更: この関数は以前は start, end の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
str[start:end] 中に substr が最初に出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所のインデクスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。
バージョン 2.5 で変更: この関数は以前は start, end の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
str[start:end] に substr が重複することなく出現する回数を返します。エラーが発生した場合には -1 を返します。
バージョン 2.5 で変更: この関数は以前は start, end と戻り値の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
str 中に出現する substr を最大で maxcount 個 replstr に置換し、置換結果を Unicode オブジェクトにして返します。 maxcount == -1 にすると、全ての substr を置換します。
バージョン 2.5 で変更: この関数は以前は maxcount の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
二つの文字列を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。
二つのunicode文字列を比較して、下のうちの一つを返します:
Py_EQ と Py_NE の比較は、引数からUnicodeへの変換が UnicodeDecodeError で失敗した時に、 UnicodeWarning を発生する可能性があることに注意してください。
op に入れられる値は、 Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, and Py_LE のどれかです。
数値変換と、書式化文字列出力のための関数群
書式化文字列 format と追加の引数から、 size バイトを超えない文字列を str に出力します。 Unix man page の snprintf(2) を参照してください。
書式化文字列 format と可変長引数リスト va から、 size バイトを超えない文字列を str に出力します。 Unix man page の vsnprintf(2) を参照してください。
PyOS_snprintf() と PyOS_vsnprintf() は標準Cライブラリの snprintf() と vsnprintf() 関数をラップします。これらの関数の目的は、C標準ライブラリが保証していないコーナーケースでの動作を保証することです。
これらのラッパ関数は、戻るときに str*[*size-1] が常に '\0' であることを保証します。 (str の末尾の '\0' を含めて) size バイト以上を書き込みません。 str != NULL, size > 0, format != NULL を要求します。
もし vsnprintf() のないプラットフォームで、切り捨てを避けるために必要なバッファサイズが size を512バイトより大きく超過していれば、 Python は Py_FatalError で abort します。
The return value (rv) for these functions should be interpreted as follows: これらの関数の戻り値 (rv) は次のように解釈されなければなりません:
以下の関数は locale 非依存な文字列から数値への変換を行ないます。
文字列 s を double に変換します。失敗したときは Python の例外を発生させます。受け入れられる文字列は、 Python の float() コンストラクタが受け付ける文字列に準拠しますが、 s の先頭と末尾に空白文字があってはならないという部分が異なります。この変換は現在のロケールに依存しません。
endptr が NULL の場合、変換は文字列全体に対して行われます。文字列が正しい浮動小数点数の表現になっていない場合は -1.0 を返して ValueError を発生させます。
endptr が NULL で無い場合、文字列を可能な範囲で変換して、 *endptr に最初の変換されなかった文字へのポインタを格納します。文字列の先頭に正しい浮動小数点数の表現が無かった場合、 *endptr を文字列の先頭に設定して、 ValueError を発生させ、 -1.0 を返します。
s が float に格納し切れないほど大きい値を表現していた場合、 (例えば、 "1e500" は多くのプラットフォームで表現できません) overflow_exception が NULL なら Py_HUGE_VAL に適切な符号を付けて返します。他の場合は overflow_exception は Python の例外オブジェクトへのポインタでなければならず、その例外を発生させて -1.0 を返します。どちらの場合でも、 *endptr には変換された値の直後の最初の文字へのポインタが設定されます。
それ以外のエラーが変換中に発生した場合(例えば out-of-memory エラー)、適切な Python の例外を設定して -1.0 を返します。
バージョン 2.7 で追加.
文字列を double へ変換します。この関数は、C locale におけるC標準の strtod() と同じように動作します。スレッドセーフのために、この関数は現在の locale を変更せずに実装されています。
PyOS_ascii_strtod() は通常、設定ファイルを読み込むときや、ロケール独立な非ユーザーからの入力を読み込むときに使われるべきです。
詳細は Unix man page の strtod(2) を参照してください。
バージョン 2.4 で追加.
バージョン 2.7 で撤廃: 代わりに PyOS_string_to_double() を使ってください。
double を '.' を小数点記号に利用して文字列に変換します。 format は数値のフォーマットを指定する printf() スタイルの文字列です。利用できる変換文字は 'e', 'E', 'f', 'F', 'g', 'G' です。
戻り値は、変換された文字列が格納された buffer へのポインタか、失敗した場合は NULL です。
バージョン 2.4 で追加.
バージョン 2.7 で撤廃: この関数は Python 2.7 と 3.1 では削除されました。 代わりに PyOS_double_to_string() を使ってください。
double val を指定された format_code, precision, flags に基づいて文字列に変換します。
format_code は 'e', 'E', 'f', 'F', 'g', 'G', 'r' のどれかでなければなりません。 'r' の場合、 precision は 0 でなければならず、無視されます。 'r' フォーマットコードは標準の repr() フォーマットを指定しています。
flags は 0 か、 Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, Py_DTSF_ALT かこれらの or を取ったものです。
ptype が NULL で無い場合、 val が有限数、無限数、NaNのどれかに合わせて、 Py_DTST_FINITE, Py_DTST_INFINITE, Py_DTST_NAN のいずれかに設定されます。
戻り値は変換後の文字列が格納された buffer へのポインタか、変換が失敗した場合は NULL です。呼び出し側は、返された文字列を PyMem_Free() を使って解放する責任があります。
バージョン 2.7 で追加.
文字列を、 locale 非依存な方法で double へ変換します。
詳細は Unix man page の atof(2) を参照してください。
バージョン 2.4 で追加.
バージョン 3.1 で撤廃: 代わりに PyOS_string_to_double() を使ってください。
大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strcmp() と同じ動作をします。
バージョン 2.6 で追加.
大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strncmp() と同じ動作をします。
バージョン 2.6 で追加.
この PyTypeObject のインスタンスは Python 浮動小数点型を表現します。これは float や types.FloatType と同じオブジェクトです。
引数が PyFloatObject か PyFloatObject のサブタイプのときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
引数が PyFloatObject 型で、かつ PyFloatObject 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
str の文字列値をもとに PyFloatObject オブジェクトを生成します。失敗すると NULL を返します。引数 pend は無視されます。この引数は後方互換性のためだけに残されています。
v から PyFloatObject オブジェクトを生成して返します。失敗すると NULL を返します。
float の精度、最小値、最大値に関する情報を含む structseq インスタンスを返します。これは、 float.h ファイルの薄いラッパーです。
バージョン 2.6 で追加.
float の表現できる最大限解値 DBL_MAX を C の double 型で返します。
バージョン 2.6 で追加.
float の正規化された最小の正の値 DBL_MIN を C の double 型で返します。
バージョン 2.6 で追加.
float の free list をクリアします。開放できなかったアイテム数を返します。
バージョン 2.6 で追加.
str() と同じルールで v を文字列に変換します。 buf の長さは 100 以上でなければなりません。
この関数は長さを知らないバッファに書きこむので安全ではありません。
バージョン 2.7 で撤廃: 代わりに func:PyObject_Str か PyOS_double_to_string() を利用してください。
PyFloat_AsString とほとんど同じですが、 repr() とおなじルールを使います。 buf の長さは 100 以上でなければなりません。
この関数は長さを知らないバッファに書きこむので安全ではありません。
バージョン 2.7 で撤廃: 代わりに PyObject_Repr() か PyOS_double_to_string() を利用してください。
バージョン 2.5 で追加.
このセクションでは set と frozenset の公開 API について詳しく述べます。以降で説明していない機能は、抽象オブジェクトプロトコル ( PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print(), PyObject_GetIter() を含む) か抽象数値プロトコル ( PyNumber_Add(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAdd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr(), PyNumber_InPlaceXor() を含む) を使って利用できます。
この PyObject を継承した型は、 set と frozenset 両方の内部データを保存するのに用いられます。 PyDictObject と同じように、小さい集合(set)に対しては(タプルのように)固定サイズであり、そうでない集合に対しては(リストと同じように)可変長のメモリブロックを用います。この構造体のどのフィールドも、非公開で変更される可能性があると考えて下さい。すべてのアクセスは、構造体の中の値を直接操作するのではなく、ドキュメントされた API を用いて行うべきです。
この PyTypeObject のインスタンスは、Python の set 型を表します。
この PyTypeObject のインスタンスは、Python の frozenset 型を表します。
以降の型チェックマクロはすべての Python オブジェクトに対するポインタに対して動作します。同様に、コンストラクタはすべてのイテレート可能な Python オブジェクトに対して動作します。
p が set か frozenset のどちらかのオブジェクトであるときに true を返します。サブタイプのオブジェクトは含みません。
iterable が返すオブジェクトを含む新しい set を返します。 iterable が NULL のときは、空の set を返します。成功したら新しい set を、失敗したら NULL を返します。 iterable がイテレート可能で無い場合は、 TypeError を送出します。このコンストラクタは set をコピーするときにも使えます。 (c=set(s))
iterable が返すオブジェクトを含む新しい frozenset を返します。 iterable が NULL のときは、空の frozenset を返します。 iterable がイテレート可能で無い場合は、 TypeError を送出します。
バージョン 2.6 で変更: 完全に新しい frozenset オブジェクトを返すことが保証されるように なりました。以前は、大きさがゼロの frozenset はシングルトンでした。 これは新しい frozenset を PySet_Add() を使って作成するためです。
以降の関数やマクロは、 set と frozenset とそのサブタイプのインスタンスに対して利用できます。
set や frozenset のオブジェクトの長さを返します。 len(anyset) と同じです。 anyset が set 、 frozenset 及びそのサブタイプのオブジェクトで無い場合は、 PyExc_SystemError を送出します。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
エラーチェックを行わない、 PySet_Size() のマクロ形式。
見つかったら 1 を、見つからなかったら 0 を、エラーが発生したときは -1 を返します。 Python の __contains__() メソッドと違って、この関数は非ハッシュ set を一時 frozenset に自動で変換しません。 key がハッシュ可能で無い場合、 TypeError を送出します。 anyset が set, frozenset 及びそのサブタイプのオブジェクトで無い場合は PyExc_SystemError を送出します。
set のインスタンスに key を追加します。 frozenset のインスタンスに使わないで下さい。成功したら 0 を、失敗したら -1 を返します。 key がハッシュ可能でないなら、 TypeError を送出します。 set を大きくする余裕が無い場合は、 MemoryError を送出します。 set が set とそのサブタイプのインスタンスで無い場合は、 SystemError を送出します。
バージョン 2.6 で変更: frozenset やそのサブタイプのインスタンスに対して利用できる ようになりました。 PyTuple_SetItem() のように、新しい frozenset を他のコードに渡す まえに内容を追加するためのに使うことができます。
以降の関数は、 set とそのサブタイプに対して利用可能です。 frozenset とそのサブタイプには利用できません。
見つかって削除したら 1 を返します。見つからなかったら何もせずに 0 を返します。エラーが発生したら -1 を返します。 key が無くても KeyError を送出しません。 key がハッシュ不可能であれば TypeError を送出します。 Python の discard() メソッドと違って、この関数は非ハッシュ set を一時 frozenset に変換しません。 set が set とそのサブタイプのインスタンスで無いときは、 PyExc_SystemError を送出します。
ここで説明されているクラスオブジェクトは旧スタイルクラスのもので、 Python 3 では削除されることに注意してください。新スタイルクラス(type)を拡張モジュールで作成する場合は、 type オブジェクトを扱うべきです。 (型オブジェクト (type object) を参照)
ビルトインクラスを表すためのオブジェクトの構造体
o が、標準のクラスオブジェクトから派生した type のインスタンスだった場合を含めて、クラスオブジェクトだった場合に真を返します。それ以外の場合は偽を返します。
klass が base のサブクラスだった場合に真を返します。それ以外の場合は偽を返します。
インスタンスオブジェクト固有の関数はきわめてわずかです。
クラスインスタンスの型オブジェクトです。
C API にはメソッドオブジェクトを扱うのに便利な関数があります。
この PyTypeObject のインスタンスは Python のメソッド型を表現します。このオブジェクトは、 types.MethodType として Python プログラムに公開されています。
o がメソッドオブジェクト (PyMethod_Type 型である) 場合に真を返します。パラメータは NULL にできません。
任意の呼び出し可能オブジェクト func を使った新たなメソッドオブジェクトを返します; 関数 func は、メソッドが呼び出された時に呼び出されるオブジェクトです。このメソッドをインスタンスに束縛 (bind) したい場合、 self をインスタンス自体にして、 class を self のクラスにしなければなりません。それ以外の場合は self を NULL に、 class を非束縛メソッドを提供しているクラスにしなければなりません。
メソッドオブジェクト meth を生成したクラスオブジェクトを返します; インスタンスがメソッドオブジェクトを生成した場合、戻り値はインスタンスのクラスになります。
PyMethod_Class() をマクロで実装したバージョンで、エラーチェックを行いません。
メソッド meth に関連付けられている関数オブジェクトを返します。
PyMethod_Function() のマクロ版で、エラーチェックを行いません。
meth が束縛メソッドの場合には、メソッドに関連付けられているインスタンスを返します。それ以外の場合には NULL を返します。
PyMethod_Self() のマクロ版で、エラーチェックを行いません。
free list をクリアします。解放された要素数を返します。
バージョン 2.6 で追加.
Python インタプリタを初期化します。 Python の埋め込みを行うアプリケーションでは、他のあらゆる Python/C API を使用するよりも前にこの関数を呼び出さねばなりません。ただし、 Py_SetProgramName(), PyEval_InitThreads(), PyEval_ReleaseLock(), および PyEval_AcquireLock() は例外です。この関数はロード済みモジュールのテーブル (sys.modules) を初期化し、基盤となるモジュール群、 __builtin__, __main__, sys を生成します。また、モジュール検索パス (sys.path) も初期化します。 sys.argv の設定は行いません。設定するには、 PySys_SetArgvEx() を使ってください。この関数を (Py_Finalize() を呼ばずに) 再度呼び出しても何も行いません。戻り値はありません。初期化が失敗すれば、それは致命的なエラーです。
initsigs に1を指定すれば Py_Initialize() と同じ処理を実行しますが、 Python埋め込みアプリケーションでは initsigs を0として初期化時にシグナルハンドラの登録をスキップすることができます。
バージョン 2.4 で追加.
Python インタプリタがすでに初期化済みの場合に真 (非ゼロ) を返し、そうでない場合には偽 (ゼロ) を返します。 Py_Finalize() を呼び出すと、次に Py_Initialize() を呼び出すまでこの関数は偽を返します。
Py_Initialize() とそれ以後の Python/C API 関数で行った全ての初期化処理を取り消し、最後の Py_Initialize() 呼び出し以後に Python インタプリタが生成した全てのサブインタプリタ (sub-interpreter, 下記の Py_NewInterpreter() を参照) を消去します。理想的な状況では、この関数によって Python インタプリタが確保したメモリは全て解放されます。この関数を (Py_Initialize() を呼ばずに) 再度呼び出しても何も行いません。戻り値はありません。 終了処理中のエラーは無視されます。
この関数が提供されている理由はいくつかあります。 Python の埋め込みを行っているアプリケーションでは、アプリケーションを再起動することなく Python を再起動したいことがあります。また、動的ロード可能イブラリ (あるいは DLL) から Python インタプリタをロードするアプリケーションでは、DLL をアンロードする前に Python が確保したメモリを全て解放したいと考えるかもしれません。アプリケーション内で起きているメモリリークを追跡する際に、開発者は Python が確保したメモリをアプリケーションの終了前に解放させたいと思う場合もあります。
バグおよび注意事項: モジュールやモジュール内のオブジェクトはランダムな順番で削除されます。このため、他のオブジェクト(関数オブジェクトも含みます) やモジュールに依存するデストラクタ (__del__() メソッド) が失敗してしまうことがあります。動的にロードされるようになっている拡張モジュールが Python によってロードされていた場合、アンロードされません。 Python が確保したメモリがわずかながら解放されないかもしれません (メモリリークを発見したら、どうか報告してください)。オブジェクト間の循環参照に捕捉されているメモリは解放されないことがあります。拡張モジュールが確保したメモリは解放されないことがあります。拡張モジュールによっては、初期化ルーチンを 2 度以上呼び出すと正しく動作しないことがあります。 こうした状況は、 Py_Initialize() や Py_Finalize() を 2 度以上呼び出すと起こり得ます。
この関数を呼び出すなら、最初に Py_Initialize() を呼び出すよりも前に呼び出さねばなりません。この関数はインタプリタにプログラムの main() 関数に指定した argv[0] 引数の値を教えます。この引数値は、 Py_GetPath() や、以下に示すその他の関数が、インタプリタの実行可能形式から Python ランタイムライブラリへの相対パスを取得するために使われます。デフォルトの値は 'python' です。引数はゼロ終端されたキャラクタ文字列で、静的な記憶領域に入っていなければならず、その内容はプログラムの実行中に変更してはなりません。 Python インタプリタ内のコードで、この記憶領域の内容を変更するものは一切ありません。
Py_SetProgramName() で設定されたプログラム名か、デフォルトのプログラム名を返します。関数が返す文字列ポインタは静的な記憶領域を返します。関数の呼び出し側はこの値を変更できません。
プラットフォーム非依存のファイル群がインストールされている場所である prefix を返します。この値は Py_SetProgramName() でセットされたプログラム名やいくつかの環境変数をもとに、数々の複雑な規則から導出されます。例えば、プログラム名が '/usr/local/bin/python' の場合、prefix は '/usr/local' になります。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値はトップレベルの Makefile に指定されている変数 prefix や、ビルド値に configure スクリプトに指定した --prefix 引数に対応しています。この値は Python コードからは sys.prefix として利用できます。これはUnixでのみ有用です。次に説明する関数も参照してください。
プラットフォーム 依存 のファイルがインストールされている場所である exec-prefix を返します。この値は Py_SetProgramName() でセットされたプログラム名やいくつかの環境変数をもとに、数々の複雑な規則から導出されます。例えば、プログラム名が '/usr/local/bin/python' の場合、exec-prefix は '/usr/local' になります。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値はトップレベルの Makefile に指定されている変数 exec_prefix や、ビルド値に configure スクリプトに指定した --exec-prefix 引数に対応しています。この値は Python コードからは sys.exec_prefix として利用できます。 Unixのみで有用です。
背景: プラットフォーム依存のファイル (実行形式や共有ライブラリ) が別のディレクトリツリー内にインストールされている場合、 exec-prefix は prefix と異なります。典型的なインストール形態では、プラットフォーム非依存のファイルが /usr/local に収められる一方、プラットフォーム依存のファイルは /usr/local/plat サブツリーに収められます。
一般的に、プラットフォームとは、ハードウェアとソフトウェアファミリの組み合わせを指します。例えば、 Solaris 2.x を動作させている Sparc マシンは全て同じプラットフォームであるとみなしますが、Solaris 2.x を動作させている Intel マシンは違うプラットフォームになりますし、同じ Intel マシンでも Linux を動作させているならまた別のプラットフォームです。一般的には、同じオペレーティングシステムでも、メジャーリビジョンの違うものは異なるプラットフォームです。非 Unix のオペレーティングシステムの場合は話はまた別です; 非 Unix のシステムでは、インストール方法はとても異なっていて、 prefix や exec-prefix には意味がなく、空文字列が設定されています。コンパイル済みの Python バイトコードはプラットフォームに依存しないので注意してください (ただし、どのバージョンの Python でコンパイルされたかには依存します!)。
システム管理者は、 mount や automount プログラムを使って、各プラットフォーム用の /usr/local/plat を異なったファイルシステムに置き、プラットフォーム間で /usr/local を共有するための設定方法を知っているでしょう。
Python 実行可能形式の完全なプログラム名を返します; この値はデフォルトのモジュール検索パスを (前述の Py_SetProgramName() で設定された) プログラム名から導出する際に副作用的に計算されます。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.executable として利用できます。
デフォルトのモジュール検索パスを返します; パスは (上の Py_SetProgramName() で設定された) プログラム名と、いくつかの環境変数から計算されます。戻り値となる文字列は、プラットフォーム依存のパス区切り文字で分割された一連のディレクトリ名からなります。区切り文字は Unix と Mac OS X では ':', Windows では ';' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。 sys.path はインタプリタによってこの値で初期化され、その後にモジュールをロードする際の検索パスを変更するために修正することが可能で、たいていそうされます。
Python インタプリタのバージョンを返します。バージョンは、次のような形式の文字列です。
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
第一ワード (最初のスペース文字まで) は、現在の Python のバージョンです; 最初の三文字は、ピリオドで区切られたメジャーバージョンとマイナーバージョンです。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version として利用できます。
現在のプラットフォームのプラットフォーム識別文字列を返します。 Unixでは、オペレーティングシステムの “公式の” 名前を小文字に変換し、後ろにメジャーリビジョン番号を付けた構成になっています。例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、 'sunos5' になります。Mac OS X では 'darwin' です。 Windows では 'win' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.platform として利用できます。
現在の Python バージョンに対する公式の著作権表示文字列、例えば 'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam' を返します。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.copyright として利用できます。
現在使っているバージョンの Python をビルドする際に用いたコンパイラを示す文字列を、角括弧で囲った文字列を返します。例えば:
"[GCC 2.7.2.2]"
になります。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。
現在使っている Python インタプリタインスタンスの、シーケンス番号とビルド日時に関する情報を返します。例えば
"#67, Aug 1 1997, 22:34:28"
になります。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。
argc および argv に基づいて sys.argv を設定します。これらの引数はプログラムの main() に渡した引数に似ていますが、最初の要素が Python インタプリタの宿主となっている実行形式の名前ではなく、実行されるスクリプト名を参照しなければならない点が違います。実行するスクリプトがない場合、 argv の最初の要素は空文字列にしてもかまいません。この関数が sys.argv の初期化に失敗した場合、致命的エラーを Py_FatalError() で知らせます。
updatepath が 0 の場合、ここまでの動作がこの関数がすることの全てです。 updatepath が 0 でない場合、この関数は sys.path を以下のアルゴリズムに基づいて修正します:
ノート
Python インタプリタを、単一のスクリプトを実行する以外の目的で埋め込むアプリケーションは、 updatepath に 0 を渡して必要なら自分で sys.path を更新することをおすすめします。 CVE-2008-5983 を参照してください。
2.6.6 より前のバージョンでは、 PySys_SetArgv() を呼出たあとに同じ事を手動で sys.path の先頭の要素を取り除くことで実現できます。例えば、次のようにします。
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
バージョン 2.6.6 で追加.
PySys_SetArgvEx() の updatepath に 1 を設定したのと同じように動作します。
Python の標準ライブラリがある、デフォルトの “home” ディレクトリを設定します。引数の文字列の意味については PYTHONHOME を参照してください。
引数は静的なストレージに置かれてプログラム実行中に書き換えられないようなゼロ終端の文字列であるべきです。 Python インタプリタはこのストレージの内容を変更しません。
前回の Py_SetPythonHome() 呼び出しで設定されたデフォルトの “home” か、 PYTHONHOME 環境変数が設定されていればその値を返します。
Python インタプリタは完全にはスレッドセーフではありません。マルチスレッドの Python プログラムをサポートするために、グローバルインタプリタロック(global interpreter lock, GIL) と呼ばれるグローバルなロックが存在していて、現在のスレッドが Python オブジェクトに安全にアクセスする前に必ずロックを獲得しなければならなくなっています。ロック機構がなければ、単純な操作でさえ、マルチスレッドプログラムの実行に問題を引き起こす可能性があります。たとえば、二つのスレッドが同じオブジェクトの参照カウントを同時にインクリメントすると、結果的に参照カウントは二回でなく一回だけしかインクリメントされないかもしれません。
このため、 GIL を獲得したスレッドだけが Python オブジェクトを操作したり、 Python/C API 関数を呼び出したりできるというルールがあります。並行処理をエミュレートするために、インタプリタは定期的にロックを解放したり獲得したりします。 (sys.setcheckinterval() を参照) このロックはブロックが起こりうる I/O 操作の付近でも解放・獲得され、 I/O を要求するスレッドが I/O 操作の完了を待つ間、他のスレッドが動作できるようにしています。
Python インタプリタはスレッドごとに必要な情報を PyThreadState と呼ばれるデータ構造の中に保存します。そしてグローバル変数として現在の PyThreadState を指すポインタを1つ持ちます。このグローバル変数は PyThreadState_Get() を使って取得できます。
GIL を操作するほとんどのコードは、次のような単純な構造になります。
スレッド状態をローカル変数に保存する。
GILを解放する。
...ブロックが起きるような何らかの I/O 操作...
GILを獲得する。
ローカル変数からスレッド状態を回復する。
この構造は非常に一般的なので、作業を単純にするために2つのマクロが用意されています:
Py_BEGIN_ALLOW_THREADS
...ブロックが起きるような何らかの I/O 操作...
Py_END_ALLOW_THREADS
Py_BEGIN_ALLOW_THREADS マクロは新たなブロックを開始し、隠しローカル変数を宣言します; Py_END_ALLOW_THREADS はブロックを閉じます。 Python をスレッドサポートなしでコンパイルしたときでもこの2つのマクロは利用可能です。 (単に、空行に展開されます)
スレッドサポートが有効になっている場合、上記のブロックは以下のようなコードに展開されます:
PyThreadState *_save;
_save = PyEval_SaveThread();
...ブロックが起きるような何らかの I/O 操作...
PyEval_RestoreThread(_save);
これらの関数の動作を説明します。 GIL は現在のスレッド状態を指すポインタを保護するために使われます。ロックを解放してスレッド状態を退避する際、ロックを解放する前に現在のスレッド状態ポインタを取得しておかなければなりません (他のスレッドがすぐさまロックを獲得して、自らのスレッド状態をグローバル変数に保存してしまうかもしれないからです)。逆に、ロックを獲得してスレッド状態を復帰する際には、グローバル変数にスレッド状態ポインタを保存する前にロックを獲得しておかなければなりません。
Python API を通して作られたスレッド (threading モジュールなど) では自動的にスレッド状態が割り当てられて、上記のコードは正しく動きます。しかし、(自前でスレッド管理を行う外部のライブラリなどにより)C言語でスレッドを生成した場合、そのスレッドには GIL がなく、スレッド状態データ構造体もないことに注意する必要があります。
このようなスレッドから Python コードを呼び出す必要がある場合 (外部のライブラリからコールバックするAPIなどがよくある例です)、 Python/C API を呼び出す前に、スレッド状態データ構造体を生成し、 GIL を獲得し、スレッド状態ポインタを保存することで、スレッドをインタプリタに登録しなければなりません。スレッドが作業を終えたら、スレッド状態ポインタをリセットして、ロックを解放し、最後にスレッド状態データ構造体のメモリを解放しなければなりません。
PyGILState_Ensure() と PyGILState_Release() はこの処理を自動的に行います。 Cのスレッドから Python を呼び出す典型的な方法は以下のとおりです。
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();
/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */
/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
PyGILState_*() 関数は、(Py_Initialize() によって自動的に作られる) グローバルインタプリタ1つだけが存在すると仮定する事に気をつけて下さい。 Python は (Py_NewInterpreter() を使って) 追加のインタプリタを作成できることに変わりはありませんが、複数インタプリタと PyGILState_*() API を混ぜて使うことはサポートされていません。
注意しないといけないもう一つの重要な点は、 C の fork() を呼び出した時の動作です。ほとんどの fork() を持っているシステムでは、fork されたプロセスには fork を実行したスレッドしか存在しません。これは、別のスレッドに取得されたロックがずっと開放されないことを意味します。 Python は fork する前にロックを取得し、その後に fork を開放することでこの問題を解決しています。加えて、子プロセスではすべての Lock オブジェクト をリセットします。 Python を拡張したり埋め込んだりしている場合、 Python に fork 前に取得したり fork 後に開放しなければならない追加の (Python 以外の) ロックを Python に教える手段がありません。 Python と同じことを実現するには、 posix_atfork() のようなOSの機能を使う必要があります。加えて、Python を拡張したり埋め込んだりしているときに、 os.fork() を通してではなく直接 fork() を呼び出すと、fork後に失われるスレッドに取得されていた Python の内部ロックのためにデッドロックが発生するかもしれません。 PyOS_AfterFork() は必要なロックのリセットを試みますが、いつでもそれが可能とは限りません。
C拡張を書いたりPythonインタプリタを埋め込むときに最も一般的に使われる型や関数は次のとおりです。
このデータ構造体は、協調動作する多数のスレッド間で共有されている状態を表現します。同じインタプリタに属するスレッドはモジュール管理情報やその他いくつかの内部的な情報を共有しています。この構造体には公開 (public) のメンバはありません。
異なるインタプリタに属するスレッド間では、利用可能なメモリ、開かれているファイルデスクリプタなどといったプロセス状態を除いて、初期状態では何も共有されていません。 GILもまた、スレッドがどのインタプリタに属しているかに関わらずすべてのスレッドで共有されています。
単一のスレッドの状態を表現する表現するデータ構造体です。スレッドのインタプリタ状態を指すポインタ PyInterpreterState * interp だけが公開されているデータメンバです。
GIL を初期化し、獲得します。この関数は、主スレッドが第二のスレッドを生成する以前や、 PyEval_ReleaseLock() や PyEval_ReleaseThread(tstate) といった他のスレッド操作に入るよりも前に呼び出されるようにしておかなければなりません。 PyEval_SaveThread(), PyEval_RestoreThread() の前に呼び出す必要はありません。
二度目に呼び出すと何も行いません。この関数を Py_Initialize() の前に呼び出しても安全です。
ノート
主スレッドしか存在しないのであれば、GIL操作は必要ありません。これはよくある状況ですし (ほとんどの Python プログラムはスレッドを使いません)、ロック操作はインタプリタをごくわずかに低速化します。従って、初期状態ではロックは生成されません。ロックを使わない状況は、すでにロックを獲得している状況と同じです: 単一のスレッドしかなければ、オブジェクトへのアクセスは全て安全です。従って、この関数がGILを初期化すると、同時にロックを獲得するようになっています。Python の _thread モジュールは、新たなスレッドを作成する前に、ロックが存在するか、あるいはまだ作成されていないかを調べ、 PyEval_InitThreads() を呼び出します。この関数から処理が戻った場合、ロックが作成され、呼び出し元スレッドがそのロックを獲得している事が保証されています。
どのスレッドが現在 GIL を (存在する場合) 持っているか分からない時にこの関数を使うのは安全では ありません 。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
PyEval_InitThreads() をすでに呼び出している場合は真 (非ゼロ) を返します。この関数は、GILを獲得せずに呼び出すことができますので、シングルスレッドで実行している場合にはロック関連のAPI呼び出しを避けるために使うことができます。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
バージョン 2.4 で追加.
(GIL が生成されていて、スレッドサポートが有効の場合) GILを解放して、スレッド状態を NULL にし、以前のスレッド状態 (NULL にはなりません) を返します。ロックがすでに生成されている場合、現在のスレッドがロックを獲得していなければなりません。 (この関数はコンパイル時にスレッドサポートが無効にされていても利用できます。)
(GIL が生成されていて、スレッドサポートが有効の場合) GIL を獲得して、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。 GIL が生成されていて、この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。 (この関数はコンパイル時にスレッドサポートが無効にされていても利用できます。)
現在のスレッド状態を返します。GIL を保持していなければなりません。現在のスレッド状態が NULL なら、(呼び出し側が NULL チェックをしなくてすむように) この関数は致命的エラーを起こすようになっています。
現在のスレッド状態を tstate に指定したスレッド状態と入れ変えます。 tstate は NULL の場合があります。 GIL を保持していなければならず、開放しません。
この関数は PyOS_AfterFork() から呼び出され、新しい子プロセスが、子プロセス内で実行していないスレッドが持っているロックを持たないようにします。
以下の関数はスレッドローカルストレージを利用していて、サブインタプリタとの互換性がありません。
Pythonの状態やGILに関わらず、実行中スレッドでPython C APIの呼び出しが可能となるようにします。この関数はスレッド内で何度でも呼び出すことができますが、必ず全ての呼び出しに対応して PyGILState_Release() を呼び出す必要があります。
通常、 PyGILState_Ensure() 呼び出しと PyGILState_Release() 呼び出しの間でこれ以外のスレッド関連API を使用することができますが、Release()の前にスレッド状態は復元されていなければなりません。例えば、通常の Py_BEGIN_ALLOW_THREADS マクロと Py_END_ALLOW_THREADS は使用することができます。
戻り値は PyGILState_Ensure() 呼び出し時のスレッド状態を隠蔽した”ハンドル”で、 PyGILState_Release() に渡してPythonを同じ状態に保たなければなりません。再起呼び出しも可能ですが、ハンドルを共有することは できません - それぞれの PyGILState_Ensure() 呼び出しでハンドルを保存し、対応する PyGILState_Release() 呼び出しで渡してください。
関数から復帰したとき、実行中のスレッドはGILを所有していて、任意の Python コードを実行できます。処理の失敗は致命的なエラーです。
バージョン 2.3 で追加.
獲得したすべてのリソースを開放します。この関数を呼び出すと、Pythonの状態は対応する PyGILState_Ensure() を呼び出す前と同じとなります。(通常、この状態は呼び出し元でははわかりませんので、GILState APIを利用するようにしてください。）
PyGILState_Ensure() を呼び出す場合は、必ず同一スレッド内で対応する PyGILState_Release() を呼び出してください。
バージョン 2.3 で追加.
以下のマクロは、通常末尾にセミコロンを付けずに使います; Python ソース配布物内の使用例を見てください。
このマクロを展開すると { PyThreadState *_save; _save = PyEval_SaveThread(); になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は後で Py_END_ALLOW_THREADS マクロと対応させなければなりません。マクロについての詳しい議論は上記を参照してください。コンパイル時にスレッドサポートが無効化されていると何も行いません。
このマクロを展開すると PyEval_RestoreThread(_save); } になります。マクロに開き波括弧が入っていることに注意してください; この波括弧は事前の Py_BEGIN_ALLOW_THREADS マクロと対応していなければなりません。マクロについての詳しい議論は上記を参照してください。コンパイル時にスレッドサポートが無効化されていると何も行いません。
このマクロを展開すると PyEval_RestoreThread(_save); になります: 閉じ波括弧のない Py_END_ALLOW_THREADS と同じです。コンパイル時にスレッドサポートが無効化されていると何も行いません。
このマクロを展開すると _save = PyEval_SaveThread(); になります: 開き波括弧のない Py_BEGIN_ALLOW_THREADS と同じです。コンパイル時にスレッドサポートが無効化されていると何も行いません。
以下の全ての関数はコンパイル時にスレッドサポートが有効になっている時だけ利用でき、呼び出すのはGILがすでに作成されている場合だけにしなくてはなりません。
新しいインタプリタ状態オブジェクトを生成します。 GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。
インタプリタ状態オブジェクト内の全ての情報をリセットします。 GIL を保持していなければなりません。
インタプリタ状態オブジェクトを破壊します。GIL を保持しておく必要はありません。インタプリタ状態は PyInterpreterState_Clear() であらかじめリセットしておかなければなりません。
指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを生成します。 GIL を保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。
スレッド状態オブジェクト内の全ての情報をリセットします。 GIL を保持していなければなりません。
スレッド状態オブジェクトを破壊します。GIL を保持する必要はありません。スレッド状態は PyThreadState_Clear() であらかじめリセットしておかなければなりません。
拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを使わねばなりません。現在のスレッド状態がない時にこの関数を呼び出してもかまいません。この関数が NULL を返す場合、例外はまったく送出されず、呼び出し側は現在のスレッド状態が利用できないと考えねばなりません。
バージョン 2.3 で変更: 以前は、現在のスレッドがアクティブなときのみ呼び出せるようになっており、 NULL は例外が送出されたことを意味していました.
スレッド内で非同期的に例外を送出します。 id 引数はターゲットとなるスレッドのスレッド id です; exc は送出する例外オブジェクトです。この関数は exc に対する参照を一切盗み取りません。素朴な間違いを防ぐため、この関数を呼び出すには独自に C 拡張モジュールを書かねばなりません。 GIL を保持した状態で呼び出さなければなりません。
変更を受けたスレッド状態の数を返します; これは普通は1ですが、スレッドidが見つからなかった場合は0になります。もし exc が NULL であれば、そのスレッドで保留されている例外があればクリアします。この場合は例外は発生しません。
バージョン 2.3 で追加.
GIL を獲得し、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。ロックはあらかじめ作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。
PyEval_RestoreThread() はより高レベルな関数で常に(スレッドサポートが無効な場合やスレッドが初期化されていない場合でも)利用できます。
現在のスレッド状態をリセットして NULL にし、GIL を解放します。ロックはあらかじめ作成されていなければならず、かつ現在のスレッドが保持していなければなりません。 tstate は NULL であってはなりませんが、その値が現在のスレッド状態を表現しているかどうかを調べるためにだけ使われます — もしそうでなければ、致命的エラーが報告されます。
PyEval_SaveThread() はより高レベルな関数で常に(スレッドサポートが無効な場合やスレッドが初期化されていない場合でも)利用できます。
GILを獲得します。ロックは前もって作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。
警告
この関数は現在のスレッド状態を変更しません。代わりに PyEval_RestoreThread() か PyEval_AcquireThread() を利用してください。
GILを解放します。ロックは前もって作成されていなければなりません。
警告
この関数は現在のスレッド状態を変更しません。代わりに PyEval_SaveThread() か PyEval_ReleaseThread() を利用してください。
ほとんどの場合は埋め込む Python インタプリタは1つだけですが、いくつかの場合に同一プロセス内、あるいは同一スレッド内で、複数の独立したインタプリタを作成する必要があります。サブインタプリタはこれを可能にします。 PyThreadState_Swap() 関数を使ってサブインタプリタを切り替えることができます。以下の関数を使ってサブインタプリタの作成と削除を行えます。
新しいサブインタプリタ (sub-interpreter) を生成します。サブインタプリタとは、(ほぼ完全に) 個別に分割された Python コードの実行環境です。特に、新しいサブインタプリタは、 import されるモジュール全てについて個別のバージョンを持ち、これには基盤となるモジュール __builtin__, __main__ および sys も含まれます。ロード済みのモジュールからなるテーブル (sys.modules) およびモジュール検索パス (sys.path) もサブインタプリタ毎に別個のものになります。新たなサブインタプリタ環境には sys.argv 変数がありません。また、サブインタプリタは新たな標準 I/O ストリーム sys.stdin, sys.stdout, sys.stderr を持ちます (とはいえ、これらのストリームは根底にある C ライブラリの同じ FILE 構造体を参照しています)。
戻り値は、新たなサブインタプリタが生成したスレッド状態 (thread state) オブジェクトのうち、最初のものを指しています。このスレッド状態が現在のスレッド状態 (current thread state) になります。実際のスレッドが生成されるわけではないので注意してください; 下記のスレッド状態に関する議論を参照してください。新たなインタプリタの生成に失敗すると、 NULL を返します; 例外状態はセットされませんが、これは例外状態が現在のスレッド状態に保存されることになっていて、現在のスレッド状態なるものが存在しないことがあるからです。 (他の Python/C API 関数のように、この関数を呼び出す前にはGILが保持されていなければならず、関数が処理を戻した際にも保持されたままになります; しかし、他の Python/C API 関数とは違い、関数から戻ったときの現在のスレッド状態が関数に入るときと同じとは限らないので注意してください)。
拡張モジュールは以下のような形で (サブ) インタプリタ間で共有されます: ある特定の拡張モジュールを最初に import すると、モジュールを通常通りに初期化し、そのモジュールの辞書の (浅い) コピーをしまい込んでおきます。他の (サブ) インタプリタが同じ拡張モジュールを import すると、新たなモジュールを初期化し、先ほどのコピーの内容で辞書の値を埋めます; 拡張モジュールの init 関数は呼び出されません。この挙動は、 Py_Finalize() および Py_Initialize() を呼び出してインタプリタを完全に再初期化した後に拡張モジュールを import した際の挙動とは異なるので注意してください; 再初期化後に import を行うと、拡張モジュールの initmodule は再度 呼び出されます 。
指定されたスレッド状態 tstate で表現される (サブ) インタプリタを抹消します。 tstate は現在のスレッド状態でなければなりません。下記のスレッド状態に関する議論を参照してください。関数呼び出しが戻ったとき、現在のスレッド状態は NULL になっています。このインタプリタに関連付けられた全てのスレッド状態は抹消されます。 (この関数を呼び出す前にはGILを保持しておかねばならず、ロックは関数が戻ったときも保持されています。) Py_Finalize() は、その時点で明示的に抹消されていない全てのサブインタプリタを抹消します。
サブインタプリタ (とメインインタプリタ) は同じプロセスの一部分なので、インタプリタ間の隔離は完璧ではありません — 例えば、 os.close() のような低レベルのファイル操作を使うと、 (偶然なり故意なりに) 互いのインタプリタ下にある開かれたファイルに影響を及ぼせてしまいます。拡張モジュールを (サブ) インタプリタ間で共有する方法のせいで、拡張モジュールによっては正しく動作しないかもしれません; 拡張モジュールが (静的な) グローバル変数を利用している場合や、拡張モジュールが初期化後に自身のモジュール辞書を操作する場合には特にそうです。一つのサブインタプリタで生成されたオブジェクトは他のサブインタプリタの名前空間への挿入が可能です; ユーザ定義関数、メソッド、インスタンスおよびクラスをサブインタプリタをサブインタプリタ間で共有しないように十分注意してください。というのは、これらの共有オブジェクトが実行した import 文は間違った (サブ) インタプリタのロード済みモジュール辞書に影響を及ぼす場合があるからです。
サブインタプリタを PyGILState_*() API と組み合わせるのが難しいことにも注意してください。これらのAPIはPythonのスレッド状態とOSレベルスレッドが1対1で対応していることを前提にしていて、サブインタプリタが存在するとその前提が崩れるからです。対応する PyGILState_Ensure() と PyGILState_Release() の呼び出しのペアの間では、サブインタプリタの切り替えを行わないことを強く推奨します。さらに、(ctypes のような)これらのAPIを使ってPythonの外で作られたスレッドから Pythonコードを実行している拡張モジュールはサブインタプリタを使うと壊れる可能性があります。
メインのインタプリタスレッドへの非同期通知機構が提供されています。この通知は関数ポインタと void 引数の形をしています。
各チェックインターバルにおいて、GILがリリースされて再取得されるときに、 Python はそのような提供された関数を呼び出します。この関数は例えば非同期IOハンドラなどが利用できます。通知はワーカースレッドなどからスケジュールされ、実際の呼び出しはメインスレッドで最初の、GILを所有していて任意の Python API 呼び出しが可能なタイミングで実行されます。
Python のメインスレッドへの通知を登録します。成功した場合、 func は引数 arg と共に、最初の適切なタイミングで呼び出されます。 func は GIL を取得した状態で呼び出されるので、任意の Python API を利用することができ、オブジェクトの属性にIOの完了を知らせるなど、任意の動作をすることができます。通知関数は成功したときには 0 を、例外を通知するときには -1 を返さなければなりません。通知関数は他の通知関数を再帰的に実行するために割り込まれることはありませんが、たとえばPythonコードをコールバックしたときにGILを開放して他のスレッドに切り替えられる可能性はあります。
この関数は成功して通知関数がスケジュールされたときは 0 を返します。それ以外の場合、たとえば通知バッファがいっぱいのときは、例外を設定せずに -1 を返します。
この関数はどのスレッドからでも、 Python スレッドでもそれ以外のシステムスレッドからでも呼び出すことができます。 Python スレッドから呼び出される場合は、GILを確保していてもいなくてもかまいません。
バージョン 2.7 で追加.
Python インタプリタは、プロファイル: 分析 (profile) や実行のトレース: 追跡 (trace) といった機能を組み込むために低水準のサポートを提供しています。このサポートは、プロファイルやデバッグ、適用範囲分析 (coverage analysis) ツールなどに使われます。
Python 2.2 になってから、この機能の実装は実質的に作り直され、 C から呼び出すためのインタフェースが追加されました。この C インタフェースは、プロファイルやトレース作業時に、 Python レベルの呼び出し可能オブジェクトが呼び出されることによるオーバヘッドを避け、直接 C 関数呼び出しが行えるようにしています。プロファイルやトレース機能の本質的な特性は変わっていません; インタフェースではとレース関数をスレッドごとにインストールでき、トレース関数に報告される基本イベント (basic event) は以前のバージョンにおいて Python レベルのトレース関数で報告されていたものと同じです。
PyEval_SetProfile() および PyEval_SetTrace() を使って登録できるトレース関数の形式です。最初のパラメタはオブジェクトで、登録関数に obj として渡されます。 frame はイベントが属している実行フレームオブジェクトで、 what は定数 PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, あるいは PyTrace_C_RETURN のいずれかで、 arg は what の値によって以下のように異なります:
| what の値 | arg の意味 |
|---|---|
| PyTrace_CALL | 常に NULL です。 |
| PyTrace_EXCEPTION | sys.exc_info() の返す例外情報です。 |
| PyTrace_LINE | 常に NULL です。 |
| PyTrace_RETURN | 呼び出し側に返される予定の値か、例外によって関数を抜ける場合は NULL です。 |
| PyTrace_C_CALL | 呼び出される関数オブジェクト |
| PyTrace_C_EXCEPTION | 呼び出された関数オブジェクト |
| PyTrace_C_RETURN | 呼び出された関数オブジェクト |
関数やメソッドが新たに呼び出されたり、ジェネレータが新たなエントリの処理に入ったことを報告する際の、 Py_tracefunc の what の値です。イテレータやジェネレータ関数の生成は、対応するフレーム内の Python バイトコードに制御の委譲 (control transfer) が起こらないため報告されないので注意してください。
例外が送出された際の Py_tracefunc の what の値です。現在実行されているフレームで例外がセットされ、何らかのバイトコードが処理された後に、 what にこの値がセットされた状態でコールバック関数が呼び出されます。
この結果、例外の伝播によって Python が呼び出しスタックを逆戻りする際に、各フレームから処理が戻るごとにコールバック関数が呼び出されます。トレース関数だけがこれらのイベントを受け取ります; プロファイラはこの種のイベントを必要としません。
行番号イベントを報告するときに (プロファイル関数ではなく) トレース関数の what パラメタとして渡す値です。
関数呼び出しが例外の伝播なしに返るときに Py_tracefunc 関数の what パラメタとして渡す値です。
C関数を呼び出す直前に Py_tracefunc 関数の what パラメタとして渡す値です。
C関数が例外を送出したときに Py_tracefunc 関数の what パラメタとして渡す値です。
C関数から戻るときに Py_tracefunc 関数の what パラメタとして渡す値です。
プロファイル関数を func に設定します。 obj パラメタは関数の第一パラメタとして渡され、何らかの Python オブジェクトかまたは NULL になります。プロファイル関数がスレッド状態を維持する必要があるなら、各々のスレッドに異なる obj を使うことで、状態を記憶しておく便利でスレッドセーフな場所を提供できます。プロファイル関数は、モニタされているイベントのうち、行番号イベントを除く全てのイベントに対して呼び出されます。
トレース関数を func にセットします。 PyEval_SetProfile() に似ていますが、トレース関数は行番号イベントを受け取る点が違います。
以下の関数は高度なデバッグツールでの使用のためだけのものです。
インタプリタ状態オブジェクトからなるリストのうち、先頭にあるものを返します。
バージョン 2.2 で追加.
インタプリタ状態オブジェクトからなるリストのうち、 interp の次にあるものを返します。
バージョン 2.2 で追加.
インタプリタ interp に関連付けられているスレッドからなるリストのうち、先頭にある PyThreadState オブジェクトを返します。
バージョン 2.2 で追加.
tstate と同じ PyInterpreterState オブジェクトに属しているスレッド状態オブジェクトのうち、 tstate の次にあるものを返します。
バージョン 2.2 で追加.
モジュールオブジェクト固有の関数は数個しかありません。
この PyTypeObject のインスタンスは Python のモジュールオブジェクト型を表現します。このオブジェクトは、Python プログラムには types.ModuleType として公開されています。
o がモジュールオブジェクトかモジュールオブジェクトのサブタイプであるときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
o がモジュールオブジェクトで、かつモジュールオブジェクトのサブタイプでないときに真を返します。 PyModule_Type.
バージョン 2.2 で追加.
__name__ 属性が name に設定された新たなモジュールオブジェクトを返します。モジュールの __doc__ および __name__ 属性だけに値が入っています; __file__ 属性に値を入れるのは呼び出し側の責任です。
module の名前空間を実現する辞書オブジェクトを返します; このオブジェクトはモジュールオブジェクトの __dict__ と同じです。この関数が失敗することはありません。 拡張モジュールでは、この関数で得たモジュールの __dict__ を直接いじるより、他の PyModule_*() および PyObject_*() 関数を使うよう勧めます。
module の __name__ の値を返します。モジュールがこの属性を提供していない場合や文字列型でない場合、 SystemError を送出して NULL を返します。
module をロードするために使ったファイルの名前を、 module の __file__ 属性から調べて返します。 __file__ が定義されていない場合や文字列型でない場合、 SystemError を送出して NULL を返します。
module にオブジェクトを name として追加します。この関数はモジュールの初期化関数から利用される便宜関数です。エラーのときには -1 を、成功したときには 0 を返します。
バージョン 2.0 で追加.
module に整数定数を name として追加します。この便宜関数はモジュールの初期化関数から利用されています。エラーのときには -1 を、成功したときには 0 を返します。
バージョン 2.0 で追加.
module に文字列定数を name として追加します。この便宜関数はモジュールの初期化関数から利用されています。文字列 value は null 終端されていなければなりません。エラーのときには -1 を、成功したときには 0 を返します。
バージョン 2.0 で追加.
using-capsules 以下のオブジェクトを使う方法については 拡張モジュールに C API を提供する を参照してください。
この PyObject のサブタイプは、任意の値を表し、C拡張モジュールから Pythonコードを経由して他のC言語のコードに任意の値を(void* ポインタの形で)渡す必要があるときに有用です。あるモジュール内で定義されているC言語関数のポインタを、他のモジュールに渡してそこから呼び出せるようにするためによく使われます。これにより、動的にロードされるモジュールの中の C API に通常の import 機構を通してアクセスすることができます。
カプセルに対するデストラクタコールバック型. 次のように定義されます:
typedef void (*PyCapsule_Destructor)(PyObject *);
PyCapsule_Destructor コールバックの動作については PyCapsule_New() を参照してください。
pointer を格納する PyCapsule を作成します。 pointer 引数は NULL であってはなりません。
失敗した場合、例外を設定して NULL を返します。
name 文字列は NULL か、有効なC文字列へのポインタです。 NULL で無い場合、この文字列は少なくともカプセルより長く生存する必要があります。 (destructor の中で解放することは許可されています)
destructor が NULL で無い場合、カプセルが削除されるときにそのカプセルを引数として呼び出されます。
このカプセルがモジュールの属性として保存される場合、 name は modulename.attributename と指定されるべきです。こうすると、他のモジュールがそのカプセルを PyCapsule_Import() でインポートすることができます。
カプセルに保存されている pointer を取り出します。失敗した場合は例外を設定して NULL を返します。
name 引数はカプセルに保存されている名前と正確に一致しなければなりません。もしカプセルに格納されている name が NULL なら、この関数の name 引数も同じく NULL でなければなりません。 Python は C言語の strcmp() を使ってこの name を比較します。
カプセルに保存されている現在のデストラクタを返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL をデストラクタとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred を利用して確認してください。
カプセルに保存されている現在のコンテキスト(context)を返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL をコンテキストとして持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred を利用して確認してください。
カプセルに保存されている現在の name を返します。失敗した場合、例外を設定して NULL を返します。
カプセルは NULL を name として持つことができます。従って、戻り値の NULL がエラーを指してない可能性があります。 PyCapsule_IsValid() か PyErr_Occurred を利用して確認してください。
モジュールのカプセル属性から Cオブジェクトへのポインタをインポートします。 name 引数はその属性の完全名を module.attribute のように指定しなければなりません。カプセルに格納されている name はこの文字列に正確に一致しなければなりません。 no_block が真の時、モジュールを(PyImport_InportModuleNoBlock() を使って) ブロックせずにインポートします。 no_block が偽の時、モジュールは (PyImport_ImportModule() を使って) 通常の方法でインポートされます。
成功した場合、カプセル内部の pointer を返します。失敗した場合、例外を設定して NULL を返します。ただし、 no_block が真だった場合は、 PyCapsule_Import() はモジュールのインポートに失敗しても例外を設定しません。
capsule が有効なカプセルであるかどうかをチェックします。有効な capsule は、非 NULL で、 PyCapsule_CheckExact() をパスし、非 NULL なポインタを格納していて、内部の name が引数 name とマッチします。 (name の比較方法については PyCapsule_GetPointer() を参照)
言い換えると、 PyCapsule_IsValid() が真を返す場合、全てのアクセッサ (PyCapsule_Get() で始まる全ての関数) が成功することが保証されます。
オブジェクトが有効で name がマッチした場合に非0を、それ以外の場合に 0 を返します。この関数は絶対に失敗しません。
capsule 内部のコンテキストポインタを context に設定します。
成功したら 0 を、失敗したら例外を設定して 非0 を返します。
capsule 内部のデストラクタを destructor に設定します。
成功したら 0 を、失敗したら例外を設定して 非0 を返します。
| Release: | 2.7 |
|---|---|
| Date: | 2011年 12月 26日 |
このマニュアルでは、拡張モジュールを書いたり Python インタプリタをアプリケーションに埋め込んだりしたい C/C++ プログラマが利用できる API について述べています。 Python インタプリタの拡張と埋め込み は拡張モジュールを書く際の一般的な決まりごとについて記述していますが、 API の詳細までは記述していないので、このドキュメントが手引きになります。
オブジェクトがシーケンス型プロトコルを提供している場合に 1 を返し、そうでないときには 0 を返します。この関数呼び出しは常に成功します。
成功するとシーケンス o 中のオブジェクトの数を返し、失敗すると -1 を返します。シーケンス型プロトコルをサポートしないオブジェクトに対しては、 Python の式 len(o) と同じになります。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
成功すると o1 と o2 の連結 (concatenation) を返し、失敗すると NULL を返します。 Python の式 o1 + o2 と同じです。
成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。 Python の式 o * count と同じです。
バージョン 2.5 で変更: この関数は以前は count の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
成功すると o1 と o2 の連結 (concatenation) を返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の式 o1 += o2 と同じです。
成功するとオブジェクト o の count 回繰り返しを返し、失敗すると NULL を返します。 o1 が in-place 演算をサポートする場合、in-place 演算を行います。 Python の式 o *= count と同じです。
バージョン 2.5 で変更: この関数は以前は count の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
成功すると o の i 番目の要素を返し、失敗すると NULL を返します。 Python の式 o[i] と同じです。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
成功すると o の i1 から i2 までの間のスライスを返し、失敗すると NULL を返します。 Python の式 o[i1:i2] と同じです。
バージョン 2.5 で変更: この関数は以前は i1, i2 の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o の i 番目の要素に v を代入します。失敗すると -1 を返します。 Python の文 o[i] = v と同じです。この関数は v への参照を盗み取り ません 。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o の i 番目の要素を削除します。失敗すると -1 を返します。 Python の文 del o[i] と同じです。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o の i1 から i2 までの間のスライスに v を代入します。 Python の文 o[i1:i2] = v と同じです。
バージョン 2.5 で変更: この関数は以前は i1, i2 の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
シーケンスオブジェクト o の i1 から i2 までの間のスライスを削除します。失敗すると -1 を返します。 Python の文 del o[i1:i2] と同じです。
バージョン 2.5 で変更: この関数は以前は i1, i2 の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o における value の出現回数、すなわち o[key] == value となる key の個数を返します。失敗すると -1 を返します。 Python の式 o.count(value) と同じです。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o に value が入っているか判定します。 o のある要素が value と等価 (equal) ならば 1 を返し、それ以外の場合には 0 を返します。エラーが発生すると -1 を返します。 Python の式 value in o と同じです。
o[i] == value となる最初に見つかったインデクス i を返します。エラーが発生すると -1 を返します。 Python の式 o.index(value) と同じです。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
任意のシーケンス o と同じ内容を持つリストオブジェクトを返します。返されるリストは必ず新しいリストオブジェクトになります。
任意のシーケンス o と同じ内容を持つタプルオブジェクトを返します。失敗したら NULL を返します。 o がタプルの場合、新たな参照を返します。それ以外の場合、適切な内容が入ったタプルを構築して返します。 Pythonの式 tuple(o) と同じです。
シーケンス o がすでにタプルやリストであれば o を返し、そうでなければ o をタプルで返します。返されるタプルのメンバにアクセスするには PySequence_Fast_GET_ITEM() を使ってください。失敗すると NULL を返します。オブジェクトがシーケンスでなければ、 m がメッセージテキストになっている TypeError を送出します。
o が NULL でなく、 PySequence_Fast() が返したオブジェクトであり、かつ i がインデクスの範囲内にあると仮定して、 o の i 番目の要素を返します。
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyObject ポインタの背後にあるアレイを返します．この関数では， o は PySequence_Fast() の返したオブジェクトであり， NULL でないものと仮定しています．
リストのサイズが変更されるとき、メモリ再確保が要素の配列を再配置するかもしれないことに注意してください。そのため、シーケンスの変更が発生しないコンテキストでのみ背後にあるポインタを使ってください。
バージョン 2.4 で追加.
成功すると o の i 番目の要素を返し、失敗すると NULL を返します。 PySequence_GetItem() ですが、 PySequence_Check(o)() が真になるかチェックせず、負のインデクスに対する調整を行いません。
バージョン 2.3 で追加.
バージョン 2.5 で変更: この関数は以前は i の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o が NULL でなく、 PySequence_Fast() が返したオブジェクトであると仮定して、 o の長さを返します。 o のサイズは PySequence_Size() を呼び出しても得られますが、 PySequence_Fast_GET_SIZE() の方が o をリストかタプルであると仮定して処理するため、より高速です。
この PyTypeObject のインスタンスは Python のタプル型を表現します; Python レイヤにおける tuple や types.TupleType と同じオブジェクトです。
p がタプルオブジェクトか、タプル型のサブタイプのインスタンスである場合に真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
サイズが len の新たなタプルオブジェクトを返します。失敗すると NULL を返します。
バージョン 2.5 で変更: この関数は以前は len の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
サイズが n の新たなタプルオブジェクトを返します。失敗すると NULL を返します。タプルの値は後続の n 個の Python オブジェクトを指す C 引数になります。 PyTuple_Pack(2, a, b) は Py_BuildValue("(OO)", a, b) と同じです。
バージョン 2.4 で追加.
バージョン 2.5 で変更: この関数は以前は n の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
タプルオブジェクトへのポインタを引数にとり、そのタプルのサイズを返します。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
タプル p のサイズを返しますが、 p は非 NULL でなくてはならず、タプルオブジェクトを指していなければなりません; この関数はエラーチェックを行いません。
バージョン 2.5 で変更: これらの関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
p の指すタプルオブジェクト内の、位置 pos にあるオブジェクトを返します。 pos が範囲を超えている場合、 NULL を返して IndexError 例外をセットします。
バージョン 2.5 で変更: この関数は以前は pos の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyTuple_GetItem() に似ていますが、引数に対するエラーチェックを行いません。
バージョン 2.5 で変更: この関数は以前は pos の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
p の指すタプルオブジェクト内の、位置 low から high までのスライスを取り出して、タプルオブジェクトとして返します。
バージョン 2.5 で変更: この関数は以前は low, high の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
p の指すタプルオブジェクト内の位置 pos に、オブジェクト o への参照を挿入します。成功した場合には 0 を返します。
ノート
この関数は o への参照を “盗み取り” ます。
バージョン 2.5 で変更: この関数は以前は pos の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyTuple_SetItem() に似ていますが、エラーチェックを行わず、新たなタプルに値を入れるとき 以外には使ってはなりません 。
ノート
この関数は o への参照を “盗み取り” ます。
バージョン 2.5 で変更: この関数は以前は pos の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
タプルをリサイズする際に使えます。 newsize はタプルの新たな長さです。タプルは変更不能なオブジェクト ということになっている ので、この関数はこのオブジェクトに対してただ一つしか参照がない時以外には使ってはなりません。タプルがコード中の他の部分ですでに参照されている場合には、この関数を 使ってはなりません 。タプルは常に指定サイズの末尾まで伸縮します。成功した場合には 0 を返します。クライアントコードは、 *p の値が呼び出し前と同じになると期待してはなりません。 *p が置き換えられた場合、オリジナルの *p は破壊されます。失敗すると -1 を返し、 *p を NULL に設定して、 MemoryError または SystemError を送出します。
バージョン 2.2 で変更: 使われていなかった三つ目のパラメタ、 last_is_sticky を削除しました.
バージョン 2.5 で変更: この関数は以前は newsize の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
free list をクリアします。開放したアイテム数を返します。
バージョン 2.6 で追加.
新しい codec 検索関数を登録します。
副作用として、この関数は encodings パッケージが常に検索関数の先頭に来るように、まだロードされていない場合はロードします。
encoding のための登録された codec が存在するかどうかに応じて 1 か 0 を返します。
汎用の codec ベースの encode API.
encoding に応じて見つかったエンコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。エンコーダが見つからなかった場合は LookupError を発生させます。
汎用の codec ベースの dencode API.
encoding に応じて見つかったデコーダ関数に対して object を渡します。エラーハンドリングメソッドは errors で指定します。 errors は NULL でもよく、その場合はその codec のデフォルトのメソッドが利用されます。デコーダが見つからなかった場合は LookupError を発生させます。
以下の関数では、文字列 encoding は全て小文字に変換することで、効率的に、大文字小文字を無視した検索をします。コーデックが見つからない場合、 KeyError を設定して NULL を返します。
encoding の IncrementalEncoder オブジェクトを返します。
encoding の IncrementalDecoder オブジェクトを返します。
エラーハンドルのためのコールバック関数 error を name で登録します。このコールバック関数は、コーデックがエンコードできない文字/デコードできないバイトに遭遇した時に、そのエンコード/デコード関数の呼び出しで name が指定されていたら呼び出されます。
コールバックは1つの引数として、 UnicodeEncodeError, UnicodeDecodeError, UnicodeTranslateError のどれかのインスタンスを受け取ります。このインスタンスは問題のある文字列やバイト列に関する情報と、その元の文字列中のオフセットを持っています。(その情報を取得するための関数については Unicode 例外オブジェクト を参照してください。) コールバックは渡された例外を発生させるか、2要素のタプルに問題のシーケンスの代替と、 encode/decode を再開する元の文字列中のオフセットとなる整数を格納して返します。
成功したら 0 を、エラー時は -1 を返します。
この文書は、Pythonドキュメント翻訳プロジェクトによる Python C/API Reference Release の日本語訳版です。日本語訳に対する質問や提案などがありましたら、Pythonドキュメント翻訳プロジェクトのメーリングリスト
http://www.python.jp/mailman/listinfo/python-doc-jp
または、Google Project Hosting 上の Issue Tracker
http://code.google.com/p/python-doc-ja/issues/entry
までご報告ください。
オブジェクト o をファイル fp に出力します。失敗すると -1 を返します。 flags 引数は何らかの出力オプションを有効にする際に使います。現在サポートされている唯一のオプションは Py_PRINT_RAW です; このオプションを指定すると、 repr() の代わりに str() を使ってオブジェクトを書き込みます。
o が属性 attr_name を持つときに 1 を、それ以外のときに 0 を返します。この関数は Python の式 hasattr(o, attr_name) と同じです。この関数は常に成功します。
o が属性 attr_name を持つときに 1 を、それ以外のときに 0 を返します。この関数は Python の式 hasattr(o, attr_name) と同じです。この関数は常に成功します。
オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると NULL を返します。この関数は Python の式 o.attr_name と同じです。
オブジェクト o から、名前 attr_name の属性を取得します。成功すると属性値を返し失敗すると NULL を返します。この関数は Python の式 o.attr_name と同じです。
汎用の属性取得関数で、 type オブジェクトの tp_getattro スロットに置かれることを意図されています。この関数は、オブジェクトのMRO中のクラスの辞書にあるディスクリプタと、オブジェクトの __dict__ (があれば)に格納されている属性を検索します。 デスクリプタ (descriptor) の実装 で説明されているように、データディスクリプタはインスタンス属性より優先され、非データディスクリプタは後回しにされます。見つからなかった場合は AttributeError を発生させます。
オブジェクト o の attr_name という名の属性に、値 v を設定します。失敗すると -1 を返します。この関数は Python の式 o.attr_name = v と同じです。
オブジェクト o の attr_name という名の属性に、値 v を設定します。失敗すると -1 を返します。この関数は Python の式 o.attr_name = v と同じです。
汎用の属性設定関数で、typeオブジェクトの tp_setattro スロットに置かれることを意図しています。オブジェクトのMROにあるクラス列の辞書からデータディスクリプタを探し、見つかればインスタンス辞書への格納よりもデータディスクリプタを優先します。見つからなければ、オブジェクトの __dict__ (があれば) に属性を設定します。失敗した場合、 AttributeError を発生させて -1 を返します。
オブジェクト o の attr_name という名の属性を削除します。失敗すると -1 を返します。この関数は Python の文 del o.attr_name と同じです。
オブジェクト o の attr_name という名の属性を削除します。失敗すると -1 を返します。この関数は Python の文 del o.attr_name と同じです。
o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。この関数は Python の式 o1 op o2 と同じで、 op が opid に対応する演算子です。成功すると比較結果の値を返し失敗すると NULL を返します。
o1 と o2 を opid に指定した演算によって比較します。 opid は Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, または Py_GE, のいずれかでなければならず、それぞれ <, <=, ==, !=, >, および >= に対応します。比較結果が真ならば 1 を、偽ならば 0 を、エラーが発生すると -1 を返します。この関数は Python の式 o1 op o2 と同じで、 op が opid に対応する演算子です。
ノート
o1 と o2 が同一のオブジェクトである場合、 PyObject_RichCompareBool() は Py_EQ に対して常に 1 を返し、 Py_NE に対して常に 0 を返します。
o1 と o2 の値を比較します。このとき o1 が比較ルーチンを持っていればそれを使い、なければ o2 のルーチンを使います。比較結果は result に返されます。失敗すると -1 を返します。 Python 文 result = cmp(o1, o2) と同じです。
o1 と o2 の値を比較します。このとき o1 が比較ルーチンを持っていればそれを使い、なければ o2 のルーチンを使います。比較結果は result に返されます。失敗すると -1 を返します。 Python 文 result = cmp(o1, o2) と同じです。成功すると比較結果を返します。エラーが生じた場合の戻り値は未定義です; PyErr_Occurred() を使ってエラー検出を行って下さい。Python 式 cmp(o1, o2) と同じです。
o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。Python 式 repr(o) と同じです。この関数は組み込み関数 repr() や逆クオート表記の処理で呼び出されます。
o の文字列表現を計算します。成功すると文字列表現を返し、失敗すると NULL を返します。Python 式 str(o) と同じです。この関数は組み込み関数 str() や print 文の処理で呼び出されます。
o オブジェクトの bytes 表現を計算します。 2.x では、単に PyObject_Str() のエイリアスです。
o の Unicode 文字列表現を計算します。成功すると Unicode 文字列表現を返し失敗すると NULL を返します。 Python 式 unicode(o) と同じです。この関数は組み込み関数 unicode() の処理で呼び出されます。
inst が cls のインスタンスか、 cls のサブクラスのインスタンスの場合に -1 を返し、そうでなければ 0 を返します。エラーの時には -1 を返し、例外をセットします。 cls がクラスオブジェクトではなく型オブジェクトの場合、 PyObject_IsInstance() は inst が cls であるときに 1 を返します。 cls をタプルで指定した場合、 cls に指定した全てのエントリについてチェックを行います。少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 inst がクラスインスタンスでなく、かつ cls が型オブジェクトでもクラスオブジェクトでもタプルでもない場合、 inst には __class__ 属性がなくてはなりません — この場合、 __class__ 属性の値と、 cls の値の間のクラス関係を、関数の戻り値を決定するのに使います。
バージョン 2.1 で追加.
バージョン 2.2 で変更: 二つ目の引数にタプルのサポートを追加しました。.
サブクラスの決定はかなり正攻法で行いますが、クラスシステムの拡張を実装する人たちに知っておいて欲しいちょっとした問題点があります。 A と B がクラスオブジェクトの場合、 B が A のサブクラスとなるのは、 B が A を直接的あるいは間接的に継承 (inherit) している場合です。両方がクラスオブジェクトでない場合、二つのオブジェクト間のクラス関係を決めるには、より汎用の機構を使います。 B が A のサブクラスであるか調べたとき、 A が B と等しければ、 PyObject_IsSubclass() は真を返します。 A および B が異なるオブジェクトなら、 B の __bases__ 属性から深さ優先探索 (depth-first search)で A を探索します — オブジェクトに __bases__ があるだけで、この決定法を適用する条件を満たしているとみなされます。
クラス derived が cls と同じクラスか、 cls の派生クラスの場合に 1 を返し、それ以外の場合には 0 を返します。エラーが生じると -1 を返します。 cls をタプルで指定した場合、 cls に指定した全てのエントリについてチェックを行います。少なくとも一つのエントリに対するチェックが 1 を返せば結果は 1 になり、そうでなければ 0 になります。 derived または cls のいずれかが実際のクラスオブジェクト (あるいはタプル) でない場合、上で述べた汎用アルゴリズムを使います。
バージョン 2.1 で追加.
バージョン 2.3 で変更: 以前の Python のバージョンは、二つ目の引数にタプルをサポートしていませんでした.
オブジェクト o が呼び出し可能オブジェクトかどうか調べます。オブジェクトが呼び出し可能であるときに 1 を返し、そうでないときには 0 を返します。この関数呼び出しは常に成功します。
呼び出し可能な Python オブジェクト callable_object をタプルで指定された引数 args および辞書で指定された名前つき引数 (named argument) kw とともに呼び出します。名前つき引数を必要としない場合、 kw を NULL にしてもかまいません。 args は NULL であってはなりません。引数が全く必要ない場合には空のタプルを使ってください。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable_object, args, kw) あるいは callable_object(*args, **kw) と同じです。
バージョン 2.2 で追加.
呼び出し可能な Python オブジェクト callable_object をタプルで指定された引数 args とともに呼び出します。 引数を必要としない場合、 args を NULL にしてもかまいません。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable_object, args) あるいは callable_object(*args) と同じです。
呼び出し可能な Python オブジェクト callable_object を可変数個の C 引数とともに呼び出します。C 引数は Py_BuildValue() 形式のフォーマット文字列を使って記述します。 format は NULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 apply(callable, args) あるいは callable(*args) と同じです。もしも、 PyObject * args だけを引数に渡す場合は、 PyObject_CallFunctionObjArgs() がより速い方法であることを覚えておいてください。
オブジェクト o の method という名前のメソッドを、可変数個の C 引数とともに呼び出します。C 引数はタプルを生成するような Py_BuildValue() 形式のフォーマット文字列を使って記述します。 format は NULL にしてもよく、与える引数がないことを表します。成功すると呼び出し結果として得られたオブジェクトを返し、失敗すると NULL を返します。 Python の式 o.method(args) と同じです。もしも、 PyObject * args だけを引数に渡す場合は、 PyObject_CallMethodObjArgs() がより速い方法であることを覚えておいてください。
呼び出し可能な Python オブジェクト callable_object を可変数個の PyObject* 引数とともに呼び出します。引数列は末尾に NULL がついた可変数個のパラメタとして与えます。成功すると呼び出し結果として得られたオブジェクトを返し失敗すると NULL を返します。
バージョン 2.2 で追加.
オブジェクト o のメソッドを呼び出します、メソッド名は Python 文字列オブジェクト name で与えます。可変数個の PyObject* 引数と共に呼び出されます. 引数列は末尾に NULL がついた可変数個のパラメタとして与えます。成功すると呼び出し結果として得られたオブジェクトを返し失敗すると NULL を返します。
バージョン 2.2 で追加.
type(o) がハッシュ不可能であることを示す TypeError を設定し、 -1 を返します。この関数は tp_hash スロットに格納されたときには特別な扱いを受け、その type がハッシュ不可能であることをインタプリタに明示的に示します。
バージョン 2.6 で追加.
o が真を表すとみなせる場合には 1 を、そうでないときには 0 を返します。 Python の式 not not o と同じです。失敗すると -1 を返します。
o が真を表すとみなせる場合には 0 を、そうでないときには 1 を返します。 Python の式 not o と同じです。失敗すると -1 を返します。
o が NULL でない場合、オブジェクト o のオブジェクト型に相当する型オブジェクトを返します。失敗すると SystemError を送出して NULL を返します。 Python の式 type(o) と同じです。 この関数は戻り値の参照カウントをインクリメントします。参照カウントのインクリメントが必要でない限り、広く使われていて PyTypeObject* 型のポインタを返す表記法 o->ob_type の代わりに使う理由は全くありません。
オブジェクト o が、 type か type のサブタイプであるときに真を返します。どちらのパラメタも NULL であってはなりません。
バージョン 2.2 で追加.
o の長さを返します。オブジェクト o がシーケンス型プロトコルとマップ型プロトコルの両方を提供している場合、シーケンスとしての長さを返します。エラーが生じると -1 を返します。 Python の式 len(o) と同じです。
バージョン 2.5 で変更: これらの関数は以前は int 型を返していました。 この変更により、 64bit システムを適切にサポートするためにはコードの修正が必要になります。
成功するとオブジェクト key に対応する o の要素を返し、失敗すると NULL を返します。 Python の式 o[key] と同じです。
オブジェクト key を値 v に対応付けます。失敗すると -1 を返します。 Python の文 o[key] = v と同じです。
オブジェクト o から key に対する対応付けを削除します。失敗すると -1 を返します。 Python の文 del o[key] と同じです。
Python オブジェクトからファイル記述子を取り出します。オブジェクトが整数か長整数なら、その値を返します。 (長)整数でない場合、オブジェクトに fileno() メソッドがあれば呼び出します; この場合、 fileno() メソッドは整数または長整数をファイル記述子の値として返さなければなりません。失敗すると -1 を返します。
この関数は Python の式 dir(o) と同じで、オブジェクトの変数名に割り当てている文字列からなるリスト (空の場合もあります) を返します。エラーの場合には NULL を返します。引数を NULL にすると、Python における dir() と同様に、現在のローカルな名前を返します; この場合、アクティブな実行フレームがなければ NULL を返しますが、 PyErr_Occurred() は偽を返します。
Python では二種類のイテレータオブジェクトを提供しています。一つ目はシーケンスイテレータで、 __getitem__() メソッドをサポートする任意のシーケンスを取り扱います。二つ目は呼び出し可能オブジェクトとセンチネル値 (sentinel value) を扱い、シーケンス内の要素ごとに呼び出し可能オブジェクトを呼び出して、センチネル値が返されたときに反復処理を終了します。
PySeqIter_New() や、組み込みシーケンス型に対して 1 引数形式の組み込み関数 iter() を呼び出したときに返される、イテレータオブジェクトの型オブジェクトです。
バージョン 2.2 で追加.
PySeqIter_Type の型が op のときに真を返します。
バージョン 2.2 で追加.
一般的なシーケンスオブジェクト seq を扱うイテレータを返します。反復処理は、シーケンスが添字指定操作の際に IndexError を返したときに終了します。
バージョン 2.2 で追加.
PyCallIter_New() や、組み込み関数 iter() の 2 引数形式が返すイテレータオブジェクトの型オブジェクトです。 iter() built-in function.
バージョン 2.2 で追加.
PyCallIter_Type の型が op のときに真を返します。
バージョン 2.2 で追加.
Python が循環参照を含むガベージの検出とコレクションをサポートするには、他のオブジェクトに対する “コンテナ” (他のオブジェクトには他のコンテナも含みます) となるオブジェクト型によるサポートが必要です。他のオブジェクトに対する参照を記憶しないオブジェクトや、 (数値や文字列のような) アトム型 (atomic type) への参照だけを記憶するような型では、ガベージコレクションに際して特別これといったサポートを提供する必要はありません。
コンテナ型を作るには、型オブジェクトの tp_flags フィールドに Py_TPFLAGS_HAVE_GC フラグがなくてはならず、 tp_traverse ハンドラの実装を提供しなければなりません。実装する型のインスタンスを変更可能なオブジェクトにするなら、 tp_clear の実装も提供しなければなりません。
このフラグをセットした型のオブジェクトは、この節に述べた規則に適合しなければなりません。簡単のため、このフラグをセットした型のオブジェクトをコンテナオブジェクトと呼びます。
コンテナ型のコンストラクタは以下の二つの規則に適合しなければなりません:
PyObject_New() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト用です。
PyObject_NewVar() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト用です。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyObject_NewVar() が確保したオブジェクトのメモリをリサイズします。リサイズされたオブジェクトを返します。失敗すると NULL を返します。
バージョン 2.5 で変更: この関数は以前は newsize の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
ガベージコレクタが追跡しているコンテナオブジェクトの集合にオブジェクト op を追加します。ガベージコレクタの動作する回数は予測不能なので、追加対象にするオブジェクトは追跡されている間ずっと有効なオブジェクトでなければなりません。この関数は、通常コンストラクタの最後付近で、 tp_traverse ハンドラ以降の全てのフィールドが有効な値になった時点で呼び出さねばなりません。
PyObject_GC_Track() のマクロ版です。拡張モジュールに使ってはなりません。
同様に、オブジェクトのメモリ解放関数も以下の二つの規則に適合しなければなりません:
PyObject_GC_New() や PyObject_GC_NewVar() を使って確保されたメモリを解放します。
ガベージコレクタが追跡しているコンテナオブジェクトの集合からオブジェクト op を除去します。再度 PyObject_GC_Track() を呼び出して、除去したオブジェクトを追跡対象セットに追加できることに注意してください。メモリ解放関数 (deallocator, tp_dealloc ハンドラ) は、 tp_traverse ハンドラが使用しているフィールドのいずれかが無効化されるよりも以前にオブジェクトに対して呼び出されていなければなりません。
PyObject_GC_UnTrack() のマクロ版です。拡張モジュールに使ってはなりません。
tp_traverse ハンドラは以下の型を持つ関数を引数の一つとしてとります:
tp_traverse ハンドラに渡すビジタ関数 (visitor function) の型です。この関数は追跡すべきオブジェクトを object に、 tp_traverse ハンドラの第三引数を arg にして呼び出されます。Python のコア部分では、ガベージコレクションの実装に複数のビジタ関数を使っています。ユーザが独自にビジタ関数を書く必要があるとは想定されていません。
tp_traverse ハンドラは以下の型でなければなりません:
コンテナオブジェクトのためのトラバーサル関数 (traversal function) です。実装では、 self に直接入っている各オブジェクトに対して visit 関数を呼び出さねばなりません。このとき、 visit へのパラメタはコンテナに入っている各オブジェクトと、このハンドラに渡された arg の値です。 visit 関数は NULL オブジェクトを引数に渡して呼び出してはなりません。 visit が非ゼロの値を返す場合、エラーが発生し、戻り値をそのまま返すようににしなければなりません。
tp_traverse ハンドラの作成を単純化するため、 Py_VISIT() マクロが提供されています。このマクロを使うには、 tp_traverse の実装で、引数を visit および arg という名前にしておかねばなりません:
引数 o および arg を使って visit コールバックを呼び出します。 visit が非ゼロの値を返した場合、その値をそのまま返します。このマクロを使えば、 tp_traverse ハンドラは以下のようになります:
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
Py_VISIT(self->foo);
Py_VISIT(self->bar);
return 0;
}
バージョン 2.4 で追加.
tp_clear ハンドラは inquiry 型にするか、オブジェクトが変更不能の場合には NULL にしなければなりません。
循環参照を形成しているとおぼしき参照群を放棄します。変更不可能なオブジェクトは循環参照を直接形成することが決してないので、この関数を定義する必要はありません。このメソッドを呼び出した後でもオブジェクトは有効なままでなければならないので注意してください (参照に対して Py_DECREF() を呼ぶだけにしないでください)。ガベージコレクタは、オブジェクトが循環参照を形成していることを検出した際にこのメソッドを呼び出します。
現在のスレッド状態のフレームを返します。現在実行中のフレームがなければ NULL を返します。
frame が現在実行している行番号を返します。
現在のフレームがありそれが制限モードで実行していた場合、真を返します。それ以外の場合は僞を返します。
func が 関数、クラス、インスタンスオブジェクトであればその名前を、そうでなければ func の型を返します。
func の型に依存する、解説文字列(description string)を返します。戻り値は、関数とメソッドに対しては “()”, ” constructor”, ” instance”, ” object” です。 PyEval_GetFuncName() と連結された結果、 func の解説になります。
バージョン 2.2 で追加.
イテレータを扱うための固有の関数は二つしかありません。
反復処理 o における次の値を返します。オブジェクトがイテレータの場合、この関数は反復処理における次の値を取り出します。要素が何も残っていない場合には例外がセットされていない状態で NULL を返します。オブジェクトがイテレータでない場合には TypeError を送出します。要素を取り出す際にエラーが生じると NULL を返し、発生した例外を送出します。
イテレータの返す要素にわたって反復処理を行うループを書くと、 C のコードは以下のようになるはずです:
PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;
if (iterator == NULL) {
/* エラーの伝播処理をここに書く */
}
while (item = PyIter_Next(iterator)) {
/* 取り出した要素で何らかの処理を行う */
...
/* 終わったら参照を放棄する */
Py_DECREF(item);
}
Py_DECREF(iterator);
if (PyErr_Occurred()) {
/* エラーの伝播処理をここに書く */
}
else {
/* 別の処理を続ける */
}
Python は 弱参照 を第一級オブジェクト (first-class object) としてサポートします。弱参照を直接実装する二種類の固有のオブジェクト型があります。第一は単純な参照オブジェクトで、第二はオリジナルのオブジェクトに対して可能な限りプロキシとして振舞うオブジェクトです。
ob が参照オブジェクトかプロキシオブジェクトの場合に真を返します。
バージョン 2.2 で追加.
ob が参照オブジェクトの場合に真を返します。
バージョン 2.2 で追加.
ob がプロキシオブジェクトの場合に真を返します。
バージョン 2.2 で追加.
ob に対する弱参照オブジェクトを返します。この関数は常に新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証はありません; 既存の参照オブジェクトが返されることもあります。第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして受け取ります。 callback は None や NULL にしてもかまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、 None 、 NULL のいずれでもない場合は、 NULL を返して TypeError を送出します。
バージョン 2.2 で追加.
ob に対する弱参照プロキシオブジェクトを返します。この関数は常に新たな参照を返しますが、必ずしも新たなオブジェクトを作る保証はありません; 既存の参照オブジェクトが返されることもあります。第二のパラメタ callback は呼び出し可能オブジェクトで、 ob がガーベジコレクションされた際に通知を受け取ります; callback は弱参照オブジェクト自体を単一のパラメタとして受け取ります。 callback は None や NULL にしてもかまいません。 ob が弱参照できないオブジェクトの場合や、 callback が呼び出し可能オブジェクト、 None 、 NULL のいずれでもない場合は、 NULL を返して TypeError を送出します。
バージョン 2.2 で追加.
弱参照 ref が参照しているオブジェクトを返します。被参照オブジェクトがすでに存続していない場合、 Py_None を返します。
バージョン 2.2 で追加.
警告
この関数は参照先オブジェクトの 借り物の参照 を返します。そのため、そのオブジェクトを利用している間そのオブジェクトが破棄されないことが判っている場合を除き、常に Py_INCREF() を呼び出すべきです。
PyWeakref_GetObject() に似ていますが、マクロで実装されていて、エラーチェックを行いません。
バージョン 2.2 で追加.
Pythonの関数にはいくつかの種類があります。
関数に使われるCの構造体
PyTypeObject 型のインスタンスで、 Python の関数型を表します。これは Python プログラムに types.FunctionType として公開されます。
o が関数オブジェクト (PyFunction_Type を持っている) なら true を返します。引数は NULL であってはいけません。
コードオブジェクト code に関連付けられた新しい関数オブジェクトを返します。 globals はこの関数からアクセスできるグローバル変数の辞書でなければなりません。
関数のドキュメント文字列、名前および __module__ はコードオブジェクトから取得されます。引数のデフォルト値やクロージャは NULL にセットされます。
関数オブジェクト op に関連付けられたコードオブジェクトを返します。
関数オブジェクト op に関連付けられたglobals辞書を返します。
関数オブジェクト op の __module__ 属性を返します。 これは普通はモジュール名の文字列が入っていますが、Python コードから他のオブジェクトをセットされることもあります。
関数オブジェクト op の引数のデフォルト値を返します。引数のタプルか NULL になります。
関数オブジェクト op の引数のデフォルト値を設定します。 defaults は Py_None かタプルでなければいけません。
失敗した時は、 SystemError を発生し、 -1 を返します。
関数オブジェクト op に設定されたクロージャを返します。 NULL か cell オブジェクトのタプルです。
関数オブジェクト op にクロージャを設定します。 closure は、 Py_None もしくは cell オブジェクトのタプルでなければなりません。
失敗した時は、 SystemError を送出し、 -1 を返します。
これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利です。詳しい情報や用例は Python インタプリタの拡張と埋め込み にあります。
最初に説明する 3 つの関数、 PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(),および PyArg_Parse() はいずれも 書式化文字列 (format string) を使います。書式化文字列は、関数が受け取るはずの引数に関する情報を伝えるのに用いられます。いずれの関数における書式化文字列も、同じ書式を使っています。
書式化文字列は、ゼロ個またはそれ以上の “書式化単位 (format unit)” から成り立ちます。 1つの書式化単位は1つの Python オブジェクトを表します; 通常は単一の文字か、書式化単位からなる文字列を括弧で囲ったものになります。例外として、括弧で囲われていない書式化単位文字列が単一のアドレス引数に対応する場合がいくつかあります。以下の説明では、引用符のついた形式は書式化単位です; (丸)括弧で囲った部分は書式化単位に対応する Python のオブジェクト型です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。
これは s の変化形で、値を二つの変数に記録します。一つ目の変数はキャラクタ文字列へのポインタで、二つ目はその長さです。この書式化単位の場合には、Python 文字列に null バイトが埋め込まれていてもかまいません。 Unicode オブジェクトの場合、デフォルトエンコーディングでの変換が可能ならば、変換したオブジェクトから文字列へのポインタを返します。その他の読み出しバッファ互換オブジェクトは生の内部データ表現への参照を返します。
Python 2.5 から、長さの引数の型を、 Python.h を include する前に PY_SSIZE_T_CLEAN マクロ を定義することで制御できるようになりました。もしこのマクロが定義されていた場合、長さは int ではなく Py_ssize_t になります。
s# と似ていますが、呼び出し元から渡された Py_buffer 構造体に書き込みます。バッファーはロックされるので、呼び出し元はそのバッファーを Py_BEGIN_ALLOW_THREADS したブロック内でさえも利用することができます。その代わり、呼び出し元には、データを処理した後にその構造体に対して PyBuffer_Release する責任があります。
バージョン 2.6 で追加.
s* の s を z にしたような意味です。
バージョン 2.6 で追加.
これは s の変化形で、Unicode オブジェクトや Unicode に変換可能なオブジェクトをキャラクタ型バッファにエンコードするために用いられます。NUL バイトが埋め込まれていない文字列でのみ動作します。
この書式化単位には二つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型でなければなりません。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。
PyArg_ParseTuple() を使うと、必要なサイズのバッファを確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。
s# の変化形で、Unicode オブジェクトや Unicode に変換可能なオブジェクトをキャラクタ型バッファにエンコードするために用いられます。 es 書式化単位と違って、この変化形はバイトが埋め込まれていてもかまいません。
この書式化単位には三つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型か NULL でなければなりません。 NULL の場合にはデフォルトエンコーディングを使います。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。第三の引数は整数へのポインタでなければなりません; ポインタが参照している整数の値は出力バッファ内のバイト数にセットされます。
この書式化単位の処理には二つのモードがあります:
*buffer が NULL ポインタを指している場合、関数は必要なサイズのバッファを確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。
*buffer が非 NULL のポインタ (すでにメモリ確保済みのバッファ) を指している場合、 PyArg_ParseTuple() はこのメモリ位置をバッファとして用い、 *buffer_length の初期値をバッファサイズとして用います。 PyArg_ParseTuple() は次にエンコード済みのデータをバッファにコピーして、NUL で終端します。バッファの大きさが足りなければ ValueError がセットされます。
どちらの場合も、 *buffer_length は終端の NUL バイトを含まないエンコード済みデータの長さにセットされます。
Python の整数を、オーバフローチェックを行わずに、 C の unsigned char 型の小さな整数に変換します。
バージョン 2.3 で追加.
Python の整数を、オーバフローチェックを行わずに、 C の unsigned short int 型に変換します。
バージョン 2.3 で追加.
Python の整数を、オーバフローチェックを行わずに、 C の unsigned int 型に変換します。
バージョン 2.3 で追加.
Python の整数もしくは長整数を、オーバフローチェックを行わずに、 C の unsigned long int 型に変換します。
バージョン 2.3 で追加.
Python の整数もしくは長整数を、オーバフローチェックを行わずに、 C の unsigned long long 型に変換します。この書式化単位は、 unsigned long long 型 (または Windows の unsigned _int64 型) がサポートされているプラットフォームでのみ利用できます。
バージョン 2.3 で追加.
Python の整数もしくは長整数をCの Py_ssize_t 型に変換します。
バージョン 2.5 で追加.
Python オブジェクトを converter 関数を介して C の変数に変換します。二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数へのアドレスを void * 型に変換したものです。 converter は以下のようにして呼び出されます:
status = converter(object, address);
ここで object は変換対象の Python オブジェクトで、 address は PyArg_Parse*() に渡した void* 型の引数です。戻り値 status は変換に成功した際に 1,失敗した場合には 0 になります。変換に失敗した場合、 converter 関数は address の内容を変更せずに例外を送出しなくてはなりません。
s に対する s* と同じ、 w のバージョンです。
バージョン 2.6 で追加.
オブジェクトは items に入っている書式化単位の数だけの長さを持つ Python のシーケンス型でなくてはなりません。各 C 引数は items 内の個々の書式化単位に対応づけできねばなりません。シーケンスの書式化単位は入れ子構造にできます。
ノート
Python のバージョン 1.5.2 より以前は、この書式化指定文字列はパラメタ列ではなく、個別のパラメタが入ったタプルでなければなりませんでした。このため、以前は TypeError を引き起こしていたようなコードが現在は例外を出さずに処理されるかもしれません。とはいえ、既存のコードにとってこれは問題ないと思われます。
Python 整数型を要求している場所に Python 長整数型を渡すのは可能です; しかしながら、適切な値域チェックはまったく行われません — 値を受け取るためのフィールドが、値全てを受け取るには小さすぎる場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、このセマンティクスは C のダウンキャスト (downcast) から継承しています — その恩恵は人それぞれかもしれませんが)。
その他、書式化文字列において意味を持つ文字がいくつかあります。それらの文字は括弧による入れ子内には使えません。以下に文字を示します:
呼び出し側に提供される Python オブジェクトの参照は全て 借りた (borrowed) ものです; オブジェクトの参照カウントをデクリメントしてはなりません!
以下の関数に渡す補助引数 (additional argument) は、書式化文字列から決定される型へのアドレスでなければなりません; 補助引数に指定したアドレスは、タプルから入力された値を保存するために使います。上の書式化単位のリストで説明したように、補助引数を入力値として使う場合がいくつかあります; その場合、対応する書式化単位の指定する形式に従うようにせねばなりません。
変換を正しく行うためには、 arg オブジェクトは書式化文字に一致しなければならず、かつ書式化文字列内の書式化単位に全て値が入るようにせねばなりません。成功すると、 PyArg_Parse*() 関数は真を返します。それ以外の場合には偽を返し、適切な例外を送出します。書式化単位のどれかの変換失敗により PyArg_Parse*() が失敗した場合、失敗した書式化単位に対応するアドレスとそれ以降のアドレスの内容は変更されません。
固定引数のみを引数にとる関数のパラメタを解釈して、ローカルな変数に変換します。成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
PyArg_ParseTuple() と同じですが、可変長の引数ではなく va_list を引数にとります。
固定引数およびキーワード引数をとる関数のパラメタを解釈して、ローカルな変数に変換します。成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
PyArg_ParseTupleAndKeywords() と同じですが、可変長の引数ではなく va_list を引数にとります。
“旧スタイル” の関数における引数リストを分析するために使われる関数です — 旧スタイルの関数は、引数解釈手法に METH_OLDARGS を使います。新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、標準のインタプリタにおけるほとんどのコードがもはや引数解釈のためにこの関数を使わないように変更済みです。この関数を残しているのは、この関数が依然として引数以外のタプルを分析する上で便利だからですが、この目的においては将来も使われつづけるかもしれません。
パラメータ取得を簡単にした形式で、引数の型を指定する書式化文字列を使いません。パラメタの取得にこの手法を使う関数は、関数宣言テーブル、またはメソッド宣言テーブル内で METH_VARARGS として宣言しなくてはなりません。実引数の入ったタプルは args に渡します; このタプルは本当のタプルでなくてはなりません。タプルの長さは少なくとも min で、 max を超えてはなりません; min と max が等しくてもかまいません。補助引数を関数に渡さなくてはならず、各補助引数は PyObject* 変数へのポインタでなくてはなりません; これらの補助引数には、 args の値が入ります; 値の参照は借りた参照です。オプションのパラメタに対応する変数のうち、 args に指定していないものには値が入りません; 呼び出し側はそれらの値を初期化しておかねばなりません。この関数は成功すると真を返し、 args がタプルでない場合や間違った数の要素が入っている場合に偽を返します; 何らかの失敗が起きた場合には例外をセットします。
この関数の使用例を以下に示します。この例は、弱参照のための _weakref 補助モジュールのソースコードからとったものです:
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
PyObject *object;
PyObject *callback = NULL;
PyObject *result = NULL;
if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
result = PyWeakref_NewRef(object, callback);
}
return result;
}
この例における PyArg_UnpackTuple() 呼び出しは、 PyArg_ParseTuple() を使った以下の呼び出し:
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
と全く等価です。
バージョン 2.2 で追加.
バージョン 2.5 で変更: この関数は min と max に int を利用していました。 この変更により、64 bitシステムを正しくサポートするためには修正が必要になるでしょう。
PyArg_Parse*() ファミリの関数が受け取るのと似た形式の書式化文字列および値列に基づいて、新たな値を生成します。生成した値を返します。エラーの場合には NULL を返します; NULL を返す場合、例外を送出するでしょう。
Py_BuildValue() は常にタプルを生成するとは限りません。この関数がタプルを生成するのは、書式化文字列に二つ以上の書式化単位が入っているときだけです。書式化文字列が空の場合、 None を返します; 書式化単位が厳密に一つだけ入っている場合、書式化単位で指定されている何らかのオブジェクト単体を返します。サイズがゼロや 1 のタプルを返すように強制するには、丸括弧で囲われた書式化文字列を使います。
書式化単位 s や s# の場合のように、オブジェクトを構築する際にデータを供給するためにメモリバッファをパラメタとして渡す場合には、指定したデータはコピーされます。 Py_BuildValue() が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照しません。別の言い方をすれば、 malloc() を呼び出してメモリを確保し、それを Py_BuildValue() に渡した場合、コード内で Py_BuildValue() が返った後で free() を呼び出す責任があるということです。
以下の説明では、引用符のついた形式は書式化単位です; (丸)括弧で囲った部分は書式化単位が返す Python のオブジェクト型です; [角] 括弧は関数に渡す値の C 変数型です。
書式化文字列内では、(s# のような書式化単位を除いて) スペース、タブ、コロンおよびコンマは無視されます。これらの文字を使うと、長い書式化文字列をちょっとだけ読みやすくできます。
C の unsigned long を Python の整数オブジェクト、あるいは長整数オブジェクトに変換します。
バージョン 2.5 で追加.
書式化文字列に関するエラーが生じると、 SystemError 例外をセットして NULL を返します。
Py_BuildValue() と同じですが、可変長引数の代わりに va_list を受け取ります。
この節のマクロはPythonオブジェクトの参照カウントを管理するために使われます。
オブジェクト o に対する参照カウントを一つ増やします。オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XINCREF() を使ってください。
オブジェクト o に対する参照カウントを一つ減らします。オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XDECREF() を使ってください。参照カウントがゼロになったら、オブジェクトの型のメモリ解放関数(NULL であってはならない)が呼ばれます。
警告
(例えば __del__() メソッドをもつクラスインスタンスがメモリ解放されたときに)メモリ解放関数は任意のPythonコードを呼び出すことができます。このようなコードでは例外は伝播しませんが、実行されたコードはすべてのPythonグローバル変数に自由にアクセスできます。これが意味するのは、 Py_DECREF() が呼び出されるより前では、グローバル変数から到達可能などんなオブジェクトも一貫した状態にあるべきであるということです。例えば、リストからオブジェクトを削除するコードは削除するオブジェクトへの参照を一時変数にコピーし、リストデータ構造を更新し、それから一時変数に対して Py_DECREF() を呼び出すべきです。
オブジェクト o への参照カウントを一つ減らします。オブジェクトは NULL でもかまいませんが、その場合マクロは何の影響も与えません。それ以外の場合、結果は Py_DECREF() と同じです。また、注意すべきことも同じです。
o の参照カウントを減らします．オブジェクトは NULL でもよく，その場合このマクロは何も行いません．オブジェクトが NULL でなければ，引数を NULL にした Py_DECREF() と同じ効果をもたらします．このマクロは一時変数を使って，参照カウントをデクリメントする前に引数を NULL にセットしてくれるので， Py_DECREF() に使うときの警告を気にしなくてすみます．
ガベージコレクション中に追跡される可能性のある変数の参照デクリメントを行うには，このマクロを使うのがよいでしょう．
バージョン 2.4 で追加.
以下の関数: Py_IncRef(PyObject *o), Py_DecRef(PyObject *o), は，実行時の動的な Python 埋め込みで使われる関数です．これらの関数はそれぞれ Py_XINCREF() および Py_XDECREF() をエクスポートしただけです．
以下の関数やマクロ: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference() は，インタプリタのコアの内部においてのみ使用するためのものです。また、グローバル変数 _Py_RefTotal も同様です。
datetime モジュールでは、様々な日付オブジェクトや時刻オブジェクトを提供しています。以下に示す関数を使う場合には、あらかじめヘッダファイル datetime.h をソースに include し (Python.h はこのファイルを include しません)、 PyDateTime_IMPORT マクロを、通常はモジュール初期化関数から、起動しておく必要があります。このマクロは以下のマクロで使われる静的変数 PyDateTimeAPI に C 構造体へのポインタを入れます。
以下は型チェックマクロです:
ob が PyDateTime_DateType 型か PyDateTime_DateType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_DateType 型のオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_DateTimeType 型か PyDateTime_DateTimeType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_DateTimeType 型のオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_TimeType 型か PyDateTime_TimeType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_TimeType 型のオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_DeltaType 型か PyDateTime_DeltaType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_DeltaType 型のオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_TZInfoType 型か PyDateTime_TZInfoType 型のサブタイプのオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
ob が PyDateTime_TZInfoType 型のオブジェクトの場合に真を返します; ob は NULL であってはなりません。
バージョン 2.4 で追加.
以下はオブジェクトを作成するためのマクロです:
指定された年、月、日の datetime.date オブジェクトを返します。
バージョン 2.4 で追加.
指定された年、月、日、時、分、秒、マイクロ秒の datetime.datetime オブジェクトを返します。
バージョン 2.4 で追加.
指定された時、分、秒、マイクロ秒の datetime.time オブジェクトを返します。
バージョン 2.4 で追加.
指定された日、秒、マイクロ秒の datetime.timedelta オブジェクトを返します。マイクロ秒と秒が datetime.timedelta オブジェクトで定義されている範囲に入るように正規化を行います。
バージョン 2.4 で追加.
以下のマクロは date オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_Date またはそのサブクラス (例えば PyDateTime_DateTime)の インスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:
年を正の整数で返します。
バージョン 2.4 で追加.
月を 1 から 12 の間の整数で返します。
バージョン 2.4 で追加.
日を 1 から 31 の間の整数で返します。
バージョン 2.4 で追加.
以下のマクロは datetime オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_DateTime またはそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:
時を 0 から 23 の間の整数で返します。
バージョン 2.4 で追加.
分を 0 から 59 の間の整数で返します。
バージョン 2.4 で追加.
秒を 0 から 59 の間の整数で返します。
バージョン 2.4 で追加.
マイクロ秒を 0 から 999999 の間の整数で返します。
バージョン 2.4 で追加.
以下のマクロは time オブジェクトからフィールド値を取り出すためのものです。引数は PyDateTime_Time またはそのサブクラスのインスタンスでなければなりません。引数を NULL にしてはならず、型チェックは行いません:
時を 0 から 23 の間の整数で返します。
バージョン 2.4 で追加.
分を 0 から 59 の間の整数で返します。
バージョン 2.4 で追加.
秒を 0 から 59 の間の整数で返します。
バージョン 2.4 で追加.
マイクロ秒を 0 から 999999 の間の整数で返します。
バージョン 2.4 で追加.
以下のマクロは DB API を実装する上での便宜用です:
この章の関数を使うとファイルまたはバッファにあるPythonソースコードを実行できますが、より詳細なやり取りをインタプリタとすることはできないでしょう。
これらの関数のいくつかは引数として文法の開始記号を受け取ります。使用できる開始記号は Py_eval_input と Py_file_input 、 Py_single_input です。開始期号の説明はこれらを引数として取る関数の後にあります。
これらの関数のいくつかが FILE* 引数をとることにも注意してください。注意深く扱う必要がある特別な問題の1つは、異なるCライブラリの FILE 構造体は異なっていて互換性がない可能性があるということです。実際に(少なくとも)Windowsでは、動的リンクされる拡張が異なるライブラリを使うことが可能であり、したがって、 FILE* 引数がPythonランタイムが使っているライブラリと同じライブラリによって作成されたことが確かならば、単にこれらの関数へ渡すだけということに注意すべきです。
標準インタプリタのためのメインプログラム。Pythonを組み込むプログラムのためにこれを利用できるようにしています。 argc と argv 引数をCプログラムの main() 関数へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値はインタプリタが(例外などではなく)普通に終了した時は 0 に、例外で終了したときには 1 に、引数リストが正しい Python コマンドラインが渡されなかったときは 2 になります。
Py_InspectFlag が設定されていない場合、未処理の SystemExit 例外が発生すると、この関数は 1 を返すのではなくプロセスを exit することに気をつけてください。
下記の PyRun_AnyFileExFlags() の closeit を 0 に、 flags を NULL にして単純化したインタフェースです。
下記の PyRun_AnyFileExFlags() の closeit を 0 にして単純化したインタフェースです。
下記の PyRun_AnyFileExFlags() の flags を NULL にして単純化したインタフェースです。
fp が対話的デバイス(コンソールや端末入力あるいはUnix仮想端末)と関連づけられたファイルを参照しているならば、 PyRun_InteractiveLoop() の値を返します。それ以外の場合は、 PyRun_SimpleFile() の結果を返します。 filename が NULL ならば、この関数はファイル名として "???" を使います。
下記の PyRun_SimpleStringFlags() の PyCompilerFlags* を NULL にして単純化したインタフェースです。
__main__ モジュールの中で flags に従って command に含まれる Python ソースコードを実行します。 __main__ がまだ存在しない場合は作成されます。正常終了の場合は 0 を返し、また例外が発生した場合は -1 を返します。エラーがあっても、例外情報を得る方法はありません。 flags の意味については、後述します。
Py_InspectFlag が設定されていない場合、未処理の SystemExit 例外が発生すると、この関数は 1 を返すのではなくプロセスを exit することに気をつけてください。
下記の PyRun_SimpleStringFileExFlags() の closeit を 0 に、 flags を NULL にして単純化したインタフェースです。
下記の PyRun_SimpleStringFileExFlags() の closeit を 0 にして単純化したインタフェースです。
下記の PyRun_SimpleStringFileExFlags() の flags を NULL にして単純化したインタフェースです。
Similar to PyRun_SimpleStringFlags(), but the Python source PyRun_SimpleString() と似ていますが、Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなければなりません。 closeit が真ならば、PyRun_SimpleFileExFlags は処理を戻す前にファイルを閉じます。
下記の PyRun_InteractiveOneFlags() の flags を NULL にして単純化したインタフェースです。
対話的デバイスに関連付けられたファイルから文を一つ読み込み、 flags に従って実行します。 sys.ps1 と sys.ps2 を使って、ユーザにプロンプトを表示します。入力が正常に実行されたときは 0 を返します。例外が発生した場合は -1 を返します。パースエラーの場合はPythonの一部として配布されている errcode.h インクルードファイルにあるエラーコードを返します。 (Python.h は errcode.h をインクルードしません。したがって、必要ならば特別にインクルードしなければならないことに注意してください。)
下記の PyRun_InteractiveLoopFlags() の flags を 0 にして単純化したインタフェースです。
対話的デバイスに関連付けられたファイルからEOF に達するまで複数の文を読み込み実行します。使われます。 sys.ps1 と sys.ps2 を使って、ユーザにプロンプトを表示します。 EOFに達すると 0 を返します。
下記の PyRun_SimpleParseStringFlagsFilename() の filename を NULL に、 flags を 0 にして単純化したインタフェースです。
下記の PyRun_SimpleParseStringFlagsFilename() の filename を NULL にして単純化したインタフェースです。
開始トークン start を使って str に含まれる Python ソースコードを flags 引数に従ってパースします。効率的に評価可能なコードオブジェクトを作成するためにその結果を使うことができます。コード断片を何度も評価しなければならない場合に役に立ちます。
下記の PyRun_SimpleParseFileFlags() の flags を 0 にして単純化したインタフェースです。
PyParser_SimpleParseStringFlagsFilename() に似ていますが、 Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなけれななりません。
下記の PyRun_StringFlags() の flags を NULL にして単純化したインタフェースです。
辞書 globals と locals で指定されるコンテキストにおいて、 str に含まれるPythonソースコードをコンパイラフラグ flags のもとで実行します。パラメータ start はソースコードをパースするために使われるべき開始トークンを指定します。
コードを実行した結果をPythonオブジェクトとして返します。または、例外が発生したならば NULL を返します。
下記の PyRun_FileExFlags() の closeit を 0 にし、 flags を NULL にして単純化したインタフェースです。
下記の PyRun_FileExFlags() の flags を NULL にして単純化したインタフェースです。
下記の PyRun_FileExFlags() の closeit を 0 にして単純化したインタフェースです。
PyRun_String() と似ていますが、Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 closeit を真にすると、 PyRun_FileExFlags() から処理を戻す前にファイルを閉じます。 filename はそのファイルの名前でなければなりません。
下記の Py_CompileStringFlags() の flags を NULL にして単純化したインタフェースです。
str 内のPythonソースコードをパースしてコンパイルし、作られたコードオブジェクトを返します。開始トークンは start によって与えられます。これはコンパイル可能なコードを制限するために使うことができ、 Py_eval_input 、 Py_file_input もしくは Py_single_input であるべきです。 filename で指定されるファイル名はコードオブジェクトを構築するために使われ、トレースバックあるいは SyntaxError 例外メッセージに出てくる可能性があります。コードがパースできなかったりコンパイルできなかったりした場合に、これは NULL を返します。
PyEval_EvalCodeEx() に対するシンプルなインタフェースで、コードオブジェクトと、グローバル・ローカル変数辞書だけを受け取ります。他の引数には NULL が渡されます。
与えられた特定の環境で、コンパイル済みのコードオブジェクトを評価します。環境はグローバルとローカルの辞書、引き数の配列、キーワードとデフォルト値、クロージャーのためのセルのタプルで構成されています。
実行フレームを評価します。これは PyEval_EvalFrameEx に対するシンプルなインタフェースで、後方互換性のためのものです。
Python のインタープリタの主要な、直接的な関数です。この関数には 2000 行ほどあります。実行フレーム f に関連付けられたコードオブジェクトを実行します。バイトコードを解釈して、必要に応じて呼び出しを実行します。追加の throwflag 引数はほとんど無視できます。 - もし true なら、すぐに例外を発生させます。これはジェネレータオブジェクトの throw() メソッドで利用されます。
現在の評価フレームのフラグを変更します。成功したら true を、失敗したら false を返します。
単独の式に対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。
ファイルあるいは他のソースから読み込まれた文の並びに対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。これは任意の長さのPythonソースコードをコンパイルするときに使う記号です。
単一の文に対するPython文法の開始記号で、 Py_CompileString() と一緒に使います。これは対話式のインタプリタループのための記号です。
コンパイラフラグを収めておくための構造体です。コードをコンパイルするだけの場合、この構造体が int flags として渡されます。コードを実行する場合には PyCompilerFlags *flags として渡されます。この場合、 from __future__ import は flags の内容を変更できます。
PyCompilerFlags *flags が NULL の場合、 cf_flags は 0 として扱われ、 from __future__ import による変更は無視されます。
struct PyCompilerFlags {
int cf_flags;
}
Python の組み込みファイルオブジェクトは、全て標準 C ライブラリの FILE* サポートの上に実装されています。以下の詳細説明は一実装に関するもので、将来の Python のリリースで変更されるかもしれません。
この PyTypeObject のインスタンスは Python のファイル型を表現します。このオブジェクトは file および types.FileType として Python プログラムで公開されています。
引数が PyFileObject か PyFileObject のサブタイプのときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
引数が PyFileObject 型で、かつ PyFileObject 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
成功すると、 filename に指定した名前のファイルを mode に指定したファイルモードで開いて得た新たなファイルオブジェクトを返します。 mode のセマンティクスは標準 C ルーチン fopen() と同じです。失敗すると NULL を返します。
すでに開かれている標準 C ファイルポインタ fp から新たな PyFileObject を生成します。この関数で生成したファイルオブジェクトは、閉じる際に close に指定した関数を呼び出します。失敗すると NULL を返します。
p に関連付けられたファイルオブジェクトを FILE* で返します。
呼び出し側が GIL を開放している間もこの関数が返した FILE* オブジェクトを使うのであれば、以下に解説されている PyFile_IncUseCount() と PyFile_DecUseCount() 関数を適切に呼び出さなければなりません。
PyFileObject 内部の、 FILE* が使用中であることを示す使用数カウントをインクリメントします。これは、別のスレッドで使用中の FILE* に対して Python が fclose() を呼び出すことを防ぎます。この関数の呼び出し側は、 FILE* を使い終わったときに必ず PyFile_DecUseCount() を呼び出さなければなりません。そうしなければ、 Python はそのファイルオブジェクトを永遠に閉じません。
この関数を呼び出すときは、 GIL を取得していなければなりません。
例えば、 PyFile_AsFile() を呼び出した後、GILを開放する前にこの関数を呼び出します。
FILE *fp = PyFile_AsFile(p);
PyFile_IncUseCount(p);
/* ... */
Py_BEGIN_ALLOW_THREADS
do_something(fp);
Py_END_ALLOW_THREADS
/* ... */
PyFile_DecUseCount(p);
バージョン 2.6 で追加.
PyFileObject 内部の、 FILE* が使用中であることを示す unlocked_count メンバーをデクリメントして、呼び出し元が FILE* を使い終わったことを示します。これは、先に行った PyFile_IncUseCount() の呼び出しを取り消すためだけに呼び出されるでしょう。
この関数を呼び出すときは、 GIL を取得していなければなりません。 (上の例を参照してください)
バージョン 2.6 で追加.
p.readline([*n*]) と同じで、この関数はオブジェクト p の各行を読み出します。 p はファイルオブジェクトか、 readline() メソッドを持つ何らかのオブジェクトでかまいません。 n が 0 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が 0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を返します。 n が 0 より小さければ、長さに関わらず 1 行だけを読み出しますが、すぐにファイルの終端に到達した場合には EOFError を送出します。
setvbuf() があるシステムでのみ利用できます。この関数を呼び出してよいのはファイルオブジェクトの生成直後のみです。
Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc にします。成功すると 1 を、失敗すると 0 を返します。
バージョン 2.3 で追加.
Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc に設定し、そのエラーモードを err に設定します。
バージョン 2.6 で追加.
この関数はインタプリタの内部的な利用のために存在します。この関数は p の softspace 属性を newflag に設定し、以前の設定値を返します。この関数を正しく動作させるために、 p がファイルオブジェクトである必然性はありません; 任意のオブジェクトをサポートします (softspace 属性が設定されているかどうかのみが問題だと思ってください)。この関数は全てのエラーを解消し、属性値が存在しない場合や属性値を取得する際にエラーが生じると、 0 を以前の値として返します。この関数からはエラーを検出できませんが、そもそもそういう必要はありません。
“セル (cell)” オブジェクトは、複数のスコープから参照される変数群を実装するために使われます。セルは各変数について作成され、各々の値を記憶します; この値を参照する各スタックフレームにおけるローカル変数には、そのスタックフレームの外側で同じ値を参照しているセルに対する参照が入ります。セルで表現された値にアクセスすると、セルオブジェクト自体の代わりにセル内の値が使われます。このセルオブジェクトを使った間接参照 (dereference) は、インタプリタによって生成されたバイトコード内でサポートされている必要があります; セルオブジェクトにアクセスした際に、自動的に間接参照は起こりません。上記以外の状況では、セルオブジェクトは役に立たないはずです。
セルオブジェクトに使われる C 構造体です。
セルオブジェクトに対応する型オブジェクトです。
ob がセルオブジェクトの場合に真を返します; ob は NULL であってはなりません。
値 ob の入った新たなセルオブジェクトを生成して返します。引数を NULL にしてもかまいません。
cell の内容を返しますが、 cell が非 NULL でかつセルオブジェクトであるかどうかチェックしません。
この章ではは、特定の Python オブジェクト型固有の関数について述べています。これらの関数に間違った型のオブジェクトを渡すのは良い考えではありません; Python プログラムから何らかのオブジェクトを受け取ったとき、そのオブジェクトが正しい型になっているか確信をもてないのなら、まず型チェックを行わなければなりません; 例えば、あるオブジェクトが辞書型か調べるには、 PyDict_Check() を使います。この章は Python のオブジェクト型における “家計図” に従って構成されています。
警告
この章で述べている関数は、渡されたオブジェクトの型を注意深くチェックしはするものの、多くの関数は渡されたオブジェクトが有効な NULL なのか有効なオブジェクトなのかをチェックしません。これらの関数に NULL を渡させてしまうと、関数はメモリアクセス違反を起こして、インタプリタを即座に終了させてしまうはずです。
この節では、Python の型オブジェクトとシングルトン(singleton)オブジェクト None について述べます。
シーケンスオブジェクトに対する一般的な操作については前の章ですでに述べました; この節では、Python 言語にもともと備わっている特定のシーケンスオブジェクトについて扱います。
組み込み型を記述する際に用いられる、オブジェクトを表す C 構造体です。
オブジェクト o が型オブジェクトの場合に真を返します。標準型オブジェクトから派生したサブタイプ (subtype) のインスタンスも含みます。その他の場合には偽を返します。
オブジェクト o が型オブジェクトの場合に真を返します。標準型のサブタイプの場合は含みません。その他の場合には偽を返します。
バージョン 2.2 で追加.
内部の検索キャッシュをクリアします。現在のバージョンタグを返します。
バージョン 2.6 で追加.
内部の検索キャッシュを、その type とすべてのサブタイプに対して無効にします。この関数は type の属性や基底クラス列を変更したあとに手動で呼び出さなければなりません。
バージョン 2.6 で追加.
型オブジェクト o に、型機能 feature が設定されている場合に真を返します。型機能は各々単一ビットのフラグで表されます。
型オブジェクトが o が循環参照検出をサポートしている場合に真を返します; この関数は型機能フラグ Py_TPFLAGS_HAVE_GC の設定状態をチェックします。
バージョン 2.0 で追加.
a が b のサブタイプの場合に真を返します。
バージョン 2.2 で追加.
バージョン 2.2 で追加.
バージョン 2.5 で変更: この関数は以前は nitems の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
バージョン 2.2 で追加.
型オブジェクトの後始末処理 (finalize) を行います。この関数は全てのオブジェクトで初期化を完了するために呼び出されなくてはなりません。この関数は、基底クラス型から継承したスロットを型オブジェクトに追加する役割があります。成功した場合には 0 を返し、エラーの場合には -1 を返して例外情報を設定します。
バージョン 2.2 で追加.
この PyTypeObject のインスタンスは Python 長整数型を表現します。これは long や types.LongType と同じオブジェクトです。
引数が PyLongObject か PyLongObject のサブタイプのときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
引数が PyLongObject 型で、かつ PyLongObject 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
v から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
C の unsigned long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
C の Py_ssize_t 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
バージョン 2.6 で追加.
C の size_t 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
バージョン 2.6 で追加.
v から新しい PyLongObject オブジェクトを返します。失敗したら NULL を返します。
バージョン 2.6 で追加.
v から新しい PyLongObject オブジェクトを返します。失敗したら NULL を返します。
バージョン 2.6 で追加.
C の long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
C の unsigned long long 型から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
v の整数部から新たな PyLongObject オブジェクトを生成して返します。失敗のときには NULL を返します。
str の文字列値に基づいて、新たな PyLongObject を返します。このとき base を基数として文字列を解釈します。 pend が NULL でなければ、 *pend は str 中で数が表現されている部分以後の先頭の文字のアドレスを指しています。 base が 0 ならば、 str の先頭の文字列に基づいて基数を決定します: もし str が '0x' または '0X' で始まっていれば、基数に 16 を使います; str が '0' で始まっていれば、基数に 8 を使います; その他の場合には基数に 10 を使います。 base が 0 でなければ、 base は 2 以上 36 以下の数でなければなりません。先頭に空白がある場合は無視されます。数字が全くない場合、 ValueError が送出されます。
Unicode の数字配列を Python の長整数型に変換します。最初のパラメタ u は、 Unicode 文字列の最初の文字を指し、 length には文字数を指定し、 base には変換時の基数を指定します。基数は範囲 [2, 36] になければなりません; 範囲外の基数を指定すると、 ValueError を送出します。
バージョン 1.6 で追加.
バージョン 2.5 で変更: この関数は以前は length の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Python 整数型または長整数型をポインタ p から生成します。ポインタに入れる値は PyLong_AsVoidPtr() を使って得られるような値です。
バージョン 1.5.2 で追加.
バージョン 2.5 で変更: 整数値がLONG_MAXより大きい場合は、正の長整数を返します.
pylong の指す長整数値を、 C の long 型表現で返します。 pylong が LONG_MAX よりも大きい場合、 OverflowError を送出し、 -1 を返します。
pylong の値を long で返す。 pylong が LONG_MAX より大きかったり LONG_MIN より小さい場合、 *overflow に 1 か -1 を設定して -1 を返します。それ以外の場合は *overflow に 0 を設定します。なにか例外が発生した場合は(TypeError や MemoryErrorなど)、 *overflow は 0 で戻り値が -1 になります。
バージョン 2.7 で追加.
pylong の値を long long で返す。 pylong が PY_LLONG_MAX より大きかったり PY_LLONG_MIN より小さい場合、 *overflow に 1 か -1 を設定して -1 を返します。それ以外の場合は *overflow に 0 を設定します。なにか例外が発生した場合は(TypeError や MemoryErrorなど)、 *overflow は 0 で戻り値が -1 になります。
バージョン 2.7 で追加.
pylong の指す長整数値を、 C の Py_ssize_t 型表現で返します。 pylong が PY_SSIZE_T_MAX よりも大きい場合、 OverflowError を送出し、 -1 を返します。
バージョン 2.6 で追加.
pylong の指す長整数値を、 C の unsigned long 型表現で返します。 pylong が ULONG_MAX よりも大きい場合、 OverflowError を送出します。
pylong の指す長整数値を、 C の Py_ssize_t 型表現で返します。 pylong が PY_SSIZE_T_MAX より大きい場合、 OverflowError を発生させます。
バージョン 2.6 で追加.
pylong の指す長整数値を、 C の long long 型表現で返します。 pylong が long long で表せない場合、 OverflowError を送出し -1 を返します。
バージョン 2.2 で追加.
pylong の指す値を、 C の unsigned long long 型表現で返します。 pylong が unsigned long long で表せない場合、 OverflowError を発生させて、 (unsigned long long)-1 を返します。
バージョン 2.2 で追加.
バージョン 2.7 で変更: 負の pylong が TypeError ではなく OverflowError を発生させるようになりました。
Python 長整数値を、オーバフローチェックを行わずに C の unsigned long 型表現で返します。
バージョン 2.3 で追加.
Python 長整数値を、オーバフローチェックを行わずに C の unsigned long long 型表現で返します。
バージョン 2.3 で追加.
pylong の指す値を、 C の double 型表現で返します。 pylong が double を使って近似表現できない場合、 OverflowError 例外を送出して -1.0 を返します。
Python の整数型か長整数型を指す pylong を、 C の void ポインタに変換します。 pylong を変換できなければ、 OverflowError を送出します。この関数は PyLong_FromVoidPtr() で値を生成するときに使うような void ポインタ型を生成できるだけです。
バージョン 1.5.2 で追加.
バージョン 2.5 で変更: 値が0..LONG_MAXの範囲の外だった場合、符号付き整数と符号無し整数の両方とも利用可能です.
“デスクリプタ (descriptor)” は、あるオブジェクトのいくつかの属性について記述したオブジェクトです。デスクリプタオブジェクトは型オブジェクトの辞書内にあります。
組み込みデスクリプタ型の型オブジェクトです。
バージョン 2.2 で追加.
バージョン 2.2 で追加.
バージョン 2.2 で追加.
バージョン 2.2 で追加.
バージョン 2.2 で追加.
コードオブジェクト(Code objects)は CPython 実装の低レベルな詳細部分です。各オブジェクトは関数に束縛されていない実行可能コードの塊を表現しています。
コードオブジェクトを表現するために利用されるC構造体。この型のフィールドは何時でも変更され得ます。
Python の code 型を表現する PyTypeObject のインスタンス
新しいコードオブジェクトを返します。フレームを作成するためにダミーのコードオブジェクトが必要な場合は、代わりに PyCode_NewEmpty() を利用してください。バイトコードは頻繁に変更されるため、 PyCode_New() を直接呼び出すと、 Python の詳細バージョンに依存してしまうことがあります。
このセクションは Python 1.6 で導入された古いバッファプロトコルについて解説します。このプロトコルは、 Python 2.x 系ではサポートされていますが廃止予定扱いです。 Python 3.0 から、このプロトコルの弱点や欠点を克服した新しいバッファプロトコルが導入され、 Python 2.6 へと逆移植されました。詳細は buffer オブジェクトと memoryview オブジェクト を参照してください。
文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。
バージョン 1.6 で追加.
バージョン 2.5 で変更: この関数は以前は buffer_len の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
任意のデータを収めた読み出し専用のメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる読み出し可能バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。
バージョン 1.6 で追加.
バージョン 2.5 で変更: この関数は以前は buffer_len の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
o が単一セグメントからなる読み出し可能バッファインタフェースをサポートしている場合に 1 を返します。それ以外の場合には 0 を返します。
バージョン 2.2 で追加.
書き込み可能なメモリ上の位置へのポインタを返します。 obj 引数は単一セグメントからなる文字バッファインタフェースをサポートしていなければなりません。成功すると 0 を返し、 buffer をメモリの位置に、 buffer_len をバッファの長さに設定します。エラーの際には -1 を返し、 TypeError をセットします。
バージョン 1.6 で追加.
バージョン 2.5 で変更: この関数は以前は buffer_len の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
スライスオブジェクトの型オブジェクトです。 slice や types.SliceType と同じです。
指定した値から新たなスライスオブジェクトを返します。パラメタ start, stop, および step はスライスオブジェクトにおける同名の属性として用いられます。これらの値はいずれも NULL にでき、対応する値には None が使われます。新たなオブジェクトをアロケーションできない場合には NULL を返します。
スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このときシーケンスの長さを length と仮定します。 length よりも大きなインデクスになるとエラーとして扱います。
成功のときには 0 を、エラーのときには例外をセットせずに -1 を返します (ただし、指定インデクスのいずれか一つが None ではなく、かつ整数に変換できなかった場合を除きます。この場合、 -1 を返して例外をセットします)。
おそらくこの関数を使う気にはならないでしょう。バージョン 2.3 以前の Python でスライスオブジェクトを使いたいのなら、 PySlice_GetIndicesEx() のソースを適切に名前変更して自分の拡張モジュールのソースコード内に組み込むとよいでしょう。
バージョン 2.5 で変更: この関数は以前は length の型に int を、 start, stop, step の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PySlice_GetIndices() の置き換えとして使える関数です。
スライスオブジェクト slice における start, stop, および step のインデクス値を取得します。このときシーケンスの長さを length と仮定します。スライスの長さを slicelength に記憶します。境界をはみだしたインデクスは、通常のスライスを扱うのと同じ一貫したやり方でクリップされます。
成功のときには 0 を、エラーのときには例外をセットして -1 を返します。
バージョン 2.3 で追加.
バージョン 2.5 で変更: この関数は以前は length の型に int を、 start, stop, step, slicelength の型に int * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
Python の Bool 型は整数のサブクラスとして実装されています。ブール型の値は、 Py_False と Py_True の 2 つしかありません。従って、通常の生成／削除関数はブール型にはあてはまりません。とはいえ、以下のマクロが利用できます。
Python における False オブジェクトです。このオブジェクトはメソッドを持ちません。参照カウントの点では、他のオブジェクトと同様に扱う必要があります。
Py_False に適切な参照カウントのインクリメントを行って、関数から返すためのマクロです。
バージョン 2.4 で追加.
Py_True に適切な参照カウントのインクリメントを行って、関数から返すためのマクロです。
バージョン 2.4 で追加.
v の値に応じて Py_True または Py_False への新しい参照を返します。
バージョン 2.3 で追加.
None に対する PyTypeObject は、 Python/C API では直接公開されていないので注意してください。 None は単量子 (singleton) なので、オブジェクトのアイデンティティテスト (C では ==) を使うだけで十分だからです。同じ理由から、 PyNone_Check() 関数はありません。
この章では、新しいオブジェクト型 (new object type) を定義する際に使われる関数、型、およびマクロについて説明します。
バージョン 2.6 で追加.
この PyTypeObject のインスタンスは、 Python bytearray 型を示します。 Python レイヤでの bytearray と同じオブジェクトです。
バッファプロトコルを実装している任意のオブジェクト o から、新しい bytearray オブジェクトを作成し返します。
string とその長さ len から新しい bytearray オブジェクトを返します。失敗した場合は NULL を返します。
以下のマクロは、ポインタのチェックをしないことにより安全性を犠牲にしてスピードを優先しています。
PyByteArray_AsString() のマクロバージョン。
PyByteArray_Size() のマクロバージョン。
Python におけるメモリ管理には、全ての Python オブジェクトとデータ構造が入ったプライベートヒープ (private heap) が必須です。プライベートヒープの管理は、内部的には Python メモリマネージャ (Python memory manager) が確実に行います。Python メモリマネージャには、共有 (sharing)、セグメント分割 (segmentation)、事前割り当て (preallocation)、キャッシュ化 (caching) といった、様々な動的記憶管理の側面を扱うために、個別のコンポーネントがあります。
最低水準層では、素のメモリ操作関数 (raw memory allocator) がオペレーティングシステムのメモリ管理機構とやりとりして、プライベートヒープ内にPython 関連の全てのデータを記憶するのに十分な空きがあるかどうか確認します。素のメモリ操作関数の上には、いくつかのオブジェクト固有のメモリ操作関数があります。これらは同じヒープを操作し、各オブジェクト型固有の事情に合ったメモリ管理ポリシを実装しています。例えば、整数オブジェクトは文字列やタプル、辞書とは違ったやり方でヒープ内で管理されます。というのも、整数には値を記憶する上で特別な要件があり、速度/容量のトレードオフが存在するからです。このように、 Python メモリマネジャは作業のいくつかをオブジェクト固有のメモリ操作関数に委譲しますが、これらの関数がプライベートヒープからはみ出してメモリ管理を行わないようにしています。
重要なのは、たとえユーザがいつもヒープ内のメモリブロックを指すようなオブジェクトポインタを操作しているとしても、Python 用ヒープの管理はインタプリタ自体が行うもので、ユーザがそれを制御する余地はないと理解することです。Python オブジェクトや内部使用されるバッファを入れるためのヒープ空間のメモリ確保は、必要に応じて、Python メモリマネージャがこのドキュメント内で列挙しているPython/C API 関数群を介して行います。
メモリ管理の崩壊を避けるため、拡張モジュールの作者は決して Python オブジェクトを C ライブラリが公開している関数: malloc() 、 calloc() 、 realloc() および free() で操作しようとしてはなりません。こうした関数を使うと、C のメモリ操作関数と Python メモリマネージャとの間で関数呼び出しが交錯します。 C のメモリ操作関数とPython メモリマネージャは異なるアルゴリズムで実装されていて、異なるヒープを操作するため、呼び出しの交錯は致命的な結果を招きます。とはいえ、個別の目的のためなら、 C ライブラリのメモリ操作関数を使って安全にメモリを確保したり解放したりできます。例えば、以下がそのような例です:
PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyString_FromString(buf);
free(buf); /* malloc'ed */
return res;
この例では、I/O バッファに対するメモリ要求は C ライブラリのメモリ操作関数を使っています。 Python メモリマネジャは戻り値として返される文字列オブジェクトを確保する時にだけ必要です。
とはいえ、ほとんどの状況では、メモリの操作は Python ヒープに固定して行うよう勧めます。なぜなら、Python ヒープは Python メモリマネジャの管理下にあるからです。例えば、インタプリタを C で書かれた新たなオブジェクト型で拡張する際には、ヒープでのメモリ管理が必要です。 Python ヒープを使った方がよいもう一つの理由として、拡張モジュールが必要としているメモリについて Python メモリマネージャに 情報を提供 してほしいということがあります。たとえ必要なメモリが内部的かつ非常に特化した用途に対して排他的に用いられるものだとしても、全てのメモリ操作要求を Python メモリマネージャに委譲すれば、インタプリタはより正確なメモリフットプリント (memory footprint) の全体像を把握できます。その結果、特定の状況では、 Python メモリマネージャがガベージコレクションやメモリのコンパクト化、その他何らかの予防措置といった、適切な動作をトリガできることがあります。上の例で示したように C ライブラリのメモリ操作関数を使うと、 I/O バッファ用に確保したメモリは Python メモリマネージャの管理から完全に外れることに注意してください。
Python ヒープに対してメモリを確保したり解放したりするために、以下の関数セットが利用できます。これらの関数は ANSI C 標準に従ってモデル化されていますが、0 バイトの領域を要求した際の動作についても定義しています:
n バイトをメモリ確保し、確保されたメモリを指す void* 型のポインタを返します。確保要求に失敗した場合には NULL を返します。 0 バイトをリクエストすると、可能ならば独立した非 NULL のポインタを返します。このポインタは PyMem_Malloc(1)() を代わりに呼んだときのようなメモリ領域を指しています。確保されたメモリ領域はいかなる初期化も行われていません。
p が指しているメモリブロックを n バイトにサイズ変更します。メモリの内容のうち、新旧のサイズのうち小さい方までの領域は変更されません。 p が NULL ならば、この関数は PyMem_Malloc(n)() と等価になります; それ以外の場合で、 n がゼロに等しければ、メモリブロックはサイズ変更されますが、解放されず、非 NULL のポインタを返します。 p の値を NULL にしないのなら、以前呼び出した PyMem_Malloc() や PyMem_Realloc() の返した値でなければなりません。
p が指すメモリブロックを解放します。 p は以前呼び出した PyMem_Malloc() や PyMem_Realloc() の返した値でなければなりません。それ以外の場合や、すでに PyMem_Free(p)() を呼び出した後だった場合、未定義の動作になります。 p が NULL なら、何も行いません。
以下に挙げる型対象のマクロは利便性のために提供されているものです。 TYPE は任意の C の型を表します。
PyMem_Malloc() と同じですが、 (n * sizeof(TYPE)) バイトのメモリを確保します。 TYPE* に型キャストされたポインタを返します。メモリには何の初期化も行われていません。
PyMem_Realloc() と同じですが、 (n * sizeof(TYPE)) バイトにサイズ変更されたメモリを確保します。 TYPE* に型キャストされたポインタを返します。関数が終わったとき、 p は新しいメモリ領域のポインタか、失敗した場合は NULL になります。これは C プリプロセッサのマクロで、 p は常に上書きされます。エラーを処理するときにメモリを失う事を避けるには、 p の元の値を保存しておいてください。
PyMem_Free() と同じです。
上記に加えて、C API 関数を介することなく Python メモリ操作関数を直接呼び出すための以下のマクロセットが提供されています。ただし、これらのマクロは Python バージョン間でのバイナリ互換性を保てず、それゆえに拡張モジュールでは撤廃されているので注意してください。
PyMem_MALLOC() 、 PyMem_REALLOC() 、 PyMem_FREE() 。
PyMem_NEW() 、 PyMem_RESIZE() 、 PyMem_DEL() 。
最初に述べた関数セットを使って、 概要 節の例を Python ヒープに I/O バッファをメモリ確保するように書き換えたものを以下に示します:
PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;
同じコードを型対象の関数セットで書いたものを以下に示します:
PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;
上の二つの例では、バッファを常に同じ関数セットに属する関数で操作していることに注意してください。実際、あるメモリブロックに対する操作は、異なるメモリ操作機構を混用する危険を減らすために、同じメモリ API ファミリを使って行うことが必要です。以下のコードには二つのエラーがあり、そのうちの一つには異なるヒープを操作する別のメモリ操作関数を混用しているので 致命的 (Fatal) とラベルづけをしています。
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
free(buf2); /* Right -- allocated via malloc() */
free(buf1); /* Fatal -- should be PyMem_Del() */
素のメモリブロックを Python ヒープ上で操作する関数に加え、 PyObject_New() 、 PyObject_NewVar() 、および PyObject_Del() を使うと、 Python におけるオブジェクトをメモリ確保したり解放したりできます。
これらの関数については、次章の C による新しいオブジェクト型の定義や実装に関する記述の中で説明します。
Contents
これは単純な問題ではないかもしれません。あなたがすでに Windows コマンドラインからプログラムを作動させることに慣れているなら、すぐに全て分かりますが、そうでなければ少し案内が必要です。Windows 95、98、NT、 ME、2000、XP の間にも差があり、混乱のもとになっています。
このスクリーンキャストのシリーズは、あなたが Windows XP で Python を扱えるようにすることを目標としています。知識は 90 分に凝縮され、あなたが正しい Python ディストリビューションを、あなたが選んだ IDE でコーディングし、ユニットテストでデバッグをして堅実なコードを書いていけるようにします。
あなたがある種の統合開発環境を使っているのでない限り、結局は Windows コマンドを “DOS ウィンドウ” や “コマンドプロンプトウィンドウ” と様々に呼ばれるものに タイプする ことになります。通常、このようなウィンドウはスタートメニューから出すことができます。Windows 2000 では選ぶメニューは Start ‣ Programs ‣ Accessories ‣ Command Prompt です。そのようなウィンドウが開いたことは、通常このような Windows “コマンドプロンプト” が見られることからわかるでしょう:
C:\>
この文字は異なっていたり、続きがあったりするので、コンピュータの設定や、あなたが最近何をしたかに依って、このようになっていることもあるでしょう:
D:\Steve\Projects\Python>
このようなウィンドウさえ開けば、Python プログラムを動かす手順は順調に進みます。
前提として、Python スクリプトは、Python インタプリタという別のプログラムによって加工されなければなりません。インタプリタはスクリプトを読み込み、バイトコードにコンパイルし、そのバイトコードを実行してプログラムを動かします。では、インタプリタに Python を扱わせるにはどうするのでしょうか？
最初に、コマンドウィンドウが “python” という文字列をインタプリタを開始するための導入として認識していることを確かめる必要があります。コマンドウィンドウが開いたなら、コマンド python を入力してリターンキーを打ってみましょう。するとこのようなものが現れます:
Python 2.2 (#28, Dec 21 2001, 12:21:22) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
インタプリタの”対話モード”が始まりました。これで Python の文や式を対話的に入力して、待っている間に実行や評価させることができます。これが Python の最強の機能のひとつです。いくつかの式を選んで入力し、結果を見て確かめてみましょう:
>>> print("Hello")
Hello
>>> "Hello" * 3
HelloHelloHello
多くの人が対話モードを便利で高度なプログラム可能計算機として使っています。対話式 Python セッションを終わらせたいなら、Ctrl キーを押しながら Z を入力し、 “Enter” キーを打って Windows コマンドプロンプトに戻ってください。
また、スタートメニューには Start ‣ Programs ‣ Python 2.2 ‣ Python (command line) という項目があり、そこから新しいウィンドウで >>> というプロンプトが現れます。その場合は、Ctrl-Z の文字を入力するとウィンドウは消えます。Windows はウィンドウで “python” コマンドだけを実行していて、そのウィンドウはインタプリタを終了すると閉じられるのです。
python コマンドで、インタプリタプロンプト >>> ではなく次のようなメッセージ:
'python' is not recognized as an internal or external command,
operable program or batch file.
Python はデフォルトでは DOS パスに加えられていません。このスクリーンキャストでは、すべてのユーザーがコマンドラインから Python を実行できるようにして、 システムパス に適切な entry を加えられるようにします。
や:
Bad command or filename
が現れたなら、コンピュータが Python インタプリタの場所を認識しているか確かめなければなりません。そのためには、Windows がプログラムを探すディレクトリのリストである PATH という設定を変更しなければなりません。
コマンドウィンドウが始まるごとに Python がインストールされたディレクトリが PATH 加えられるように設定するといいでしょう。あなたが Python をインストールしたのが結構最近なら、コマンド:
dir C:\py*
で、どこにインストールされているかわかるでしょう。通常の場所は C:\Python23 のようになっています。そうでなければ、ディスク全体を検索することになるでしょう ... Tools ‣ Find を使うか Search ボタンを押して “python.exe” を探してください。 Python が C:\Python23 ディレクトリ (執筆時点でのデフォルト) にインストールされていたとしたら、次のコマンドを入力すれば上と同じようなインタプリタが開始されることがわかるでしょう (もちろん、終了に “CTRL-Z” と “Enter” が必要です):
c:\Python23\python
一旦ディレクトリを変更したら、コンピュータが行うスタートアップルーチンに加える必要があります。古いバージョンの Windows では、一番簡単な方法は C:\AUTOEXEC.BAT ファイルを編集することです。AUTOEXEC.BAT に以下の行を追加しましょう:
PATH C:\Python23;%PATH%
Windows NT、2000、(おそらく) XP では、このような文字列:
;C:\Python23
を “マイコンピュータ” のプロパティウィンドウの “詳細” タブにある、 PATH 環境変数の現在の設定に加えましょう。なお、十分な権限があれば、現在のユーザに設定するかシステムに設定するかを選べます。すべてのユーザーが Python をコンピュータで実行したいのであれば後者を選ぶのがいいです。
この中に自信のない操作があれば、助けを求めてください！ ここでは、新しい設定が効いたことを絶対確実にするために、システムを再起動しましょう。 Windows NT、XP、2000 では、おそらく再起動の必要はないでしょう。それ以前のバージョンでも、AUTOEXEC.BAT の代わりに C:\WINDOWS\COMMAND\CMDINIT.BAT を編集すれば再起動しなくて済みます。
これで新しいコマンドウィンドウが開き、C:\> (等) のプロンプトに python を入力すれば、Python インタプリタが対話式コマンドを受け付けることを示す >>> が現れるでしょう。
それでは、pytest.py というプログラムが C:\Steve\Projects\Python ディレクトリにあったとしましょう。このプログラムを実行するためのセッションはこのようになるでしょう:
C:\> cd \Steve\Projects\Python
C:\Steve\Projects\Python> python pytest.py
インタプリタを開始するためのコマンドにファイル名を加えたので、インタプリタは開始時にその名前の Python スクリプトを読み込み、コンパイルし、実行し、終了し、それから再び C:\> プロンプトが現れます。カレントディレクトリを変更したくないなら、このように入力しても良いです:
C:\> python \Steve\Projects\Python\pytest.py
NT、2000、XP では、インストール過程ですでにコマンド pytest.py (または、カレントディレクトリになければ C:\Steve\Projects\Python\pytest.py) が ”.py” 拡張子を認識してその名前のファイルで Python を実行するように準備してあるかもしれません。この機能を使うと便利ですが、Windows の いくつかの バージョンでは、この形式がインタプリタを明示的に使うのと正確には同じにならないというバグがありますので、ご注意ください。
憶えておくべき重要なポイントは:
Python をスタートメニューから開始する、または PATH を正しく設定して Windows が Python インタプリタを見つけられるようにします:
python
で Python インタプリタから ‘>>>’ プロンプトが与えられます。もちろん、 CTRL-Z と ENTER でインタプリタが終了します(そして、スタートメニューからそのウィンドウを開始したのなら、そのウィンドウは消えます)。
それができたら、このコマンドでプログラムを実行してください:
python {program-file}
使うべきコマンドを知れば、特定の作業ディレクトリを指定して、どのスクリプト上でも Python インタプリタを実行する Windows ショートカットを構成できます。複雑なことがしたいなら:
python --help
を見てください。
対話モード (>>> プロンプトが現れるところ) は、単一の文や式が思ったとおりに動くか確かめたり、実験的にコードを開発するときに使うと最高です。
Windows 2000 では、標準の Python インストーラはすでに .py 拡張子をあるファイル型 (Python.File) に関連付け、そのファイル型にインタプリタを実行するオープンコマンド (D:\Program Files\Python\python.exe "%1" %*) を与えます。コマンドプロンプトから ‘foo.py’ としてスクリプトを実行可能にするにはこれで十分です。スクリプトを拡張子なしで ‘foo’ とだけタイプして実行したいのなら、PATHEXT 環境変数に .py を加えてください。
Windows NT では、インストーラによって行われる上記のような段階により、スクリプトを ‘foo.py’ で実行できるようになりますが、長年のバグにより、 NT コマンドプロセッサで入力や出力のリダイレクトをすることは、この方法ではできません。これがしばしば重要になります。
Python スクリプトを WinNT で実行できるようにするおまじないは、ファイルに .cmd 拡張子をつけ、最初の行に以下の文を加えることです:
@setlocal enableextensions & python -x %~f0 %* & goto :EOF
通常 Python は Windows でとても早く起動しますが、ときどき Python が急にスタートアップに時間がかかるようになったというバグレポートがあります。更に複雑なことに、Python は同様に設定された他の Windows システムではきちんと動くのです。
この問題はそのマシンのウイルス対策ソフトウェアの設定ミスによって起こされることがあります。ウイルススキャナの中には、ファイルシステムからの全ての読み込みを監視するように設定した場合に、二桁のスタートアップオーバーヘッドを引き起すことが知られているものがあります。あなたのシステムのウイルススキャンソフトウェアの設定を確かめて、本当に同様に設定されていることを確実にしてください。
“Freeze” は Python プログラムをひとつのスタンドアロンな実行可能なファイルにまとめて送れるようにするプログラムです。これはコンパイラ ではありません。プログラムの実行が速くなるわけでも、配布が簡単になるわけでもありません、少なくとも OS や CPU が同じならば。
Windows で freeze を使用できますが、ソースツリーをダウンロードする必要があります (http://www.python.org/download/source を参照してください)。 freeze プログラムはソースツリーの Tools\freeze サブディレクトリにあります。
Microsoft VC++ コンパイラが必要で、Python をビルドすることも必要になるでしょう。要求されるプロジェクトファイルは PCbuild ディレクトリにあります。
はい、.pyd ファイルは dll と同じようなものですが、少し違いがあります。 foo.pyd という名前の DLL があったとしたら、それには関数 initfoo() が含まれていなければなりません。そうすれば Python で “import foo” を書けて、 Python は foo.pyd (や foo.py、foo.pyc) を探して、あれば、initfoo() を呼び出して初期化しようとします。Windows が DLL の存在を必要とするのと違い、 .exe ファイルを foo.lib にリンクするわけではありません。
なお、foo.pyd を検索するパスは PYTHONPATH であり、Windows が foo.dll を検索するパスと同じではありません。また、プログラムを dll にリンクしたときはプログラムの実行に dll が必要ですが、foo.pyd は実行には必要はありません。もちろん、import foo したいなら foo.pyd は 必要です。DLL では、リンクはソースコード内で __declspec(dllexport) によって宣言されます。.pyd では、リンクは使える関数のリストで定義されます。
Python インタプリタを Windows app に埋め込む方法は、次のように要約できます:
Python を .exe ファイルディレクトリに組み込 _まないでください_ 。Windows では、Python は (それ自体 DLL である) モジュールをインポートして扱う DLL でなくてはなりません (ドキュメント化されていない重大な事実の一つ目です)。組み込む代わりに、pythonNN.dll にリンクしてください。通常は C:\Windows\System にインストールされています。NN は Python のバージョンで、Python 2.3 なら “23” のようになります。
Python には、静的に、または動的にリンクできます。静的なリンクは、 pythonNN.lib に対してリンクするもので、動的なリンクは pythonNN.dll に対してリンクするものです。動的なリンクの欠点は、 pythonNN.dll がシステムに存在しないとアプリケーションが起動しないことです。(一般的な注意: pythonNN.lib は pythonNN.dll に対するいわゆる “インポートライブラリ” です。これは単にリンカに対するシンボルを定義します。)
動的なリンクは、リンクの選択を大いに単純化します。全ては実行時に行われます。コードは Windows の LoadLibraryEx() ルーチンで pythonNN.dll をロードしなければなりません。コードはまた、Windows の GetProcAddress() ルーチンで得られるポインタで、pythonNN.dll (すなわち、Python の C API)のルーチンとデータへアクセスしていなければなりません。マクロによって、このポインタを Python の C API のルーチンを呼び出す任意の C コードに通して使えます。
Borland note: まず pythonNN.lib を Coff2Omf.exe で OMF フォーマットに変換してください。
SWIG を使えば、app のデータとメソッドを Python で使えるようにする Python “拡張モジュール”を簡単に作れます。SWIG は雑用を殆どやってくれるでしょう。結果として、.exe ファイル の中に リンクする C コードができます(！)。 DLL を作 _らなくてもよく_ 、リンクも簡潔になります。
SWIG は拡張の名前に依る名前の init 関数 (C 関数) を作ります。例えば、モジュールの名前が leo なら、init 関数の名前は initleo() になります。 SWIG shadow クラスを使ったほうがよく、そうすると init 関数の名前は initleoc() になります。これは shadow クラスが使うほとんど隠れた helper クラスを初期化します。
ステップ 2 の C コードを .exe ファイルにリンクできるのは、初期化関数の呼び出しと Python へのモジュールのインポートが同等だからです！ (ドキュメント化されていない重大な事実の二つ目です)
要するに、以下のコードを使って Python インタプリタを拡張モジュール込みで初期化することができます。
#include "python.h"
...
Py_Initialize(); // Initialize Python.
initmyAppc(); // Initialize (import) the helper class.
PyRun_SimpleString("import myApp") ; // Import the shadow class.
Python の C API には、pythonNN.dll をビルドするのに使われたコンパイラ MSVC 以外のコンパイラを使うと現れる二つの問題があります。
問題 1: コンパイラによって struct FILE に対する概念が異なるため、FILE * 引数を取るいわゆる “超高水準” 関数は、多コンパイラ環境で働きません。実装の観点から、これらは超 _低_ 水準関数になっています。
問題 2: SWIG は void 関数へのラッパを生成するときに以下のコードを生成します:
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
ああ、Py_none は pythonNN.dll 内の _Py_NoneStruct という複雑なデータ構造に展開するマクロです。また、このコードは他コンパイラ環境では失敗します。このコードを次のように置き換えてください:
return Py_BuildValue("");
これで、SWIG をまだ仕事に使えない (私は SWIG の完全な初心者です) 私でも、 SWIG の %typemap コマンドを使って自動的に変更できるようになります。
Python シェルスクリプトを使って Windows app 内から Python インタプリタウィンドウを掲示するのはいい方法ではありません。そのように表示されるウィンドウは app のウィンドウシステムとは関係ありません。むしろ “ネイティブな” インタプリタウィンドウを (wxPythonWindow を使ったりして) 作るべきです。そのウィンドウを Python インタプリタにつなぐのは簡単です。 Python の i/o は読み書きをサポートする _どんな_ オブジェクトにもリダイレクトできるので、read() と write() メソッドを含む (拡張モジュールで定義された) Python オブジェクトさえあればいいのです。
Microsoft IIS server と Win95 MS Personal Web Server では、 Python を他のどんなスクリプトエンジンとも同じように設定します。
regedt32 を起動し:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
に移動し、以下の行を入力してください。(システムによって変わることがあります):
.py :REG_SZ: c:\<path to python>\python.exe -u %s %s
この一行によって、スクリプトを http://yourserver/scripts/yourscript.py のように簡単な参照で呼び出せるようになります。ここで “scripts” は (通常はデフォルトの) “executable” ディレクトリです。-u フラグはバッファリングを無効にしたバイナリモードを stdin に使うことを指定するフラグで、バイナリデータを扱うときに必要です。
さらに、この状況で使われるファイル拡張子には ”.py” を使うのを避けることを勧めます (サポートモジュールに *.py を、”メインプログラム” スクリプトに *.cgi や *.cgp を残しておきたいでしょう)。
Python を CGI 加工に使うために Internet Information Services 5 を設定するには、以下のリンクを参照してください:
http://www.e-coli.net/pyiis_server.html (for Win2k Server) http://www.e-coli.net/pyiis.html (for Win2k pro)
Apache の設定はもっと単純です。Apache の設定ファイル httpd.conf で、ファイルの終わりに以下の行を加えてください:
ScriptInterpreterSource Registry
そして、Python CGI スクリプトに拡張子 .py をつけて、それらを cgi-bin ディレクトリに置いてください。
この FAQ ではタブを使うことを勧めません。Python スタイルガイド PEP 8 では、配布される Python コードにはスペース 4 つを使うことを推奨しています。これは Emacs の python-mode のデフォルトでも同じです。
いかなるエディタでも、タブとスペースを混ぜるのは良くないです。 MSVC も全く同じ立場であり、スペースを使うようにする設定が簡単にできます。 Tools ‣ Options ‣ Tabs を選択し、ファイルタイプの “デフォルト” の “タブ幅” と “インデント幅” に 4 を設定して、 “スペースを挿入する” のラジオボタンを選択してください。
タブとスペースが混ざっていることで先頭の空白に問題が出ている可能性があるなら、 Python を -t スイッチをつけて起動するか、 Tools/Scripts/tabnanny.py を起動してディレクトリツリーをバッチモードで確認してください。
msvcrt モジュールを使ってください。これは標準の Windows 専用拡張モジュールです。これはキーボードが打たれているかを調べる関数 kbhit() と、反響することなく一文字を得る getch() を定義します。
Python 2.7 および 3.2 以前では、プロセスを終了するために、ctypes が使えます:
import ctypes
def kill(pid):
"""kill function for Win32"""
kernel32 = ctypes.windll.kernel32
handle = kernel32.OpenProcess(1, 0, pid)
return (0 != kernel32.TerminateProcess(handle, 0))
2.7 および 3.2 では、上の関数と同様な os.kill() が実装されていて、追加の機能として、CTRL+C や CTRL+BREAK をそれらのシグナルを扱うように設計されたコンソールのサブプロセスに送ることができます。
共有されたドライブの最後にいつも “\” を加えることで、解決が見えます:
>>> import os
>>> os.path.isdir( '\\\\rorschach\\public')
0
>>> os.path.isdir( '\\\\rorschach\\public\\')
1
共有店をドライブ文字と同じようなものと考えるとわかりやすいです。例:
k: is not a directory
k:\ is a directory
k:\media is a directory
k:\media\ is not a directory
“k:” を “\conkyfoo” に置き換えても同じことが言えます:
\\conky\foo is not a directory
\\conky\foo\ is a directory
\\conky\foo\media is a directory
\\conky\foo\media\ is not a directory
最新の python.exe であること、Python の GUI バージョンではなく python.exe を使っていること、それからサーバが CGI 拡張に:
"...\python.exe -u ..."
を実行するように設定してあることを確認してください。-u (unbuffered) オプションは NT や Win95 でインタプリタが標準入出力で改行を変換することを防ぎます。これがないとリクエストの post/multipart は誤った長さを持つと見なされ、バイナリ (例えば GIF) の応答がでっち上げられる(そして壊れた画像、 PDF ファイル、その他のバイナリのダウンロード失敗につながる)でしょう。
os.popen() が PythonWin の内部から動かないのは、Microsoft の C Runtime Library (CRT) のバグによるものです。CRT はプロセスに Win32 コンソールが結び付けられていると決めてかかります。
その代わりに、Win32 コンソールが結び付けられているかに依らない win32pipe モジュールの popen() を使うべきです。
例:
import win32pipe
f = win32pipe.popen('dir /c c:\\')
print(f.readlines())
f.close()
Win9x にはバグがあって、os.popen/win32pipe.popen* が働きません。嬉しいことに、この問題に対処する方法があります。Microsoft Knowledge Base のこの記事を調べてください: Q150956。この knowledge base へのリンクはここで見つかります: http://support.microsoft.com/。
コンパイラのベンダ、バージョン、(もしかすると) オプションに関しても微妙です。埋め込みシステムの FILE* 構造体が Python インタプリタの想定と異なると、うまく行きません。
Python 1.5.* DLLs (python15.dll) は全て MS VC++ 5.0 にてマルチスレッディング DLL オプション (/MD) をつけてコンパイルされています。
コンパイラやフラグを変更できないなら、Py_RunSimpleString() を使ってみてください。これで任意のファイルを起動するための技は、exec() や open() をファイル名を引数として呼ぶことです。
また、Debug と Release 版は継ぎ合わせられません。Debug マルチスレッド DLL を使いたいなら、そのモジュールは _d がファイル名に加えられ ていなくてはなりません。
たまに、_tkinter のインポートが Windows 95 や 98 で失敗し、その時に以下のようなメッセージを訴えます:
ImportError: DLL load failed: One of the library files needed
to run this application cannot be found.
このとき Tcl/Tk がインストールされていないのかもしれませんが、Tcl/Tk がインストールされていて、Wish アプリケーションが正しく動いているなら、インストーラが autoexec.bat を適切に編集していないという問題かもしれません。インストーラは PATH 環境変数に Tcl/Tk ‘bin’ サブディレクトリを含めるように変える文を追加しようとしますが、この編集が機能していないことがあります。通常、このファイルをノートパッドで開くことで、問題が何か解ります。
(David Szafranski による追加のヒント: ここで長いファイル名を使ってはいけません。例えば、C:\Program Files\Tcl\bin の代わりに C:\PROGRA~1\Tcl\bin を使ってください。)
たまに、web ブラウザで Windows マシンにドキュメントパッケージをダウンロードするとき、その保存されたファイルの拡張子が .EXE になっていることがあります。これは間違いです。本来の拡張子は .TGZ です。
単純に、ダウンロードしたファイルを名付け直して拡張子を .TGZ にしてください。そうすれば WinZip で扱えます。(手元の WinZip でできなかったら、 http://www.winzip.com から新しいのをもらいましょう)
たまに、Tkinter を Windows で使っているとき、 cw3215mt.dll や cw3215.dll が見つからないというエラーが出ます。
原因: パス (おそらく C:\Windows) にある Tcl/Tk DLL が cygwin でビルドされた古いものです。標準の Tcl/Tk インストール (Python 1.5.2 に付属しています) による Tcl/Tk を使わなければなりません。
Python インストーラはこのような警告をします:
This version uses CTL3D32.DLL which is not the correct version.
This version is used for windows NT applications only.
Tim Peters いわく:
これは DLL の、そして悪名高きソースの問題です。このメッセージが伝えるものはこうです: この DLL のバージョンがオペレーティングシステムに合いません。 Python のインストールが原因ではありません - それ以前にインストールした何かが OS に付属していた DLL を上書きしたのです (おそらく何かの古いソフトでしょうが、もうそれは判断できません)。検索エンジン (例えば Altavista) で “CTL3D32” を探せば、あらゆる種類のインストールプログラムでの同様の問題を訴えるウェブページが何百も何百も現れるでしょう。それらのページにシステムにあった正しいバージョンをダウンロードする方法が指摘されていることでしょう (Python によって起こされたものではないので、我々には直しようがないのです)。
David A Burton はこれを直すための小さなプログラムを書きました。 http://www.burtonsys.com/downloads.html に行って “ctl3dfix.zip” をクリックしてください。