python-docs-ja/c-api/extension-modules.po at 3.14 · python/python-docs-ja

533 lines (459 loc) · 18.2 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# Translators:
# qqfunc, 2025
# python-doc bot, 2026
"Project-Id-Version: Python 3.15\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-08-25 14:37+0000\n"
"PO-Revision-Date: 2025-09-16 00:00+0000\n"
"Last-Translator: python-doc bot, 2026\n"
"Language-Team: Japanese (https://app.transifex.com/python-doc/teams/5390/"
"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"
#: ../../c-api/extension-modules.rst:6
msgid "Defining extension modules"
msgstr "拡張モジュールの定義"
#: ../../c-api/extension-modules.rst:8
"A C extension for CPython is a shared library (for example, a ``.so`` file "
"on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python "
"process (for example, it is compiled with compatible compiler settings), and "
"which exports an :dfn:`export hook` function (or an old-style :ref:"
"`initialization function <extension-pyinit>`)."
#: ../../c-api/extension-modules.rst:14
"To be importable by default (that is, by :py:class:`importlib.machinery."
"ExtensionFileLoader`), the shared library must be available on :py:attr:`sys."
"path`, and must be named after the module name plus an extension listed in :"
"py:attr:`importlib.machinery.EXTENSION_SUFFIXES`."
"デフォルトで (つまり、 :py:class:`importlib.machinery.ExtensionFileLoader` に"
"よって) インポート可能であるためには、共有ライブラリは :py:attr:`sys.path` 上"
"で利用可能である必要があり、モジュール名と :py:attr:`importlib.machinery."
"EXTENSION_SUFFIXES`. に含まれる拡張子で命名する必要があります。"
#: ../../c-api/extension-modules.rst:22
"Building, packaging and distributing extension modules is best done with "
"third-party tools, and is out of scope of this document. One suitable tool "
"is Setuptools, whose documentation can be found at https://setuptools.pypa."
"io/en/latest/setuptools.html."
"拡張モジュールのビルド、パッケージ化および配布には、サードパーティのツールが"
"最適であり、このドキュメントの範囲外です。適切なツールの一つは Setuptools で"
"あり、ドキュメントは https://setuptools.pypa.io/en/latest/setuptools.html に"
#: ../../c-api/extension-modules.rst:30
msgid "Extension export hook"
#: ../../c-api/extension-modules.rst:34
"Support for the :samp:`PyModExport_{<name>}` export hook was added in Python "
"3.15. The older way of defining modules is still available: consult either "
"the :ref:`extension-pyinit` section or earlier versions of this "
"documentation if you plan to support earlier Python versions."
#: ../../c-api/extension-modules.rst:39
"The export hook must be an exported function with the following signature:"
#: ../../c-api/extension-modules.rst:43
"For modules with ASCII-only names, the :ref:`export hook <extension-export-"
"hook>` must be named :samp:`PyModExport_{<name>}`, with ``<name>`` replaced "
"by the module's name."
#: ../../c-api/extension-modules.rst:47
"For non-ASCII module names, the export hook must instead be named :samp:"
"`PyModExportU_{<name>}` (note the ``U``), with ``<name>`` encoded using "
"Python's *punycode* encoding with hyphens replaced by underscores. In Python:"
#: ../../c-api/extension-modules.rst:51
"def hook_name(name):\n"
"    try:\n"
"        suffix = b'_' + name.encode('ascii')\n"
"    except UnicodeEncodeError:\n"
"        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')\n"
"    return b'PyModExport' + suffix"
#: ../../c-api/extension-modules.rst:60
"The export hook returns an array of :c:type:`PySlot` entries, terminated by "
"an entry with a slot ID of ``0``. These slots describe how the module should "
"be created and initialized."
#: ../../c-api/extension-modules.rst:64
"This array must remain valid and constant until interpreter shutdown. "
"Typically, it should use ``static`` storage. Prefer using the :c:macro:"
"`Py_mod_create` and :c:macro:`Py_mod_exec` slots for any dynamic behavior."
#: ../../c-api/extension-modules.rst:69
"The export hook may return ``NULL`` with an exception set to signal failure."
#: ../../c-api/extension-modules.rst:71
"It is recommended to define the export hook function using a helper macro:"
#: ../../c-api/extension-modules.rst:75
msgid "Declare an extension module export hook. This macro:"
#: ../../c-api/extension-modules.rst:78
msgid "specifies the :c:expr:`PySlot*` return type,"
#: ../../c-api/extension-modules.rst:79 ../../c-api/extension-modules.rst:248
msgid "adds any special linkage declarations required by the platform, and"
#: ../../c-api/extension-modules.rst:80 ../../c-api/extension-modules.rst:249
msgid "for C++, declares the function as ``extern \"C\"``."
#: ../../c-api/extension-modules.rst:82 ../../c-api/extension-modules.rst:279
msgid "For example, a module called ``spam`` would be defined like this::"
#: ../../c-api/extension-modules.rst:84
"PyABIInfo_VAR(abi_info);\n"
"static PySlot spam_slots[] = {\n"
"    PySlot_STATIC_DATA(Py_mod_abi, &abi_info),\n"
"    PySlot_STATIC_DATA(Py_mod_name, \"spam\"),\n"
"    PySlot_FUNC(Py_mod_init, spam_init_function),\n"
"    ...\n"
"    PySlot_END\n"
"PyMODEXPORT_FUNC\n"
"PyModExport_spam(void)\n"
"    return spam_slots;\n"
#: ../../c-api/extension-modules.rst:100
"The export hook is typically the only non-\\ ``static`` item defined in the "
"module's C source."
#: ../../c-api/extension-modules.rst:105
"The hook should be kept short. If it does more than ``return`` a static "
"array, several caveats apply:"
#: ../../c-api/extension-modules.rst:108
"If you need to use any Python C API, it is recommended to call :c:func:"
"`PyABIInfo_Check` first to raise an exception, rather than crash, in common "
"cases of ABI mismatch."
#: ../../c-api/extension-modules.rst:111
"Code in the export hook must never rely on the :term:`GIL`: :term:`free-"
"threaded builds <free-threaded build>` of Python can only check the :c:macro:"
"`Py_mod_gil` slot (or the lack of it) after the hook returns,"
#: ../../c-api/extension-modules.rst:114
"Similarly, the hook may be called in any subinterpreter, since the :c:macro:"
"`Py_mod_multiple_interpreters` slot (or lack of it) is only checked after "
"the hook returns."
#: ../../c-api/extension-modules.rst:118
msgid "For example::"
msgstr "例えば::"
#: ../../c-api/extension-modules.rst:120
"PyMODEXPORT_FUNC\n"
"PyModExport_modulename(void)\n"
"   if (PyABIInfo_Check(&abi_info, \"modulename\") < 0) {\n"
"      /* ABI mismatch. It's not safe to examine the raised exception. */\n"
"      return NULL;\n"
"   /* use Python API (as little as possible); don't rely on GIL */\n"
"   return modulename_slots;\n"
#: ../../c-api/extension-modules.rst:135
"It is possible to export multiple modules from a single shared library by "
"defining multiple export hooks. However, importing  them requires a custom "
"importer or suitably named copies/links of the extension file, because "
"Python's import machinery only finds the function corresponding to the "
"filename. See the `Multiple modules in one library <https://peps.python.org/"
"pep-0489/#multiple-modules-in-one-library>`__ section in :pep:`489` for "
#: ../../c-api/extension-modules.rst:147
msgid "Multi-phase initialization"
msgstr "多段階初期化"
#: ../../c-api/extension-modules.rst:149
msgid "The process of creating an extension module follows several phases:"
#: ../../c-api/extension-modules.rst:151
"Python finds and calls the export hook to get information on how to create "
"the module."
#: ../../c-api/extension-modules.rst:153
"Before any substantial code is executed, Python can determine which "
"capabilities the module supports, and it can adjust the environment or "
"refuse loading an incompatible extension. Slots like :c:data:`Py_mod_abi`, :"
"c:data:`Py_mod_gil` and :c:data:`Py_mod_multiple_interpreters` influence "
"this step."
#: ../../c-api/extension-modules.rst:158
"By default, Python itself then creates the module object -- that is, it does "
"the equivalent of calling :py:meth:`~object.__new__` when creating an "
"object. This step can be overridden using the :c:data:`Py_mod_create` slot."
#: ../../c-api/extension-modules.rst:161
"Python sets initial module attributes like :attr:`~module.__package__` and :"
"attr:`~module.__loader__`, and inserts the module object into :py:attr:`sys."
"modules`."
#: ../../c-api/extension-modules.rst:164
"Afterwards, the module object is initialized in an extension-specific way -- "
"the equivalent of :py:meth:`~object.__init__` when creating an object, or of "
"executing top-level code in a Python-language module. The behavior is "
"specified using the :c:data:`Py_mod_exec` slot."
#: ../../c-api/extension-modules.rst:169
"This is called *multi-phase initialization* to distinguish it from the "
"legacy (but still supported) :ref:`single-phase initialization <single-phase-"
"initialization>`, where an initialization function returns a fully "
"constructed module."
#: ../../c-api/extension-modules.rst:175
msgid "Added support for multi-phase initialization (:pep:`489`)."
msgstr "多段階初期化 (:pep:`489`) のサポートを追加しました。"
#: ../../c-api/extension-modules.rst:179
msgid "Multiple module instances"
msgstr "複数のモジュールインスタンス"
#: ../../c-api/extension-modules.rst:181
"By default, extension modules are not singletons. For example, if the :py:"
"attr:`sys.modules` entry is removed and the module is re-imported, a new "
"module object is created and, typically, populated with fresh method and "
"type objects. The old module is subject to normal garbage collection. This "
"mirrors the behavior of pure-Python modules."
#: ../../c-api/extension-modules.rst:188
"Additional module instances may be created in :ref:`sub-interpreters <sub-"
"interpreter-support>` or after Python runtime reinitialization (:c:func:"
"`Py_Finalize` and :c:func:`Py_Initialize`). In these cases, sharing Python "
"objects between module instances would likely cause crashes or undefined "
"behavior."
#: ../../c-api/extension-modules.rst:195
"To avoid such issues, each instance of an extension module should be "
"*isolated*: changes to one instance should not implicitly affect the others, "
"and all state owned by the module, including references to Python objects, "
"should be specific to a particular module instance. See :ref:`isolating-"
"extensions-howto` for more details and a practical guide."
#: ../../c-api/extension-modules.rst:201
"A simpler way to avoid these issues is :ref:`raising an error on repeated "
"initialization <isolating-extensions-optout>`."
#: ../../c-api/extension-modules.rst:204
"All modules are expected to support :ref:`sub-interpreters <sub-interpreter-"
"support>`, or otherwise explicitly signal a lack of support. This is usually "
"achieved by isolation or blocking repeated initialization, as above. A "
"module may also be limited to the main interpreter using the :c:data:"
"`Py_mod_multiple_interpreters` slot."
#: ../../c-api/extension-modules.rst:216
msgid "``PyInit`` function"
#: ../../c-api/extension-modules.rst:220
"This functionality will not get new features, but there are no plans to "
"remove it."
#: ../../c-api/extension-modules.rst:223
"Instead of :c:func:`PyModExport_modulename`, an extension module can define "
"an older-style :dfn:`initialization function` with the signature:"
#: ../../c-api/extension-modules.rst:228
"Its name should be :samp:`PyInit_{<name>}`, with ``<name>`` replaced by the "
"name of the module. For non-ASCII module names, use :samp:`PyInitU_{<name>}` "
"instead, with ``<name>`` encoded in the same way as for the :ref:`export "
"hook <extension-export-hook>` (that is, using Punycode with underscores)."
#: ../../c-api/extension-modules.rst:235
"If a module exports both :samp:`PyInit_{<name>}` and :samp:"
"`PyModExport_{<name>}`, the :samp:`PyInit_{<name>}` function is ignored."
#: ../../c-api/extension-modules.rst:239
"Like with :c:macro:`PyMODEXPORT_FUNC`, it is recommended to define the "
"initialization function using a helper macro:"
#: ../../c-api/extension-modules.rst:244
msgid "Declare an extension module initialization function. This macro:"
#: ../../c-api/extension-modules.rst:247
msgid "specifies the :c:expr:`PyObject*` return type,"
#: ../../c-api/extension-modules.rst:252
"Normally, the initialization function (``PyInit_modulename``) returns a :c:"
"type:`PyModuleDef` instance with non-``NULL`` :c:member:`~PyModuleDef."
"m_slots`. This allows Python to use :ref:`multi-phase initialization <multi-"
"phase-initialization>`."
#: ../../c-api/extension-modules.rst:257
"Before it is returned, the ``PyModuleDef`` instance must be initialized "
"using the following function:"
#: ../../c-api/extension-modules.rst:262
"Ensure a module definition is a properly initialized Python object that "
"correctly reports its type and a reference count."
#: ../../c-api/extension-modules.rst:265
msgid "Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred."
#: ../../c-api/extension-modules.rst:267
"Calling this function is required before returning a :c:type:`PyModuleDef` "
"from a module initialization function. It should not be used in other "
"contexts."
#: ../../c-api/extension-modules.rst:271
"Note that Python assumes that ``PyModuleDef`` structures are statically "
"allocated. This function may return either a new reference or a borrowed "
"one; this reference must not be released."
#: ../../c-api/extension-modules.rst:281
"static struct PyModuleDef spam_module = {\n"
"    .m_base = PyModuleDef_HEAD_INIT,\n"
"    .m_name = \"spam\",\n"
"    ...\n"
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"    return PyModuleDef_Init(&spam_module);\n"
#: ../../c-api/extension-modules.rst:297
msgid "Legacy single-phase initialization"
msgstr "従来の一段階初期化"
#: ../../c-api/extension-modules.rst:301
"Single-phase initialization is a legacy mechanism to initialize extension "
"modules, with known drawbacks and design flaws. Extension module authors are "
"encouraged to use multi-phase initialization instead."
#: ../../c-api/extension-modules.rst:305
msgid "However, there are no plans to remove support for it."
#: ../../c-api/extension-modules.rst:307
"In single-phase initialization, the old-style :ref:`initialization function "
"<extension-pyinit>` (``PyInit_modulename``) should create, populate and "
"return a module object. This is typically done using :c:func:"
"`PyModule_Create` and functions like :c:func:`PyModule_AddObjectRef`."
#: ../../c-api/extension-modules.rst:313
"Single-phase initialization differs from the :ref:`default <multi-phase-"
"initialization>` in the following ways:"
#: ../../c-api/extension-modules.rst:316
msgid "Single-phase modules are, or rather *contain*, “singletons”."
#: ../../c-api/extension-modules.rst:318
"When the module is first initialized, Python saves the contents of the "
"module's ``__dict__`` (that is, typically, the module's functions and types)."
#: ../../c-api/extension-modules.rst:322
"For subsequent imports, Python does not call the initialization function "
"again. Instead, it creates a new module object with a new ``__dict__``, and "
"copies the saved contents to it. For example, given a single-phase module "
"``_testsinglephase`` [#testsinglephase]_ that defines a function ``sum`` and "
"an exception class ``error``:"
#: ../../c-api/extension-modules.rst:330
">>> import sys\n"
">>> import _testsinglephase as one\n"
">>> del sys.modules['_testsinglephase']\n"
">>> import _testsinglephase as two\n"
">>> one is two\n"
">>> one.__dict__ is two.__dict__\n"
">>> one.sum is two.sum\n"
">>> one.error is two.error\n"
#: ../../c-api/extension-modules.rst:345
"The exact behavior should be considered a CPython implementation detail."
#: ../../c-api/extension-modules.rst:347
"To work around the fact that ``PyInit_modulename`` does not take a *spec* "
"argument, some state of the import machinery is saved and applied to the "
"first suitable module created during the ``PyInit_modulename`` call. "
"Specifically, when a sub-module is imported, this mechanism prepends the "
"parent package name to the name of the module."
#: ../../c-api/extension-modules.rst:353
"A single-phase ``PyInit_modulename`` function should create “its” module "
"object as soon as possible, before any other module objects can be created."
#: ../../c-api/extension-modules.rst:356
msgid "Non-ASCII module names (``PyInitU_modulename``) are not supported."
#: ../../c-api/extension-modules.rst:358
"Single-phase modules support module lookup functions like :c:func:"
"`PyState_FindModule`."
#: ../../c-api/extension-modules.rst:361
msgid "The module's :c:member:`PyModuleDef.m_slots` must be NULL."
#: ../../c-api/extension-modules.rst:363
"``_testsinglephase`` is an internal module used in CPython's self-test "
"suite; your installation may or may not include it."
Navigation Menu

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FilesExpand file tree

extension-modules.po

Latest commit

History

extension-modules.po

File metadata and controls
