pytho****@googl*****
pytho****@googl*****
2011年 5月 4日 (水) 19:15:41 JST
8 new revisions: Revision: 32164f206329 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 04:27:57 2011 Log: 2.6.6: translate library/mailbox.rst http://code.google.com/p/python-doc-ja/source/detail?r=32164f206329 Revision: a41959a9abbb Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:21:45 2011 Log: 2.6.6: translate library/email.mime.rst http://code.google.com/p/python-doc-ja/source/detail?r=a41959a9abbb Revision: d4b00f49d036 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:41:46 2011 Log: 2.6.6: translate library/email.message.rst http://code.google.com/p/python-doc-ja/source/detail?r=d4b00f49d036 Revision: 56b26f7c1598 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:42:37 2011 Log: 2.6.6: translate library/email.charset.rst http://code.google.com/p/python-doc-ja/source/detail?r=56b26f7c1598 Revision: 4b0e0d2e25c9 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:44:46 2011 Log: 2.6.6: translate library/email.encoders.rst http://code.google.com/p/python-doc-ja/source/detail?r=4b0e0d2e25c9 Revision: 3fb0e648b616 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:47:10 2011 Log: 2.6.6: translate library/email.header.rst http://code.google.com/p/python-doc-ja/source/detail?r=3fb0e648b616 Revision: c5c97e85a56f Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:56:34 2011 Log: 原文のコメントアウト漏れを修正 http://code.google.com/p/python-doc-ja/source/detail?r=c5c97e85a56f Revision: cf1840f544d7 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 06:18:14 2011 Log: cmarkup の修正 extending/{embedding,extending}.rst library/{exceptions,ma... http://code.google.com/p/python-doc-ja/source/detail?r=cf1840f544d7 ============================================================================== Revision: 32164f206329 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 04:27:57 2011 Log: 2.6.6: translate library/mailbox.rst http://code.google.com/p/python-doc-ja/source/detail?r=32164f206329 Modified: /library/mailbox.rst ======================================= --- /library/mailbox.rst Sat Nov 27 10:59:46 2010 +++ /library/mailbox.rst Tue May 3 04:27:57 2011 @@ -612,7 +612,7 @@ `nmh - Message Handling System <http://www.nongnu.org/nmh/>`_ :program:`mh` の改良版である :program:`nmh` のホームページ - `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_ + `MH & nmh: Email for Users & Programmers <http://rand-mh.sourceforge.net/book/>`_ GPLライセンスの :program:`mh` および :program:`nmh` の本で、このメー ルボックス形式についての情報があります @@ -1511,7 +1511,7 @@ するクラスのインスタンスであるかもしれません。次のメッセージがない場合、 このメソッドは ``None`` を返します。 ほとんどの古いメールボックスクラスは現在のメールボックスクラスと違う名前で すが、 :class:`Maildir` だけは例外です。そのため、新しい方の -:class:`Maildir` クラスには :meth:`next` メソッドが定義され、コンストラクタ も他の新しいメールボックスクラスとは少し異なります。 +:class:`Maildir` クラスには :meth:`!next` メソッドが定義され、コンストラク タも他の新しいメールボックスクラスとは少し異なります。 古いメールボックスのクラスで名前が新しい対応物と同じでないものは以下の通り です: @@ -1521,7 +1521,7 @@ 全てのメッセージが単一のファイルに収められ、 ``From`` (``From_`` として 知られています) 行によって分割されているような、旧来の Unix形式のメールボックスにアクセスします。ファイルオブジェクト *fp* は メールボックスファイルを指します。オプションの *factory* パラメタは新たなメッセージオブジェクトを生成するような呼び出し可能オブジ ェクトです。 *factory* は、メールボックスオブジェクトに対して - :meth:`next` メソッドを実行した際に、単一の引数、 *fp* を伴って呼び出さ れます。この引数の標準の値は + :meth:`!next` メソッドを実行した際に、単一の引数、 *fp* を伴って呼び出さ れます。この引数の標準の値は :class:`rfc822.Message` クラスです (:mod:`rfc822` モジュール -- および以 下 -- を参照してください)。 .. note:: ============================================================================== Revision: a41959a9abbb Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:21:45 2011 Log: 2.6.6: translate library/email.mime.rst http://code.google.com/p/python-doc-ja/source/detail?r=a41959a9abbb Modified: /library/email.mime.rst ======================================= --- /library/email.mime.rst Sat Nov 27 10:59:46 2010 +++ /library/email.mime.rst Tue May 3 05:21:45 2011 @@ -9,13 +9,13 @@ テキストをパーザに通すことで得られます。パーザは与えられた\ テキストを解析し、基底となる root のメッセージオブジェクトを返します。\ しかし、完全なメッセージオブジェクト構造を何もないところから作成することも\ -また可能です。個別の :class:`Message` を手で作成することさえできます。\ +また可能です。個別の :class:`~email.message.Message` を手で作成することさえ できます。\ 実際には、すでに存在するメッセージオブジェクト構造をとってきて、\ -そこに新たな :class:`Message` オブジェクトを追加したり、あるものを\ +そこに新たな :class:`~email.message.Message` オブジェクトを追加したり、ある ものを\ 別のところへ移動させたりできます。これは MIME メッセージを\ 切ったりおろしたりするために非常に便利なインターフェイスを提供します。 -新しいメッセージオブジェクト構造は :class:`Message` インスタンスを\ +新しいメッセージオブジェクト構造は :class:`~email.message.Message` インスタ ンスを\ 作成することにより作れます。ここに添付ファイルやその他適切なものを\ すべて手で加えてやればよいのです。MIME メッセージの場合、 :mod:`email` パッケージはこれらを簡単におこなえるようにするために\ @@ -29,7 +29,7 @@ Module: :mod:`email.mime.base` - これはすべての MIME 用サブクラスの基底となるクラスです。\ + これはすべての :class:`~email.message.Message` の MIME 用サブクラスの基 底となるクラスです。\ とくに :class:`MIMEBase` のインスタンスを直接作成することは (可能ではありますが) ふつうはしないでしょう。 :class:`MIMEBase` は単により特化された MIME @@ -54,11 +54,11 @@ Module: :mod:`email.mime.nonmultipart` - :class:`MIMEBase` のサブクラスで、これは :mimetype:`multipart` 形式でな い MIME + :class:`~email.mime.base.MIMEBase` のサブクラスで、これ は :mimetype:`multipart` 形式でない MIME メッセージのための中間的な基底クラスです。このクラスのおもな目的は、 通常 :mimetype:`multipart` 形式のメッセージに対してのみ意味をなす :meth:`attach` メソッドの使用をふせぐことです。もし :meth:`attach` メソ ッドが\ - 呼ばれた場合、これは :exc:`MultipartConversionError` 例外を発生します。 + 呼ばれた場合、これは :exc:`~email.errors.MultipartConversionError` 例外 を発生します。 .. versionadded:: 2.2.2 @@ -69,7 +69,7 @@ Module: :mod:`email.mime.multipart` - :class:`MIMEBase` のサブクラスで、これは :mimetype:`multipart` 形式の MIME + :class:`~email.mime.base.MIMEBase` のサブクラスで、これ は :mimetype:`multipart` 形式の MIME メッセージのための中間的な基底クラスです。オプション引数 *_subtype* は\ デフォルトでは :mimetype:`mixed` になっていますが、そのメッセージの副形 式 (subtype) を指定するのに使うことができます。メッセージオブジェクトには @@ -77,7 +77,8 @@ :mailheader:`MIME-Version` ヘッダが追加されるでしょう。 オプション引数 *boundary* は multipart の境界文字列です。 - これが ``None`` の場合 (デフォルト)、境界は必要に応じて計算されます。 + これが ``None`` の場合 (デフォルト)、境界は必要に応じて計算されます + （例えばメッセージがシリアライズされるときなど）。 *_subparts* はそのペイロードの subpart の初期値からなるシーケンスです。 このシーケンスはリストに変換できるようになっている必要があります。 @@ -97,7 +98,7 @@ Module: :mod:`email.mime.application` - :class:`MIMENonMultipart` のサブクラスである :class:`MIMEApplication` + :class:`~email.mime.nonmultipart.MIMENonMultipart` のサブクラスであ る :class:`MIMEApplication` クラスは MIME メッセージオブジェクトのメジャータイ プ :mimetype:`application` を表します。 *_data* は生のバイト列が入った文字列です。オプション引数 *_subtype* は @@ -126,7 +127,7 @@ Module: :mod:`email.mime.audio` - :class:`MIMEAudio` クラスは :class:`MIMENonMultipart` のサブクラスで、 + :class:`MIMEAudio` クラス は :class:`~email.mime.nonmultipart.MIMENonMultipart` のサブクラスで、 主形式 (maintype) が :mimetype:`audio` の MIME オブジェクトを作成\ するのに使われます。 *_audiodata* は実際の音声データを格納した文字列で す。 もしこのデータが標準の Python モジュール :mod:`sndhdr` によって\ @@ -155,7 +156,7 @@ Module: :mod:`email.mime.image` - :class:`MIMEImage` クラスは :class:`MIMENonMultipart` のサブクラスで、 + :class:`MIMEImage` クラス は :class:`~email.mime.nonmultipart.MIMENonMultipart.MIMENonMultipart` のサ ブクラスで、 主形式 (maintype) が :mimetype:`image` の MIME オブジェクトを作成\ するのに使われます。 *_imagedata* は実際の画像データを格納した文字列で す。 もしこのデータが標準の Python モジュール :mod:`imghdr` によって\ @@ -176,7 +177,7 @@ デフォルトのエンコーディングは base64 です。組み込みのエンコーダの詳細に ついては :mod:`email.encoders` を参照してください。 - *_params* は :class:`MIMEBase` コンストラクタに直接渡されます。 + *_params* は :class:`~email.mime.base.MIMEBase` コンストラクタに直接渡さ れます。 .. currentmodule:: email.mime.message @@ -185,10 +186,10 @@ Module: :mod:`email.mime.message` - :class:`MIMEMessage` クラスは :class:`MIMENonMultipart` のサブクラスで、 + :class:`MIMEMessage` クラス は :class:`~email.mime.nonmultipart.MIMENonMultipart` のサブクラスで、 主形式 (maintype) が :mimetype:`message` の MIME オブジェクトを作成\ するのに使われます。ペイロードとして使われるメッセージは *_msg* - になります。これは :class:`Message` クラス (あるいはそのサブクラス) の\ + になります。これは :class:`~email.message.Message` クラス (あるいはその サブクラス) の\ インスタンスでなければいけません。そうでない場合、この関数は :exc:`TypeError` を発生します。 @@ -202,16 +203,17 @@ Module: :mod:`email.mime.text` - :class:`MIMEText` クラスは :class:`MIMENonMultipart` のサブクラスで、 + :class:`MIMEText` クラス は :class:`~email.mime.nonmultipart.MIMENonMultipart` のサブクラスで、 主形式 (maintype) が :mimetype:`text` の MIME オブジェクトを作成\ するのに使われます。ペイロードの文字列は *_text* になります。 *_subtype* には副形式 (subtype) を指定し、デフォルト は :mimetype:`plain` です。 *_charset* はテキストの文字セットで、 - :class:`MIMENonMultipart` コンストラクタに引数として渡されます。 + :class:`~email.mime.nonmultipart.MIMENonMultipart` コンストラクタに引数 として渡されます。 デフォルトではこの値は ``us-ascii`` になっています。 - テキストデータに対しては文字コードの推定やエンコードはまったく行われませ ん。 - + *_text* が unicode の場合には *_charset* の *output_charset* でエンコー ドされ、 + それ以外の場合にはそのまま使われます。 + .. versionchanged:: 2.4 以前、推奨されない引数であった *_encoding* は撤去されました。 - エンコーディングは *_charset* 引数をもとにして暗黙のうちに決定されま す。 - + *_charset* 引数を基にして Content Transfer Encodnig が暗黙に決定され ます。 + ============================================================================== Revision: d4b00f49d036 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:41:46 2011 Log: 2.6.6: translate library/email.message.rst http://code.google.com/p/python-doc-ja/source/detail?r=d4b00f49d036 Modified: /library/email.message.rst ======================================= --- /library/email.message.rst Sat Nov 27 10:59:46 2010 +++ /library/email.message.rst Tue May 3 05:41:46 2011 @@ -45,10 +45,18 @@ メッセージ全体をフラットな文字列として返します。オプション *unixfrom* が ``True`` の場合、返される文字列にはエンベロープヘッダも含まれます。 *unixfrom* のデフォルトは ``False`` です。 + もし、文字列への変換を完全に行うためにデフォルト値を埋める必要がある 場合、 + メッセージのフラット化は :class:`Message` の変更を引き起こす可能性が あります + (例えば、MIME の境界が生成される、変更される等)。 + + Flattening the message may trigger + changes to the :class:`Message` if defaults need to be filled in to + complete the transformation to a string (for example, MIME boundaries may + be generated or modified). このメソッドは手軽に利用する事ができますが、必ずしも期待通りにメッ セージを\ フォーマットするとは限りません。たとえば、これはデフォルトでは ``From`` で\ - 始まる行を変更してしまいます。以下の例のように :class:`Generator` + 始まる行を変更してしまいます。以下の例のよう に :class:`~email.generator.Generator` のインスタンスを生成して :meth:`flatten` メソッドを直接呼び出せば\ より柔軟な処理を行う事ができます。 :: @@ -139,18 +147,18 @@ .. method:: set_charset(charset) ペイロードの文字セットを *charset* に変更します。 - ここには :class:`Charset` インスタンス (:mod:`email.charset` 参照)、 + ここには :class:`~email.charset.Charset` インスタンス (:mod:`email.charset` 参照)、 文字セット名をあらわす文字列、あるいは ``None`` のいずれかが指定でき ます。 - 文字列を指定した場合、これは :class:`Charset` インスタンスに変換され ます。 + 文字列を指定した場合、これは :class:`~email.charset.Charset` インスタ ンスに変換されます。 *charset* が ``None`` の場合、 ``charset`` パラメータは :mailheader:`Content-Type` ヘッダから除去されます。 これ以外のものを文字セットとして指定した場合、 :exc:`TypeError` が発生します。 - ここでいうメッセージとは、 *charset.input_charset* でエンコードされた - :mimetype:`text/\*` 形式のものを仮定しています。これは、もし必要とあ らば\ + ここでいうメッセージとは、unicode 文字列か *charset.input_charset* で エンコードされた + ペイロードを持つ :mimetype:`text/\*` 形式のものを仮定しています。これ は、もし必要とあらば\ プレーンテキスト形式を変換するさいに *charset.output_charset* の - エンコードに変換されます。MIME ヘッダ (:mailheader:`MIME-Version`, + トランスファーエンコードに変換されます。MIME ヘッダ (:mailheader:`MIME-Version`, :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) は必要に応じて追加されます。 @@ -159,7 +167,7 @@ .. method:: get_charset() - そのメッセージ中のペイロードの :class:`Charset` インスタンスを返しま す。 + そのメッセージ中のペイロードの :class:`~email.charset.Charset` インス タンスを返します。 .. versionadded:: 2.2.2 @@ -519,7 +527,7 @@ 注意: これは :meth:`get_charset` メソッドとは異なります。 こちらのほうは文字列のかわりに、そのメッセージボディのデフォルト\ - エンコーディングの :class:`Charset` インスタンスを返します。 + エンコーディングの :class:`~email.charset.Charset` インスタンスを返し ます。 .. versionadded:: 2.2.2 @@ -579,7 +587,7 @@ 対応していないメールソフトで見る場合、このテキストは目に見えることに なります。 *preamble* 属性は MIME ドキュメントに加えるこの最初の MIME - 範囲外テキストを含んでいます。 :class:`Parser` + 範囲外テキストを含んでいます。 :class:`~email.parser.Parser` があるテキストをヘッダ以降に発見したが、それはまだ最初の MIME 境界文字列が現れる前だった場合、パーザはそのテキストをメッセージの *preamble* 属性に格納します。 :class:`Generator` がある MIME メッセージから\ ============================================================================== Revision: 56b26f7c1598 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:42:37 2011 Log: 2.6.6: translate library/email.charset.rst http://code.google.com/p/python-doc-ja/source/detail?r=56b26f7c1598 Modified: /library/email.charset.rst ======================================= --- /library/email.charset.rst Sat Nov 27 10:59:46 2010 +++ /library/email.charset.rst Tue May 3 05:42:37 2011 @@ -163,7 +163,7 @@ これは行の長さ問題のあるマルチバイトの文字セットに対しては役に立ちま せん (マルチバイト文字はバイト境界ではなく、文字ごとの境界で split する必要があります)。 - これらの問題を扱うには、高水準のクラスである :class:`Header` クラスを \ + これらの問題を扱うには、高水準のクラスであ る :class:`~email.header.Header` クラスを\ 使ってください (:mod:`email.header` を参照)。 *convert* の値はデフォルトでは ``False`` です。 ============================================================================== Revision: 4b0e0d2e25c9 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:44:46 2011 Log: 2.6.6: translate library/email.encoders.rst http://code.google.com/p/python-doc-ja/source/detail?r=4b0e0d2e25c9 Modified: /library/email.encoders.rst ======================================= --- /library/email.encoders.rst Sun Mar 1 08:41:39 2009 +++ /library/email.encoders.rst Tue May 3 05:44:46 2011 @@ -5,15 +5,15 @@ :synopsis: 電子メールメッセージのペイロードのためのエンコーダ。 -何もないところから :class:`Message` を作成するときしばしば必要になるのが、 +何もないところから :class:`~email.message.Message` を作成するときしばしば必 要になるのが、 ペイロードをメールサーバに通すためにエンコードすることです。 これはとくにバイナリデータを含んだ :mimetype:`image/\*` や :mimetype:`text/\*` タイプのメッセージで必要です。 :mod:`email` パッケージでは、 :mod:`encoders` モジュールにおいて いくかの便宜的なエンコーディングをサポートしています。 -実際にはこれらのエンコーダは :class:`MIMEAudio` および -:class:`MIMEImage` クラスのコンストラクタでデフォルトエンコーダとして使われ ています。 +実際にはこれらのエンコーダは :class:`~email.mime.audio.MIMEAudio` および +:class:`~email.mime.audio.MIMEImage` クラスのコンストラクタでデフォルトエン コーダとして使われています。 すべてのエンコーディング関数は、エンコードするメッセージオブジェクト\ ひとつだけを引数にとります。これらはふつうペイロードを取りだし、 それをエンコードして、ペイロードをエンコードされたものにセットしなおしま す。 ============================================================================== Revision: 3fb0e648b616 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:47:10 2011 Log: 2.6.6: translate library/email.header.rst http://code.google.com/p/python-doc-ja/source/detail?r=3fb0e648b616 Modified: /library/email.header.rst ======================================= --- /library/email.header.rst Sat Nov 27 10:59:46 2010 +++ /library/email.header.rst Tue May 3 05:47:10 2011 @@ -24,7 +24,7 @@ ご自分の電子メールヘッダ、たとえば :mailheader:`Subject` や :mailheader:`To` などのフィールドに非ASCII文字を入れたい場合、 :class:`Header` クラスを使う必要があります。 -:class:`Message` オブジェクトの該当フィールドに文字列ではなく、 +:class:`~email.message.Message` オブジェクトの該当フィールドに文字列ではな く、 :class:`Header` インスタンスを使うのです。 :class:`Header` クラスは :mod:`email.header` モジュールから\ インポートしてください。たとえば:: @@ -42,7 +42,7 @@ :mailheader:`Subject` フィールドに非ASCII文字をふくめていることに\ 注目してください。ここでは、含めたいバイト列がエンコードされている\ 文字セットを指定して :class:`Header` インスタンスを作成することによって\ -実現しています。のちにこの :class:`Message` インスタンスから\ +実現しています。のちにこの :class:`~email.message.Message` インスタンスから \ フラットなテキストを生成するさいに、この :mailheader:`Subject` フィールド は :rfc:`2047` 準拠の適切な形式にエンコードされます。MIME 機能のついている\ メーラなら、このヘッダに埋めこまれた ISO-8859-1 文字をただしく表示するでし ょう。 @@ -90,8 +90,8 @@ この MIME ヘッダに文字列 *s* を追加します。 オプション引数 *charset* がもし与えられた場合、これは - :class:`Charset` インスタンス (:mod:`email.charset` を参照) か、 - あるいは文字セットの名前でなければなりません。この場合 は :class:`Charset` + :class:`~email.charset.Charset` インスタンス (:mod:`email.charset` を 参照) か、 + あるいは文字セットの名前でなければなりません。この場合 は :class:`~email.charset.Charset` インスタンスに変換されます。この値が ``None`` の場合 (デフォルト)、 コンストラクタで与えられた *charset* が使われます。 ============================================================================== Revision: c5c97e85a56f Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 05:56:34 2011 Log: 原文のコメントアウト漏れを修正 http://code.google.com/p/python-doc-ja/source/detail?r=c5c97e85a56f Modified: /library/platform.rst ======================================= --- /library/platform.rst Sat Apr 16 17:12:19 2011 +++ /library/platform.rst Tue May 3 05:56:34 2011 @@ -226,7 +226,8 @@ .. function:: linux_distribution(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...), full_distribution_name=1) - Tries to determine the name of the Linux OS distribution name. + .. Tries to determine the name of the Linux OS distribution name. + OSディストリビューション名の取得を試みます。 .. ``supported_dists`` may be given to define the set of Linux distributions to ============================================================================== Revision: cf1840f544d7 Author: Akihiro Uchida <uchid****@ike-d*****> Date: Tue May 3 06:18:14 2011 Log: cmarkup の修正 extending/{embedding,extending}.rst library/{exceptions,mailbox}.rst http://code.google.com/p/python-doc-ja/source/detail?r=cf1840f544d7 Modified: /extending/embedding.rst /extending/extending.rst /library/exceptions.rst /library/mailbox.rst ======================================= --- /extending/embedding.rst Sat Nov 27 12:10:59 2010 +++ /extending/embedding.rst Tue May 3 06:18:14 2011 @@ -19,13 +19,13 @@ 実行させる --- かもしれない、ということです。 従って、 Python の埋め込みを行う場合、自作のメインプログラムを提供しなけれ ばなりません。メインプログラムがやらなければならないことの一つに、 -Python インタプリタの初期化があります。とにかく少なくとも関 数 :cfunc:`Py_Initialize` +Python インタプリタの初期化があります。とにかく少なくとも関 数 :c:func:`Py_Initialize` を呼び出さねばなりません。オプションとして、Python 側にコマンドライン引数を渡すために関数呼び出しを行います。その後、アプリ ケーションのどこでもインタプリタを呼び出せるようになります。 -インタプリタを呼び出すには、異なるいくつかの方法があります: Python 文が入っ た文字列を :cfunc:`PyRun_SimpleString` に渡す、 +インタプリタを呼び出すには、異なるいくつかの方法があります: Python 文が入っ た文字列を :c:func:`PyRun_SimpleString` に渡す、 stdio ファイルポインタとファイル名 (これはエラーメッセージ内でコードを識別 するためだけのものです) を -:cfunc:`PyRun_SimpleFile` に渡す、といった具合です。これまでの各章で説明し た低水準の操作を呼び出して、Python オブジェクトを +:c:func:`PyRun_SimpleFile` に渡す、といった具合です。これまでの各章で説明し た低水準の操作を呼び出して、Python オブジェクトを 構築したり使用したりもできます。 Python の埋め込みを行っている簡単なデモは、ソース配布物 の :file:`Demo/embed/` ディレクトリにあります。 @@ -57,10 +57,10 @@ return 0; } -上のコードでは、まず Python インタプリタを :cfunc:`Py_Initialize` で起動 し、続いてハードコードされた Python -スクリプトで日付と時間の出力を実行します。その後、 :cfunc:`Py_Finalize` の 呼び出しでインタプリタを終了し, プログラムの終了に続きます。 +上のコードでは、まず Python インタプリタを :c:func:`Py_Initialize` で起動 し、続いてハードコードされた Python +スクリプトで日付と時間の出力を実行します。その後、 :c:func:`Py_Finalize` の 呼び出しでインタプリタを終了し, プログラムの終了に続きます。 実際のプログラムでは、Python スクリプトを他のソース、おそらくテキストエディ タルーチンやファイル、データベースから取り出したいと -考えるかもしれません。Python コードをファイルから取り出すに は、 :cfunc:`PyRun_SimpleFile` 関数を使うのがよいでしょう。 +考えるかもしれません。Python コードをファイルから取り出すに は、 :c:func:`PyRun_SimpleFile` 関数を使うのがよいでしょう。 この関数はメモリを確保して、ファイルの内容をロードする手間を省いてくれま す。 @@ -139,8 +139,8 @@ から始まる部分です。 -インタプリタの初期化後、スクリプトは :cfunc:`PyImport_Import` を使って読み 込まれます。このルーチンは Python -文字列を引数に取る必要があり、データ変換ルーチ ン :cfunc:`PyString_FromString` で構築します。 :: +インタプリタの初期化後、スクリプトは :c:func:`PyImport_Import` を使って読み 込まれます。このルーチンは Python +文字列を引数に取る必要があり、データ変換ルーチ ン :c:func:`PyString_FromString` で構築します。 :: pFunc = PyObject_GetAttrString(pModule, argv[2]); /* pFunc は新たな参照 */ @@ -150,7 +150,7 @@ } Py_XDECREF(pFunc); -ひとたびスクリプトが読み込まれると、 :cfunc:`PyObject_GetAttrString` を使っ て必要な名前を取得 +ひとたびスクリプトが読み込まれると、 :c:func:`PyObject_GetAttrString` を使 って必要な名前を取得 できます。名前がスクリプト中に存在し、取得したオブジェクトが呼び出し可能オ ブジェクトであれば、このオブジェクトが関数であると 考えて差し支えないでしょう。そこでプログラムは定石どおりに引数のタプル構築 に進みます。その後、Python 関数を以下のコードで呼び出します:: @@ -188,7 +188,7 @@ {NULL, NULL, 0, NULL} }; -上のコードを :cfunc:`main` 関数のすぐ上に挿入します。また、以下の二つの文 を :cfunc:`Py_Initialize` の直後 +上のコードを :c:func:`main` 関数のすぐ上に挿入します。また、以下の二つの文 を :c:func:`Py_Initialize` の直後 に挿入します:: numargs = argc; ======================================= --- /extending/extending.rst Mon Nov 22 06:08:51 2010 +++ /extending/extending.rst Tue May 3 06:18:14 2011 @@ -23,7 +23,7 @@ ======== ``spam`` (Monty Python ファンの好物ですね) という名の拡張モジュールを作成す ることにして、C ライブラリ関数 -:cfunc:`system` に対する Python インタフェースを作成したいとします。 [#]_ この関数は null +:c:func:`system` に対する Python インタフェースを作成したいとします。 [#]_ この関数は null で終端されたキャラクタ文字列を引数にとり、整数を返します。この関数を以下の ようにして Python から呼び出せるようにしたいとします:: >>> import spam @@ -45,7 +45,7 @@ 標準ヘッダファイル内の定義は除きます。簡単のためと、Python 内で広範に使うこ とになるという理由から、 ``"Python.h"`` はいくつかの標準ヘッダファイル: ``<stdio.h>`` 、 ``<string.h>`` 、 ``<errno.h>`` 、および ``<stdlib.h>`` をインクルードしています。後者のヘッダファイルがシステム上になければ、 ``"Python.h"`` が関数 -:cfunc:`malloc` 、 :cfunc:`free` および :cfunc:`realloc` を直接定義しま す。 +:c:func:`malloc` 、 :c:func:`free` および :c:func:`realloc` を直接定義しま す。 次にファイルに追加する内容は、Python 式 ``spam.system(string)`` を評価する 際に呼び出されることになる C 関数です (この関数を最終的にどのように呼び出すかは、後ですぐわかります):: @@ -71,11 +71,11 @@ *args* 引数は、引数の入った Python タプルオブジェクトへのポインタになりま す。タプル内の各要素は、呼び出しの際の引数リストに おける各引数に対応します。引数は Python オブジェクトです --- C 関数で引数 を使って何かを行うには、オブジェクトから C の値に -変換せねばなりません。Python API の関数 :cfunc:`PyArg_ParseTuple` は引数の 型をチェックし、C の値に変換します。 -:cfunc:`PyArg_ParseTuple` はテンプレート文字列を使って、引数オブジェクトの 型と、変換された値を入れる C 変数の型を判別します。 +変換せねばなりません。Python API の関数 :c:func:`PyArg_ParseTuple` は引数の 型をチェックし、C の値に変換します。 +:c:func:`PyArg_ParseTuple` はテンプレート文字列を使って、引数オブジェクトの 型と、変換された値を入れる C 変数の型を判別します。 これについては後で詳しく説明します。 -:cfunc:`PyArg_ParseTuple` は、全ての引数が正しい型を持っていて、アドレス渡 しされた各変数に各引数要素を保存したときに真 (非ゼロ) +:c:func:`PyArg_ParseTuple` は、全ての引数が正しい型を持っていて、アドレス渡 しされた各変数に各引数要素を保存したときに真 (非ゼロ) を返します。この関数は不正な引数リストを渡すと偽 (ゼロ) を返します。後者の 場合、関数は適切な例外を送出するので、呼び出し側は (例にもあるように) すぐに *NULL* を返すようにしてください。 @@ -96,58 +96,58 @@ Python API では、様々な型の例外をセットするための関数をいくつか定義していま す。 -もっともよく用いられるのは :cfunc:`PyErr_SetString` です。引数は例外オブジ ェクトと C 文字列です。例外オブジェクトは -通常、 :cdata:`PyExc_ZeroDivisionError` のような定義済みのオブジェクトで す。 C 文字列はエラーの原因を示し、Python +もっともよく用いられるのは :c:func:`PyErr_SetString` です。引数は例外オブジ ェクトと C 文字列です。例外オブジェクトは +通常、 :c:data:`PyExc_ZeroDivisionError` のような定義済みのオブジェクトで す。 C 文字列はエラーの原因を示し、Python 文字列オブジェクトに変換されて例外の "付属値" に保存されます。 -もう一つ有用な関数として :cfunc:`PyErr_SetFromErrno` があります。この関数は 引数に例外だけをとり、付属値はグローバル変数 -:cdata:`errno` から構築します。もっとも汎用的な関数 は :cfunc:`PyErr_SetObject` で、 -二つのオブジェクト、例外と付属値を引数にとります。これら関数に渡すオブジェ クトには :cfunc:`Py_INCREF` を使う必要はありません。 - -例外がセットされているかどうかは、 :cfunc:`PyErr_Occurred` を使って非破壊 的に調べられます。この関数は現在の例外オブジェクトを +もう一つ有用な関数として :c:func:`PyErr_SetFromErrno` があります。この関数 は引数に例外だけをとり、付属値はグローバル変数 +:c:data:`errno` から構築します。もっとも汎用的な関数 は :c:func:`PyErr_SetObject` で、 +二つのオブジェクト、例外と付属値を引数にとります。これら関数に渡すオブジェ クトには :c:func:`Py_INCREF` を使う必要はありません。 + +例外がセットされているかどうかは、 :c:func:`PyErr_Occurred` を使って非破壊 的に調べられます。この関数は現在の例外オブジェクトを 返します。例外が発生していない場合には *NULL* を返します。通常は、関数の戻 り値からエラーが発生したかを判別できるはずなので、 -:cfunc:`PyErr_Occurred` を呼び出す必要はありません。 +:c:func:`PyErr_Occurred` を呼び出す必要はありません。 関数 *g* を呼び出す *f* が、前者の関数の呼び出しに失敗したことを検出する と、 *f* 自体はエラー値 (大抵は *NULL* や ``-1``) -を返さねばなりません。しかし、 :cfunc:`PyErr_\*` 関数群のいずれかを呼び出す 必要は *ありません* --- なぜなら、 *g* +を返さねばなりません。しかし、 :c:func:`PyErr_\*` 関数群のいずれかを呼び出 す必要は *ありません* --- なぜなら、 *g* がすでに呼び出しているからです。次いで *f* を呼び出したコードもエラーを示す 値を *自らを呼び出したコード* に返すことになりますが、 -同様に :cfunc:`PyErr_\*` は *呼び出しません* 。以下同様に続きます --- エ ラーの最も詳しい原因は、最初にエラーを検出した +同様に :c:func:`PyErr_\*` は *呼び出しません* 。以下同様に続きます --- エ ラーの最も詳しい原因は、最初にエラーを検出した 関数がすでに報告しているからです。エラーが Python インタプリタのメインルー プに到達すると、現在実行中の Python コードは一時停止し、 Python プログラマが指定した例外ハンドラを探し出そうとします。 -(モジュールが :cfunc:`PyErr_\*` 関数をもう一度呼び出して、より詳細なエラー メッセージを提供するような状況があります。このような状況では -そうすべきです。とはいえ、一般的な規則としては、 :cfunc:`PyErr_\*` を何度 も呼び出す必要はなく、ともすればエラーの原因に関する情報を +(モジュールが :c:func:`PyErr_\*` 関数をもう一度呼び出して、より詳細なエラー メッセージを提供するような状況があります。このような状況では +そうすべきです。とはいえ、一般的な規則としては、 :c:func:`PyErr_\*` を何度 も呼び出す必要はなく、ともすればエラーの原因に関する情報を 失う結果になりがちです: これにより、ほとんどの操作が様々な理由から失敗する かもしれません) -ある関数呼び出しでの処理の失敗によってセットされた例外を無視するに は、 :cfunc:`PyErr_Clear` を呼び出して例外状態を明示的に消去 +ある関数呼び出しでの処理の失敗によってセットされた例外を無視するに は、 :c:func:`PyErr_Clear` を呼び出して例外状態を明示的に消去 しなくてはなりません。エラーをインタプリタには渡したくなく、自前で (何か他 の作業を行ったり、何も起こらなかったかのように見せかけるような) -エラー処理を完全に行う場合にのみ、 :cfunc:`PyErr_Clear` を呼び出すようにす べきです。 - -:cfunc:`malloc` の呼び出し失敗は、常に例外にしなくてはなりません --- :cfunc:`malloc` (または -:cfunc:`realloc`) を直接呼び出しているコードは、 :cfunc:`PyErr_NoMemory` -を呼び出して、失敗を示す値を返さねばなりません。オブジェクトを生成する全て の関数 (例えば :cfunc:`PyInt_FromLong`) は -:cfunc:`PyErr_NoMemory` の呼び出しを済ませてしまうので、この規則が関係する のは直接 :cfunc:`malloc` を呼び出す +エラー処理を完全に行う場合にのみ、 :c:func:`PyErr_Clear` を呼び出すようにす べきです。 + +:c:func:`malloc` の呼び出し失敗は、常に例外にしなくてはなりません --- :c:func:`malloc` (または +:c:func:`realloc`) を直接呼び出しているコードは、 :c:func:`PyErr_NoMemory` +を呼び出して、失敗を示す値を返さねばなりません。オブジェクトを生成する全て の関数 (例えば :c:func:`PyInt_FromLong`) は +:c:func:`PyErr_NoMemory` の呼び出しを済ませてしまうので、この規則が関係する のは直接 :c:func:`malloc` を呼び出す コードだけです。 -また、 :cfunc:`PyArg_ParseTuple` という重要な例外を除いて、整数の状態コード を返す関数はたいてい、Unix のシステムコール +また、 :c:func:`PyArg_ParseTuple` という重要な例外を除いて、整数の状態コー ドを返す関数はたいてい、Unix のシステムコール と同じく、処理が成功した際にはゼロまたは正の値を返し、失敗した場合には ``-1`` を返します。 -最後に、エラー標示値を返す際に、(エラーが発生するまでに既に生成してしまった オブジェクトに対して :cfunc:`Py_XDECREF` や -:cfunc:`Py_DECREF` を呼び出して) ごみ処理を注意深く行ってください! - -どの例外を返すかの選択は、ユーザに完全にゆだねられま す。 :cdata:`PyExc_ZeroDivisionError` のように、全ての組み込みの +最後に、エラー標示値を返す際に、(エラーが発生するまでに既に生成してしまった オブジェクトに対して :c:func:`Py_XDECREF` や +:c:func:`Py_DECREF` を呼び出して) ごみ処理を注意深く行ってください! + +どの例外を返すかの選択は、ユーザに完全にゆだねられま す。 :c:data:`PyExc_ZeroDivisionError` のように、全ての組み込みの Python 例外には対応する宣言済みの C オブジェクトがあり、直接利用できます。 もちろん、例外の選択は賢く行わねばなりません --- -ファイルが開けなかったことを表すのに :cdata:`PyExc_TypeError` を使ったりは しないでください -(この場合はおそらく :cdata:`PyExc_IOError` の方にすべきでしょう)。 -引数リストに問題がある場合には、 :cfunc:`PyArg_ParseTuple` はたいて い :cdata:`PyExc_TypeError` -を送出します。引数の値が特定の範囲を超えていたり、その他の満たすべき条件を 満たさなかった場合には、 :cdata:`PyExc_ValueError` +ファイルが開けなかったことを表すのに :c:data:`PyExc_TypeError` を使ったり はしないでください +(この場合はおそらく :c:data:`PyExc_IOError` の方にすべきでしょう)。 +引数リストに問題がある場合には、 :c:func:`PyArg_ParseTuple` はたいて い :c:data:`PyExc_TypeError` +を送出します。引数の値が特定の範囲を超えていたり、その他の満たすべき条件を 満たさなかった場合には、 :c:data:`PyExc_ValueError` が適切です。 モジュール固有の新たな例外も定義できます。定義するには、通常はファイルの先 頭部分に静的なオブジェクト変数の宣言を行います:: static PyObject *SpamError; -そして、モジュールの初期化関数 (:cfunc:`initspam`) の中で、例外オブジェクト を使って初期化します (ここでは +そして、モジュールの初期化関数 (:c:func:`initspam`) の中で、例外オブジェク トを使って初期化します (ここでは エラーチェックを省略しています):: PyMODINIT_FUNC @@ -165,13 +165,13 @@ } Python レベルでの例外オブジェクトの名前は :exc:`spam.error` になることに注 意してください。 -:cfunc:`PyErr_NewException` 関数は、 :ref:`bltin-exceptions` で述べられて いる +:c:func:`PyErr_NewException` 関数は、 :ref:`bltin-exceptions` で述べられて いる :exc:`Exception` クラスを基底クラスに持つ例外クラスも作成できます (*NULL* の代わりに他のクラスを渡した場合は別です)。 -:cdata:`SpamError` 変数は、新たに生成された例外クラスへの参照を維持すること にも注意してください; これは意図的な仕様です! -外部のコードが例外オブジェクトをモジュールから除去できるため、モジュールか ら新たに作成した例外クラスが見えなくなり、 :cdata:`SpamError` +:c:data:`SpamError` 変数は、新たに生成された例外クラスへの参照を維持するこ とにも注意してください; これは意図的な仕様です! +外部のコードが例外オブジェクトをモジュールから除去できるため、モジュールか ら新たに作成した例外クラスが見えなくなり、 :c:data:`SpamError` がぶら下がりポインタ (dangling pointer) になってしまわないようにするため に、クラスに対する参照を所有しておかねばなりません。 -もし :cdata:`SpamError` がぶら下がりポインタになってしまうと、 C コードが例 外を送出しようとしたときにコアダンプや意図しない副作用を +もし :c:data:`SpamError` がぶら下がりポインタになってしまうと、 C コードが 例外を送出しようとしたときにコアダンプや意図しない副作用を 引き起こすことがあります。 この例にある、関数の戻り値型に PyMODINIT_FUNC の使う方法については後で議論 します。 @@ -187,32 +187,32 @@ if (!PyArg_ParseTuple(args, "s", &command)) return NULL; -この実行文は、 :cfunc:`PyArg_ParseTuple` がセットする例外によって、引数リス トに何らかのエラーが生じたときに *NULL* +この実行文は、 :c:func:`PyArg_ParseTuple` がセットする例外によって、引数リ ストに何らかのエラーが生じたときに *NULL* (オブジェクトへのポインタを返すタイプの関数におけるエラー標示値) を返しま す。エラーでなければ、引数として与えた文字列値はローカルな変数 -:cdata:`command` にコピーされています。この操作はポインタ代入であり、ポイン タが指している文字列に対して変更が行われるとは想定されていません -(従って、標準 C では、変数 :cdata:`command` は ``const char* command`` とし て適切に定義せねばなりません)。 - -次の文では、 :cfunc:`PyArg_ParseTuple` で得た文字列を渡して Unix 関 数 :cfunc:`system` を呼び出しています:: +:c:data:`command` にコピーされています。この操作はポインタ代入であり、ポイ ンタが指している文字列に対して変更が行われるとは想定されていません +(従って、標準 C では、変数 :c:data:`command` は ``const char* command`` と して適切に定義せねばなりません)。 + +次の文では、 :c:func:`PyArg_ParseTuple` で得た文字列を渡して Unix 関 数 :c:func:`system` を呼び出しています:: sts = system(command); -:func:`spam.system` は :cdata:`sts` を Python オブジェクト -として返さねばなりません。これには、 :cfunc:`PyArg_ParseTuple` の逆ともいう べき関数 :cfunc:`Py_BuildValue` -を使います: :cfunc:`Py_BuildValue` は書式化文字列と任意の数の C の値を引数 にとり、新たな Python オブジェクトを返します。 -:cfunc:`Py_BuildValue` に関する詳しい情報は後で示します。 :: +:func:`spam.system` は :c:data:`sts` を Python オブジェクト +として返さねばなりません。これには、 :c:func:`PyArg_ParseTuple` の逆ともい うべき関数 :c:func:`Py_BuildValue` +を使います: :c:func:`Py_BuildValue` は書式化文字列と任意の数の C の値を引数 にとり、新たな Python オブジェクトを返します。 +:c:func:`Py_BuildValue` に関する詳しい情報は後で示します。 :: return Py_BuildValue("i", sts); -上の場合では、 :cfunc:`Py_BuildValue` は整数オブジェクトを返します。(そう、 整数ですら、 Python においてはヒープ上の +上の場合では、 :c:func:`Py_BuildValue` は整数オブジェクトを返します。(そ う、整数ですら、 Python においてはヒープ上の オブジェクトなのです! ) -何ら有用な値を返さない関数 (:ctype:`void` を返す関数) に対応する Python の 関数は ``None`` を返さねばなりません。関数に -``None`` を返させるには、以下のような慣用句を使います (この慣用句 は :cmacro:`Py_RETURN_NONE` マクロに実装されています):: +何ら有用な値を返さない関数 (:c:type:`void` を返す関数) に対応する Python の 関数は ``None`` を返さねばなりません。関数に +``None`` を返させるには、以下のような慣用句を使います (この慣用句 は :c:macro:`Py_RETURN_NONE` マクロに実装されています):: Py_INCREF(Py_None); return Py_None; -:cdata:`Py_None` は特殊な Pyhton オブジェクトである ``None`` に対応する C +:c:data:`Py_None` は特殊な Pyhton オブジェクトである ``None`` に対応する C での名前です。これまで見てきたようにほとんどのコンテキストで "エラー" を意 味する *NULL* ポインタとは違い、 ``None`` は純粋な Python のオブジェクトです。 @@ -222,7 +222,7 @@ モジュールのメソッドテーブルと初期化関数 ======================================== -さて、前に約束したように、 :cfunc:`spam_system` Python プログラム +さて、前に約束したように、 :c:func:`spam_system` Python プログラム からどうやって呼び出すかをこれから示します。まずは、関数名とアドレスを "メ ソッドテーブル (method table)" に列挙する必要があります:: static PyMethodDef SpamMethods[] = { @@ -235,18 +235,18 @@ リスト要素の三つ目のエントリ (``METH_VARARGS``) に注意してください。このエ ントリは、C 関数が使う呼び出し規約をインタプリタに教えるための フラグです。通常この値は ``METH_VARARGS`` か ``METH_VARARGS | METH_KEYWORDS`` のはずです; ``0`` -は旧式の :cfunc:`PyArg_ParseTuple` の変化形が使われることを意味します。 - -``METH_VARARGS`` だけを使う場合、C 関数は、Python レベルでの引数 が :cfunc:`PyArg_ParseTuple` +は旧式の :c:func:`PyArg_ParseTuple` の変化形が使われることを意味します。 + +``METH_VARARGS`` だけを使う場合、C 関数は、Python レベルでの引数 が :c:func:`PyArg_ParseTuple` が受理できるタプルの形式で渡されるものと想定しなければなりません; この関数 についての詳細は下で説明します。 関数にキーワード引数が渡されることになっているのなら、第三フィールド に :const:`METH_KEYWORDS` ビットをセットできます。この場合、C 関数は第三引数に ``PyObject *`` を受理するようにせねばなりません。このオブ ジェクトは、キーワード引数の辞書に -なります。こうした関数で引数を解釈するに は、 :cfunc:`PyArg_ParseTupleAndKeywords` を使ってください。 +なります。こうした関数で引数を解釈するに は、 :c:func:`PyArg_ParseTupleAndKeywords` を使ってください。 メソッドテーブルは、モジュールの初期化関数内でインタプリタに渡さねばなりま せん。 初期化関数はモジュールの名前を *name* としたときに -:cfunc:`initname` という名前でなければならず、 +:c:func:`initname` という名前でなければならず、 モジュールファイル内で定義されているもののうち、唯一の非 `static` 要素でなければなりません:: @@ -259,19 +259,19 @@ PyMODINIT_FUNC は関数の戻り値を ``void`` になるように宣言し、プラットフォー ム毎に必要とされる、特有のリンク宣言 (linkage declaration) を定義すること、さらに C++ の場合には関数を ``extern "C"`` に 宣言することに注意してください。 -Python プログラムがモジュール :mod:`spam` を初めて import すると き、 :cfunc:`initspam` が呼び出されます。 -(Python の埋め込みに関するコメントは下記を参照してください。 ) :cfunc:`initspam` は :cfunc:`Py_InitModule` +Python プログラムがモジュール :mod:`spam` を初めて import すると き、 :c:func:`initspam` が呼び出されます。 +(Python の埋め込みに関するコメントは下記を参照してください。 ) :c:func:`initspam` は :c:func:`Py_InitModule` を呼び出して "モジュールオブジェクト" を生成し (オブジェクトは ``"spam"`` をキーとして辞書 ``sys.modules`` -に挿入されます)、第二引数として与えたメソッドテーブル (:ctype:`PyMethodDef` 構造体の配列) の情報に -基づいて、組み込み関数オブジェクトを新たなモジュールに挿入していきま す。 :cfunc:`Py_InitModule` は、自らが生成した +に挿入されます)、第二引数として与えたメソッドテーブル (:c:type:`PyMethodDef` 構造体の配列) の情報に +基づいて、組み込み関数オブジェクトを新たなモジュールに挿入していきま す。 :c:func:`Py_InitModule` は、自らが生成した (この段階ではまだ未使用の) モジュールオブジェクトへのポインタを返します。 -:cfunc:`Py_InitModule` +:c:func:`Py_InitModule` は、幾つかのエラーでは致命的エラーで abort し、それ以外のモジュールが満足に 初期化できなかった場合は *NULL* を返します。 -Python を埋め込む場合には、 :cdata:`_PyImport_Inittab` テーブルのエントリ内 に :cfunc:`initspam` -がない限り、 :cfunc:`initspam` は自動的には呼び出されません。この問題を解決 する最も簡単な方法は、 :cfunc:`Py_Initialize` -や :cfunc:`PyMac_Initialize` を呼び出した後に :cfunc:`initspam` を直接呼び 出し、 +Python を埋め込む場合には、 :c:data:`_PyImport_Inittab` テーブルのエントリ 内に :c:func:`initspam` +がない限り、 :c:func:`initspam` は自動的には呼び出されません。この問題を解 決する最も簡単な方法は、 :c:func:`Py_Initialize` +や :c:func:`PyMac_Initialize` を呼び出した後に :c:func:`initspam` を直接呼 び出し、 静的にリンクしておいたモジュールを静的に初期化してしまうというものです:: int @@ -290,11 +290,11 @@ .. note:: - 単一のプロセス内 (または :cfunc:`fork` 後の :cfunc:`exec` が介入していな い状態) における複数のインタプリタにおいて、 + 単一のプロセス内 (または :c:func:`fork` 後の :c:func:`exec` が介入してい ない状態) における複数のインタプリタにおいて、 ``sys.module`` からエントリを除去したり新たなコンパイル済みモジュールを import したりすると、拡張モジュールによっては問題を生じることがあります。拡張モ ジュールの作者は、内部データ構造を初期化する際にはよくよく 用心すべきです。また、 :func:`reload` 関数を拡張モジュールに対して利用で き、この場合はモジュール初期化関数 - (:cfunc:`initspam`) は呼び出されますが、モジュールが動的にロード可能なオ ブジェクトファイル (Unixでは + (:c:func:`initspam`) は呼び出されますが、モジュールが動的にロード可能な オブジェクトファイル (Unixでは :file:`.so` 、Windows では :file:`.dll`) から読み出された場合にはモジ ュールファイルを再読み込みしないので注意してください。 より実質的なモジュール例は、Python ソース配布物 に :file:`Modules/xxmodule.c` という名前で入っています。 @@ -349,7 +349,7 @@ Python 関数の呼び出しは簡単です。まず、C のコードに対してコールバックを登録 しようとする Python プログラムは、何らかの方法で Python の関数オブジェクトを渡さねばなりません。このために、コールバック登録関数 (またはその他のインタフェース) を提供 せねばなりません。このコールバック登録関数が呼び出された際に、引き渡された Python 関数オブジェクトへのポインタをグローバル変数に --- -あるいは、どこか適切な場所に --- 保存します (関数オブジェクト を :cfunc:`Py_INCREF` するようよく注意して +あるいは、どこか適切な場所に --- 保存します (関数オブジェクト を :c:func:`Py_INCREF` するようよく注意して ください!)。例えば、以下のような関数がモジュールの一部になっていることでし ょう:: static PyObject *my_callback = NULL; @@ -377,19 +377,19 @@ この関数は :const:`METH_VARARGS` フラグを使ってインタプリタに登録せねばなり ません; :const:`METH_VARARGS` フラグについては、 :ref:`methodtable` で説明しています。 -:cfunc:`PyArg_ParseTuple` 関数とその引数については、 :ref:`parsetuple` に記 述しています。 - -:cfunc:`Py_XINCREF` および :cfunc:`Py_XDECREF` は、オブジェクトに対する参照 カウントをインクリメント/デクリメントする +:c:func:`PyArg_ParseTuple` 関数とその引数については、 :ref:`parsetuple` に 記述しています。 + +:c:func:`Py_XINCREF` および :c:func:`Py_XDECREF` は、オブジェクトに対する参 照カウントをインクリメント/デクリメントする ためのマクロで、 *NULL* ポインタが渡されても安全に操作できる形式です (とは いえ、上の流れでは *temp* が *NULL* になることはありません)。 これらのマクロと参照カウントについては、 :ref:`refcounts` で説明していま す。 .. index:: single: PyObject_CallObject() -その後、コールバック関数を呼び出す時が来たら、C 関 数 :cfunc:`PyObject_CallObject` を呼び出します。この関数には二つの引数: +その後、コールバック関数を呼び出す時が来たら、C 関 数 :c:func:`PyObject_CallObject` を呼び出します。この関数には二つの引数: Python 関数と Python 関数の引数リストがあり、いずれも任意の Python オブジェ クトを表すポインタ型です。 引数リストは常にタプルオブジェクトでなければならず、その長さは引数の数にな ります。Python 関数を引数なしで呼び出すのなら、 NULL か空のタプルを渡します; -単一の引数で関数を呼び出すのなら、単要素 (singleton) のタプルを渡しま す。 :cfunc:`Py_BuildValue` +単一の引数で関数を呼び出すのなら、単要素 (singleton) のタプルを渡しま す。 :c:func:`Py_BuildValue` の書式化文字列中に、ゼロ個または一個以上の書式化コードが入った丸括弧がある 場合、この関数はタプルを返します。以下に例を示します:: int arg; @@ -403,21 +403,21 @@ result = PyObject_CallObject(my_callback, arglist); Py_DECREF(arglist); -:cfunc:`PyObject_CallObject` は Python オブジェクトへのポインタを返します; これは Python -関数からの戻り値になります。 :cfunc:`PyObject_CallObject` は、引数に対し て "参照カウント中立 (reference-count- -neutral)" です。上の例ではタプルを生成して引数リストとして提供しており、こ のタプルは呼び出し直後に :cfunc:`Py_DECREF` +:c:func:`PyObject_CallObject` は Python オブジェクトへのポインタを返しま す; これは Python +関数からの戻り値になります。 :c:func:`PyObject_CallObject` は、引数に対し て "参照カウント中立 (reference-count- +neutral)" です。上の例ではタプルを生成して引数リストとして提供しており、こ のタプルは呼び出し直後に :c:func:`Py_DECREF` しています。 -:cfunc:`PyObject_CallObject` は戻り値として "新しい" オブジェクト: 新規に作 成されたオブジェクトか、既存のオブジェクトの +:c:func:`PyObject_CallObject` は戻り値として "新しい" オブジェクト: 新規に 作成されたオブジェクトか、既存のオブジェクトの 参照カウントをインクリメントしたものを返します。 従って、このオブジェクトをグローバル変数に保存したいのでないかぎり、たとえ この戻り値に興味がなくても -(むしろ、そうであればなおさら!) 何がしかの方法で戻り値オブジェクト を :cfunc:`Py_DECREF` しなければなりません。 - -とはいえ、戻り値を :cfunc:`Py_DECREF` する前には、値が *NULL* でないかチェ ックしておくことが重要です。もし -*NULL* なら、呼び出した Python 関数は例外を送出して終了させられていま す。 :cfunc:`PyObject_CallObject` +(むしろ、そうであればなおさら!) 何がしかの方法で戻り値オブジェクト を :c:func:`Py_DECREF` しなければなりません。 + +とはいえ、戻り値を :c:func:`Py_DECREF` する前には、値が *NULL* でないかチェ ックしておくことが重要です。もし +*NULL* なら、呼び出した Python 関数は例外を送出して終了させられていま す。 :c:func:`PyObject_CallObject` を呼び出しているコード自体もまた Python から呼び出されているのであれば、今 度は C コードが自分を呼び出している Python コードにエラー標示値を返さねばなりません。それにより、インタプリタはスタッ クトレースを出力したり、例外を処理するための Python -コードを呼び出したりできます。例外の送出が不可能だったり、したくないのな ら、 :cfunc:`PyErr_Clear` +コードを呼び出したりできます。例外の送出が不可能だったり、したくないのな ら、 :c:func:`PyErr_Clear` を呼んで例外を消去しておかねばなりません。例えば以下のようにします:: if (result == NULL) @@ -425,9 +425,9 @@ ...use result... Py_DECREF(result); -Python コールバック関数をどんなインタフェースにしたいかによっては、引数リス トを :cfunc:`PyObject_CallObject` に与えなければ +Python コールバック関数をどんなインタフェースにしたいかによっては、引数リス トを :c:func:`PyObject_CallObject` に与えなければ ならない場合もあります。あるケースでは、コールバック関数を指定したのと同じ インタフェースを介して、引数リストも渡されているかもしれません。 -また別のケースでは、新しいタプルを構築して引数リストを渡さねばならないかも しれません。この場合最も簡単なのは :cfunc:`Py_BuildValue` +また別のケースでは、新しいタプルを構築して引数リストを渡さねばならないかも しれません。この場合最も簡単なのは :c:func:`Py_BuildValue` を呼ぶやり方です。例えば、整数のイベントコードを渡したければ、以下のような コードを使うことになるでしょう:: PyObject *arglist; @@ -441,11 +441,11 @@ Py_DECREF(result); ``Py_DECREF(arglist)`` が呼び出しの直後、エラーチェックよりも前に置かれてい ることに注意してください! また、厳密に言えば、このコードは -完全ではありません: :cfunc:`Py_BuildValue` はメモリ不足におちいるかもしれ ず、チェックしておくべきです。 - -通常の引数とキーワード引数をサポートする :cfunc:`PyObject_Call` を使って、 +完全ではありません: :c:func:`Py_BuildValue` はメモリ不足におちいるかもしれ ず、チェックしておくべきです。 + +通常の引数とキーワード引数をサポートする :c:func:`PyObject_Call` を使って、 キーワード引数を伴う関数呼び出しをすることができます。 -上の例と同じように、 :cfunc:`Py_BuildValue` を作って辞書を作ります。 :: +上の例と同じように、 :c:func:`Py_BuildValue` を作って辞書を作ります。 :: PyObject *dict; ... @@ -465,7 +465,7 @@ .. index:: single: PyArg_ParseTuple() -:cfunc:`PyArg_ParseTuple` は、以下のように宣言されています:: +:c:func:`PyArg_ParseTuple` は、以下のように宣言されています:: int PyArg_ParseTuple(PyObject *arg, char *format, ...); @@ -474,8 +474,8 @@ Python/C API リファレンスマニュアルの :ref:`arg-parsing` で解説されている書 法に従わねばなりません。 残りの引数は、それぞれの変数のアドレスで、書式化文字列から決まる型になって いなければなりません。 -:cfunc:`PyArg_ParseTuple` は Python 側から与えられた引数が -必要な型になっているか調べるのに対し、 :cfunc:`PyArg_ParseTuple` は呼び出 しの際に渡された C 変数のアドレスが有効な値を持つか調べ +:c:func:`PyArg_ParseTuple` は Python 側から与えられた引数が +必要な型になっているか調べるのに対し、 :c:func:`PyArg_ParseTuple` は呼び出 しの際に渡された C 変数のアドレスが有効な値を持つか調べ られないことに注意してください: ここで間違いを犯すと、コードがクラッシュす るかもしれませんし、少なくともでたらめなビットを メモリに上書きしてしまいます。慎重に! @@ -552,17 +552,17 @@ .. index:: single: PyArg_ParseTupleAndKeywords() -:cfunc:`PyArg_ParseTupleAndKeywords` は、以下のように宣言されています:: +:c:func:`PyArg_ParseTupleAndKeywords` は、以下のように宣言されています:: int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict, char *format, char *kwlist[], ...); -*arg* と *format* パラメタは :cfunc:`PyArg_ParseTuple` のものと同じです。 *kwdict* +*arg* と *format* パラメタは :c:func:`PyArg_ParseTuple` のものと同じで す。 *kwdict* パラメタはキーワード引数の入った辞書で、 Python ランタイムシステムから第三 パラメタとして受け取ります。 *kwlist* パラメタは各パラメタを識別するための文字列からなる、 *NULL* 終端されたリス トです; 各パラメタ名は *format* 中の 型情報に対して左から右の順に照合されます。 -成功すると :cfunc:`PyArg_ParseTupleAndKeywords` は真を返し、それ以外の場合 には適切な例外を送出して偽を返します。 +成功すると :c:func:`PyArg_ParseTupleAndKeywords` は真を返し、それ以外の場合 には適切な例外を送出して偽を返します。 .. note:: @@ -624,18 +624,18 @@ 任意の値を構築する ================== -:cfunc:`Py_BuildValue` は :cfunc:`PyArg_ParseTuple` の +:c:func:`Py_BuildValue` は :c:func:`PyArg_ParseTuple` の 対極に位置するものです。この関数は以下のように定義されています:: PyObject *Py_BuildValue(char *format, ...); -:cfunc:`Py_BuildValue` は、 :cfunc:`PyArg_ParseTuple` +:c:func:`Py_BuildValue` は、 :c:func:`PyArg_ParseTuple` の認識する一連の書式化単位に似た書式化単位を認識します。ただし (関数への出 力ではなく、入力に使われる) 引数はポインタではなく、 ただの値でなければなりません。 Python から呼び出された C 関数が返す値として 適切な、新たな Python オブジェクトを返します。 -:cfunc:`PyArg_ParseTuple` とは一つ違う点がありま す: :cfunc:`PyArg_ParseTuple` +:c:func:`PyArg_ParseTuple` とは一つ違う点がありま す: :c:func:`PyArg_ParseTuple` は第一引数をタプルにする必要があります (Python の引数リストは内部的には常に タプルとして表現されるからです) -が、 :cfunc:`Py_BuildValue` はタプルを生成するとは限りませ ん。 :cfunc:`Py_BuildValue` +が、 :c:func:`Py_BuildValue` はタプルを生成するとは限りませ ん。 :c:func:`Py_BuildValue` は書式化文字列中に書式化単位が二つかそれ以上入っている場合にのみタプルを構 築します。書式化文字列が空なら、 ``None`` を返します。きっかり一つの 書式化単位なら、その書式化単位が記述している何らかのオブジェクトになりま す。サイズが 0 や 1 のタプル返させたいのなら、書式化文字列を丸括弧で囲いま す。 @@ -664,14 +664,14 @@ ============== C や C++のような言語では、プログラマはヒープ上のメモリを動的に確保したり解 放したりする責任があります。こうした作業は C -では関数 :cfunc:`malloc` や :cfunc:`free` で行います。C++では本質的に同じ意 味で演算子 ``new`` や +では関数 :c:func:`malloc` や :c:func:`free` で行います。C++では本質的に同じ 意味で演算子 ``new`` や ``delete`` が使われます。そこで、以下の議論は C の場合に限定して行います。 -:cfunc:`malloc` が確保する全てのメモリブロックは、最終的には :cfunc:`free` を厳密に一度だけ呼び出して利用可能メモリのプールに -戻さねばなりません。そこで、適切な時に :cfunc:`free` を呼び出すことが重要に なります。あるメモリブロックに対して、 :cfunc:`free` +:c:func:`malloc` が確保する全てのメモリブロックは、最終的に は :c:func:`free` を厳密に一度だけ呼び出して利用可能メモリのプールに +戻さねばなりません。そこで、適切な時に :c:func:`free` を呼び出すことが重要 になります。あるメモリブロックに対して、 :c:func:`free` を呼ばなかったにもかかわらずそのアドレスを忘却してしまうと、ブロックが占有 しているメモリはプログラムが終了するまで再利用できなくなります。 -これはメモリリーク(:dfn:`memory leak`) と呼ばれています。逆に、プログラムが あるメモリブロックに対して :cfunc:`free` を -呼んでおきながら、そのブロックを使い続けようとすると、別の :cfunc:`malloc` 呼び出しによって行われるブロックの再利用 +これはメモリリーク(:dfn:`memory leak`) と呼ばれています。逆に、プログラムが あるメモリブロックに対して :c:func:`free` を +呼んでおきながら、そのブロックを使い続けようとすると、別 の :c:func:`malloc` 呼び出しによって行われるブロックの再利用 と衝突を起こします。これは解放済みメモリの使用 (:dfn:`using freed memory`) と呼ばれます。これは初期化されていないデータに対する参照と同様のよくない結 果 --- コアダンプ、誤った参照、不可解なクラッシュ --- を引き起こします。 @@ -683,7 +683,7 @@ メモリリークが明らかになるのは、長い間動作していたプロセスがリークを起こす 関数を何度も使った場合に限られるからです。 従って、この種のエラーを最小限にとどめるようなコーディング規約や戦略を設け て、不慮のメモリリークを避けることが重要なのです。 -Python は :cfunc:`malloc` や :cfunc:`free` を非常によく利用するため、メモリ リークの防止に加え、解放されたメモリの使用を +Python は :c:func:`malloc` や :c:func:`free` を非常によく利用するため、メモ リリークの防止に加え、解放されたメモリの使用を 防止する戦略が必要です。このために選ばれたのが参照カウント法 (:dfn:`reference counting`) と呼ばれる手法です。 参照カウント法の原理は簡単です: 全てのオブジェクトにはカウンタがあり、オブ ジェクトに対する参照がどこかに保存されたら カウンタをインクリメントし、オブジェクトに対する参照が削除されたらデクリメ ントします。カウンタがゼロになったら、オブジェクトへの @@ -691,10 +691,10 @@ もう一つの戦略は自動ガベージコレクション (:dfn:`automatic garbage collection`) と呼ばれています。 (参照カウント法はガベージコレクション戦略の一つとして挙げられることもあるの で、二つを区別するために筆者は "自動 (automatic)" -を使っています。) 自動ガベージコレクションの大きな利点は、ユーザ が :cfunc:`free` を明示的によばなくてよいことにあります。 +を使っています。) 自動ガベージコレクションの大きな利点は、ユーザ が :c:func:`free` を明示的によばなくてよいことにあります。 (速度やメモリの有効利用性も利点として主張されています --- が、これは確たる 事実ではありません。) C における自動ガベージコレクションの欠点は、真に可搬性のあるガベージコレクタ が存在しないということです。それに対し、参照カウント法は可搬性のある実装がで きます -(:cfunc:`malloc` や :cfunc:`free` を利用できるのが前提です --- C 標準はこ れを保証しています)。 +(:c:func:`malloc` や :c:func:`free` を利用できるのが前提です --- C 標準は これを保証しています)。 いつの日か、十分可搬性のあるガベージコレクタが C で使えるようになるかもしれ ませんが、それまでは参照カウント法でやっていく以外にはないのです。 Python では、伝統的な参照カウント法の実装を行っている一方で、参照の循環を検 出するために働く循環参照検出機構 (cycle detector) @@ -722,18 +722,18 @@ ----------------------------- Python には、参照カウントのインクリメントやデクリメントを処理する二つのマク ロ、 ``Py_INCREF(x)`` と ``Py_DECREF(x)`` -があります。 :cfunc:`Py_DECREF` は、参照カウントがゼロに到達した際に、オブ ジェクトのメモリ解放も行います。 -柔軟性を持たせるために、 :cfunc:`free` を直接呼び出しません --- その代わり にオブジェクトの型オブジェクト (:dfn:`type +があります。 :c:func:`Py_DECREF` は、参照カウントがゼロに到達した際に、オブ ジェクトのメモリ解放も行います。 +柔軟性を持たせるために、 :c:func:`free` を直接呼び出しません --- その代わ りにオブジェクトの型オブジェクト (:dfn:`type object`) を介します。このために (他の目的もありますが)、全てのオブジェクト には自身の型オブジェクトに対するポインタが入っています。 さて、まだ重大な疑問が残っています: いつ ``Py_INCREF(x)`` や ``Py_DECREF(x)`` を使えばよいのでしょうか? まず、いくつかの用語説明から始めさせてください。まず、オブジェクトは "占有 (own)" されることはありません; しかし、あるオブジェクトに対する参照の所有 :dfn:`own a reference` はできま す。オブジェクトの参照カウントは、そのオブジェクトが -参照を所有を受けている回数と定義されています。参照の所有者は、参照が必要な くなった際に :cfunc:`Py_DECREF` +参照を所有を受けている回数と定義されています。参照の所有者は、参照が必要な くなった際に :c:func:`Py_DECREF` を呼び出す役割を担います。参照の所有権は委譲 (transfer) できます。所有参照 (owned reference) の放棄には、渡す、保存する、 -:cfunc:`Py_DECREF` を呼び出す、という三つの方法があります。所有参照を処理し 忘れると、メモリリークを引き起こします。 - -オブジェクトに対する参照は、借用 (:dfn:`borrow`) も可能です。 [#]_ 参照の 借用者は、 :cfunc:`Py_DECREF` +:c:func:`Py_DECREF` を呼び出す、という三つの方法があります。所有参照を処理 し忘れると、メモリリークを引き起こします。 + +オブジェクトに対する参照は、借用 (:dfn:`borrow`) も可能です。 [#]_ 参照の 借用者は、 :c:func:`Py_DECREF` を呼んではなりません。借用者は、参照の所有者から借用した期間を超えて参照を 保持し続けてはなりません。所有者が参照を放棄した後で借用参照を使うと、 解放済みメモリを使用してしまう危険があるので、絶対に避けねばなりません。 [#]_ @@ -742,8 +742,8 @@ 逆に、所有よりも不利な点は、ごくまともに見えるコードが、実際には参照の借用 元で放棄されてしまった後に その参照を使うかもしれないような微妙な状況があるということです。 -:cfunc:`Py_INCREF` を呼び出すと、借用参照を所有参照 に変更できます。この操 作は参照の借用元の状態には影響しません --- -:cfunc:`Py_INCREF` は新たな所有参照を生成し、参照の所有者が担うべき全ての責 任を課します (つまり、新たな参照の所有者は、以前の +:c:func:`Py_INCREF` を呼び出すと、借用参照を所有参照 に変更できます。この 操作は参照の借用元の状態には影響しません --- +:c:func:`Py_INCREF` は新たな所有参照を生成し、参照の所有者が担うべき全ての 責任を課します (つまり、新たな参照の所有者は、以前の 所有者と同様、参照の放棄を適切に行わねばなりません)。 @@ -754,28 +754,28 @@ オブジェクトへの参照を関数の内外に渡す場合には、オブジェクトの所有権が参照 と共に渡されるか否かが常に関数インタフェース仕様の一部となります。 -オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も渡します。 特に、 :cfunc:`PyInt_FromLong` や -:cfunc:`Py_BuildValue` のように、新しいオブジェクトを生成する関数は全て所有 権を相手に渡します。オブジェクトが実際には新たな -オブジェクトでなくても、そのオブジェクトに対する新たな参照の所有権を得ま す。例えば、 :cfunc:`PyInt_FromLong` +オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も渡します。 特に、 :c:func:`PyInt_FromLong` や +:c:func:`Py_BuildValue` のように、新しいオブジェクトを生成する関数は全て所 有権を相手に渡します。オブジェクトが実際には新たな +オブジェクトでなくても、そのオブジェクトに対する新たな参照の所有権を得ま す。例えば、 :c:func:`PyInt_FromLong` はよく使う値をキャッシュしており、キャッシュされた値への参照を返すことがあ ります。 -:cfunc:`PyObject_GetAttrString` のように、あるオブジェクトから別のオブジェ クトを抽出するような関数もまた、参照とともに所有権を +:c:func:`PyObject_GetAttrString` のように、あるオブジェクトから別のオブジェ クトを抽出するような関数もまた、参照とともに所有権を 委譲します。こちらの方はやや理解しにくいかもしれません。というのはよく使わ れるルーチンのいくつかが例外となっているからです: -:cfunc:`PyTuple_GetItem` 、 :cfunc:`PyList_GetItem` 、 :cfunc:`PyDict_GetItem` 、 お よび -:cfunc:`PyDict_GetItemString` は全て、タプル、リスト、または辞書から借用参 照を返します。 - -:cfunc:`PyImport_AddModule` は、実際にはオブジェクトを生成して返すことがあ るにもかかわらず、借用参照を返します: +:c:func:`PyTuple_GetItem` 、 :c:func:`PyList_GetItem` 、 :c:func:`PyDict_GetItem` 、 お よび +:c:func:`PyDict_GetItemString` は全て、タプル、リスト、または辞書から借用参 照を返します。 + +:c:func:`PyImport_AddModule` は、実際にはオブジェクトを生成して返すことがあ るにもかかわらず、借用参照を返します: これが可能なのは、生成されたオブジェクトに対する所有参照は ``sys.modules`` に保持されるからです。 オブジェクトへの参照を別の関数に渡す場合、一般的には、関数側は呼び出し手か ら参照を借用します --- 参照を保存する必要があるなら、 -関数側は :cfunc:`Py_INCREF` を呼び出して独立した所有者になります。とはい え、この規則には二つの重要な例外: -:cfunc:`PyTuple_SetItem` と :cfunc:`PyList_SetItem` があります。これらの関 数は、渡された引数要素に対して所有権を -乗っ取り (take over) ます --- たとえ失敗してもです! (:cfunc:`PyDict_SetItem` とその仲間は所有権を乗っ取りません +関数側は :c:func:`Py_INCREF` を呼び出して独立した所有者になります。とはい え、この規則には二つの重要な例外: +:c:func:`PyTuple_SetItem` と :c:func:`PyList_SetItem` があります。これらの 関数は、渡された引数要素に対して所有権を +乗っ取り (take over) ます --- たとえ失敗してもです! (:c:func:`PyDict_SetItem` とその仲間は所有権を乗っ取りません --- これらはいわば "普通の" 関数です。) Python から C 関数が呼び出される際には、C 関数は呼び出し側から引数への参照 を借用します。C 関数の呼び出し側はオブジェクトへの参照を 所有しているので、借用参照の生存期間が保証されるのは関数が処理を返すまでで す。このようにして借用参照を保存したり他に渡したりしたい -場合にのみ、 :cfunc:`Py_INCREF` を使って所有参照にする必要があります。 +場合にのみ、 :c:func:`Py_INCREF` を使って所有参照にする必要があります。 Python から呼び出された C 関数が返す参照は所有参照でなければなりません --- 所有権は関数から呼び出し側へと委譲されます。 @@ -789,7 +789,7 @@ インタプリタが参照の所有者に参照を放棄させてしまう状況と関係しています。 知っておくべきケースのうち最初の、そして最も重要なものは、リスト要素に対す る参照を借りている際に起きる、 -関係ないオブジェクトに対する :cfunc:`Py_DECREF` の使用です。例えば:: +関係ないオブジェクトに対する :c:func:`Py_DECREF` の使用です。例えば:: void bug(PyObject *list) @@ -803,13 +803,13 @@ 上の関数はまず、 ``list[0]`` への参照を借用し、次に ``list[1]`` を値 ``0`` で置き換え、最後にさきほど借用した参照を出力 しています。何も問題ないように見えますね? でもそうではないのです! -:cfunc:`PyList_SetItem` の処理の流れを追跡してみましょう。リストは全ての要 素に対して参照を所有しているので、要素 1 を +:c:func:`PyList_SetItem` の処理の流れを追跡してみましょう。リストは全ての要 素に対して参照を所有しているので、要素 1 を 置き換えると、以前の要素 1 を放棄します。ここで、以前の要素 1 がユーザ定義 クラスのインスタンスであり、さらにこのクラスが :meth:`__del__` メソッドを定義していると仮定しましょう。このクラスインスタンスの参照カウン トが 1 だった場合、リストが参照を放棄すると、インスタンスの :meth:`__del__` メソッドが呼び出されます。 クラスは Python で書かれているので、 :meth:`__del__` は任意の Python コード を実行できます。この :meth:`__del__` -が :cfunc:`bug` における ``item`` に何か不正なことをしているのでしょうか? その通り! :cfunc:`buf` に渡したリストが +が :c:func:`bug` における ``item`` に何か不正なことをしているのでしょうか? その通り! :c:func:`buf` に渡したリストが :meth:`__del__` メソッドから操作できるとすると、 ``del list[0]`` の効果を持 つような文を実行できてしまいます。もしこの操作で ``list[0]`` に対する最後の参照が放棄されてしまうと、 `` list[0]`` に関連付 けられていたメモリは解放され、結果的に `` item`` は無効な値になってしまいます。 @@ -832,7 +832,7 @@ 二つ目は、借用参照がスレッドに関係しているケースです。通常は、 Python イン タプリタにおける複数のスレッドは、 グローバルインタプリタロックがオブジェクト空間全体を保護しているため、互い に邪魔し合うことはありません。とはいえ、ロックは -:cmacro:`Py_BEGIN_ALLOW_THREADS` マクロで一時的に解除した り、 :cmacro:`Py_END_ALLOW_THREADS` +:c:macro:`Py_BEGIN_ALLOW_THREADS` マクロで一時的に解除した り、 :c:macro:`Py_END_ALLOW_THREADS` で再獲得したりできます。これらのマクロはブロックの起こる I/O 呼び出しの周囲 によく置かれ、 I/O が完了するまでの間に他のスレッドがプロセッサを利用できるようにします。明ら かに、以下の関数は上の例と似た問題をはらんでいます:: @@ -858,10 +858,10 @@ *NULL* テストを行えば、冗長なテストが大量に行われ、コードはより低速に動くこ とになります。 従って、 *NULL* のテストはオブジェクトの "発生源"、すなわち値が *NULL* にな るかもしれないポインタを受け取ったときだけに -しましょう。 :cfunc:`malloc` や、例外を送出する可能性のある関数がその例で す。 - -マクロ :cfunc:`Py_INCREF` および :cfunc:`Py_DECREF` は *NULL* ポインタのチ ェックを行いません --- -しかし、これらのマクロの変化形である :cfunc:`Py_XINCREF` およ び :cfunc:`Py_XDECREF` はチェックを行います。 +しましょう。 :c:func:`malloc` や、例外を送出する可能性のある関数がその例で す。 + +マクロ :c:func:`Py_INCREF` および :c:func:`Py_DECREF` は *NULL* ポインタの チェックを行いません --- +しかし、これらのマクロの変化形である :c:func:`Py_XINCREF` およ び :c:func:`Py_XDECREF` はチェックを行います。 特定のオブジェクト型について調べるマクロ (``Pytype_Check()``) は *NULL* ポ インタのチェックを行いません --- 繰り返しますが、 様々な異なる型を想定してオブジェクトの型を調べる際には、こうしたマクロを続 けて呼び出す必要があるので、個別に *NULL* ポインタの @@ -916,7 +916,7 @@ 名前が衝突するのを避けるためです。また、他の拡張モジュールからアクセスを *受けるべきではない* シンボルは別のやり方で公開せねばなりません。 Python はある拡張モジュールの C レベルの情報 (ポインタ) を別のモジュールに 渡すための特殊な機構: CObject を提供しています。 -CObject はポインタ (:ctype:`void\*`) を記憶する Python のデータ型です。 CObject は C API +CObject はポインタ (:c:type:`void\*`) を記憶する Python のデータ型です。 CObject は C API を介してのみ生成したりアクセスしたりできますが、他の Python オブジェクトと 同じように受け渡しできます。とりわけ、CObject は拡張モジュールの名前空間内にある名前に代入できます。他の拡張モジュールは このモジュールを import でき、次に名前を取得し、最後にCObject へのポインタを取得します。 @@ -926,16 +926,16 @@ そして、ポインタに対する保存や取得といった様々な作業は、コードを提供してい るモジュールとクライアントモジュールとの間では異なる方法で分散できます。 以下の例では、名前を公開するモジュールの作者にほとんどの負荷が掛かります が、よく使われるライブラリを作る際に適切なアプローチを実演します。 -このアプローチでは、全ての C API ポインタ (例中では一つだけですが!) を、 CObject の値となる :ctype:`void` +このアプローチでは、全ての C API ポインタ (例中では一つだけですが!) を、 CObject の値となる :c:type:`void` ポインタの配列に保存します。拡張モジュールに対応するヘッダファイルは、モジ ュールの import と C API ポインタを取得するよう手配するマクロを提供します; クライアントモジュール は、C API にアクセスする前にこのマクロを呼ぶだけです。 名前を公開する側のモジュールは、 :ref:`extending-simpleexample` 節 の :mod:`spam` -モジュールを修正したものです。関数 :func:`spam.system` は C ライブラリ関 数 :cfunc:`system` を直接呼び出さず、 -:cfunc:`PySpam_System` を呼び出します。この関数はもちろん、実際には (全ての コマンドに "spam" を付けるといったような) -より込み入った処理を行います。この関数 :cfunc:`PySpam_System` はまた、他の 拡張モジュールにも公開されます。 - -関数 :cfunc:`PySpam_System` は、他の全ての関数と同様に ``static`` で宣言さ れた通常の C 関数です。 :: +モジュールを修正したものです。関数 :func:`spam.system` は C ライブラリ関 数 :c:func:`system` を直接呼び出さず、 +:c:func:`PySpam_System` を呼び出します。この関数はもちろん、実際には (全て のコマンドに "spam" を付けるといったような) +より込み入った処理を行います。この関数 :c:func:`PySpam_System` はまた、他の 拡張モジュールにも公開されます。 + +関数 :c:func:`PySpam_System` は、他の全ての関数と同様に ``static`` で宣言さ れた通常の C 関数です。 :: static int PySpam_System(const char *command) @@ -943,7 +943,7 @@ return system(command); } -:cfunc:`spam_system` には取るに足らない変更が施されています:: +:c:func:`spam_system` には取るに足らない変更が施されています:: static PyObject * spam_system(PyObject *self, PyObject *args) @@ -1053,8 +1053,8 @@ #endif /* !defined(Py_SPAMMODULE_H) */ -:cfunc:`PySpam_System` へのアクセス手段を得るためにクライアントモジュール側 がしなければならないことは、初期化関数内 -での :cfunc:`import_spam` 関数 (またはマクロ) の呼び出しです:: +:c:func:`PySpam_System` へのアクセス手段を得るためにクライアントモジュール 側がしなければならないことは、初期化関数内 +での :c:func:`import_spam` 関数 (またはマクロ) の呼び出しです:: PyMODINIT_FUNC initclient(void) ======================================= --- /library/exceptions.rst Wed Apr 20 03:07:25 2011 +++ /library/exceptions.rst Tue May 3 06:18:14 2011 @@ -363,7 +363,7 @@ .. Raised when an operation runs out of memory but the situation may still be .. rescued (by deleting some objects). The associated value is a string indicating .. what kind of (internal) operation ran out of memory. Note that because of the - .. underlying memory management architecture (C's :cfunc:`malloc` function), the + .. underlying memory management architecture (C's :c:func:`malloc` function), the .. interpreter may not always be able to completely recover from this situation; it .. nevertheless raises an exception so that a stack traceback can be printed, in .. case a run-away program was the cause. @@ -372,7 +372,7 @@ 消去することで) まだ復旧可能かもしれない場合に送出されます。例外の 関連値は、どんな種類の (内部) 操作がメモリ不足になっているか を示す文字列です。背後にあるメモリ管理アーキテクチャ (C の - :cfunc:`malloc` 関数) によっては、インタプリタが常にその状況を完璧 + :c:func:`malloc` 関数) によっては、インタプリタが常にその状況を完璧 に復旧できるとはかぎらないので注意してください; プログラムの暴走が 原因の場合にも、やはり実行スタックの追跡結果を出力できるようにする ために例外が送出されます。 @@ -410,7 +410,7 @@ .. function returns a system-related error (not for illegal argument types or .. other incidental errors). The :attr:`errno` attribute is a numeric error .. code from :c:data:`errno`, and the :attr:`strerror` attribute is the - .. corresponding string, as would be printed by the C function :cfunc:`perror`. + .. corresponding string, as would be printed by the C function :c:func:`perror`. .. See the module :mod:`errno`, which contains names for the error codes defined .. by the underlying operating system. @@ -418,7 +418,7 @@ 関数がシステムに関連したエラーを返した場合に送出されます (引数の型が間違っている場合や、他の偶発的なエラーは除きます)。 :attr:`errno` 属性は :c:data:`errno` に基づく数字のエラーコードで、 - :attr:`strerror` 属性は C の :cfunc:`perror` 関数で表示されるような + :attr:`strerror` 属性は C の :c:func:`perror` 関数で表示されるような 文字列です。 オペレーティングシステムに依存したエラーコードの定義と名前については、 :mod:`errno` モジュールを参照して下さい。 @@ -553,14 +553,14 @@ .. This exception is raised by the :func:`sys.exit` function. When it is not .. handled, the Python interpreter exits; no stack traceback is printed. If the .. associated value is a plain integer, it specifies the system exit status (passed - .. to C's :cfunc:`exit` function); if it is ``None``, the exit status is zero; if + .. to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if .. it has another type (such as a string), the object's value is printed and the .. exit status is one. この例外は :func:`sys.exit` 関数によって送出されます。この例外が 処理されなかった場合、スタックのトレースバックを全く表示することなく Python インタプリタは終了します。関連値が通常の整数であれば、 - システム終了ステータスを表します (:cfunc:`exit` 関数に渡されます)。 + システム終了ステータスを表します (:c:func:`exit` 関数に渡されます)。 値が ``None`` の場合、終了ステータスは 0 です。 (文字列のような) 他の 型の場合、そのオブジェクトの値が表示され、終了ステータスは 1 になりま す。 @@ -696,14 +696,14 @@ .. Raised when a Windows-specific error occurs or when the error number does not .. correspond to an :c:data:`errno` value. The :attr:`winerror` and .. :attr:`strerror` values are created from the return values of the - .. :cfunc:`GetLastError` and :cfunc:`FormatMessage` functions from the Windows + .. :c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows .. Platform API. The :attr:`errno` value maps the :attr:`winerror` value to .. corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`. Windows 特有のエラーか、エラー番号が :c:data:`errno` 値に対応しない 場合に送出されます。 :attr:`winerrno` および :attr:`strerror` の値は - Windows プラットフォーム API の関数 :cfunc:`GetLastError` と - :cfunc:`FormatMessage` の戻り値から生成されます。 :attr:`errno` の + Windows プラットフォーム API の関数 :c:func:`GetLastError` と + :c:func:`FormatMessage` の戻り値から生成されます。 :attr:`errno` の 値は :attr:`winerror` の値を対応する ``errno.h`` の値にマップしたもので す。 :exc:`OSError` のサブクラスです。 @@ -711,10 +711,10 @@ .. versionadded:: 2.0 .. .. versionchanged:: 2.5 - .. .. Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`. + .. .. Previous versions put the :c:func:`GetLastError` codes into :attr:`errno`. .. versionchanged:: 2.5 - 以前のバージョンは :cfunc:`GetLastError` のコードを + 以前のバージョンは :c:func:`GetLastError` のコードを :attr:`errno` に入れていました。 ======================================= --- /library/mailbox.rst Tue May 3 04:27:57 2011 +++ /library/mailbox.rst Tue May 3 06:18:14 2011 @@ -472,7 +472,7 @@ unlock() 3種類のロック機構が使われます --- ドットロッキングと、もし使用可能な らば - :cfunc:`flock` と :cfunc:`lockf` システムコールです。 + :c:func:`flock` と :c:func:`lockf` システムコールです。 .. seealso:: @@ -585,7 +585,7 @@ unlock() 3種類のロック機構が使われます --- ドットロッキングと、もし使用可能な らば - :cfunc:`flock` と :cfunc:`lockf` システムコールです。 + :c:func:`flock` と :c:func:`lockf` システムコールです。 MH メールボックスに対するロックとは :file:`.mh_sequences` のロック と、 それが影響を与える操作中だけの個々のメッセージファイルに対するロック を意味します。 @@ -678,7 +678,7 @@ unlock() 3種類のロック機構が使われます --- ドットロッキングと、もし使用可能な らば - :cfunc:`flock` と :cfunc:`lockf` システムコールです。 + :c:func:`flock` と :c:func:`lockf` システムコールです。 .. seealso:: @@ -728,7 +728,7 @@ unlock() 3種類のロック機構が使われます --- ドットロッキングと、もし使用可能な らば - :cfunc:`flock` と :cfunc:`lockf` システムコールです。 + :c:func:`flock` と :c:func:`lockf` システムコールです。 .. seealso::
