Objeto tupla
************

PyTupleObject

   Este subtipo de "PyObject" representa um objeto tupla em Python.

PyTypeObject PyTuple_Type

   Esta instância de "PyTypeObject" representa o tipo tupla de Python;
   é o mesmo objeto que "tuple" na camada Python.

int PyTuple_Check(PyObject *p)

   Retorna verdadeiro se *p* é um objeto tupla ou uma instância de um
   subtipo do tipo tupla. Esta função sempre tem sucesso.

int PyTuple_CheckExact(PyObject *p)

   Retorna verdadeiro se *p* é um objeto tupla, mas não uma instância
   de um subtipo do tipo tupla. Esta função sempre tem sucesso.

PyObject* PyTuple_New(Py_ssize_t len)
    *Return value: New reference.*

   Retorna um novo objeto tupla de tamanho *len*, ou "NULL" em caso de
   falha.

PyObject* PyTuple_Pack(Py_ssize_t n, ...)
    *Return value: New reference.*

   Retorna um novo objeto tupla de tamanho *n*, ou "NULL" em caso de
   falha. Os valores da tupla são inicializados para os *n* argumentos
   C subsequentes apontando para objetos Python. "`PyTuple_Pack(2, a,
   b)" é equivalente a "Py_BuildValue("(OO)", a, b)".

Py_ssize_t PyTuple_Size(PyObject *p)

   Pega um ponteiro para um objeto tupla e retorna o tamanho dessa
   tupla.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

   Retorna o tamanho da tupla *p*, que deve ser diferente de "NULL" e
   apontar para uma tupla; nenhuma verificação de erro é executada.

PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
    *Return value: Borrowed reference.*

   Retorna o objeto na posição *pos* na tupla apontada por *p*. Se
   *pos* estiver fora dos limites, retorna "NULL" e define uma exceção
   "IndexError".

PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *Return value: Borrowed reference.*

   Como "PyTuple_GetItem()", mas faz nenhuma verificação de seus
   argumentos.

PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
    *Return value: New reference.*

   Retorna a fatia da tupla apontada por *p* entre *low* (baixo) e
   *high* (alto), ou "NULL" em caso de falha. Este é o equivalente da
   expressão Python "p[low:high]". A indexação do final da lista não é
   suportada.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

   Insere uma referência ao objeto *o* na posição *pos* da tupla
   apontada por *p*. Retorna "0" em caso de sucesso. Se *pos* estiver
   fora dos limites, retorne "-1" e define uma exceção "IndexError".

   Nota:

     Esta função "rouba" uma referência a *o* e descarta uma
     referência a um item já na tupla na posição afetada.

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

   Como "PyTuple_SetItem()", mas não verifica erros e deve *apenas*
   ser usado para preencher novas tuplas.

   Nota:

     Esta macro "rouba" uma referência para *o* e, ao contrário de
     "PyTuple_SetItem()", *não* descarta uma referência para nenhum
     item que esteja sendo substituído; qualquer referência na tupla
     na posição *pos* será perdida.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

   Pode ser usado para redimensionar uma tupla. *newsize* será o novo
   comprimento da tupla. Como as tuplas são *supostamente* imutáveis,
   isso só deve ser usado se houver apenas uma referência ao objeto.
   *Não* use isto se a tupla já for conhecida por alguma outra parte
   do código. A tupla sempre aumentará ou diminuirá no final. Pense
   nisso como destruir a tupla antiga e criar uma nova, mas com mais
   eficiência. Retorna "0" em caso de sucesso. O código do cliente
   nunca deve presumir que o valor resultante de "*p" será o mesmo de
   antes de chamar esta função. Se o objeto referenciado por "*p" for
   substituído, o "*p" original será destruído. Em caso de falha,
   retorna "-1" e define "*p" para "NULL", e levanta "MemoryError" ou
   "SystemError".


Objetos sequência de estrutura
******************************

Objetos sequência de estrutura são o equivalente em C dos objetos
"namedtuple()", ou seja, uma sequência cujos itens também podem ser
acessados por meio de atributos. Para criar uma sequência de
estrutura, você primeiro precisa criar um tipo de sequência de
estrutura específico.

PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
    *Return value: New reference.*

   Cria um novo tipo de sequência de estrutura a partir dos dados em
   *desc*, descrito abaixo. Instâncias do tipo resultante podem ser
   criadas com "PyStructSequence_New()".

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

   Inicializa um tipo de sequência de estrutura *type* de *desc* no
   lugar.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

   O mesmo que "PyStructSequence_InitType", mas retorna "0" em caso de
   sucesso e "-1" em caso de falha.

   Novo na versão 3.4.

PyStructSequence_Desc

   Contém as metainformações de um tipo de sequência de estrutura a
   ser criado.

   +---------------------+--------------------------------+----------------------------------------+
   | Campo               | Tipo em C                      | Significado                            |
   |=====================|================================|========================================|
   | "name"              | "const char *"                 | nome do tipo sequência de estrutura    |
   +---------------------+--------------------------------+----------------------------------------+
   | "doc"               | "const char *"                 | ponteiro para docstring para o tipo ou |
   |                     |                                | "NULL" para omitir                     |
   +---------------------+--------------------------------+----------------------------------------+
   | "fields"            | "PyStructSequence_Field *"     | ponteiro para um vetor terminado em    |
   |                     |                                | "NULL" com nomes de campos do novo     |
   |                     |                                | tipo                                   |
   +---------------------+--------------------------------+----------------------------------------+
   | "n_in_sequence"     | "int"                          | número de campos visíveis para o lado  |
   |                     |                                | Python (se usado como tupla)           |
   +---------------------+--------------------------------+----------------------------------------+

PyStructSequence_Field

   Descreve um campo de uma sequência de estrutura. Como uma sequência
   de estrutura é modelada como uma tupla, todos os campos são
   digitados como "PyObject *". O índice no vetor "fields" do
   "PyStructSequence_Desc" determina qual campo da sequência de
   estrutura é descrito.

   +-------------+--------------------+-------------------------------------------+
   | Campo       | Tipo em C          | Significado                               |
   |=============|====================|===========================================|
   | "name"      | "const char *"     | nome do campo ou "NULL" para terminar a   |
   |             |                    | lista de campos nomeados; definida para   |
   |             |                    | "PyStructSequence_UnnamedField" para      |
   |             |                    | deixar sem nome                           |
   +-------------+--------------------+-------------------------------------------+
   | "doc"       | "const char *"     | campo docstring ou "NULL" para omitir     |
   +-------------+--------------------+-------------------------------------------+

const char * const PyStructSequence_UnnamedField

   Valor especial para um nome de campo para deixá-lo sem nome.

   Alterado na versão 3.9: O tipo foi alterado de "char *".

PyObject* PyStructSequence_New(PyTypeObject *type)
    *Return value: New reference.*

   Cria um instância de *type*, que deve ser criada com
   "PyStructSequence_NewType()".

PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
    *Return value: Borrowed reference.*

   Retorna o objeto na posição *pos* na sequência de estrutura
   apontada por *p*. Nenhuma verificação de limites é executada.

PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *Return value: Borrowed reference.*

   Macro equivalente de "PyStructSequence_GetItem()".

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

   Define o campo no índice *pos* da sequência de estrutura *p* para o
   valor *o*. Como "PyTuple_SET_ITEM()", isto só deve ser usado para
   preencher novas instâncias.

   Nota:

     Esta função "rouba" uma referência a *o*.

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

   Macro equivalente de "PyStructSequence_SetItem()".

   Nota:

     Esta função "rouba" uma referência a *o*.
