docs: Add _collections module reference.

2 files changed, 56 insertions, 0 deletions

diff --git a/docs/library/_collections.rst b/docs/library/_collections.rst
new file mode 100644
index 0000000000..2554c4d0a1
--- /dev/null
+++ b/docs/library/_collections.rst
@@ -0,0 +1,53 @@
+:mod:`_collections` -- collection and container types
+=====================================================
+
+.. module:: _collections
+   :synopsis: collection and container types
+
+This module implements advanced collection and container types to
+hold/accumulate various objects.
+
+Classes
+-------
+
+.. function:: namedtuple(name, fields)
+
+    This is factory function to create a new namedtuple type with a specific
+    name and set of fields. A namedtyple 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 compatibily 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]
+
+.. function:: OrderedDict(...)
+
+    ``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
diff --git a/docs/library/index.rst b/docs/library/index.rst
index 87fbb3cffb..b954f3cf1b 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -28,6 +28,7 @@ library.
        :maxdepth: 1
 
        cmath.rst
+       _collections.rst
        gc.rst
        math.rst
        select.rst
@@ -49,6 +50,7 @@ library.
        :maxdepth: 1
 
        cmath.rst
+       _collections.rst
        gc.rst
        math.rst
        select.rst
@@ -85,6 +87,7 @@ library.
     .. toctree::
        :maxdepth: 1
 
+       _collections.rst
        gc.rst
        math.rst
        sys.rst