Introdução
**********

A Interface de Programação de Aplicações (API) para Python fornece aos
programadores C e C++ acesso ao interpretador Python em uma variedade
de níveis. A API pode ser usada igualmente em C++, mas, para abreviar,
geralmente é chamada de API Python/C. Existem dois motivos
fundamentalmente diferentes para usar a API Python/C. A primeira razão
é escrever *módulos de extensão* para propósitos específicos; esses
são módulos C que estendem o interpretador Python. Este é
provavelmente o uso mais comum. O segundo motivo é usar Python como um
componente em uma aplicação maior; esta técnica é geralmente referida
como *incorporação* Python em uma aplicação.

Escrever um módulo de extensão é um processo relativamente bem
compreendido, no qual uma abordagem de "livro de receitas" funciona
bem. Existem várias ferramentas que automatizam o processo até certo
ponto. Embora as pessoas tenham incorporado o Python em outras
aplicações desde sua existência inicial, o processo de incorporação do
Python é menos direto do que escrever uma extensão.

Muitas funções da API são úteis independentemente de você estar
incorporando ou estendendo o Python; além disso, a maioria das
aplicações que incorporam Python também precisará fornecer uma
extensão customizada, portanto, é provavelmente uma boa ideia se
familiarizar com a escrita de uma extensão antes de tentar incorporar
Python em uma aplicação real.


Padrões de codificação
======================

Se você estiver escrevendo código C para inclusão no CPython, **deve**
seguir as diretrizes e padrões definidos na **PEP 7**. Essas
diretrizes se aplicam independentemente da versão do Python com a qual
você está contribuindo. Seguir essas convenções não é necessário para
seus próprios módulos de extensão de terceiros, a menos que você
eventualmente espere contribuí-los para o Python.


Arquivos de inclusão
====================

Todas as definições de função, tipo e macro necessárias para usar a
API Python/C estão incluídas em seu código pela seguinte linha:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

Isso implica a inclusão dos seguintes cabeçalhos padrão: "<stdio.h>",
"<string.h>", "<errno.h>", "<limits.h>", "<assert.h>" e "<stdlib.h>"
(se disponível).

Nota:

  Uma vez que Python pode definir algumas definições de
  pré-processador que afetam os cabeçalhos padrão em alguns sistemas,
  você *deve* incluir "Python.h" antes de quaisquer cabeçalhos padrão
  serem incluídos.É recomendável sempre definir "PY_SSIZE_T_CLEAN"
  antes de incluir "Python.h". Veja Análise de argumentos e construção
  de valores para uma descrição desta macro.

Todos os nomes visíveis ao usuário definidos por Python.h (exceto
aqueles definidos pelos cabeçalhos padrão incluídos) têm um dos
prefixos "Py" ou "_Py". Nomes começando com "_Py" são para uso interno
pela implementação Python e não devem ser usados por escritores de
extensão. Os nomes dos membros da estrutura não têm um prefixo
reservado.

Nota:

  O código do usuário nunca deve definir nomes que começam com "Py" ou
  "_Py". Isso confunde o leitor e coloca em risco a portabilidade do
  código do usuário para versões futuras do Python, que podem definir
  nomes adicionais começando com um desses prefixos.

Os arquivos de cabeçalho são normalmente instalados com Python. No
Unix, eles estão localizados nos diretórios
"*prefix*/include/pythonversion/" e
"*exec_prefix*/include/pythonversion/", onde "prefix" e "exec_prefix"
são definidos pelos parâmetros correspondentes ao script **configure**
e *version* do Python é "'%d.%d' % sys.version_info[:2]". No Windows,
os cabeçalhos são instalados em "*prefix*/include", onde "prefix" é o
diretório de instalação especificado para o instalador.

Para incluir os cabeçalhos, coloque os dois diretórios (se diferentes)
no caminho de pesquisa do compilador para as inclusões. *Não* coloque
os diretórios pais no caminho de busca e então use "#include
<pythonX.Y/Python.h>"; isto irá quebrar em compilações
multiplataforma, uma vez que os cabeçalhos independentes da plataforma
em "prefix" incluem os cabeçalhos específicos da plataforma de
"exec_prefix".

Os usuários de C++ devem notar que embora a API seja definida
inteiramente usando C, os arquivos de cabeçalho declaram
apropriadamente os pontos de entrada como "extern "C"". Como
resultado, não há necessidade de fazer nada especial para usar a API
do C++.


Macros úteis
============

Diversas macros úteis são definidas nos arquivos de cabeçalho do
Python. Muitas são definidas mais próximas de onde são úteis (por
exemplo, "Py_RETURN_NONE"). Outras de utilidade mais geral são
definidas aqui. Esta não é necessariamente uma lista completa.

PyMODINIT_FUNC

   Declara uma função de inicialização do módulo de extensão "PyInit".
   O tipo de retorno da função é PyObject*. A macro declara quaisquer
   declarações de ligação especial necessárias pela plataforma e, para
   C++, declara a função como "extern "C"".

   A função de inicialização deve ser nomeada "PyInit_*name*", onde
   *name* é o nome do módulo, e deve ser o único item não-"static"
   definido no arquivo do módulo. Exemplo:

      static struct PyModuleDef spam_module = {
          PyModuleDef_HEAD_INIT,
          .m_name = "spam",
          ...
      };

      PyMODINIT_FUNC
      PyInit_spam(void)
      {
          return PyModule_Create(&spam_module);
      }

Py_ABS(x)

   Retorna o valor absoluto de "x".

   Adicionado na versão 3.3.

Py_ALWAYS_INLINE

   Pede ao compilador para sempre embutir uma função em linha
   estática. O compilador pode ignorá-lo e decide não inserir a
   função.

   Ele pode ser usado para inserir funções em linha estáticas críticas
   de desempenho ao compilar Python no modo de depuração com função de
   inserir em linha desabilitada. Por exemplo, o MSC desabilita a
   função de inserir em linha ao compilar no modo de depuração.

   Marcar cegamente uma função em linha estática com Py_ALWAYS_INLINE
   pode resultar em desempenhos piores (devido ao aumento do tamanho
   do código, por exemplo). O compilador geralmente é mais inteligente
   que o desenvolvedor para a análise de custo/benefício.

   Se o Python tiver sido compilado em modo de depuração (se a macro
   "Py_DEBUG" estiver definida), a macro "Py_ALWAYS_INLINE" não fará
   nada.

   Deve ser especificado antes do tipo de retorno da função. Uso:

      static inline Py_ALWAYS_INLINE int random(void) { return 4; }

   Adicionado na versão 3.11.

Py_CHARMASK(c)

   O argumento deve ser um caractere ou um número inteiro no intervalo
   [-128, 127] ou [0, 255]. Esta macro retorna "c" convertido em um
   "unsigned char".

Py_DEPRECATED(version)

   Use isso para declarações descontinuadas. A macro deve ser colocada
   antes do nome do símbolo.

   Exemplo:

      Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

   Alterado na versão 3.8: Suporte a MSVC foi adicionado.

Py_GETENV(s)

   Como "getenv(s)", mas retorna "NULL" se a opção "-E" foi passada na
   linha de comando (veja "PyConfig.use_environment").

Py_MAX(x, y)

   Retorna o valor máximo entre "x" e "y".

   Adicionado na versão 3.3.

Py_MEMBER_SIZE(type, member)

   Retorna o tamanho do "member" de uma estrutura ("type") em bytes.

   Adicionado na versão 3.6.

Py_MIN(x, y)

   Retorna o valor mínimo entre "x" e "y".

   Adicionado na versão 3.3.

Py_NO_INLINE

   Desabilita a inserção em linha em uma função. Por exemplo, isso
   reduz o consumo da pilha C: útil em compilações LTO+PGO que faz uso
   intenso de inserção em linha de código (veja bpo-33720).

   Uso:

      Py_NO_INLINE static int random(void) { return 4; }

   Adicionado na versão 3.11.

Py_STRINGIFY(x)

   Converte "x" para uma string C. Por exemplo, "Py_STRINGIFY(123)"
   retorna ""123"".

   Adicionado na versão 3.4.

Py_UNREACHABLE()

   Use isso quando você tiver um caminho de código que não pode ser
   alcançado por design. Por exemplo, na cláusula "default:" em uma
   instrução "switch" para a qual todos os valores possíveis são
   incluídos nas instruções "case". Use isto em lugares onde você pode
   ficar tentado a colocar uma chamada "assert(0)" ou "abort()".

   No modo de lançamento, a macro ajuda o compilador a otimizar o
   código e evita um aviso sobre código inacessível. Por exemplo, a
   macro é implementada com "__builtin_unreachable()" no GCC em modo
   de lançamento.

   Um uso para "Py_UNREACHABLE()" é seguir uma chamada de uma função
   que nunca retorna, mas que não é declarada com "_Py_NO_RETURN".

   Se um caminho de código for um código muito improvável, mas puder
   ser alcançado em casos excepcionais, esta macro não deve ser usada.
   Por exemplo, sob condição de pouca memória ou se uma chamada de
   sistema retornar um valor fora do intervalo esperado. Nesse caso, é
   melhor relatar o erro ao chamador. Se o erro não puder ser
   reportado ao chamador, "Py_FatalError()" pode ser usada.

   Adicionado na versão 3.7.

Py_UNUSED(arg)

   Use isso para argumentos não usados em uma definição de função para
   silenciar avisos do compilador. Exemplo: "int func(int a, int
   Py_UNUSED(b)) { return a; }".

   Adicionado na versão 3.4.

PyDoc_STRVAR(name, str)

   Cria uma variável com o nome "name" que pode ser usada em
   docstrings. Se o Python for compilado sem docstrings, o valor
   estará vazio.

   Use "PyDoc_STRVAR" para docstrings para ter suporte à compilação do
   Python sem docstrings, conforme especificado em **PEP 7**.

   Exemplo:

      PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

      static PyMethodDef deque_methods[] = {
          // ...
          {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
          // ...
      }

PyDoc_STR(str)

   Cria uma docstring para a string de entrada fornecida ou uma string
   vazia se docstrings estiverem desabilitadas.

   Use "PyDoc_STR" ao especificar docstrings para ter suporte à
   compilação do Python sem docstrings, conforme especificado em **PEP
   7**.

   Exemplo:

      static PyMethodDef pysqlite_row_methods[] = {
          {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
              PyDoc_STR("Returns the keys of the row.")},
          {NULL, NULL}
      };


Objetos, tipos e contagens de referências
=========================================

A maioria das funções da API Python/C tem um ou mais argumentos, bem
como um valor de retorno do tipo PyObject*. Este tipo é um ponteiro
para um tipo de dados opaco que representa um objeto Python
arbitrário. Como todos os tipos de objeto Python são tratados da mesma
maneira pela linguagem Python na maioria das situações (por exemplo,
atribuições, regras de escopo e passagem de argumento), é adequado que
eles sejam representados por um único tipo C. Quase todos os objetos
Python vivem na pilha: você nunca declara uma variável automática ou
estática do tipo "PyObject", variáveis de apenas ponteiro do tipo
PyObject* podem ser declaradas. A única exceção são os objetos de
tipo; uma vez que estes nunca devem ser desalocados, eles são
normalmente objetos estáticos "PyTypeObject".

Todos os objetos Python (mesmo inteiros Python) têm um *tipo* e uma
*contagem de referências*. O tipo de um objeto determina que tipo de
objeto ele é (por exemplo, um número inteiro, uma lista ou uma função
definida pelo usuário; existem muitos mais, conforme explicado em A
hierarquia de tipos padrão). Para cada um dos tipos conhecidos, há uma
macro para verificar se um objeto é desse tipo; por exemplo,
"PyList_Check(a)" é verdadeiro se (e somente se) o objeto apontado por
*a* for uma lista Python.


Contagens de referências
------------------------

The reference count is important because today's computers have a
finite (and often severely limited) memory size; it counts how many
different places there are that have a *strong reference* to an
object. Such a place could be another object, or a global (or static)
C variable, or a local variable in some C function. When the last
*strong reference* to an object is released (i.e. its reference count
becomes zero), the object is deallocated. If it contains references to
other objects, those references are released. Those other objects may
be deallocated in turn, if there are no more references to them, and
so on.  (There's an obvious problem  with objects that reference each
other here; for now, the solution is "don't do that.")

Reference counts are always manipulated explicitly.  The normal way is
to use the macro "Py_INCREF()" to take a new reference to an object
(i.e. increment its reference count by one), and "Py_DECREF()" to
release that reference (i.e. decrement the reference count by one).
The "Py_DECREF()" macro is considerably more complex than the incref
one, since it must check whether the reference count becomes zero and
then cause the object's deallocator to be called.  The deallocator is
a function pointer contained in the object's type structure.  The
type-specific deallocator takes care of releasing references for other
objects contained in the object if this is a compound object type,
such as a list, as well as performing any additional finalization
that's needed.  There's no chance that the reference count can
overflow; at least as many bits are used to hold the reference count
as there are distinct memory locations in virtual memory (assuming
"sizeof(Py_ssize_t) >= sizeof(void*)"). Thus, the reference count
increment is a simple operation.

It is not necessary to hold a *strong reference* (i.e. increment the
reference count) for every local variable that contains a pointer to
an object.  In theory, the  object's reference count goes up by one
when the variable is made to  point to it and it goes down by one when
the variable goes out of  scope.  However, these two cancel each other
out, so at the end the  reference count hasn't changed.  The only real
reason to use the  reference count is to prevent the object from being
deallocated as  long as our variable is pointing to it.  If we know
that there is at  least one other reference to the object that lives
at least as long as our variable, there is no need to take a new
*strong reference* (i.e. increment the reference count) temporarily.
An important situation where this arises is in objects  that are
passed as arguments to C functions in an extension module  that are
called from Python; the call mechanism guarantees to hold a  reference
to every argument for the duration of the call.

However, a common pitfall is to extract an object from a list and hold
on to it for a while without taking a new reference.  Some other
operation might conceivably remove the object from the list, releasing
that reference, and possibly deallocating it. The real danger is that
innocent-looking operations may invoke arbitrary Python code which
could do this; there is a code path which allows control to flow back
to the user from a "Py_DECREF()", so almost any operation is
potentially dangerous.

A safe approach is to always use the generic operations (functions
whose name begins with "PyObject_", "PyNumber_", "PySequence_" or
"PyMapping_"). These operations always create a new *strong reference*
(i.e. increment the reference count) of the object they return. This
leaves the caller with the responsibility to call "Py_DECREF()" when
they are done with the result; this soon becomes second nature.


Detalhes da contagem de referências
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The reference count behavior of functions in the Python/C API is best
explained in terms of *ownership of references*.  Ownership pertains
to references, never to objects (objects are not owned: they are
always shared).  "Owning a reference" means being responsible for
calling Py_DECREF on it when the reference is no longer needed.
Ownership can also be transferred, meaning that the code that receives
ownership of the reference then becomes responsible for eventually
releasing it by calling "Py_DECREF()" or "Py_XDECREF()" when it's no
longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its
caller, the caller is said to receive a *new* reference.  When no
ownership is transferred, the caller is said to *borrow* the
reference. Nothing needs to be done for a *borrowed reference*.

Por outro lado, quando uma função de chamada passa uma referência a um
objeto, há duas possibilidades: a função *rouba* uma referência ao
objeto, ou não. *Roubar uma referência* significa que quando você
passa uma referência para uma função, essa função presume que agora
ela possui essa referência e você não é mais responsável por ela.

Poucas funções roubam referências; as duas exceções notáveis são
"PyList_SetItem()" e "PyTuple_SetItem()", que roubam uma referência
para o item (mas não para a tupla ou lista na qual o item é
colocado!). Essas funções foram projetadas para roubar uma referência
devido a um idioma comum para preencher uma tupla ou lista com objetos
recém-criados; por exemplo, o código para criar a tupla "(1, 2,
"three")" pode ser parecido com isto (esquecendo o tratamento de erros
por enquanto; uma maneira melhor de codificar isso é mostrada abaixo):

   PyObject *t;

   t = PyTuple_New(3);
   PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
   PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
   PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

Aqui, "PyLong_FromLong()" retorna uma nova referência que é
imediatamente roubada por "PyTuple_SetItem()". Quando você quiser
continuar usando um objeto, embora a referência a ele seja roubada,
use "Py_INCREF()" para obter outra referência antes de chamar a função
de roubo de referência.

A propósito, "PyTuple_SetItem()" é a *única* maneira de definir itens
de tupla; "PySequence_SetItem()" e "PyObject_SetItem()" se recusam a
fazer isso, pois tuplas são um tipo de dados imutável. Você só deve
usar "PyTuple_SetItem()" para tuplas que você mesmo está criando.

O código equivalente para preencher uma lista pode ser escrita usando
"PyList_New()" e "PyList_SetItem()".

No entanto, na prática, você raramente usará essas maneiras de criar e
preencher uma tupla ou lista. Existe uma função genérica,
"Py_BuildValue()", que pode criar objetos mais comuns a partir de
valores C, dirigidos por uma *string de formato*. Por exemplo, os dois
blocos de código acima podem ser substituídos pelos seguintes (que
também cuidam da verificação de erros):

   PyObject *tuple, *list;

   tuple = Py_BuildValue("(iis)", 1, 2, "three");
   list = Py_BuildValue("[iis]", 1, 2, "three");

It is much more common to use "PyObject_SetItem()" and friends with
items whose references you are only borrowing, like arguments that
were passed in to the function you are writing.  In that case, their
behaviour regarding references is much saner, since you don't have to
take a new reference just so you can give that reference away ("have
it be stolen").  For example, this function sets all items of a list
(actually, any mutable sequence) to a given item:

   int
   set_all(PyObject *target, PyObject *item)
   {
       Py_ssize_t i, n;

       n = PyObject_Length(target);
       if (n < 0)
           return -1;
       for (i = 0; i < n; i++) {
           PyObject *index = PyLong_FromSsize_t(i);
           if (!index)
               return -1;
           if (PyObject_SetItem(target, index, item) < 0) {
               Py_DECREF(index);
               return -1;
           }
           Py_DECREF(index);
       }
       return 0;
   }

A situação é ligeiramente diferente para os valores de retorno da
função. Embora passar uma referência para a maioria das funções não
altere suas responsabilidades de propriedade para aquela referência,
muitas funções que retornam uma referência a um objeto fornecem a
propriedade da referência. O motivo é simples: em muitos casos, o
objeto retornado é criado instantaneamente e a referência que você
obtém é a única referência ao objeto. Portanto, as funções genéricas
que retornam referências a objetos, como "PyObject_GetItem()" e
"PySequence_GetItem()", sempre retornam uma nova referência (o
chamador torna-se o dono da referência).

É importante perceber que se você possui uma referência retornada por
uma função depende de qual função você chama apenas --- *a plumagem*
(o tipo do objeto passado como um argumento para a função) *não entra
nela!* Assim, se você extrair um item de uma lista usando
"PyList_GetItem()", você não possui a referência --- mas se obtiver o
mesmo item da mesma lista usando "PySequence_GetItem()" (que leva
exatamente os mesmos argumentos), você possui uma referência ao objeto
retornado.

Aqui está um exemplo de como você poderia escrever uma função que
calcula a soma dos itens em uma lista de inteiros; uma vez usando
"PyList_GetItem()", e uma vez usando "PySequence_GetItem()".

   long
   sum_list(PyObject *list)
   {
       Py_ssize_t i, n;
       long total = 0, value;
       PyObject *item;

       n = PyList_Size(list);
       if (n < 0)
           return -1; /* Not a list */
       for (i = 0; i < n; i++) {
           item = PyList_GetItem(list, i); /* Can't fail */
           if (!PyLong_Check(item)) continue; /* Skip non-integers */
           value = PyLong_AsLong(item);
           if (value == -1 && PyErr_Occurred())
               /* Integer too big to fit in a C long, bail out */
               return -1;
           total += value;
       }
       return total;
   }

   long
   sum_sequence(PyObject *sequence)
   {
       Py_ssize_t i, n;
       long total = 0, value;
       PyObject *item;
       n = PySequence_Length(sequence);
       if (n < 0)
           return -1; /* Has no length */
       for (i = 0; i < n; i++) {
           item = PySequence_GetItem(sequence, i);
           if (item == NULL)
               return -1; /* Not a sequence, or other failure */
           if (PyLong_Check(item)) {
               value = PyLong_AsLong(item);
               Py_DECREF(item);
               if (value == -1 && PyErr_Occurred())
                   /* Integer too big to fit in a C long, bail out */
                   return -1;
               total += value;
           }
           else {
               Py_DECREF(item); /* Discard reference ownership */
           }
       }
       return total;
   }


Tipos
-----

Existem alguns outros tipos de dados que desempenham um papel
significativo na API Python/C; a maioria são tipos C simples, como
int, long, double e char*. Alguns tipos de estrutura são usados para
descrever tabelas estáticas usadas para listar as funções exportadas
por um módulo ou os atributos de dados de um novo tipo de objeto, e
outro é usado para descrever o valor de um número complexo. Eles serão
discutidos junto com as funções que os utilizam.

type Py_ssize_t
    * Parte da ABI Estável.*

   Um tipo integral assinado tal que "sizeof(Py_ssize_t) ==
   sizeof(size_t)". C99 não define tal coisa diretamente (size_t é um
   tipo integral não assinado). Veja **PEP 353** para mais detalhes.
   "PY_SSIZE_T_MAX" é o maior valor positivo do tipo "Py_ssize_t".


Exceções
========

O programador Python só precisa lidar com exceções se o tratamento de
erros específico for necessário; as exceções não tratadas são
propagadas automaticamente para o chamador, depois para o chamador e
assim por diante, até chegarem ao interpretador de nível superior,
onde são relatadas ao usuário acompanhadas por um traceback (situação
da pilha de execução).

Para programadores C, entretanto, a verificação de erros sempre deve
ser explícita. Todas as funções na API Python/C podem levantar
exceções, a menos que uma declaração explícita seja feita de outra
forma na documentação de uma função. Em geral, quando uma função
encontra um erro, ela define uma exceção, descarta todas as
referências de objeto de sua propriedade e retorna um indicador de
erro. Se não for documentado de outra forma, este indicador é "NULL"
ou "-1", dependendo do tipo de retorno da função. Algumas funções
retornam um resultado booleano verdadeiro/falso, com falso indicando
um erro. Muito poucas funções não retornam nenhum indicador de erro
explícito ou têm um valor de retorno ambíguo e requerem teste
explícito para erros com "PyErr_Occurred()". Essas exceções são sempre
documentadas explicitamente.

O estado de exceção é mantido no armazenamento por thread (isso é
equivalente a usar o armazenamento global em uma aplicação sem
thread). Uma thread pode estar em um de dois estados: ocorreu uma
exceção ou não. A função "PyErr_Occurred()" pode ser usada para
verificar isso: ela retorna uma referência emprestada ao objeto do
tipo de exceção quando uma exceção ocorreu, e "NULL" caso contrário.
Existem várias funções para definir o estado de exceção:
"PyErr_SetString()" é a função mais comum (embora não a mais geral)
para definir o estado de exceção, e "PyErr_Clear()" limpa o estado da
exceção.

O estado de exceção completo consiste em três objetos (todos os quais
podem ser "NULL"): o tipo de exceção, o valor de exceção
correspondente e o traceback. Eles têm os mesmos significados que o
resultado do Python de "sys.exc_info()"; no entanto, eles não são os
mesmos: os objetos Python representam a última exceção sendo tratada
por uma instrução Python "try" ... "except", enquanto o estado de
exceção de nível C só existe enquanto uma exceção está sendo
transmitido entre funções C até atingir o loop principal do
interpretador de bytecode Python, que se encarrega de transferi-lo
para "sys.exc_info()" e amigos.

Observe que a partir do Python 1.5, a maneira preferida e segura para
thread para acessar o estado de exceção do código Python é chamar a
função "sys.exc_info()", que retorna o estado de exceção por thread
para o código Python. Além disso, a semântica de ambas as maneiras de
acessar o estado de exceção mudou, de modo que uma função que captura
uma exceção salvará e restaurará o estado de exceção de seu segmento
de modo a preservar o estado de exceção de seu chamador. Isso evita
bugs comuns no código de tratamento de exceções causados por uma
função aparentemente inocente sobrescrevendo a exceção sendo tratada;
também reduz a extensão da vida útil frequentemente indesejada para
objetos que são referenciados pelos quadros de pilha no traceback.

Como princípio geral, uma função que chama outra função para realizar
alguma tarefa deve verificar se a função chamada levantou uma exceção
e, em caso afirmativo, passar o estado da exceção para seu chamador.
Ele deve descartar todas as referências de objeto que possui e
retornar um indicador de erro, mas *não* deve definir outra exceção
--- que sobrescreveria a exceção que acabou de ser gerada e perderia
informações importantes sobre a causa exata do erro.

A simple example of detecting exceptions and passing them on is shown
in the "sum_sequence()" example above.  It so happens that this
example doesn't need to clean up any owned references when it detects
an error.  The following example function shows some error cleanup.
First, to remind you why you like Python, we show the equivalent
Python code:

   def incr_item(dict, key):
       try:
           item = dict[key]
       except KeyError:
           item = 0
       dict[key] = item + 1

Aqui está o código C correspondente, em toda sua glória:

   int
   incr_item(PyObject *dict, PyObject *key)
   {
       /* Objects all initialized to NULL for Py_XDECREF */
       PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
       int rv = -1; /* Return value initialized to -1 (failure) */

       item = PyObject_GetItem(dict, key);
       if (item == NULL) {
           /* Handle KeyError only: */
           if (!PyErr_ExceptionMatches(PyExc_KeyError))
               goto error;

           /* Clear the error and use zero: */
           PyErr_Clear();
           item = PyLong_FromLong(0L);
           if (item == NULL)
               goto error;
       }
       const_one = PyLong_FromLong(1L);
       if (const_one == NULL)
           goto error;

       incremented_item = PyNumber_Add(item, const_one);
       if (incremented_item == NULL)
           goto error;

       if (PyObject_SetItem(dict, key, incremented_item) < 0)
           goto error;
       rv = 0; /* Success */
       /* Continue with cleanup code */

    error:
       /* Cleanup code, shared by success and failure path */

       /* Use Py_XDECREF() to ignore NULL references */
       Py_XDECREF(item);
       Py_XDECREF(const_one);
       Py_XDECREF(incremented_item);

       return rv; /* -1 for error, 0 for success */
   }

Este exemplo representa um uso endossado da instrução "goto" em C! Ele
ilustra o uso de "PyErr_ExceptionMatches()" e "PyErr_Clear()" para
lidar com exceções específicas, e o uso de "Py_XDECREF()" para
descartar referências de propriedade que podem ser "NULL" (observe o
"'X'" no nome; "Py_DECREF()" travaria quando confrontado com uma
referência "NULL"). É importante que as variáveis usadas para manter
as referências de propriedade sejam inicializadas com "NULL" para que
isso funcione; da mesma forma, o valor de retorno proposto é
inicializado para "-1" (falha) e apenas definido para sucesso após a
chamada final feita ser bem sucedida.


Incorporando Python
===================

A única tarefa importante com a qual apenas os incorporadores (em
oposição aos escritores de extensão) do interpretador Python precisam
se preocupar é a inicialização e, possivelmente, a finalização do
interpretador Python. A maior parte da funcionalidade do interpretador
só pode ser usada após a inicialização do interpretador.

A função de inicialização básica é "Py_Initialize()". Isso inicializa
a tabela de módulos carregados e cria os módulos fundamentais
"builtins", "__main__" e "sys". Ela também inicializa o caminho de
pesquisa de módulos ("sys.path").

"Py_Initialize()" não define a "lista de argumentos de script"
("sys.argv"). Se esta variável for necessária para o código Python que
será executado posteriormente, "PyConfig.argv" e "PyConfig.parse_argv"
devem estar definidas; veja Configuração de inicialização do Python.

Na maioria dos sistemas (em particular, no Unix e no Windows, embora
os detalhes sejam ligeiramente diferentes), "Py_Initialize()" calcula
o caminho de pesquisa de módulos com base em sua melhor estimativa
para a localização do executável do interpretador Python padrão,
presumindo que a biblioteca Python é encontrada em um local fixo em
relação ao executável do interpretador Python. Em particular, ele
procura por um diretório chamado "lib/python*X.Y*" relativo ao
diretório pai onde o executável chamado "python" é encontrado no
caminho de pesquisa de comandos do shell (a variável de ambiente
"PATH").

Por exemplo, se o executável Python for encontrado em
"/usr/local/bin/python", ele presumirá que as bibliotecas estão em
"/usr/local/lib/python*X.Y*". (Na verdade, este caminho particular
também é o local reserva, usado quando nenhum arquivo executável
chamado "python" é encontrado ao longo de "PATH".) O usuário pode
substituir este comportamento definindo a variável de ambiente
"PYTHONHOME", ou insira diretórios adicionais na frente do caminho
padrão definindo "PYTHONPATH".

The embedding application can steer the search by setting
"PyConfig.program_name" *before* calling "Py_InitializeFromConfig()".
Note that "PYTHONHOME" still overrides this and "PYTHONPATH" is still
inserted in front of the standard path.  An application that requires
total control has to provide its own implementation of "Py_GetPath()",
"Py_GetPrefix()", "Py_GetExecPrefix()", and "Py_GetProgramFullPath()"
(all defined in "Modules/getpath.c").

Às vezes, é desejável "desinicializar" o Python. Por exemplo, a
aplicação pode querer iniciar novamente (fazer outra chamada para
"Py_Initialize()") ou a aplicação simplesmente termina com o uso de
Python e deseja liberar memória alocada pelo Python. Isso pode ser
feito chamando "Py_FinalizeEx()". A função "Py_IsInitialized()"
retorna verdadeiro se o Python está atualmente no estado inicializado.
Mais informações sobre essas funções são fornecidas em um capítulo
posterior. Observe que "Py_FinalizeEx()" *não* libera toda a memória
alocada pelo interpretador Python, por exemplo, a memória alocada por
módulos de extensão atualmente não pode ser liberada.


Compilações de depuração
========================

Python pode ser compilado com várias macros para permitir verificações
extras do interpretador e módulos de extensão. Essas verificações
tendem a adicionar uma grande quantidade de sobrecarga ao tempo de
execução, portanto, não são habilitadas por padrão.

Uma lista completa dos vários tipos de compilações de depuração está
no arquivo "Misc/SpecialBuilds.txt" na distribuição do código-fonte do
Python. Estão disponíveis compilações que oferecem suporte ao
rastreamento de contagens de referências, depuração do alocador de
memória ou criação de perfil de baixo nível do laço do interpretador
principal. Apenas as compilações usadas com mais frequência serão
descritas no restante desta seção.

Py_DEBUG

Compiling the interpreter with the "Py_DEBUG" macro defined produces
what is generally meant by a debug build of Python. "Py_DEBUG" is
enabled in the Unix build by adding "--with-pydebug" to the
"./configure" command. It is also implied by the presence of the not-
Python-specific "_DEBUG" macro.  When "Py_DEBUG" is enabled in the
Unix build, compiler optimization is disabled.

Além da depuração de contagem de referências descrita abaixo,
verificações extras são realizadas, consulte Compilação de Depuração
do Python.

Definir "Py_TRACE_REFS" habilita o rastreamento de referência (veja a
opção "opção --with-trace-refs de configure"). Quando definida, uma
lista circular duplamente vinculada de objetos ativos é mantida
adicionando dois campos extras a cada "PyObject". As alocações totais
também são rastreadas. Ao sair, todas as referências existentes são
impressas. (No modo interativo, isso acontece após cada instrução
executada pelo interpretador.)

Consulte "Misc/SpecialBuilds.txt" na distribuição do código-fonte
Python para informações mais detalhadas.
