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

  Insere val no dicionário p usando key como uma chave. key deve ser a `const char*`. O objeto chave é criado usando `PyUnicode_FromString(key)`. 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_DelItem`(PyObject *p, PyObject *key)

  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)

  Remove a entrada no dicionário p que tem uma chave especificada pela string key. Se key não estiver no dicionário, `KeyError` é levantada. Retorna `0` em caso de sucesso ou `-1` em caso de falha.

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.

  É o mesmo que `PyDict_GetItem()`, mas key é especificada como um `const char*`, em vez de um `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)

  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)

  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