# 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:

# python-doc bot, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.9\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-01-03 16:35+0000\n"

"PO-Revision-Date: 2025-09-22 17:54+0000\n"

"Last-Translator: python-doc bot, 2025\n"

"Language-Team: Chinese (China) (https://app.transifex.com/python-doc/teams/5390/zh_CN/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: zh_CN\n"

"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../extending/embedding.rst:8

msgid "Embedding Python in Another Application"

msgstr "在其它应用程序嵌入 Python"

#: ../../extending/embedding.rst:10

msgid ""

"The previous chapters discussed how to extend Python, that is, how to extend"

" the functionality of Python by attaching a library of C functions to it. "

"It is also possible to do it the other way around: enrich your C/C++ "

"application by embedding Python in it. Embedding provides your application "

"with the ability to implement some of the functionality of your application "

"in Python rather than C or C++. This can be used for many purposes; one "

"example would be to allow users to tailor the application to their needs by "

"writing some scripts in Python. You can also use it yourself if some of the"

" functionality can be written in Python more easily."

msgstr ""

"前几章讨论了如何对 Python 进行扩展，也就是如何用 C 函数库 扩展 Python 的功能。反过来也是可以的：将 Python 嵌入到 C/C++"

" 应用程序中丰富其功能。这种嵌入可以让应用程序用 Python 来实现某些功能，而不是用 C 或 C++ 。用途会有很多；比如允许用户用 Python "

"编写一些脚本，以便定制应用程序满足需求。如果某些功能用 Python 编写起来更为容易，那么开发人员自己也能这么干。"

#: ../../extending/embedding.rst:20

msgid ""

"Embedding Python is similar to extending it, but not quite. The difference "

"is that when you extend Python, the main program of the application is still"

" the Python interpreter, while if you embed Python, the main program may "

"have nothing to do with Python --- instead, some parts of the application "

"occasionally call the Python interpreter to run some Python code."

msgstr ""

"Python 的嵌入类似于扩展，但不完全相同。不同之处在于，扩展 Python 时应用程序的主程序仍然是 Python 解释器，而嵌入 Python "

"时的主程序可能与 Python 完全无关——而是应用程序的某些部分偶尔会调用 Python 解释器来运行一些 Python 代码。"

#: ../../extending/embedding.rst:26

msgid ""

"So if you are embedding Python, you are providing your own main program. "

"One of the things this main program has to do is initialize the Python "

"interpreter. At the very least, you have to call the function "

":c:func:`Py_Initialize`. There are optional calls to pass command line "

"arguments to Python. Then later you can call the interpreter from any part "

"of the application."

msgstr ""

"因此，若要嵌入 Python，就要提供自己的主程序。此主程序要做的事情之一就是初始化 Python 解释器。至少得调用函数 "

":c:func:`Py_Initialize`。还有些可选的调用可向 Python 传递命令行参数。之后即可从应用程序的任何地方调用解释器了。"

#: ../../extending/embedding.rst:32

msgid ""

"There are several different ways to call the interpreter: you can pass a "

"string containing Python statements to :c:func:`PyRun_SimpleString`, or you "

"can pass a stdio file pointer and a file name (for identification in error "

"messages only) to :c:func:`PyRun_SimpleFile`. You can also call the lower-"

"level operations described in the previous chapters to construct and use "

"Python objects."

msgstr ""

"调用解释器的方式有好几种：可向 :c:func:`PyRun_SimpleString` 传入一个包含 Python 语句的字符串，也可向 "

":c:func:`PyRun_SimpleFile` 传入一个 stdio "

"文件指针和一个文件名（仅在错误信息中起到识别作用）。还可以调用前面介绍过的底层操作来构造并使用 Python 对象。"

#: ../../extending/embedding.rst:42

msgid ":ref:`c-api-index`"

msgstr ":ref:`c-api-index`"

#: ../../extending/embedding.rst:42

msgid ""

"The details of Python's C interface are given in this manual. A great deal "

"of necessary information can be found here."

msgstr "本文详细介绍了 Python 的 C 接口。这里有大量必要的信息。"

#: ../../extending/embedding.rst:49

msgid "Very High Level Embedding"

msgstr "高层次的嵌入"

#: ../../extending/embedding.rst:51

msgid ""

"The simplest form of embedding Python is the use of the very high level "

"interface. This interface is intended to execute a Python script without "

"needing to interact with the application directly. This can for example be "

"used to perform some operation on a file. ::"

msgstr ""

"最简单的 Python 嵌入形式就是采用非常高层的接口。该接口的目标是只执行一段 Python "

"脚本，而无需与应用程序直接交互。比如以下代码可以用来对某个文件进行一些操作。"

#: ../../extending/embedding.rst:78

msgid ""

"The :c:func:`Py_SetProgramName` function should be called before "

":c:func:`Py_Initialize` to inform the interpreter about paths to Python run-"

"time libraries. Next, the Python interpreter is initialized with "

":c:func:`Py_Initialize`, followed by the execution of a hard-coded Python "

"script that prints the date and time. Afterwards, the "

":c:func:`Py_FinalizeEx` call shuts the interpreter down, followed by the end"

" of the program. In a real program, you may want to get the Python script "

"from another source, perhaps a text-editor routine, a file, or a database. "

"Getting the Python code from a file can better be done by using the "

":c:func:`PyRun_SimpleFile` function, which saves you the trouble of "

"allocating memory space and loading the file contents."

msgstr ""

"在 :c:func:`Py_Initialize` 之前，应该先调用 :c:func:`Py_SetProgramName` 函数，以便向解释器告知 "

"Python运行库的路径。接下来，:c:func:`Py_Initialize` 会初始化 Python 解释器，然后执行硬编码的 Python "

"脚本，打印出日期和时间。之后，调用 :c:func:`Py_FinalizeEx` 关闭解释器，程序结束。在真实的程序中，可能需要从其他来源获取 "

"Python 脚本，或许是从文本编辑器例程、文件，或者某个数据库。利用 :c:func:`PyRun_SimpleFile` 函数可以更好地从文件中获取"

" Python 代码，可省去分配内存空间和加载文件内容的麻烦。"

#: ../../extending/embedding.rst:93

msgid "Beyond Very High Level Embedding: An overview"

msgstr "突破高层次嵌入的限制：概述"

#: ../../extending/embedding.rst:95

msgid ""

"The high level interface gives you the ability to execute arbitrary pieces "

"of Python code from your application, but exchanging data values is quite "

"cumbersome to say the least. If you want that, you should use lower level "

"calls. At the cost of having to write more C code, you can achieve almost "

"anything."

msgstr ""

"高级接口能从应用程序中执行任何 Python "

"代码，但至少交换数据可说是相当麻烦的。如若需要交换数据，应使用较低级别的调用。几乎可以实现任何功能，代价是得写更多的 C 代码。"

#: ../../extending/embedding.rst:100

msgid ""

"It should be noted that extending Python and embedding Python is quite the "

"same activity, despite the different intent. Most topics discussed in the "

"previous chapters are still valid. To show this, consider what the extension"

" code from Python to C really does:"

msgstr ""

"应该注意，尽管意图不同，但扩展 Python 和嵌入 Python 的过程相当类似。前几章中讨论的大多数主题依然有效。为了说明这一点，不妨来看一下从 "

"Python 到 C 的扩展代码到底做了什么："

#: ../../extending/embedding.rst:105

msgid "Convert data values from Python to C,"

msgstr "将 Python 的数据转换为 C 格式，"

#: ../../extending/embedding.rst:107

msgid "Perform a function call to a C routine using the converted values, and"

msgstr "用转换后的数据执行 C 程序的函数调用，"

#: ../../extending/embedding.rst:109

msgid "Convert the data values from the call from C to Python."

msgstr "将调用返回的数据从 C 转换为 Python 格式。"

#: ../../extending/embedding.rst:111

msgid "When embedding Python, the interface code does:"

msgstr "嵌入 Python 时，接口代码会这样做："

#: ../../extending/embedding.rst:113

msgid "Convert data values from C to Python,"

msgstr "将 C 数据转换为 Python 格式，"

#: ../../extending/embedding.rst:115

msgid ""

"Perform a function call to a Python interface routine using the converted "

"values, and"

msgstr "用转换后的数据执行对 Python 接口的函数调用，"

#: ../../extending/embedding.rst:118

msgid "Convert the data values from the call from Python to C."

msgstr "将调用返回的数据从 Python 转换为 C 格式。"

#: ../../extending/embedding.rst:120

msgid ""

"As you can see, the data conversion steps are simply swapped to accommodate "

"the different direction of the cross-language transfer. The only difference "

"is the routine that you call between both data conversions. When extending, "

"you call a C routine, when embedding, you call a Python routine."

msgstr ""

"可见只是数据转换的步骤交换了一下顺序，以顺应跨语言的传输方向。唯一的区别是在两次数据转换之间调用的函数不同。在执行扩展时，调用一个 C "

"函数，而执行嵌入时调用的是个 Python 函数。"

#: ../../extending/embedding.rst:125

msgid ""

"This chapter will not discuss how to convert data from Python to C and vice "

"versa. Also, proper use of references and dealing with errors is assumed to"

" be understood. Since these aspects do not differ from extending the "

"interpreter, you can refer to earlier chapters for the required information."

msgstr ""

"本文不会讨论如何将数据从 Python 转换到 C "

"去，反之亦然。另外还假定读者能够正确使用引用并处理错误。由于这些地方与解释器的扩展没有区别，请参考前面的章节以获得所需的信息。"

#: ../../extending/embedding.rst:134

msgid "Pure Embedding"

msgstr "只做嵌入"

#: ../../extending/embedding.rst:136

msgid ""

"The first program aims to execute a function in a Python script. Like in the"

" section about the very high level interface, the Python interpreter does "

"not directly interact with the application (but that will change in the next"

" section)."

msgstr ""

"第一个程序的目标是执行 Python 脚本中的某个函数。就像高层次接口那样，Python 解释器并不会直接与应用程序进行交互（但下一节将改变这一点）。"

#: ../../extending/embedding.rst:141

msgid "The code to run a function defined in a Python script is:"

msgstr "要运行 Python 脚本中定义的函数，代码如下："

#: ../../extending/embedding.rst:146

msgid ""

"This code loads a Python script using ``argv[1]``, and calls the function "

"named in ``argv[2]``. Its integer arguments are the other values of the "

"``argv`` array. If you :ref:`compile and link <compiling>` this program "

"(let's call the finished executable :program:`call`), and use it to execute "

"a Python script, such as:"

msgstr ""

"上述代码先利用 ``argv[1]`` 加载 Python 脚本，再调用 ``argv[2]`` 指定的函数。函数的整数参数是 ``argv`` "

"数组中的其余值。如果 :ref:`编译并链接<compiling>` 该程序（此处将最终的可执行程序称作 :program:`call`）, "

"并用它执行一个 Python 脚本，例如："

#: ../../extending/embedding.rst:161

msgid "then the result should be:"

msgstr "然后结果应该是："

#: ../../extending/embedding.rst:169

msgid ""

"Although the program is quite large for its functionality, most of the code "

"is for data conversion between Python and C, and for error reporting. The "

"interesting part with respect to embedding Python starts with ::"

msgstr ""

"尽管相对其功能而言，该程序体积相当庞大，但大部分代码是用于 Python 和 C 之间的数据转换，以及报告错误。嵌入 Python 的有趣部分从此开始："

#: ../../extending/embedding.rst:178

msgid ""

"After initializing the interpreter, the script is loaded using "

":c:func:`PyImport_Import`. This routine needs a Python string as its "

"argument, which is constructed using the :c:func:`PyUnicode_FromString` data"

" conversion routine. ::"

msgstr ""

"初始化解释器之后，则用 :c:func:`PyImport_Import` 加载脚本。此函数的参数需是个 Python 字符串，一个用 "

":c:func:`PyUnicode_FromString` 数据转换函数构建的字符串。"

#: ../../extending/embedding.rst:191

msgid ""

"Once the script is loaded, the name we're looking for is retrieved using "

":c:func:`PyObject_GetAttrString`. If the name exists, and the object "

"returned is callable, you can safely assume that it is a function. The "

"program then proceeds by constructing a tuple of arguments as normal. The "

"call to the Python function is then made with::"

msgstr ""

"脚本一旦加载完毕，就会用 :c:func:`PyObject_GetAttrString` "

"查找属性名称。如果名称存在，并且返回的是可调用对象，即可安全地视其为函数。然后程序继续执行，照常构建由参数组成的元组。然后用以下方式调用 Python "

"函数："

#: ../../extending/embedding.rst:199

msgid ""

"Upon return of the function, ``pValue`` is either ``NULL`` or it contains a "

"reference to the return value of the function. Be sure to release the "

"reference after examining the value."

msgstr "当函数返回时，``pValue`` 要么为 ``NULL``，要么包含对函数返回值的引用。请确保用完后释放该引用。"

#: ../../extending/embedding.rst:207

msgid "Extending Embedded Python"

msgstr "对嵌入 Python 功能进行扩展"

#: ../../extending/embedding.rst:209

msgid ""

"Until now, the embedded Python interpreter had no access to functionality "

"from the application itself. The Python API allows this by extending the "

"embedded interpreter. That is, the embedded interpreter gets extended with "

"routines provided by the application. While it sounds complex, it is not so "

"bad. Simply forget for a while that the application starts the Python "

"interpreter. Instead, consider the application to be a set of subroutines, "

"and write some glue code that gives Python access to those routines, just "

"like you would write a normal Python extension. For example::"

msgstr ""

"到目前为止，嵌入的 Python 解释器还不能访问应用程序本身的功能。Python API 通过扩展嵌入解释器实现了这一点。 "

"也就是说，用应用程序提供的函数对嵌入的解释器进行扩展。虽然听起来有些复杂，但也没那么糟糕。只要暂时忘记是应用程序启动了 Python "

"解释器。而把应用程序看作是一堆子程序，然后写一些胶水代码让 Python 访问这些子程序，就像编写普通的 Python 扩展程序一样。 例如："

#: ../../extending/embedding.rst:246

msgid ""

"Insert the above code just above the :c:func:`main` function. Also, insert "

"the following two statements before the call to :c:func:`Py_Initialize`::"

msgstr "在 :c:func:`main` 函数之前插入上述代码。并在调用 :c:func:`Py_Initialize` 之前插入以下两条语句："

#: ../../extending/embedding.rst:252

msgid ""

"These two lines initialize the ``numargs`` variable, and make the "

":func:`emb.numargs` function accessible to the embedded Python interpreter. "

"With these extensions, the Python script can do things like"

msgstr ""

"这两行代码初始化了 ``numargs`` 变量，并让 :func:`emb.numargs` 函数能被嵌入的 Python "

"解释器访问到。有了这些扩展，Python 脚本可以执行类似以下功能："

#: ../../extending/embedding.rst:261

msgid ""

"In a real application, the methods will expose an API of the application to "

"Python."

msgstr "在真实的应用程序中，这种方法将把应用的 API 暴露给 Python 使用。"

#: ../../extending/embedding.rst:271

msgid "Embedding Python in C++"

msgstr "在 C++ 中嵌入 Python"

#: ../../extending/embedding.rst:273

msgid ""

"It is also possible to embed Python in a C++ program; precisely how this is "

"done will depend on the details of the C++ system used; in general you will "

"need to write the main program in C++, and use the C++ compiler to compile "

"and link your program. There is no need to recompile Python itself using "

"C++."

msgstr ""

"还可以将 Python 嵌入到 C++ 程序中去；确切地说，实现方式将取决于 C++ 系统的实现细节；一般需用 C++ 编写主程序，并用 C++ "

"编译器来编译和链接程序。不需要用 C++ 重新编译 Python 本身。"

#: ../../extending/embedding.rst:282

msgid "Compiling and Linking under Unix-like systems"

msgstr "在类 Unix 系统中编译和链接"

#: ../../extending/embedding.rst:284

msgid ""

"It is not necessarily trivial to find the right flags to pass to your "

"compiler (and linker) in order to embed the Python interpreter into your "

"application, particularly because Python needs to load library modules "

"implemented as C dynamic extensions (:file:`.so` files) linked against it."

msgstr ""

"为了将 Python 解释器嵌入应用程序，找到正确的编译参数传给编译器 (和链接器) 并非易事，特别是因为 Python 加载的库模块是以 C "

"动态扩展（:file:`.so` 文件）的形式实现的。"

#: ../../extending/embedding.rst:290

msgid ""

"To find out the required compiler and linker flags, you can execute the "

":file:`python{X.Y}-config` script which is generated as part of the "

"installation process (a :file:`python3-config` script may also be "

"available). This script has several options, of which the following will be"

" directly useful to you:"

msgstr ""

"为了得到所需的编译器和链接器参数，可执行 :file:`python{X.Y}-config` 脚本，它是在安装 Python 时生成的（也可能存在 "

":file:`python3-config` 脚本）。该脚本有几个参数，其中以下几个参数会直接有用："

#: ../../extending/embedding.rst:296

msgid ""

"``pythonX.Y-config --cflags`` will give you the recommended flags when "

"compiling:"

msgstr "``pythonX.Y-config --cflags`` 将给出建议的编译参数。"

#: ../../extending/embedding.rst:304

msgid ""

"``pythonX.Y-config --ldflags`` will give you the recommended flags when "

"linking:"

msgstr "``pythonX.Y-config --ldflags`` 将给出建议的链接参数。"

#: ../../extending/embedding.rst:313

msgid ""

"To avoid confusion between several Python installations (and especially "

"between the system Python and your own compiled Python), it is recommended "

"that you use the absolute path to :file:`python{X.Y}-config`, as in the "

"above example."

msgstr ""

"为了避免多个 Python 安装版本引发混乱（特别是在系统安装版本和自己编译版本之间），建议用 :file:`python{X.Y}-config` "

"指定绝对路径，如上例所述。"

#: ../../extending/embedding.rst:318

msgid ""

"If this procedure doesn't work for you (it is not guaranteed to work for all"

" Unix-like platforms; however, we welcome :ref:`bug reports <reporting-"

"bugs>`) you will have to read your system's documentation about dynamic "

"linking and/or examine Python's :file:`Makefile` (use "

":func:`sysconfig.get_makefile_filename` to find its location) and "

"compilation options. In this case, the :mod:`sysconfig` module is a useful "

"tool to programmatically extract the configuration values that you will want"

" to combine together. For example:"

msgstr ""

"如果上述方案不起作用（不能保证对所有 Unix 类平台都生效；欢迎提出 :ref:`bug 报告<reporting-"

"bugs>`），就得阅读系统关于动态链接的文档，并检查 Python 的 :file:`Makefile` （用 "

":func:`sysconfig.get_makefile_filename` 找到所在位置）和编译参数。这时 :mod:`sysconfig` "

"模块会是个有用的工具，可用编程方式提取需组合在一起的配置值。比如："