extension-modules.po

# 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, 2026
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Python 3.15\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-06-25 16:18+0000\n"
"PO-Revision-Date: 2025-09-16 00:00+0000\n"
"Last-Translator: python-doc bot, 2026\n"
"Language-Team: Portuguese (Brazil) (https://app.transifex.com/python-doc/"
"teams/5390/pt_BR/)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: pt_BR\n"
"Plural-Forms: nplurals=3; plural=(n == 0 || n == 1) ? 0 : n != 0 && n % "
"1000000 == 0 ? 1 : 2;\n"

#: ../../c-api/extension-modules.rst:6
msgid "Defining extension modules"
msgstr "Definindo módulos de extensão"

#: ../../c-api/extension-modules.rst:8
msgid ""
"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>`)."
msgstr ""

#: ../../c-api/extension-modules.rst:14
msgid ""
"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`."
msgstr ""
"Para ser importável por padrão (ou seja, por :py:class:`importlib.machinery."
"ExtensionFileLoader`), a biblioteca compartilhada deve estar disponível em :"
"py:attr:`sys.path` e deve ser nomeada após o nome do módulo mais uma "
"extensão listada em :py:attr:`importlib.machinery.EXTENSION_SUFFIXES`."

#: ../../c-api/extension-modules.rst:22
msgid ""
"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."
msgstr ""
"A construção, o empacotamento e a distribuição de módulos de extensão são "
"melhor realizados com ferramentas de terceiros e estão fora do escopo deste "
"documento. Uma ferramenta adequada é o Setuptools, cuja documentação pode "
"ser encontrada em https://setuptools.pypa.io/en/latest/setuptools.html."

#: ../../c-api/extension-modules.rst:30
msgid "Extension export hook"
msgstr ""

#: ../../c-api/extension-modules.rst:34
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:39
msgid ""
"The export hook must be an exported function with the following signature:"
msgstr ""

#: ../../c-api/extension-modules.rst:43
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:47
msgid ""
"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:"
msgstr ""

#: ../../c-api/extension-modules.rst:51
msgid ""
"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"
msgstr ""

#: ../../c-api/extension-modules.rst:60
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:64
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:69
msgid ""
"The export hook may return ``NULL`` with an exception set to signal failure."
msgstr ""

#: ../../c-api/extension-modules.rst:71
msgid ""
"It is recommended to define the export hook function using a helper macro:"
msgstr ""

#: ../../c-api/extension-modules.rst:75
msgid "Declare an extension module export hook. This macro:"
msgstr ""

#: ../../c-api/extension-modules.rst:78
msgid "specifies the :c:expr:`PySlot*` return type,"
msgstr ""

#: ../../c-api/extension-modules.rst:79 ../../c-api/extension-modules.rst:248
msgid "adds any special linkage declarations required by the platform, and"
msgstr ""
"adiciona quaisquer declarações de vinculação especiais exigidas pela "
"plataforma e"

#: ../../c-api/extension-modules.rst:80 ../../c-api/extension-modules.rst:249
msgid "for C++, declares the function as ``extern \"C\"``."
msgstr "para C++, declara a função como ``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::"
msgstr "Por exemplo, um módulo chamado ``spam`` seria definido assim::"

#: ../../c-api/extension-modules.rst:84
msgid ""
"PyABIInfo_VAR(abi_info);\n"
"\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"
"};\n"
"\n"
"PyMODEXPORT_FUNC\n"
"PyModExport_spam(void)\n"
"{\n"
"    return spam_slots;\n"
"}"
msgstr ""

#: ../../c-api/extension-modules.rst:100
msgid ""
"The export hook is typically the only non-\\ ``static`` item defined in the "
"module's C source."
msgstr ""

#: ../../c-api/extension-modules.rst:105
msgid ""
"The hook should be kept short. If it does more than ``return`` a static "
"array, several caveats apply:"
msgstr ""

#: ../../c-api/extension-modules.rst:108
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:111
msgid ""
"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,"
msgstr ""

#: ../../c-api/extension-modules.rst:114
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:118
msgid "For example::"
msgstr "Por exemplo::"

#: ../../c-api/extension-modules.rst:120
msgid ""
"PyMODEXPORT_FUNC\n"
"PyModExport_modulename(void)\n"
"{\n"
"   if (PyABIInfo_Check(&abi_info, \"modulename\") < 0) {\n"
"      /* ABI mismatch. It's not safe to examine the raised exception. */\n"
"      return NULL;\n"
"   }\n"
"\n"
"   /* use Python API (as little as possible); don't rely on GIL */\n"
"\n"
"   return modulename_slots;\n"
"}"
msgstr ""

#: ../../c-api/extension-modules.rst:135
msgid ""
"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 "
"details."
msgstr ""

#: ../../c-api/extension-modules.rst:147
msgid "Multi-phase initialization"
msgstr "Inicialização multifásica"

#: ../../c-api/extension-modules.rst:149
msgid "The process of creating an extension module follows several phases:"
msgstr ""

#: ../../c-api/extension-modules.rst:151
msgid ""
"Python finds and calls the export hook to get information on how to create "
"the module."
msgstr ""

#: ../../c-api/extension-modules.rst:153
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:158
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:161
msgid ""
"Python sets initial module attributes like :attr:`~module.__package__` and :"
"attr:`~module.__loader__`, and inserts the module object into :py:attr:`sys."
"modules`."
msgstr ""

#: ../../c-api/extension-modules.rst:164
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:169
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:175
msgid "Added support for multi-phase initialization (:pep:`489`)."
msgstr "Adicionado suporte para inicialização multifásica (:pep:`489`)."

#: ../../c-api/extension-modules.rst:179
msgid "Multiple module instances"
msgstr "Várias instâncias de módulo"

#: ../../c-api/extension-modules.rst:181
msgid ""
"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."
msgstr ""

#: ../../c-api/extension-modules.rst:188
msgid ""
"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."
msgstr ""
"Instâncias adicionais do módulo podem ser criadas em :ref:"
"`subinterpretadores <sub-interpreter-support>` ou após a reinicialização do "
"tempo de execução do Python (:c:func:`Py_Finalize` e :c:func:"
"`Py_Initialize`). Nesses casos, compartilhar objetos Python entre instâncias "
"do módulo provavelmente causaria travamentos ou comportamento indefinido."

#: ../../c-api/extension-modules.rst:195
msgid ""
"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."
msgstr ""
"Para evitar tais problemas, cada instância de um módulo de extensão deve ser "
"*isolada*: alterações em uma instância não devem afetar implicitamente as "
"outras, e todos os estados pertencentes ao módulo, incluindo referências a "
"objetos Python, devem ser específicos de uma instância específica do módulo. "
"Consulte :ref:`isolating-extensions-howto` para obter mais detalhes e um "
"guia prático."

#: ../../c-api/extension-modules.rst:201
msgid ""
"A simpler way to avoid these issues is :ref:`raising an error on repeated "
"initialization <isolating-extensions-optout>`."
msgstr ""
"Uma maneira mais simples de evitar esses problemas é :ref:`levantar um erro "
"na inicialização repetida <isolating-extensions-optout>`."

#: ../../c-api/extension-modules.rst:204
msgid ""
"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."
msgstr ""
"Espera-se que todos os módulos ofereçam suporte a :ref:`subinterpretador "
"<sub-interpreter-support>`, ou então sinalizem explicitamente a falta de "
"suporte. Isso geralmente é obtido por isolamento ou bloqueio de "
"inicializações repetidas, como acima. Um módulo também pode ser limitado ao "
"interpretador principal usando o slot :c:data:`Py_mod_multiple_interpreters`."

#: ../../c-api/extension-modules.rst:216
msgid "``PyInit`` function"
msgstr ""

#: ../../c-api/extension-modules.rst:220
msgid ""
"This functionality will not get new features, but there are no plans to "
"remove it."
msgstr ""

#: ../../c-api/extension-modules.rst:223
msgid ""
"Instead of :c:func:`PyModExport_modulename`, an extension module can define "
"an older-style :dfn:`initialization function` with the signature:"
msgstr ""

#: ../../c-api/extension-modules.rst:228
msgid ""
"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)."
msgstr ""

#: ../../c-api/extension-modules.rst:235
msgid ""
"If a module exports both :samp:`PyInit_{<name>}` and :samp:"
"`PyModExport_{<name>}`, the :samp:`PyInit_{<name>}` function is ignored."
msgstr ""

#: ../../c-api/extension-modules.rst:239
msgid ""
"Like with :c:macro:`PyMODEXPORT_FUNC`, it is recommended to define the "
"initialization function using a helper macro:"
msgstr ""

#: ../../c-api/extension-modules.rst:244
msgid "Declare an extension module initialization function. This macro:"
msgstr "Declara uma função de inicialização do módulo de extensão. Esta macro:"

#: ../../c-api/extension-modules.rst:247
msgid "specifies the :c:expr:`PyObject*` return type,"
msgstr "especifica o tipo de retorno :c:expr:`PyObject*`,"

#: ../../c-api/extension-modules.rst:252
msgid ""
"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>`."
msgstr ""

#: ../../c-api/extension-modules.rst:257
msgid ""
"Before it is returned, the ``PyModuleDef`` instance must be initialized "
"using the following function:"
msgstr ""

#: ../../c-api/extension-modules.rst:262
msgid ""
"Ensure a module definition is a properly initialized Python object that "
"correctly reports its type and a reference count."
msgstr ""
"Garante que uma definição de módulo é um objeto Python devidamente "
"inicializado que reporta corretamente seu tipo e uma contagem de referências."

#: ../../c-api/extension-modules.rst:265
msgid "Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred."
msgstr ""
"Retorna *def* convertido para ``PyObject*``, ou ``NULL`` se ocorrer um erro."

#: ../../c-api/extension-modules.rst:267
msgid ""
"Calling this function is required before returning a :c:type:`PyModuleDef` "
"from a module initialization function. It should not be used in other "
"contexts."
msgstr ""

#: ../../c-api/extension-modules.rst:271
msgid ""
"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."
msgstr ""
"Observe que o Python assume que as estruturas ``PyModuleDef`` são alocadas "
"estaticamente. Esta função pode retornar uma nova referência ou uma "
"referência emprestada; esta referência não deve ser liberada."

#: ../../c-api/extension-modules.rst:281
msgid ""
"static struct PyModuleDef spam_module = {\n"
"    .m_base = PyModuleDef_HEAD_INIT,\n"
"    .m_name = \"spam\",\n"
"    ...\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    return PyModuleDef_Init(&spam_module);\n"
"}"
msgstr ""
"static struct PyModuleDef spam_module = {\n"
"    .m_base = PyModuleDef_HEAD_INIT,\n"
"    .m_name = \"spam\",\n"
"    ...\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_spam(void)\n"
"{\n"
"    return PyModuleDef_Init(&spam_module);\n"
"}"

#: ../../c-api/extension-modules.rst:297
msgid "Legacy single-phase initialization"
msgstr "Inicialização monofásica legada"

#: ../../c-api/extension-modules.rst:301
msgid ""
"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."
msgstr ""
"A inicialização monofásica é um mecanismo legado para inicializar módulos de "
"extensão, com desvantagens e falhas de projeto conhecidas. Os autores de "
"módulos de extensão são incentivados a utilizar a inicialização multifásica."

#: ../../c-api/extension-modules.rst:305
msgid "However, there are no plans to remove support for it."
msgstr ""

#: ../../c-api/extension-modules.rst:307
msgid ""
"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`."
msgstr ""

#: ../../c-api/extension-modules.rst:313
msgid ""
"Single-phase initialization differs from the :ref:`default <multi-phase-"
"initialization>` in the following ways:"
msgstr ""
"A inicialização monofásica difere do :ref:`padrão <multi-phase-"
"initialization>` nas seguintes maneiras:"

#: ../../c-api/extension-modules.rst:316
msgid "Single-phase modules are, or rather *contain*, “singletons”."
msgstr "Módulos monofásicos são, ou melhor, *contêm*, “singletons”."

#: ../../c-api/extension-modules.rst:318
msgid ""
"When the module is first initialized, Python saves the contents of the "
"module's ``__dict__`` (that is, typically, the module's functions and types)."
msgstr ""
"Quando o módulo é inicializado pela primeira vez, o Python salva o conteúdo "
"do ``__dict__`` do módulo (ou seja, normalmente, as funções e os tipos do "
"módulo)."

#: ../../c-api/extension-modules.rst:322
msgid ""
"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``:"
msgstr ""
"Para importações subsequentes, o Python não chama a função de inicialização "
"novamente. Em vez disso, ele cria um novo objeto de módulo com um novo "
"``__dict__`` e copia o conteúdo salvo para ele. Por exemplo, dado um módulo "
"monofásico ``_testsinglephase`` [#testsinglephase]_ que define uma função "
"``sum`` e uma classe de exceção ``error``:"

#: ../../c-api/extension-modules.rst:330
msgid ""
">>> import sys\n"
">>> import _testsinglephase as one\n"
">>> del sys.modules['_testsinglephase']\n"
">>> import _testsinglephase as two\n"
">>> one is two\n"
"False\n"
">>> one.__dict__ is two.__dict__\n"
"False\n"
">>> one.sum is two.sum\n"
"True\n"
">>> one.error is two.error\n"
"True"
msgstr ""
">>> import sys\n"
">>> import _testsinglephase as one\n"
">>> del sys.modules['_testsinglephase']\n"
">>> import _testsinglephase as two\n"
">>> one is two\n"
"False\n"
">>> one.__dict__ is two.__dict__\n"
"False\n"
">>> one.sum is two.sum\n"
"True\n"
">>> one.error is two.error\n"
"True"

#: ../../c-api/extension-modules.rst:345
msgid ""
"The exact behavior should be considered a CPython implementation detail."
msgstr ""
"O comportamento exato deve ser considerado um detalhe da implementação do "
"CPython."

#: ../../c-api/extension-modules.rst:347
msgid ""
"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."
msgstr ""
"Para contornar o fato de que ``PyInit_modulename`` não aceita um argumento "
"*spec*, parte do estado do mecanismo de importação é salvo e aplicado ao "
"primeiro módulo adequado criado durante a chamada ``PyInit_modulename``. "
"Especificamente, quando um submódulo é importado, esse mecanismo adiciona o "
"nome do pacote pai ao nome do módulo."

#: ../../c-api/extension-modules.rst:353
msgid ""
"A single-phase ``PyInit_modulename`` function should create “its” module "
"object as soon as possible, before any other module objects can be created."
msgstr ""
"Uma função monofásica ``PyInit_modulename`` deve criar “seu” objeto de "
"módulo o mais rápido possível, antes que qualquer outro objeto de módulo "
"possa ser criado."

#: ../../c-api/extension-modules.rst:356
msgid "Non-ASCII module names (``PyInitU_modulename``) are not supported."
msgstr ""
"Nomes de módulos não ASCII (``PyInitU_modulename``) não são suportados."

#: ../../c-api/extension-modules.rst:358
msgid ""
"Single-phase modules support module lookup functions like :c:func:"
"`PyState_FindModule`."
msgstr ""
"Módulos monofásicos oferecem suporte a funções de pesquisa de módulos como :"
"c:func:`PyState_FindModule`."

#: ../../c-api/extension-modules.rst:361
msgid "The module's :c:member:`PyModuleDef.m_slots` must be NULL."
msgstr ""

#: ../../c-api/extension-modules.rst:363
msgid ""
"``_testsinglephase`` is an internal module used in CPython's self-test "
"suite; your installation may or may not include it."
msgstr ""
"``_testsinglephase`` é um módulo interno usado no conjunto de autotestes do "
"CPython; sua instalação pode ou não incluí-lo."