Type cardinality-one relationships as an assignable descriptor (#1064)

[FragmentedPacket]

Fixes #1064. Stacked on #1063 (base branch is ihs-relatednode-generic-1063); retarget once #1063 / #763 merge.

Problem

Generated cardinality-one relationships are typed read-only as RelatedNode, but the documented way to set a relationship is node.rel = "<id>" or node.rel = peer_node. Under mypy/ty (since py.typed in 1.19.0) every such assignment fails with Incompatible types in assignment ... variable has type "RelatedNode" (assignment).

Change

• Adds a typing-only descriptor RelationshipAttribute / RelationshipAttributeSync (in infrahub_sdk/node/related_node.py). It reads back as RelatedNode[Peer] (so .peer keeps the peer type from bug: RelatedNode.peer is typed InfrahubNode, losing the peer type during relationship traversal #1063) and accepts assignment of str | list[str] | Peer | None, mirroring the runtime InfrahubNode.__setattr__, which wraps the assigned value in a RelatedNode.
• infrahubctl protocols now emits cardinality-one relationships as RelationshipAttribute[Peer] (cardinality-many stays RelationshipManager[Peer]).
• The descriptor only appears in generated protocols and is never instantiated at runtime — purely to give node.rel separate read/assign types.

Verification

• SDK: mypy (125 files) ✅, ty ✅, ruff ✅, generator test updated, 258 node/relationship/protocol unit tests ✅.
• Against the downstream AI/DC repo: the relationship-assignment errors (node.rel = "<id>" / = peer) drop to 0. Remaining downstream errors are unrelated (untyped client.create(kind="...") results that need a cast, and an Optional not handled) — not relationship assignments.

Depends on

#1063 (generic RelatedNode) — RelationshipAttribute.__get__ returns RelatedNode[Peer].

🤖 Generated with Claude Code

---

Summary by cubic

Make cardinality-one relationships assignable in type-checked code by adding a typing-only RelationshipAttribute[...] descriptor. Reads still return RelatedNode[Peer], so .peer keeps its type and node.rel = "<id>" or a peer node now type-checks.

• Bug Fixes

  • Added RelationshipAttribute/RelationshipAttributeSync that accept str | list[str] | Peer | None and read as RelatedNode[Peer]; typing-only, never used at runtime.
  • Protocols now emit RelationshipAttribute[Peer] for cardinality-one (including parent); many stays RelationshipManager[Peer].
  • Exported via infrahub_sdk.node; removes mypy/ty assignment errors without changing runtime behavior.

• Migration

  • Regenerate protocols with infrahubctl protocols to pick up the new typing; existing generated files won’t update automatically.

^{Written for commit c5887f0. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	c5887f0
Status:	✅  Deploy successful!
Preview URL:	https://050bdb6d.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://ihs-relationship-assignment.infrahub-sdk-python.pages.dev

View logs

[codecov]

Codecov Report

❌ Patch coverage is 76.47059% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
infrahub_sdk/node/related_node.py	73.33%	0 Missing and 4 partials ⚠️

@@             Coverage Diff             @@
##           develop    #1067      +/-   ##
===========================================
- Coverage    82.26%   81.82%   -0.45%     
===========================================
  Files          135      135              
  Lines        11956    11684     -272     
  Branches      1785     1766      -19     
===========================================
- Hits          9836     9560     -276     
- Misses        1573     1575       +2     
- Partials       547      549       +2     

Flag	Coverage Δ
integration-tests	41.56% <0.00%> (-0.96%)	⬇️
python-3.10	55.19% <5.88%> (-0.80%)	⬇️
python-3.11	55.19% <5.88%> (-0.82%)	⬇️
python-3.12	55.19% <5.88%> (-0.82%)	⬇️
python-3.13	55.19% <5.88%> (-0.80%)	⬇️
python-3.14	55.19% <5.88%> (-0.80%)	⬇️
python-filler-3.12	22.42% <70.58%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/node/__init__.py	100.00% <100.00%> (ø)
infrahub_sdk/protocols_generator/generator.py	95.12% <100.00%> (ø)
infrahub_sdk/node/related_node.py	91.00% <73.33%> (-1.57%)	⬇️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cubic-dev-ai]

No issues found across 6 files

_{Re-trigger cubic}

[ogenstad]

LGTM, this will be a great improvement! One thing I think is missing here is that the protocols will need to be recreated once this is in place and we should highlight this in the changelog newsfragment so that it's clear that it won't just work out of the box.