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

  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)

  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.

  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.

  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)

  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.

  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.

  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.

  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.

  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.

  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)

  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.

  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)

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

int PyStructSequence_InitType2( PyTypeObject *type, PyStructSequence_Desc *desc)

  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.

  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.

  Retorna o objeto na posição pos na sequência de estrutura apontada por 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.

  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.

  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)

  Apelido para `PyStructSequence_SetItem()`.

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