Objetos dicionários¶

type PyDictObject¶: Este subtipo do PyObject representa um objeto dicionário Python.

PyTypeObject PyDict_Type¶: Parte da ABI Estável.
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 dicionário ou uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.

int PyDict_CheckExact(PyObject *p)¶: Retorna verdadeiro se p é um objeto dicionário, mas não uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.

PyObject *PyDict_New()¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo dicionário vazio ou NULL em caso de falha.

PyObject *PyDictProxy_New(PyObject *mapping)¶: Retorna valor: Nova referência. Parte da ABI Estável.
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)¶: Parte da ABI Estável.
Esvazia um dicionário existente de todos os pares chave-valor.

int PyDict_Contains(PyObject *p, PyObject *key)¶: Parte da ABI Estável.
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.

int PyDict_ContainsString(PyObject *p, const char *key)¶: É o mesmo que PyDict_Contains(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_Copy(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo dicionário que contém o mesmo chave-valor como p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: Parte da ABI Estável.
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)¶: Parte da ABI Estável.
É o mesmo que PyDict_SetItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)¶: Parte da ABI Estável.
Remove a entrada no dicionário p com a chave key. key deve ser hasheável; se não for, TypeError é levantada. Se key não estiver no dicionário, KeyError é levantada. Retorna 0 em caso de sucesso ou -1 em caso de falha.

int PyDict_DelItemString(PyObject *p, const char *key)¶: Parte da ABI Estável.
É o mesmo que PyDict_DelItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

Parte da ABI Estável desde a versão 3.13.

Retorna uma nova referência forte para o objeto dicionário p que possui uma chave key:

Se a chave estiver presente, define *result como uma nova referência forte para o valor e retorna 1.
Se a chave estiver ausente, define *result como NULL e retorna 0.
Em caso de erro, levanta uma exceção e retorna -1.

Adicionado na versão 3.13.

Veja também a função PyObject_GetItem().

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
Retorna um referência emprestada para 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.

Nota

Exceções que ocorrem ao chamar os métodos __hash__() e __eq__() são ignoradas silenciosamente. Ao invés disso, use a função PyDict_GetItemWithError().

Alterado na versão 3.10: Chamar esta API sem GIL retida era permitido por motivos históricos. Não é mais permitido.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
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)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
É o mesmo que PyDict_GetItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Nota

Exceções que ocorrem ao chamar os métodos __hash__() e __eq__() ou ao criar objetos temporários da classe str são ignoradas silenciosamente. Ao invés disso, prefira usar a função PyDict_GetItemWithError() com sua própria key de PyUnicode_FromString().

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶: Parte da ABI Estável desde a versão 3.13.
Similar a PyDict_GetItemRef(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶: Retorna valor: Referência emprestada.
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.

Adicionado na versão 3.4.

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

Insere default_value no dicionário p com uma chave key se a chave ainda não estiver presente no dicionário. Se result não for NULL, então *result é definido como uma referência forte para default_value, se a chave não estiver presente, ou para o valor existente, se key já estava presente no dicionário. Retorna 1 se a chave estava presente e default_value não foi inserido, ou 0 se a chave não estava presente e default_value foi inserido. Em caso de falha, retorna -1, define uma exceção e define *result como NULL.

Para maior clareza: se você tiver uma referência forte para default_value antes de chamar esta função, então depois que ela retornar, você terá uma referência forte para default_value e *result (se não for NULL). Estes podem referir-se ao mesmo objeto: nesse caso você mantém duas referências separadas para ele.

Adicionado na versão 3.13.

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

Remove key do dicionário p e, opcionalmente, retorna o valor removido. Não levanta KeyError se a chave estiver ausente.

Se a chave estiver presente, define *result como uma nova referência para o valor se result não for NULL e retorna 1.
Se a chave estiver ausente, define *result como NULL se result não for NULL e retorna 0.
Em caso de erro, levanta uma exceção e retorna -1.

Isto é semelhante a dict.pop(), mas sem o valor padrão e sem levantar KeyError se a chave estiver ausente.

Adicionado na versão 3.13.

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)¶: Similar a PyDict_Pop(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_Items(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todos os itens do dicionário.

PyObject *PyDict_Keys(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todas as chaves do dicionário.

PyObject *PyDict_Values(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todos os valores do dicionário p.

Py_ssize_t PyDict_Size(PyObject *p)¶: Parte da ABI Estável.
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)¶

Parte da ABI Estável.

Itera todos os pares de valores-chave no dicionário p. O Py_ssize_t referido por ppos deve ser inicializado para 0 antes da primeira chamada para esta função para iniciar a iteração; a função retorna true para cada par no dicionário e false quando todos os pares forem relatados. Os parâmetros pkey e pvalue devem apontar para variáveis de PyObject* que serão preenchidas com cada chave e valor, respectivamente, ou podem ser NULL. Todas as referências retornadas por meio deles são emprestadas. ppos não deve ser alterado durante a iteração. Seu valor representa deslocamentos dentro da estrutura do dicionário interno e, como a estrutura é esparsa, os deslocamentos não são consecutivos.

Por exemplo:

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

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* fazer algo de interessante com os valores... */
    ...
}

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);
}

A função não é segura para thread na construção com threads livres sem sincronização externa. Você pode usar Py_BEGIN_CRITICAL_SECTION para travar o dicionário enquanto itera sobre ele:

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶: Parte da ABI Estável.
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)¶: Parte da ABI Estável.
É 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)¶

Parte da ABI Estável.

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_AddWatcher(PyDict_WatchCallback callback)¶: Registra callback como um observador de dicionário. Retorna um ID inteiro não negativo que deve ser passado para futuras chamadas a PyDict_Watch(). Em caso de erro (por exemplo, não há mais IDs de observador disponíveis), retorna -1 e define uma exceção.

Adicionado na versão 3.12.

int PyDict_ClearWatcher(int watcher_id)¶: Limpa o observador identificado por watcher_id retornado anteriormente de PyDict_AddWatcher(). Retorna 0 em caso de sucesso, -1 em caso de erro (por exemplo, se o watcher_id fornecido nunca foi registrado).

Adicionado na versão 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)¶: Marca o dicionário dict como observado. A função de retorno concedida a watcher_id por PyDict_AddWatcher() será chamada quando dict for modificado ou desalocado. Retorna 0 em caso de sucesso ou -1 em caso de erro.

Adicionado na versão 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶: Marca o dicionário dict como não mais observado. A função de retorno concedida a watcher_id por PyDict_AddWatcher() será chamada quando dict for modificado ou desalocado. O dicionário deve ter sido observado anteriormente por este observador. Retorna 0 em caso de sucesso ou -1 em caso de erro.

Adicionado na versão 3.12.

type PyDict_WatchEvent¶: Enumeração de possíveis eventos de observador de dicionário: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED ou PyDict_EVENT_DEALLOCATED.

Adicionado na versão 3.12.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)¶

Tipo de uma função de retorno de chamada de observador de dicionário.

Se event for PyDict_EVENT_CLEARED ou PyDict_EVENT_DEALLOCATED, tanto key quanto new_value serão NULL. Se event for PyDict_EVENT_ADDED ou PyDict_EVENT_MODIFIED, new_value será o novo valor de key. Se event for PyDict_EVENT_DELETED, key estará sendo excluída do dicionário e new_value será NULL.

PyDict_EVENT_CLONED ocorre quando dict estava anteriormente vazio e outro dict é mesclado a ele. Para manter a eficiência dessa operação, os eventos PyDict_EVENT_ADDED por chave não são emitidos nesse caso; em vez disso, um único PyDict_EVENT_CLONED é emitido e key será o dicionário de origem.

A função de retorno pode inspecionar, mas não deve modificar o dict; isso pode ter efeitos imprevisíveis, inclusive recursão infinita. Não acione a execução do código Python na função de retorno, pois isso poderia modificar o dict como um efeito colateral.

Se event for PyDict_EVENT_DEALLOCATED, a obtenção de uma nova referência na função de retorno para o dicionário prestes a ser destruído o ressuscitará e impedirá que ele seja liberado nesse momento. Quando o objeto ressuscitado for destruído mais tarde, quaisquer funções de retorno do observador ativos naquele momento serão chamados novamente.

As funções de retorno ocorrem antes que a modificação notificada no dict ocorra, de modo que o estado anterior do dict possa ser inspecionado.

Se a função de retorno definir uma exceção, ela deverá retornar -1; essa exceção será impressa como uma exceção não reprovável usando PyErr_WriteUnraisable(). Caso contrário, deverá retornar 0.

É possível que já exista uma exceção pendente definida na entrada da função de retorno. Nesse caso, a função de retorno deve retornar 0 com a mesma exceção ainda definida. Isso significa que a função de retorno não pode chamar nenhuma outra API que possa definir uma exceção, a menos que salve e limpe o estado da exceção primeiro e o restaure antes de retornar.

Adicionado na versão 3.12.

Objetos dicionários¶

Tópico anterior

Próximo tópico

Esta página