[ILibrary] update docs for add()

masque/library.py

@@ -923,8 +923,8 @@ class ILibrary(ILibraryView, MutableMapping[str, 'Pattern'], metaclass=ABCMeta):
                 (default).
 
         Returns:
-            A mapping of `{old_name: new_name}` for all `old_name`s in `other`. Unchanged
-            names map to themselves.
+            A mapping of `{old_name: new_name}` for all names in `other` which were
+            renamed while being added. Unchanged names are omitted.
 
         Raises:
             `LibraryError` if a duplicate name is encountered even after applying `rename_theirs()`.

masque/test/test_library.py

@@ -280,6 +280,18 @@ def test_library_add_no_duplicates_respects_mutate_other_false() -> None:
     assert tuple(src_pat.ports["A"].offset) == (0.0, 0.0)
 
 
+def test_library_add_returns_only_renamed_entries() -> None:
+    lib = Library({"a": Pattern(), "_shape": Pattern()})
+
+    assert lib.add({"b": Pattern(), "c": Pattern()}, mutate_other=False) == {}
+
+    rename_map = lib.add({"_shape": Pattern(), "keep": Pattern()}, mutate_other=False)
+
+    assert set(rename_map) == {"_shape"}
+    assert rename_map["_shape"] != "_shape"
+    assert "keep" not in rename_map
+
+
 def test_library_subtree() -> None:
     lib = Library()
     lib["a"] = Pattern()