From 1f7fff83ff5f05edcb6f570330eb2b38d5c8d595 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Tue, 7 Jun 2022 19:40:02 -0500
Subject: [PATCH] Add NameHint tag

---
 arraycontext/context.py  |  4 ++++
 arraycontext/metadata.py | 24 +++++++++++++++++++++++-
 doc/other.rst            |  7 +++++++
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/arraycontext/context.py b/arraycontext/context.py
index bf2b547..cc157a4 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 6291a86..39934d6 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 bc1998d..53f0ab8 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`
 ------------------------------------------------------------------------
 
-- 
GitLab