Objetos dicionários

PyDictObject

Este subtipo do PyObject representa um objeto dicionário Python.

PyTypeObject PyDict_Type

Esta instância do PyTypeObject representa o tipo do dicionário Python. Este é o mesmo objeto dict na camada do Python.

int PyDict_Check(PyObject *p)

Retorna verdadeiro se p é um objeto dict ou uma instância de um subtipo do tipo dict.

int PyDict_CheckExact(PyObject *p)

Retorna verdadeiro se p for um objeto dict, mas não uma instância de um subtipo do tipo dict.

PyObject* PyDict_New()

Return value: New reference.

Retorna um novo dicionário vazio ou NULL em caso de falha.

PyObject* PyDictProxy_New(PyObject *mapping)

Return value: New reference.

Retorna um objeto types.MappingProxyType para um mapeamento que reforça o comportamento somente leitura. Isso normalmente é usado para criar uma visão para evitar a modificação do dicionário para tipos de classes não dinâmicas.

void PyDict_Clear(PyObject *p)

Esvazia um dicionário existente de todos os pares chave-valor.

int PyDict_Contains(PyObject *p, PyObject *key)

Determina se o dicionário p contém key. Se um item em p corresponder à key, retorna 1, caso contrário, retorna 0. Em caso de erro, retorna -1. Isso é equivalente à expressão Python key in p.

PyObject* PyDict_Copy(PyObject *p)

Return value: New reference.

Retorna um novo dicionário que contém o mesmo chave-valor como p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

Insere val no dicionário p com a tecla key. key deve ser hasheável; se não for, TypeError será levantada. Retorna 0 em caso de sucesso ou -1 em caso de falha. Esta função não rouba uma referência a val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

Insert val into the dictionary p using key as a key. key should be a const char*. The key object is created using PyUnicode_FromString(key). Return 0 on success or -1 on failure. This function does not steal a reference to val.

int PyDict_DelItem(PyObject *p, PyObject *key)

Remove the entry in dictionary p with key key. key must be hashable; if it isn’t, TypeError is raised. If key is not in the dictionary, KeyError is raised. Return 0 on success or -1 on failure.

int PyDict_DelItemString(PyObject *p, const char *key)

Remove the entry in dictionary p which has a key specified by the string key. If key is not in the dictionary, KeyError is raised. Return 0 on success or -1 on failure.

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

Return value: Borrowed reference.

Retorna o objeto do dicionário p que possui uma chave key. Retorna NULL se a chave key não estiver presente, mas sem definir uma exceção.

Observe que as exceções que ocorrem ao chamar os métodos __hash__() e __eq__() serão suprimidas. Para obter o relatório de erros, use PyDict_GetItemWithError().

PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)

Return value: Borrowed reference.

Variante de PyDict_GetItem() que não suprime exceções. Retorna NULL com uma exceção definida se uma exceção ocorreu. Retorna NULL ** sem ** uma exceção definida se a chave não estiver presente.

PyObject* PyDict_GetItemString(PyObject *p, const char *key)

Return value: Borrowed reference.

This is the same as PyDict_GetItem(), but key is specified as a const char*, rather than a PyObject*.

Observe que as exceções que ocorrem ao chamar os métodos __hash__() e __eq__() e criar um objeto string temporário serão suprimidas. Para obter o relatório de erros, use PyDict_GetItemWithError().

PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Return value: Borrowed reference.

Isso é o mesmo que o dict.setdefault() de nível Python. Se presente, ele retorna o valor correspondente a key do dicionário p. Se a chave não estiver no dict, ela será inserida com o valor defaultobj e defaultobj será retornado. Esta função avalia a função hash de key apenas uma vez, em vez de avaliá-la independentemente para a pesquisa e a inserção.

Novo na versão 3.4.

PyObject* PyDict_Items(PyObject *p)

Return value: New reference.

Retorna um PyListObject contendo todos os itens do dicionário.

PyObject* PyDict_Keys(PyObject *p)

Return value: New reference.

Retorna um PyListObject contendo todas as chaves do dicionário.

PyObject* PyDict_Values(PyObject *p)

Return value: New reference.

Retorna um PyListObject contendo todos os valores do dicionário p.

Py_ssize_t PyDict_Size(PyObject *p)

Retorna o número de itens no dicionário. Isso é equivalente a len(p) em um dicionário.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

Iterate over all key-value pairs in the dictionary p. The Py_ssize_t referred to by ppos must be initialized to 0 prior to the first call to this function to start the iteration; the function returns true for each pair in the dictionary, and false once all pairs have been reported. The parameters pkey and pvalue should either point to PyObject* variables that will be filled in with each key and value, respectively, or may be NULL. Any references returned through them are borrowed. ppos should not be altered during iteration. Its value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive.

Por exemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

O dicionário p não deve sofrer mutação durante a iteração. É seguro modificar os valores das chaves à medida que você itera no dicionário, mas apenas enquanto o conjunto de chaves não mudar. Por exemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)

Itera sobre o objeto de mapeamento b adicionando pares de valores-chave ao dicionário a. b pode ser um dicionário, ou qualquer objeto que suporte PyMapping_Keys() e PyObject_GetItem(). Se override for verdadeiro, os pares existentes em a serão substituídos se uma chave correspondente for encontrada em b, caso contrário, os pares serão adicionados apenas se não houver uma chave correspondente em a. Retorna 0 em caso de sucesso ou `` -1`` se uma exceção foi levantada.

int PyDict_Update(PyObject *a, PyObject *b)

É o mesmo que PyDict_Merge(a, b, 1) em C, e é semelhante a a.update(b) em Python, exceto que PyDict_Update() não cai na iteração em uma sequência de pares de valores de chave se o segundo argumento não tiver o atributo “keys”. Retorna 0 em caso de sucesso ou -1 se uma exceção foi levantada.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

Atualiza ou mescla no dicionário a, a partir dos pares de chave-valor em seq2. seq2 deve ser um objeto iterável produzindo objetos iteráveis de comprimento 2, vistos como pares chave-valor. No caso de chaves duplicadas, a última vence se override for verdadeiro, caso contrário, a primeira vence. Retorne 0 em caso de sucesso ou -1 se uma exceção foi levantada. Python equivalente (exceto para o valor de retorno):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

int PyDict_ClearFreeList()

Limpe a lista livre. Retorna o número total de itens liberados.

Novo na versão 3.3.