netlist_carpentry.core.netlist_elements.element_path

Module for handling of hierarchical paths inside a given circuit.

Classes:

• ElementPath –

  Represents a path to a specific element in a netlist.

• ModulePath –

  Represents a path to a module.

• InstancePath –

  Represents a hierarchical path to an instance.

• PortPath –

  Represents a hierarchical path to a port.

• PortSegmentPath –

  Represents a hierarchical path to a port segment.

• WirePath –

  Represents a hierarchical path to a wire.

• WireSegmentPath –

  Represents a hierarchical path to a wire segment.

ElementPath

Bases: BaseModel

Represents a path to a specific element in a netlist.

Attributes:

• type (ElementsEnum) –

  The type of the element.

• raw (str) –

  The raw path string representing the element location.

• separator (str) –

  The separator used in the path. Defaults to '.'.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path)
"PortPath(top_module.sub_module.port1)"

Example 2

>>> element_path = InstancePath(raw="top_module/sub_module/instance1", separator='/')
>>> print(element_path)
"InstancePath(top_module/sub_module/instance1)"

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

type property

type: EType

The type of the element.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

parent property

parent: ElementPath

Retrieves the parent element path of this element.

The parent is determined by removing the last component from the path. The type of the parent is inferred from the type mapping, specifically using the second-to-last element's mapped type.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the parent element.

Raises:

• IndexError –

  If this path does not have a parent (i.e., it has only one component or is empty).

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

ModulePath

Bases: ElementPath

Represents a path to a module.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.MODULE for instances of ModulePath.

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• parent (ElementPath) –

  Retrieves the parent element path of this element.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.MODULE for instances of ModulePath.

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

parent property

parent: ElementPath

Retrieves the parent element path of this element.

The parent is determined by removing the last component from the path. The type of the parent is inferred from the type mapping, specifically using the second-to-last element's mapped type.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the parent element.

Raises:

• IndexError –

  If this path does not have a parent (i.e., it has only one component or is empty).

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

InstancePath

Bases: ElementPath

Represents a hierarchical path to an instance.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.INSTANCE for instances of InstancePath.

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.INSTANCE for instances of InstancePath.

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

PortPath

Bases: ElementPath

Represents a hierarchical path to a port.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.PORT for instances of PortPath.

• is_instance_port (bool) –

  Whether this port path points to an instance port (then True) or a module port (then False).

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.PORT for instances of PortPath.

is_instance_port property

is_instance_port: bool

Whether this port path points to an instance port (then True) or a module port (then False).

Checks whether the parent path of this path is an instance path (in which case this port is an instance port) or not (in which case it is a module port).

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

PortSegmentPath

Bases: ElementPath

Represents a hierarchical path to a port segment.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.PORT_SEGMENT for instances of PortSegmentPath.

• is_instance_port (bool) –

  Whether this port segment path points to an instance port segment (then True) or a module port segment (then False).

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.PORT_SEGMENT for instances of PortSegmentPath.

is_instance_port property

is_instance_port: bool

Whether this port segment path points to an instance port segment (then True) or a module port segment (then False).

Checks whether the parent path of this path is an instance port path (in which case this port segment belongs to an instance port) or not (in which case it belongs to a module port).

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

WirePath

Bases: ElementPath

Represents a hierarchical path to a wire.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.WIRE for instances of WirePath.

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.WIRE for instances of WirePath.

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.

WireSegmentPath

Bases: ElementPath

Represents a hierarchical path to a wire segment.

Methods:

• nth_parent –

  Retrieves the nth parent of this element path.

• has_parent –

  Whether the nth parent of this element path exists.

• get –

  Returns the element at the specified index in the path.

• get_subseq –

  Returns a sublist of elements from the raw path.

• is_type –

  Returns whether the type of this path matches the given element type.

Attributes:

• type (EType) –

  The type of the element, which is EType.WIRE_SEGMENT for instances of WireSegmentPath.

• raw (str) –

  The raw path string representing the element location.

• sep (str) –

  The separator used in the path. Defaults to '.'.

• parts (List[str]) –

  Splits the raw path into a list of components via the specified separator.

• type_mapping (List[tuple[str, EType]]) –

  Calculates a mapping of path components to element types.

• name (str) –

  The name of the element, i.e. the key of this element path.

• hierarchy_level (int) –

  The hierarchy level of the element, i.e. the number of times the separator appears in the path.

• is_empty (bool) –

  Whether this path consists of no characters and thus represents an empty string.

type property

type: EType

The type of the element, which is EType.WIRE_SEGMENT for instances of WireSegmentPath.

raw instance-attribute

raw: str

The raw path string representing the element location.

sep class-attribute instance-attribute

sep: str = '.'

The separator used in the path. Defaults to '.'.

parts property

parts: List[str]

Splits the raw path into a list of components via the specified separator.

Returns:

• List[str] –

  List[str]: A list of strings representing the split path components.

type_mapping property

type_mapping: List[tuple[str, EType]]

Calculates a mapping of path components to element types.

This is a heuristic approach, assuming the first element is a module name and the last element is of the type of this path. Intermediate elements are mapped to instances (since they are most probably module instances) and/or to their superordinate types (e.g. the second-to-last element is presumably a port, if the last element in the path is a port segment).

Returns:

• List[tuple[str, EType]] –

  List[tuple[str, EType]]: A list of tuples, where each tuple contains

• List[tuple[str, EType]] –

  a path component and its presumably corresponding element type.

name property writable

name: str

The name of the element, i.e. the key of this element path.

hierarchy_level property

hierarchy_level: int

The hierarchy level of the element, i.e. the number of times the separator appears in the path.

For empty paths, the hierarchy level is -1.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.hierarchy_level)
2

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.hierarchy_level)
1

Example 3

>>> element_path = ElementPath(raw="")
>>> print(element_path.hierarchy_level)
-1

is_empty property

is_empty: bool

Whether this path consists of no characters and thus represents an empty string.

nth_parent

nth_parent(index: NonNegativeInt) -> ElementPath

Retrieves the nth parent of this element path.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - nth_parent(0) returns the same path ("module.instance.port") - nth_parent(1) returns the parent path ("module.instance") - nth_parent(2) returns the grandparent path ("module")

Parameters:

• index

  (NonNegativeInt) –

  The level of the parent to retrieve. 0 means self, 1 means immediate parent, etc.

Returns:

• ElementPath ( ElementPath ) –

  A new instance of the appropriate ElementPath subclass representing the nth parent element.

Raises:

• IndexError –

  If the requested parent level exceeds the hierarchy depth.

has_parent

has_parent(index: NonNegativeInt = 1) -> bool

Whether the nth parent of this element path exists.

The 0th parent is the element itself. For example, if this path represents "module.instance.port", then: - has_parent(0) will always return True - has_parent(1) returns True as well ("module.instance") - has_parent(2) returns True as well ("module") - has_parent(3) returns False (no hierarchy left)

Parameters:

• index

  (NonNegativeInt, default: 1 ) –

  The level of the parent to check. 0 means self, 1 means immediate parent, etc.

Returns:

• bool ( bool ) –

  True if the parent exists, False otherwise

get

get(index: int) -> str

Returns the element at the specified index in the path.

For an Elementpath some_path, some_path.get(i) is similar to some_path[i], except some_path[i] raises an IndexError exception for invalid indices, where some_path.get(i) returns an empty string.

Negative indices count from the end, with -1 being the last element (i.e. the target of this path). For wire or port segments, -1 is the segment itself, -2 is the wire or port the segment belongs to, and -3 is the instance or module to which the wire or port belongs.

Positive indices count from the start of the path, with 0 being the name of a module (e.g. the top-level module). Index 1 is thus an instance, port or wire within the top-level module. In case, the object at index 1 is an instance, index 2 could then be a port, wire or another instance. The latter two however are only available if the instance represents a submodule and not a primitive structure.

Example 1

>>> element_path = PortPath(raw="top_module.sub_module.port1")
>>> print(element_path.get(-1))
port1

Example 2

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(0))
top_module

Example 3

>>> element_path = InstancePath(raw="top_module/instance1", separator='/')
>>> print(element_path.get(-69420))
""

get_subseq

get_subseq(lower_idx: Optional[int], upper_idx: Optional[int]) -> List[str]

Returns a sublist of elements from the raw path.

This is useful when you need to extract a subset of elements from the full path, such as getting all instances or modules up to a certain level, or extracting a specific segment from a wire or port path.

Parameters:

• lower_idx

  (Optional[int]) –

  The starting index (inclusive) for slicing the list. If None, this conforms to an unset lower bound, i.e. [ : ....

• upper_idx

  (Optional[int]) –

  The ending index (exclusive) for slicing the list. If None, this conforms to an unset upper bound, i.e. ... : ].

Returns:

• list ( List[str] ) –

  A list of strings representing the subsequence of elements in the raw path.

is_type

is_type(type: EType) -> bool

Returns whether the type of this path matches the given element type.

If this path is an InstancePath and the given type is EType.INSTANCE, returns True. Returns False for all other types. Works analogously for all other types, depending on the given type and the value of ElementPath.type.

Parameters:

• type

  (EType) –

  The type to compare the type of this ElementPath with.

Returns:

• bool ( bool ) –

  Whether the given type matches the actual type of this path.