DOC: Document ``dtype.metadata``

This adds some basic documentation to the ``dtype.metadata``
attribute.  Note that none of the documentation mentions metadata
including https://numpy.org/devdocs/reference/arrays.dtypes.html

2 files changed, 40 insertions, 0 deletions

diff --git a/doc/source/reference/arrays.dtypes.rst b/doc/source/reference/arrays.dtypes.rst
index c7703764f..575984707 100644
--- a/doc/source/reference/arrays.dtypes.rst
+++ b/doc/source/reference/arrays.dtypes.rst
@@ -537,6 +537,13 @@ Attributes providing additional information:
    dtype.alignment
    dtype.base
 
+Metadata attached by the user:
+
+.. autosummary::
+   :toctree: generated/
+
+    dtype.metadata
+
 
 Methods
 -------
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
index c3b4374f4..e32b32fbd 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -5491,6 +5491,39 @@ add_newdoc('numpy.core.multiarray', 'dtype', ('kind',
 
     """))
 
+add_newdoc('numpy.core.multiarray', 'dtype', ('metadata',
+    """
+    Either ``None`` or a readonly dictionary of metadata (mappingproxy).
+
+    The metadata field can be set using any dictionary at data-type
+    creation. Note that whether or not operations on arrays with metadata
+    attached to their datatypes is currently not well defined and should
+    not be relied on.
+
+    Examples
+    --------
+
+    >>> dt = np.dtype(float, metadata={"key": "value"})
+    >>> dt.metadata["key"]
+    'value'
+    >>> arr = np.array([1, 2, 3], dtype=dt)
+    >>> arr.dtype.metadata
+    mappingproxy({'key': 'value'})
+
+    Some operations may preserve metadata (identical data types):
+
+    >>> (arr + arr).dtype.metadata
+    mappingproxy({'key': 'value'})
+
+    But for example, adding two arrays with different metadata does not
+    propagate either one:
+
+    >>> dt2 = np.dtype(float, metadata={"key2": "value2"})
+    >>> arr2 = np.array([3, 2, 1], dtype=dt2)
+    >>> (arr + arr2).dtype.metadata is None
+    True  # The metadata field is cleared so None is returned
+    """))
+
 add_newdoc('numpy.core.multiarray', 'dtype', ('name',
     """
     A bit-width name for this data-type.