extending.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2025, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
# Translators:
# Yusuke Miyazaki <miyazaki.dev@gmail.com>, 2021
# mollinaca, 2021
# Shin Saito, 2021
# 菊池 健志, 2023
# tomo, 2023
# 石井明久, 2024
# Arihiro TAKASE, 2024
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Python 3.13\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-03-28 14:18+0000\n"
"PO-Revision-Date: 2021-06-28 00:51+0000\n"
"Last-Translator: Arihiro TAKASE, 2024\n"
"Language-Team: Japanese (https://app.transifex.com/python-doc/teams/5390/"
"ja/)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: ja\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../extending/extending.rst:8
msgid "Extending Python with C or C++"
msgstr "C や C++ による Python の拡張"

#: ../../extending/extending.rst:10
msgid ""
"It is quite easy to add new built-in modules to Python, if you know how to "
"program in C.  Such :dfn:`extension modules` can do two things that can't be "
"done directly in Python: they can implement new built-in object types, and "
"they can call C library functions and system calls."
msgstr ""
"C プログラムの書き方を知っているなら、Python に新たな組み込みモジュールを追加"
"するのはきわめて簡単です。この新たなモジュール、拡張モジュール (:dfn:"
"`extension module`) を使うと、Python が直接行えない二つのこと: 新しい組み込み"
"オブジェクトの実装、そして全ての C ライブラリ関数とシステムコールに対する呼び"
"出し、ができるようになります。"

#: ../../extending/extending.rst:15
msgid ""
"To support extensions, the Python API (Application Programmers Interface) "
"defines a set of functions, macros and variables that provide access to most "
"aspects of the Python run-time system.  The Python API is incorporated in a "
"C source file by including the header ``\"Python.h\"``."
msgstr ""
"拡張モジュールをサポートするため、Python API (Application Programmer's "
"Interface) では一連の関数、マクロおよび変数を提供していて、Python ランタイム"
"システムのほとんどの側面へのアクセス手段を提供しています。 Python API は、"
"ヘッダ ``\"Python.h\"`` をインクルードして C ソースに取り込みます。"

#: ../../extending/extending.rst:20
msgid ""
"The compilation of an extension module depends on its intended use as well "
"as on your system setup; details are given in later chapters."
msgstr ""
"拡張モジュールのコンパイル方法は、モジュールの用途やシステムの設定方法に依存"
"します。詳細は後の章で説明します。"

#: ../../extending/extending.rst:25
msgid ""
"The C extension interface is specific to CPython, and extension modules do "
"not work on other Python implementations.  In many cases, it is possible to "
"avoid writing C extensions and preserve portability to other "
"implementations. For example, if your use case is calling C library "
"functions or system calls, you should consider using the :mod:`ctypes` "
"module or the `cffi <https://cffi.readthedocs.io/>`_ library rather than "
"writing custom C code. These modules let you write Python code to interface "
"with C code and are more portable between implementations of Python than "
"writing and compiling a C extension module."
msgstr ""
"C 拡張のインターフェイスは CPython に固有のものであり、これによる拡張モジュー"
"ルはほかの Python 実装では動作しません。多くの場合、C 拡張を書くことを避けて"
"ほかの Python 実装のために移植性を確保することは可能です。たとえば、あなたが"
"したいことが C ライブラリの関数やシステムコールを呼び出すことである場合、 :"
"mod:`ctypes` あるいは `cffi <https://cffi.readthedocs.io/>`_ ライブラリの利用"
"を検討すべきです。これらのモジュールは C コードとインターフェイスし、C 拡張を"
"書いてコンパイルするのに較べて Python 実装間のより高い移植性をもった Python "
"コードを書かせてくれます。"

#: ../../extending/extending.rst:40
msgid "A Simple Example"
msgstr "簡単な例"

#: ../../extending/extending.rst:42
msgid ""
"Let's create an extension module called ``spam`` (the favorite food of Monty "
"Python fans...) and let's say we want to create a Python interface to the C "
"library function :c:func:`system` [#]_. This function takes a null-"
"terminated character string as argument and returns an integer.  We want "
"this function to be callable from Python as follows:"
msgstr ""
"``spam`` (Monty Python ファンの好物ですね) という名の拡張モジュールを作成する"
"ことにして、C ライブラリ関数 :c:func:`system` に対する Python インターフェイ"
"スを作成したいとします。 [#]_ この関数は null で終端されたキャラクタ文字列を"
"引数にとり、整数を返します。この関数を以下のようにして Python から呼び出せる"
"ようにしたいとします。"

#: ../../extending/extending.rst:48
msgid ""
">>> import spam\n"
">>> status = spam.system(\"ls -l\")"
msgstr ""

#: ../../extending/extending.rst:53
msgid ""
"Begin by creating a file :file:`spammodule.c`.  (Historically, if a module "
"is called ``spam``, the C file containing its implementation is called :file:"
"`spammodule.c`; if the module name is very long, like ``spammify``, the "
"module name can be just :file:`spammify.c`.)"
msgstr ""
"まずは :file:`spammodule.c` を作成するところから始めます。 (伝統として、 "
"``spam`` という名前のモジュールを作成する場合、モジュールの実装が入った C "
"ファイルを :file:`spammodule.c` と呼ぶことになっています; ``spammify`` のよう"
"に長すぎるモジュール名の場合には、単に :file:`spammify.c` にもできます。)"

#: ../../extending/extending.rst:58
msgid "The first two lines of our file can be::"
msgstr "このファイルの最初の 2 行は以下のようにします::"

#: ../../extending/extending.rst:60 ../../extending/extending.rst:663
msgid ""
"#define PY_SSIZE_T_CLEAN\n"
"#include <Python.h>"
msgstr ""

#: ../../extending/extending.rst:63
msgid ""
"which pulls in the Python API (you can add a comment describing the purpose "
"of the module and a copyright notice if you like)."
msgstr ""
"これで、Python API を取り込みます (必要なら、モジュールの用途に関する説明や、"
"著作権表示を追加します)。"

#: ../../extending/extending.rst:68
msgid ""
"Since Python may define some pre-processor definitions which affect the "
"standard headers on some systems, you *must* include :file:`Python.h` before "
"any standard headers are included."
msgstr ""
"Python は、システムによっては標準ヘッダの定義に影響するようなプリプロセッサ定"
"義を行っているので、 :file:`Python.h` をいずれの標準ヘッダよりも前にインク"
"ルード *せねばなりません* 。"

#: ../../extending/extending.rst:72
msgid ""
"``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should "
"be used in some APIs instead of ``int``. It is not necessary since Python "
"3.13, but we keep it here for backward compatibility. See :ref:`arg-parsing-"
"string-and-buffers` for a description of this macro."
msgstr ""
"``#define PY_SSIZE_T_CLEAN`` は、いくつかの API では ``int`` の代わりに "
"``Py_ssize_t`` が使われるべきであることを示すために使われていました。これは "
"Python 3.13 以降では不要となりましたが、後方互換性のために維持されています。"
"このマクロの説明は :ref:`arg-parsing-string-and-buffers` にあります。"

#: ../../extending/extending.rst:77
msgid ""
"All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` "
"or ``PY``, except those defined in standard header files. For convenience, "
"and since they are used extensively by the Python interpreter, ``\"Python."
"h\"`` includes a few standard header files: ``<stdio.h>``, ``<string.h>``, "
"``<errno.h>``, and ``<stdlib.h>``.  If the latter header file does not exist "
"on your system, it declares the functions :c:func:`malloc`, :c:func:`free` "
"and :c:func:`realloc` directly."
msgstr ""
":file:`Python.h` で定義されているユーザから可視のシンボルは、全て接頭辞 "
"``Py`` または ``PY`` が付いています。ただし、標準ヘッダファイル内の定義は除き"
"ます。簡単のためと、Python 内で広範に使うことになるという理由から、 "
"``\"Python.h\"`` はいくつかの標準ヘッダファイル: ``<stdio.h>`` 、 ``<string."
"h>`` 、 ``<errno.h>`` 、および ``<stdlib.h>`` をインクルードしています。後者"
"のヘッダファイルがシステム上になければ、 ``\"Python.h\"`` が関数 :c:func:"
"`malloc` 、 :c:func:`free` および :c:func:`realloc` を直接定義します。"

#: ../../extending/extending.rst:85
msgid ""
"The next thing we add to our module file is the C function that will be "
"called when the Python expression ``spam.system(string)`` is evaluated "
"(we'll see shortly how it ends up being called)::"
msgstr ""
"次にファイルに追加する内容は、Python 式 ``spam.system(string)`` を評価する際"
"に呼び出されることになる C 関数です (この関数を最終的にどのように呼び出すか"
"は、後ですぐわかります)::"

#: ../../extending/extending.rst:89
msgid ""
"static PyObject *\n"
"spam_system(PyObject *self, PyObject *args)\n"
"{\n"
"    const char *command;\n"
"    int sts;\n"
"\n"
"    if (!PyArg_ParseTuple(args, \"s\", &command))\n"
"        return NULL;\n"
"    sts = system(command);\n"
"    return PyLong_FromLong(sts);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:101
msgid ""
"There is a straightforward translation from the argument list in Python (for "
"example, the single expression ``\"ls -l\"``) to the arguments passed to the "
"C function.  The C function always has two arguments, conventionally named "
"*self* and *args*."
msgstr ""
"ここでは、Python の引数リスト (例えば、単一の式 ``\"ls -l\"``) から C 関数に"
"渡す引数にそのまま変換しています。 C 関数は常に二つの引数を持ち、便宜的に "
"*self* および *args* と呼ばれます。"

#: ../../extending/extending.rst:106
msgid ""
"The *self* argument points to the module object for module-level functions; "
"for a method it would point to the object instance."
msgstr ""
"*self* 引数には、モジュールレベルの関数であればモジュールが、メソッドにはオブ"
"ジェクトインスタンスが渡されます。"

#: ../../extending/extending.rst:109
msgid ""
"The *args* argument will be a pointer to a Python tuple object containing "
"the arguments.  Each item of the tuple corresponds to an argument in the "
"call's argument list.  The arguments are Python objects --- in order to do "
"anything with them in our C function we have to convert them to C values.  "
"The function :c:func:`PyArg_ParseTuple` in the Python API checks the "
"argument types and converts them to C values.  It uses a template string to "
"determine the required types of the arguments as well as the types of the C "
"variables into which to store the converted values.  More about this later."
msgstr ""
"*args* 引数は、引数の入った Python タプルオブジェクトへのポインタになります。"
"タプル内の各要素は、呼び出しの際の引数リストにおける各引数に対応します。引数"
"は Python オブジェクトです --- C 関数で引数を使って何かを行うには、オブジェク"
"トから C の値に変換せねばなりません。Python API の関数 :c:func:"
"`PyArg_ParseTuple` は引数の型をチェックし、C の値に変換します。 :c:func:"
"`PyArg_ParseTuple` はテンプレート文字列を使って、引数オブジェクトの型と、変換"
"された値を入れる C 変数の型を判別します。これについては後で詳しく説明します。"

#: ../../extending/extending.rst:118
msgid ""
":c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the "
"right type and its components have been stored in the variables whose "
"addresses are passed.  It returns false (zero) if an invalid argument list "
"was passed.  In the latter case it also raises an appropriate exception so "
"the calling function can return ``NULL`` immediately (as we saw in the "
"example)."
msgstr ""
":c:func:`PyArg_ParseTuple` は、全ての引数が正しい型を持っていて、アドレス渡し"
"された各変数に各引数要素を保存したときに真 (非ゼロ) を返します。この関数は不"
"正な引数リストを渡すと偽 (ゼロ) を返します。後者の場合、関数は適切な例外を送"
"出するので、呼び出し側は (例にもあるように) すぐに ``NULL`` を返すようにして"
"ください。"

#: ../../extending/extending.rst:128
msgid "Intermezzo: Errors and Exceptions"
msgstr "幕間小話: エラーと例外"

#: ../../extending/extending.rst:130
msgid ""
"An important convention throughout the Python interpreter is the following: "
"when a function fails, it should set an exception condition and return an "
"error value (usually ``-1`` or a ``NULL`` pointer).  Exception information "
"is stored in three members of the interpreter's thread state.  These are "
"``NULL`` if there is no exception.  Otherwise they are the C equivalents of "
"the members of the Python tuple returned by :meth:`sys.exc_info`.  These are "
"the exception type, exception instance, and a traceback object.  It is "
"important to know about them to understand how errors are passed around."
msgstr ""

#: ../../extending/extending.rst:139
msgid ""
"The Python API defines a number of functions to set various types of "
"exceptions."
msgstr ""
"Python API では、様々な型の例外をセットするための関数をいくつか定義していま"
"す。"

#: ../../extending/extending.rst:141
msgid ""
"The most common one is :c:func:`PyErr_SetString`.  Its arguments are an "
"exception object and a C string.  The exception object is usually a "
"predefined object like :c:data:`PyExc_ZeroDivisionError`.  The C string "
"indicates the cause of the error and is converted to a Python string object "
"and stored as the \"associated value\" of the exception."
msgstr ""
"もっともよく用いられるのは :c:func:`PyErr_SetString` です。引数は例外オブジェ"
"クトと C 文字列です。例外オブジェクトは通常、 :c:data:"
"`PyExc_ZeroDivisionError` のような定義済みのオブジェクトです。 C 文字列はエ"
"ラーの原因を示し、Python 文字列オブジェクトに変換されて例外の \"付属値\" に保"
"存されます。"

#: ../../extending/extending.rst:147
msgid ""
"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an "
"exception argument and constructs the associated value by inspection of the "
"global variable :c:data:`errno`.  The most general function is :c:func:"
"`PyErr_SetObject`, which takes two object arguments, the exception and its "
"associated value.  You don't need to :c:func:`Py_INCREF` the objects passed "
"to any of these functions."
msgstr ""
"もう一つ有用な関数として :c:func:`PyErr_SetFromErrno` があります。この関数は"
"引数に例外だけをとり、付属値はグローバル変数 :c:data:`errno` から構築します。"
"もっとも汎用的な関数は :c:func:`PyErr_SetObject` で、二つのオブジェクト、例外"
"と付属値を引数にとります。これら関数に渡すオブジェクトには :c:func:"
"`Py_INCREF` を使う必要はありません。"

#: ../../extending/extending.rst:154
msgid ""
"You can test non-destructively whether an exception has been set with :c:"
"func:`PyErr_Occurred`.  This returns the current exception object, or "
"``NULL`` if no exception has occurred.  You normally don't need to call :c:"
"func:`PyErr_Occurred` to see whether an error occurred in a function call, "
"since you should be able to tell from the return value."
msgstr ""
"例外がセットされているかどうかは、 :c:func:`PyErr_Occurred` を使って非破壊的"
"に調べられます。この関数は現在の例外オブジェクトを返します。例外が発生してい"
"ない場合には ``NULL`` を返します。通常は、関数の戻り値からエラーが発生したか"
"を判別できるはずなので、 :c:func:`PyErr_Occurred` を呼び出す必要はありませ"
"ん。"

#: ../../extending/extending.rst:160
msgid ""
"When a function *f* that calls another function *g* detects that the latter "
"fails, *f* should itself return an error value (usually ``NULL`` or "
"``-1``).  It should *not* call one of the ``PyErr_*`` functions --- one has "
"already been called by *g*. *f*'s caller is then supposed to also return an "
"error indication to *its* caller, again *without* calling ``PyErr_*``, and "
"so on --- the most detailed cause of the error was already reported by the "
"function that first detected it.  Once the error reaches the Python "
"interpreter's main loop, this aborts the currently executing Python code and "
"tries to find an exception handler specified by the Python programmer."
msgstr ""
"関数 *g* を呼び出す *f* が、前者の関数の呼び出しに失敗したことを検出すると、 "
"*f* 自体はエラー値 (大抵は ``NULL`` や ``-1``) を返さねばなりません。しか"
"し、 ``PyErr_*`` 関数群のいずれかを呼び出す必要は *ありません* --- なぜな"
"ら、 *g* がすでに呼び出しているからです。次いで *f* を呼び出したコードもエ"
"ラーを示す値を *自らを呼び出したコード* に返すことになりますが、同様に "
"``PyErr_*`` は *呼び出しません* 。以下同様に続きます --- エラーの最も詳しい原"
"因は、最初にエラーを検出した関数がすでに報告しているからです。エラーが "
"Python インタプリタのメインループに到達すると、現在実行中の Python コードは一"
"時停止し、 Python プログラマが指定した例外ハンドラを探し出そうとします。"

#: ../../extending/extending.rst:170
msgid ""
"(There are situations where a module can actually give a more detailed error "
"message by calling another ``PyErr_*`` function, and in such cases it is "
"fine to do so.  As a general rule, however, this is not necessary, and can "
"cause information about the cause of the error to be lost: most operations "
"can fail for a variety of reasons.)"
msgstr ""
"(モジュールが ``PyErr_*`` 関数をもう一度呼び出して、より詳細なエラーメッセー"
"ジを提供するような状況があります。このような状況ではそうすべきです。とはい"
"え、一般的な規則としては、この関数を何度も呼び出す必要はなく、ともすればエ"
"ラーの原因に関する情報を失う結果になりがちです: これにより、ほとんどの操作が"
"様々な理由から失敗するかもしれません)"

#: ../../extending/extending.rst:176
msgid ""
"To ignore an exception set by a function call that failed, the exception "
"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`.  The "
"only time C code should call :c:func:`PyErr_Clear` is if it doesn't want to "
"pass the error on to the interpreter but wants to handle it completely by "
"itself (possibly by trying something else, or pretending nothing went wrong)."
msgstr ""
"ある関数呼び出しでの処理の失敗によってセットされた例外を無視するには、 :c:"
"func:`PyErr_Clear` を呼び出して例外状態を明示的に消去しなくてはなりません。エ"
"ラーをインタプリタには渡したくなく、自前で (何か他の作業を行ったり、何も起こ"
"らなかったかのように見せかけるような) エラー処理を完全に行う場合にのみ、 :c:"
"func:`PyErr_Clear` を呼び出すようにすべきです。"

#: ../../extending/extending.rst:182
msgid ""
"Every failing :c:func:`malloc` call must be turned into an exception --- the "
"direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:"
"`PyErr_NoMemory` and return a failure indicator itself.  All the object-"
"creating functions (for example, :c:func:`PyLong_FromLong`) already do this, "
"so this note is only relevant to those who call :c:func:`malloc` directly."
msgstr ""
":c:func:`malloc` の呼び出し失敗は、常に例外にしなくてはなりません --- :c:"
"func:`malloc` (または :c:func:`realloc`) を直接呼び出しているコードは、 :c:"
"func:`PyErr_NoMemory` を呼び出して、失敗を示す値を返さねばなりません。オブ"
"ジェクトを生成する全ての関数 (例えば :c:func:`PyLong_FromLong`) は :c:func:"
"`PyErr_NoMemory` の呼び出しを済ませてしまうので、この規則が関係するのは直接 :"
"c:func:`malloc` を呼び出すコードだけです。"

#: ../../extending/extending.rst:188
msgid ""
"Also note that, with the important exception of :c:func:`PyArg_ParseTuple` "
"and friends, functions that return an integer status usually return a "
"positive value or zero for success and ``-1`` for failure, like Unix system "
"calls."
msgstr ""
"また、 :c:func:`PyArg_ParseTuple` という重要な例外を除いて、整数の状態コード"
"を返す関数はたいてい、Unix のシステムコールと同じく、処理が成功した際にはゼロ"
"または正の値を返し、失敗した場合には ``-1`` を返します。"

#: ../../extending/extending.rst:192
msgid ""
"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or :"
"c:func:`Py_DECREF` calls for objects you have already created) when you "
"return an error indicator!"
msgstr ""
"最後に、エラー標示値を返す際に、(エラーが発生するまでに既に生成してしまったオ"
"ブジェクトに対して :c:func:`Py_XDECREF` や :c:func:`Py_DECREF` を呼び出して) "
"ごみ処理を注意深く行ってください!"

#: ../../extending/extending.rst:196
msgid ""
"The choice of which exception to raise is entirely yours.  There are "
"predeclared C objects corresponding to all built-in Python exceptions, such "
"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, "
"you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` "
"to mean that a file couldn't be opened (that should probably be :c:data:"
"`PyExc_OSError`). If something's wrong with the argument list, the :c:func:"
"`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`.  If "
"you have an argument whose value must be in a particular range or must "
"satisfy other conditions, :c:data:`PyExc_ValueError` is appropriate."
msgstr ""

#: ../../extending/extending.rst:206
msgid ""
"You can also define a new exception that is unique to your module. For this, "
"you usually declare a static object variable at the beginning of your file::"
msgstr ""
"モジュール固有の新たな例外も定義できます。定義するには、通常はファイルの先頭"
"部分に静的なオブジェクト変数の宣言を行います::"

#: ../../extending/extending.rst:209
msgid "static PyObject *SpamError;"
msgstr ""

#: ../../extending/extending.rst:211
msgid ""
"and initialize it in your module's initialization function (:c:func:`!"
"PyInit_spam`) with an exception object::"
msgstr ""

#: ../../extending/extending.rst:214
msgid ""
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    PyObject *m;\n"
"\n"
"    m = PyModule_Create(&spammodule);\n"
"    if (m == NULL)\n"
"        return NULL;\n"
"\n"
"    SpamError = PyErr_NewException(\"spam.error\", NULL, NULL);\n"
"    if (PyModule_AddObjectRef(m, \"error\", SpamError) < 0) {\n"
"        Py_CLEAR(SpamError);\n"
"        Py_DECREF(m);\n"
"        return NULL;\n"
"    }\n"
"\n"
"    return m;\n"
"}"
msgstr ""

#: ../../extending/extending.rst:233
msgid ""
"Note that the Python name for the exception object is :exc:`!spam.error`.  "
"The :c:func:`PyErr_NewException` function may create a class with the base "
"class being :exc:`Exception` (unless another class is passed in instead of "
"``NULL``), described in :ref:`bltin-exceptions`."
msgstr ""

#: ../../extending/extending.rst:238
msgid ""
"Note also that the :c:data:`!SpamError` variable retains a reference to the "
"newly created exception class; this is intentional!  Since the exception "
"could be removed from the module by external code, an owned reference to the "
"class is needed to ensure that it will not be discarded, causing :c:data:`!"
"SpamError` to become a dangling pointer. Should it become a dangling "
"pointer, C code which raises the exception could cause a core dump or other "
"unintended side effects."
msgstr ""

#: ../../extending/extending.rst:245
msgid ""
"We discuss the use of :c:macro:`PyMODINIT_FUNC` as a function return type "
"later in this sample."
msgstr ""

#: ../../extending/extending.rst:248
msgid ""
"The :exc:`!spam.error` exception can be raised in your extension module "
"using a call to :c:func:`PyErr_SetString` as shown below::"
msgstr ""

#: ../../extending/extending.rst:251
msgid ""
"static PyObject *\n"
"spam_system(PyObject *self, PyObject *args)\n"
"{\n"
"    const char *command;\n"
"    int sts;\n"
"\n"
"    if (!PyArg_ParseTuple(args, \"s\", &command))\n"
"        return NULL;\n"
"    sts = system(command);\n"
"    if (sts < 0) {\n"
"        PyErr_SetString(SpamError, \"System command failed\");\n"
"        return NULL;\n"
"    }\n"
"    return PyLong_FromLong(sts);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:271
msgid "Back to the Example"
msgstr "例に戻る"

#: ../../extending/extending.rst:273
msgid ""
"Going back to our example function, you should now be able to understand "
"this statement::"
msgstr "先ほどの関数の例に戻ると、今度は以下の実行文を理解できるはずです::"

#: ../../extending/extending.rst:276
msgid ""
"if (!PyArg_ParseTuple(args, \"s\", &command))\n"
"    return NULL;"
msgstr ""

#: ../../extending/extending.rst:279
msgid ""
"It returns ``NULL`` (the error indicator for functions returning object "
"pointers) if an error is detected in the argument list, relying on the "
"exception set by :c:func:`PyArg_ParseTuple`.  Otherwise the string value of "
"the argument has been copied to the local variable :c:data:`!command`.  This "
"is a pointer assignment and you are not supposed to modify the string to "
"which it points (so in Standard C, the variable :c:data:`!command` should "
"properly be declared as ``const char *command``)."
msgstr ""

#: ../../extending/extending.rst:287
msgid ""
"The next statement is a call to the Unix function :c:func:`system`, passing "
"it the string we just got from :c:func:`PyArg_ParseTuple`::"
msgstr ""
"次の文では、 :c:func:`PyArg_ParseTuple` で得た文字列を渡して Unix 関数 :c:"
"func:`system` を呼び出しています::"

#: ../../extending/extending.rst:290
msgid "sts = system(command);"
msgstr ""

#: ../../extending/extending.rst:292
msgid ""
"Our :func:`!spam.system` function must return the value of :c:data:`!sts` as "
"a Python object.  This is done using the function :c:func:"
"`PyLong_FromLong`. ::"
msgstr ""

#: ../../extending/extending.rst:295
msgid "return PyLong_FromLong(sts);"
msgstr ""

#: ../../extending/extending.rst:297
msgid ""
"In this case, it will return an integer object.  (Yes, even integers are "
"objects on the heap in Python!)"
msgstr ""
"上の場合では、整数オブジェクトを返します。(そう、整数ですら、 Python において"
"はヒープ上のオブジェクトなのです! )"

#: ../../extending/extending.rst:300
msgid ""
"If you have a C function that returns no useful argument (a function "
"returning :c:expr:`void`), the corresponding Python function must return "
"``None``.   You need this idiom to do so (which is implemented by the :c:"
"macro:`Py_RETURN_NONE` macro)::"
msgstr ""
"何ら有用な値を返さない関数 (:c:expr:`void` を返す関数) に対応する Python の関"
"数は ``None`` を返さねばなりません。関数に ``None`` を返させるには、以下のよ"
"うな慣用句を使います (この慣用句は :c:macro:`Py_RETURN_NONE` マクロに実装され"
"ています)::"

#: ../../extending/extending.rst:305
msgid ""
"Py_INCREF(Py_None);\n"
"return Py_None;"
msgstr ""

#: ../../extending/extending.rst:308
msgid ""
":c:data:`Py_None` is the C name for the special Python object ``None``.  It "
"is a genuine Python object rather than a ``NULL`` pointer, which means "
"\"error\" in most contexts, as we have seen."
msgstr ""
":c:data:`Py_None` は特殊な Pyhton オブジェクトである ``None`` に対応する C で"
"の名前です。これまで見てきたようにほとんどのコンテキストで \"エラー\" を意味"
"する ``NULL`` ポインタとは違い、 ``None`` は純粋な Python のオブジェクトで"
"す。"

#: ../../extending/extending.rst:316
msgid "The Module's Method Table and Initialization Function"
msgstr "モジュールのメソッドテーブルと初期化関数"

#: ../../extending/extending.rst:318
msgid ""
"I promised to show how :c:func:`!spam_system` is called from Python "
"programs. First, we need to list its name and address in a \"method table\"::"
msgstr ""

#: ../../extending/extending.rst:321
msgid ""
"static PyMethodDef SpamMethods[] = {\n"
"    ...\n"
"    {\"system\",  spam_system, METH_VARARGS,\n"
"     \"Execute a shell command.\"},\n"
"    ...\n"
"    {NULL, NULL, 0, NULL}        /* Sentinel */\n"
"};"
msgstr ""

#: ../../extending/extending.rst:329
msgid ""
"Note the third entry (``METH_VARARGS``).  This is a flag telling the "
"interpreter the calling convention to be used for the C function.  It should "
"normally always be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a "
"value of ``0`` means that an obsolete variant of :c:func:`PyArg_ParseTuple` "
"is used."
msgstr ""
"リスト要素の三つ目のエントリ (``METH_VARARGS``) に注意してください。このエン"
"トリは、C 関数が使う呼び出し規約をインタプリタに教えるためのフラグです。通常"
"この値は ``METH_VARARGS`` か ``METH_VARARGS | METH_KEYWORDS`` のはずです; "
"``0`` は旧式の :c:func:`PyArg_ParseTuple` の変化形が使われることを意味しま"
"す。"

#: ../../extending/extending.rst:334
msgid ""
"When using only ``METH_VARARGS``, the function should expect the Python-"
"level parameters to be passed in as a tuple acceptable for parsing via :c:"
"func:`PyArg_ParseTuple`; more information on this function is provided below."
msgstr ""
"``METH_VARARGS`` だけを使う場合、C 関数は、Python レベルでの引数が :c:func:"
"`PyArg_ParseTuple` が受理できるタプルの形式で渡されるものと想定しなければなり"
"ません; この関数についての詳細は下で説明します。"

#: ../../extending/extending.rst:338
msgid ""
"The :c:macro:`METH_KEYWORDS` bit may be set in the third field if keyword "
"arguments should be passed to the function.  In this case, the C function "
"should accept a third ``PyObject *`` parameter which will be a dictionary of "
"keywords. Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments "
"to such a function."
msgstr ""

#: ../../extending/extending.rst:344
msgid ""
"The method table must be referenced in the module definition structure::"
msgstr ""
"メソッドテーブルはモジュール定義の構造体から参照されていなければなりません::"

#: ../../extending/extending.rst:346
msgid ""
"static struct PyModuleDef spammodule = {\n"
"    PyModuleDef_HEAD_INIT,\n"
"    \"spam\",   /* name of module */\n"
"    spam_doc, /* module documentation, may be NULL */\n"
"    -1,       /* size of per-interpreter state of the module,\n"
"                 or -1 if the module keeps state in global variables. */\n"
"    SpamMethods\n"
"};"
msgstr ""

#: ../../extending/extending.rst:355
msgid ""
"This structure, in turn, must be passed to the interpreter in the module's "
"initialization function.  The initialization function must be named :c:func:"
"`!PyInit_name`, where *name* is the name of the module, and should be the "
"only non-\\ ``static`` item defined in the module file::"
msgstr ""

#: ../../extending/extending.rst:360
msgid ""
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    return PyModule_Create(&spammodule);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:366
msgid ""
"Note that :c:macro:`PyMODINIT_FUNC` declares the function as ``PyObject *`` "
"return type, declares any special linkage declarations required by the "
"platform, and for C++ declares the function as ``extern \"C\"``."
msgstr ""

#: ../../extending/extending.rst:370
msgid ""
"When the Python program imports module :mod:`!spam` for the first time, :c:"
"func:`!PyInit_spam` is called. (See below for comments about embedding "
"Python.) It calls :c:func:`PyModule_Create`, which returns a module object, "
"and inserts built-in function objects into the newly created module based "
"upon the table (an array of :c:type:`PyMethodDef` structures) found in the "
"module definition. :c:func:`PyModule_Create` returns a pointer to the module "
"object that it creates.  It may abort with a fatal error for certain errors, "
"or return ``NULL`` if the module could not be initialized satisfactorily. "
"The init function must return the module object to its caller, so that it "
"then gets inserted into ``sys.modules``."
msgstr ""

#: ../../extending/extending.rst:381
msgid ""
"When embedding Python, the :c:func:`!PyInit_spam` function is not called "
"automatically unless there's an entry in the :c:data:`PyImport_Inittab` "
"table. To add the module to the initialization table, use :c:func:"
"`PyImport_AppendInittab`, optionally followed by an import of the module::"
msgstr ""

#: ../../extending/extending.rst:386
msgid ""
"#define PY_SSIZE_T_CLEAN\n"
"#include <Python.h>\n"
"\n"
"int\n"
"main(int argc, char *argv[])\n"
"{\n"
"    PyStatus status;\n"
"    PyConfig config;\n"
"    PyConfig_InitPythonConfig(&config);\n"
"\n"
"    /* Add a built-in module, before Py_Initialize */\n"
"    if (PyImport_AppendInittab(\"spam\", PyInit_spam) == -1) {\n"
"        fprintf(stderr, \"Error: could not extend in-built modules "
"table\\n\");\n"
"        exit(1);\n"
"    }\n"
"\n"
"    /* Pass argv[0] to the Python interpreter */\n"
"    status = PyConfig_SetBytesString(&config, &config.program_name, "
"argv[0]);\n"
"    if (PyStatus_Exception(status)) {\n"
"        goto exception;\n"
"    }\n"
"\n"
"    /* Initialize the Python interpreter.  Required.\n"
"       If this step fails, it will be a fatal error. */\n"
"    status = Py_InitializeFromConfig(&config);\n"
"    if (PyStatus_Exception(status)) {\n"
"        goto exception;\n"
"    }\n"
"    PyConfig_Clear(&config);\n"
"\n"
"    /* Optionally import the module; alternatively,\n"
"       import can be deferred until the embedded script\n"
"       imports it. */\n"
"    PyObject *pmodule = PyImport_ImportModule(\"spam\");\n"
"    if (!pmodule) {\n"
"        PyErr_Print();\n"
"        fprintf(stderr, \"Error: could not import module 'spam'\\n\");\n"
"    }\n"
"\n"
"    // ... use Python C API here ...\n"
"\n"
"    return 0;\n"
"\n"
"  exception:\n"
"     PyConfig_Clear(&config);\n"
"     Py_ExitStatusException(status);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:436
msgid ""
"Removing entries from ``sys.modules`` or importing compiled modules into "
"multiple interpreters within a process (or following a :c:func:`fork` "
"without an intervening :c:func:`exec`) can create problems for some "
"extension modules. Extension module authors should exercise caution when "
"initializing internal data structures."
msgstr ""
"単一のプロセス内 (または :c:func:`fork` 後の :c:func:`exec` が介入していない"
"状態) における複数のインタプリタにおいて、 ``sys.modules`` からエントリを除去"
"したり新たなコンパイル済みモジュールを import したりすると、拡張モジュールに"
"よっては問題を生じることがあります。拡張モジュールの作者は、内部データ構造を"
"初期化する際にはよくよく用心すべきです。"

#: ../../extending/extending.rst:442
msgid ""
"A more substantial example module is included in the Python source "
"distribution as :file:`Modules/xxmodule.c`.  This file may be used as a  "
"template or simply read as an example."
msgstr ""
"より実質的なモジュール例は、Python ソース配布物に :file:`Modules/xxmodule.c` "
"という名前で入っています。このファイルはテンプレートとしても利用できますし、"
"単に例としても読めます。"

#: ../../extending/extending.rst:448
msgid ""
"Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization* "
"(new in Python 3.5), where a PyModuleDef structure is returned from "
"``PyInit_spam``, and creation of the module is left to the import machinery. "
"For details on multi-phase initialization, see :PEP:`489`."
msgstr ""
"``xmodule`` は ``spam`` と異なり、 *多段階初期化 (multi-phase "
"initialization* (Python 3.5 の新機能) を使っています。 ``PyInit_spam`` が "
"PyModuleDef を返し、モジュールの生成は後に import 機構が行います。多段階初期"
"化についての詳細は :PEP:`489` を参照してください。"

#: ../../extending/extending.rst:457
msgid "Compilation and Linkage"
msgstr "コンパイルとリンク"

#: ../../extending/extending.rst:459
msgid ""
"There are two more things to do before you can use your new extension: "
"compiling and linking it with the Python system.  If you use dynamic "
"loading, the details may depend on the style of dynamic loading your system "
"uses; see the chapters about building extension modules (chapter :ref:"
"`building`) and additional information that pertains only to building on "
"Windows (chapter :ref:`building-on-windows`) for more information about this."
msgstr ""
"新しい拡張モジュールを使えるようになるまで、まだ二つの作業: コンパイルと、"
"Python システムへのリンク、が残っています。動的読み込み (dynamic loading) を"
"使っているのなら、作業の詳細は自分のシステムが使っている動的読み込みの形式に"
"よって変わるかもしれません; 詳しくは、拡張モジュールのビルドに関する章 (:ref:"
"`building` 章) や、Windows におけるビルドに関係する追加情報の章 (:ref:"
"`building-on-windows` 章) を参照してください。"

#: ../../extending/extending.rst:466
msgid ""
"If you can't use dynamic loading, or if you want to make your module a "
"permanent part of the Python interpreter, you will have to change the "
"configuration setup and rebuild the interpreter.  Luckily, this is very "
"simple on Unix: just place your file (:file:`spammodule.c` for example) in "
"the :file:`Modules/` directory of an unpacked source distribution, add a "
"line to the file :file:`Modules/Setup.local` describing your file:"
msgstr ""
"動的読み込みを使えなかったり、モジュールを常時 Python インタプリタの一部にし"
"ておきたい場合には、インタプリタのビルド設定を変更して再ビルドしなければなら"
"なくなるでしょう。Unixでは、幸運なことにこの作業はとても単純です: 単に自作の"
"モジュールファイル (例えば :file:`spammodule.c`) を展開したソース配布物の :"
"file:`Modules/`  ディレクトリに置き、 :file:`Modules/Setup.local` に自分の"
"ファイルを説明する以下の一行:"

#: ../../extending/extending.rst:473
msgid "spam spammodule.o"
msgstr ""

#: ../../extending/extending.rst:477
msgid ""
"and rebuild the interpreter by running :program:`make` in the toplevel "
"directory.  You can also run :program:`make` in the :file:`Modules/` "
"subdirectory, but then you must first rebuild :file:`Makefile` there by "
"running ':program:`make` Makefile'.  (This is necessary each time you change "
"the :file:`Setup` file.)"
msgstr ""
"を追加して、トップレベルのディレクトリで :program:`make` を実行して、インタプ"
"リタを再ビルドするだけです。 :file:`Modules/` サブディレクトリでも :program:"
"`make` を実行できますが、前もって ':program:`make` Makefile' を実行して :"
"file:`Makefile` を再ビルドしておかなければならりません。(この作業は :file:"
"`Setup` ファイルを変更するたびに必要です。)"

#: ../../extending/extending.rst:483
msgid ""
"If your module requires additional libraries to link with, these can be "
"listed on the line in the configuration file as well, for instance:"
msgstr ""
"モジュールが別のライブラリとリンクされている必要がある場合、ライブラリも設定"
"ファイルに列挙できます。例えば以下のようにします。"

#: ../../extending/extending.rst:486
msgid "spam spammodule.o -lX11"
msgstr ""

#: ../../extending/extending.rst:494
msgid "Calling Python Functions from C"
msgstr "C から Python 関数を呼び出す"

#: ../../extending/extending.rst:496
msgid ""
"So far we have concentrated on making C functions callable from Python.  The "
"reverse is also useful: calling Python functions from C. This is especially "
"the case for libraries that support so-called \"callback\" functions.  If a "
"C interface makes use of callbacks, the equivalent Python often needs to "
"provide a callback mechanism to the Python programmer; the implementation "
"will require calling the Python callback functions from a C callback.  Other "
"uses are also imaginable."
msgstr ""
"これまでは、Python からの C 関数の呼び出しに重点を置いて述べてきました。とこ"
"ろでこの逆: C からの Python 関数の呼び出しもまた有用です。とりわけ、いわゆる "
"\"コールバック\" 関数をサポートするようなライブラリを作成する際にはこの機能が"
"便利です。ある C インターフェースがコールバックを利用している場合、同等の機能"
"を提供する Python コードでは、しばしば Python プログラマにコールバック機構を"
"提供する必要があります; このとき実装では、 C で書かれたコールバック関数から "
"Python で書かれたコールパック関数を呼び出すようにする必要があるでしょう。もち"
"ろん、他の用途も考えられます。"

#: ../../extending/extending.rst:504
msgid ""
"Fortunately, the Python interpreter is easily called recursively, and there "
"is a standard interface to call a Python function.  (I won't dwell on how to "
"call the Python parser with a particular string as input --- if you're "
"interested, have a look at the implementation of the :option:`-c` command "
"line option in :file:`Modules/main.c` from the Python source code.)"
msgstr ""
"幸運なことに、Python インタプリタは簡単に再帰呼び出しでき、 Python 関数を呼び"
"出すための標準インターフェースもあります。 (Python パーザを特定の入力文字を"
"使って呼び出す方法について詳説するつもりはありません --- この方法に興味がある"
"なら、 Python ソースコードの :file:`Modules/main.c` にある、コマンドラインオ"
"プション :option:`-c` の実装を見てください)"

#: ../../extending/extending.rst:510
msgid ""
"Calling a Python function is easy.  First, the Python program must somehow "
"pass you the Python function object.  You should provide a function (or some "
"other interface) to do this.  When this function is called, save a pointer "
"to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a "
"global variable --- or wherever you see fit. For example, the following "
"function might be part of a module definition::"
msgstr ""
"Python 関数の呼び出しは簡単です。まず、C のコードに対してコールバックを登録し"
"ようとする Python プログラムは、何らかの方法で Python の関数オブジェクトを渡"
"さねばなりません。このために、コールバック登録関数 (またはその他のインター"
"フェース) を提供せねばなりません。このコールバック登録関数が呼び出された際"
"に、引き渡された Python 関数オブジェクトへのポインタをグローバル変数に --- あ"
"るいは、どこか適切な場所に --- 保存します (関数オブジェクトを :c:func:"
"`Py_INCREF` するようよく注意してください!)。例えば、以下のような関数がモ"
"ジュールの一部になっていることでしょう::"

#: ../../extending/extending.rst:517
msgid ""
"static PyObject *my_callback = NULL;\n"
"\n"
"static PyObject *\n"
"my_set_callback(PyObject *dummy, PyObject *args)\n"
"{\n"
"    PyObject *result = NULL;\n"
"    PyObject *temp;\n"
"\n"
"    if (PyArg_ParseTuple(args, \"O:set_callback\", &temp)) {\n"
"        if (!PyCallable_Check(temp)) {\n"
"            PyErr_SetString(PyExc_TypeError, \"parameter must be "
"callable\");\n"
"            return NULL;\n"
"        }\n"
"        Py_XINCREF(temp);         /* Add a reference to new callback */\n"
"        Py_XDECREF(my_callback);  /* Dispose of previous callback */\n"
"        my_callback = temp;       /* Remember new callback */\n"
"        /* Boilerplate to return \"None\" */\n"
"        Py_INCREF(Py_None);\n"
"        result = Py_None;\n"
"    }\n"
"    return result;\n"
"}"
msgstr ""

#: ../../extending/extending.rst:540
msgid ""
"This function must be registered with the interpreter using the :c:macro:"
"`METH_VARARGS` flag; this is described in section :ref:`methodtable`.  The :"
"c:func:`PyArg_ParseTuple` function and its arguments are documented in "
"section :ref:`parsetuple`."
msgstr ""

#: ../../extending/extending.rst:545
msgid ""
"The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement "
"the reference count of an object and are safe in the presence of ``NULL`` "
"pointers (but note that *temp* will not be  ``NULL`` in this context).  More "
"info on them in section :ref:`refcounts`."
msgstr ""
":c:func:`Py_XINCREF` および :c:func:`Py_XDECREF` は、オブジェクトに対する参照"
"カウントをインクリメント/デクリメントするためのマクロで、 ``NULL`` ポインタが"
"渡されても安全に操作できる形式です (とはいえ、上の流れでは *temp* が "
"``NULL`` になることはありません)。これらのマクロと参照カウントについては、 :"
"ref:`refcounts` で説明しています。"

#: ../../extending/extending.rst:552
msgid ""
"Later, when it is time to call the function, you call the C function :c:func:"
"`PyObject_CallObject`.  This function has two arguments, both pointers to "
"arbitrary Python objects: the Python function, and the argument list.  The "
"argument list must always be a tuple object, whose length is the number of "
"arguments.  To call the Python function with no arguments, pass in ``NULL``, "
"or an empty tuple; to call it with one argument, pass a singleton tuple. :c:"
"func:`Py_BuildValue` returns a tuple when its format string consists of zero "
"or more format codes between parentheses.  For example::"
msgstr ""
"その後、コールバック関数を呼び出す時が来たら、C 関数 :c:func:"
"`PyObject_CallObject` を呼び出します。この関数には二つの引数: Python 関数と "
"Python 関数の引数リストがあり、いずれも任意の Python オブジェクトを表すポイン"
"タ型です。引数リストは常にタプルオブジェクトでなければならず、その長さは引数"
"の数になります。Python 関数を引数なしで呼び出すのなら、 ``NULL`` か空のタプル"
"を渡します; 単一の引数で関数を呼び出すのなら、単要素 (singleton) のタプルを渡"
"します。 :c:func:`Py_BuildValue` の書式文字列中に、ゼロ個または一個以上の書式"
"化コードが入った丸括弧がある場合、この関数はタプルを返します。以下に例を示し"
"ます::"

#: ../../extending/extending.rst:561
msgid ""
"int arg;\n"
"PyObject *arglist;\n"
"PyObject *result;\n"
"...\n"
"arg = 123;\n"
"...\n"
"/* Time to call the callback */\n"
"arglist = Py_BuildValue(\"(i)\", arg);\n"
"result = PyObject_CallObject(my_callback, arglist);\n"
"Py_DECREF(arglist);"
msgstr ""

#: ../../extending/extending.rst:572
msgid ""
":c:func:`PyObject_CallObject` returns a Python object pointer: this is the "
"return value of the Python function.  :c:func:`PyObject_CallObject` is "
"\"reference-count-neutral\" with respect to its arguments.  In the example a "
"new tuple was created to serve as the argument list, which is :c:func:"
"`Py_DECREF`\\ -ed immediately after the :c:func:`PyObject_CallObject` call."
msgstr ""
":c:func:`PyObject_CallObject` は Python オブジェクトへのポインタを返します: "
"これは Python 関数からの戻り値になります。 :c:func:`PyObject_CallObject` は、"
"引数に対して \"参照カウント中立 (reference-count- neutral)\" です。上の例では"
"タプルを生成して引数リストとして提供しており、このタプルは :c:func:"
"`PyObject_CallObject` の呼び出し直後に :c:func:`Py_DECREF` されています。"

#: ../../extending/extending.rst:579
msgid ""
"The return value of :c:func:`PyObject_CallObject` is \"new\": either it is a "
"brand new object, or it is an existing object whose reference count has been "
"incremented.  So, unless you want to save it in a global variable, you "
"should somehow :c:func:`Py_DECREF` the result, even (especially!) if you are "
"not interested in its value."
msgstr ""
":c:func:`PyObject_CallObject` は戻り値として \"新しい\" オブジェクト: 新規に"
"作成されたオブジェクトか、既存のオブジェクトの参照カウントをインクリメントし"
"たものを返します。従って、このオブジェクトをグローバル変数に保存したいのでな"
"いかぎり、たとえこの戻り値に興味がなくても (むしろ、そうであればなおさら!) 何"
"がしかの方法で戻り値オブジェクトを :c:func:`Py_DECREF` しなければなりません。"

#: ../../extending/extending.rst:585
msgid ""
"Before you do this, however, it is important to check that the return value "
"isn't ``NULL``.  If it is, the Python function terminated by raising an "
"exception. If the C code that called :c:func:`PyObject_CallObject` is called "
"from Python, it should now return an error indication to its Python caller, "
"so the interpreter can print a stack trace, or the calling Python code can "
"handle the exception. If this is not possible or desirable, the exception "
"should be cleared by calling :c:func:`PyErr_Clear`.  For example::"
msgstr ""
"とはいえ、戻り値を :c:func:`Py_DECREF` する前には、値が ``NULL`` でないか"
"チェックしておくことが重要です。もし ``NULL`` なら、呼び出した Python 関数は"
"例外を送出して終了させられています。 :c:func:`PyObject_CallObject` を呼び出し"
"ているコード自体もまた Python から呼び出されているのであれば、今度は C コード"
"が自分を呼び出している Python コードにエラー標示値を返さねばなりません。それ"
"により、インタプリタはスタックトレースを出力したり、例外を処理するための "
"Python コードを呼び出したりできます。例外の送出が不可能だったり、したくないの"
"なら、 :c:func:`PyErr_Clear` を呼んで例外を消去しておかねばなりません。例えば"
"以下のようにします::"

#: ../../extending/extending.rst:593
msgid ""
"if (result == NULL)\n"
"    return NULL; /* Pass error back */\n"
"...use result...\n"
"Py_DECREF(result);"
msgstr ""

#: ../../extending/extending.rst:598
msgid ""
"Depending on the desired interface to the Python callback function, you may "
"also have to provide an argument list to :c:func:`PyObject_CallObject`.  In "
"some cases the argument list is also provided by the Python program, through "
"the same interface that specified the callback function.  It can then be "
"saved and used in the same manner as the function object.  In other cases, "
"you may have to construct a new tuple to pass as the argument list.  The "
"simplest way to do this is to call :c:func:`Py_BuildValue`.  For example, if "
"you want to pass an integral event code, you might use the following code::"
msgstr ""
"Python コールバック関数をどんなインターフェースにしたいかによっては、引数リス"
"トを :c:func:`PyObject_CallObject` に与えなければならない場合もあります。ある"
"ケースでは、コールバック関数を指定したのと同じインターフェースを介して、引数"
"リストも渡されているかもしれません。また別のケースでは、新しいタプルを構築し"
"て引数リストを渡さねばならないかもしれません。この場合最も簡単なのは :c:func:"
"`Py_BuildValue` を呼ぶやり方です。例えば、整数のイベントコードを渡したけれ"
"ば、以下のようなコードを使うことになるでしょう::"

#: ../../extending/extending.rst:607
msgid ""
"PyObject *arglist;\n"
"...\n"
"arglist = Py_BuildValue(\"(l)\", eventcode);\n"
"result = PyObject_CallObject(my_callback, arglist);\n"
"Py_DECREF(arglist);\n"
"if (result == NULL)\n"
"    return NULL; /* Pass error back */\n"
"/* Here maybe use the result */\n"
"Py_DECREF(result);"
msgstr ""

#: ../../extending/extending.rst:617
msgid ""
"Note the placement of ``Py_DECREF(arglist)`` immediately after the call, "
"before the error check!  Also note that strictly speaking this code is not "
"complete: :c:func:`Py_BuildValue` may run out of memory, and this should be "
"checked."
msgstr ""
"``Py_DECREF(arglist)`` が呼び出しの直後、エラーチェックよりも前に置かれている"
"ことに注意してください! また、厳密に言えば、このコードは完全ではありません: :"
"c:func:`Py_BuildValue` はメモリ不足におちいるかもしれず、チェックしておくべき"
"です。"

#: ../../extending/extending.rst:621
msgid ""
"You may also call a function with keyword arguments by using :c:func:"
"`PyObject_Call`, which supports arguments and keyword arguments.  As in the "
"above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::"
msgstr ""
"通常の引数とキーワード引数をサポートする :c:func:`PyObject_Call` を使って、"
"キーワード引数を伴う関数呼び出しをすることができます。上の例と同じように、 :"
"c:func:`Py_BuildValue` を作って辞書を作ります。 ::"

#: ../../extending/extending.rst:625
msgid ""
"PyObject *dict;\n"
"...\n"
"dict = Py_BuildValue(\"{s:i}\", \"name\", val);\n"
"result = PyObject_Call(my_callback, NULL, dict);\n"
"Py_DECREF(dict);\n"
"if (result == NULL)\n"
"    return NULL; /* Pass error back */\n"
"/* Here maybe use the result */\n"
"Py_DECREF(result);"
msgstr ""

#: ../../extending/extending.rst:639
msgid "Extracting Parameters in Extension Functions"
msgstr "拡張モジュール関数でのパラメタ展開"

#: ../../extending/extending.rst:643
msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::"
msgstr ":c:func:`PyArg_ParseTuple` 関数は以下のように宣言されています::"

#: ../../extending/extending.rst:645
msgid "int PyArg_ParseTuple(PyObject *arg, const char *format, ...);"
msgstr ""

#: ../../extending/extending.rst:647
msgid ""
"The *arg* argument must be a tuple object containing an argument list passed "
"from Python to a C function.  The *format* argument must be a format string, "
"whose syntax is explained in :ref:`arg-parsing` in the Python/C API "
"Reference Manual.  The remaining arguments must be addresses of variables "
"whose type is determined by the format string."
msgstr ""
"引数 *arg* は C 関数から Python に渡される引数リストが入ったタプルオブジェク"
"トでなければなりません。 *format* 引数は書式文字列で、 Python/C API リファレ"
"ンスマニュアルの :ref:`arg-parsing` で解説されている書法に従わねばなりませ"
"ん。残りの引数は、それぞれの変数のアドレスで、書式化文字列から決まる型になっ"
"ていなければなりません。"

#: ../../extending/extending.rst:653
msgid ""
"Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments "
"have the required types, it cannot check the validity of the addresses of C "
"variables passed to the call: if you make mistakes there, your code will "
"probably crash or at least overwrite random bits in memory.  So be careful!"
msgstr ""
":c:func:`PyArg_ParseTuple` は Python 側から与えられた引数が必要な型になってい"
"るか調べるのに対し、 :c:func:`PyArg_ParseTuple` は呼び出しの際に渡された C 変"
"数のアドレスが有効な値を持つか調べられないことに注意してください: ここで間違"
"いを犯すと、コードがクラッシュするかもしれませんし、少なくともでたらめなビッ"
"トをメモリに上書きしてしまいます。慎重に!"

#: ../../extending/extending.rst:658
msgid ""
"Note that any Python object references which are provided to the caller are "
"*borrowed* references; do not decrement their reference count!"
msgstr ""
"呼び出し側に提供されるオブジェクトへの参照はすべて *借用* 参照 (borrowed "
"reference) になります; これらのオブジェクトの参照カウントをデクリメントしては"
"なりません!"

#: ../../extending/extending.rst:661
msgid "Some example calls::"
msgstr "以下にいくつかの呼び出し例を示します::"

#: ../../extending/extending.rst:668
msgid ""
"int ok;\n"
"int i, j;\n"
"long k, l;\n"
"const char *s;\n"
"Py_ssize_t size;\n"
"\n"
"ok = PyArg_ParseTuple(args, \"\"); /* No arguments */\n"
"    /* Python call: f() */"
msgstr ""

#: ../../extending/extending.rst:679
msgid ""
"ok = PyArg_ParseTuple(args, \"s\", &s); /* A string */\n"
"    /* Possible Python call: f('whoops!') */"
msgstr ""

#: ../../extending/extending.rst:684
msgid ""
"ok = PyArg_ParseTuple(args, \"lls\", &k, &l, &s); /* Two longs and a string "
"*/\n"
"    /* Possible Python call: f(1, 2, 'three') */"
msgstr ""

#: ../../extending/extending.rst:689
msgid ""
"ok = PyArg_ParseTuple(args, \"(ii)s#\", &i, &j, &s, &size);\n"
"    /* A pair of ints and a string, whose size is also returned */\n"
"    /* Possible Python call: f((1, 2), 'three') */"
msgstr ""

#: ../../extending/extending.rst:695
msgid ""
"{\n"
"    const char *file;\n"
"    const char *mode = \"r\";\n"
"    int bufsize = 0;\n"
"    ok = PyArg_ParseTuple(args, \"s|si\", &file, &mode, &bufsize);\n"
"    /* A string, and optionally another string and an integer */\n"
"    /* Possible Python calls:\n"
"       f('spam')\n"
"       f('spam', 'w')\n"
"       f('spam', 'wb', 100000) */\n"
"}"
msgstr ""

#: ../../extending/extending.rst:709
msgid ""
"{\n"
"    int left, top, right, bottom, h, v;\n"
"    ok = PyArg_ParseTuple(args, \"((ii)(ii))(ii)\",\n"
"             &left, &top, &right, &bottom, &h, &v);\n"
"    /* A rectangle and a point */\n"
"    /* Possible Python call:\n"
"       f(((0, 0), (400, 300)), (10, 10)) */\n"
"}"
msgstr ""

#: ../../extending/extending.rst:720
msgid ""
"{\n"
"    Py_complex c;\n"
"    ok = PyArg_ParseTuple(args, \"D:myfunction\", &c);\n"
"    /* a complex, also providing a function name for errors */\n"
"    /* Possible Python call: myfunction(1+2j) */\n"
"}"
msgstr ""

#: ../../extending/extending.rst:731
msgid "Keyword Parameters for Extension Functions"
msgstr "拡張モジュール関数のキーワードパラメタ"

#: ../../extending/extending.rst:735
msgid ""
"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::"
msgstr ""
":c:func:`PyArg_ParseTupleAndKeywords` は、以下のように宣言されています::"

#: ../../extending/extending.rst:737
msgid ""
"int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,\n"
"                                const char *format, char * const "
"*kwlist, ...);"
msgstr ""

#: ../../extending/extending.rst:740
msgid ""
"The *arg* and *format* parameters are identical to those of the :c:func:"
"`PyArg_ParseTuple` function.  The *kwdict* parameter is the dictionary of "
"keywords received as the third parameter from the Python runtime.  The "
"*kwlist* parameter is a ``NULL``-terminated list of strings which identify "
"the parameters; the names are matched with the type information from "
"*format* from left to right.  On success, :c:func:"
"`PyArg_ParseTupleAndKeywords` returns true, otherwise it returns false and "
"raises an appropriate exception."
msgstr ""
"*arg* と *format* パラメタは :c:func:`PyArg_ParseTuple` のものと同じです。 "
"*kwdict* パラメタはキーワード引数の入った辞書で、 Python ランタイムシステムか"
"ら第三パラメタとして受け取ります。 *kwlist* パラメタは各パラメタを識別するた"
"めの文字列からなる、 ``NULL`` 終端されたリストです; 各パラメタ名は *format* "
"中の型情報に対して左から右の順に照合されます。成功すると :c:func:"
"`PyArg_ParseTupleAndKeywords` は真を返し、それ以外の場合には適切な例外を送出"
"して偽を返します。"

#: ../../extending/extending.rst:750
msgid ""
"Nested tuples cannot be parsed when using keyword arguments!  Keyword "
"parameters passed in which are not present in the *kwlist* will cause :exc:"
"`TypeError` to be raised."
msgstr ""
"キーワード引数を使っている場合、タプルは入れ子にして使えません! *kwlist* 内に"
"存在しないキーワードパラメタが渡された場合、 :exc:`TypeError` の送出を引き起"
"こします。"

#: ../../extending/extending.rst:756
msgid ""
"Here is an example module which uses keywords, based on an example by Geoff "
"Philbrick (philbrick@hks.com)::"
msgstr ""
"以下にキーワードを使ったモジュール例を示します。これは Geoff Philbrick "
"(philbrick@hks.com) によるプログラム例をもとにしています::"

#: ../../extending/extending.rst:759
msgid ""
"#define PY_SSIZE_T_CLEAN\n"
"#include <Python.h>\n"
"\n"
"static PyObject *\n"
"keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)\n"
"{\n"
"    int voltage;\n"
"    const char *state = \"a stiff\";\n"
"    const char *action = \"voom\";\n"
"    const char *type = \"Norwegian Blue\";\n"
"\n"
"    static char *kwlist[] = {\"voltage\", \"state\", \"action\", \"type\", "
"NULL};\n"
"\n"
"    if (!PyArg_ParseTupleAndKeywords(args, keywds, \"i|sss\", kwlist,\n"
"                                     &voltage, &state, &action, &type))\n"
"        return NULL;\n"
"\n"
"    printf(\"-- This parrot wouldn't %s if you put %i Volts through it."
"\\n\",\n"
"           action, voltage);\n"
"    printf(\"-- Lovely plumage, the %s -- It's %s!\\n\", type, state);\n"
"\n"
"    Py_RETURN_NONE;\n"
"}\n"
"\n"
"static PyMethodDef keywdarg_methods[] = {\n"
"    /* The cast of the function is necessary since PyCFunction values\n"
"     * only take two PyObject* parameters, and keywdarg_parrot() takes\n"
"     * three.\n"
"     */\n"
"    {\"parrot\", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | "
"METH_KEYWORDS,\n"
"     \"Print a lovely skit to standard output.\"},\n"
"    {NULL, NULL, 0, NULL}   /* sentinel */\n"
"};\n"
"\n"
"static struct PyModuleDef keywdargmodule = {\n"
"    PyModuleDef_HEAD_INIT,\n"
"    \"keywdarg\",\n"
"    NULL,\n"
"    -1,\n"
"    keywdarg_methods\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_keywdarg(void)\n"
"{\n"
"    return PyModule_Create(&keywdargmodule);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:811
msgid "Building Arbitrary Values"
msgstr "任意の値を構築する"

#: ../../extending/extending.rst:813
msgid ""
"This function is the counterpart to :c:func:`PyArg_ParseTuple`.  It is "
"declared as follows::"
msgstr ""
":c:func:`Py_BuildValue` は :c:func:`PyArg_ParseTuple` の対極に位置するもので"
"す。この関数は以下のように定義されています::"

#: ../../extending/extending.rst:816
msgid "PyObject *Py_BuildValue(const char *format, ...);"
msgstr ""

#: ../../extending/extending.rst:818
msgid ""
"It recognizes a set of format units similar to the ones recognized by :c:"
"func:`PyArg_ParseTuple`, but the arguments (which are input to the function, "
"not output) must not be pointers, just values.  It returns a new Python "
"object, suitable for returning from a C function called from Python."
msgstr ""
":c:func:`Py_BuildValue` は、 :c:func:`PyArg_ParseTuple` の認識する一連の書式"
"単位に似た書式単位を認識します。ただし (関数への出力ではなく、入力に使われ"
"る) 引数はポインタではなく、ただの値でなければなりません。 Python から呼び出"
"された C 関数が返す値として適切な、新たな Python オブジェクトを返します。"

#: ../../extending/extending.rst:823
msgid ""
"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires "
"its first argument to be a tuple (since Python argument lists are always "
"represented as tuples internally), :c:func:`Py_BuildValue` does not always "
"build a tuple.  It builds a tuple only if its format string contains two or "
"more format units. If the format string is empty, it returns ``None``; if it "
"contains exactly one format unit, it returns whatever object is described by "
"that format unit.  To force it to return a tuple of size 0 or one, "
"parenthesize the format string."
msgstr ""
":c:func:`PyArg_ParseTuple` とは一つ違う点があります: :c:func:"
"`PyArg_ParseTuple` は第一引数をタプルにする必要があります (Python の引数リス"
"トは内部的には常にタプルとして表現されるからです) が、 :c:func:"
"`Py_BuildValue` はタプルを生成するとは限りません。 :c:func:`Py_BuildValue` は"
"書式文字列中に書式単位が二つかそれ以上入っている場合にのみタプルを構築しま"
"す。書式文字列が空なら、 ``None`` を返します。きっかり一つの書式単位なら、そ"
"の書式単位が記述している何らかのオブジェクトになります。サイズが 0 や 1 のタ"
"プル返させたいのなら、書式文字列を丸括弧で囲います。"

#: ../../extending/extending.rst:831
msgid ""
"Examples (to the left the call, to the right the resulting Python value):"
msgstr ""
"以下に例を示します (左に呼び出し例を、右に構築される Python 値を示します):"

#: ../../extending/extending.rst:833
msgid ""
"Py_BuildValue(\"\")                        None\n"
"Py_BuildValue(\"i\", 123)                  123\n"
"Py_BuildValue(\"iii\", 123, 456, 789)      (123, 456, 789)\n"
"Py_BuildValue(\"s\", \"hello\")              'hello'\n"
"Py_BuildValue(\"y\", \"hello\")              b'hello'\n"
"Py_BuildValue(\"ss\", \"hello\", \"world\")    ('hello', 'world')\n"
"Py_BuildValue(\"s#\", \"hello\", 4)          'hell'\n"
"Py_BuildValue(\"y#\", \"hello\", 4)          b'hell'\n"
"Py_BuildValue(\"()\")                      ()\n"
"Py_BuildValue(\"(i)\", 123)                (123,)\n"
"Py_BuildValue(\"(ii)\", 123, 456)          (123, 456)\n"
"Py_BuildValue(\"(i,i)\", 123, 456)         (123, 456)\n"
"Py_BuildValue(\"[i,i]\", 123, 456)         [123, 456]\n"
"Py_BuildValue(\"{s:i,s:i}\",\n"
"              \"abc\", 123, \"def\", 456)    {'abc': 123, 'def': 456}\n"
"Py_BuildValue(\"((ii)(ii)) (ii)\",\n"
"              1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))"
msgstr ""

#: ../../extending/extending.rst:857
msgid "Reference Counts"
msgstr "参照カウント法"

#: ../../extending/extending.rst:859
msgid ""
"In languages like C or C++, the programmer is responsible for dynamic "
"allocation and deallocation of memory on the heap.  In C, this is done using "
"the functions :c:func:`malloc` and :c:func:`free`.  In C++, the operators "
"``new`` and ``delete`` are used with essentially the same meaning and we'll "
"restrict the following discussion to the C case."
msgstr ""
"C や C++のような言語では、プログラマはヒープ上のメモリを動的に確保したり解放"
"したりする責任があります。こうした作業は C では関数 :c:func:`malloc` や :c:"
"func:`free` で行います。C++では本質的に同じ意味で演算子 ``new`` や "
"``delete`` が使われます。そこで、以下の議論は C の場合に限定して行います。"

#: ../../extending/extending.rst:865
msgid ""
"Every block of memory allocated with :c:func:`malloc` should eventually be "
"returned to the pool of available memory by exactly one call to :c:func:"
"`free`. It is important to call :c:func:`free` at the right time.  If a "
"block's address is forgotten but :c:func:`free` is not called for it, the "
"memory it occupies cannot be reused until the program terminates.  This is "
"called a :dfn:`memory leak`.  On the other hand, if a program calls :c:func:"
"`free` for a block and then continues to use the block, it creates a "
"conflict with reuse of the block through another :c:func:`malloc` call.  "
"This is called :dfn:`using freed memory`. It has the same bad consequences "
"as referencing uninitialized data --- core dumps, wrong results, mysterious "
"crashes."
msgstr ""

#: ../../extending/extending.rst:876
msgid ""
"Common causes of memory leaks are unusual paths through the code.  For "
"instance, a function may allocate a block of memory, do some calculation, "
"and then free the block again.  Now a change in the requirements for the "
"function may add a test to the calculation that detects an error condition "
"and can return prematurely from the function.  It's easy to forget to free "
"the allocated memory block when taking this premature exit, especially when "
"it is added later to the code.  Such leaks, once introduced, often go "
"undetected for a long time: the error exit is taken only in a small fraction "
"of all calls, and most modern machines have plenty of virtual memory, so the "
"leak only becomes apparent in a long-running process that uses the leaking "
"function frequently.  Therefore, it's important to prevent leaks from "
"happening by having a coding convention or strategy that minimizes this kind "
"of errors."
msgstr ""
"よくあるメモリリークの原因はコード中の普通でない処理経路です。例えば、ある関"
"数があるメモリブロックを確保し、何らかの計算を行って、再度ブロックを解放する"
"とします。さて、関数の要求仕様を変更して、計算に対するテストを追加すると、エ"
"ラー条件を検出し、関数の途中で処理を戻すようになるかもしれません。この途中で"
"の終了が起きるとき、確保されたメモリブロックは解放し忘れやすいのです。コード"
"が後で追加された場合には特にそうです。このようなメモリリークが一旦紛れ込んで"
"しまうと、長い間検出されないままになることがよくあります: エラーによる関数の"
"終了は、全ての関数呼び出しのに対してほんのわずかな割合しか起きず、その一方で"
"ほとんどの近代的な計算機は相当量の仮想記憶を持っているため、メモリリークが明"
"らかになるのは、長い間動作していたプロセスがリークを起こす関数を何度も使った"
"場合に限られるからです。従って、この種のエラーを最小限にとどめるようなコー"
"ディング規約や戦略を設けて、不慮のメモリリークを避けることが重要なのです。"

#: ../../extending/extending.rst:889
msgid ""
"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it "
"needs a strategy to avoid memory leaks as well as the use of freed memory.  "
"The chosen method is called :dfn:`reference counting`.  The principle is "
"simple: every object contains a counter, which is incremented when a "
"reference to the object is stored somewhere, and which is decremented when a "
"reference to it is deleted. When the counter reaches zero, the last "
"reference to the object has been deleted and the object is freed."
msgstr ""
"Python は :c:func:`malloc` や :c:func:`free` を非常によく利用するため、メモリ"
"リークの防止に加え、解放されたメモリの使用を防止する戦略が必要です。このため"
"に選ばれたのが参照カウント法 (:dfn:`reference counting`) と呼ばれる手法です。"
"参照カウント法の原理は簡単です: 全てのオブジェクトにはカウンタがあり、オブ"
"ジェクトに対する参照がどこかに保存されたらカウンタをインクリメントし、オブ"
"ジェクトに対する参照が削除されたらデクリメントします。カウンタがゼロになった"
"ら、オブジェクトへの最後の参照が削除されたことになり、オブジェクトは解放され"
"ます。"

#: ../../extending/extending.rst:897
msgid ""
"An alternative strategy is called :dfn:`automatic garbage collection`. "
"(Sometimes, reference counting is also referred to as a garbage collection "
"strategy, hence my use of \"automatic\" to distinguish the two.)  The big "
"advantage of automatic garbage collection is that the user doesn't need to "
"call :c:func:`free` explicitly.  (Another claimed advantage is an "
"improvement in speed or memory usage --- this is no hard fact however.)  The "
"disadvantage is that for C, there is no truly portable automatic garbage "
"collector, while reference counting can be implemented portably (as long as "
"the functions :c:func:`malloc` and :c:func:`free` are available --- which "
"the C Standard guarantees). Maybe some day a sufficiently portable automatic "
"garbage collector will be available for C. Until then, we'll have to live "
"with reference counts."
msgstr ""
"もう一つの戦略は自動ガベージコレクション (:dfn:`automatic garbage "
"collection`) と呼ばれています。 (参照カウント法はガベージコレクション戦略の一"
"つとして挙げられることもあるので、二つを区別するために筆者は \"自動 "
"(automatic)\" を使っています。) 自動ガベージコレクションの大きな利点は、ユー"
"ザが :c:func:`free` を明示的によばなくてよいことにあります。 (速度やメモリの"
"有効利用性も利点として主張されています --- が、これは確たる事実ではありませ"
"ん。) C における自動ガベージコレクションの欠点は、真に可搬性のあるガベージコ"
"レクタが存在しないということです。それに対し、参照カウント法は可搬性のある実"
"装ができます (:c:func:`malloc` や :c:func:`free` を利用できるのが前提です "
"--- C 標準はこれを保証しています)。いつの日か、十分可搬性のあるガベージコレク"
"タが C で使えるようになるかもしれませんが、それまでは参照カウント法でやってい"
"く以外にはないのです。"

#: ../../extending/extending.rst:909
msgid ""
"While Python uses the traditional reference counting implementation, it also "
"offers a cycle detector that works to detect reference cycles.  This allows "
"applications to not worry about creating direct or indirect circular "
"references; these are the weakness of garbage collection implemented using "
"only reference counting.  Reference cycles consist of objects which contain "
"(possibly indirect) references to themselves, so that each object in the "
"cycle has a reference count which is non-zero.  Typical reference counting "
"implementations are not able to reclaim the memory belonging to any objects "
"in a reference cycle, or referenced from the objects in the cycle, even "
"though there are no further references to the cycle itself."
msgstr ""
"Python では、伝統的な参照カウント法の実装を行っている一方で、参照の循環を検出"
"するために働く循環参照検出機構 (cycle detector) も提供しています。循環参照検"
"出機構のおかげで、直接、間接にかかわらず循環参照の生成を気にせずにアプリケー"
"ションを構築できます; というのも、参照カウント法だけを使ったガベージコレク"
"ション実装にとって循環参照は弱点だからです。循環参照は、(間接参照の場合も含め"
"て) 相互への参照が入ったオブジェクトから形成されるため、循環内のオブジェクト"
"は各々非ゼロの参照カウントを持ちます。典型的な参照カウント法の実装では、たと"
"え循環参照を形成するオブジェクトに対して他に全く参照がないとしても、循環参照"
"内のどのオブジェクトに属するメモリも再利用できません。"

#: ../../extending/extending.rst:920
msgid ""
"The cycle detector is able to detect garbage cycles and can reclaim them. "
"The :mod:`gc` module exposes a way to run the detector (the :func:`~gc."
"collect` function), as well as configuration interfaces and the ability to "
"disable the detector at runtime."
msgstr ""
"循環参照検出機構はそのようなガベージサイクル (前述したような循環参照オブジェ"
"クト) を検出して回収することができます。\n"
":mod:`gc` モジュールそのような検出機構の実行 (:func:`~gc.collect` 関数) を提"
"供するとともに、設定のためのインタフェースおよび検出機構を実行時に無効にする"
"方法も提供しています。"

#: ../../extending/extending.rst:929
msgid "Reference Counting in Python"
msgstr "Python における参照カウント法"

#: ../../extending/extending.rst:931
msgid ""
"There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle "
"the incrementing and decrementing of the reference count. :c:func:"
"`Py_DECREF` also frees the object when the count reaches zero. For "
"flexibility, it doesn't call :c:func:`free` directly --- rather, it makes a "
"call through a function pointer in the object's :dfn:`type object`.  For "
"this purpose (and others), every object also contains a pointer to its type "
"object."
msgstr ""
"Python には、参照カウントのインクリメントやデクリメントを処理する二つのマク"
"ロ、 ``Py_INCREF(x)`` と ``Py_DECREF(x)`` があります。 :c:func:`Py_DECREF` "
"は、参照カウントがゼロに到達した際に、オブジェクトのメモリ解放も行います。柔"
"軟性を持たせるために、 :c:func:`free` を直接呼び出しません --- その代わりにオ"
"ブジェクトの型オブジェクト (:dfn:`type object`) を介します。このために (他の"
"目的もありますが)、全てのオブジェクトには自身の型オブジェクトに対するポインタ"
"が入っています。"

#: ../../extending/extending.rst:938
msgid ""
"The big question now remains: when to use ``Py_INCREF(x)`` and "
"``Py_DECREF(x)``? Let's first introduce some terms.  Nobody \"owns\" an "
"object; however, you can :dfn:`own a reference` to an object.  An object's "
"reference count is now defined as the number of owned references to it.  The "
"owner of a reference is responsible for calling :c:func:`Py_DECREF` when the "
"reference is no longer needed.  Ownership of a reference can be "
"transferred.  There are three ways to dispose of an owned reference: pass it "
"on, store it, or call :c:func:`Py_DECREF`. Forgetting to dispose of an owned "
"reference creates a memory leak."
msgstr ""
"さて、まだ重大な疑問が残っています: いつ ``Py_INCREF(x)`` や "
"``Py_DECREF(x)`` を使えばよいのでしょうか? まず、いくつかの用語説明から始めさ"
"せてください。まず、オブジェクトは \"占有 (own)\" されることはありません; し"
"かし、あるオブジェクトに対する参照の所有 :dfn:`own a reference` はできます。"
"オブジェクトの参照カウントは、そのオブジェクトが参照の所有を受けている回数と"
"定義されています。参照の所有者は、参照が必要なくなった際に :c:func:"
"`Py_DECREF` を呼び出す役割を担います。参照の所有権は委譲 (transfer) できま"
"す。所有参照 (owned reference) の放棄には、渡す、保存する、 :c:func:"
"`Py_DECREF` を呼び出す、という三つの方法があります。所有参照を処理し忘れる"
"と、メモリリークを引き起こします。"

#: ../../extending/extending.rst:947
msgid ""
"It is also possible to :dfn:`borrow` [#]_ a reference to an object.  The "
"borrower of a reference should not call :c:func:`Py_DECREF`.  The borrower "
"must not hold on to the object longer than the owner from which it was "
"borrowed. Using a borrowed reference after the owner has disposed of it "
"risks using freed memory and should be avoided completely [#]_."
msgstr ""
"オブジェクトに対する参照は、借用 (:dfn:`borrow`) も可能です。 [#]_ 参照の借用"
"者は、 :c:func:`Py_DECREF` を呼んではなりません。借用者は、参照の所有者から借"
"用した期間を超えて参照を保持し続けてはなりません。所有者が参照を放棄した後で"
"借用参照を使うと、解放済みメモリを使用してしまう危険があるので、絶対に避けね"
"ばなりません。 [#]_"

#: ../../extending/extending.rst:953
msgid ""
"The advantage of borrowing over owning a reference is that you don't need to "
"take care of disposing of the reference on all possible paths through the "
"code --- in other words, with a borrowed reference you don't run the risk of "
"leaking when a premature exit is taken.  The disadvantage of borrowing over "
"owning is that there are some subtle situations where in seemingly correct "
"code a borrowed reference can be used after the owner from which it was "
"borrowed has in fact disposed of it."
msgstr ""
"参照の借用が参照の所有よりも優れている点は、コードがとりうるあらゆる処理経路"
"で参照を廃棄しておくよう注意しなくて済むことです --- 別の言い方をすれば、借用"
"参照の場合には、処理の途中で関数を終了してもメモリリークの危険を冒すことがな"
"い、ということです。逆に、所有よりも不利な点は、ごくまともに見えるコードが、"
"実際には参照の借用元で放棄されてしまった後にその参照を使うかもしれないような"
"微妙な状況があるということです。"

#: ../../extending/extending.rst:961
msgid ""
"A borrowed reference can be changed into an owned reference by calling :c:"
"func:`Py_INCREF`.  This does not affect the status of the owner from which "
"the reference was borrowed --- it creates a new owned reference, and gives "
"full owner responsibilities (the new owner must dispose of the reference "
"properly, as well as the previous owner)."
msgstr ""
":c:func:`Py_INCREF` を呼び出すと、借用参照を所有参照に変更できます。この操作"
"は参照の借用元の状態には影響しません --- :c:func:`Py_INCREF` は新たな所有参照"
"を生成し、参照の所有者が担うべき全ての責任を課します (つまり、新たな参照の所"
"有者は、以前の所有者と同様、参照の放棄を適切に行わねばなりません)。"

#: ../../extending/extending.rst:971
msgid "Ownership Rules"
msgstr "所有権にまつわる規則"

#: ../../extending/extending.rst:973
msgid ""
"Whenever an object reference is passed into or out of a function, it is part "
"of the function's interface specification whether ownership is transferred "
"with the reference or not."
msgstr ""
"オブジェクトへの参照を関数の内外に渡す場合には、オブジェクトの所有権が参照と"
"共に渡されるか否かが常に関数インターフェース仕様の一部となります。"

#: ../../extending/extending.rst:977
msgid ""
"Most functions that return a reference to an object pass on ownership with "
"the reference.  In particular, all functions whose function it is to create "
"a new object, such as :c:func:`PyLong_FromLong` and :c:func:`Py_BuildValue`, "
"pass ownership to the receiver.  Even if the object is not actually new, you "
"still receive ownership of a new reference to that object.  For instance, :c:"
"func:`PyLong_FromLong` maintains a cache of popular values and can return a "
"reference to a cached item."
msgstr ""
"オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も渡します。特"
"に、 :c:func:`PyLong_FromLong` や :c:func:`Py_BuildValue` のように、新しいオ"
"ブジェクトを生成する関数は全て所有権を相手に渡します。オブジェクトが実際には"
"新たなオブジェクトでなくても、そのオブジェクトに対する新たな参照の所有権を得"
"ます。例えば、 :c:func:`PyLong_FromLong` はよく使う値をキャッシュしており、"
"キャッシュされた値への参照を返すことがあります。"

#: ../../extending/extending.rst:985
msgid ""
"Many functions that extract objects from other objects also transfer "
"ownership with the reference, for instance :c:func:"
"`PyObject_GetAttrString`.  The picture is less clear, here, however, since a "
"few common routines are exceptions: :c:func:`PyTuple_GetItem`, :c:func:"
"`PyList_GetItem`, :c:func:`PyDict_GetItem`, and :c:func:"
"`PyDict_GetItemString` all return references that you borrow from the tuple, "
"list or dictionary."
msgstr ""
":c:func:`PyObject_GetAttrString` のように、あるオブジェクトから別のオブジェク"
"トを抽出するような関数もまた、参照とともに所有権を委譲します。こちらの方はや"
"や理解しにくいかもしれません。というのはよく使われるルーチンのいくつかが例外"
"となっているからです: :c:func:`PyTuple_GetItem` 、 :c:func:"
"`PyList_GetItem` 、 :c:func:`PyDict_GetItem` 、および :c:func:"
"`PyDict_GetItemString` は全て、タプル、リスト、または辞書から借用参照を返しま"
"す。"

#: ../../extending/extending.rst:992
msgid ""
"The function :c:func:`PyImport_AddModule` also returns a borrowed reference, "
"even though it may actually create the object it returns: this is possible "
"because an owned reference to the object is stored in ``sys.modules``."
msgstr ""
":c:func:`PyImport_AddModule` は、実際にはオブジェクトを生成して返すことがある"
"にもかかわらず、借用参照を返します: これが可能なのは、生成されたオブジェクト"
"に対する所有参照は ``sys.modules`` に保持されるからです。"

#: ../../extending/extending.rst:996
msgid ""
"When you pass an object reference into another function, in general, the "
"function borrows the reference from you --- if it needs to store it, it will "
"use :c:func:`Py_INCREF` to become an independent owner.  There are exactly "
"two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:"
"`PyList_SetItem`.  These functions take over ownership of the item passed to "
"them --- even if they fail!  (Note that :c:func:`PyDict_SetItem` and friends "
"don't take over ownership --- they are \"normal.\")"
msgstr ""
"オブジェクトへの参照を別の関数に渡す場合、一般的には、関数側は呼び出し手から"
"参照を借用します --- 参照を保存する必要があるなら、関数側は :c:func:"
"`Py_INCREF` を呼び出して独立した所有者になります。とはいえ、この規則には二つ"
"の重要な例外: :c:func:`PyTuple_SetItem` と :c:func:`PyList_SetItem` がありま"
"す。これらの関数は、渡された引数要素に対して所有権を乗っ取り (take over) ま"
"す --- たとえ失敗してもです! (:c:func:`PyDict_SetItem` とその仲間は所有権を"
"乗っ取りません --- これらはいわば \"普通の\" 関数です。)"

#: ../../extending/extending.rst:1004
msgid ""
"When a C function is called from Python, it borrows references to its "
"arguments from the caller.  The caller owns a reference to the object, so "
"the borrowed reference's lifetime is guaranteed until the function returns.  "
"Only when such a borrowed reference must be stored or passed on, it must be "
"turned into an owned reference by calling :c:func:`Py_INCREF`."
msgstr ""
"Python から C 関数が呼び出される際には、C 関数は呼び出し側から引数への参照を"
"借用します。C 関数の呼び出し側はオブジェクトへの参照を所有しているので、借用"
"参照の生存期間が保証されるのは関数が処理を返すまでです。このようにして借用参"
"照を保存したり他に渡したりしたい場合にのみ、 :c:func:`Py_INCREF` を使って所有"
"参照にする必要があります。"

#: ../../extending/extending.rst:1010
msgid ""
"The object reference returned from a C function that is called from Python "
"must be an owned reference --- ownership is transferred from the function to "
"its caller."
msgstr ""
"Python から呼び出された C 関数が返す参照は所有参照でなければなりません --- 所"
"有権は関数から呼び出し側へと委譲されます。"

#: ../../extending/extending.rst:1018
msgid "Thin Ice"
msgstr "薄氷"

#: ../../extending/extending.rst:1020
msgid ""
"There are a few situations where seemingly harmless use of a borrowed "
"reference can lead to problems.  These all have to do with implicit "
"invocations of the interpreter, which can cause the owner of a reference to "
"dispose of it."
msgstr ""
"数少ない状況において、一見無害に見える借用参照の利用が問題をひきおこすことが"
"あります。この問題はすべて、インタプリタが非明示的に呼び出され、インタプリタ"
"が参照の所有者に参照を放棄させてしまう状況と関係しています。"

#: ../../extending/extending.rst:1024
msgid ""
"The first and most important case to know about is using :c:func:`Py_DECREF` "
"on an unrelated object while borrowing a reference to a list item.  For "
"instance::"
msgstr ""
"知っておくべきケースのうち最初の、そして最も重要なものは、リスト要素に対する"
"参照を借りている際に起きる、関係ないオブジェクトに対する :c:func:`Py_DECREF` "
"の使用です。例えば::"

#: ../../extending/extending.rst:1027
msgid ""
"void\n"
"bug(PyObject *list)\n"
"{\n"
"    PyObject *item = PyList_GetItem(list, 0);\n"
"\n"
"    PyList_SetItem(list, 1, PyLong_FromLong(0L));\n"
"    PyObject_Print(item, stdout, 0); /* BUG! */\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1036
msgid ""
"This function first borrows a reference to ``list[0]``, then replaces "
"``list[1]`` with the value ``0``, and finally prints the borrowed reference. "
"Looks harmless, right?  But it's not!"
msgstr ""
"上の関数はまず、 ``list[0]`` への参照を借用し、次に ``list[1]`` を値 ``0`` で"
"置き換え、最後にさきほど借用した参照を出力しています。何も問題ないように見え"
"ますね? でもそうではないのです!"

#: ../../extending/extending.rst:1040
msgid ""
"Let's follow the control flow into :c:func:`PyList_SetItem`.  The list owns "
"references to all its items, so when item 1 is replaced, it has to dispose "
"of the original item 1.  Now let's suppose the original item 1 was an "
"instance of a user-defined class, and let's further suppose that the class "
"defined a :meth:`!__del__` method.  If this class instance has a reference "
"count of 1, disposing of it will call its :meth:`!__del__` method."
msgstr ""

#: ../../extending/extending.rst:1047
msgid ""
"Since it is written in Python, the :meth:`!__del__` method can execute "
"arbitrary Python code.  Could it perhaps do something to invalidate the "
"reference to ``item`` in :c:func:`!bug`?  You bet!  Assuming that the list "
"passed into :c:func:`!bug` is accessible to the :meth:`!__del__` method, it "
"could execute a statement to the effect of ``del list[0]``, and assuming "
"this was the last reference to that object, it would free the memory "
"associated with it, thereby invalidating ``item``."
msgstr ""

#: ../../extending/extending.rst:1055
msgid ""
"The solution, once you know the source of the problem, is easy: temporarily "
"increment the reference count.  The correct version of the function reads::"
msgstr ""
"問題の原因が分かれば、解決は簡単です。一時的に参照回数を増やせばよいのです。"
"正しく動作するバージョンは以下のようになります::"

#: ../../extending/extending.rst:1058
msgid ""
"void\n"
"no_bug(PyObject *list)\n"
"{\n"
"    PyObject *item = PyList_GetItem(list, 0);\n"
"\n"
"    Py_INCREF(item);\n"
"    PyList_SetItem(list, 1, PyLong_FromLong(0L));\n"
"    PyObject_Print(item, stdout, 0);\n"
"    Py_DECREF(item);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1069
msgid ""
"This is a true story.  An older version of Python contained variants of this "
"bug and someone spent a considerable amount of time in a C debugger to "
"figure out why his :meth:`!__del__` methods would fail..."
msgstr ""

#: ../../extending/extending.rst:1073
msgid ""
"The second case of problems with a borrowed reference is a variant involving "
"threads.  Normally, multiple threads in the Python interpreter can't get in "
"each other's way, because there is a global lock protecting Python's entire "
"object space.  However, it is possible to temporarily release this lock "
"using the macro :c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it "
"using :c:macro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O "
"calls, to let other threads use the processor while waiting for the I/O to "
"complete. Obviously, the following function has the same problem as the "
"previous one::"
msgstr ""
"二つ目は、借用参照がスレッドに関係しているケースです。通常は、 Python インタ"
"プリタにおける複数のスレッドは、グローバルインタプリタロックがオブジェクト空"
"間全体を保護しているため、互いに邪魔し合うことはありません。とはいえ、ロック"
"は :c:macro:`Py_BEGIN_ALLOW_THREADS` マクロで一時的に解除したり、 :c:macro:"
"`Py_END_ALLOW_THREADS` で再獲得したりできます。これらのマクロはブロックの起こ"
"る I/O 呼び出しの周囲によく置かれ、 I/O が完了するまでの間に他のスレッドがプ"
"ロセッサを利用できるようにします。明らかに、以下の関数は上の例と似た問題をは"
"らんでいます::"

#: ../../extending/extending.rst:1082
msgid ""
"void\n"
"bug(PyObject *list)\n"
"{\n"
"    PyObject *item = PyList_GetItem(list, 0);\n"
"    Py_BEGIN_ALLOW_THREADS\n"
"    ...some blocking I/O call...\n"
"    Py_END_ALLOW_THREADS\n"
"    PyObject_Print(item, stdout, 0); /* BUG! */\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1096
msgid "NULL Pointers"
msgstr "NULL ポインタ"

#: ../../extending/extending.rst:1098
msgid ""
"In general, functions that take object references as arguments do not expect "
"you to pass them ``NULL`` pointers, and will dump core (or cause later core "
"dumps) if you do so.  Functions that return object references generally "
"return ``NULL`` only to indicate that an exception occurred.  The reason for "
"not testing for ``NULL`` arguments is that functions often pass the objects "
"they receive on to other function --- if each function were to test for "
"``NULL``, there would be a lot of redundant tests and the code would run "
"more slowly."
msgstr ""
"一般論として、オブジェクトへの参照を引数にとる関数はユーザが ``NULL`` ポイン"
"タを渡すとは予想しておらず、渡そうとするとコアダンプになる (か、あとでコアダ"
"ンプを引き起こす) ことでしょう。一方、オブジェクトへの参照を返すような関数は"
"一般に、例外の発生を示す場合にのみ ``NULL`` を返します。引数に対して "
"``NULL`` テストを行わない理由は、関数はしばしば受け取ったオブジェクトを他の関"
"数へと引き渡すからです --- 各々の関数が ``NULL`` テストを行えば、冗長なテスト"
"が大量に行われ、コードはより低速に動くことになります。"

#: ../../extending/extending.rst:1106
msgid ""
"It is better to test for ``NULL`` only at the \"source:\" when a pointer "
"that may be ``NULL`` is received, for example, from :c:func:`malloc` or from "
"a function that may raise an exception."
msgstr ""
"従って、 ``NULL`` のテストはオブジェクトの \"発生源\"、すなわち値が ``NULL`` "
"になるかもしれないポインタを受け取ったときだけにしましょう。 :c:func:"
"`malloc` や、例外を送出する可能性のある関数がその例です。"

#: ../../extending/extending.rst:1110
msgid ""
"The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for "
"``NULL`` pointers --- however, their variants :c:func:`Py_XINCREF` and :c:"
"func:`Py_XDECREF` do."
msgstr ""
"マクロ :c:func:`Py_INCREF` および :c:func:`Py_DECREF` は ``NULL`` ポインタの"
"チェックを行いません --- しかし、これらのマクロの変化形である :c:func:"
"`Py_XINCREF` および :c:func:`Py_XDECREF` はチェックを行います。"

#: ../../extending/extending.rst:1114
msgid ""
"The macros for checking for a particular object type (``Pytype_Check()``) "
"don't check for ``NULL`` pointers --- again, there is much code that calls "
"several of these in a row to test an object against various different "
"expected types, and this would generate redundant tests.  There are no "
"variants with ``NULL`` checking."
msgstr ""
"特定のオブジェクト型について調べるマクロ (``Pytype_Check()``) は *NULL* ポイ"
"ンタのチェックを行いません --- 繰り返しますが、様々な異なる型を想定してオブ"
"ジェクトの型を調べる際には、こうしたマクロを続けて呼び出す必要があるので、個"
"別に ``NULL`` ポインタのチェックをすると冗長なテストになってしまうのです。型"
"を調べるマクロには、 ``NULL`` チェックを行う変化形はありません。"

#: ../../extending/extending.rst:1120
msgid ""
"The C function calling mechanism guarantees that the argument list passed to "
"C functions (``args`` in the examples) is never ``NULL`` --- in fact it "
"guarantees that it is always a tuple [#]_."
msgstr ""
"Python から C 関数を呼び出す機構は、C 関数に渡される引数リスト (例でいうとこ"
"ろの ``args``) が決して ``NULL`` にならないよう保証しています --- 実際には、"
"常にタプル型になるよう保証しています。[#]_"

#: ../../extending/extending.rst:1124
msgid ""
"It is a severe error to ever let a ``NULL`` pointer \"escape\" to the Python "
"user."
msgstr ""
"``NULL`` ポインタを Python ユーザレベルに \"逃がし\" てしまうと、深刻なエラー"
"を引き起こします。"

#: ../../extending/extending.rst:1135
msgid "Writing Extensions in C++"
msgstr "C++での拡張モジュール作成"

#: ../../extending/extending.rst:1137
msgid ""
"It is possible to write extension modules in C++.  Some restrictions apply.  "
"If the main program (the Python interpreter) is compiled and linked by the C "
"compiler, global or static objects with constructors cannot be used.  This "
"is not a problem if the main program is linked by the C++ compiler.  "
"Functions that will be called by the Python interpreter (in particular, "
"module initialization functions) have to be declared using ``extern \"C\"``. "
"It is unnecessary to enclose the Python header files in ``extern \"C\" {...}"
"`` --- they use this form already if the symbol ``__cplusplus`` is defined "
"(all recent C++ compilers define this symbol)."
msgstr ""
"C++でも拡張モジュールは作成できます。ただしいくつか制限があります。メインプロ"
"グラム (Python インタプリタ) は C コンパイラでコンパイルされリンクされている"
"ので、グローバル変数や静的オブジェクトをコンストラクタで作成できません。メイ"
"ンプログラムが C++ コンパイラでリンクされているならこれは問題ではありませ"
"ん。 Python インタプリタから呼び出される関数 (特にモジュール初期化関数) は、 "
"``extern \"C\"`` を使って宣言しなければなりません。また、Python ヘッダファイ"
"ルを ``extern \"C\" {...}`` に入れる必要はありません--- シンボル "
"``__cplusplus`` (最近の C++ コンパイラは全てこのシンボルを定義しています) が"
"定義されているときに ``extern \"C\" {...}`` が行われるように、ヘッダファイル"
"内にすでに書かれているからです。"

#: ../../extending/extending.rst:1151
msgid "Providing a C API for an Extension Module"
msgstr "拡張モジュールに C API を提供する"

#: ../../extending/extending.rst:1156
msgid ""
"Many extension modules just provide new functions and types to be used from "
"Python, but sometimes the code in an extension module can be useful for "
"other extension modules. For example, an extension module could implement a "
"type \"collection\" which works like lists without order. Just like the "
"standard Python list type has a C API which permits extension modules to "
"create and manipulate lists, this new collection type should have a set of C "
"functions for direct manipulation from other extension modules."
msgstr ""
"多くの拡張モジュールは単に Python から使える新たな関数や型を提供するだけです"
"が、時に拡張モジュール内のコードが他の拡張モジュールでも便利なことがありま"
"す。例えば、あるモジュールでは順序概念のないリストのように動作する \"コレク"
"ション (collection)\" クラスを実装しているかもしれません。ちょうどリストを生"
"成したり操作したりできる C API を備えた標準の Python リスト型のように、この新"
"たなコレクション型も他の拡張モジュールから直接操作できるようにするには一連の "
"C 関数を持っていなければなりません。"

#: ../../extending/extending.rst:1164
msgid ""
"At first sight this seems easy: just write the functions (without declaring "
"them ``static``, of course), provide an appropriate header file, and "
"document the C API. And in fact this would work if all extension modules "
"were always linked statically with the Python interpreter. When modules are "
"used as shared libraries, however, the symbols defined in one module may not "
"be visible to another module. The details of visibility depend on the "
"operating system; some systems use one global namespace for the Python "
"interpreter and all extension modules (Windows, for example), whereas others "
"require an explicit list of imported symbols at module link time (AIX is one "
"example), or offer a choice of different strategies (most Unices). And even "
"if symbols are globally visible, the module whose functions one wishes to "
"call might not have been loaded yet!"
msgstr ""
"一見するとこれは簡単なこと: 単に関数を (もちろん ``static`` などとは宣言せず"
"に) 書いて、適切なヘッダファイルを提供し、C API を書けばよいだけ、に思えま"
"す。そして実際のところ、全ての拡張モジュールが Python インタプリタに常に静的"
"にリンクされている場合にはうまく動作します。ところがモジュールが共有ライブラ"
"リの場合には、一つのモジュールで定義されているシンボルが他のモジュールから不"
"可視なことがあります。可視性の詳細はオペレーティングシステムによります; ある"
"システムは Python インタプリタと全ての拡張モジュール用に単一のグローバルな名"
"前空間を用意しています (例えば Windows)。別のシステムはモジュールのリンク時に"
"取り込まれるシンボルを明示的に指定する必要があります (AIX がその一例です)、ま"
"た別のシステム (ほとんどの Unix) では、違った戦略を選択肢として提供していま"
"す。そして、たとえシンボルがグローバル変数として可視であっても、呼び出したい"
"関数の入ったモジュールがまだロードされていないことだってあります!"

#: ../../extending/extending.rst:1176
msgid ""
"Portability therefore requires not to make any assumptions about symbol "
"visibility. This means that all symbols in extension modules should be "
"declared ``static``, except for the module's initialization function, in "
"order to avoid name clashes with other extension modules (as discussed in "
"section :ref:`methodtable`). And it means that symbols that *should* be "
"accessible from other extension modules must be exported in a different way."
msgstr ""
"従って、可搬性の点からシンボルの可視性には何ら仮定をしてはならないことになり"
"ます。つまり拡張モジュール中の全てのシンボルは ``static`` と宣言せねばなりま"
"せん。例外はモジュールの初期化関数で、これは (:ref:`methodtable` で述べたよう"
"に) 他の拡張モジュールとの間で名前が衝突するのを避けるためです。また、他の拡"
"張モジュールからアクセスを *受けるべきではない* シンボルは別のやり方で公開せ"
"ねばなりません。"

#: ../../extending/extending.rst:1183
msgid ""
"Python provides a special mechanism to pass C-level information (pointers) "
"from one extension module to another one: Capsules. A Capsule is a Python "
"data type which stores a pointer (:c:expr:`void \\*`).  Capsules can only be "
"created and accessed via their C API, but they can be passed around like any "
"other Python object. In particular,  they can be assigned to a name in an "
"extension module's namespace. Other extension modules can then import this "
"module, retrieve the value of this name, and then retrieve the pointer from "
"the Capsule."
msgstr ""
"Python はある拡張モジュールの C レベルの情報 (ポインタ) を別のモジュールに渡"
"すための特殊な機構: Capsule (カプセル)を提供しています。 Capsule はポインタ "
"(:c:expr:`void \\*`) を記憶する Python のデータ型です。 Capsule は C API を介"
"してのみ生成したりアクセスしたりできますが、他の Python オブジェクトと同じよ"
"うに受け渡しできます。とりわけ、Capsule は拡張モジュールの名前空間内にある名"
"前に代入できます。他の拡張モジュールはこのモジュールを import でき、次に名前"
"を取得し、最後にCapsule へのポインタを取得します。"

#: ../../extending/extending.rst:1191
msgid ""
"There are many ways in which Capsules can be used to export the C API of an "
"extension module. Each function could get its own Capsule, or all C API "
"pointers could be stored in an array whose address is published in a "
"Capsule. And the various tasks of storing and retrieving the pointers can be "
"distributed in different ways between the module providing the code and the "
"client modules."
msgstr ""
"拡張モジュールの C API を公開するために、様々な方法で Capsule が使われます。"
"各関数を1つのオブジェクトに入れたり、全ての C API のポインタ配列を Capsule に"
"入れることができます。そして、ポインタに対する保存や取得といった様々な作業"
"は、コードを提供しているモジュールとクライアントモジュールとの間では異なる方"
"法で分散できます。"

#: ../../extending/extending.rst:1197
msgid ""
"Whichever method you choose, it's important to name your Capsules properly. "
"The function :c:func:`PyCapsule_New` takes a name parameter (:c:expr:`const "
"char \\*`); you're permitted to pass in a ``NULL`` name, but we strongly "
"encourage you to specify a name.  Properly named Capsules provide a degree "
"of runtime type-safety; there is no feasible way to tell one unnamed Capsule "
"from another."
msgstr ""
"どの方法を選ぶにしても、 Capsule の name を正しく設定することは重要です。 :c:"
"func:`PyCapsule_New` は name 引数 (:c:expr:`const char \\*`) を取ります。 "
"``NULL`` を name に渡すことも許可されていますが、 name を設定することを強く推"
"奨します。正しく名前を付けられた Capsule はある程度の実行時型安全性を持ちま"
"す。名前を付けられていない Capsule を他の Capsule と区別する現実的な方法はあ"
"りません。"

#: ../../extending/extending.rst:1204
msgid ""
"In particular, Capsules used to expose C APIs should be given a name "
"following this convention::"
msgstr ""
"特に、 C API を公開するための Capsule には次のルールに従った名前を付けるべき"
"です::"

#: ../../extending/extending.rst:1207
msgid "modulename.attributename"
msgstr ""

#: ../../extending/extending.rst:1209
msgid ""
"The convenience function :c:func:`PyCapsule_Import` makes it easy to load a "
"C API provided via a Capsule, but only if the Capsule's name matches this "
"convention.  This behavior gives C API users a high degree of certainty that "
"the Capsule they load contains the correct C API."
msgstr ""
":c:func:`PyCapsule_Import` という便利関数は、 Capsule の名前がこのルールに一"
"致しているときにのみ、簡単に Capsule 経由で公開されている C API をロードする"
"ことができます。この挙動により、 C API のユーザーが、確実に正しい C API を格"
"納している Capsule をロードできたことを確かめることができます。"

#: ../../extending/extending.rst:1214
msgid ""
"The following example demonstrates an approach that puts most of the burden "
"on the writer of the exporting module, which is appropriate for commonly "
"used library modules. It stores all C API pointers (just one in the "
"example!) in an array of :c:expr:`void` pointers which becomes the value of "
"a Capsule. The header file corresponding to the module provides a macro that "
"takes care of importing the module and retrieving its C API pointers; client "
"modules only have to call this macro before accessing the C API."
msgstr ""
"以下の例では、名前を公開するモジュールの作者にほとんどの負荷が掛かりますが、"
"よく使われるライブラリを作る際に適切なアプローチを実演します。このアプローチ"
"では、全ての C API ポインタ (例中では一つだけですが!) を、 Capsule の値とな"
"る :c:expr:`void` ポインタの配列に保存します。拡張モジュールに対応するヘッダ"
"ファイルは、モジュールの import と C API ポインタを取得するよう手配するマクロ"
"を提供します; クライアントモジュールは、C API にアクセスする前にこのマクロを"
"呼ぶだけです。"

#: ../../extending/extending.rst:1222
msgid ""
"The exporting module is a modification of the :mod:`!spam` module from "
"section :ref:`extending-simpleexample`. The function :func:`!spam.system` "
"does not call the C library function :c:func:`system` directly, but a "
"function :c:func:`!PySpam_System`, which would of course do something more "
"complicated in reality (such as adding \"spam\" to every command). This "
"function :c:func:`!PySpam_System` is also exported to other extension "
"modules."
msgstr ""

#: ../../extending/extending.rst:1229
msgid ""
"The function :c:func:`!PySpam_System` is a plain C function, declared "
"``static`` like everything else::"
msgstr ""

#: ../../extending/extending.rst:1232
msgid ""
"static int\n"
"PySpam_System(const char *command)\n"
"{\n"
"    return system(command);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1238
msgid "The function :c:func:`!spam_system` is modified in a trivial way::"
msgstr ""

#: ../../extending/extending.rst:1240
msgid ""
"static PyObject *\n"
"spam_system(PyObject *self, PyObject *args)\n"
"{\n"
"    const char *command;\n"
"    int sts;\n"
"\n"
"    if (!PyArg_ParseTuple(args, \"s\", &command))\n"
"        return NULL;\n"
"    sts = PySpam_System(command);\n"
"    return PyLong_FromLong(sts);\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1252
msgid "In the beginning of the module, right after the line ::"
msgstr "モジュールの先頭にある以下の行 ::"

#: ../../extending/extending.rst:1254
msgid "#include <Python.h>"
msgstr ""

#: ../../extending/extending.rst:1256
msgid "two more lines must be added::"
msgstr "の直後に、以下の二行を必ず追加してください::"

#: ../../extending/extending.rst:1258
msgid ""
"#define SPAM_MODULE\n"
"#include \"spammodule.h\""
msgstr ""

#: ../../extending/extending.rst:1261
msgid ""
"The ``#define`` is used to tell the header file that it is being included in "
"the exporting module, not a client module. Finally, the module's "
"initialization function must take care of initializing the C API pointer "
"array::"
msgstr ""
"``#define`` は、ファイル :file:`spammodule.h` をインクルードしているのが名前"
"を公開する側のモジュールであって、クライアントモジュールではないことをヘッダ"
"ファイルに教えるために使われます。最後に、モジュールの初期化関数は C API のポ"
"インタ配列を初期化するよう手配しなければなりません::"

#: ../../extending/extending.rst:1265
msgid ""
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    PyObject *m;\n"
"    static void *PySpam_API[PySpam_API_pointers];\n"
"    PyObject *c_api_object;\n"
"\n"
"    m = PyModule_Create(&spammodule);\n"
"    if (m == NULL)\n"
"        return NULL;\n"
"\n"
"    /* Initialize the C API pointer array */\n"
"    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;\n"
"\n"
"    /* Create a Capsule containing the API pointer array's address */\n"
"    c_api_object = PyCapsule_New((void *)PySpam_API, \"spam._C_API\", "
"NULL);\n"
"\n"
"    if (PyModule_Add(m, \"_C_API\", c_api_object) < 0) {\n"
"        Py_DECREF(m);\n"
"        return NULL;\n"
"    }\n"
"\n"
"    return m;\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1290
msgid ""
"Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array "
"would disappear when :c:func:`!PyInit_spam` terminates!"
msgstr ""

#: ../../extending/extending.rst:1293
msgid ""
"The bulk of the work is in the header file :file:`spammodule.h`, which looks "
"like this::"
msgstr ""
"からくりの大部分はヘッダファイル :file:`spammodule.h` 内にあり、以下のように"
"なっています::"

#: ../../extending/extending.rst:1296
msgid ""
"#ifndef Py_SPAMMODULE_H\n"
"#define Py_SPAMMODULE_H\n"
"#ifdef __cplusplus\n"
"extern \"C\" {\n"
"#endif\n"
"\n"
"/* Header file for spammodule */\n"
"\n"
"/* C API functions */\n"
"#define PySpam_System_NUM 0\n"
"#define PySpam_System_RETURN int\n"
"#define PySpam_System_PROTO (const char *command)\n"
"\n"
"/* Total number of C API pointers */\n"
"#define PySpam_API_pointers 1\n"
"\n"
"\n"
"#ifdef SPAM_MODULE\n"
"/* This section is used when compiling spammodule.c */\n"
"\n"
"static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;\n"
"\n"
"#else\n"
"/* This section is used in modules that use spammodule's API */\n"
"\n"
"static void **PySpam_API;\n"
"\n"
"#define PySpam_System \\\n"
" (*(PySpam_System_RETURN (*)PySpam_System_PROTO) "
"PySpam_API[PySpam_System_NUM])\n"
"\n"
"/* Return -1 on error, 0 on success.\n"
" * PyCapsule_Import will set an exception if there's an error.\n"
" */\n"
"static int\n"
"import_spam(void)\n"
"{\n"
"    PySpam_API = (void **)PyCapsule_Import(\"spam._C_API\", 0);\n"
"    return (PySpam_API != NULL) ? 0 : -1;\n"
"}\n"
"\n"
"#endif\n"
"\n"
"#ifdef __cplusplus\n"
"}\n"
"#endif\n"
"\n"
"#endif /* !defined(Py_SPAMMODULE_H) */"
msgstr ""

#: ../../extending/extending.rst:1344
msgid ""
"All that a client module must do in order to have access to the function :c:"
"func:`!PySpam_System` is to call the function (or rather macro) :c:func:`!"
"import_spam` in its initialization function::"
msgstr ""

#: ../../extending/extending.rst:1348
msgid ""
"PyMODINIT_FUNC\n"
"PyInit_client(void)\n"
"{\n"
"    PyObject *m;\n"
"\n"
"    m = PyModule_Create(&clientmodule);\n"
"    if (m == NULL)\n"
"        return NULL;\n"
"    if (import_spam() < 0)\n"
"        return NULL;\n"
"    /* additional initialization can happen here */\n"
"    return m;\n"
"}"
msgstr ""

#: ../../extending/extending.rst:1362
msgid ""
"The main disadvantage of this approach is that the file :file:`spammodule.h` "
"is rather complicated. However, the basic structure is the same for each "
"function that is exported, so it has to be learned only once."
msgstr ""
"このアプローチの主要な欠点は、 :file:`spammodule.h` がやや難解になるというこ"
"とです。とはいえ、各関数の基本的な構成は公開されるものと同じなので、書き方を"
"一度だけ学べばすみます。"

#: ../../extending/extending.rst:1366
msgid ""
"Finally it should be mentioned that Capsules offer additional functionality, "
"which is especially useful for memory allocation and deallocation of the "
"pointer stored in a Capsule. The details are described in the Python/C API "
"Reference Manual in the section :ref:`capsules` and in the implementation of "
"Capsules (files :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` "
"in the Python source code distribution)."
msgstr ""
"最後に、Capsule は、自身に保存されているポインタをメモリ確保したり解放したり"
"する際に特に便利な、もう一つの機能を提供しているということに触れておかねばな"
"りません。詳細は Python/C API リファレンスマニュアルの :ref:`capsules`, およ"
"び Capsule の実装部分 (Python ソースコード配布物中のファイル :file:`Include/"
"pycapsule.h` および :file:`Objects/pycapsule.c` に述べられています。"

#: ../../extending/extending.rst:1374
msgid "Footnotes"
msgstr "脚注"

#: ../../extending/extending.rst:1375
msgid ""
"An interface for this function already exists in the standard module :mod:"
"`os` --- it was chosen as a simple and straightforward example."
msgstr ""
"この関数へのインターフェースはすでに標準モジュール :mod:`os` にあります --- "
"この関数を選んだのは、単純で直接的な例を示したいからです。"

#: ../../extending/extending.rst:1378
msgid ""
"The metaphor of \"borrowing\" a reference is not completely correct: the "
"owner still has a copy of the reference."
msgstr ""
"参照を \"借用する\" というメタファは厳密には正しくありません: なぜなら、参照"
"の所有者は依然として参照のコピーを持っているからです。"

#: ../../extending/extending.rst:1381
msgid ""
"Checking that the reference count is at least 1 **does not work** --- the "
"reference count itself could be in freed memory and may thus be reused for "
"another object!"
msgstr ""
"参照カウントが 1 以上かどうか調べる方法は **うまくいきません** --- 参照カウン"
"ト自体も解放されたメモリ上にあるため、その領域が他のオブジェクトに使われてい"
"る可能性があります!"

#: ../../extending/extending.rst:1385
msgid ""
"These guarantees don't hold when you use the \"old\" style calling "
"convention --- this is still found in much existing code."
msgstr ""
"\"旧式の\" 呼び出し規約を使っている場合には、この保証は適用されません --- 既"
"存のコードにはいまだに旧式の呼び出し規約が多々あります。"

#: ../../extending/extending.rst:550
msgid "PyObject_CallObject (C function)"
msgstr ""

#: ../../extending/extending.rst:641
msgid "PyArg_ParseTuple (C function)"
msgstr ""

#: ../../extending/extending.rst:733
msgid "PyArg_ParseTupleAndKeywords (C function)"
msgstr ""

#: ../../extending/extending.rst:754
msgid "Philbrick, Geoff"
msgstr "Philbrick, Geoff"