| Author: | Greg Ward — 日本語訳: Python ドキュメント翻訳プロジェクト |
|---|---|
| Release: | 2.6 |
| Date: | 2011年 11月 04日 |
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 | C:\Python | (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) |
注記:
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 設定ファイル 節を参照してください)。
参考
この手引きは2.4.1 以降のPython と 3.0.0 (binutils-2.13.90-20030111-1) 以上の MinGW でのみ有効です。
この節では、 Cygwin や MinGW [2] 配布物中の GNU C/C++ コンパイラで Distutils を使うために必要な手順について述べます。 Cygwin 向けにビルドされている Python インタプリタを使っているなら、以下の手順をとらなくても Distutils はまったく問題なく動作します。
上記のコンパイラは、いくつかの特殊なライブラリを必要とします。この作業は 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, ... ) を必要とする場合、それらのライブラリも変換しなければなりません。変換されたファイルは、それぞれ通常のライブラリが置かれているのと同じディレクトリに置かねばなりません。
Cygwin を使って Distutils に拡張モジュールをコンパイルさせるには、
python setup.py build --compiler=cygwin
のように入力します。また、非 cygwin モードの Cygwin [3] や MinGW では、
python setup.py build --compiler=mingw32
のように入力します。
上記のオプションやコンパイラをデフォルトにしたいなら、自分用、またはシステム全体向けに、 Distutils の設定ファイルを書くことを検討した方がよいでしょう ( Distutils 設定ファイル 節を参照してください)。
参考
脚注
| [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/list
までご報告ください。
この章の関数は、 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") と全く同じ。 |
| %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 が付きます。 |
識別できない書式指定文字があった場合、残りの書式文字列はそのまま出力文字列にコピーされ、残りの引数は無視されます。
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, fortran が 'F' なら Fortran-style の) 多次元配列として埋める。
バッファインタフェースに関するより詳しい情報は、 “バッファオブジェクト構造体” 節 ( バッファオブジェクト構造体 (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 オブジェクトです; モジュール関数の場合、 Py_InitModule4() に与えることになる値が入ります (NULL にすると Py_InitModule() が使われます)。第二のパラメタ (よく 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 参照) に追加されます。
サブタイプはこのフィールドを継承しません (算出属性は別個のメカニズムで継承されています)。
Docs for PyGetSetDef (XXX belong elsewhere):
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);
XXX blah, blah.
サブタイプはこのフィールドを継承します。
オプションのフィールドです。ポインタで、 “デスクリプタ set” 関数を指します。
関数のシグネチャは次のとおりです。
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
サブタイプはこのフィールドを継承します。
XXX blah, blah.
型のインスタンスにインスタンス変数の入った辞書がある場合、このフィールドは非ゼロの値になり、型のインスタンスデータ構造体におけるインスタンス変数辞書へのオフセットが入ります; このオフセット値は 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 は文字列であるべきであり、 printf() に似た書式化コードを含んでいます。書式化コードの前の 幅.精度(width.precision) は解析されますが、幅の部分は無視されます。
| 書式文字 | 型 | コメント |
|---|---|---|
| %% | n/a | リテラルの % 文字。 |
| %c | int | 一文字. Cのintで表現される。 |
| %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* | NULL終端の C の文字配列。 |
| %p | void* | C ポインタの16進表現。プラットフォームのprintfによらず、必ずリテラル 0x が頭につくことが保証されるという以外、 printf("%p") とほぼ同じ。 |
認識できない書式化文字があると書式化文字列の残りすべてがそのまま結果の文字列へコピーされ、余分の引数はどれも捨てられます。
これは 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 は有効なファイルディスクリプタであるべきです。この関数の呼び出しはメインスレッドのみから行われるべきです。
このユーティリティ関数は新しい例外オブジェクトを作成して返します。 name 引数は新しい例外の名前、 module.class 形式の C文字列でなければならない。 base と dict 引数は通常 NULL です。これはすべての例外のためのルート、組み込み名 Exception (Cでは PyExc_Exception としてアクセス可能)をルートとして派生したクラスオブジェクトを作成します。
新しいクラスの __module__ 属性は name 引数の前半部分(最後のドットまで)に設定され、クラス名は後半部分(最後のドットの後)に設定されます。 base 引数は代わりのベースクラスを指定するために使えます; 一つのクラスでも、クラスのタプルでも構いません。 dict 引数はクラス変数とメソッドの辞書を指定するために使えます。
例外が設定されているがインタプリタが実際に例外を発生させることができないときに、このユーティリティ関数は警告メッセージを sys.stderr へプリントします。例えば、例外が __del__() メソッドで発生したときに使われます。
発生させられない例外が生じたコンテキストを特定するための一つの引数 obj とともに関数が呼び出されます。 obj のreprが警告メッセージにプリントされるでしょう。
これら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 で追加.
Pythonへ組み込まれるすべての例外あるいは標準ライブラリに提供されている例外は、 BaseException から導出されています。
インタプリタで既存のコードが変更なしで動作するように、文字列例外は今でもサポートされています。しかし、これも将来のリリースで変更されるでしょう。
この 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>' または '???' のいずれかに等しい場合にも真を返します。
ファイル filename の最終更新時刻を返します。結果は標準 C ライブラリ関数 time() が返すタイムスタンプと同じ様式で符号化されています。
プロセスが 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>, <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_SetArgv(argc, argv) を呼び出して明示的に設定しなければなりません。
ほとんどのシステムでは (特に 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 であってはなりません。
このオブジェクトの使用法に関する情報は、 Python インタプリタの拡張と埋め込み 1.12 節、 “Providing a C API for an Extension Module,” を参照してください。
この 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 を返します。
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 バッファをエンコードした 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 型バッファを 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 システムを正しくサポートするには修正が必要になります。
以下は mapping codec の APIです:
この 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 を実現するマップ型に入れる必要がある対応付け関係は、ある文字を別のコード点に対応付けるものだけです。
エンコードされた 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 への対応付けを行う特殊なものです。
指定された長さを持つ 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 非依存な文字列から数値への変換を行ないます。
文字列を double へ変換します。この関数は、C locale におけるC標準の strtod() と同じように動作します。スレッドセーフのために、この関数は現在の locale を変更せずに実装されています。
PyOS_ascii_strtod() は通常、設定ファイルを読み込むときや、ロケール独立な非ユーザーからの入力を読み込むときに使われるべきです。
バージョン 2.4 で追加.
詳細は Unix man page の strtod(2) を参照してください。
double を '.' を小数点記号に利用して文字列に変換します。 format は数値のフォーマットを指定する printf() スタイルの文字列です。利用できる変換文字は 'e', 'E', 'f', 'F', 'g', 'G' です。
戻り値は、変換された文字列が格納された buffer へのポインタか、失敗した場合は NULL です。
バージョン 2.4 で追加.
文字列を、 locale 非依存な方法で double へ変換します。
バージョン 2.4 で追加.
詳細は Unix man page の atof(2) を参照してください。
大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 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 で追加.
バージョン 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 度以上呼び出すと起こり得ます。
新しいサブインタプリタ (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 関数のように、この関数を呼び出す前にはグローバルインタプリタロック (global interpreter lock) が保持されていなければならず、関数が処理を戻した際にも保持されたままになります; しかし、他の Python/C API 関数とは違い、関数から戻ったときの現在のスレッド状態が関数に入るときと同じとは限らないので注意してください)。
拡張モジュールは以下のような形で (サブ) インタプリタ間で共有されます: ある特定の拡張モジュールを最初に import すると、モジュールを通常通りに初期化し、そのモジュールの辞書の (浅い) コピーをしまい込んでおきます。他の (サブ) インタプリタが同じ拡張モジュールを import すると、新たなモジュールを初期化し、先ほどのコピーの内容で辞書の値を埋めます; 拡張モジュールの init 関数は呼び出されません。この挙動は、 Py_Finalize() および Py_Initialize() を呼び出してインタプリタを完全に再初期化した後に拡張モジュールを import した際の挙動とは異なるので注意してください; 再初期化後に import を行うと、拡張モジュールの initmodule は再度 呼び出され ます。
バグと注意事項: サブインタプリタ (とメインインタプリタ) は同じプロセスの一部分なので、インタプリタどうしの隔離は完璧ではありません — 例えば、 os.close() のような低レベルのファイル操作を使うと、 (偶然なり故意なりに) 互いのインタプリタ下にある開かれたファイルに影響を及ぼせてしまいます。拡張モジュールを (サブ) インタプリタ間で共有する方法のせいで、拡張モジュールによっては正しく動作しないかもしれません; 拡張モジュールが (静的な) グローバル変数を利用している場合や、拡張モジュールが初期化後に自身のモジュール辞書を操作する場合には特にそうです。一つのサブインタプリタで生成されたオブジェクトは他のサブインタプリタの名前空間への挿入が可能です; ユーザ定義関数、メソッド、インスタンスおよびクラスをサブインタプリタをサブインタプリタ間で共有しないように十分注意してください。というのは、これらの共有オブジェクトが実行した import 文は間違った (サブ) インタプリタのロード済みモジュール辞書に影響を及ぼす場合があるからです (XXX この問題は修正が難しいバグで、将来のリリースで解決される予定です)
この機能は PyObjC や ctypes のような、 PyGILState_*() API を利用するタイプの拡張モジュールと相性が悪いことにも注意してください。 (これは、 PyGILState_*() 関数の動作特有の問題です) 単純なことなら上手くいくかもしれませんが、いつ混乱させる動作をするかわかりません。
指定されたスレッド状態 tstate で表現される (サブ) インタプリタを抹消します。 tstate は現在のスレッド状態でなければなりません。下記のスレッド状態に関する議論を参照してください。関数呼び出しが戻ったとき、現在のスレッド状態は NULL になっています。このインタプリタに関連付けられた全てのスレッド状態は抹消されます。 (この関数を呼び出す前にはグローバルインタプリタロックを保持しておかねばならず、ロックは関数が戻ったときも保持されています。) Py_Finalize() は、その時点で明示的に抹消されていない全てのサブインタプリタを抹消します。
この関数を呼び出すなら、最初に 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 として利用できます。 Unixのみで有用です。
デフォルトモジュール検索パスを返します; パスは (上の 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_SetArgv() の updatepath に 1 を設定したのと同じように動作します。
Python の標準ライブラリがある、デフォルトの “home” ディレクトリを設定します。ライブラリは home/lib/pythonversion と home/lib/pythonversion から検索されます。引数は静的なストレージに置かれてプログラム実行中に書き換えられないようなゼロ終端の文字列であるべきです。 Python インタプリタはこのストレージの内容を変更しません。
前回の Py_SetPythonHome() 呼び出しで設定されたデフォルトの “home” か、 PYTHONHOME 環境変数が設定されていればその値を返します。
Python インタプリタは完全にスレッド安全 (thread safe) ではありません。マルチスレッドの Python プログラムをサポートするために、 global interpreter lock や GIL と呼ばれるグローバルなロックが存在していて、現在のスレッドが Python オブジェクトに安全にアクセスする前に必ずロックを獲得しなければならなくなっています。ロック機構がなければ、単純な操作でさえ、マルチスレッドプログラムの実行に問題を引き起こす可能性があります: たとえば、二つのスレッドが同じオブジェクトの参照カウントを同時にインクリメントすると、結果的に参照カウントは二回でなく一回だけしかインクリメントされないかもしれません。
このため、グローバルインタプリタロックを獲得したスレッドだけが Python オブジェクトを操作したり、 Python/C API 関数を呼び出したりできるというルールがあります。マルチスレッドの Python プログラムをサポートするため、インタプリタは定期的に — デフォルトの設定ではバイトコード 100 命令ごとに (この値は sys.setcheckinterval() で変更できます) — ロックを解放したり獲得したりします。このロックはブロックが起こりうる I/O 操作の付近でも解放・獲得され、I/O を要求するスレッドが I/O 操作の完了を待つ間、他のスレッドが動作できるようにしています。
Python インタプリタはスレッドごとに何らかの予約情報を持っておかねばなりません — このため、Python は PyThreadState と呼ばれるデータ構造を用います。とはいえ、グローバル変数はまだ一つだけ残っています: それは現在の PyThreadState 構造体を指すポインタです。スレッドローカルストレージ (thread-local-storage, TLS) が追加される前は、現在のスレッドの状態を明示的に操作しなければなりませんでした。
ほとんどのケースで、このような操作は十分簡単にできます。グローバルインタプリタロックを操作するほとんどのコードは、以下のような単純な構造を持ちます:
スレッド状態をローカル変数に保存する。
グローバルインタプリタロックを解放する。
...ブロックが起きるような何らかの I/O 操作...
グローバルインタプリタロックを獲得する。
ローカル変数からスレッド状態を回復する。
このやりかたは非常に一般的なので、作業を単純にするために二つのマクロが用意されています:
Py_BEGIN_ALLOW_THREADS
...ブロックが起きるような何らかの I/O 操作...
Py_END_ALLOW_THREADS
Py_BEGIN_ALLOW_THREADS マクロは新たなブロック文を開始し、隠しローカル変数を宣言します; Py_END_ALLOW_THREADS はブロック文を終了します。これらの二つのマクロを使うもうひとつの利点は、 Python をスレッドサポートなしでコンパイルしたとき、マクロの内容、すなわちスレッド状態の退避とGIL操作が空になるという点です。
スレッドサポートが有効になっている場合、上記のブロックは以下のようなコードに展開されます:
PyThreadState *_save;
_save = PyEval_SaveThread();
...ブロックが起きるような何らかの I/O 操作...
PyEval_RestoreThread(_save);
より低水準のプリミティブを使うと、以下のようにしてほぼ同じ効果を得られます:
PyThreadState *_save;
_save = PyThreadState_Swap(NULL);
PyEval_ReleaseLock();
...ブロックが起きるような何らかの I/O 操作...
PyEval_AcquireLock();
PyThreadState_Swap(_save);
上の二つには微妙な違いがあります; とりわけ、 PyEval_RestoreThread() はグローバル変数 errno の値を保存しておいて元に戻す点が異なります。というのは、ロック操作が errno に何もしないという保証がないからです。また、スレッドサポートが無効化されている場合、 PyEval_SaveThread() および PyEval_RestoreThread() はGILを操作しません; この場合、 PyEval_ReleaseLock() および PyEval_AcquireLock() は利用できません。この仕様は、スレッドサポートを無効化してコンパイルされているインタプリタが、スレッドサポートが有効化された状態でコンパイルされている動的ロード拡張モジュールをロードできるようにするためのものです。
グローバルインタプリタロックは、現在のスレッド状態を指すポインタを保護するために使われます。ロックを解放してスレッド状態を退避する際、ロックを解放する前に現在のスレッド状態ポインタを取得しておかなければなりません (他のスレッドがすぐさまロックを獲得して、自らのスレッド状態をグローバル変数に保存してしまうかもしれないからです)。逆に、ロックを獲得してスレッド状態を復帰する際には、グローバル変数にスレッド状態ポインタを保存する前にロックを獲得しておかなければなりません。
C でスレッドを生成した場合、そのスレッドにはグローバルインタプリタロックがなく、スレッド状態データ構造体もないことに注意する必要があります。このようなスレッドが Python/C API を利用するには、まずスレッド状態データ構造体を生成し、次にロックを獲得し、そしてスレッド状態ポインタを保存するといったように、自分自身をブートストラップして生成しなければなりません。スレッドが作業を終えたら、スレッド状態ポインタをリセットして、ロックを解放し、最後にスレッド状態データ構造体をメモリ解放しなければなりません。
スレッドデータ構造体を生成する際には、インタプリタ状態データ構造体を指定する必要があります。インタプリタ状態データ構造体は、インタプリタ内の全てのスレッド間で共有されているグローバルなデータ、例えばモジュール管理データ (codesys.modules) を保持しています。必要に応じて、新たなインタプリタ状態データ構造体を作成するなり、 Python メインスレッドが使っているインタプリタ状態データ構造体を共有するなりできます (後者のデータにアクセスするためには、スレッド状態データ構造体を獲得して、その interp メンバにアクセスしなければなりません; この処理は、Python が作成したスレッドから行うか、Python を初期化した後で主スレッドから行わねばなりません)。
インタプリタオブジェクトにアクセスできるという仮定の下では、C のスレッドから Python を呼び出す際の典型的な常套句は以下のようになります。
バージョン 2.3 からは、上記の事を全て自動で行われて、スレッドは PyGILState_*() の恩恵に預かることができます。 C のスレッドから Python を呼び出す典型的な方法は以下のとおりです。
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();
/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result */
/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
PyGILState_*() 関数は、(Py_Initialize() によって自動的に作られる) グローバルインタプリタ一つだけが存在すると仮定する事に気をつけて下さい。 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() は必要なロックのリセットを試みますが、いつでもそれが可能とは限りません。
このデータ構造体は、協調動作する多数のスレッド間で共有されている状態 (state) を表現します。同じインタプリタに属するスレッドはモジュール管理情報やその他いくつかの内部的な情報を共有しています。この構造体には公開 (public) のメンバはありません。
異なるインタプリタに属するスレッド間では、利用可能なメモリ、開かれているファイルデスクリプタなどといったプロセス状態を除き、初期状態では何も共有されていません。グローバルインタプリタロックもまた、スレッドがどのインタプリタに属しているかに関わらずすべてのスレッドで共有されています。
単一のスレッドの状態を表現する表現するデータ構造体です。データメンバ PyInterpreterState * interp だけが公開されていて、スレッドのインタプリタ状態を指すポインタになっています。
グローバルインタプリタロックを初期化し、獲得します。この関数は、主スレッドが第二のスレッドを生成する以前や、 PyEval_ReleaseLock() や PyEval_ReleaseThread(tstate) といった他のスレッド操作に入るよりも前に呼び出されるようにしておかなければなりません。
二度目に呼び出すと何も行いません。この関数を Py_Initialize() の前に呼び出しても安全です。
主スレッドしか存在しないのであれば、GIL操作は必要ありません。これはよくある状況ですし (ほとんどの Python プログラムはスレッドを使いません)、ロック操作はインタプリタをごくわずかに低速化します。従って、初期状態ではロックは生成されません。ロックを使わない状況は、すでにロックを獲得している状況と同じです: 単一のスレッドしかなければ、オブジェクトへのアクセスは全て安全です。従って、この関数がGILを初期化すると、同時にロックを獲得するようになっています。Python の thread モジュールは、新たなスレッドを作成する前に、ロックが存在するか、あるいはまだ作成されていないかを調べ、 PyEval_InitThreads() を呼び出します。この関数から処理が戻った場合、ロックが作成作成され、呼び出し元スレッドがそのロックを獲得している事が保証されています。
どのスレッドが現在グローバルインタプリタロックを (存在する場合) 持っているか分からない時にこの関数を使うのは安全では ありません 。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
PyEval_InitThreads() をすでに呼び出している場合は真 (非ゼロ) を返します。この関数は、GILを獲得せずに呼び出すことができますので、シングルスレッドで実行している場合にはロック関連のAPI呼び出しを避けるために使うことができます。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
バージョン 2.4 で追加.
グローバルインタプリタロックを獲得します。ロックは前もって作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
グローバルインタプリタロックを解放します。ロックは前もって作成されていなければなりません。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
グローバルインタプリタロックを獲得し、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。ロックはあらかじめ作成されていなければなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
現在のスレッド状態をリセットして NULL にし、グローバルインタプリタロックを解放します。ロックはあらかじめ作成されていなければならず、かつ現在のスレッドが保持していなければなりません。 tstate は NULL であってはなりませんが、その値が現在のスレッド状態を表現しているかどうかを調べるためにだけ使われます — もしそうでなければ、致命的エラーが報告されます。この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
(インタプリタロックが生成されていて、スレッドサポートが有効の場合) グローバルインタプリタロックを解放して、スレッド状態を NULL にし、以前のスレッド状態 (NULL にはなりません) を返します。ロックがすでに生成されている場合、現在のスレッドがロックを獲得していなければなりません。
(インタプリタロックが生成されていて、スレッドサポートが有効の場合) グローバルインタプリタロックを獲得して、現在のスレッド状態を tstate に設定します。 tstate は NULL であってはなりません。この関数を呼び出したスレッドがすでにロックを獲得している場合、デッドロックに陥ります。 (この関数はコンパイル時にスレッドサポートを無効化すると利用できません。)
以下のマクロは、通常末尾にセミコロンを付けずに使います; 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 と同じです。コンパイル時にスレッドサポートが無効化されていると何も行いません。
以下の全ての関数はコンパイル時にスレッドサポートが有効になっている時だけ利用でき、呼び出すのはグローバルインタプリタロックがすでに作成されている場合だけにしなくてはなりません。
新しいインタプリタ状態オブジェクトを生成します。グローバルインタプリタロックを保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。
インタプリタ状態オブジェクト内の全ての情報をリセットします。グローバルインタプリタロックを保持していなければなりません。
インタプリタ状態オブジェクトを破壊します。グローバルインタプリタロックを保持しておく必要はありません。インタプリタ状態は PyInterpreterState_Clear() であらかじめリセットしておかなければなりません。
指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを生成します。グローバルインタプリタロックを保持しておく必要はありませんが、この関数を次々に呼び出す必要がある場合には保持しておいたほうがよいでしょう。
スレッド状態オブジェクト内の全ての情報をリセットします。グローバルインタプリタロックを保持していなければなりません。
スレッド状態オブジェクトを破壊します。グローバルインタプリタロックを保持していなければなりません。スレッド状態は PyThreadState_Clear() であらかじめリセットしておかなければなりません。
現在のスレッド状態を返します。グローバルインタプリタロックを保持していなければなりません。現在のスレッド状態が NULL なら、(呼び出し側が NULL チェックをしなくてすむように) この関数は致命的エラーを起こすようになっています。
現在のスレッド状態を tstate に指定したスレッド状態と入れ変えます。 tstate は NULL であってはなりません。グローバルインタプリタロックを保持していなければなりません。
拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを使わねばなりません。現在のスレッド状態がない時にこの関数を呼び出してもかまいません。この関数が NULL を返す場合、例外はまったく送出されず、呼び出し側は現在のスレッド状態が利用できないと考えねばなりません。
バージョン 2.3 で変更: 以前は、現在のスレッドがアクティブなときのみ呼び出せるようになっており、 NULL は例外が送出されたことを意味していました.
スレッド内で非同期的に例外を送出します。 id 引数はターゲットとなるスレッドのスレッド id です; exc は送出する例外オブジェクトです。この関数は exc に対する参照を一切盗み取りません。素朴な間違いを防ぐため、この関数を呼び出すには独自に C 拡張モジュールを書かねばなりません。グローバルインタプリタロックを保持した状態で呼び出さなければなりません。
変更を受けたスレッド状態の数を返します; これは普通は1ですが、スレッドidが見つからなかった場合は0になります。もし exc が NULL であれば、そのスレッドで保留されている例外があればクリアします。この関数自体は例外を送出しません。
バージョン 2.3 で追加.
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を所有しています。処理の失敗は致命的なエラーです。
バージョン 2.3 で追加.
獲得したすべてのリソースを開放します。この関数を呼び出すと、Pythonの状態は対応する PyGILState_Ensure() を呼び出す前と同じとなります。(通常、この状態は呼び出し元でははわかりませんので、GILState APIを利用するようにしてください。）
PyGILState_Ensure() を呼び出す場合は、必ず同一スレッド内で対応する PyGILState_Release() を呼び出してください。
バージョン 2.3 で追加.
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 | 呼び出し側に返される予定の値です。 |
| PyTrace_C_CALL | 呼び出している関数の名前です。 |
| PyTrace_C_EXCEPTION | 常に NULL です。 |
| PyTrace_C_RETURN | 常に NULL です。 |
関数やメソッドが新たに呼び出されたり、ジェネレータが新たなエントリの処理に入ったことを報告する際の、 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 で追加.
| Release: | 2.6 |
|---|---|
| Date: | 2011年 11月 04日 |
このマニュアルでは、拡張モジュールを書いたり 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 で追加.
この文書は、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/list
までご報告ください。
オブジェクト 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 の値を比較します。このとき 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 を返します。
現在のフレームがありそれが制限モードで実行していた場合、真を返します。それ以外の場合は僞を返します。
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() 関数へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値は sys.exit() 関数へ渡される整数でしょう。例外が原因でインタプリタが終了した場合は 1 、あるいは、引数リストが有効なPythonコマンドラインになっていない場合は 2 です。
Py_InspectFlag が設定されていない場合、未処理の SystemError 例外が発生すると、この関数は 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 が設定されていない場合、未処理の SystemError 例外が発生すると、この関数は 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 に従って実行します。 filename が NULL ならば、 "???" が代わりに使われます。 sys.ps1 と sys.ps2 を使って、ユーザにプロンプトを提示します。入力が正常に実行されたときは 0 を返します。例外が発生した場合は -1 を返します。パースエラーの場合はPythonの一部として配布されている errcode.h インクルードファイルにあるエラーコードを返します。 (Python.h は errcode.h をインクルードしません。したがって、必要ならば特別にインクルードしなければならないことに注意してください。)
下記の PyRun_InteractiveLoopFlags() の flags を 0 にして単純化したインタフェースです。
対話的デバイスに関連付けられたファイルからEOF に達するまで複数の文を読み込み実行します。 filename が NULL ならば、 "???" が代わりに使われます。 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を開放する前にこの関数を呼び出します。
バージョン 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 で追加.
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 の指す長整数値を、 C の Py_ssize_t 型表現で返します。 pylong が PY_SSIZE_T_MAX よりも大きい場合、 OverflowError を送出し、 -1 を返します。
バージョン 2.6 で追加.
pylong の指す長整数値を、 C の unsigned long 型表現で返します。 pylong が ULONG_MAX よりも大きい場合、 OverflowError を送出します。
pylong の指す長整数値を、 C の long long 型表現で返します。 pylong が long long で表せない場合、 OverflowError を送出します。
バージョン 2.2 で追加.
pylong の指す値を、 C の unsigned long long 型表現で返します。 pylong が unsigned long long で表せない場合、正の値なら OverflowError を、負の値なら TypeError を送出します。
バージョン 2.2 で追加.
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 で追加.
このセクションは Python 1.6 で導入された古いバッファプロトコルについて解説します。このプロトコルは、 Python 2.x 系ではサポートされていますが廃止予定扱いです。 Python 3.0 から、このプロトコルの弱点や欠点を克服した新しいバッファプロトコルが導入され、 Python 2.6 へと逆移植されました。詳細は バッファーオブジェクト を参照してください。
文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを返します。 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
This is not necessarily a straightforward question. If you are already familiar with running programs from the Windows command line then everything will seem obvious; otherwise, you might need a little more guidance. There are also differences between Windows 95, 98, NT, ME, 2000 and XP which can add to the confusion.
This series of screencasts aims to get you up and running with Python on Windows XP. The knowledge is distilled into 1.5 hours and will get you up and running with the right Python distribution, coding in your choice of IDE, and debugging and writing solid code with unit-tests.
Unless you use some sort of integrated development environment, you will end up typing Windows commands into what is variously referred to as a “DOS window” or “Command prompt window”. Usually you can create such a window from your Start menu; under Windows 2000 the menu selection is Start ‣ Programs ‣ Accessories ‣ Command Prompt. You should be able to recognize when you have started such a window because you will see a Windows “command prompt”, which usually looks like this:
C:\>
The letter may be different, and there might be other things after it, so you might just as easily see something like:
D:\Steve\Projects\Python>
depending on how your computer has been set up and what else you have recently done with it. Once you have started such a window, you are well on the way to running Python programs.
You need to realize that your Python scripts have to be processed by another program called the Python interpreter. The interpreter reads your script, compiles it into bytecodes, and then executes the bytecodes to run your program. So, how do you arrange for the interpreter to handle your Python?
First, you need to make sure that your command window recognises the word “python” as an instruction to start the interpreter. If you have opened a command window, you should try entering the command python and hitting return. You should then see something like:
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.
>>>
You have started the interpreter in “interactive mode”. That means you can enter Python statements or expressions interactively and have them executed or evaluated while you wait. This is one of Python’s strongest features. Check it by entering a few expressions of your choice and seeing the results:
>>> print "Hello"
Hello
>>> "Hello" * 3
HelloHelloHello
Many people use the interactive mode as a convenient yet highly programmable calculator. When you want to end your interactive Python session, hold the Ctrl key down while you enter a Z, then hit the “Enter” key to get back to your Windows command prompt.
You may also find that you have a Start-menu entry such as Start ‣ Programs ‣ Python 2.2 ‣ Python (command line) that results in you seeing the >>> prompt in a new window. If so, the window will disappear after you enter the Ctrl-Z character; Windows is running a single “python” command in the window, and closes it when you terminate the interpreter.
If the python command, instead of displaying the interpreter prompt >>>, gives you a message like:
'python' is not recognized as an internal or external command,
operable program or batch file.
Python is not added to the DOS path by default. This screencast will walk you through the steps to add the correct entry to the System Path, allowing Python to be executed from the command-line by all users.
or:
Bad command or filename
then you need to make sure that your computer knows where to find the Python interpreter. To do this you will have to modify a setting called PATH, which is a list of directories where Windows will look for programs.
You should arrange for Python’s installation directory to be added to the PATH of every command window as it starts. If you installed Python fairly recently then the command
dir C:\py*
will probably tell you where it is installed; the usual location is something like C:\Python23. Otherwise you will be reduced to a search of your whole disk ... use Tools ‣ Find or hit the Search button and look for “python.exe”. Supposing you discover that Python is installed in the C:\Python23 directory (the default at the time of writing), you should make sure that entering the command
c:\Python23\python
starts up the interpreter as above (and don’t forget you’ll need a “CTRL-Z” and an “Enter” to get out of it). Once you have verified the directory, you need to add it to the start-up routines your computer goes through. For older versions of Windows the easiest way to do this is to edit the C:\AUTOEXEC.BAT file. You would want to add a line like the following to AUTOEXEC.BAT:
PATH C:\Python23;%PATH%
For Windows NT, 2000 and (I assume) XP, you will need to add a string such as
;C:\Python23
to the current setting for the PATH environment variable, which you will find in the properties window of “My Computer” under the “Advanced” tab. Note that if you have sufficient privilege you might get a choice of installing the settings either for the Current User or for System. The latter is preferred if you want everybody to be able to run Python on the machine.
If you aren’t confident doing any of these manipulations yourself, ask for help! At this stage you may want to reboot your system to make absolutely sure the new setting has taken effect. You probably won’t need to reboot for Windows NT, XP or 2000. You can also avoid it in earlier versions by editing the file C:\WINDOWS\COMMAND\CMDINIT.BAT instead of AUTOEXEC.BAT.
You should now be able to start a new command window, enter python at the C:\> (or whatever) prompt, and see the >>> prompt that indicates the Python interpreter is reading interactive commands.
Let’s suppose you have a program called pytest.py in directory C:\Steve\Projects\Python. A session to run that program might look like this:
C:\> cd \Steve\Projects\Python
C:\Steve\Projects\Python> python pytest.py
Because you added a file name to the command to start the interpreter, when it starts up it reads the Python script in the named file, compiles it, executes it, and terminates, so you see another C:\> prompt. You might also have entered
C:\> python \Steve\Projects\Python\pytest.py
if you hadn’t wanted to change your current directory.
Under NT, 2000 and XP you may well find that the installation process has also arranged that the command pytest.py (or, if the file isn’t in the current directory, C:\Steve\Projects\Python\pytest.py) will automatically recognize the ”.py” extension and run the Python interpreter on the named file. Using this feature is fine, but some versions of Windows have bugs which mean that this form isn’t exactly equivalent to using the interpreter explicitly, so be careful.
The important things to remember are:
Start Python from the Start Menu, or make sure the PATH is set correctly so Windows can find the Python interpreter.
python
should give you a ‘>>>’ prompt from the Python interpreter. Don’t forget the CTRL-Z and ENTER to terminate the interpreter (and, if you started the window from the Start Menu, make the window disappear).
Once this works, you run programs with commands:
python {program-file}
When you know the commands to use you can build Windows shortcuts to run the Python interpreter on any of your scripts, naming particular working directories, and adding them to your menus. Take a look at
python --help
if your needs are complex.
Interactive mode (where you see the >>> prompt) is best used for checking that individual statements and expressions do what you think they will, and for developing code by experiment.
On Windows 2000, the standard Python installer already associates the .py extension with a file type (Python.File) and gives that file type an open command that runs the interpreter (D:\Program Files\Python\python.exe "%1" %*). This is enough to make scripts executable from the command prompt as ‘foo.py’. If you’d rather be able to execute the script by simple typing ‘foo’ with no extension you need to add .py to the PATHEXT environment variable.
On Windows NT, the steps taken by the installer as described above allow you to run a script with ‘foo.py’, but a longtime bug in the NT command processor prevents you from redirecting the input or output of any script executed in this way. This is often important.
The incantation for making a Python script executable under WinNT is to give the file an extension of .cmd and add the following as the first line:
@setlocal enableextensions & python -x %~f0 %* & goto :EOF
Usually Python starts very quickly on Windows, but occasionally there are bug reports that Python suddenly begins to take a long time to start up. This is made even more puzzling because Python will work fine on other Windows systems which appear to be configured identically.
The problem may be caused by a misconfiguration of virus checking software on the problem machine. Some virus scanners have been known to introduce startup overhead of two orders of magnitude when the scanner is configured to monitor all reads from the filesystem. Try checking the configuration of virus scanning software on your systems to ensure that they are indeed configured identically. McAfee, when configured to scan all file system read activity, is a particular offender.
“Freeze” is a program that allows you to ship a Python program as a single stand-alone executable file. It is not a compiler; your programs don’t run any faster, but they are more easily distributable, at least to platforms with the same OS and CPU. Read the README file of the freeze program for more disclaimers.
You can use freeze on Windows, but you must download the source tree (see http://www.python.org/download/source). The freeze program is in the Tools\freeze subdirectory of the source tree.
You need the Microsoft VC++ compiler, and you probably need to build Python. The required project files are in the PCbuild directory.
Yes, .pyd files are dll’s, but there are a few differences. If you have a DLL named foo.pyd, then it must have a function initfoo(). You can then write Python “import foo”, and Python will search for foo.pyd (as well as foo.py, foo.pyc) and if it finds it, will attempt to call initfoo() to initialize it. You do not link your .exe with foo.lib, as that would cause Windows to require the DLL to be present.
Note that the search path for foo.pyd is PYTHONPATH, not the same as the path that Windows uses to search for foo.dll. Also, foo.pyd need not be present to run your program, whereas if you linked your program with a dll, the dll is required. Of course, foo.pyd is required if you want to say import foo. In a DLL, linkage is declared in the source code with __declspec(dllexport). In a .pyd, linkage is defined in a list of available functions.
Embedding the Python interpreter in a Windows app can be summarized as follows:
Do _not_ build Python into your .exe file directly. On Windows, Python must be a DLL to handle importing modules that are themselves DLL’s. (This is the first key undocumented fact.) Instead, link to pythonNN.dll; it is typically installed in C:\Windows\System. NN is the Python version, a number such as “23” for Python 2.3.
You can link to Python statically or dynamically. Linking statically means linking against pythonNN.lib, while dynamically linking means linking against pythonNN.dll. The drawback to dynamic linking is that your app won’t run if pythonNN.dll does not exist on your system. (General note: pythonNN.lib is the so-called “import lib” corresponding to python.dll. It merely defines symbols for the linker.)
Linking dynamically greatly simplifies link options; everything happens at run time. Your code must load pythonNN.dll using the Windows LoadLibraryEx() routine. The code must also use access routines and data in pythonNN.dll (that is, Python’s C API’s) using pointers obtained by the Windows GetProcAddress() routine. Macros can make using these pointers transparent to any C code that calls routines in Python’s C API.
Borland note: convert pythonNN.lib to OMF format using Coff2Omf.exe first.
If you use SWIG, it is easy to create a Python “extension module” that will make the app’s data and methods available to Python. SWIG will handle just about all the grungy details for you. The result is C code that you link into your .exe file (!) You do _not_ have to create a DLL file, and this also simplifies linking.
SWIG will create an init function (a C function) whose name depends on the name of the extension module. For example, if the name of the module is leo, the init function will be called initleo(). If you use SWIG shadow classes, as you should, the init function will be called initleoc(). This initializes a mostly hidden helper class used by the shadow class.
The reason you can link the C code in step 2 into your .exe file is that calling the initialization function is equivalent to importing the module into Python! (This is the second key undocumented fact.)
In short, you can use the following code to initialize the Python interpreter with your extension module.
#include "python.h"
...
Py_Initialize(); // Initialize Python.
initmyAppc(); // Initialize (import) the helper class.
PyRun_SimpleString("import myApp") ; // Import the shadow class.
There are two problems with Python’s C API which will become apparent if you use a compiler other than MSVC, the compiler used to build pythonNN.dll.
Problem 1: The so-called “Very High Level” functions that take FILE * arguments will not work in a multi-compiler environment because each compiler’s notion of a struct FILE will be different. From an implementation standpoint these are very _low_ level functions.
Problem 2: SWIG generates the following code when generating wrappers to void functions:
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
Alas, Py_None is a macro that expands to a reference to a complex data structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will fail in a mult-compiler environment. Replace such code by:
return Py_BuildValue("");
It may be possible to use SWIG’s %typemap command to make the change automatically, though I have not been able to get this to work (I’m a complete SWIG newbie).
Using a Python shell script to put up a Python interpreter window from inside your Windows app is not a good idea; the resulting window will be independent of your app’s windowing system. Rather, you (or the wxPythonWindow class) should create a “native” interpreter window. It is easy to connect that window to the Python interpreter. You can redirect Python’s i/o to _any_ object that supports read and write, so all you need is a Python object (defined in your extension module) that contains read() and write() methods.
On the Microsoft IIS server or on the Win95 MS Personal Web Server you set up Python in the same way that you would set up any other scripting engine.
Run regedt32 and go to:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
and enter the following line (making any specific changes that your system may need):
.py :REG_SZ: c:\<path to python>\python.exe -u %s %s
This line will allow you to call your script with a simple reference like: http://yourserver/scripts/yourscript.py provided “scripts” is an “executable” directory for your server (which it usually is by default). The -u flag specifies unbuffered and binary mode for stdin - needed when working with binary data.
In addition, it is recommended that using ”.py” may not be a good idea for the file extensions when used in this context (you might want to reserve *.py for support modules and use *.cgi or *.cgp for “main program” scripts).
In order to set up Internet Information Services 5 to use Python for CGI processing, please see the following links:
http://www.e-coli.net/pyiis_server.html (for Win2k Server) http://www.e-coli.net/pyiis.html (for Win2k pro)
Configuring Apache is much simpler. In the Apache configuration file httpd.conf, add the following line at the end of the file:
ScriptInterpreterSource Registry
Then, give your Python CGI-scripts the extension .py and put them in the cgi-bin directory.
The FAQ does not recommend using tabs, and the Python style guide, PEP 8, recommends 4 spaces for distributed Python code; this is also the Emacs python-mode default.
Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in this respect, and is easily configured to use spaces: Take Tools ‣ Options ‣ Tabs, and for file type “Default” set “Tab size” and “Indent size” to 4, and select the “Insert spaces” radio button.
If you suspect mixed tabs and spaces are causing problems in leading whitespace, run Python with the -t switch or run Tools/Scripts/tabnanny.py to check a directory tree in batch mode.
Use the msvcrt module. This is a standard Windows-specific extension module. It defines a function kbhit() which checks whether a keyboard hit is present, and getch() which gets one character without echoing it.
To terminate a process, you can use 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))
Be sure you have the latest python.exe, that you are using python.exe rather than a GUI version of Python and that you have configured the server to execute
"...\python.exe -u ..."
for the CGI execution. The -u (unbuffered) option on NT and Win95 prevents the interpreter from altering newlines in the standard input and output. Without it post/multipart requests will seem to have the wrong length and binary (e.g. GIF) responses may get garbled (resulting in broken images, PDF files, and other binary downloads failing).
The reason that os.popen() doesn’t work from within PythonWin is due to a bug in Microsoft’s C Runtime Library (CRT). The CRT assumes you have a Win32 console attached to the process.
You should use the win32pipe module’s popen() instead which doesn’t depend on having an attached Win32 console.
Example:
import win32pipe
f = win32pipe.popen('dir /c c:\\')
print f.readlines()
f.close()
There is a bug in Win9x that prevents os.popen/win32pipe.popen* from working. The good news is there is a way to work around this problem. The Microsoft Knowledge Base article that you need to lookup is: Q150956. You will find links to the knowledge base at: http://support.microsoft.com/.
This is very sensitive to the compiler vendor, version and (perhaps) even options. If the FILE* structure in your embedding program isn’t the same as is assumed by the Python interpreter it won’t work.
The Python 1.5.* DLLs (python15.dll) are all compiled with MS VC++ 5.0 and with multithreading-DLL options (/MD).
If you can’t change compilers or flags, try using Py_RunSimpleString(). A trick to get it to run an arbitrary file is to construct a call to execfile() with the name of your file as argument.
Also note that you can not mix-and-match Debug and Release versions. If you wish to use the Debug Multithreaded DLL, then your module must have an “_d” appended to the base name.
Sometimes, the import of _tkinter fails on Windows 95 or 98, complaining with a message like the following:
ImportError: DLL load failed: One of the library files needed
to run this application cannot be found.
It could be that you haven’t installed Tcl/Tk, but if you did install Tcl/Tk, and the Wish application works correctly, the problem may be that its installer didn’t manage to edit the autoexec.bat file correctly. It tries to add a statement that changes the PATH environment variable to include the Tcl/Tk ‘bin’ subdirectory, but sometimes this edit doesn’t quite work. Opening it with notepad usually reveals what the problem is.
(One additional hint, noted by David Szafranski: you can’t use long filenames here; e.g. use C:\PROGRA~1\Tcl\bin instead of C:\Program Files\Tcl\bin.)
Sometimes, when you download the documentation package to a Windows machine using a web browser, the file extension of the saved file ends up being .EXE. This is a mistake; the extension should be .TGZ.
Simply rename the downloaded file to have the .TGZ extension, and WinZip will be able to handle it. (If your copy of WinZip doesn’t, get a newer one from http://www.winzip.com.)
Sometimes, when using Tkinter on Windows, you get an error that cw3215mt.dll or cw3215.dll is missing.
Cause: you have an old Tcl/Tk DLL built with cygwin in your path (probably C:\Windows). You must use the Tcl/Tk DLLs from the standard Tcl/Tk installation (Python 1.5.2 comes with one).
The Python installer issues a warning like this:
This version uses ``CTL3D32.DLL`` which is not the correct version.
This version is used for windows NT applications only.
Tim Peters:
This is a Microsoft DLL, and a notorious source of problems. The message means what it says: you have the wrong version of this DLL for your operating system. The Python installation did not cause this – something else you installed previous to this overwrote the DLL that came with your OS (probably older shareware of some sort, but there’s no way to tell now). If you search for “CTL3D32” using any search engine (AltaVista, for example), you’ll find hundreds and hundreds of web pages complaining about the same problem with all sorts of installation programs. They’ll point you to ways to get the correct version reinstalled on your system (since Python doesn’t cause this, we can’t fix it).
David A Burton has written a little program to fix this. Go to http://www.burtonsys.com/downloads.html and click on “ctl3dfix.zip”.