diff --git a/arraycontext/context.py b/arraycontext/context.py index bf2b547b02777c4da76f0cb42660616427d5525e..cc157a4f8ea1068d0044abb92840b0fb777d0fea 100644 --- a/arraycontext/context.py +++ b/arraycontext/context.py @@ -327,6 +327,8 @@ class ArrayContext(ABC): metadata, return a version of *array* with the *tags* applied. *array* itself is not modified. + See :ref:`metadata` as well as application-specific metadata types. + .. versionadded:: 2021.2 """ @@ -338,6 +340,8 @@ class ArrayContext(ABC): metadata, return a version of *array* in which axis number *iaxis* has the *tags* applied. *array* itself is not modified. + See :ref:`metadata` as well as application-specific metadata types. + .. versionadded:: 2021.2 """ diff --git a/arraycontext/metadata.py b/arraycontext/metadata.py index 6291a86504563c64faf63be79467784ff65a6cfa..39934d6d487dea33407f4e0486ba10ac388ebeb7 100644 --- a/arraycontext/metadata.py +++ b/arraycontext/metadata.py @@ -1,3 +1,8 @@ +""" +.. autoclass:: NameHint +""" + + __copyright__ = """ Copyright (C) 2020-1 University of Illinois Board of Trustees """ @@ -23,10 +28,27 @@ THE SOFTWARE. """ import sys -from pytools.tag import Tag +from dataclasses import dataclass +from pytools.tag import Tag, UniqueTag from warnings import warn +@dataclass(frozen=True) +class NameHint(UniqueTag): + """A tag acting on arrays or array axes. Express that :attr:`name` is a + useful starting point in forming an identifier for the tagged object. + + .. attribute:: name + + A string. Must be a valid Python identifier. Not necessarily unique. + """ + name: str + + def __post_init__(self): + if not self.name.isidentifier(): + raise ValueError("'name' must be an identifier") + + # {{{ deprecation handling try: diff --git a/doc/other.rst b/doc/other.rst index bc1998d74b6224a8ee0f7bdb5f44a44c2126d485..53f0ab835011130ecfc331ae3d07f08de1767d85 100644 --- a/doc/other.rst +++ b/doc/other.rst @@ -1,6 +1,13 @@ Other functionality =================== +.. _metadata: + +Metadata ("tags") for Arrays and Array Axes +------------------------------------------- + +.. automodule:: arraycontext.metadata + :class:`~arraycontext.ArrayContext`-generating fixture for :mod:`pytest` ------------------------------------------------------------------------