pipeline: implement and document restrictions on pipeline names

Author: mdekstrand

docs/guide/pipeline.rst

@@ -108,8 +108,8 @@ These are arranged in a directed acyclic graph, consisting of:
   components and how to provide each component with the inputs it requires; see
   :ref:`pipeline-connections` for details.
 
-Each node has a name that can be used to look up the node with
-:meth:`Pipeline.node` (or :meth:`PipelineBuilder.node`) and appears in
+Each node has a :ref:`name <pipeline-names>` that can be used to look up the
+node with :meth:`Pipeline.node` (or :meth:`PipelineBuilder.node`) and appears in
 serialization and logging situations. Names must be unique within a pipeline.
 
 .. _pipeline-connections:
@@ -244,6 +244,12 @@ These component names replace the task-specific interfaces in pre-2025 LensKit;
 a ``Recommender`` is now just a pipeline with ``recommender`` and/or ``ranker``
 components.
 
+.. note:: Limits on Names
+
+    Component names must consist of alphanumeric characters and the symbols
+    ``_-.@%!*?``, and may not begin with ``_``. Names beginning with ``_`` are
+    reserved for LensKit internal use.
+
 .. _pipeline-serialization:
 
 Pipeline Serialization

src/lenskit/pipeline/_builder.py

@@ -38,7 +38,7 @@
     fallback_on_none,
     is_component_class,
 )
-from .config import PipelineConfig, PipelineHook
+from .config import PipelineConfig, PipelineHook, check_name
 from .nodes import (
     ComponentConstructorNode,
     ComponentInstanceNode,
@@ -208,6 +208,7 @@ def create_input[T](self, name: str, *types: type[T] | UnionType | None) -> Node
             ValueError:
                 a node with the specified ``name`` already exists.
         """
+        check_name(name, what="input")
         self._check_available_name(name)
 
         rts: set[type[T | None]] = set()
@@ -234,6 +235,8 @@ def literal[T](self, value: T, *, name: str | None = None) -> LiteralNode[T]:
         if name is None:
             lit = config.PipelineLiteral.represent(value)
             name = str(uuid5(NAMESPACE_LITERAL_DATA, lit.model_dump_json()))
+        else:
+            check_name(name)
         node = LiteralNode(name, value, types=set([type(value)]))
         self._nodes[name] = node
         return node
@@ -300,6 +303,7 @@ def alias(self, alias: str, node: Node[Any] | str, *, replace: bool = False) ->
             ValueError:
                 if the alias is already used as an alias or node name.
         """
+        check_name(alias, what="alias")
         node = self.node(node)
         if replace:
             if alias in self._nodes:
@@ -355,6 +359,7 @@ def add_component[CFG, T](
         """
         from lenskit.training import Trainable
 
+        check_name(name, what="component")
         self._check_available_name(name)
 
         if hasattr(comp, "train"):
@@ -417,6 +422,7 @@ def replace_component[CFG, T](
         if isinstance(name, Node):
             name = name.name
 
+        check_name(name, what="component")
         node = ComponentNode[T].create(name, comp, config)
         self._nodes[name] = node
 

src/lenskit/pipeline/config.py

@@ -13,6 +13,7 @@
 
 import base64
 import pickle
+import re
 import warnings
 from collections import OrderedDict
 from hashlib import sha256
@@ -31,6 +32,25 @@
 from .components import Component
 from .nodes import ComponentConstructorNode, ComponentInstanceNode, ComponentNode, InputNode
 
+VALID_NAME = re.compile(r"^[\w.@%!*?-]+$", re.UNICODE)
+
+
+def check_name(name: str, *, what: str = "node", allow_reserved: bool = False):
+    """
+    Check that a name is valid.
+
+    Raises:
+        ValueError:
+            If the specified name is not valid.
+    """
+
+    if not VALID_NAME.match(name):
+        raise ValueError(f"invalid {what} name “{name}”")
+    if name.startswith("_") and not allow_reserved:
+        raise ValueError(
+            f"invalid {what} name “{name}”, names beginning with “_” are reserved by LensKit"
+        )
+
 
 class PipelineHook(BaseModel):
     """

tests/pipeline/test_pipeline.py

@@ -101,6 +101,40 @@ def test_alias():
         pipe.create_input("person", bytes)
 
 
+def test_invalid_input_name():
+    pipe = PipelineBuilder()
+
+    with raises(ValueError, match=r"invalid input name.*reserved"):
+        pipe.create_input("_user", int, str)
+
+    with raises(ValueError, match=r"invalid input name"):
+        pipe.create_input("user 7", int, str)
+
+
+def test_invalid_component_name():
+    pipe = PipelineBuilder()
+    user = pipe.create_input("user", int, str)
+
+    def incr(x: int) -> int:
+        return x + 1
+
+    with raises(ValueError, match=r"invalid component name.*reserved"):
+        pipe.add_component("_incr", incr, x=user)
+
+
+def test_invalid_node_alias():
+    pipe = PipelineBuilder()
+    user = pipe.create_input("user", int, str)
+
+    def incr(x: int) -> int:
+        return x + 1
+
+    inode = pipe.add_component("incr", incr, x=user)
+
+    with raises(ValueError, match=r"invalid alias.*reserved"):
+        pipe.alias("_incr", inode)
+
+
 def test_component_type():
     pipe = PipelineBuilder()
     msg = pipe.create_input("msg", str)