Issue #14386: Expose the dict_proxy internal type as types.MappingProxyType

4 files changed, 73 insertions, 10 deletions

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index ac714a6..6bacc32 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -36,11 +36,11 @@ Dictionary Objects
    Return a new empty dictionary, or *NULL* on failure.
 
 
-.. c:function:: PyObject* PyDictProxy_New(PyObject *dict)
+.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
 
-   Return a proxy object for a mapping which enforces read-only behavior.
-   This is normally used to create a proxy to prevent modification of the
-   dictionary for non-dynamic class types.
+   Return a :class:`types.MappingProxyType` object for a mapping which
+   enforces read-only behavior.  This is normally used to create a view to
+   prevent modification of the dictionary for non-dynamic class types.
 
 
 .. c:function:: void PyDict_Clear(PyObject *p)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 8b8400e..f06f579 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2258,13 +2258,13 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
 
    .. method:: items()
 
-      Return a new view of the dictionary's items (``(key, value)`` pairs).  See
-      below for documentation of view objects.
+      Return a new view of the dictionary's items (``(key, value)`` pairs).
+      See the :ref:`documentation of view objects <dict-views>`.
 
    .. method:: keys()
 
-      Return a new view of the dictionary's keys.  See below for documentation of
-      view objects.
+      Return a new view of the dictionary's keys.  See the :ref:`documentation
+      of view objects <dict-views>`.
 
    .. method:: pop(key[, default])
 
@@ -2298,8 +2298,12 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
 
    .. method:: values()
 
-      Return a new view of the dictionary's values.  See below for documentation of
-      view objects.
+      Return a new view of the dictionary's values.  See the
+      :ref:`documentation of view objects <dict-views>`.
+
+.. seealso::
+   :class:`types.MappingProxyType` can be used to create a read-only view
+   of a :class:`dict`.
 
 
 .. _dict-views:
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index d4a76b6..0368177 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -85,3 +85,55 @@ The module defines the following names:
 
       In other implementations of Python, this type may be identical to
       ``GetSetDescriptorType``.
+
+.. class:: MappingProxyType(mapping)
+
+   Read-only proxy of a mapping. It provides a dynamic view on the mapping's
+   entries, which means that when the mapping changes, the view reflects these
+   changes.
+
+   .. versionadded:: 3.3
+
+   .. describe:: key in proxy
+
+      Return ``True`` if the underlying mapping has a key *key*, else
+      ``False``.
+
+   .. describe:: proxy[key]
+
+      Return the item of the underlying mapping with key *key*.  Raises a
+      :exc:`KeyError` if *key* is not in the underlying mapping.
+
+   .. describe:: iter(proxy)
+
+      Return an iterator over the keys of the underlying mapping.  This is a
+      shortcut for ``iter(proxy.keys())``.
+
+   .. describe:: len(proxy)
+
+      Return the number of items in the underlying mapping.
+
+   .. method:: copy()
+
+      Return a shallow copy of the underlying mapping.
+
+   .. method:: get(key[, default])
+
+      Return the value for *key* if *key* is in the underlying mapping, else
+      *default*.  If *default* is not given, it defaults to ``None``, so that
+      this method never raises a :exc:`KeyError`.
+
+   .. method:: items()
+
+      Return a new view of the underlying mapping's items (``(key, value)``
+      pairs).
+
+   .. method:: keys()
+
+      Return a new view of the underlying mapping's keys.
+
+   .. method:: values()
+
+      Return a new view of the underlying mapping's values.
+
+
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index 766d3f3..495243f 100644
--- a/Doc/whatsnew/3.3.rst
+++ b/Doc/whatsnew/3.3.rst
@@ -1068,6 +1068,13 @@ The :mod:`time` module has new functions:
 (Contributed by Victor Stinner in :issue:`10278`)
 
 
+types
+-----
+
+Add a new :class:`types.MappingProxyType` class: Read-only proxy of a mapping.
+(:issue:`14386`)
+
+
 urllib
 ------