Issue #14386: Expose the dict_proxy internal type as types.MappingProxyType
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 @@
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 @@
.. 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 @@
.. 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 @@
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 @@
(Contributed by Victor Stinner in :issue:`10278`)
+types
+-----
+
+Add a new :class:`types.MappingProxyType` class: Read-only proxy of a mapping.
+(:issue:`14386`)
+
+
urllib
------