Objetos dicionários¶
-
PyTypeObject PyDict_Type¶
- Parte da ABI Estável.
Esta instância do
PyTypeObjectrepresenta o tipo do dicionário Python. Este é o mesmo objetodictna 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
NULLem caso de falha.
-
PyObject *PyDictProxy_New(PyObject *mapping)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um objeto
types.MappingProxyTypepara 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, retorna0. Em caso de erro, retorna-1. Isso é equivalente à expressão Pythonkey 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,
TypeErrorserá levantada. Retorna0em caso de sucesso ou-1em 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. Retorna0em caso de sucesso ou-1em 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
NULLe retorna0.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
NULLse 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çãoPyDict_GetItemWithError().Alterado na versão 3.10: Chamar esta API sem um estado de thread anexado 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. RetornaNULLcom uma exceção definida se uma exceção ocorreu. RetornaNULL** 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 classestrsão ignoradas silenciosamente. Ao invés disso, prefira usar a funçãoPyDict_GetItemWithError()com sua própria key dePyUnicode_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. Retorna1se a chave estava presente e default_value não foi inserido, ou0se a chave não estava presente e default_value foi inserido. Em caso de falha, retorna-1, define uma exceção e define*resultcomoNULL.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
KeyErrorse a chave estiver ausente.Se a chave estiver presente, define *result como uma nova referência para o valor se result não for
NULLe retorna1.Se a chave estiver ausente, define *result como
NULLse result não forNULLe retorna0.Em caso de erro, levanta uma exceção e retorna
-1.
Similar a
dict.pop(), mas sem o valor padrão e sem levantarKeyErrorse 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
PyListObjectcontendo todos os itens do dicionário.
-
PyObject *PyDict_Keys(PyObject *p)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um
PyListObjectcontendo todas as chaves do dicionário.
-
PyObject *PyDict_Values(PyObject *p)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um
PyListObjectcontendo 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_treferido por ppos deve ser inicializado para0antes 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 serNULL. 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_SECTIONpara 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();
Nota
On the free-threaded build, this function can be used safely inside a critical section. However, the references returned for pkey and pvalue are borrowed and are only valid while the critical section is held. If you need to use these objects outside the critical section or when the critical section can be suspended, create a strong reference (for example, using
Py_NewRef()).
-
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()ePyObject_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. Retorna0em caso de sucesso ou-1se 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 aa.update(b)em Python, exceto quePyDict_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”. Retorna0em caso de sucesso ou-1se 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
0em caso de sucesso ou-1se 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-1e 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(). Retorna0em caso de sucesso,-1em 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. Retorna0em caso de sucesso ou-1em 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. Retorna0em caso de sucesso ou-1em 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_CLEAREDouPyDict_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_CLEAREDouPyDict_EVENT_DEALLOCATED, tanto key quanto new_value serãoNULL. Se event forPyDict_EVENT_ADDEDouPyDict_EVENT_MODIFIED, new_value será o novo valor de key. Se event forPyDict_EVENT_DELETED, key estará sendo excluída do dicionário e new_value seráNULL.PyDict_EVENT_CLONEDocorre quando dict estava anteriormente vazio e outro dict é mesclado a ele. Para manter a eficiência dessa operação, os eventosPyDict_EVENT_ADDEDpor chave não são emitidos nesse caso; em vez disso, um únicoPyDict_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 usandoPyErr_WriteUnraisable(). Caso contrário, deverá retornar0.É 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
0com 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.