module.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2022, Python Software Foundation
# This file is distributed under the same license as the Python package.
#
# Translators:
# Leon H., 2017
msgid ""
msgstr ""
"Project-Id-Version: Python 3.10\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2022-10-06 00:23+0000\n"
"PO-Revision-Date: 2018-05-23 14:32+0000\n"
"Last-Translator: Adrian Liaw <adrianliaw2000@gmail.com>\n"
"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
"tw)\n"
"Language: zh_TW\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../c-api/module.rst:6
msgid "Module Objects"
msgstr "模組物件模組"

#: ../../c-api/module.rst:15
msgid ""
"This instance of :c:type:`PyTypeObject` represents the Python module type.  "
"This is exposed to Python programs as ``types.ModuleType``."
msgstr ""

#: ../../c-api/module.rst:21
msgid ""
"Return true if *p* is a module object, or a subtype of a module object. This "
"function always succeeds."
msgstr ""

#: ../../c-api/module.rst:27
msgid ""
"Return true if *p* is a module object, but not a subtype of :c:data:"
"`PyModule_Type`.  This function always succeeds."
msgstr ""

#: ../../c-api/module.rst:40
msgid ""
"Return a new module object with the :attr:`__name__` attribute set to "
"*name*. The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, "
"and :attr:`__loader__` attributes are filled in (all but :attr:`__name__` "
"are set to ``None``); the caller is responsible for providing a :attr:"
"`__file__` attribute."
msgstr ""

#: ../../c-api/module.rst:48
msgid ":attr:`__package__` and :attr:`__loader__` are set to ``None``."
msgstr ":attr:`__package__` 和 :attr:`__loader__` 被設為 ``None``。"

#: ../../c-api/module.rst:54
msgid ""
"Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded "
"string instead of a Unicode object."
msgstr ""

#: ../../c-api/module.rst:62
msgid ""
"Return the dictionary object that implements *module*'s namespace; this "
"object is the same as the :attr:`~object.__dict__` attribute of the module "
"object. If *module* is not a module object (or a subtype of a module "
"object), :exc:`SystemError` is raised and ``NULL`` is returned."
msgstr ""

#: ../../c-api/module.rst:67
msgid ""
"It is recommended extensions use other ``PyModule_*`` and ``PyObject_*`` "
"functions rather than directly manipulate a module's :attr:`~object."
"__dict__`."
msgstr ""

#: ../../c-api/module.rst:78
msgid ""
"Return *module*'s :attr:`__name__` value.  If the module does not provide "
"one, or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is "
"returned."
msgstr ""

#: ../../c-api/module.rst:86
msgid ""
"Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to "
"``'utf-8'``."
msgstr ""

#: ../../c-api/module.rst:91
msgid ""
"Return the \"state\" of the module, that is, a pointer to the block of "
"memory allocated at module creation time, or ``NULL``.  See :c:member:"
"`PyModuleDef.m_size`."
msgstr ""

#: ../../c-api/module.rst:98
msgid ""
"Return a pointer to the :c:type:`PyModuleDef` struct from which the module "
"was created, or ``NULL`` if the module wasn't created from a definition."
msgstr ""

#: ../../c-api/module.rst:108
msgid ""
"Return the name of the file from which *module* was loaded using *module*'s :"
"attr:`__file__` attribute.  If this is not defined, or if it is not a "
"unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise "
"return a reference to a Unicode object."
msgstr ""

#: ../../c-api/module.rst:118
msgid ""
"Similar to :c:func:`PyModule_GetFilenameObject` but return the filename "
"encoded to 'utf-8'."
msgstr ""

#: ../../c-api/module.rst:121
msgid ""
":c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on "
"unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead."
msgstr ""

#: ../../c-api/module.rst:129
msgid "Initializing C modules"
msgstr ""

#: ../../c-api/module.rst:131
msgid ""
"Modules objects are usually created from extension modules (shared libraries "
"which export an initialization function), or compiled-in modules (where the "
"initialization function is added using :c:func:`PyImport_AppendInittab`). "
"See :ref:`building` or :ref:`extending-with-embedding` for details."
msgstr ""

#: ../../c-api/module.rst:136
msgid ""
"The initialization function can either pass a module definition instance to :"
"c:func:`PyModule_Create`, and return the resulting module object, or request "
"\"multi-phase initialization\" by returning the definition struct itself."
msgstr ""

#: ../../c-api/module.rst:142
msgid ""
"The module definition struct, which holds all information needed to create a "
"module object. There is usually only one statically initialized variable of "
"this type for each module."
msgstr ""

#: ../../c-api/module.rst:148
msgid "Always initialize this member to :const:`PyModuleDef_HEAD_INIT`."
msgstr ""

#: ../../c-api/module.rst:152
msgid "Name for the new module."
msgstr ""

#: ../../c-api/module.rst:156
msgid ""
"Docstring for the module; usually a docstring variable created with :c:macro:"
"`PyDoc_STRVAR` is used."
msgstr ""

#: ../../c-api/module.rst:161
msgid ""
"Module state may be kept in a per-module memory area that can be retrieved "
"with :c:func:`PyModule_GetState`, rather than in static globals. This makes "
"modules safe for use in multiple sub-interpreters."
msgstr ""

#: ../../c-api/module.rst:165
msgid ""
"This memory area is allocated based on *m_size* on module creation, and "
"freed when the module object is deallocated, after the :c:member:`m_free` "
"function has been called, if present."
msgstr ""

#: ../../c-api/module.rst:169
msgid ""
"Setting ``m_size`` to ``-1`` means that the module does not support sub-"
"interpreters, because it has global state."
msgstr ""

#: ../../c-api/module.rst:172
msgid ""
"Setting it to a non-negative value means that the module can be re-"
"initialized and specifies the additional amount of memory it requires for "
"its state. Non-negative ``m_size`` is required for multi-phase "
"initialization."
msgstr ""

#: ../../c-api/module.rst:177
msgid "See :PEP:`3121` for more details."
msgstr "更多詳情請見 :pep:`3121`\\ 。"

#: ../../c-api/module.rst:181
msgid ""
"A pointer to a table of module-level functions, described by :c:type:"
"`PyMethodDef` values.  Can be ``NULL`` if no functions are present."
msgstr ""

#: ../../c-api/module.rst:186
msgid ""
"An array of slot definitions for multi-phase initialization, terminated by a "
"``{0, NULL}`` entry. When using single-phase initialization, *m_slots* must "
"be ``NULL``."
msgstr ""

#: ../../c-api/module.rst:192
msgid ""
"Prior to version 3.5, this member was always set to ``NULL``, and was "
"defined as:"
msgstr ""

#: ../../c-api/module.rst:199
msgid ""
"A traversal function to call during GC traversal of the module object, or "
"``NULL`` if not needed."
msgstr ""

#: ../../c-api/module.rst:202 ../../c-api/module.rst:217
#: ../../c-api/module.rst:238
msgid ""
"This function is not called if the module state was requested but is not "
"allocated yet. This is the case immediately after the module is created and "
"before the module is executed (:c:data:`Py_mod_exec` function). More "
"precisely, this function is not called if :c:member:`m_size` is greater than "
"0 and the module state (as returned by :c:func:`PyModule_GetState`) is "
"``NULL``."
msgstr ""

#: ../../c-api/module.rst:209 ../../c-api/module.rst:230
#: ../../c-api/module.rst:245
msgid "No longer called before the module state is allocated."
msgstr ""

#: ../../c-api/module.rst:214
msgid ""
"A clear function to call during GC clearing of the module object, or "
"``NULL`` if not needed."
msgstr ""

#: ../../c-api/module.rst:224
msgid ""
"Like :c:member:`PyTypeObject.tp_clear`, this function is not *always* called "
"before a module is deallocated. For example, when reference counting is "
"enough to determine that an object is no longer used, the cyclic garbage "
"collector is not involved and :c:member:`~PyModuleDef.m_free` is called "
"directly."
msgstr ""

#: ../../c-api/module.rst:235
msgid ""
"A function to call during deallocation of the module object, or ``NULL`` if "
"not needed."
msgstr ""

#: ../../c-api/module.rst:249
msgid "Single-phase initialization"
msgstr ""

#: ../../c-api/module.rst:251
msgid ""
"The module initialization function may create and return the module object "
"directly. This is referred to as \"single-phase initialization\", and uses "
"one of the following two module creation functions:"
msgstr ""

#: ../../c-api/module.rst:257
msgid ""
"Create a new module object, given the definition in *def*.  This behaves "
"like :c:func:`PyModule_Create2` with *module_api_version* set to :const:"
"`PYTHON_API_VERSION`."
msgstr ""

#: ../../c-api/module.rst:264
msgid ""
"Create a new module object, given the definition in *def*, assuming the API "
"version *module_api_version*.  If that version does not match the version of "
"the running interpreter, a :exc:`RuntimeWarning` is emitted."
msgstr ""

#: ../../c-api/module.rst:270
msgid ""
"Most uses of this function should be using :c:func:`PyModule_Create` "
"instead; only use this if you are sure you need it."
msgstr ""

#: ../../c-api/module.rst:273
msgid ""
"Before it is returned from in the initialization function, the resulting "
"module object is typically populated using functions like :c:func:"
"`PyModule_AddObjectRef`."
msgstr ""

#: ../../c-api/module.rst:279
msgid "Multi-phase initialization"
msgstr ""

#: ../../c-api/module.rst:281
msgid ""
"An alternate way to specify extensions is to request \"multi-phase "
"initialization\". Extension modules created this way behave more like Python "
"modules: the initialization is split between the *creation phase*, when the "
"module object is created, and the *execution phase*, when it is populated. "
"The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` "
"methods of classes."
msgstr ""

#: ../../c-api/module.rst:288
msgid ""
"Unlike modules created using single-phase initialization, these modules are "
"not singletons: if the *sys.modules* entry is removed and the module is re-"
"imported, a new module object is created, and the old module is subject to "
"normal garbage collection -- as with Python modules. By default, multiple "
"modules created from the same definition should be independent: changes to "
"one should not affect the others. This means that all state should be "
"specific to the module object (using e.g. using :c:func:"
"`PyModule_GetState`), or its contents (such as the module's :attr:`__dict__` "
"or individual classes created with :c:func:`PyType_FromSpec`)."
msgstr ""

#: ../../c-api/module.rst:298
msgid ""
"All modules created using multi-phase initialization are expected to "
"support :ref:`sub-interpreters <sub-interpreter-support>`. Making sure "
"multiple modules are independent is typically enough to achieve this."
msgstr ""

#: ../../c-api/module.rst:302
msgid ""
"To request multi-phase initialization, the initialization function "
"(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty :"
"c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef`` "
"instance must be initialized with the following function:"
msgstr ""

#: ../../c-api/module.rst:309
msgid ""
"Ensures a module definition is a properly initialized Python object that "
"correctly reports its type and reference count."
msgstr ""

#: ../../c-api/module.rst:312
msgid "Returns *def* cast to ``PyObject*``, or ``NULL`` if an error occurred."
msgstr ""

#: ../../c-api/module.rst:316
msgid ""
"The *m_slots* member of the module definition must point to an array of "
"``PyModuleDef_Slot`` structures:"
msgstr ""

#: ../../c-api/module.rst:323
msgid "A slot ID, chosen from the available values explained below."
msgstr ""

#: ../../c-api/module.rst:327
msgid "Value of the slot, whose meaning depends on the slot ID."
msgstr ""

#: ../../c-api/module.rst:331
msgid "The *m_slots* array must be terminated by a slot with id 0."
msgstr ""

#: ../../c-api/module.rst:333
msgid "The available slot types are:"
msgstr ""

#: ../../c-api/module.rst:337
msgid ""
"Specifies a function that is called to create the module object itself. The "
"*value* pointer of this slot must point to a function of the signature:"
msgstr ""

#: ../../c-api/module.rst:342
msgid ""
"The function receives a :py:class:`~importlib.machinery.ModuleSpec` "
"instance, as defined in :PEP:`451`, and the module definition. It should "
"return a new module object, or set an error and return ``NULL``."
msgstr ""

#: ../../c-api/module.rst:347
msgid ""
"This function should be kept minimal. In particular, it should not call "
"arbitrary Python code, as trying to import the same module again may result "
"in an infinite loop."
msgstr ""

#: ../../c-api/module.rst:351
msgid ""
"Multiple ``Py_mod_create`` slots may not be specified in one module "
"definition."
msgstr ""

#: ../../c-api/module.rst:354
msgid ""
"If ``Py_mod_create`` is not specified, the import machinery will create a "
"normal module object using :c:func:`PyModule_New`. The name is taken from "
"*spec*, not the definition, to allow extension modules to dynamically adjust "
"to their place in the module hierarchy and be imported under different names "
"through symlinks, all while sharing a single module definition."
msgstr ""

#: ../../c-api/module.rst:360
msgid ""
"There is no requirement for the returned object to be an instance of :c:type:"
"`PyModule_Type`. Any type can be used, as long as it supports setting and "
"getting import-related attributes. However, only ``PyModule_Type`` instances "
"may be returned if the ``PyModuleDef`` has non-``NULL`` ``m_traverse``, "
"``m_clear``, ``m_free``; non-zero ``m_size``; or slots other than "
"``Py_mod_create``."
msgstr ""

#: ../../c-api/module.rst:369
msgid ""
"Specifies a function that is called to *execute* the module. This is "
"equivalent to executing the code of a Python module: typically, this "
"function adds classes and constants to the module. The signature of the "
"function is:"
msgstr ""

#: ../../c-api/module.rst:376
msgid ""
"If multiple ``Py_mod_exec`` slots are specified, they are processed in the "
"order they appear in the *m_slots* array."
msgstr ""

#: ../../c-api/module.rst:379
msgid "See :PEP:`489` for more details on multi-phase initialization."
msgstr ""

#: ../../c-api/module.rst:382
msgid "Low-level module creation functions"
msgstr ""

#: ../../c-api/module.rst:384
msgid ""
"The following functions are called under the hood when using multi-phase "
"initialization. They can be used directly, for example when creating module "
"objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and "
"``PyModule_ExecDef`` must be called to fully initialize a module."
msgstr ""

#: ../../c-api/module.rst:391
msgid ""
"Create a new module object, given the definition in *module* and the "
"ModuleSpec *spec*.  This behaves like :c:func:`PyModule_FromDefAndSpec2` "
"with *module_api_version* set to :const:`PYTHON_API_VERSION`."
msgstr ""

#: ../../c-api/module.rst:399
msgid ""
"Create a new module object, given the definition in *module* and the "
"ModuleSpec *spec*, assuming the API version *module_api_version*. If that "
"version does not match the version of the running interpreter, a :exc:"
"`RuntimeWarning` is emitted."
msgstr ""

#: ../../c-api/module.rst:406
msgid ""
"Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec` "
"instead; only use this if you are sure you need it."
msgstr ""

#: ../../c-api/module.rst:413
msgid "Process any execution slots (:c:data:`Py_mod_exec`) given in *def*."
msgstr ""

#: ../../c-api/module.rst:419
msgid ""
"Set the docstring for *module* to *docstring*. This function is called "
"automatically when creating a module from ``PyModuleDef``, using either "
"``PyModule_Create`` or ``PyModule_FromDefAndSpec``."
msgstr ""

#: ../../c-api/module.rst:428
msgid ""
"Add the functions from the ``NULL`` terminated *functions* array to "
"*module*. Refer to the :c:type:`PyMethodDef` documentation for details on "
"individual entries (due to the lack of a shared module namespace, module "
"level \"functions\" implemented in C typically receive the module as their "
"first parameter, making them similar to instance methods on Python classes). "
"This function is called automatically when creating a module from "
"``PyModuleDef``, using either ``PyModule_Create`` or "
"``PyModule_FromDefAndSpec``."
msgstr ""

#: ../../c-api/module.rst:440
msgid "Support functions"
msgstr ""

#: ../../c-api/module.rst:442
msgid ""
"The module initialization function (if using single phase initialization) or "
"a function called from a module execution slot (if using multi-phase "
"initialization), can use the following functions to help initialize the "
"module state:"
msgstr ""

#: ../../c-api/module.rst:449
msgid ""
"Add an object to *module* as *name*.  This is a convenience function which "
"can be used from the module's initialization function."
msgstr ""

#: ../../c-api/module.rst:452
msgid ""
"On success, return ``0``. On error, raise an exception and return ``-1``."
msgstr ""

#: ../../c-api/module.rst:454
msgid ""
"Return ``NULL`` if *value* is ``NULL``. It must be called with an exception "
"raised in this case."
msgstr ""

#: ../../c-api/module.rst:457 ../../c-api/module.rst:506
msgid "Example usage::"
msgstr ""
"用法範例：\n"
"\n"
"::"

#: ../../c-api/module.rst:471 ../../c-api/module.rst:524
msgid ""
"The example can also be written without checking explicitly if *obj* is "
"``NULL``::"
msgstr ""

#: ../../c-api/module.rst:483 ../../c-api/module.rst:540
msgid ""
"Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in this "
"case, since *obj* can be ``NULL``."
msgstr ""

#: ../../c-api/module.rst:491
msgid ""
"Similar to :c:func:`PyModule_AddObjectRef`, but steals a reference to "
"*value* on success (if it returns ``0``)."
msgstr ""

#: ../../c-api/module.rst:494
msgid ""
"The new :c:func:`PyModule_AddObjectRef` function is recommended, since it is "
"easy to introduce reference leaks by misusing the :c:func:"
"`PyModule_AddObject` function."
msgstr ""

#: ../../c-api/module.rst:500
msgid ""
"Unlike other functions that steal references, ``PyModule_AddObject()`` only "
"decrements the reference count of *value* **on success**."
msgstr ""

#: ../../c-api/module.rst:503
msgid ""
"This means that its return value must be checked, and calling code must :c:"
"func:`Py_DECREF` *value* manually on error."
msgstr ""

#: ../../c-api/module.rst:546
msgid ""
"Add an integer constant to *module* as *name*.  This convenience function "
"can be used from the module's initialization function. Return ``-1`` on "
"error, ``0`` on success."
msgstr ""

#: ../../c-api/module.rst:553
msgid ""
"Add a string constant to *module* as *name*.  This convenience function can "
"be used from the module's initialization function.  The string *value* must "
"be ``NULL``-terminated.  Return ``-1`` on error, ``0`` on success."
msgstr ""

#: ../../c-api/module.rst:560
msgid ""
"Add an int constant to *module*. The name and the value are taken from "
"*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int "
"constant *AF_INET* with the value of *AF_INET* to *module*. Return ``-1`` on "
"error, ``0`` on success."
msgstr ""

#: ../../c-api/module.rst:568
msgid "Add a string constant to *module*."
msgstr ""

#: ../../c-api/module.rst:572
msgid ""
"Add a type object to *module*. The type object is finalized by calling "
"internally :c:func:`PyType_Ready`. The name of the type object is taken from "
"the last component of :c:member:`~PyTypeObject.tp_name` after dot. Return "
"``-1`` on error, ``0`` on success."
msgstr ""

#: ../../c-api/module.rst:582
msgid "Module lookup"
msgstr ""

#: ../../c-api/module.rst:584
msgid ""
"Single-phase initialization creates singleton modules that can be looked up "
"in the context of the current interpreter. This allows the module object to "
"be retrieved later with only a reference to the module definition."
msgstr ""

#: ../../c-api/module.rst:588
msgid ""
"These functions will not work on modules created using multi-phase "
"initialization, since multiple such modules can be created from a single "
"definition."
msgstr ""

#: ../../c-api/module.rst:593
msgid ""
"Returns the module object that was created from *def* for the current "
"interpreter. This method requires that the module object has been attached "
"to the interpreter state with :c:func:`PyState_AddModule` beforehand. In "
"case the corresponding module object is not found or has not been attached "
"to the interpreter state yet, it returns ``NULL``."
msgstr ""

#: ../../c-api/module.rst:600
msgid ""
"Attaches the module object passed to the function to the interpreter state. "
"This allows the module object to be accessible via :c:func:"
"`PyState_FindModule`."
msgstr ""

#: ../../c-api/module.rst:603
msgid "Only effective on modules created using single-phase initialization."
msgstr ""

#: ../../c-api/module.rst:605
msgid ""
"Python calls ``PyState_AddModule`` automatically after importing a module, "
"so it is unnecessary (but harmless) to call it from module initialization "
"code. An explicit call is needed only if the module's own init code "
"subsequently calls ``PyState_FindModule``. The function is mainly intended "
"for implementing alternative import mechanisms (either by calling it "
"directly, or by referring to its implementation for details of the required "
"state updates)."
msgstr ""

#: ../../c-api/module.rst:613 ../../c-api/module.rst:624
msgid "The caller must hold the GIL."
msgstr ""

#: ../../c-api/module.rst:615
msgid "Return 0 on success or -1 on failure."
msgstr ""

#: ../../c-api/module.rst:621
msgid ""
"Removes the module object created from *def* from the interpreter state. "
"Return 0 on success or -1 on failure."
msgstr ""