diff options
| -rw-r--r-- | doc/source/reference/arrays.dtypes.rst | 7 | ||||
| -rw-r--r-- | numpy/core/_add_newdocs.py | 33 |
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. |