🔧 Store NeedPartData.backlinks as NeedLink instead of str (useblocks#1679)

Change `NeedPartData.backlinks` from `dict[str, list[str]]` to
`dict[str, list[NeedLink]]`, aligning it with how `NeedItem` already
stores its backlinks internally.

Previously, part backlinks were stored as raw strings and converted to
`NeedLink` on read (e.g. in `NeedPartItem.get_backlinks(as_str=False)`).
Now they are stored as `NeedLink` from the start, avoiding redundant
re-parsing and making the internal representation consistent across
needs and parts.

**Changes:**
- `NeedPartData.backlinks` type: `dict[str, list[str]]` → `dict[str,
list[NeedLink]]`
- `resolve_links()`: append `NeedLink(id=key)` instead of raw `str` to
part backlinks
- `_recompute()`, `NeedPartItem.__init__`: serialize via
`to_filter_string()` for dict-like access and JSON output (unchanged
external behavior)
- `NeedPartItem.get_backlinks`/`iter_backlinks_items`: return stored
`NeedLink` directly instead of re-parsing from strings
- `_validate_part`: validate `NeedLink` instances instead of `str`

No change in external behavior — dict-like access
(`item["links_back"]`), JSON serialization, and all public APIs continue
to return the same values.

Author: chrisjsewell

sphinx_needs/directives/need.py

@@ -479,7 +479,7 @@ def resolve_links(
                         if linked_part := linked_need.get_part(need_link.part):
                             if link_type not in linked_part.backlinks:
                                 linked_part.backlinks[link_type] = []
-                            linked_part.backlinks[link_type].append(key)
+                            linked_part.backlinks[link_type].append(NeedLink(id=key))
                         else:
                             dead_links.append((link_type, need_link))
                 else:

sphinx_needs/need_item.py

@@ -183,7 +183,7 @@ class NeedPartData:
 
     id: str
     content: str
-    backlinks: dict[str, list[str]] = field(default_factory=dict)
+    backlinks: dict[str, list[NeedLink]] = field(default_factory=dict)
 
 
 @dataclass(slots=True, frozen=True, kw_only=True)
@@ -423,7 +423,11 @@ def _recompute(self) -> None:
                 "id": p.id,
                 "content": p.content,
                 **(
-                    {f"{k}_back": v for k, v in p.backlinks.items() if v}  # type: ignore[typeddict-item]
+                    {
+                        f"{k}_back": [li.to_filter_string() for li in v]
+                        for k, v in p.backlinks.items()
+                        if v
+                    }  # type: ignore[typeddict-item]
                     if p.backlinks is not None
                     else {}
                 ),
@@ -916,11 +920,11 @@ def _validate_part(self, part: NeedPartData) -> None:
         if not isinstance(part.backlinks, dict) or any(
             not isinstance(k, str)
             or not isinstance(v, list)
-            or any(not isinstance(i, str) for i in v)
+            or any(not isinstance(i, NeedLink) for i in v)
             for k, v in part.backlinks.items()
         ):
             raise ValueError(
-                f"Part {part.id!r} backlinks must be a dictionary of lists of strings."
+                f"Part {part.id!r} backlinks must be a dictionary of lists of NeedLink instances."
             )
         if unknown_part_links := (set(part.backlinks) - set(self._links)):
             raise ValueError(
@@ -1020,7 +1024,7 @@ def __init__(self, need: NeedItem, part_id: str) -> None:
             **{
                 f"{name}_back": []
                 if part.backlinks is None or not (blinks := part.backlinks.get(name))
-                else blinks
+                else [li.to_filter_string() for li in blinks]
                 for name in need.iter_links_keys()
             },
         }
@@ -1270,7 +1274,7 @@ def get_backlinks(
             return self[f"{link_type}_back"]  # type: ignore[no-any-return]
         part = self._need.get_part(self.part_id)
         assert part is not None
-        return [NeedLink.from_string(v) for v in part.backlinks.get(link_type, [])]
+        return part.backlinks.get(link_type, [])
 
     @overload
     def iter_backlinks_items(
@@ -1295,5 +1299,5 @@ def iter_backlinks_items(
                 assert part is not None
                 yield (
                     key,
-                    [NeedLink.from_string(v) for v in part.backlinks.get(key, [])],
+                    part.backlinks.get(key, []),
                 )

tests/test_need_item_api.py

@@ -366,7 +366,9 @@ def test_need_part_item(snapshot):
     item = NeedItem(
         core=core(),
         parts=(
-            NeedPartData(id="part1", content="Part 1", backlinks={"links": ["ref3"]}),
+            NeedPartData(
+                id="part1", content="Part 1", backlinks={"links": [NeedLink(id="ref3")]}
+            ),
         ),
         content=content("Need 1"),
         extras={