collections.rst

:mod:`collections` -- collection and container types

Limitations: Not implemented on the smallest CircuitPython boards for space reasons.

.. module:: collections
   :synopsis: collection and container types

|see_cpython_module| :mod:`python:collections`.

This module implements advanced collection and container types to hold/accumulate various objects.

Classes

Deques (pronounced "deck" and short for "double-ended queue") are fixed length list-like containers that support O(1) appends and pops from either side of the deque. New deques are created using the following arguments:

• iterable must be specified as an empty or non-empty iterable. If the iterable is empty, the new deque is created empty. If the iterable is not empty, the new deque is created with the items from the iterable.
• maxlen must be specified and the deque will be bounded to this maximum length. Once the deque is full, any new items added will discard items from the opposite end.
• flag is optional and can be set to 1 to check for overflow when adding items. If the deque is full and overflow checking is enabled, an IndexError will be raised when adding items.

Deque objects have the following methods:

.. method:: deque.append(x)

    Add *x* to the right side of the deque.
    Raises ``IndexError`` if overflow checking is enabled and there is
    no more room in the queue.

.. method:: deque.appendleft(x)

    Add *x* to the left side of the deque.
    Raises ``IndexError`` if overflow checking is enabled and there is
    no more room in the queue.

.. method:: deque.pop()

    Remove and return an item from the right side of the deque.
    Raises ``IndexError`` if no items are present.

.. method:: deque.popleft()

    Remove and return an item from the left side of the deque.
    Raises ``IndexError`` if no items are present.

.. method:: deque.extend(iterable)

    Extend the right side of the deque by appending items from the ``iterable`` argument.
    Raises IndexError if overflow checking is enabled and there is no more room left
    for all of the items in ``iterable``.

In addition to the above, deques support iteration, bool, len(d), reversed(d), membership testing with the in operator, and subscript references like d[0]. Note: Indexed access is O(1) at both ends but slows to O(n) in the middle of the deque, so for fast random access use a list instead.

.. function:: namedtuple(name, fields)

    This is factory function to create a new namedtuple type with a specific
    name and set of fields. A namedtuple is a subclass of tuple which allows
    to access its fields not just by numeric index, but also with an attribute
    access syntax using symbolic field names. Fields is a sequence of strings
    specifying field names. For compatibility with CPython it can also be a
    a string with space-separated field named (but this is less efficient).
    Example of use::

        from collections import namedtuple

        MyTuple = namedtuple("MyTuple", ("id", "name"))
        t1 = MyTuple(1, "foo")
        t2 = MyTuple(2, "bar")
        print(t1.name)
        assert t2.name == t2[1]

dict type subclass which remembers and preserves the order of keys added. When ordered dict is iterated over, keys/items are returned in the order they were added:

from collections import OrderedDict

# To make benefit of ordered keys, OrderedDict should be initialized
# from sequence of (key, value) pairs.
d = OrderedDict([("z", 1), ("a", 2)])
# More items can be added as usual
d["w"] = 5
d["b"] = 3
for k, v in d.items():
    print(k, v)

Output:

z 1
a 2
w 5
b 3

.. method:: OrderedDict.popitem()

    Remove and return a (key, value) pair from the dictionary.
    Pairs are returned in LIFO order.

    .. admonition:: Difference to CPython
        :class: attention

        ``OrderedDict.popitem()`` does not support the ``last=False`` argument and
        will always remove and return the last item if present.

        A workaround for this is to use ``pop(<first_key>)`` to remove the first item::

            first_key = next(iter(d))
            d.pop(first_key)