Add src parameter to WireVector, Output, and Register

[timsherwood]

Summary

• Adds an optional src parameter to WireVector, Output, and Register constructors, allowing wire connections at construction time.
• For WireVector and Output, src=x is equivalent to wire <<= x.
• For Register, src=x is equivalent to reg.next <<= x.

Example

a = pyrtl.Input(name="a", bitwidth=8)
b = pyrtl.Input(name="b", bitwidth=8)
begin = pyrtl.Input(name="begin", bitwidth=1)

x, done = gcd(a, b, begin)

x = pyrtl.Output(name="x", src=x)
done = pyrtl.Output(name="done", src=done)

Notes

• Input and Const do not accept src (raises TypeError).
• Self-referencing register patterns like reg = Register(src=reg + 1) are not possible; use reg.next <<= reg + 1 for those cases.
• The block parameter is moved to the last position in all affected constructors for consistency.

Test plan

• All 1382 existing tests pass
• 11 new tests covering WireVector, Output, and Register src usage, bitwidth inference, coercion, and negative cases

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.8%. Comparing base (d0021d4) to head (5c9666c).

Additional details and impacted files

@@              Coverage Diff              @@
##           development    #512     +/-   ##
=============================================
+ Coverage         93.8%   93.8%   +0.1%     
=============================================
  Files               30      30             
  Lines             7174    7178      +4     
=============================================
+ Hits              6724    6729      +5     
+ Misses             450     449      -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[fdxmw]

Thanks for putting this together! Some questions/comments:

• I think it's better to leave the block argument where it was, currently this change is not backwards-compatible. Users depending on positional argument order will likely have problems after this change.
• What do you think about renaming src to source? IMO three vowels are a small cost for dictionary-safety :)
• What about naming Register's constructor argument next, to match Register.next?
• What do you think about making these new constructor arguments keyword-only? IMO that would improve readability, I think it's quite hard to figure out what this code does, without consulting the documentation:

  wire = WireVector(2, "three", 3)

• Along those lines, this change makes it easier to write inefficient code, like the example above, which should just be Const(3, name="three"), rather than a Const connected to a WireVector. Here's another:

  wire = WireVector(src=other)

  It is a little annoying that we can't skip construction of these useless objects. Should we emit a warning when we can detect cases like these?

[timsherwood]

I think it's better to leave the block argument where it was, currently this change is not backwards-compatible. Users depending on positional argument order will likely have problems after this change.

Agreed, no need to break backwards compatability

What do you think about renaming src to source? IMO three vowels are a small cost for dictionary-safety :)

That is fine with me, I was trying to use the naming we already had internally for source, but don't feel strongly. Maybe it makes it more clear they are different to have it be "source".

What do you think about making these new constructor arguments keyword-only? IMO that would improve readability, I think it's quite hard to figure out what this code does, without consulting the documentation:
wire = WireVector(2, "three", 3)

Agreed, keyword only is fine with me

Along those lines, this change makes it easier to write inefficient code, like the example above, which should just be Const(3, name="three"), rather than a Const connected to a WireVector. Here's another:
wire = WireVector(src=other)
It is a little annoying that we can't skip construction of these useless objects. Should we emit a warning when we can detect cases like these?

The const one seems funny, but but it is longer than doing it the "right" way, and catching that style difference actively could make things more confusing because now you have to enumerate which cases are warned in yet another place and the constant might be coming from another variable. Because as_wires is pretty clearly the primary place where coercion of types is handled in pyrtl, I think we can be most clear and consistent in saying that anything that can be as_wireded is always good to go. It could be something you consider checking with a pyrtl linter rule though? (just an idea)

With regard to the wire = WireVector(src=other), I would argue we should not pre-optimize because sometime you just want to, like make a wire, man. If I explicitly call a constructor I think the least surprising behavior is to construct the object requested and it is already caught by optimization.

What about naming Register's constructor argument next, to match Register.next?

Originally I liked the uniformity with the other constructors in case I ever want to call them in abstract, but I certainly see how would be confusing for it to be source... yes I think you are right it should be next.