# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# 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 covergroup coverage of the UCIS XML interchange format: an instance's ``<covergroupCoverage>``, its covergroup
instances with their coverpoints and crosses.
"""
from __future__ import annotations
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.CoverOptions import CovergroupOptions
from pyEDAA.Reports.CodeCoverage.UCIS.Coverpoints import Coverpoint
from pyEDAA.Reports.CodeCoverage.UCIS.Crosses import Cross
from pyEDAA.Reports.CodeCoverage.UCIS.Elements import Base, MetricCoverage, StatementID, UserAttribute
if TYPE_CHECKING:
from pyEDAA.Reports.CodeCoverage.UCIS.Instances import InstanceCoverage
[docs]
@export
class CovergroupCoverage(MetricCoverage):
"""
A ``<covergroupCoverage>`` of an instance: its covergroup instances.
"""
_instances: list[CovergroupInstance] #: The covergroup instances.
[docs]
def __init__(
self,
metricMode: Nullable[str] = None,
weight: int = 1,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[InstanceCoverage] = None
) -> None:
"""
Initialize the covergroup coverage, and append it to the covergroup coverages of its instance.
Its covergroup instances are added by creating them with this coverage as their parent.
:param metricMode: Optional, the mode in which the coverage was measured. Default: ``None``.
:param weight: Optional, weight of the mode in computing the coverage. Default: ``1``.
:param userAttributes: Optional, the user-defined attributes. Default: ``None``.
:param parent: Optional, the instance the coverage belongs to. Default: ``None``.
:raises TypeError: If parameter ``metricMode`` isn't of type :class:`str`.
:raises ValueError: If parameter ``weight`` is ``None``.
:raises TypeError: If parameter ``weight`` isn't of type :class:`int`.
:raises ValueError: If parameter ``weight`` is negative.
: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 TypeError: If parameter ``parent`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Instances.InstanceCoverage`.
"""
super().__init__(metricMode, weight, userAttributes, parent=parent)
self._instances = []
if parent is not None:
parent._covergroupCoverages.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[InstanceCoverage] = None) -> Self:
"""
Parse a covergroup coverage and its covergroup instances from its ``<covergroupCoverage>`` element.
:param element: The ``<covergroupCoverage>`` element.
:param parent: Optional, the instance the coverage belongs to. Default: ``None``.
:returns: The covergroup coverage.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
covergroupCoverage = cls(
element.attrib.get("metricMode"),
int(element.attrib.get("weight", "1")),
cls._ParseUserAttributes(element),
parent=parent
)
for instanceElement in element.iterfind("{*}cgInstance"):
CovergroupInstance.Parse(instanceElement, parent=covergroupCoverage)
return covergroupCoverage
@readonly
def Instances(self) -> list[CovergroupInstance]:
"""
Read-only property to access the covergroup instances (:attr:`_instances`).
:returns: The covergroup instances, in the order the report lists them.
"""
return self._instances
[docs]
@export
class CovergroupID(metaclass=ExtendedType, slots=True):
"""
A ``<cgId>`` of a covergroup instance: the covergroup's name, the module or package declaring it, and where the
covergroup and the instance are declared.
It is a value, as a path is: it names no parent.
"""
_name: str #: Name of the covergroup.
_moduleName: str #: Name of the module or package declaring the covergroup.
_instanceSourceID: StatementID #: Where the covergroup instance is declared.
_sourceID: StatementID #: Where the covergroup is declared.
[docs]
def __init__(self, name: str, moduleName: str, instanceSourceID: StatementID, sourceID: StatementID) -> None:
"""
Initialize the covergroup identifier.
:param name: Name of the covergroup, e.g. ``cg``.
:param moduleName: Name of the module or package declaring the covergroup.
:param instanceSourceID: Where the covergroup instance is declared.
:param sourceID: Where the covergroup is declared.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``moduleName`` is ``None``.
:raises TypeError: If parameter ``moduleName`` isn't of type :class:`str`.
:raises ValueError: If parameter ``instanceSourceID`` is ``None``.
:raises TypeError: If parameter ``instanceSourceID`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.StatementID`.
:raises ValueError: If parameter ``sourceID`` is ``None``.
:raises TypeError: If parameter ``sourceID`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.StatementID`.
"""
for parameterName, value in (
("name", name),
("moduleName", moduleName)
):
if value is None:
raise ValueError(f"Parameter '{parameterName}' is None.")
elif not isinstance(value, str):
ex = TypeError(f"Parameter '{parameterName}' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(value)}'.")
raise ex
for parameterName, value in (
("instanceSourceID", instanceSourceID),
("sourceID", sourceID)
):
if value is None:
raise ValueError(f"Parameter '{parameterName}' is None.")
elif not isinstance(value, StatementID):
ex = TypeError(f"Parameter '{parameterName}' is not of type 'StatementID'.")
ex.add_note(f"Got type '{getFullyQualifiedName(value)}'.")
raise ex
self._name = name
self._moduleName = moduleName
self._instanceSourceID = instanceSourceID
self._sourceID = sourceID
[docs]
@classmethod
def Parse(cls, element: _Element) -> Self:
"""
Parse a covergroup identifier from its ``<cgId>`` element.
:param element: The ``<cgId>`` element.
:returns: The covergroup identifier.
"""
return cls(
element.attrib["cgName"],
element.attrib["moduleName"],
StatementID.Parse(element.find("{*}cginstSourceId")),
StatementID.Parse(element.find("{*}cgSourceId"))
)
@readonly
def Name(self) -> str:
"""
Read-only property to access the name of the covergroup (:attr:`_name`).
:returns: The name, as declared.
"""
return self._name
@readonly
def ModuleName(self) -> str:
"""
Read-only property to access the name of the module or package declaring the covergroup (:attr:`_moduleName`).
:returns: The name, as stated.
"""
return self._moduleName
@readonly
def InstanceSourceID(self) -> StatementID:
"""
Read-only property to access where the covergroup instance is declared (:attr:`_instanceSourceID`).
:returns: The source statement identifier.
"""
return self._instanceSourceID
@readonly
def SourceID(self) -> StatementID:
"""
Read-only property to access where the covergroup is declared (:attr:`_sourceID`).
:returns: The source statement identifier.
"""
return self._sourceID
# A class with a property named like a class - ``CovergroupID`` - 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.
_CovergroupID = CovergroupID
[docs]
@export
class CovergroupInstance(Base):
"""
A ``<cgInstance>`` of a covergroup coverage: an instance of a covergroup - or the covergroup as a whole -, its
options and parameters, its coverpoints and crosses.
"""
_parent: Nullable[CovergroupCoverage] #: The covergroup coverage the covergroup instance belongs to.
_name: str #: Name of the covergroup instance.
_key: str #: UCIS key of the covergroup instance.
_options: CovergroupOptions #: The options of the covergroup instance.
_covergroupID: _CovergroupID #: The covergroup and where it and the instance are declared.
_parameters: dict[str, str] #: The parameters of the covergroup instance, by name.
_alias: Nullable[str] #: An alias of the covergroup instance's name.
_isExcluded: bool #: Whether the covergroup instance is excluded from the coverage.
_excludedReason: Nullable[str] #: Why the covergroup instance is excluded.
_coverpoints: list[Coverpoint] #: The coverpoints.
_crosses: list[Cross] #: The crosses.
[docs]
def __init__(
self,
name: str,
key: str,
options: CovergroupOptions,
covergroupID: CovergroupID,
parameters: Nullable[Mapping[str, str]] = None,
alias: Nullable[str] = None,
excluded: bool = False,
excludedReason: Nullable[str] = None,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[CovergroupCoverage] = None
) -> None:
"""
Initialize the covergroup instance, and append it to the covergroup instances of its covergroup coverage.
Its coverpoints and crosses are added by creating them with this covergroup instance as their parent.
:param name: Name of the covergroup instance, e.g. ``top.cv``.
:param key: UCIS key of the covergroup instance.
:param options: The options of the covergroup instance.
:param covergroupID: The covergroup and where it and the instance are declared.
:param parameters: Optional, the parameters of the covergroup instance, by name. Default: ``None``.
:param alias: Optional, an alias of the covergroup instance's name. Default: ``None``.
:param excluded: Optional, whether the covergroup instance is excluded from the coverage. Default:
``False``.
:param excludedReason: Optional, why the covergroup instance is excluded. Default: ``None``.
:param userAttributes: Optional, the user-defined attributes. Default: ``None``.
:param parent: Optional, the covergroup coverage the covergroup instance belongs to. Default: ``None``.
: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 ``options`` is ``None``.
:raises TypeError: If parameter ``options`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.CoverOptions.CovergroupOptions`.
:raises ValueError: If parameter ``covergroupID`` is ``None``.
:raises TypeError: If parameter ``covergroupID`` isn't of type :class:`CovergroupID`.
:raises TypeError: If parameter ``parameters`` isn't a mapping.
:raises TypeError: If parameter ``parameters`` contains a name or value not of type :class:`str`.
:raises TypeError: If parameter ``alias`` isn't of type :class:`str`.
:raises ValueError: If parameter ``excluded`` is ``None``.
:raises TypeError: If parameter ``excluded`` isn't of type :class:`bool`.
:raises TypeError: If parameter ``excludedReason`` isn't of type :class:`str`.
: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 TypeError: If parameter ``parent`` isn't of type :class:`CovergroupCoverage`.
"""
super().__init__(userAttributes)
for parameterName, value in (
("name", name),
("key", key)
):
if value is None:
raise ValueError(f"Parameter '{parameterName}' is None.")
elif not isinstance(value, str):
ex = TypeError(f"Parameter '{parameterName}' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(value)}'.")
raise ex
if options is None:
raise ValueError("Parameter 'options' is None.")
elif not isinstance(options, CovergroupOptions):
ex = TypeError("Parameter 'options' is not of type 'CovergroupOptions'.")
ex.add_note(f"Got type '{getFullyQualifiedName(options)}'.")
raise ex
if covergroupID is None:
raise ValueError("Parameter 'covergroupID' is None.")
elif not isinstance(covergroupID, CovergroupID):
ex = TypeError("Parameter 'covergroupID' is not of type 'CovergroupID'.")
ex.add_note(f"Got type '{getFullyQualifiedName(covergroupID)}'.")
raise ex
for parameterName, value in (
("alias", alias),
("excludedReason", excludedReason)
):
if value is not None and not isinstance(value, str):
ex = TypeError(f"Parameter '{parameterName}' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(value)}'.")
raise ex
if excluded is None:
raise ValueError("Parameter 'excluded' is None.")
elif not isinstance(excluded, bool):
ex = TypeError("Parameter 'excluded' is not of type 'bool'.")
ex.add_note(f"Got type '{getFullyQualifiedName(excluded)}'.")
raise ex
if parent is not None and not isinstance(parent, CovergroupCoverage):
ex = TypeError("Parameter 'parent' is not of type 'CovergroupCoverage'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
self._parent = parent
self._name = name
self._key = key
self._options = options
self._covergroupID = covergroupID
self._parameters = {}
self._alias = alias
self._isExcluded = excluded
self._excludedReason = excludedReason
self._coverpoints = []
self._crosses = []
if parameters is not None:
if not isinstance(parameters, Mapping):
ex = TypeError("Parameter 'parameters' is not a mapping.")
ex.add_note(f"Got type '{getFullyQualifiedName(parameters)}'.")
raise ex
for parameterName, value in parameters.items():
if not isinstance(parameterName, str) or not isinstance(value, str):
ex = TypeError("Parameter 'parameters' contains a name or value not of type 'str'.")
ex.add_note(f"Got types '{getFullyQualifiedName(parameterName)}' and '{getFullyQualifiedName(value)}'.")
raise ex
self._parameters[parameterName] = value
if parent is not None:
parent._instances.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[CovergroupCoverage] = None) -> Self:
"""
Parse a covergroup instance, its coverpoints and crosses from its ``<cgInstance>`` element.
:param element: The ``<cgInstance>`` element.
:param parent: Optional, the covergroup coverage the covergroup instance belongs to. Default: ``None``.
:returns: The covergroup instance.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
instance = cls(
element.attrib["name"],
element.attrib["key"],
CovergroupOptions.Parse(element.find("{*}options")),
CovergroupID.Parse(element.find("{*}cgId")),
{
parameterElement.findtext("{*}name"): parameterElement.findtext("{*}value")
for parameterElement in element.iterfind("{*}cgParms")
},
element.attrib.get("alias"),
cls._ParseBoolean(element.attrib.get("excluded", "false")),
element.attrib.get("excludedReason"),
cls._ParseUserAttributes(element),
parent=parent
)
for coverpointElement in element.iterfind("{*}coverpoint"):
Coverpoint.Parse(coverpointElement, parent=instance)
for crossElement in element.iterfind("{*}cross"):
Cross.Parse(crossElement, parent=instance)
return instance
@readonly
def Parent(self) -> Nullable[CovergroupCoverage]:
"""
Read-only property to access the covergroup coverage the covergroup instance belongs to (:attr:`_parent`).
:returns: The covergroup coverage; ``None``, if the covergroup instance belongs to none.
"""
return self._parent
@readonly
def Name(self) -> str:
"""
Read-only property to access the name of the covergroup 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 covergroup instance (:attr:`_key`).
:returns: The key, as stated.
"""
return self._key
@readonly
def Options(self) -> CovergroupOptions:
"""
Read-only property to access the options of the covergroup instance (:attr:`_options`).
:returns: The options.
"""
return self._options
@readonly
def CovergroupID(self) -> CovergroupID:
"""
Read-only property to access the covergroup and where it and the instance are declared (:attr:`_covergroupID`).
:returns: The covergroup identifier.
"""
return self._covergroupID
@readonly
def Parameters(self) -> dict[str, str]:
"""
Read-only property to access the parameters of the covergroup instance (:attr:`_parameters`).
:returns: The parameters' values, by name.
"""
return self._parameters
@readonly
def Alias(self) -> Nullable[str]:
"""
Read-only property to access the alias of the covergroup instance's name (:attr:`_alias`).
:returns: The alias; ``None``, if the report states none.
"""
return self._alias
@readonly
def IsExcluded(self) -> bool:
"""
Read-only property to access whether the covergroup instance is excluded from the coverage (:attr:`_isExcluded`).
:returns: ``True``, if excluded.
"""
return self._isExcluded
@readonly
def ExcludedReason(self) -> Nullable[str]:
"""
Read-only property to access why the covergroup instance is excluded (:attr:`_excludedReason`).
:returns: The reason; ``None``, if the report states none.
"""
return self._excludedReason
@readonly
def Coverpoints(self) -> list[Coverpoint]:
"""
Read-only property to access the coverpoints (:attr:`_coverpoints`).
:returns: The coverpoints, in the order the report lists them.
"""
return self._coverpoints
@readonly
def Crosses(self) -> list[Cross]:
"""
Read-only property to access the crosses (:attr:`_crosses`).
:returns: The crosses, in the order the report lists them.
"""
return self._crosses