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

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

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
  Retorna valor: Referência emprestada. Parte da ABI Estável.

  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.

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

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.

  Novo na versão 3.4.

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)) {
          /* 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)
  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