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

type PyTupleObject

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

PyTypeObject PyTuple_Type
    * Parte da ABI Estável.*

   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)
    *Retorna valor: Nova referência.** Parte da ABI Estável.** Thread
   safety: Atomic.*

   Retorna um novo objeto tupla de tamanho *len*, ou "NULL" com uma
   exceção definida em caso de falha.

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)
    * Thread safety: Atomic.*

   Create a tuple of *size* items and copy references from *array* to
   the new tuple.

   *array* can be NULL if *size* is "0".

   On success, return a new reference. On error, set an exception and
   return "NULL".

   Adicionado na versão 3.15.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)
    *Retorna valor: Nova referência.** Parte da ABI Estável.** Thread
   safety: Atomic.*

   Retorna um novo objeto tupla de tamanho *n*, ou "NULL" com uma
   exceção 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)
    * Parte da ABI Estável.** Thread safety: Atomic.*

   Pega um ponteiro para um objeto tupla e retorna o tamanho dessa
   tupla. No erro, retorna "-1" com uma exceção definida.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
    * Thread safety: Atomic.*

   Como "PyTuple_Size()", mas sem verificação de erro.

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
    *Retorna valor: Referência emprestada.** Parte da ABI Estável.**
   Thread safety: Safe to call from multiple threads with external
   synchronization only.*

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

   A referência retornada é emprestada da tupla *p* (ou seja: ela só é
   válida enquanto você mantém uma referência a *p*). Para obter uma
   *referência forte*, use "Py_NewRef(PyTuple_GetItem(...))" ou
   "PySequence_GetItem()".

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *Retorna valor: Referência emprestada.** Thread safety: Safe to
   call from multiple threads with external synchronization only.*

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

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
    *Retorna valor: Nova referência.** Parte da ABI Estável.** Thread
   safety: Atomic.*

   Retorna a fatia da tupla apontada por *p* entre *low* e *high*, ou
   "NULL" com uma exceção definida em caso de falha.

   Isso é o equivalente da expressão Python "p[low:high]". A indexação
   do final da tupla não é suportada.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
    * Parte da ABI Estável.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   Insert a reference to object *o* at position *pos* of the tuple
   pointed to by *p*.  Return "0" on success.  If *pos* is out of
   bounds, return "-1" and set an "IndexError" exception. This
   function should only be used to fill in brand new tuples; using it
   on an existing tuple is thread-unsafe.

   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)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   Like "PyTuple_SetItem()", but does no error checking, and should
   *only* be used to fill in brand new tuples, using it on an existing
   tuple is thread-unsafe.

   A verificação de limites é realizada como uma asserção se o Python
   for construído em modo de depuração ou "com asserções".

   Nota:

     Esta função "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.

   Aviso:

     Esta macro deve ser usada *somente* em tuplas recém-criadas. Usar
     esta macro em uma tupla que já está em uso (ou, em outras
     palavras, com uma contagem de referências > 1) pode levar a um
     comportamento indefinido.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   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
******************************

A struct sequence object is a *named tuple*, that is, a sequence whose
items can also be accessed through attributes. It is similar to
"collections.namedtuple()", but provides a slightly different
interface.

To create a struct sequence, you first have to create a specific
struct sequence type.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)
    *Retorna valor: Nova referência.** Parte da ABI Estável.** Thread
   safety: Atomic.*

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

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

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
    * Thread safety: Safe to call without external synchronization on
   distinct objects.*

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

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
    * Thread safety: Safe to call without external synchronization on
   distinct objects.*

   Como "PyStructSequence_InitType()", mas retorna "0" em caso de
   sucesso e "-1" com uma exceção definida em caso de falha.

   Adicionado na versão 3.4.

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

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

   const char *name

      Nome totalmente qualificado do tipo; codificado em UTF-8
      terminado em nulo. O nome deve conter o nome do módulo.

   const char *doc

      Ponteiro para docstring para o tipo ou "NULL" para omitir

   PyStructSequence_Field *fields

      Ponteiro para um vetor terminado em "NULL" com nomes de campos
      do novo tipo

   int n_in_sequence

      Número de campos visíveis para o lado Python (se usado como
      tupla)

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

   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.

   const char *name

      Nome do campo ou "NULL" para terminar a lista de campos
      nomeados; definida para "PyStructSequence_UnnamedField" para
      deixar sem nome.

   const char *doc

      Campo docstring ou "NULL" para omitir.

const char *const PyStructSequence_UnnamedField
    * Parte da ABI Estável desde a versão 3.11.*

   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)
    *Retorna valor: Nova referência.** Parte da ABI Estável.** Thread
   safety: Atomic.*

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

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

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
    *Retorna valor: Referência emprestada.** Parte da ABI Estável.**
   Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   Return the object at position *pos* in the struct sequence pointed
   to by *p*. The returned reference is borrowed from the struct
   sequence *p* (that is: it is only valid as long as you hold a
   reference to *p*).

   A verificação de limites é realizada como uma asserção se o Python
   for construído em modo de depuração ou "com asserções".

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *Retorna valor: Referência emprestada.** Thread safety: Safe to
   call from multiple threads with external synchronization only.*

   Apelido para "PyStructSequence_GetItem()".

   Alterado na versão 3.13: Agora implementada como um apelido para
   "PyStructSequence_GetItem()".

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
    * Parte da ABI Estável.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   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.

   A verificação de limites é realizada como uma asserção se o Python
   for construído em modo de depuração ou "com asserções".

   Nota:

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

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   Apelido para "PyStructSequence_SetItem()".

   Alterado na versão 3.13: Agora implementada como um apelido para
   "PyStructSequence_SetItem()".
