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

630 lines (533 loc) · 20.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:
# python-doc bot, 2025
"Project-Id-Version: Python 3.15\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-06-03 18:19+0000\n"
"PO-Revision-Date: 2025-09-16 00:00+0000\n"
"Last-Translator: python-doc bot, 2025\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/stable.rst:7
msgid "C API and ABI Stability"
#: ../../c-api/stable.rst:9
"Unless documented otherwise, Python's C API is covered by the Backwards "
"Compatibility Policy, :pep:`387`. Most changes to it are source-compatible "
"(typically by only adding new API). Changing existing API or removing API is "
"only done after a deprecation period or to fix serious issues."
#: ../../c-api/stable.rst:15
"CPython's Application Binary Interface (ABI) is forward- and backwards-"
"compatible across a minor release (if these are compiled the same way; see :"
"ref:`stable-abi-platform` below). So, code compiled for Python 3.10.0 will "
"work on 3.10.8 and vice versa, but will need to be compiled separately for "
"3.9.x and 3.11.x."
#: ../../c-api/stable.rst:21
msgid "There are two tiers of C API with different stability expectations:"
#: ../../c-api/stable.rst:23
":ref:`Unstable API <unstable-c-api>`, may change in minor versions without a "
"deprecation period. It is marked by the ``PyUnstable`` prefix in names."
#: ../../c-api/stable.rst:25
":ref:`Limited API <limited-c-api>`, is compatible across several minor "
"releases. When :c:macro:`Py_LIMITED_API` is defined, only this subset is "
"exposed from ``Python.h``."
#: ../../c-api/stable.rst:29
msgid "These are discussed in more detail below."
#: ../../c-api/stable.rst:31
"Names prefixed by an underscore, such as ``_Py_InternalState``, are private "
"API that can change without notice even in patch releases. If you need to "
"use this API, consider reaching out to `CPython developers <https://discuss."
"python.org/c/core-dev/c-api/30>`_ to discuss adding public API for your use "
#: ../../c-api/stable.rst:40
msgid "Unstable C API"
#: ../../c-api/stable.rst:44
"Any API named with the ``PyUnstable`` prefix exposes CPython implementation "
"details, and may change in every minor release (e.g. from 3.9 to 3.10) "
"without any deprecation warnings. However, it will not change in a bugfix "
"release (e.g. from 3.10.0 to 3.10.1)."
#: ../../c-api/stable.rst:49
"It is generally intended for specialized, low-level tools like debuggers."
#: ../../c-api/stable.rst:51
"Projects that use this API are expected to follow CPython development and "
"spend extra effort adjusting to changes."
#: ../../c-api/stable.rst:58
msgid "Stable Application Binary Interfaces"
#: ../../c-api/stable.rst:60
"Python's :dfn:`Stable ABI` allows extensions to be compatible with multiple "
"versions of Python, without recompilation."
#: ../../c-api/stable.rst:65
"For simplicity, this document talks about *extensions*, but Stable ABI works "
"the same way for all uses of the API – for example, embedding Python."
#: ../../c-api/stable.rst:68
msgid "There are two Stable ABIs:"
#: ../../c-api/stable.rst:70
"``abi3``, introduced in Python 3.2, is compatible with **non**-:term:`free-"
"threaded <free-threaded build>` builds of CPython."
#: ../../c-api/stable.rst:73
"``abi3t``, introduced in Python 3.15, is compatible with :term:`free-"
"threaded <free-threaded build>` builds of CPython. It has stricter API "
"limitations than ``abi3``."
#: ../../c-api/stable.rst:79
msgid "``abi3t`` was added in :pep:`803`"
#: ../../c-api/stable.rst:81
"It is possible for an extension to be compiled for *both* ``abi3`` and "
"``abi3t`` at the same time; the result will be compatible with both free-"
"threaded and non-free-threaded builds of Python. Currently, this has no "
"downsides compared to compiling for ``abi3t`` only."
#: ../../c-api/stable.rst:86
"Each Stable ABI is versioned using the first two numbers of the Python "
"version. For example, Stable ABI 3.14 corresponds to Python 3.14. An "
"extension compiled for Stable ABI 3.x is ABI-compatible with Python 3.x and "
#: ../../c-api/stable.rst:91
"Extensions that target a stable ABI must only use a limited subset of the C "
"API. This subset is known as the :dfn:`Limited API`; its contents are :ref:"
"`listed below <limited-api-list>`."
#: ../../c-api/stable.rst:95
"On Windows, extensions that use a Stable ABI should be linked against "
"``python3.dll`` rather than a version-specific library such as ``python39."
"dll``. This library only exposes the relevant symbols."
#: ../../c-api/stable.rst:100
"On some platforms, Python will look for and load shared library files named "
"with the ``abi3`` or ``abi3t`` tag (for example, ``mymodule.abi3.so``). :"
"term:`Free-threaded <free-threaded build>` interpreters only recognize the "
"``abi3t`` tag, while non-free-threaded ones will prefer ``abi3`` but fall "
"back to ``abi3t``. Thus, extensions compatible with both ABIs should use the "
"``abi3t`` tag."
#: ../../c-api/stable.rst:107
"Python does not necessarily check that extensions it loads have compatible "
"ABI. Extension authors are encouraged to add a check using the :c:macro:"
"`Py_mod_abi` slot or the :c:func:`PyABIInfo_Check` function, but the user "
"(or their packaging tool) is ultimately responsible for ensuring that, for "
"example, extensions built for Stable ABI 3.10 are not installed for lower "
"versions of Python."
#: ../../c-api/stable.rst:115
"All functions in Stable ABI are present as functions in Python's shared "
"library, not solely as macros. This makes them usable in languages that "
"don't use the C preprocessor, including Python's :py:mod:`ctypes`."
#: ../../c-api/stable.rst:124
msgid "Compiling for Stable ABI"
#: ../../c-api/stable.rst:128
"Build tools (such as, for example, meson-python, scikit-build-core, or "
"Setuptools) often have a mechanism for setting macros and synchronizing them "
"with extension filenames and other metadata. Prefer using such a mechanism, "
"if it exists, over defining the macros manually."
#: ../../c-api/stable.rst:134
"The rest of this section is mainly relevant for tool authors, and for people "
"who compile extensions manually."
#: ../../c-api/stable.rst:137
msgid "`list of recommended tools`_ in the Python Packaging User Guide"
#: ../../c-api/stable.rst:141
"To compile for a Stable ABI, define one or both of the following macros to "
"the lowest Python version your extension should support, in :c:macro:"
"`Py_PACK_VERSION` format. Typically, you should choose a specific value "
"rather than the version of the Python headers you are compiling against."
#: ../../c-api/stable.rst:147
"The macros must be defined before including ``Python.h``. Since :c:macro:"
"`Py_PACK_VERSION` is not available at this point, you will need to use the "
"numeric value directly. For reference, the values for a few recent Python "
"versions are:"
#: ../../c-api/stable.rst:1
"0x30a0000  /* Py_PACK_VERSION(3,10) */\n"
"0x30b0000  /* Py_PACK_VERSION(3,11) */\n"
"0x30c0000  /* Py_PACK_VERSION(3,12) */\n"
"0x30d0000  /* Py_PACK_VERSION(3,13) */\n"
"0x30e0000  /* Py_PACK_VERSION(3,14) */\n"
"0x30f0000  /* Py_PACK_VERSION(3,15) */"
#: ../../c-api/stable.rst:154
"When one of the macros is defined, ``Python.h`` will only expose API that is "
"compatible with the given Stable ABI -- that is, the :ref:`Limited API "
"<limited-api-list>` plus some definitions that need to be visible to the "
"compiler but should not be used directly. When both are defined, ``Python."
"h`` will only expose API compatible with both Stable ABIs."
#: ../../c-api/stable.rst:163
"Target ``abi3``, that is, non-:term:`free-threaded builds <free-threaded "
"build>` of CPython. See :ref:`above <abi3-compiling>` for common information."
#: ../../c-api/stable.rst:169
"Target ``abi3t``, that is, :term:`free-threaded builds <free-threaded "
"build>` of CPython. See :ref:`above <abi3-compiling>` for common information."
#: ../../c-api/stable.rst:175
"Both macros specify a target ABI; the different naming style is due to "
"backwards compatibility."
#: ../../c-api/stable.rst:178
msgid "Historical note"
#: ../../c-api/stable.rst:180
"You can also define ``Py_LIMITED_API`` as ``3``. This works the same as "
"``0x03020000`` (Python 3.2, the version that introduced Stable ABI)."
#: ../../c-api/stable.rst:183
"When both are defined, ``Python.h`` may, or may not, redefine :c:macro:`!"
"Py_LIMITED_API` to match :c:macro:`!Py_TARGET_ABI3T`."
#: ../../c-api/stable.rst:186
"On a :term:`free-threaded build` -- that is, when :c:macro:`Py_GIL_DISABLED` "
"is defined -- :c:macro:`!Py_TARGET_ABI3T` defaults to the value of :c:macro:"
"`!Py_LIMITED_API`. This means that there are two ways to build for both "
"``abi3`` and ``abi3t``:"
#: ../../c-api/stable.rst:191
"define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or"
#: ../../c-api/stable.rst:192
msgid "define only :c:macro:`!Py_LIMITED_API` and:"
#: ../../c-api/stable.rst:194
msgid "on Windows, define :c:macro:`!Py_GIL_DISABLED`;"
#: ../../c-api/stable.rst:195
msgid "on other systems, use the headers of free-threaded build of Python."
#: ../../c-api/stable.rst:201
msgid "Stable ABI Scope and Performance"
#: ../../c-api/stable.rst:203
"The goal for Stable ABI is to allow everything that is possible with the "
"full C API, but possibly with a performance penalty. Generally, "
"compatibility with Stable ABI will require some changes to an extension's "
"source code."
#: ../../c-api/stable.rst:208
"For example, while :c:func:`PyList_GetItem` is available, its \"unsafe\" "
"macro variant :c:func:`PyList_GET_ITEM` is not. The macro can be faster "
"because it can rely on version-specific implementation details of the list "
#: ../../c-api/stable.rst:213
"For another example, when *not* compiling for Stable ABI, some C API "
"functions are inlined or replaced by macros. Compiling for Stable ABI "
"disables this inlining, allowing stability as Python's data structures are "
"improved, but possibly reducing performance."
#: ../../c-api/stable.rst:218
"By leaving out the :c:macro:`!Py_LIMITED_API` or :c:macro:`!Py_TARGET_ABI3T` "
"definition, it is possible to compile Stable-ABI-compatible source for a "
"version-specific ABI. A potentially faster version-specific extension can "
"then be distributed alongside a version compiled for Stable ABI -- a slower "
"but more compatible fallback."
#: ../../c-api/stable.rst:229
msgid "Stable ABI Caveats"
#: ../../c-api/stable.rst:231
"Note that compiling for Stable ABI is *not* a complete guarantee that code "
"will be compatible with the expected Python versions. Stable ABI prevents "
"*ABI* issues, like linker errors due to missing symbols or data corruption "
"due to changes in structure layouts or function signatures. However, other "
"changes in Python can change the *behavior* of extensions."
#: ../../c-api/stable.rst:238
"One issue that the :c:macro:`Py_TARGET_ABI3T` and :c:macro:`Py_LIMITED_API` "
"macros do not guard against is calling a function with arguments that are "
"invalid in a lower Python version. For example, consider a function that "
"starts accepting ``NULL`` for an argument. In Python 3.9, ``NULL`` now "
"selects a default behavior, but in Python 3.8, the argument will be used "
"directly, causing a ``NULL`` dereference and crash. A similar argument works "
"for fields of structs."
#: ../../c-api/stable.rst:246
"For these reasons, we recommend testing an extension with *all* minor Python "
"versions it supports."
#: ../../c-api/stable.rst:249
"We also recommend reviewing documentation of all used API to check if it is "
"explicitly part of the Limited API. Even with ``Py_LIMITED_API`` defined, a "
"few private declarations are exposed for technical reasons (or even "
"unintentionally, as bugs)."
"また、使用するすべての API のドキュメントを確認し、それが明示的に Limited "
"API の一部であるかどうかをチェックすることをお勧めします。``Py_LIMITED_API`` "
"が定義されていても、技術的な理由で(あるいはバグとして意図せず)いくつかのプラ"
"イベート宣言が公開されることがあります。"
#: ../../c-api/stable.rst:254
"Also note that while compiling with ``Py_LIMITED_API`` 3.8 means that the "
"extension should *load* on Python 3.12, and *compile* with Python 3.12, the "
"same source will not necessarily compile with ``Py_LIMITED_API`` set to "
"3.12. In general, parts of the Limited API may be deprecated and removed, "
"provided that Stable ABI stays stable."
#: ../../c-api/stable.rst:265
msgid "Platform Considerations"
msgstr "プラットフォームで考慮すべき点"
#: ../../c-api/stable.rst:267
"ABI stability depends not only on Python, but also on the compiler used, "
"lower-level libraries and compiler options. For the purposes of the :ref:"
"`Stable ABIs <stable-abi>`, these details define a “platform”. They usually "
"depend on the OS type and processor architecture"
#: ../../c-api/stable.rst:272
"It is the responsibility of each particular distributor of Python to ensure "
"that all Python versions on a particular platform are built in a way that "
"does not break the Stable ABIs, or the version-specific ABIs. This is the "
"case with Windows and macOS releases from ``python.org`` and many third-"
"party distributors."
#: ../../c-api/stable.rst:280
msgid "ABI Checking"
#: ../../c-api/stable.rst:284
msgid "Python includes a rudimentary check for ABI compatibility."
#: ../../c-api/stable.rst:286
"This check is not comprehensive. It only guards against common cases of "
"incompatible modules being installed for the wrong interpreter. It also does "
"not take :ref:`platform incompatibilities <stable-abi-platform>` into "
"account. It can only be done after an extension is successfully loaded."
#: ../../c-api/stable.rst:293
"Despite these limitations, it is recommended that extension modules use this "
"mechanism, so that detectable incompatibilities raise exceptions rather than "
#: ../../c-api/stable.rst:297
"Most modules can use this check via the :c:data:`Py_mod_abi` slot and the :c:"
"macro:`PyABIInfo_VAR` macro, for example like this:"
#: ../../c-api/stable.rst:300
"PyABIInfo_VAR(abi_info);\n"
"static PyModuleDef_Slot mymodule_slots[] = {\n"
"   {Py_mod_abi, &abi_info},\n"
#: ../../c-api/stable.rst:310
msgid "The full API is described below for advanced use cases."
#: ../../c-api/stable.rst:314
"Verify that the given *info* is compatible with the currently running "
"interpreter."
#: ../../c-api/stable.rst:317
msgid "Return 0 on success. On failure, raise an exception and return -1."
#: ../../c-api/stable.rst:319
"If the ABI is incompatible, the raised exception will be :py:exc:"
"`ImportError`."
#: ../../c-api/stable.rst:321
"The *module_name* argument can be ``NULL``, or point to a NUL-terminated "
"UTF-8-encoded string used for error messages."
#: ../../c-api/stable.rst:324
"Note that if *info* describes the ABI that the current code uses (as defined "
"by :c:macro:`PyABIInfo_VAR`, for example), using any other Python C API may "
"lead to crashes. In particular, it is not safe to examine the raised "
"exception."
#: ../../c-api/stable.rst:333
"Define a static :c:struct:`PyABIInfo` variable with the given *NAME* that "
"describes the ABI that the current code will use. This macro expands to:"
#: ../../c-api/stable.rst:337
"static PyABIInfo NAME = {\n"
"    1, 0,\n"
"    PyABIInfo_DEFAULT_FLAGS,\n"
"    PY_VERSION_HEX,\n"
"    PyABIInfo_DEFAULT_ABI_VERSION\n"
#: ../../c-api/stable.rst:352
msgid "The major version of :c:struct:`PyABIInfo`. Can be set to:"
#: ../../c-api/stable.rst:354
msgid "``0`` to skip all checking, or"
#: ../../c-api/stable.rst:355
msgid "``1`` to specify this version of :c:struct:`!PyABIInfo`."
#: ../../c-api/stable.rst:359
"The minor version of :c:struct:`PyABIInfo`. Must be set to ``0``; larger "
"values are reserved for backwards-compatible future versions of :c:struct:`!"
"PyABIInfo`."
#: ../../c-api/stable.rst:367
msgid "This field is usually set to the following macro:"
#: ../../c-api/stable.rst:371
"Default flags, based on current values of macros such as :c:macro:"
"`Py_LIMITED_API` and :c:macro:`Py_GIL_DISABLED`."
#: ../../c-api/stable.rst:374
"Alternately, the field can be set to the following flags, combined by "
"bitwise OR. Unused bits must be set to zero."
#: ../../c-api/stable.rst:378
msgid "ABI variant -- one of:"
#: ../../c-api/stable.rst:382
msgid "Specifies that Stable ABI is used."
#: ../../c-api/stable.rst:386
"Specifies ABI specific to a particular build of CPython. Internal use only."
#: ../../c-api/stable.rst:389
msgid "Free-threading compatibility -- one of:"
#: ../../c-api/stable.rst:393
"Specifies ABI compatible with :term:`free-threaded builds <free-threaded "
"build>` of CPython. (That is, ones compiled with :option:`--disable-gil`; "
"with ``t`` in :py:data:`sys.abiflags`)"
#: ../../c-api/stable.rst:400
"Specifies ABI compatible with non-free-threaded builds of CPython (ones "
"compiled *without* :option:`--disable-gil`)."
#: ../../c-api/stable.rst:405
"Specifies ABI compatible with both free-threaded and non-free-threaded "
"builds of CPython, that is, both ``abi3`` and ``abi3t``."
#: ../../c-api/stable.rst:411
"The version of the Python headers used to build the code, in the format used "
"by :c:macro:`PY_VERSION_HEX`."
#: ../../c-api/stable.rst:414
"This can be set to ``0`` to skip any checks related to this field. This "
"option is meant mainly for projects that do not use the CPython headers "
"directly, and do not emulate a specific version of them."
#: ../../c-api/stable.rst:420
msgid "The ABI version."
#: ../../c-api/stable.rst:422
"For Stable ABI, this field should be the value of :c:macro:`Py_LIMITED_API` "
"or :c:macro:`Py_TARGET_ABI3T`. If both are defined, use the smaller value. "
"(If :c:macro:`Py_LIMITED_API` is ``3``; use :c:expr:`Py_PACK_VERSION(3, 2)` "
"instead of ``3``.)"
#: ../../c-api/stable.rst:428
msgid "Otherwise, it should be set to :c:macro:`PY_VERSION_HEX`."
#: ../../c-api/stable.rst:430
msgid "It can also be set to ``0`` to skip any checks related to this field."
#: ../../c-api/stable.rst:436
"The value that should be used for this field, based on current values of "
"macros such as :c:macro:`Py_LIMITED_API`, :c:macro:`PY_VERSION_HEX` and :c:"
"macro:`Py_GIL_DISABLED`."
#: ../../c-api/stable.rst:447
msgid "Contents of Limited API"
msgstr "限定版APIの内容"
#: ../../c-api/stable.rst:449
"This is the definitive list of :ref:`Limited API <limited-c-api>` for Python "
"|version|:"
#: ../../c-api/stable.rst:42
msgid "PyUnstable"
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

stable.po

Latest commit

History

stable.po

File metadata and controls
