inspect module#

JITX Object Introspection#

The JITX object introspection is based on traversing the design tree using the visit() function. Other utility and helper functions are also provided but they all rely on the visit() function to do the traversal.

visit(root, types, /, through=None, *, path=RefPath(()), transform=Transform((0, 0), 0, (1, 1)), opaque=None, refs=False, filter=None)[source]#

Find elements in an object structure. Objects of the specified types will be returned, traversing down through the object tree structure. If through is specified the traversal will only pass through those when looking for matching elements, otherwise all JITX structural elements will be traversed.

Parameters:

  • root – The root object to start traversing

  • types (type | tuple[type, ...] | Union) – A type, tuple of types, or union of types to find

  • through (tuple[type, ...] | Union | None) – Optional argument to limit which objects to recurse through. If undefined, only Structural elements will be visited.

  • path (RefPath) – Optional starting path

  • transform (Transform | None) – Optional starting transform, if unset will default to the identity transform. Set to None to suppress computing transforms.

  • opaque (tuple[type, ...] | Union | None) – Optional argument to limit which objects to recurse through. If unspecified, or None, contents of Ref elements will be skipped. To recurse through all structural elements, including Ref elements, set this to an empty tuple.

  • filter (Callable[[Any], bool] | None) – Optional filter function to apply to the elements. Only elements that pass the filter will be returned.

  • refs (bool)

Yields:

Pairs of Trace to the element, and the element itself.

class Trace(path, transform, parent=None, trace=None)[source]#

The Trace inspection object represents a path through the design tree to reach a particular element, it is returned by the visit() function.

Parameters:
path: RefPath#

The path to the element.

transform: Transform | None#

The accumulated transform leading up to this element, or None if one could not be determined. Note that the element’s own transform, if it has one, is not included in this transform.

parent: Any = None#

The parent structural element.

trace: Trace | None = None#

The trace to the parent object, if any.

decompose(ob, types, /, *, refs=False, filter=None)[source]#

Collect fields of a type or types into a sequence that can be used for deconstruction assignment. The elements are all semi-shallow children, traversing lists and dicts, but not other structural elements. Note that objects of subtypes can be returned as well.

>>> class A:
...     other = "field"
...     ports = [Port(), DiffPair()]
...     another = GPIO()
>>> p1, p2, p3 = decompose(A(), Port)
>>> type(p1) is Port and type(p2) is DiffPair and type(p3) is GPIO
True
Parameters:
extract(ob, types, /, through=None, *, opaque=None, refs=False, filter=None)[source]#

Recursively traverse all objects in the tree and yield all objects of a particular type or types. This is similar to visit(), but does not generate the meta information associated with each returned element.

>>> def component_ports(comp:Component) -> list[Port]:
...     return list(extract(comp, Port))
Parameters: