Objetos do Módulo
*****************

PyTypeObject PyModule_Type
    * Parte da ABI Estável.*

   Esta instância de "PyTypeObject" representa o tipo de módulo
   Python. Isso é exposto a programas Python como "types.ModuleType".

int PyModule_Check(PyObject *p)

   Retorna true se *p* for um objeto de módulo ou um subtipo de um
   objeto de módulo. Esta função sempre é bem-sucedida.

int PyModule_CheckExact(PyObject *p)

   Retorna true se *p* for um objeto de módulo, mas não um subtipo de
   "PyModule_Type". Essa função é sempre bem-sucedida.

PyObject *PyModule_NewObject(PyObject *name)
    *Retorna valor: Nova referência.** Parte da ABI Estável desde a
   versão 3.7.*

   Retorna um novo objeto de módulo com "module.__name__" definido
   como *name*. Os atributos "__name__", "__doc__", "__package__" e
   "__loader__" do módulo são preenchidos (todos, exceto "__name__",
   são definidos como "None"). O chamador é responsável por definir um
   atributo "__file__".

   Retorna "NULL" com uma exceção definida em caso de erro.

   Adicionado na versão 3.3.

   Alterado na versão 3.4: "__package__" e "__loader__" agora estão
   definidos como "None".

PyObject *PyModule_New(const char *name)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Semelhante a "PyModule_NewObject()", mas o nome é uma string
   codificada em UTF-8 em vez de um objeto Unicode.

PyObject *PyModule_GetDict(PyObject *module)
    *Retorna valor: Referência emprestada.** Parte da ABI Estável.*

   Retorna o objeto dicionário que implementa o espaço de nomes de
   *module*; este objeto é o mesmo que o atributo "__dict__" do objeto
   de módulo. Se *module* não for um objeto de módulo (ou um subtipo
   de um objeto de módulo), "SystemError" é levantada e "NULL" é
   retornado.

   É recomendado que as extensões usem outras funções "PyModule_*" e
   "PyObject_*" em vez de manipular diretamente o "__dict__" de um
   módulo.

PyObject *PyModule_GetNameObject(PyObject *module)
    *Retorna valor: Nova referência.** Parte da ABI Estável desde a
   versão 3.7.*

   Retorna o valor "__name__" do *module*. Se o módulo não fornecer
   um, ou se não for uma string, "SystemError" é levantada e "NULL" é
   retornado.

   Adicionado na versão 3.3.

const char *PyModule_GetName(PyObject *module)
    * Parte da ABI Estável.*

   Semelhante a "PyModule_GetNameObject()" mas retorna o nome
   codificado em "'utf-8'"

void *PyModule_GetState(PyObject *module)
    * Parte da ABI Estável.*

   Retorna o "estado" do módulo, ou seja, um ponteiro para o bloco de
   memória alocado no momento de criação do módulo, ou "NULL". Ver
   "PyModuleDef.m_size".

PyModuleDef *PyModule_GetDef(PyObject *module)
    * Parte da ABI Estável.*

   Retorna um ponteiro para a estrutura "PyModuleDef" da qual o módulo
   foi criado, ou "NULL" se o módulo não foi criado de uma definição.

PyObject *PyModule_GetFilenameObject(PyObject *module)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna o nome do arquivo do qual o *module* foi carregado usando o
   atributo "__file__" do *module*. Se não estiver definido, ou se não
   for uma string unicode, levanta "SystemError" e retorna "NULL";
   Caso contrário, retorna uma referência a um objeto Unicode.

   Adicionado na versão 3.2.

const char *PyModule_GetFilename(PyObject *module)
    * Parte da ABI Estável.*

   Semelhante a "PyModule_GetFilenameObject()" mas retorna o nome do
   arquivo codificado em 'utf-8'.

   Descontinuado desde a versão 3.2: "PyModule_GetFilename()": levanta
   "UnicodeEncodeError" quando há nomes de arquivos não codificáveis,
   use "PyModule_GetFilenameObject()".


Module definitions
******************

The functions in the previous section work on any module object,
including modules imported from Python code.

Modules defined using the C API typically use a *module definition*,
"PyModuleDef" -- a statically allocated, constant “description" of how
a module should be created.

The definition is usually used to define an extension's “main” module
object (see Definindo módulos de extensão for details). It is also
used to create extension modules dynamically.

Unlike "PyModule_New()", the definition allows management of *module
state* -- a piece of memory that is allocated and cleared together
with the module object. Unlike the module's Python attributes, Python
code cannot replace or delete data stored in module state.

type PyModuleDef
    * Parte da ABI Estável (incluindo todos os membros).*

   The module definition struct, which holds all information needed to
   create a module object. This structure must be statically allocated
   (or be otherwise guaranteed to be valid while any modules created
   from it exist). Usually, there is only one variable of this type
   for each extension module.

   PyModuleDef_Base m_base

      Sempre inicializa este membro para "PyModuleDef_HEAD_INIT".

   const char *m_name

      Nome para o novo módulo.

   const char *m_doc

      Docstring para o módulo; geralmente uma variável docstring
      criada com "PyDoc_STRVAR" é usada.

   Py_ssize_t m_size

      O estado do módulo pode ser mantido em uma área de memória por
      módulo que pode ser recuperada com "PyModule_GetState()", em vez
      de em globais estáticos. Isso torna os módulos seguros para uso
      em vários subinterpretadores.

      Esta área de memória é alocada com base em *m_size* na criação
      do módulo e liberada quando o objeto do módulo é desalocado,
      após a função "m_free" ter sido chamada, se presente.

      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.

      Setting "m_size" to "-1" means that the module does not support
      sub-interpreters, because it has global state. Negative "m_size"
      is only allowed when using legacy single-phase initialization or
      when creating modules dynamically.

      Ver **PEP 3121** para mais detalhes.

   PyMethodDef *m_methods

      Um ponteiro para uma tabela de funções de nível de módulo,
      descritas por valores "PyMethodDef". Pode ser "NULL" se nenhuma
      função estiver presente.

   PyModuleDef_Slot *m_slots

      An array of slot definitions for multi-phase initialization,
      terminated by a "{0, NULL}" entry. When using legacy single-
      phase initialization, *m_slots* must be "NULL".

      Alterado na versão 3.5: Antes da versão 3.5, esse membro era
      sempre definido como "NULL" e era definido como:

         inquiry m_reload

   traverseproc m_traverse

      Uma função de travessia para chamar durante a travessia do GC do
      objeto do módulo, ou "NULL" se não for necessário.

      Esta função não é mais chamada se o estado do módulo foi
      solicitado, mas ainda não está alocado. Este é o caso
      imediatamente após o módulo ser criado e antes de o módulo ser
      executado (função "Py_mod_exec"). Mais precisamente, esta função
      não é chamada se "m_size" for maior que 0 e o estado do módulo
      (como retornado por "PyModule_GetState()") for "NULL".

      Alterado na versão 3.9: Não é mais chamado antes que o estado do
      módulo seja alocado.

   inquiry m_clear

      Uma função de limpeza para chamar durante a limpeza do GC do
      objeto do módulo, ou "NULL" se não for necessário.

      Esta função não é mais chamada se o estado do módulo foi
      solicitado, mas ainda não está alocado. Este é o caso
      imediatamente após o módulo ser criado e antes de o módulo ser
      executado (função "Py_mod_exec"). Mais precisamente, esta função
      não é chamada se "m_size" for maior que 0 e o estado do módulo
      (como retornado por "PyModule_GetState()") for "NULL".

      Assim como "PyTypeObject.tp_clear", esta função não é *sempre*
      chamada antes de um módulo ser desalocado. Por exemplo, quando a
      contagem de referências é suficiente para determinar que um
      objeto não é mais usado, o coletor de lixo cíclico não é
      envolvido e "m_free" é chamado diretamente.

      Alterado na versão 3.9: Não é mais chamado antes que o estado do
      módulo seja alocado.

   freefunc m_free

      Uma função para ser chamada durante a desalocação do objeto do
      módulo, ou "NULL" se não for necessário.

      Esta função não é mais chamada se o estado do módulo foi
      solicitado, mas ainda não está alocado. Este é o caso
      imediatamente após o módulo ser criado e antes de o módulo ser
      executado (função "Py_mod_exec"). Mais precisamente, esta função
      não é chamada se "m_size" for maior que 0 e o estado do módulo
      (como retornado por "PyModule_GetState()") for "NULL".

      Alterado na versão 3.9: Não é mais chamado antes que o estado do
      módulo seja alocado.


Module slots
============

type PyModuleDef_Slot

   int slot

      Um ID de lot, escolhido a partir dos valores disponíveis
      explicados abaixo.

   void *value

      Valor do slot, cujo significado depende do ID do slot.

   Adicionado na versão 3.5.

Os tipos de slot disponíveis são:

Py_mod_create

   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:

   PyObject *create_module(PyObject *spec, PyModuleDef *def)

   The function receives a "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".

   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.

   Múltiplos slots "Py_mod_create" podem não estar especificados em
   uma definição de módulo.

   If "Py_mod_create" is not specified, the import machinery will
   create a normal module object using "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.

   There is no requirement for the returned object to be an instance
   of "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".

Py_mod_exec

   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:

   int exec_module(PyObject *module)

   Se vários slots "Py_mod_exec" forem especificados, eles serão
   processados na ordem em que aparecem no vetor *m_slots*.

Py_mod_multiple_interpreters

   Specifies one of the following values:

   Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

      The module does not support being imported in subinterpreters.

   Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

      The module supports being imported in subinterpreters, but only
      when they share the main interpreter's GIL. (See Isolando
      módulos de extensão.)

   Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

      The module supports being imported in subinterpreters, even when
      they have their own GIL. (See Isolando módulos de extensão.)

   This slot determines whether or not importing this module in a
   subinterpreter will fail.

   Multiple "Py_mod_multiple_interpreters" slots may not be specified
   in one module definition.

   If "Py_mod_multiple_interpreters" is not specified, the import
   machinery defaults to "Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED".

   Adicionado na versão 3.12.

Py_mod_gil

   Specifies one of the following values:

   Py_MOD_GIL_USED

      The module depends on the presence of the global interpreter
      lock (GIL), and may access global state without synchronization.

   Py_MOD_GIL_NOT_USED

      The module is safe to run without an active GIL.

   This slot is ignored by Python builds not configured with "--
   disable-gil".  Otherwise, it determines whether or not importing
   this module will cause the GIL to be automatically enabled. See
   CPython com threads livres for more detail.

   Multiple "Py_mod_gil" slots may not be specified in one module
   definition.

   If "Py_mod_gil" is not specified, the import machinery defaults to
   "Py_MOD_GIL_USED".

   Adicionado na versão 3.13.


Creating extension modules dynamically
**************************************

The following functions may be used to create a module outside of an
extension's initialization function. They are also used in single-
phase initialization.

PyObject *PyModule_Create(PyModuleDef *def)
    *Retorna valor: Nova referência.*

   Create a new module object, given the definition in *def*. This is
   a macro that calls "PyModule_Create2()" with *module_api_version*
   set to "PYTHON_API_VERSION", or to "PYTHON_ABI_VERSION" if using
   the limited API.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   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 "RuntimeWarning" is
   emitted.

   Retorna "NULL" com uma exceção definida em caso de erro.

   This function does not support slots. The "m_slots" member of *def*
   must be "NULL".

   Nota:

     A maioria dos usos dessa função deve ser feita com
     "PyModule_Create()"; use-o apenas se tiver certeza de que
     precisa.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
    *Retorna valor: Nova referência.*

   This macro calls "PyModule_FromDefAndSpec2()" with
   *module_api_version* set to "PYTHON_API_VERSION", or to
   "PYTHON_ABI_VERSION" if using the limited API.

   Adicionado na versão 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
    *Retorna valor: Nova referência.** Parte da ABI Estável desde a
   versão 3.7.*

   Create a new module object, given the definition in *def* and the
   ModuleSpec *spec*, assuming the API version *module_api_version*.
   If that version does not match the version of the running
   interpreter, a "RuntimeWarning" is emitted.

   Retorna "NULL" com uma exceção definida em caso de erro.

   Note that this does not process execution slots ("Py_mod_exec").
   Both "PyModule_FromDefAndSpec" and "PyModule_ExecDef" must be
   called to fully initialize a module.

   Nota:

     Most uses of this function should be using
     "PyModule_FromDefAndSpec()" instead; only use this if you are
     sure you need it.

   Adicionado na versão 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
    * Parte da ABI Estável desde a versão 3.7.*

   Process any execution slots ("Py_mod_exec") given in *def*.

   Adicionado na versão 3.5.

PYTHON_API_VERSION

   The C API version. Defined for backwards compatibility.

   Atualmente, essa constante não é atualizada nas novas versões de
   Python e não é útil para controle de versão. Isso pode mudar no
   futuro.

PYTHON_ABI_VERSION

   Defined as "3" for backwards compatibility.

   Atualmente, essa constante não é atualizada nas novas versões de
   Python e não é útil para controle de versão. Isso pode mudar no
   futuro.


Support functions
*****************

The following functions are provided to help initialize a module
state. They are intended for a module's execution slots
("Py_mod_exec"), the initialization function for legacy single-phase
initialization, or code that creates modules dynamically.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
    * Parte da ABI Estável desde a versão 3.10.*

   Add an object to *module* as *name*.  This is a convenience
   function which can be used from the module's initialization
   function.

   On success, return "0". On error, raise an exception and return
   "-1".

   Exemplo de uso:

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          if (obj == NULL) {
              return -1;
          }
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_DECREF(obj);
          return res;
       }

   To be convenient, the function accepts "NULL" *value* with an
   exception set. In this case, return "-1" and just leave the raised
   exception unchanged.

   O exemplo também pode ser escrito sem verificar explicitamente se
   *obj* é "NULL":

      static int
      add_spam(PyObject *module, int value)
      {
          PyObject *obj = PyLong_FromLong(value);
          int res = PyModule_AddObjectRef(module, "spam", obj);
          Py_XDECREF(obj);
          return res;
       }

   Note that "Py_XDECREF()" should be used instead of "Py_DECREF()" in
   this case, since *obj* can be "NULL".

   The number of different *name* strings passed to this function
   should be kept small, usually by only using statically allocated
   strings as *name*. For names that aren't known at compile time,
   prefer calling "PyUnicode_FromString()" and "PyObject_SetAttr()"
   directly. For more details, see "PyUnicode_InternFromString()",
   which may be used internally to create a key object.

   Adicionado na versão 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)
    * Parte da ABI Estável desde a versão 3.13.*

   Similar to "PyModule_AddObjectRef()", but "steals" a reference to
   *value*. It can be called with a result of function that returns a
   new reference without bothering to check its result or even saving
   it to a variable.

   Exemplo de uso:

      if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
          goto error;
      }

   Adicionado na versão 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
    * Parte da ABI Estável.*

   Similar to "PyModule_AddObjectRef()", but steals a reference to
   *value* on success (if it returns "0").

   The new "PyModule_Add()" or "PyModule_AddObjectRef()" functions are
   recommended, since it is easy to introduce reference leaks by
   misusing the "PyModule_AddObject()" function.

   Nota:

     Unlike other functions that steal references,
     "PyModule_AddObject()" only releases the reference to *value*
     **on success**.This means that its return value must be checked,
     and calling code must "Py_XDECREF()" *value* manually on error.

   Exemplo de uso:

      PyObject *obj = PyBytes_FromString(value);
      if (PyModule_AddObject(module, "spam", obj) < 0) {
          // If 'obj' is not NULL and PyModule_AddObject() failed,
          // 'obj' strong reference must be deleted with Py_XDECREF().
          // If 'obj' is NULL, Py_XDECREF() does nothing.
          Py_XDECREF(obj);
          goto error;
      }
      // PyModule_AddObject() stole a reference to obj:
      // Py_XDECREF(obj) is not needed here.

   Descontinuado desde a versão 3.13: "PyModule_AddObject()" is *soft
   deprecated*.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
    * Parte da ABI Estável.*

   Add an integer constant to *module* as *name*.  This convenience
   function can be used from the module's initialization function.
   Return "-1" with an exception set on error, "0" on success.

   This is a convenience function that calls "PyLong_FromLong()" and
   "PyModule_AddObjectRef()"; see their documentation for details.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
    * Parte da ABI Estável.*

   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" with an
   exception set on error, "0" on success.

   This is a convenience function that calls
   "PyUnicode_InternFromString()" and "PyModule_AddObjectRef()"; see
   their documentation for details.

PyModule_AddIntMacro(module, macro)

   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" with an exception set on error, "0" on
   success.

PyModule_AddStringMacro(module, macro)

   Add a string constant to *module*.

int PyModule_AddType(PyObject *module, PyTypeObject *type)
    * Parte da ABI Estável desde a versão 3.10.*

   Add a type object to *module*. The type object is finalized by
   calling internally "PyType_Ready()". The name of the type object is
   taken from the last component of "tp_name" after dot. Return "-1"
   with an exception set on error, "0" on success.

   Adicionado na versão 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
    * Parte da ABI Estável desde a versão 3.7.*

   Add the functions from the "NULL" terminated *functions* array to
   *module*. Refer to the "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" (such as when using Inicialização multifásica,
   "PyModule_Create", or "PyModule_FromDefAndSpec"). Some module
   authors may prefer defining functions in multiple "PyMethodDef"
   arrays; in that case they should call this function directly.

   Adicionado na versão 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)
    * Parte da ABI Estável desde a versão 3.7.*

   Set the docstring for *module* to *docstring*. This function is
   called automatically when creating a module from "PyModuleDef"
   (such as when using Inicialização multifásica, "PyModule_Create",
   or "PyModule_FromDefAndSpec").

   Adicionado na versão 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

   Indicate that *module* does or does not support running without the
   global interpreter lock (GIL), using one of the values from
   "Py_mod_gil". It must be called during *module*'s initialization
   function when using Inicialização monofásica legada. If this
   function is not called during module initialization, the import
   machinery assumes the module does not support running without the
   GIL. This function is only available in Python builds configured
   with "--disable-gil". Return "-1" with an exception set on error,
   "0" on success.

   Adicionado na versão 3.13.


Module lookup (single-phase initialization)
===========================================

The legacy single-phase initialization initialization scheme 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.

These functions will not work on modules created using multi-phase
initialization, since multiple such modules can be created from a
single definition.

PyObject *PyState_FindModule(PyModuleDef *def)
    *Retorna valor: Referência emprestada.** Parte da ABI Estável.*

   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
   "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".

int PyState_AddModule(PyObject *module, PyModuleDef *def)
    * Parte da ABI Estável desde a versão 3.3.*

   Attaches the module object passed to the function to the
   interpreter state. This allows the module object to be accessible
   via "PyState_FindModule()".

   Only effective on modules created using single-phase
   initialization.

   Python calls "PyState_AddModule" automatically after importing a
   module that uses single-phase initialization, 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).

   If a module was attached previously using the same *def*, it is
   replaced by the new *module*.

   The caller must have an *attached thread state*.

   Retorna "-1" com uma exceção definida em caso de erro, "0" em caso
   de sucesso.

   Adicionado na versão 3.3.

int PyState_RemoveModule(PyModuleDef *def)
    * Parte da ABI Estável desde a versão 3.3.*

   Removes the module object created from *def* from the interpreter
   state. Return "-1" with an exception set on error, "0" on success.

   The caller must have an *attached thread state*.

   Adicionado na versão 3.3.
