# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# 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 branch coverage of the UCIS XML interchange format: an instance's ``<branchCoverage>``, its branching statements
and their branches.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Generator, Generic, Iterable, \
Optional as Nullable, Self, TypeVar
from lxml.etree import _Element
from pyTooling.Common import getFullyQualifiedName
from pyTooling.Decorators import export, readonly
from pyEDAA.Reports.CodeCoverage.UCIS.Bins import Bin
from pyEDAA.Reports.CodeCoverage.UCIS.Elements import Base, MetricCoverage, ObjectAttributesMixin, StatementID, \
UserAttribute
if TYPE_CHECKING:
from pyEDAA.Reports.CodeCoverage.UCIS.Instances import InstanceCoverage
__all__ = ["BranchStatementParentType"]
# A class with a property named like a class - ``Bin`` - 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.
_Bin = Bin
BranchStatementParentType = TypeVar("BranchStatementParentType", bound="BranchCoverage | Branch")
"""A type variable for the parent of a :class:`BranchStatement`: a :class:`BranchCoverage` or a :class:`Branch`."""
[docs]
@export
class BranchCoverage(MetricCoverage):
"""
A ``<branchCoverage>`` of an instance: its branching statements.
"""
_statements: list[BranchStatement[BranchCoverage]] #: The branching statements.
[docs]
def __init__(
self,
metricMode: Nullable[str] = None,
weight: int = 1,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[InstanceCoverage] = None
) -> None:
"""
Initialize the branch coverage, and append it to the branch coverages of its instance.
Its branching statements 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._statements = []
if parent is not None:
parent._branchCoverages.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[InstanceCoverage] = None) -> Self:
"""
Parse a branch coverage and its branching statements from its ``<branchCoverage>`` element.
:param element: The ``<branchCoverage>`` element.
:param parent: Optional, the instance the coverage belongs to. Default: ``None``.
:returns: The branch coverage.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
branchCoverage = cls(
element.attrib.get("metricMode"),
int(element.attrib.get("weight", "1")),
cls._ParseUserAttributes(element),
parent=parent
)
for statementElement in element.iterfind("{*}statement"):
BranchStatement.Parse(statementElement, parent=branchCoverage)
return branchCoverage
[docs]
def IterateStatements(self) -> Generator[BranchStatement, None, None]:
"""
Iterate the branching statements, each followed by the branching statements nested in its branches.
:returns: A generator of the branching statements.
"""
for statement in self._statements:
yield statement
yield from statement.IterateStatements()
@readonly
def Statements(self) -> list[BranchStatement[BranchCoverage]]:
"""
Read-only property to access the branching statements (:attr:`_statements`).
:returns: The branching statements, which aren't nested in a branch, in the order the report lists them.
"""
return self._statements
[docs]
@export
class BranchStatement(Base, ObjectAttributesMixin, Generic[BranchStatementParentType]):
"""
A branching statement - a ``<statement>`` of a branch coverage, or a ``<nestedBranch>`` of a branch -: where it is,
its kind, its expression and its branches.
"""
_parent: Nullable[BranchStatementParentType] #: The branch coverage or branch the statement belongs to.
_id: StatementID #: Where the branching statement is.
_statementType: str #: Kind of the branching statement, e.g. ``if``.
_branchExpression: Nullable[str] #: The expression the statement branches on.
_branches: list[Branch] #: The branches.
[docs]
def __init__(
self,
statementID: StatementID,
statementType: str,
branchExpression: Nullable[str] = None,
alias: Nullable[str] = None,
excluded: bool = False,
excludedReason: Nullable[str] = None,
weight: int = 1,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[BranchStatementParentType] = None
) -> None:
"""
Initialize the branching statement, and append it to the branching statements of its parent.
Its branches are added by creating them with this statement as their parent.
:param statementID: Where the branching statement is.
:param statementType: Kind of the branching statement, e.g. ``if`` or ``case``.
:param branchExpression: Optional, the expression the statement branches on, e.g. ``(x)``. Default: ``None``.
:param alias: Optional, an alias of the statement's name. Default: ``None``.
:param excluded: Optional, whether the statement is excluded from the coverage. Default: ``False``.
:param excludedReason: Optional, why the statement is excluded. Default: ``None``.
:param weight: Optional, weight of the statement in computing the coverage. Default: ``1``.
:param userAttributes: Optional, the user-defined attributes. Default: ``None``.
:param parent: Optional, the branch coverage or branch the statement belongs to. Default: ``None``.
:raises ValueError: If parameter ``statementID`` is ``None``.
:raises TypeError: If parameter ``statementID`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.StatementID`.
:raises ValueError: If parameter ``statementType`` is ``None``.
:raises TypeError: If parameter ``statementType`` isn't of type :class:`str`.
:raises TypeError: If parameter ``branchExpression`` isn't 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 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:`BranchCoverage` or :class:`Branch`.
"""
super().__init__(userAttributes)
ObjectAttributesMixin.__init__(self, alias, excluded, excludedReason, weight)
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 statementType is None:
raise ValueError("Parameter 'statementType' is None.")
elif not isinstance(statementType, str):
ex = TypeError("Parameter 'statementType' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(statementType)}'.")
raise ex
if branchExpression is not None and not isinstance(branchExpression, str):
ex = TypeError("Parameter 'branchExpression' is not of type 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(branchExpression)}'.")
raise ex
if parent is not None and not isinstance(parent, (BranchCoverage, Branch)):
ex = TypeError("Parameter 'parent' is not of type 'BranchCoverage' or 'Branch'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
self._parent = parent
self._id = statementID
self._statementType = statementType
self._branchExpression = branchExpression
self._branches = []
if parent is not None:
parent._statements.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[BranchStatementParentType] = None) -> Self:
"""
Parse a branching statement and its branches from its ``<statement>`` or ``<nestedBranch>`` element.
:param element: The ``<statement>`` or ``<nestedBranch>`` element.
:param parent: Optional, the branch coverage or branch the statement belongs to. Default: ``None``.
:returns: The branching statement.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
statement = cls(
StatementID.Parse(element.find("{*}id")),
element.attrib["statementType"],
element.attrib.get("branchExpr"),
element.attrib.get("alias"),
cls._ParseBoolean(element.attrib.get("excluded", "false")),
element.attrib.get("excludedReason"),
int(element.attrib.get("weight", "1")),
cls._ParseUserAttributes(element),
parent=parent
)
for branchElement in element.iterfind("{*}branch"):
Branch.Parse(branchElement, parent=statement)
return statement
[docs]
def IterateStatements(self) -> Generator[BranchStatement[Branch], None, None]:
"""
Iterate the branching statements nested in this statement's branches, each followed by those nested in it.
:returns: A generator of the branching statements.
"""
for branch in self._branches:
for statement in branch._statements:
yield statement
yield from statement.IterateStatements()
@readonly
def Parent(self) -> Nullable[BranchStatementParentType]:
"""
Read-only property to access the branch coverage or branch the statement belongs to (:attr:`_parent`).
:returns: The :class:`BranchCoverage` or :class:`Branch`; ``None``, if the statement belongs to none.
"""
return self._parent
@readonly
def ID(self) -> StatementID:
"""
Read-only property to access where the branching statement is (:attr:`_id`).
:returns: The source statement identifier.
"""
return self._id
@readonly
def StatementType(self) -> str:
"""
Read-only property to access the kind of the branching statement (:attr:`_statementType`).
:returns: The kind, e.g. ``if`` or ``case``.
"""
return self._statementType
@readonly
def BranchExpression(self) -> Nullable[str]:
"""
Read-only property to access the expression the statement branches on (:attr:`_branchExpression`).
:returns: The expression; ``None``, if the report states none.
"""
return self._branchExpression
@readonly
def Branches(self) -> list[Branch]:
"""
Read-only property to access the branches (:attr:`_branches`).
:returns: The branches, in the order the report lists them.
"""
return self._branches
[docs]
@export
class Branch(Base):
"""
A ``<branch>`` of a branching statement: where it is, its bin - how often it was taken - and the branching
statements nested in it.
"""
_parent: Nullable[BranchStatement] #: The branching statement the branch belongs to.
_id: StatementID #: Where the branch is.
_bin: _Bin #: How often the branch was taken.
_statements: list[BranchStatement[Branch]] #: The branching statements nested in the branch.
[docs]
def __init__(
self,
branchID: StatementID,
coverBin: Bin,
userAttributes: Nullable[Iterable[UserAttribute]] = None,
*,
parent: Nullable[BranchStatement] = None
) -> None:
"""
Initialize the branch, become its bin's parent, and append it to the branches of its branching statement.
The branching statements nested in it are added by creating them with this branch as their parent.
:param branchID: Where the branch is.
:param coverBin: How often the branch was taken.
:param userAttributes: Optional, the user-defined attributes. Default: ``None``.
:param parent: Optional, the branching statement the branch belongs to. Default: ``None``.
:raises ValueError: If parameter ``branchID`` is ``None``.
:raises TypeError: If parameter ``branchID`` isn't of type
:class:`~pyEDAA.Reports.CodeCoverage.UCIS.Elements.StatementID`.
:raises ValueError: If parameter ``coverBin`` is ``None``.
:raises TypeError: If parameter ``coverBin`` isn't of type :class:`~pyEDAA.Reports.CodeCoverage.UCIS.Bins.Bin`.
: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:`BranchStatement`.
"""
super().__init__(userAttributes)
if branchID is None:
raise ValueError("Parameter 'branchID' is None.")
elif not isinstance(branchID, StatementID):
ex = TypeError("Parameter 'branchID' is not of type 'StatementID'.")
ex.add_note(f"Got type '{getFullyQualifiedName(branchID)}'.")
raise ex
if coverBin is None:
raise ValueError("Parameter 'coverBin' is None.")
elif not isinstance(coverBin, Bin):
ex = TypeError("Parameter 'coverBin' is not of type 'Bin'.")
ex.add_note(f"Got type '{getFullyQualifiedName(coverBin)}'.")
raise ex
if parent is not None and not isinstance(parent, BranchStatement):
ex = TypeError("Parameter 'parent' is not of type 'BranchStatement'.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
self._parent = parent
self._id = branchID
self._bin = coverBin
self._statements = []
coverBin._parent = self
if parent is not None:
parent._branches.append(self)
[docs]
@classmethod
def Parse(cls, element: _Element, *, parent: Nullable[BranchStatement] = None) -> Self:
"""
Parse a branch, its bin and the branching statements nested in it from its ``<branch>`` element.
:param element: The ``<branch>`` element.
:param parent: Optional, the branching statement the branch belongs to. Default: ``None``.
:returns: The branch.
:raises CodeCoverageError: If a user-defined attribute's value isn't of the type the attribute states.
"""
branch = cls(
StatementID.Parse(element.find("{*}id")),
Bin.Parse(element.find("{*}branchBin")),
cls._ParseUserAttributes(element),
parent=parent
)
for statementElement in element.iterfind("{*}nestedBranch"):
BranchStatement.Parse(statementElement, parent=branch)
return branch
@readonly
def Parent(self) -> Nullable[BranchStatement]:
"""
Read-only property to access the branching statement the branch belongs to (:attr:`_parent`).
:returns: The branching statement; ``None``, if the branch belongs to none.
"""
return self._parent
@readonly
def ID(self) -> StatementID:
"""
Read-only property to access where the branch is (:attr:`_id`).
:returns: The source statement identifier.
"""
return self._id
@readonly
def Bin(self) -> Bin:
"""
Read-only property to access the branch's bin (:attr:`_bin`).
:returns: The bin, stating how often the branch was taken.
"""
return self._bin
@readonly
def Statements(self) -> list[BranchStatement[Branch]]:
"""
Read-only property to access the branching statements nested in the branch (:attr:`_statements`).
:returns: The branching statements, in the order the report lists them.
"""
return self._statements