# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-2026 Electronic Design Automation Abstraction (EDA²) #
# #
# Licensed under the Apache License, Version 2.0 (the "License"); #
# you may not use this file except in compliance with the License. #
# You may obtain a copy of the License at #
# #
# http://www.apache.org/licenses/LICENSE-2.0 #
# #
# Unless required by applicable law or agreed to in writing, software #
# distributed under the License is distributed on an "AS IS" BASIS, #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
# See the License for the specific language governing permissions and #
# limitations under the License. #
# #
# SPDX-License-Identifier: Apache-2.0 #
# ==================================================================================================================== #
#
"""
The instances of the UCIS XML interchange format, each with its coverage of each kind, and the source files the
report's statement identifiers name by their ID.
"""
from __future__ import annotations
from pathlib import Path
from typing import TYPE_CHECKING, Iterable, Mapping, Optional as Nullable, Self
from lxml.etree import _Element
from pyTooling.Common import getFullyQualifiedName
from pyTooling.Decorators import export, readonly
from pyTooling.MetaClasses import ExtendedType
from pyEDAA.Reports.CodeCoverage.UCIS.Assertions import AssertionCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Blocks import BlockCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Branches import BranchCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Conditions import ConditionCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Covergroups import CovergroupCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Elements import Base, StatementID, UserAttribute
from pyEDAA.Reports.CodeCoverage.UCIS.FSMs import FSMCoverage
from pyEDAA.Reports.CodeCoverage.UCIS.Toggles import ToggleCoverage
if TYPE_CHECKING:
from pyEDAA.Reports.CodeCoverage.UCIS import Report
# A class with a property named like a class - ``Path`` - can't name that class in the annotation of a field: the class
# body's namespace, where annotations are evaluated, binds the name to the property.
_Path = Path
[docs]
@export
class SourceFile(metaclass=ExtendedType, slots=True):
"""
A ``<sourceFiles>`` of the report: a source file's path and the ID, by which statement identifiers name it.
"""
_parent: Nullable[Report] #: The report the source file belongs to.
_path: _Path #: Path of the source file.
_sourceFileID: int #: ID of the source file.
[docs]
def __init__(self, path: Path, sourceFileID: int, *, parent: Nullable[Report] = None) -> None:
"""
Initialize the source file, and add it to the source files of its report.
:param path: Path of the source file, as the tool states it.
:param sourceFileID: ID of the source file, counted from 1.
:param parent: Optional, the report the source file belongs to; the source file is added to its source
files. Default: ``None``.
:raises ValueError: If parameter ``path`` is ``None``.
:raises TypeError: If parameter ``path`` isn't of type :class:`~pathlib.Path`.
:raises ValueError: If parameter ``sourceFileID`` is ``None``.
:raises TypeError: If parameter ``sourceFileID`` isn't of type :class:`int`.
:raises ValueError: If parameter ``sourceFileID`` is less than 1.
:raises TypeError: If parameter ``parent`` isn't of type :class:`~pyEDAA.Reports.CodeCoverage.UCIS.Report`.
"""
from pyEDAA.Reports.CodeCoverage.UCIS import Report
if path is None:
raise ValueError("Parameter 'path' is None.")
elif not isinstance(path, Path):
ex = TypeError("Parameter 'path' is not of type 'Path'.")
ex.add_note(f"Got type '{getFullyQualifiedName(path)}'.")
raise ex
if sourceFileID is None:
raise ValueError("Parameter 'sourceFileID' is None.")
elif not isinstance(sourceFileID, int) or isinstance(sourceFileID, bool):
ex = TypeError("Parameter 'sourceFileID' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(sourceFileID)}'.")
raise ex
elif sourceFileID < 1:
ex = ValueError("Parameter 'sourceFileID' is less than 1.")
ex.add_note(f"Got value '{sourceFileID}'.")
raise ex
if parent is not None and not isinstance(parent, Report):
ex = TypeError("Parameter 'parent' is not of type 'Report'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
self._parent = parent
self._path = path
self._sourceFileID = sourceFileID
if parent is not None:
parent._sourceFiles[sourceFileID] = self
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[Report] = None) -> Self:
"""
Parse a source file from its ``<sourceFiles>`` element.
:param element: The ``<sourceFiles>`` element.
:param parent: Optional, the report the source file belongs to. Default: ``None``.
:returns: The source file.
"""
return cls(Path(element.attrib["fileName"]), int(element.attrib["id"]), parent=parent)
@readonly
def Parent(self) -> Nullable[Report]:
"""
Read-only property to access the report the source file belongs to (:attr:`_parent`).
:returns: The report; ``None``, if the source file belongs to none.
"""
return self._parent
@readonly
def Path(self) -> Path:
"""
Read-only property to access the path of the source file (:attr:`_path`).
:returns: The path, as the tool states it: absolute, or relative to the directory it ran in.
"""
return self._path
@readonly
def SourceFileID(self) -> int:
"""
Read-only property to access the ID of the source file (:attr:`_sourceFileID`).
:returns: The ID, by which statement identifiers name the file.
"""
return self._sourceFileID
[docs]
@export
class InstanceCoverage(Base):
"""
An ``<instanceCoverages>`` of the report: an instance of a design unit, where it is instantiated, its parameters, and
its coverage of each kind.
An instance names the instance it is instantiated in by that instance's ID.
"""
_parent: Nullable[Report] #: The report the instance belongs to.
_name: str #: Name of the instance.
_key: str #: UCIS key of the instance.
_id: StatementID #: Where the instance is instantiated.
_instanceID: Nullable[int] #: ID of the instance.
_alias: Nullable[str] #: An alias of the instance's name.
_moduleName: Nullable[str] #: Name of the design unit the instance instantiates.
_parentInstanceID: Nullable[int] #: ID of the instance this one is instantiated in.
_designParameters: dict[str, str] #: The design parameters of the instance, by name.
_toggleCoverages: list[ToggleCoverage] #: The toggle coverage, per metric mode.
_blockCoverages: list[BlockCoverage] #: The statement and block coverage, per metric mode.
_conditionCoverages: list[ConditionCoverage] #: The condition and expression coverage, per metric mode.
_branchCoverages: list[BranchCoverage] #: The branch coverage, per metric mode.
_fsmCoverages: list[FSMCoverage] #: The FSM coverage, per metric mode.
_assertionCoverages: list[AssertionCoverage] #: The assertion coverage, per metric mode.
_covergroupCoverages: list[CovergroupCoverage] #: The covergroup coverage, per metric mode.
[docs]
def __init__(
self,
name: str,
key: str,
statementID: StatementID,
instanceID: Nullable[int] = None,
alias: Nullable[str] = None,
moduleName: Nullable[str] = None,
parentInstanceID: Nullable[int] = None,
designParameters: Nullable[Mapping[str, str]] = None,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[Report] = None
) -> None:
"""
Initialize the instance, and append it to the instances of its report.
Its coverage of each kind is added by creating it with this instance as its parent.
:param name: Name of the instance, e.g. ``top.dut``.
:param key: UCIS key of the instance.
:param statementID: Where the instance is instantiated.
:param instanceID: Optional, ID of the instance. Default: ``None``.
:param alias: Optional, an alias of the instance's name. Default: ``None``.
:param moduleName: Optional, name of the design unit the instance instantiates. Default: ``None``.
:param parentInstanceID: Optional, ID of the instance this one is instantiated in. Default: ``None``.
:param designParameters: Optional, the design parameters of the instance, by name, e.g. ``{"WIDTH": "8"}``.
Default: ``None``.
:param userAttributes: Optional, the user-defined attributes. Default: ``None``.
:param parent: Optional, the report the instance belongs to; the instance is appended to its instances.
Default: ``None``.
:raises TypeError: If parameter ``userAttributes`` isn't iterable.
:raises TypeError: If parameter ``userAttributes`` contains an element not of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.UserAttribute`.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``key`` is ``None``.
:raises TypeError: If parameter ``key`` isn't of type :class:`str`.
:raises ValueError: If parameter ``statementID`` is ``None``.
:raises TypeError: If parameter ``statementID`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.StatementID`.
:raises TypeError: If parameter ``instanceID`` isn't of type :class:`int`.
:raises TypeError: If parameter ``alias`` isn't of type :class:`str`.
:raises TypeError: If parameter ``moduleName`` isn't of type :class:`str`.
:raises TypeError: If parameter ``parentInstanceID`` isn't of type :class:`int`.
:raises TypeError: If parameter ``designParameters`` isn't a mapping.
:raises TypeError: If parameter ``designParameters`` contains a name or value not of type :class:`str`.
:raises TypeError: If parameter ``parent`` isn't of type :class:`~pyEDAA.Reports.CodeCoverage.UCIS.Report`.
"""
from pyEDAA.Reports.CodeCoverage.UCIS import Report
super().__init__(userAttributes)
if name is None:
raise ValueError("Parameter 'name' is None.")
elif not isinstance(name, str):
ex = TypeError("Parameter 'name' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
raise ex
if key is None:
raise ValueError("Parameter 'key' is None.")
elif not isinstance(key, str):
ex = TypeError("Parameter 'key' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(key)}'.")
raise ex
if statementID is None:
raise ValueError("Parameter 'statementID' is None.")
elif not isinstance(statementID, StatementID):
ex = TypeError("Parameter 'statementID' is not of type 'StatementID'.")
ex.add_note(f"Got type '{getFullyQualifiedName(statementID)}'.")
raise ex
if instanceID is not None and (not isinstance(instanceID, int) or isinstance(instanceID, bool)):
ex = TypeError("Parameter 'instanceID' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(instanceID)}'.")
raise ex
if alias is not None and not isinstance(alias, str):
ex = TypeError("Parameter 'alias' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(alias)}'.")
raise ex
if moduleName is not None and not isinstance(moduleName, str):
ex = TypeError("Parameter 'moduleName' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(moduleName)}'.")
raise ex
if parentInstanceID is not None and (not isinstance(parentInstanceID, int) or isinstance(parentInstanceID, bool)):
ex = TypeError("Parameter 'parentInstanceID' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parentInstanceID)}'.")
raise ex
if parent is not None and not isinstance(parent, Report):
ex = TypeError("Parameter 'parent' is not of type 'Report'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
self._parent = parent
self._name = name
self._key = key
self._id = statementID
self._instanceID = instanceID
self._alias = alias
self._moduleName = moduleName
self._parentInstanceID = parentInstanceID
self._designParameters = {}
self._toggleCoverages = []
self._blockCoverages = []
self._conditionCoverages = []
self._branchCoverages = []
self._fsmCoverages = []
self._assertionCoverages = []
self._covergroupCoverages = []
if designParameters is not None:
if not isinstance(designParameters, Mapping):
ex = TypeError("Parameter 'designParameters' is not a mapping.")
ex.add_note(f"Got type '{getFullyQualifiedName(designParameters)}'.")
raise ex
for parameterName, value in designParameters.items():
if not isinstance(parameterName, str) or not isinstance(value, str):
ex = TypeError("Parameter 'designParameters' contains a name or value not of type 'str'.")
ex.add_note(f"Got types '{getFullyQualifiedName(parameterName)}' and '{getFullyQualifiedName(value)}'.")
raise ex
self._designParameters[parameterName] = value
if parent is not None:
parent._instances.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[Report] = None) -> Self:
"""
Parse an instance and its coverage of each kind from its ``<instanceCoverages>`` element.
:param element: The ``<instanceCoverages>`` element.
:param parent: Optional, the report the instance belongs to. Default: ``None``.
:returns: The instance.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
attributes = element.attrib
instanceID = attributes.get("instanceId")
parentInstanceID = attributes.get("parentInstanceId")
designParameters = {
parameterElement.findtext("{*}name"): parameterElement.findtext("{*}value")
for parameterElement in element.iterfind("{*}designParameter")
}
instance = cls(
attributes["name"],
attributes["key"],
StatementID.Parse(element.find("{*}id")),
None if instanceID is None else int(instanceID),
attributes.get("alias"),
attributes.get("moduleName"),
None if parentInstanceID is None else int(parentInstanceID),
designParameters,
cls._ParseUserAttributes(element),
parent=parent
)
for coverageElement in element.iterfind("{*}toggleCoverage"):
ToggleCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}blockCoverage"):
BlockCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}conditionCoverage"):
ConditionCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}branchCoverage"):
BranchCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}fsmCoverage"):
FSMCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}assertionCoverage"):
AssertionCoverage.Parse(coverageElement, parent=instance)
for coverageElement in element.iterfind("{*}covergroupCoverage"):
CovergroupCoverage.Parse(coverageElement, parent=instance)
return instance
@readonly
def Parent(self) -> Nullable[Report]:
"""
Read-only property to access the report the instance belongs to (:attr:`_parent`).
:returns: The report; ``None``, if the instance belongs to none.
"""
return self._parent
@readonly
def Name(self) -> str:
"""
Read-only property to access the name of the instance (:attr:`_name`).
:returns: The name, as stated.
"""
return self._name
@readonly
def Key(self) -> str:
"""
Read-only property to access the UCIS key of the instance (:attr:`_key`).
:returns: The key, as stated.
"""
return self._key
@readonly
def ID(self) -> StatementID:
"""
Read-only property to access where the instance is instantiated (:attr:`_id`).
:returns: The source statement identifier.
"""
return self._id
@readonly
def InstanceID(self) -> Nullable[int]:
"""
Read-only property to access the ID of the instance (:attr:`_instanceID`).
:returns: The ID; ``None``, if the report states none.
"""
return self._instanceID
@readonly
def Alias(self) -> Nullable[str]:
"""
Read-only property to access the alias of the instance's name (:attr:`_alias`).
:returns: The alias; ``None``, if the report states none.
"""
return self._alias
@readonly
def ModuleName(self) -> Nullable[str]:
"""
Read-only property to access the name of the design unit the instance instantiates (:attr:`_moduleName`).
:returns: The design unit's name; ``None``, if the report states none.
"""
return self._moduleName
@readonly
def ParentInstanceID(self) -> Nullable[int]:
"""
Read-only property to access the ID of the instance this one is instantiated in (:attr:`_parentInstanceID`).
:returns: The ID; ``None`` for a top-level instance, or if the report states none.
"""
return self._parentInstanceID
@readonly
def DesignParameters(self) -> dict[str, str]:
"""
Read-only property to access the design parameters of the instance (:attr:`_designParameters`).
:returns: The parameters' values, by name.
"""
return self._designParameters
@readonly
def BlockCoverages(self) -> list[BlockCoverage]:
"""
Read-only property to access the statement and block coverage (:attr:`_blockCoverages`).
:returns: The block coverages, one per metric mode, in the order the report lists them.
"""
return self._blockCoverages
@readonly
def BranchCoverages(self) -> list[BranchCoverage]:
"""
Read-only property to access the branch coverage (:attr:`_branchCoverages`).
:returns: The branch coverages, one per metric mode, in the order the report lists them.
"""
return self._branchCoverages
@readonly
def ToggleCoverages(self) -> list[ToggleCoverage]:
"""
Read-only property to access the toggle coverage (:attr:`_toggleCoverages`).
:returns: The toggle coverages, one per metric mode, in the order the report lists them.
"""
return self._toggleCoverages
@readonly
def ConditionCoverages(self) -> list[ConditionCoverage]:
"""
Read-only property to access the condition and expression coverage (:attr:`_conditionCoverages`).
:returns: The condition coverages, one per metric mode, in the order the report lists them.
"""
return self._conditionCoverages
@readonly
def FSMCoverages(self) -> list[FSMCoverage]:
"""
Read-only property to access the FSM coverage (:attr:`_fsmCoverages`).
:returns: The FSM coverages, one per metric mode, in the order the report lists them.
"""
return self._fsmCoverages
@readonly
def AssertionCoverages(self) -> list[AssertionCoverage]:
"""
Read-only property to access the assertion coverage (:attr:`_assertionCoverages`).
:returns: The assertion coverages, one per metric mode, in the order the report lists them.
"""
return self._assertionCoverages
@readonly
def CovergroupCoverages(self) -> list[CovergroupCoverage]:
"""
Read-only property to access the covergroup coverage (:attr:`_covergroupCoverages`).
:returns: The covergroup coverages, one per metric mode, in the order the report lists them.
"""
return self._covergroupCoverages