refpath module

Reference Paths

When inspecting a JITX design tree, for example using visit(), the path to the element is returned as a RefPath object. This is construced as a tuple of strings, integers, and Item objects, which represent attribute access, list index access, and mapping lookups, respectively, describing how to get from the reference object to the element being visited.

RefPaths are normally only used for more advanced introspection use-cases and debugging, and in most cases, a designer would not need to interact with them directly.

>>> class A(Circuit):
...     power = Power()
...     awkward = {"a": [Port()]}

>>> circuit = A()
>>> for trace, elem in visit(circuit, Port):
...     print(trace.path, "--", repr(elem))
power -- RefPath(("power"))
power.Vp -- RefPath(("power", "Vp"))
power.Vn -- RefPath(("power", "Vn"))
awkward["a"][0] -- RefPath(("awkward", Item("a"), 0))

class Item(value)

Bases: object

A RefPath Item represents a dictionary or mapping lookup, as opposed to an attribute lookup or list index, which are represented by strings and integers, respectively.

Parameters:

value (int | str)

class RefPath(steps=())

Bases: Sequence[str | int | Item]

The path to an element in the design tree. It’s made up of a tuple of strings, integers, and Item objects, which represent attribute access, list index access, and mapping lookups, respectively, for traversing a path through a design tree.

Supports some arithmetic operations:

• path1 + tuple : Concatenate path with a tuple of steps.

• path1 - path2 : Return a new RefPath that is the path of path1 relative to path2. If path2 is not a prefix of path1, path1 is returned. If paths are identical or path1 is a parent, returns empty path. If paths are diverging, the result is undefined.

Parameters:

steps (Iterable[str | int | Item])

attribute()

Return a new RefPath that is the path to the last attribute in the path, effectively stripping off trailing index and mapping lookups.

Return type:

RefPath