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