Provide automatic sanitization of field names in namedview (#19196)

Related to #19164 -- MbP uses names which are not immediately useable as `namedview` fields.

After this PR (and now that #19174 has landed), we can do e.g.
```
PositionView = namedview("PositionView", plant.GetPositionNames())
StateView = namedview("StateView", plant.GetStateNames())
```
and all of the MbP introspection variants.

Co-Authored-By: Jeremy Nimmer <jeremy.nimmer@tri.global>

Author: RussTedrake

bindings/pydrake/common/containers.py

@@ -1,6 +1,7 @@
 """Provides extensions for containers of Drake-related objects."""
 
 import numpy as np
+import re
 
 
 class _EqualityProxyBase:
@@ -71,7 +72,6 @@ class EqualToDict(_DictKeyWrap):
     `lhs.EqualTo(rhs)`.
     """
     def __init__(self, *args, **kwargs):
-
         class Proxy(_EqualityProxyBase):
             def __eq__(self, other):
                 T = type(self.value)
@@ -118,8 +118,7 @@ def __setattr__(self, name, value):
         if not hasattr(self, name):
             raise AttributeError(
                 "Cannot add attributes! The fields in this named view are"
-                f"{self.get_fields()}, but you tried to set '{name}'."
-            )
+                f"{self.get_fields()}, but you tried to set '{name}'.")
         object.__setattr__(self, name, value)
 
     def __len__(self):
@@ -142,22 +141,41 @@ def __repr__(self):
     @staticmethod
     def _item_property(i):
         # Maps an item (at a given index) to a property.
-        return property(
-            fget=lambda self: self[i],
-            fset=lambda self, value: self.__setitem__(i, value))
+        return property(fget=lambda self: self[i],
+                        fset=lambda self, value: self.__setitem__(i, value))
 
     @classmethod
     def Zero(cls):
         """Constructs a view onto values set to all zeros."""
-        return cls([0]*len(cls._fields))
+        return cls([0] * len(cls._fields))
+
 
+def _sanitize_field_name(name: str):
+    result = name
+    # Ensure the first character is a valid opener (e.g., no numbers allowed).
+    if not result[0].isidentifier():
+        result = "_" + result
+    # Ensure that each additional character is valid in turn, avoiding the
+    # special case for opening characters by prepending "_" during the check.
+    for i in range(1, len(result)):
+        if not ("_" + result[i]).isidentifier():
+            result = result[:i] + "_" + result[i+1:]
+    result = re.sub("__+", "_", result)
+    assert result.isidentifier(), f"Sanitization failed on {name} => {result}"
+    return result
 
-def namedview(name, fields):
+
+def namedview(name, fields, *, sanitize_field_names=True):
     """
     Creates a class that is a named view with given ``fields``. When the class
     is instantiated, it must be given the object that it will be a proxy for.
     Similar to ``namedtuple``.
 
+    If ``sanitize_field_names`` is True (the default), then any characters in
+    ``fields`` which are not valid in Python identifiers will be automatically
+    replaced with `_`. Leading numbers will have `_` inserted, and duplicate
+    `_` will be replaced by a single `_`.
+
     Example:
         ::
 
@@ -186,7 +204,10 @@ def namedview(name, fields):
 
     For more details, see ``NamedViewBase``.
     """
-    base_cls = (NamedViewBase,)
+    base_cls = (NamedViewBase, )
+    if sanitize_field_names:
+        fields = [_sanitize_field_name(f) for f in fields]
+    assert len(set(fields)) == len(fields), "Field names must be unique"
     type_dict = dict(_fields=tuple(fields))
     for i, field in enumerate(fields):
         type_dict[field] = NamedViewBase._item_property(i)

bindings/pydrake/common/test/containers_test.py

@@ -130,3 +130,25 @@ def test_Zero(self):
         self.assertEqual(len(view), 2)
         self.assertEqual(view.a, 0)
         self.assertEqual(view.b, 0)
+
+    def test_name_sanitation(self):
+        MyView = namedview("MyView",
+                           ["$world_base", "iiwa::iiwa", "no spaces", "2vär"])
+        self.assertEqual(MyView.get_fields(),
+                         ("_world_base", "iiwa_iiwa", "no_spaces", "_2vär"))
+        view = MyView.Zero()
+        view._world_base = 3
+        view.iiwa_iiwa = 4
+        view.no_spaces = 5
+        view._2vär = 6
+        np.testing.assert_equal(view[:], [3, 4, 5, 6])
+
+        MyView = namedview("MyView", ["$world_base", "iiwa::iiwa"],
+                           sanitize_field_names=False)
+        self.assertEqual(MyView.get_fields(), ("$world_base", "iiwa::iiwa"))
+
+    def test_uniqueness(self):
+        with self.assertRaisesRegex(AssertionError, ".*must be unique.*"):
+            namedview("MyView", ['a', 'a'])
+        with self.assertRaisesRegex(AssertionError, ".*must be unique.*"):
+            namedview("MyView", ['a_a', 'a__a'])