# `collections` — Tipos de dados do contêiner

Código-fonte: Lib/collections/__init__.py

Este módulo implementa tipos de dados de contêiner especializados que fornecem alternativas aos contêineres embutidos do Python, `dict`, `list`, `set` e `tuple`.

`namedtuple()` | função fábrica (factory function) para criar subclasses de tuplas com campos nomeados
`deque` | contêiner lista ou similar com acréscimos e retiradas rápidas nas duas extremidades
`ChainMap` | classe dict ou similar para criar uma visão única de vários mapeamentos
`Counter` | subclasse de dict para contar objetos hasheáveis
`OrderedDict` | subclasse de dict que lembra a ordem que as entradas foram adicionadas
`defaultdict` | subclasse de dict que chama uma função fábrica para fornecer valores não encontrados
`UserDict` | envoltório em torno de objetos dicionário para facilitar fazer subclasse de dict
`UserList` | envoltório em torno de objetos lista para facilitar criação de subclasse de lista
`UserString` | envoltório em torno de objetos string para uma facilitar criação de subclasse de string

Deprecated since version 3.3, will be removed in version 3.10: Movido Classes Base Abstratas de Coleções para o módulo `collections.abc`. Para compatibilidade com versões anteriores, eles continuam visíveis neste módulo no Python 3.9.

## Objetos `ChainMap`

Novo na versão 3.3.

Uma classe `ChainMap` é fornecida para ligar rapidamente uma série de mapeamentos de forma que possam ser tratados como um só. O que é frequentemente mais rápido do que criar um novo dicionário e executar múltiplas chamadas de `update()`.

A classe pode ser usada para simular escopos aninhados e é útil em modelos.

class `collections.``ChainMap`(*maps)

  `ChainMap` agrupa múltiplos dicts ou outros mapeamentos para criar uma única vista atualizável. Se nenhum mapeamento for especificado, um dicionário vazio será fornecido para que uma nova cadeia tenha sempre pelo menos um mapeamento.

  Os mapeamentos subjacentes são armazenados em uma lista. Essa lista é pública e pode ser acessada ou atualizada usando o atributo maps. Não existe outro estado.

  Faz a busca nos mapeamentos subjacentes sucessivamente até que uma chave seja encontrada. Em contraste, escrita, atualições e remoções operam apenas no primeiro mapeamento.

  Uma `ChainMap` incorpora os mapeamentos subjacentes por referência. Então, se um dos mapeamentos subjacentes for atualizado, essas alterações serão refletidas em `ChainMap`.

  Todos os métodos usuais do dicionário são suportados. Além disso, existe um atributo maps, um método para criar novos subcontextos e uma propriedade para acessar todos, exceto o primeiro mapeamento:

  `maps`

    Uma lista de mapeamentos atualizáveis ​​pelo usuário. A lista é ordenada desde o primeiro pesquisado até a última pesquisado. É o único estado armazenado e pode ser modificado para alterar quais mapeamentos são pesquisados. A lista deve sempre conter pelo menos um mapeamento.

  `new_child`(m=None)

    Retorna uma nova `ChainMap` contendo um novo mapa seguido de todos os mapas na instância atual. Se `m` for especificado, torna-se o novo mapa na frente da lista de mapeamentos; Se não especificado, é usado um dicionário vazio, de modo que chamar `d.new_child()` é equivalente a: `ChainMap({}, *d.maps)`. Esse método é usado para criar subcontextos que podem ser atualizados sem alterar valores em nenhum dos mapeamentos pai.

    Alterado na versão 3.4: O parâmetro opcional `m` foi adicionado.

  `parents`

    Propriedade que retorna um novo `ChainMap` contendo todos os mapas da instância atual, exceto o primeiro. Isso é útil para pular o primeiro mapa da pesquisa. Os casos de uso são semelhantes aos do argumento nomeado `nonlocal` usada em escopos aninhados. Os casos de uso também são paralelos aos da função embutida `super()`. Uma referência a `d.parents` é equivalente a: `ChainMap(*d.maps[1:])`.

  Observe, a ordem de iteração de um `ChainMap()` é determinada pela varredura dos mapeamentos do último ao primeiro:

      >>> baseline = {'music': 'bach', 'art': 'rembrandt'}
      >>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}
      >>> list(ChainMap(adjustments, baseline))
      ['music', 'art', 'opera']

  Isso dá a mesma ordem de uma série de chamadas `dict.update()` começando com o último mapeamento:

      >>> combined = baseline.copy()
      >>> combined.update(adjustments)
      >>> list(combined)
      ['music', 'art', 'opera']

Ver também

- A classe MultiContext no pacote CodeTools de Enthought tem opções para suportar a escrita em qualquer mapeamento na cadeia.

- Django’s Context class for templating is a read-only chain of mappings. It also features pushing and popping of contexts similar to the `new_child()` method and the `parents` property.

- A receita de Contextos Aninhados possui opções para controlar se escritas e outras mutações se aplicam a apenas o primeiro mapeamento ou para qualquer mapeamento na cadeia.

- Uma versão muito simplificada somente leitura do Chainmap.<https://code.activestate.com/recipes/305268/>`_.

### Exemplos e Receitas de `ChainMap`

Esta seção mostra várias abordagens para trabalhar com mapas encadeados.

Exemplo de simulação da cadeia de busca interna do Python:

    import builtins
    pylookup = ChainMap(locals(), globals(), vars(builtins))

Exemplo de como permitir que os argumentos de linha de comando especificados pelo usuário tenham precedência sobre as variáveis de ambiente que, por sua vez, têm precedência sobre os valores padrão:

    import os, argparse

    defaults = {'color': 'red', 'user': 'guest'}

    parser = argparse.ArgumentParser()
    parser.add_argument('-u', '--user')
    parser.add_argument('-c', '--color')
    namespace = parser.parse_args()
    command_line_args = {k: v for k, v in vars(namespace).items() if v is not None}

    combined = ChainMap(command_line_args, os.environ, defaults)
    print(combined['color'])
    print(combined['user'])

Padrões de exemplo para utilização da classe `ChainMap` para simular contextos aninhados:

    c = ChainMap()        # Create root context
    d = c.new_child()     # Create nested child context
    e = c.new_child()     # Child of c, independent from d
    e.maps[0]             # Current context dictionary -- like Python's locals()
    e.maps[-1]            # Root context -- like Python's globals()
    e.parents             # Enclosing context chain -- like Python's nonlocals

    d['x'] = 1            # Set value in current context
    d['x']                # Get first key in the chain of contexts
    del d['x']            # Delete from current context
    list(d)               # All nested values
    k in d                # Check all nested values
    len(d)                # Number of nested values
    d.items()             # All nested items
    dict(d)               # Flatten into a regular dictionary

A classe `ChainMap` só faz atualizações (escritas e remoções) no primeiro mapeamento na cadeia, enquanto as pesquisas irão buscar em toda a cadeia. Contudo, se há o desejo de escritas e remoções profundas, é fácil fazer uma subclasse que atualiza chaves encontradas mais a fundo na cadeia:

    class DeepChainMap(ChainMap):
        'Variant of ChainMap that allows direct updates to inner scopes'

        def __setitem__(self, key, value):
            for mapping in self.maps:
                if key in mapping:
                    mapping[key] = value
                    return
            self.maps[0][key] = value

        def __delitem__(self, key):
            for mapping in self.maps:
                if key in mapping:
                    del mapping[key]
                    return
            raise KeyError(key)

    >>> d = DeepChainMap({'zebra': 'black'}, {'elephant': 'blue'}, {'lion': 'yellow'})
    >>> d['lion'] = 'orange'         # update an existing key two levels down
    >>> d['snake'] = 'red'           # new keys get added to the topmost dict
    >>> del d['elephant']            # remove an existing key one level down
    >>> d                            # display result
    DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})

## Objetos `Counter`

Uma ferramenta de contagem é fornecida para apoiar contas rápidas e convenientes. Por exemplo:

    >>> # Tally occurrences of words in a list
    >>> cnt = Counter()
    >>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
    ...     cnt[word] += 1
    >>> cnt
    Counter({'blue': 3, 'red': 2, 'green': 1})

    >>> # Find the ten most common words in Hamlet
    >>> import re
    >>> words = re.findall(r'\w+', open('hamlet.txt').read().lower())
    >>> Counter(words).most_common(10)
    [('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
     ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]

class `collections.``Counter`([iterable-or-mapping])

  Um `Counter` é uma subclasse de `dict` subclass para contagem de objetos hasheáveis. É uma coleção na qual elementos são armazenados como chaves de dicionário e suas contagens são armazenadas como valores de dicionário. Contagens podem ser qualquer valor inteiro incluindo zero e contagens negativas. A classe `Counter` é similar a sacos ou multiconjuntos em outras linguagens.

  Os elementas são contados a partir de um iterável ou inicializado a partir de um outro mapeamento (ou contador):

      >>> c = Counter()                           # a new, empty counter
      >>> c = Counter('gallahad')                 # a new counter from an iterable
      >>> c = Counter({'red': 4, 'blue': 2})      # a new counter from a mapping
      >>> c = Counter(cats=4, dogs=8)             # a new counter from keyword args

  Objetos Counter tem uma interface de dicionário, com a diferença que devolvem uma contagem zero para itens que não estão presentes em vez de levantar a excessão `KeyError`:

      >>> c = Counter(['eggs', 'ham'])
      >>> c['bacon']                              # count of a missing element is zero
      0

  Definir uma contagem como zero não remove um elemento do contador. Use `del` para o remover completamente.

      >>> c['sausage'] = 0                        # counter entry with a zero count
      >>> del c['sausage']                        # del actually removes the entry

  Novo na versão 3.1.

  Alterado na versão 3.7: Como uma subclasse de `dict`, `Counter` herda a capacidade de lembrar a ordem de inserção. Operações matemáticas em objetos Counter também preservam ordem. Os resultados são ordenados de acordo com o momento que um elemento é encontrado pela primeira vez no operando da esquerda e, em seguida, pela ordem encontrada no operando da direita.

  Objetos Counter permitem três métodos além dos disponíveis para todos os dicionário:

  `elements`()

    Retorna um iterador sobre os elementos, repetindo cada um tantas vezes quanto sua contagem. Os elementos são retornados na ordem em que foram encontrados pela primeira vez. Se a contagem de um elemento é menor que um, ele será ignorado por `elements()` .

        >>> c = Counter(a=4, b=2, c=0, d=-2)
        >>> sorted(c.elements())
        ['a', 'a', 'a', 'a', 'b', 'b']

  `most_common`([n])

    Retorna uma lista dos n elementos mais comuns e suas contagens, do mais comum para o menos comum. Se n for omitido ou igual a `None`, `most_common()` retorna todos os elementos no contador. Elementos com contagens iguais são ordenados na ordem em que foram encontrados pela primeira vez:

        >>> Counter('abracadabra').most_common(3)
        [('a', 5), ('b', 2), ('r', 2)]

  `subtract`([iterable-or-mapping])

    Os elementos são subtraídos de um iterável ou de outro mapeamento (ou contador). Funciona como `dict.update()`, mas subtraindo contagens ao invés de substituí-las. Tanto as entradas quanto as saídas podem ser zero ou negativas.

        >>> c = Counter(a=4, b=2, c=0, d=-2)
        >>> d = Counter(a=1, b=2, c=3, d=4)
        >>> c.subtract(d)
        >>> c
        Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})

    Novo na versão 3.2.

  Os métodos usuais de dicionário estão disponíveis para objetos `Counter`, exceto por dois que funcionam de forma diferente para contadores.

  `fromkeys`(iterable)

    Este método de classe não está implementado para objetos `Counter`.

  `update`([iterable-or-mapping])

    Elementos são contados a partir de um iterável ou adicionados de outro mapeamento (ou contador). Funciona como `dict.update()` mas adiciona contagens em vez de substituí-las. Além disso, é esperado que o iterável seja uma sequência de elementos, e não uma sequência de pares `(key, value)`.

Padrões comuns para trabalhar com objetos `Counter`:

    sum(c.values())                 # total of all counts
    c.clear()                       # reset all counts
    list(c)                         # list unique elements
    set(c)                          # convert to a set
    dict(c)                         # convert to a regular dictionary
    c.items()                       # convert to a list of (elem, cnt) pairs
    Counter(dict(list_of_pairs))    # convert from a list of (elem, cnt) pairs
    c.most_common()[:-n-1:-1]       # n least common elements
    +c                              # remove zero and negative counts

Várias operações matemáticas são fornecidas para combinar: class: objetos Counter para produzir multisets (counters que têm contagens maiores que zero). A adição e a subtração combinam counters adicionando ou subtraindo as contagens dos elementos correspondentes. A intersecção e a união retornam o mínimo e o máximo das contagens correspondentes. Cada operação pode aceitar entradas com contagens assinadas, mas a saída excluirá resultados com contagens de zero ou menos.

    >>> c = Counter(a=3, b=1)
    >>> d = Counter(a=1, b=2)
    >>> c + d                       # add two counters together:  c[x] + d[x]
    Counter({'a': 4, 'b': 3})
    >>> c - d                       # subtract (keeping only positive counts)
    Counter({'a': 2})
    >>> c & d                       # intersection:  min(c[x], d[x])
    Counter({'a': 1, 'b': 1})
    >>> c | d                       # union:  max(c[x], d[x])
    Counter({'a': 3, 'b': 2})

A adição e subtração unárias são atalhos para adicionar um contador vazio ou subtrair de um contador vazio.

    >>> c = Counter(a=2, b=-4)
    >>> +c
    Counter({'a': 2})
    >>> -c
    Counter({'b': 4})

Novo na versão 3.3: Adicionado suporte para operador unário mais, unário menos e operação in-place multiset.

Nota

Os contadores foram projetados principalmente para funcionar com números inteiros positivos para representar contagens contínuas; no entanto, foi tomado cuidado para não impedir desnecessariamente os casos de uso que precisassem de outros tipos ou valores negativos. Para ajudar nesses casos de uso, esta seção documenta o intervalo mínimo e as restrições de tipo.

- A própria classe `Counter` é uma subclasse de dicionário sem restrições em suas chaves e valores. Os valores pretendem ser números que representam contagens, mas você pode armazenar qualquer coisa no campo de valor.

- O método `most_common()` requer apenas que os valores sejam ordenáveis.

- Para operações in-place, como `c[key] += 1`, o tipo de valor precisa suportar apenas adição e subtração. Portanto, frações, números de ponto flutuante e decimais funcionariam e os valores negativos são suportados. O mesmo também é verdadeiro para: meth: ~ Counter.update e: meth:` ~ Counter.subtract` que permitem valores negativos e zero para entradas e saídas.

- Os métodos multiset são projetados apenas para casos de uso com valores positivos. As entradas podem ser negativas ou zero, mas apenas saídas com valores positivos são criadas. Não há restrições de tipo, mas o tipo de valor precisa suportar adição, subtração e comparação.

- O método: meth: ~ Counter.elements requer contagens inteiras. Ele ignora contagens zero e negativas.

Ver também

- Classe Bag <https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html> `_ em Smalltalk.

- Entrada da Wikipedia para Multisets <https://en.wikipedia.org/wiki/Multiset> _.

- Tutorial com exemplos C++ multisets.

- Para operações matemáticas em multisets e seus casos de uso, consulte * Knuth, Donald. The Art of Computer Programming Volume II, Seção 4.6.3, Exercício 19 *.

- Para enumerar todos os multisets distintos de um determinado tamanho em um determinado conjunto de elementos, consulte: func:` itertools.combinations_with_replacement`

      map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC

## Objetos `deque`

class `collections.``deque`([iterable[, maxlen]])

  Retorna um novo objeto deque inicializado da esquerda para a direita (usando: meth: append) com dados de * iterável *. Se * iterável * não for especificado, o novo deque estará vazio.

  Deques são uma generalização de pilhas e filas (o nome é pronunciado “deck” e é abreviação de “fila dupla”). O Deques oferece suporte para acréscimos e saliências com segurança de thread e com eficiência de memória de ambos os lados do deque com aproximadamente o mesmo desempenho O (1) em qualquer direção.

  Embora os objetos: class: list suportem operações semelhantes, eles são otimizados para operações rápidas de comprimento fixo e sujeitam em custos de movimentação de memória O (n) para` pop (0) e insert (0, v) ` operações que alteram o tamanho e a posição da representação de dados subjacente.

  Se * maxlen * não for especificado ou for `` Nenhum``, deques podem crescer para um comprimento arbitrário. Caso contrário, o deque é limitado ao comprimento máximo especificado. Quando um deque de comprimento limitado está cheio, quando novos itens são adicionados, um número correspondente de itens é descartado da extremidade oposta. Deques de comprimento limitado fornecem funcionalidade semelhante ao filtro `` tail`` no Unix. Eles também são úteis para rastrear transações e outros pools de dados onde apenas a atividade mais recente é de interesse.

  Os objetos Deque suportam os seguintes métodos:

  `append`(x)

    Adicione * x * ao lado direito do deque.

  `appendleft`(x)

    Adicione * x * ao lado esquerdo do deque

  `clear`()

    Remova todos os elementos do deque deixando-o com comprimento 0.

  `copy`()

    Cria uma cópia rasa do deque.

    Novo na versão 3.5.

  `count`(x)

    Conta o número de elementos deque igual a * x *.

    Novo na versão 3.2.

  `extend`(iterable)

    Estenda o lado direito do deque anexando elementos do argumento iterável.

  `extendleft`(iterable)

    Estenda o lado esquerdo do deque anexando elementos de iterable. Observe que a série de acréscimos à esquerda resulta na reversão da ordem dos elementos no argumento iterável.

  `index`(x[, start[, stop]])

    Retorne a posição de * x * no deque (no ou após o índice * início * e antes do índice * parada *). Retorna a primeira correspondência ou aumenta: exc: ValueError se não for encontrado.

    Novo na versão 3.5.

  `insert`(i, x)

    Insira * x * no deque na posição * i *.

    Se a inserção fizer com que um deque limitado cresça além de * maxlen *, um: exc: IndexError é gerado.

    Novo na versão 3.5.

  `pop`()

    Remova e devolva um elemento do lado direito do deque. Se nenhum elemento estiver presente, levanta um: exc: IndexError.

  `popleft`()

    Remova e devolva um elemento do lado esquerdo do deque. Se nenhum elemento estiver presente, levanta um: exc: IndexError.

  `remove`(value)

    Remova a primeira ocorrência de * valor *. Se não for encontrado, levanta um: exc: ValueError.

  `reverse`()

    Inverta os elementos do deque no local e, em seguida, retorne `None`.

    Novo na versão 3.2.

  `rotate`(n=1)

    Gire os passos deque * n * para a direita. Se * n * for negativo, gire para a esquerda.

    Quando o deque não está vazio, girar um passo para a direita é equivalente a `d.appendleft(d.pop())`, e girar um passo para a esquerda é equivalente a `d.append(d.popleft())`.

  Os objetos Deque também fornecem um atributo somente leitura:

  `maxlen`

    Tamanho máximo de um deque ou `None` se ilimitado.

    Novo na versão 3.1.

Além do acima, deques oferece suporte a iteração, decapagem, teste de associação com o operador: keyword: in e referências subscritas, como para acessar o primeiro elemento. O acesso indexado é O (1) em ambas as extremidades, mas diminui para O (n) no meio. Para acesso aleatório rápido, use listas.

A partir da versão 3.5, deques suporta `` __add __ () ``, `` __mul __ () `` e `` __imul __ () ``.

Exemplo:

    >>> from collections import deque
    >>> d = deque('ghi')                 # make a new deque with three items
    >>> for elem in d:                   # iterate over the deque's elements
    ...     print(elem.upper())
    G
    H
    I

    >>> d.append('j')                    # add a new entry to the right side
    >>> d.appendleft('f')                # add a new entry to the left side
    >>> d                                # show the representation of the deque
    deque(['f', 'g', 'h', 'i', 'j'])

    >>> d.pop()                          # return and remove the rightmost item
    'j'
    >>> d.popleft()                      # return and remove the leftmost item
    'f'
    >>> list(d)                          # list the contents of the deque
    ['g', 'h', 'i']
    >>> d[0]                             # peek at leftmost item
    'g'
    >>> d[-1]                            # peek at rightmost item
    'i'

    >>> list(reversed(d))                # list the contents of a deque in reverse
    ['i', 'h', 'g']
    >>> 'h' in d                         # search the deque
    True
    >>> d.extend('jkl')                  # add multiple elements at once
    >>> d
    deque(['g', 'h', 'i', 'j', 'k', 'l'])
    >>> d.rotate(1)                      # right rotation
    >>> d
    deque(['l', 'g', 'h', 'i', 'j', 'k'])
    >>> d.rotate(-1)                     # left rotation
    >>> d
    deque(['g', 'h', 'i', 'j', 'k', 'l'])

    >>> deque(reversed(d))               # make a new deque in reverse order
    deque(['l', 'k', 'j', 'i', 'h', 'g'])
    >>> d.clear()                        # empty the deque
    >>> d.pop()                          # cannot pop from an empty deque
    Traceback (most recent call last):
        File "<pyshell#6>", line 1, in -toplevel-
            d.pop()
    IndexError: pop from an empty deque

    >>> d.extendleft('abc')              # extendleft() reverses the input order
    >>> d
    deque(['c', 'b', 'a'])

### Receitas de `deque`

Esta seção mostra várias abordagens para trabalhar com deques.

Deques de comprimento limitado fornecem funcionalidade semelhante ao filtro `tail` em Unix

    def tail(filename, n=10):
        'Return the last n lines of a file'
        with open(filename) as f:
            return deque(f, n)

Outra abordagem para usar deques é manter uma sequência de elementos adicionados recentemente, acrescentando à direita e clicando à esquerda:

    def moving_average(iterable, n=3):
        # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
        # http://en.wikipedia.org/wiki/Moving_average
        it = iter(iterable)
        d = deque(itertools.islice(it, n-1))
        d.appendleft(0)
        s = sum(d)
        for elem in it:
            s += elem - d.popleft()
            d.append(elem)
            yield s / n

Um escalonador round-robin <https://en.wikipedia.org/wiki/Round-robin_scheduling> _ pode ser implementado com iteradores de entrada armazenados em um: class: deque. Os valores são gerados a partir do iterador ativo na posição zero. Se esse iterador estiver esgotado, ele pode ser removido com: meth: ~ deque.popleft; caso contrário, ele pode voltar ao fim com o método: meth: ~ deque.rotate

    def roundrobin(*iterables):
        "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
        iterators = deque(map(iter, iterables))
        while iterators:
            try:
                while True:
                    yield next(iterators[0])
                    iterators.rotate(-1)
            except StopIteration:
                # Remove an exhausted iterator.
                iterators.popleft()

O método: meth: ~ deque.rotate fornece uma maneira de implementar o corte e exclusão: class:` deque`. Por exemplo, uma implementação Python pura de `del d[n]` depende do método `rotate()` para posicionar os elementos a serem popped

    def delete_nth(d, n):
        d.rotate(-n)
        d.popleft()
        d.rotate(n)

Para implementar o corte: class: deque, use uma abordagem semelhante aplicando: meth:` ~ deque.rotate` para trazer um elemento alvo para o lado esquerdo do deque. Remova as entradas antigas com: meth: ~ deque.popleft, adicione novas entradas com: meth:` ~ deque.extend`, e então inverta a rotação. Com pequenas variações dessa abordagem, é fácil implementar manipulações de pilha de estilo Forth, como `dup`,``drop``,``swap``,``over``,``pick``,``rot``, and `roll`.

## Objetos `defaultdict`

class `collections.``defaultdict`([default_factory[, ...]])

  Returns a new dictionary-like object. `defaultdict` is a subclass of the built-in `dict` class. It overrides one method and adds one writable instance variable. The remaining functionality is the same as for the `dict` class and is not documented here.

  O primeiro argumento fornece o valor inicial para o atributo: attr: default_factory; o padrão é `` Nenhum``. Todos os argumentos restantes são tratados da mesma forma como se fossem passados ​​para o construtor: class: dict, incluindo argumentos de palavra-chave.

  Os objetos: class: defaultdict suportam o seguinte método além das operações padrão: class:` dict`:

  `__missing__`(key)

    Se o atributo: attr: default_factory é `None`, isso levanta uma exceção: exc:` KeyError` com a * chave * como argumento.

    Se: attr: default_factory não for `None`, ele é chamado sem argumentos para fornecer um valor padrão para a * chave * fornecida, este valor é inserido no dicionário para a * chave * e retornado.

    Se chamar: attr: default_factory levanta uma exceção, esta exceção é propagada inalterada.

    Este método é chamado pelo método: meth: __getitem__ da classe: class:` dict` quando a chave solicitada não é encontrada; tudo o que ele retorna ou aumenta é então retornado ou gerado por: meth: __getitem__.

    Note that `__missing__()` is not called for any operations besides `__getitem__()`. This means that `get()` will, like normal dictionaries, return `None` as a default rather than using `default_factory`.

  Objetos `defaultdict` permitem a seguinte variável instanciada:

  `default_factory`

    This attribute is used by the `__missing__()` method; it is initialized from the first argument to the constructor, if present, or to `None`, if absent.

### Exemplos de `defaultdict`

Usando `list` como `default_factory`, se for fácil agrupar a sequencia dos pares chave-valores num dicionário de listas

    >>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
    >>> d = defaultdict(list)
    >>> for k, v in s:
    ...     d[k].append(v)
    ...
    >>> sorted(d.items())
    [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

When each key is encountered for the first time, it is not already in the mapping; so an entry is automatically created using the `default_factory` function which returns an empty `list`. The `list.append()` operation then attaches the value to the new list. When keys are encountered again, the look-up proceeds normally (returning the list for that key) and the `list.append()` operation adds another value to the list. This technique is simpler and faster than an equivalent technique using `dict.setdefault()`:

    >>> d = {}
    >>> for k, v in s:
    ...     d.setdefault(k, []).append(v)
    ...
    >>> sorted(d.items())
    [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

Setting the `default_factory` to `int` makes the `defaultdict` useful for counting (like a bag or multiset in other languages):

    >>> s = 'mississippi'
    >>> d = defaultdict(int)
    >>> for k in s:
    ...     d[k] += 1
    ...
    >>> sorted(d.items())
    [('i', 4), ('m', 1), ('p', 2), ('s', 4)]

When a letter is first encountered, it is missing from the mapping, so the `default_factory` function calls `int()` to supply a default count of zero. The increment operation then builds up the count for each letter.

The function `int()` which always returns zero is just a special case of constant functions. A faster and more flexible way to create constant functions is to use a lambda function which can supply any constant value (not just zero):

    >>> def constant_factory(value):
    ...     return lambda: value
    >>> d = defaultdict(constant_factory('<missing>'))
    >>> d.update(name='John', action='ran')
    >>> '%(name)s %(action)s to %(object)s' % d
    'John ran to <missing>'

Setting the `default_factory` to `set` makes the `defaultdict` useful for building a dictionary of sets:

    >>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
    >>> d = defaultdict(set)
    >>> for k, v in s:
    ...     d[k].add(v)
    ...
    >>> sorted(d.items())
    [('blue', {2, 4}), ('red', {1, 3})]

## `namedtuple()` Factory Function for Tuples with Named Fields

Tuplas nomeadas determinam o significado de cada posição numa tupla e permitem um código mais legível e autodocumentado. Podem ser usadas sempre que tuplas regulares forem utilizadas, e adicionam a possibilidade de acessar campos pelo nome ao invés da posição do índice.

`collections.``namedtuple`(typename, field_names, *, rename=False, defaults=None, module=None)

  Returns a new tuple subclass named typename. The new subclass is used to create tuple-like objects that have fields accessible by attribute lookup as well as being indexable and iterable. Instances of the subclass also have a helpful docstring (with typename and field_names) and a helpful `__repr__()` method which lists the tuple contents in a `name=value` format.

  The field_names are a sequence of strings such as `['x', 'y']`. Alternatively, field_names can be a single string with each fieldname separated by whitespace and/or commas, for example `'x y'` or `'x, y'`.

  Any valid Python identifier may be used for a fieldname except for names starting with an underscore. Valid identifiers consist of letters, digits, and underscores but do not start with a digit or underscore and cannot be a `keyword` such as class, for, return, global, pass, or raise.

  If rename is true, invalid fieldnames are automatically replaced with positional names. For example, `['abc', 'def', 'ghi', 'abc']` is converted to `['abc', '_1', 'ghi', '_3']`, eliminating the keyword `def` and the duplicate fieldname `abc`.

  defaults can be `None` or an iterable of default values. Since fields with a default value must come after any fields without a default, the defaults are applied to the rightmost parameters. For example, if the fieldnames are `['x', 'y', 'z']` and the defaults are `(1, 2)`, then `x` will be a required argument, `y` will default to `1`, and `z` will default to `2`.

  If module is defined, the `__module__` attribute of the named tuple is set to that value.

  Named tuple instances do not have per-instance dictionaries, so they are lightweight and require no more memory than regular tuples.

  Alterado na versão 3.1: Adicionado suporte a rename.

  Alterado na versão 3.6: The verbose and rename parameters became keyword-only arguments.

  Alterado na versão 3.6: Adicionado o parametro module

  Alterado na versão 3.7: Removido o parametro verbose e o atributo `_source`

  Alterado na versão 3.7: Adicionado o parâmetro defaults e o atributo `_field_defaults`.

    >>> # Basic example
    >>> Point = namedtuple('Point', ['x', 'y'])
    >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
    >>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
    33
    >>> x, y = p                # unpack like a regular tuple
    >>> x, y
    (11, 22)
    >>> p.x + p.y               # fields also accessible by name
    33
    >>> p                       # readable __repr__ with a name=value style
    Point(x=11, y=22)

Named tuples are especially useful for assigning field names to result tuples returned by the `csv` or `sqlite3` modules:

    EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')

    import csv
    for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
        print(emp.name, emp.title)

    import sqlite3
    conn = sqlite3.connect('/companydata')
    cursor = conn.cursor()
    cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
    for emp in map(EmployeeRecord._make, cursor.fetchall()):
        print(emp.name, emp.title)

In addition to the methods inherited from tuples, named tuples support three additional methods and two attributes. To prevent conflicts with field names, the method and attribute names start with an underscore.

classmethod `somenamedtuple.``_make`(iterable)

  Class method that makes a new instance from an existing sequence or iterable.

      >>> t = [11, 22]
      >>> Point._make(t)
      Point(x=11, y=22)

`somenamedtuple.``_asdict`()

  Retorna um novo `dict` que mapeia nomes de campo para seus respectivos valores:

      >>> p = Point(x=11, y=22)
      >>> p._asdict()
      {'x': 11, 'y': 22}

  Alterado na versão 3.1: Returns an `OrderedDict` instead of a regular `dict`.

  Alterado na versão 3.8: Returns a regular `dict` instead of an `OrderedDict`. As of Python 3.7, regular dicts are guaranteed to be ordered. If the extra features of `OrderedDict` are required, the suggested remediation is to cast the result to the desired type: `OrderedDict(nt._asdict())`.

`somenamedtuple.``_replace`(**kwargs)

  Return a new instance of the named tuple replacing specified fields with new values:

      >>> p = Point(x=11, y=22)
      >>> p._replace(x=33)
      Point(x=33, y=22)

      >>> for partnum, record in inventory.items():
      ...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())

`somenamedtuple.``_fields`

  Tuple of strings listing the field names. Useful for introspection and for creating new named tuple types from existing named tuples.

      >>> p._fields            # view the field names
      ('x', 'y')

      >>> Color = namedtuple('Color', 'red green blue')
      >>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
      >>> Pixel(11, 22, 128, 255, 0)
      Pixel(x=11, y=22, red=128, green=255, blue=0)

`somenamedtuple.``_field_defaults`

  Dictionary mapping field names to default values.

      >>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
      >>> Account._field_defaults
      {'balance': 0}
      >>> Account('premium')
      Account(type='premium', balance=0)

To retrieve a field whose name is stored in a string, use the `getattr()` function:

    >>> getattr(p, 'x')
    11

To convert a dictionary to a named tuple, use the double-star-operator (as described in Desempacotando listas de argumentos):

    >>> d = {'x': 11, 'y': 22}
    >>> Point(**d)
    Point(x=11, y=22)

Since a named tuple is a regular Python class, it is easy to add or change functionality with a subclass. Here is how to add a calculated field and a fixed-width print format:

    >>> class Point(namedtuple('Point', ['x', 'y'])):
    ...     __slots__ = ()
    ...     @property
    ...     def hypot(self):
    ...         return (self.x ** 2 + self.y ** 2) ** 0.5
    ...     def __str__(self):
    ...         return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

    >>> for p in Point(3, 4), Point(14, 5/7):
    ...     print(p)
    Point: x= 3.000  y= 4.000  hypot= 5.000
    Point: x=14.000  y= 0.714  hypot=14.018

The subclass shown above sets `__slots__` to an empty tuple. This helps keep memory requirements low by preventing the creation of instance dictionaries.

Subclassing is not useful for adding new, stored fields. Instead, simply create a new named tuple type from the `_fields` attribute:

    >>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

Docstrings can be customized by making direct assignments to the `__doc__` fields:

    >>> Book = namedtuple('Book', ['id', 'title', 'authors'])
    >>> Book.__doc__ += ': Hardcover book in active collection'
    >>> Book.id.__doc__ = '13-digit ISBN'
    >>> Book.title.__doc__ = 'Title of first printing'
    >>> Book.authors.__doc__ = 'List of authors sorted by last name'

Alterado na versão 3.5: Property docstrings became writeable.

Ver também

- See `typing.NamedTuple` for a way to add type hints for named tuples. It also provides an elegant notation using the `class` keyword:

      class Component(NamedTuple):
          part_number: int
          weight: float
          description: Optional[str] = None

- See `types.SimpleNamespace()` for a mutable namespace based on an underlying dictionary instead of a tuple.

- The `dataclasses` module provides a decorator and functions for automatically adding generated special methods to user-defined classes.

## Objetos `OrderedDict`

Ordered dictionaries are just like regular dictionaries but have some extra capabilities relating to ordering operations. They have become less important now that the built-in `dict` class gained the ability to remember insertion order (this new behavior became guaranteed in Python 3.7).

Some differences from `dict` still remain:

- The regular `dict` was designed to be very good at mapping operations. Tracking insertion order was secondary.

- The `OrderedDict` was designed to be good at reordering operations. Space efficiency, iteration speed, and the performance of update operations were secondary.

- Algorithmically, `OrderedDict` can handle frequent reordering operations better than `dict`. This makes it suitable for tracking recent accesses (for example in an LRU cache).

- The equality operation for `OrderedDict` checks for matching order.

- The `popitem()` method of `OrderedDict` has a different signature. It accepts an optional argument to specify which item is popped.

- `OrderedDict` has a `move_to_end()` method to efficiently reposition an element to an endpoint.

- Until Python 3.8, `dict` lacked a `__reversed__()` method.

class `collections.``OrderedDict`([items])

  Return an instance of a `dict` subclass that has methods specialized for rearranging dictionary order.

  Novo na versão 3.1.

  `popitem`(last=True)

    The `popitem()` method for ordered dictionaries returns and removes a (key, value) pair. The pairs are returned in LIFO order if last is true or FIFO order if false.

  `move_to_end`(key, last=True)

    Move an existing key to either end of an ordered dictionary. The item is moved to the right end if last is true (the default) or to the beginning if last is false. Raises `KeyError` if the key does not exist:

        >>> d = OrderedDict.fromkeys('abcde')
        >>> d.move_to_end('b')
        >>> ''.join(d.keys())
        'acdeb'
        >>> d.move_to_end('b', last=False)
        >>> ''.join(d.keys())
        'bacde'

    Novo na versão 3.2.

Além dos métodos usuais de mapeamento, dicionários ordenados também suportam iteração reversa usando a função `reversed()`.

Equality tests between `OrderedDict` objects are order-sensitive and are implemented as `list(od1.items())==list(od2.items())`. Equality tests between `OrderedDict` objects and other `Mapping` objects are order-insensitive like regular dictionaries. This allows `OrderedDict` objects to be substituted anywhere a regular dictionary is used.

Alterado na versão 3.5: The items, keys, and values views of `OrderedDict` now support reverse iteration using `reversed()`.

Alterado na versão 3.6: With the acceptance of PEP 468, order is retained for keyword arguments passed to the `OrderedDict` constructor and its `update()` method.

### `OrderedDict` Examples and Recipes

It is straightforward to create an ordered dictionary variant that remembers the order the keys were last inserted. If a new entry overwrites an existing entry, the original insertion position is changed and moved to the end:

    class LastUpdatedOrderedDict(OrderedDict):
        'Store items in the order the keys were last added'

        def __setitem__(self, key, value):
            super().__setitem__(key, value)
            self.move_to_end(key)

An `OrderedDict` would also be useful for implementing variants of `functools.lru_cache()`:

    class LRU(OrderedDict):
        'Limit size, evicting the least recently looked-up key when full'

        def __init__(self, maxsize=128, /, *args, **kwds):
            self.maxsize = maxsize
            super().__init__(*args, **kwds)

        def __getitem__(self, key):
            value = super().__getitem__(key)
            self.move_to_end(key)
            return value

        def __setitem__(self, key, value):
            if key in self:
                self.move_to_end(key)
            super().__setitem__(key, value)
            if len(self) > self.maxsize:
                oldest = next(iter(self))
                del self[oldest]

## `UserDict` objects

The class, `UserDict` acts as a wrapper around dictionary objects. The need for this class has been partially supplanted by the ability to subclass directly from `dict`; however, this class can be easier to work with because the underlying dictionary is accessible as an attribute.

class `collections.``UserDict`([initialdata])

  Class that simulates a dictionary. The instance’s contents are kept in a regular dictionary, which is accessible via the `data` attribute of `UserDict` instances. If initialdata is provided, `data` is initialized with its contents; note that a reference to initialdata will not be kept, allowing it be used for other purposes.

  In addition to supporting the methods and operations of mappings, `UserDict` instances provide the following attribute:

  `data`

    A real dictionary used to store the contents of the `UserDict` class.

## `UserList` objects

This class acts as a wrapper around list objects. It is a useful base class for your own list-like classes which can inherit from them and override existing methods or add new ones. In this way, one can add new behaviors to lists.

The need for this class has been partially supplanted by the ability to subclass directly from `list`; however, this class can be easier to work with because the underlying list is accessible as an attribute.

class `collections.``UserList`([list])

  Class that simulates a list. The instance’s contents are kept in a regular list, which is accessible via the `data` attribute of `UserList` instances. The instance’s contents are initially set to a copy of list, defaulting to the empty list `[]`. list can be any iterable, for example a real Python list or a `UserList` object.

  In addition to supporting the methods and operations of mutable sequences, `UserList` instances provide the following attribute:

  `data`

    A real `list` object used to store the contents of the `UserList` class.

Subclassing requirements: Subclasses of `UserList` are expected to offer a constructor which can be called with either no arguments or one argument. List operations which return a new sequence attempt to create an instance of the actual implementation class. To do so, it assumes that the constructor can be called with a single parameter, which is a sequence object used as a data source.

If a derived class does not wish to comply with this requirement, all of the special methods supported by this class will need to be overridden; please consult the sources for information about the methods which need to be provided in that case.

## `UserString` objects

The class, `UserString` acts as a wrapper around string objects. The need for this class has been partially supplanted by the ability to subclass directly from `str`; however, this class can be easier to work with because the underlying string is accessible as an attribute.

class `collections.``UserString`(seq)

  Class that simulates a string object. The instance’s content is kept in a regular string object, which is accessible via the `data` attribute of `UserString` instances. The instance’s contents are initially set to a copy of seq. The seq argument can be any object which can be converted into a string using the built-in `str()` function.

  In addition to supporting the methods and operations of strings, `UserString` instances provide the following attribute:

  `data`

    A real `str` object used to store the contents of the `UserString` class.

  Alterado na versão 3.5: New methods `__getnewargs__`, `__rmod__`, `casefold`, `format_map`, `isprintable`, and `maketrans`.