Add Range and Array modeling types

[ktbarrett]

Follow on to #2485. xref #2059. Adds a Range and Array type.

The Range type is much like Python's range type, but has an inclusive right bound like is seen in both Verilog and VHDL. It support's VHDL's to and downto directions, Verilog's automatic directionality by not specifying a direction, and VHDL's null ranges.

The Array type is a heterogenous fixed-length sequence type. It uses an initial value or a range to determine it's size at construction and it's size is fixed. It supports must of the same operations as a list that don't mutate the length. Uses a Range to describe the indexing scheme, which is arbitrary, like is seen in both Verilog and VHDL. Some indexing and slicing behavior had to change compared to a list to make something that behaved intuitively.

[ktbarrett]

I keep forgetting that cache and cached_property aren't available until 3.8. For the current use of cached_property, I could just alias property and those using less than 3.8 will suffer from slightly lower performance? Or I can just switch to using both the lru_cache and property decorators together.

[ktbarrett]

Using lru_cache and property together to mock cached_property only works if the object is hashable, which Arrays are not since they are mutable. So I went back to the original idea of just aliasing property to cached_property if it isn't available. For now people will have to deal with the performance drop (it shouldn't be noticeable anyways).

[codecov]

Codecov Report

Merging #2510 (7a18d2c) into master (c065ccb) will increase coverage by 0.81%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #2510      +/-   ##
==========================================
+ Coverage   74.46%   75.28%   +0.81%     
==========================================
  Files          38       40       +2     
  Lines        6537     6752     +215     
  Branches      560      596      +36     
==========================================
+ Hits         4868     5083     +215     
  Misses       1485     1485              
  Partials      184      184              

Impacted Files	Coverage Δ
cocotb/types/__init__.py	100.00% <100.00%> (ø)
cocotb/types/array.py	100.00% <100.00%> (ø)
cocotb/types/range.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c065ccb...7a18d2c. Read the comment docs.

[cmarqu]

We should also add cocotb/types/array.py and cocotb/types/range.py after

cocotb/setup.cfg

Line 35 in 1536fd1

cocotb/binary.py

so that the doctests are also run.

[ktbarrett]

@cmarqu if you think there are any other exception that could improve, please comment.

I need to refactor the __init__ on Array slightly so I can better check that range argument, if specified, is in fact a Range since I depend on it's implementation in the body.

[ktbarrett]

Resolved issue where constructor would not check if range value was a Range. The new implementation allows easy extension of type/value checking, etc.

[ktbarrett]

Not entirely sure if the last set of changes is welcome, but it should make extending Array for LogicArray simpler. I already wanted to encapsulate range construction, since it was done in more than one place and needed to do type checking. We could even extend _construct_range to handle an iterable that can be splatted into a Range constructor to be able to support Array(range=(1, 'to', 8)) without having to explicitly construct the value into a Range first, however, that might be of dubious merit.

[ktbarrett]

I think that's enough last minute cleanup @cocotb/maintainers. If there are no more comments in a couple days, I will merge.