# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2021-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 #
# ==================================================================================================================== #
#
"""
Abstract data model of code coverage, the common model every report format is converted to.
The model has two hierarchies over the same lines:
* The **physical** hierarchy - :class:`CoverageSummary`, :class:`Directory`, :class:`File` - is built from the file
paths a report names. A file holds its executable lines; every format has them.
* The **logical** hierarchy holds the language units a report names - :class:`Package`, :class:`Module`,
:class:`SourceFile`, :class:`Class`, :class:`Function`, :class:`Method` -, each spanning its file from a first to a
last :class:`Line`, so both hierarchies count the same lines.
A :class:`Line` and a :class:`Branch` carry a :class:`LineCoverageStatus` and - if the report says - a count: how
often the line ran, or the branch was taken. :meth:`CoverageSummary.Aggregate` computes the counters of every file,
directory and unit.
The report formats have models of their own, which convert to this one:
.. seealso::
:mod:`pyEDAA.Reports.CodeCoverage.Cobertura`
|rarr| The Cobertura XML format, as written e.g. by coverage.py (``coverage xml``) or gcovr (``--cobertura``).
:mod:`pyEDAA.Reports.CodeCoverage.CoveragePy`
|rarr| coverage.py's JSON format (``coverage json``).
:mod:`pyEDAA.Reports.CodeCoverage.GHDL`
|rarr| GHDL's JSON coverage file (``ghdl -r --coverage``).
:mod:`pyEDAA.Reports.CodeCoverage.UCIS`
|rarr| The XML interchange format of the Accellera UCIS standard, as written e.g. by pyucis (``pyucis convert``).
:mod:`pyEDAA.Reports.CodeCoverage.Gcov`
|rarr| GCC's gcov JSON format (``gcov --json-format``).
:mod:`pyEDAA.Reports.CodeCoverage.LCOV`
|rarr| lcov's tracefile format, as written e.g. by lcov (``lcov --capture``) or llvm-cov
(``llvm-cov export -format=lcov``).
:mod:`pyEDAA.Reports.CodeCoverage.JaCoCo`
|rarr| JaCoCo's XML format, as written e.g. by Gradle's task ``jacocoTestReport``.
:mod:`pyEDAA.Reports.CodeCoverage.AldecUCDB`
|rarr| Aldec's UCDB XML format, as exported by ``acdb2xml`` of Riviera-PRO or Active-HDL.
:mod:`pyEDAA.Reports.CodeCoverage.QuestaSim`
|rarr| QuestaSim's code coverage report XML (``vcover report -xml -details``).
:mod:`pyEDAA.Reports.CodeCoverage.LLVM`
|rarr| LLVM's JSON code coverage export (``llvm-cov export``), e.g. of Clang's source-based code coverage.
"""
from __future__ import annotations
from datetime import timedelta
from enum import Enum
from pathlib import Path
from typing import Callable, ClassVar, Generator, Iterable, Optional as Nullable
from pyTooling.Common import getFullyQualifiedName, getTypeName
from pyTooling.Decorators import export, readonly
from pyTooling.Exceptions import AlreadyInHierarchyError, DuplicateElementError
from pyTooling.MetaClasses import ExtendedType, abstractclass, abstractmethod
from pyEDAA.Reports import ReportException
[docs]
@export
class CodeCoverageError(ReportException):
"""Base-exception of the code coverage data model and its report formats."""
[docs]
@export
class AlreadyInCoverageReportError(CodeCoverageError, AlreadyInHierarchyError):
"""The exception is raised when an element is added to an element, but it already has a parent."""
[docs]
@export
class DuplicateDirectoryError(CodeCoverageError, DuplicateElementError):
"""The exception is raised when a directory already contains a directory or a file of the same name."""
[docs]
@export
class DuplicateFileError(CodeCoverageError, DuplicateElementError):
"""The exception is raised when a directory or a report already contains a file or a directory of the same name."""
[docs]
@export
class DuplicateUnitError(CodeCoverageError, DuplicateElementError):
"""The exception is raised when a unit or the report's root already contains a unit of the same name."""
[docs]
@export
class DuplicateLineError(CodeCoverageError, DuplicateElementError):
"""The exception is raised when a file already has a line of the same number."""
[docs]
@export
class LineCoverageStatus(Enum):
"""The coverage state of a line, a branch or a unit, as a report states it."""
Unknown = 0 #: The report doesn't say.
Uncovered = 1 #: The line never ran, the branch was never taken, the unit was never called.
PartiallyCovered = 2 #: The line ran, but not all of its branches were taken.
Covered = 3 #: The line ran, the branch was taken, the unit was called.
Excluded = 4 #: Excluded from the measurement, e.g. by a pragma comment.
[docs]
@export
class Base(metaclass=ExtendedType, slots=True):
"""
Base-class of every element of the code coverage model: a reference to the element containing it, and to the report's
root.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: The types a parent may have; assigned by each class having a parent.
_parent: Nullable[Base] #: The element containing this one, or ``None``.
_root: Nullable[CoverageSummary] #: The report's root, or ``None`` while the element isn't part of a report.
[docs]
def __init__(self, *, parent: Nullable[Base] = None) -> None:
"""
Initialize an element with its parent and the parent's root.
The parent doesn't list the element yet: the class setting the field the parent stores it by - a name, a line
number - adds it with ``parent._AddElement(self)``.
:param parent: Optional, the element containing this one. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of a type this class declares in :attr:`_PARENT_TYPE`.
"""
if parent is None:
self._parent = None
self._root = None
elif not isinstance(parent, self._PARENT_TYPE):
typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
else:
self._parent = parent
self._root = parent._root
@property
def Parent(self) -> Nullable[Base]:
"""
Property to access the element containing this one (:attr:`_parent`).
Assigning a parent adds this element to it, and sets the parent's root as the root of this element and of every
element below it.
:returns: The parent, or ``None``.
:raises ValueError: If ``None`` is assigned.
:raises TypeError: If the assigned parent isn't of a type this class declares in
:attr:`_PARENT_TYPE`.
:raises TypeError: If a parent is assigned to a :class:`CoverageSummary`, which has no parent.
:raises AlreadyInCoverageReportError: If the element already has a parent.
:raises DuplicateDirectoryError: If the assigned parent already contains a directory of this name.
:raises DuplicateFileError: If the assigned parent already contains a file of this name.
:raises DuplicateUnitError: If the assigned parent already contains a unit of this name.
:raises DuplicateLineError: If the assigned parent already contains a line of this line number.
"""
return self._parent
@Parent.setter
def Parent(self, parent: Base) -> None:
if parent is None:
raise ValueError("Parameter 'parent' is None.")
elif not isinstance(parent, self._PARENT_TYPE):
typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
elif self._parent is not None:
raise AlreadyInCoverageReportError(f"{getTypeName(self)} already has a parent.")
parent._AddElement(self)
self._parent = parent
self._SetRoot(parent._root)
@readonly
def Root(self) -> Nullable[CoverageSummary]:
"""
Read-only property to access the report's root (:attr:`_root`).
The root is maintained by :attr:`Parent`: assigning a parent sets it for this element and every element below it.
:returns: The root, or ``None`` while the element isn't part of a report.
"""
return self._root
[docs]
def _SetRoot(self, root: Nullable[CoverageSummary]) -> None:
"""
Set the report's root of this element.
A class with child elements extends it to set the root of its children too.
:param root: The report's root, or ``None`` while the element isn't part of a report.
"""
self._root = root
[docs]
@export
class BaseWithStatus(Base):
"""
Base-class of the elements with a coverage state and a count: lines, branches and units.
"""
_status: LineCoverageStatus #: The coverage state.
_coverageCount: Nullable[int] #: How often it ran, was taken or was called, if the report says.
[docs]
def __init__(self, status: LineCoverageStatus, coverageCount: Nullable[int], *, parent: Nullable[Base]) -> None:
"""
Initialize the parent, the coverage state and the count.
A count of ``0`` is uncovered, a positive count covered.
:param status: The coverage state.
:param coverageCount: How often the line ran, the branch was taken or the unit was called; ``None``, if the report
doesn't say.
:param parent: The element containing this one, or ``None``.
:raises TypeError: If parameter ``parent`` isn't of a type the class declares in :attr:`_PARENT_TYPE`.
:raises ValueError: If parameter ``status`` is ``None``.
:raises TypeError: If parameter ``status`` isn't of type :class:`LineCoverageStatus`.
:raises TypeError: If parameter ``coverageCount`` isn't of type :class:`int`.
:raises ValueError: If parameter ``coverageCount`` is negative.
:raises ValueError: If parameter ``coverageCount`` contradicts parameter ``status``.
"""
super().__init__(parent=parent)
if status is None:
raise ValueError("Parameter 'status' is None.")
elif not isinstance(status, LineCoverageStatus):
ex = TypeError("Parameter 'status' is not of type 'LineCoverageStatus'.")
ex.add_note(f"Got type '{getFullyQualifiedName(status)}'.")
raise ex
if coverageCount is not None:
if not isinstance(coverageCount, int):
ex = TypeError("Parameter 'coverageCount' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(coverageCount)}'.")
raise ex
elif coverageCount < 0:
ex = ValueError("Parameter 'coverageCount' is negative.")
ex.add_note(f"Got value '{coverageCount}'.")
raise ex
elif (coverageCount == 0 and status in (LineCoverageStatus.Covered, LineCoverageStatus.PartiallyCovered)) or \
(coverageCount > 0 and status is LineCoverageStatus.Uncovered):
ex = ValueError("Parameter 'coverageCount' contradicts parameter 'status'.")
ex.add_note(f"Got count '{coverageCount}' for status '{status.name}'.")
raise ex
self._status = status
self._coverageCount = coverageCount
@readonly
def Status(self) -> LineCoverageStatus:
"""
Read-only property to access the coverage state (:attr:`_status`).
:returns: The coverage state; :attr:`LineCoverageStatus.Unknown`, if the report doesn't say.
"""
return self._status
@readonly
def CoverageCount(self) -> Nullable[int]:
"""
Read-only property to access how often it ran, was taken or was called (:attr:`_coverageCount`).
:returns: The count, or ``None`` if the report doesn't say.
"""
return self._coverageCount
[docs]
@export
class CoverageCountersMixin(metaclass=ExtendedType, mixin=True):
"""
A mixin-class adding the counters of lines and branches, computed from the lines of a file or a unit, or summed over
a directory's children.
The counters are zero until :meth:`BaseWithPath.Aggregate` - of a directory or a file - or :meth:`Unit.Aggregate`
computed them.
"""
_totalLines: int #: Number of executable lines, without the excluded ones.
_coveredLines: int #: Number of executable lines, which ran.
_excludedLines: int #: Number of lines excluded from the measurement.
_partialLines: int #: Number of lines, which ran without taking all their branches.
_totalBranches: int #: Number of branches.
_coveredBranches: int #: Number of branches, which were taken.
[docs]
def __init__(self) -> None:
"""
Initialize the counters to zero.
"""
self._ResetCounters()
[docs]
def _ResetCounters(self) -> None:
"""
Set the counters to zero.
"""
self._totalLines = 0
self._coveredLines = 0
self._excludedLines = 0
self._partialLines = 0
self._totalBranches = 0
self._coveredBranches = 0
[docs]
def _CountLines(self, lines: Iterable[Line]) -> None:
"""
Set the counters to the counts of lines.
A line's covered branches are those its :meth:`Line.Aggregate` computed.
:param lines: The lines.
"""
self._ResetCounters()
for line in lines:
if line._status is LineCoverageStatus.Excluded:
self._excludedLines += 1
continue
self._totalLines += 1
self._totalBranches += len(line._branches)
self._coveredBranches += line._coveredBranches
if line._status is LineCoverageStatus.Covered:
self._coveredLines += 1
elif line._status is LineCoverageStatus.PartiallyCovered:
self._coveredLines += 1
self._partialLines += 1
@readonly
def TotalLines(self) -> int:
"""
Read-only property to access the number of executable lines, without the excluded ones (:attr:`_totalLines`).
:returns: The number of executable lines.
"""
return self._totalLines
@readonly
def CoveredLines(self) -> int:
"""
Read-only property to access the number of executable lines, which ran (:attr:`_coveredLines`).
:returns: The number of covered lines, including the partially covered ones.
"""
return self._coveredLines
@readonly
def MissingLines(self) -> int:
"""
Read-only property to return the number of executable lines, which never ran.
:returns: :attr:`TotalLines` minus :attr:`CoveredLines`.
"""
return self._totalLines - self._coveredLines
@readonly
def ExcludedLines(self) -> int:
"""
Read-only property to access the number of lines excluded from the measurement (:attr:`_excludedLines`).
:returns: The number of excluded lines.
"""
return self._excludedLines
@readonly
def PartialLines(self) -> int:
"""
Read-only property to access the number of lines, which ran without taking all their branches
(:attr:`_partialLines`).
:returns: The number of partially covered lines.
"""
return self._partialLines
@readonly
def TotalBranches(self) -> int:
"""
Read-only property to access the number of branches (:attr:`_totalBranches`).
:returns: The number of branches.
"""
return self._totalBranches
@readonly
def CoveredBranches(self) -> int:
"""
Read-only property to access the number of branches, which were taken (:attr:`_coveredBranches`).
:returns: The number of covered branches.
"""
return self._coveredBranches
@readonly
def MissingBranches(self) -> int:
"""
Read-only property to return the number of branches, which were never taken.
:returns: :attr:`TotalBranches` minus :attr:`CoveredBranches`.
"""
return self._totalBranches - self._coveredBranches
@readonly
def LineCoverage(self) -> float:
"""
Read-only property to return the line coverage: the ratio of covered to executable lines.
:returns: The line coverage in range 0.0..1.0; ``1.0`` if there is no executable line.
"""
return 1.0 if self._totalLines == 0 else self._coveredLines / self._totalLines
@readonly
def BranchCoverage(self) -> float:
"""
Read-only property to return the branch coverage: the ratio of taken branches to all branches.
:returns: The branch coverage in range 0.0..1.0; ``1.0`` if there is no branch.
"""
return 1.0 if self._totalBranches == 0 else self._coveredBranches / self._totalBranches
@readonly
def Coverage(self) -> float:
"""
Read-only property to return the combined coverage of lines and branches, as coverage.py computes it.
:returns: Covered lines plus taken branches, divided by executable lines plus branches, in range 0.0..1.0;
``1.0`` if there is neither.
"""
total = self._totalLines + self._totalBranches
return 1.0 if total == 0 else (self._coveredLines + self._coveredBranches) / total
[docs]
def _AggregateCounters(self, other: CoverageCountersMixin) -> None:
"""
Add the counters of another directory, file or unit to this one's.
:param other: The other directory, file or unit, aggregated.
"""
self._totalLines += other._totalLines
self._coveredLines += other._coveredLines
self._excludedLines += other._excludedLines
self._partialLines += other._partialLines
self._totalBranches += other._totalBranches
self._coveredBranches += other._coveredBranches
[docs]
@export
class BaseWithPath(Base, CoverageCountersMixin):
"""
Base-class of the physical hierarchy - directories and source files -: a name, a path below the report's root, and
the counters.
Its parent is the :class:`Directory` containing it.
"""
_name: str #: Name of the directory or file.
[docs]
def __init__(self, name: str, *, parent: Nullable[Directory]) -> None:
"""
Initialize the parent, the name and the counters.
:param name: Name of the directory or file.
:param parent: The directory containing this one, or ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Directory`.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
"""
super().__init__(parent=parent)
CoverageCountersMixin.__init__(self)
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
elif name == "":
raise ValueError("Parameter 'name' is empty.")
self._name = name
@readonly
def Name(self) -> str:
"""
Read-only property to access the name of the directory or file (:attr:`_name`).
:returns: The name.
"""
return self._name
@readonly
def Path(self) -> Path:
"""
Read-only property to return the path below the root: the names of the parent directories and the own name.
A file ``Counter.vhdl`` in a directory ``src`` has the path ``src/Counter.vhdl``.
:returns: The path; the name, if there is no parent.
"""
if self._parent is None:
return Path(self._name)
return self._parent.Path / self._name
[docs]
@abstractmethod
def Aggregate(self) -> None:
"""
Compute the counters.
"""
[docs]
@export
class Directory(BaseWithPath):
"""
A directory: its directories and source files, and their summed counters.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: A directory is in a directory; assigned below the class.
_directories: dict[str, Directory] #: The directories in this directory, by name.
_files: dict[str, File] #: The source files in this directory, by name.
[docs]
def __init__(self, name: str, *, parent: Nullable[Directory] = None) -> None:
"""
Initialize a directory, and add it to its parent directory.
:param name: Name of the directory.
:param parent: Optional, the directory containing this one. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Directory`.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises DuplicateDirectoryError: If the parent directory already contains a file or directory of this name.
"""
super().__init__(name, parent=parent)
self._directories = {}
self._files = {}
if parent is not None:
parent._AddElement(self)
[docs]
def _AddElement(self, element: Directory | File) -> None:
"""
Add a directory or file, which names this directory as its parent.
:param element: The directory or file.
:raises DuplicateDirectoryError: If this directory already contains a directory of this name.
:raises DuplicateFileError: If this directory already contains a file of this name.
"""
if isinstance(element, Directory):
elements = self._directories
exception = DuplicateDirectoryError
else:
elements = self._files
exception = DuplicateFileError
if element._name in self._directories or element._name in self._files:
raise exception(f"Directory '{self.Path.as_posix()}' already contains '{element._name}'.")
elements[element._name] = element
[docs]
def _SetRoot(self, root: Nullable[CoverageSummary]) -> None:
"""
Set the report's root of this directory, and of the directories and files in it.
:param root: The report's root, or ``None`` while the directory isn't part of a report.
"""
super()._SetRoot(root)
for directory in self._directories.values():
directory._SetRoot(root)
for file in self._files.values():
file._SetRoot(root)
@readonly
def Directories(self) -> dict[str, Directory]:
"""
Read-only property to access the directories in this directory (:attr:`_directories`).
:returns: The directories, by name.
"""
return self._directories
@readonly
def Files(self) -> dict[str, File]:
"""
Read-only property to access the source files in this directory (:attr:`_files`).
:returns: The files, by name.
"""
return self._files
@readonly
def FileCount(self) -> int:
"""
Read-only property to return the number of source files in this directory and below.
:returns: The number of files.
"""
return len(self._files) + sum(directory.FileCount for directory in self._directories.values())
[docs]
def GetOrAddFile(self, path: Path | str) -> File:
"""
Return the source file at a path below this directory, adding it and the directories on its way, if missing.
A backslash in a string path separates directories too, as a report written on Windows has them.
:param path: The file's path relative to this directory, e.g. ``src/Counter.vhdl``.
:returns: The file.
:raises ValueError: If parameter ``path`` is ``None``.
:raises TypeError: If parameter ``path`` isn't of type :class:`~pathlib.Path` or :class:`str`.
:raises ValueError: If parameter ``path`` names no file.
:raises CodeCoverageError: If a part of the path is a file instead of a directory, or the file's name is a
directory's.
"""
if path is None:
raise ValueError("Parameter 'path' is None.")
elif isinstance(path, str):
path = Path(path.replace("\\", "/"))
elif not isinstance(path, Path):
ex = TypeError("Parameter 'path' is not of type 'Path' or 'str'.")
ex.add_note(f"Got type '{getFullyQualifiedName(path)}'.")
raise ex
parts = [part for part in path.parts if part not in ("", ".", path.anchor)]
if len(parts) == 0:
ex = ValueError("Parameter 'path' names no file.")
ex.add_note(f"Got path '{path}'.")
raise ex
directory = self
for part in parts[:-1]:
if part in directory._files:
raise CodeCoverageError(f"'{(directory.Path / part).as_posix()}' is a file, not a directory.")
elif (subdirectory := directory._directories.get(part)) is None:
subdirectory = Directory(part, parent=directory)
directory = subdirectory
if (file := directory._files.get(parts[-1])) is None:
file = File(parts[-1], parent=directory)
return file
[docs]
def IterateFiles(self, predicate: Nullable[Callable[[File], bool]] = None) -> Generator[File, None, None]:
"""
Iterate all or selected source files in this directory and below.
A directory's files come before its directories' files, each in the order they were added. If parameter
``predicate`` is not None, the given filter function is used to skip files in the generator.
:param predicate: Optional, filter function accepting any file and returning a boolean. Default: ``None``.
:returns: A generator of the files.
"""
if predicate is None:
yield from self._files.values()
for directory in self._directories.values():
yield from directory.IterateFiles()
else:
for file in self._files.values():
if predicate(file):
yield file
for directory in self._directories.values():
yield from directory.IterateFiles(predicate)
[docs]
def Aggregate(self) -> None:
"""
Aggregate the directories and files in this directory, then sum their counters.
"""
self._ResetCounters()
for child in (*self._directories.values(), *self._files.values()):
child.Aggregate()
self._AggregateCounters(child)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the directory for debugging.
A directory ``src`` of 3 files reads ``<Directory src: 3 files, 75.0%>``.
:returns: The directory's path, its number of files and its line coverage.
"""
return f"<Directory {self.Path.as_posix()}: {self.FileCount} files, {self.LineCoverage:.1%}>"
Directory._PARENT_TYPE = (Directory, )
[docs]
@export
class CoverageSummary(Directory):
"""
The root of a code coverage report: the directory the report's file paths are relative to, and the top-level units
of the logical hierarchy.
It is its own root.
"""
_sourceDirectories: list[Path] #: The directories the report names as where the sources were, if any.
_units: dict[str, Unit] #: The top-level units, by name.
[docs]
def __init__(self, name: str, *, sourceDirectories: Nullable[Iterable[Path]] = None) -> None:
"""
Initialize the root of a code coverage report.
:param name: Name of the report, e.g. of the project measured.
:param sourceDirectories: Optional, the directories the report names as where the sources were. Default: none.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises TypeError: If parameter ``sourceDirectories`` isn't iterable.
:raises TypeError: If parameter ``sourceDirectories`` contains an element not of type :class:`~pathlib.Path`.
"""
super().__init__(name)
self._root = self
self._sourceDirectories = []
self._units = {}
if sourceDirectories is not None:
if not isinstance(sourceDirectories, Iterable):
ex = TypeError("Parameter 'sourceDirectories' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(sourceDirectories)}'.")
raise ex
for sourceDirectory in sourceDirectories:
if not isinstance(sourceDirectory, Path):
ex = TypeError("Parameter 'sourceDirectories' contains an element not of type 'Path'.")
ex.add_note(f"Got type '{getFullyQualifiedName(sourceDirectory)}'.")
raise ex
self._sourceDirectories.append(sourceDirectory)
@Base.Parent.setter
def Parent(self, parent: None) -> None:
ex = TypeError(f"A '{getFullyQualifiedName(self)}' has no parent.")
ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
raise ex
[docs]
def _AddElement(self, element: Directory | File | Unit) -> None:
"""
Add a top-level unit, directory or file, which names the report's root as its parent.
:param element: The unit, directory or file.
:raises DuplicateUnitError: If the root already contains a unit of this name.
:raises DuplicateDirectoryError: If the root already contains a directory of this name.
:raises DuplicateFileError: If the root already contains a file of this name.
"""
if not isinstance(element, Unit):
super()._AddElement(element)
elif element._name in self._units:
raise DuplicateUnitError(f"Unit '{element._name}' is added twice to '{self._name}'.")
else:
self._units[element._name] = element
@readonly
def Path(self) -> Path:
"""
Read-only property to return the path below the root, which is the root's own: ``.``.
So the paths of the directories and files below are relative to the root, without its name.
:returns: ``.``
"""
return Path(".")
@readonly
def SourceDirectories(self) -> list[Path]:
"""
Read-only property to access the directories the report names as where the sources were
(:attr:`_sourceDirectories`).
They are the paths on the machine the coverage was measured on, so they may not exist where the report is read.
:returns: The source directories; empty, if the report names none.
"""
return self._sourceDirectories
@readonly
def Units(self) -> dict[str, Unit]:
"""
Read-only property to access the top-level units of the logical hierarchy (:attr:`_units`).
:returns: The units, by name.
"""
return self._units
[docs]
def IterateUnits(self, predicate: Nullable[Callable[[Unit], bool]] = None) -> Generator[Unit, None, None]:
"""
Iterate all or selected units of the logical hierarchy.
A unit comes before its units, each level in the order the units were added. If parameter ``predicate`` is not None,
the given filter function is used to skip units in the generator. A skipped unit's units are still iterated.
:param predicate: Optional, filter function accepting any unit and returning a boolean. Default: ``None``.
:returns: A generator of the units.
"""
for unit in self._units.values():
yield from unit.IterateUnits(predicate)
[docs]
def Aggregate(self) -> None:
"""
Aggregate the physical hierarchy - directories and files -, then the units of the logical hierarchy.
"""
super().Aggregate()
for unit in self._units.values():
unit.Aggregate()
[docs]
@export
class File(BaseWithPath):
"""
A source file: the coverage of its executable lines, and the units of the logical hierarchy it holds.
The lines are a list indexed by line number: index 0 is unused, and a line the report doesn't list - a comment, a
declaration - is ``None``. Lines are iterated in order, and looked up without hashing.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (Directory, ) #: A file is in a directory.
_lines: list[Nullable[Line]] #: The executable lines by line number; ``None`` at index 0 and for gaps.
_lastLineNumber: int #: The last line number the report lists; ``0``, if it lists none.
_units: list[Unit] #: The units naming this file, in the order they were added.
[docs]
def __init__(self, name: str, *, lines: Nullable[Iterable[Line]] = None, parent: Nullable[Directory] = None) -> None:
"""
Initialize a source file, and add it to its directory.
:param name: Name of the file.
:param lines: Optional, the executable lines. Default: ``None``.
:param parent: Optional, the directory containing the file. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Directory`.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises DuplicateFileError: If the directory already contains a file or directory of this name.
:raises TypeError: If parameter ``lines`` isn't iterable.
:raises TypeError: If parameter ``lines`` contains an element not of type :class:`Line`.
:raises DuplicateLineError: If two lines have the same number.
"""
super().__init__(name, parent=parent)
self._units = []
if parent is not None:
parent._AddElement(self)
if lines is None:
self._lines = [None]
self._lastLineNumber = 0
elif not isinstance(lines, Iterable):
ex = TypeError("Parameter 'lines' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(lines)}'.")
raise ex
else:
# check the lines and find the last line number, then allocate the list once at its final size
lineList = []
lastLineNumber = 0
for line in lines:
if not isinstance(line, Line):
ex = TypeError("Parameter 'lines' contains an element not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(line)}'.")
raise ex
lineList.append(line)
if line._lineNumber > lastLineNumber:
lastLineNumber = line._lineNumber
fileLines = [None] * (lastLineNumber + 1)
for line in lineList:
lineNumber = line._lineNumber
if fileLines[lineNumber] is not None:
raise DuplicateLineError(f"Line {lineNumber} of file '{self.Path.as_posix()}' is added twice.")
fileLines[lineNumber] = line
line._parent = self
line._SetRoot(self._root)
self._lines = fileLines
self._lastLineNumber = lastLineNumber
[docs]
def _AddElement(self, line: Line) -> None:
"""
Add a line, which names this file as its parent.
:param line: The line.
:raises DuplicateLineError: If the file already has a line of this number.
"""
lineNumber = line._lineNumber
if (gap := lineNumber - len(self._lines)) >= 0:
if gap > 0:
self._lines.extend([None] * gap)
self._lines.append(line)
elif self._lines[lineNumber] is None:
self._lines[lineNumber] = line
else:
raise DuplicateLineError(f"Line {lineNumber} of file '{self.Path.as_posix()}' is added twice.")
if lineNumber > self._lastLineNumber:
self._lastLineNumber = lineNumber
[docs]
def _SetRoot(self, root: Nullable[CoverageSummary]) -> None:
"""
Set the report's root of this file, and of its lines.
:param root: The report's root, or ``None`` while the file isn't part of a report.
"""
super()._SetRoot(root)
for line in self.IterateLines():
line._SetRoot(root)
@readonly
def Lines(self) -> list[Nullable[Line]]:
"""
Read-only property to access the executable lines (:attr:`_lines`).
The list ends at the last line the report lists. To iterate only the listed lines, use :meth:`IterateLines`.
:returns: The lines, indexed by line number; ``None`` for index 0 and for a line the report doesn't list.
"""
return self._lines
@readonly
def LastLineNumber(self) -> int:
"""
Read-only property to access the number of the last line the report lists (:attr:`_lastLineNumber`).
:returns: The line number; ``0``, if the report lists no line.
"""
return self._lastLineNumber
[docs]
def GetLine(self, lineNumber: int) -> Nullable[Line]:
"""
Return the line of a line number.
:param lineNumber: The line number, counted from 1.
:returns: The line, or ``None`` if the report doesn't list it.
:raises ValueError: If parameter ``lineNumber`` is ``None``.
:raises TypeError: If parameter ``lineNumber`` isn't of type :class:`int`.
:raises ValueError: If parameter ``lineNumber`` is less than 1.
:raises ValueError: If parameter ``lineNumber`` is beyond the last line the report lists (:attr:`LastLineNumber`).
"""
if lineNumber is None:
raise ValueError("Parameter 'lineNumber' is None.")
elif not isinstance(lineNumber, int):
ex = TypeError("Parameter 'lineNumber' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(lineNumber)}'.")
raise ex
elif lineNumber < 1:
ex = ValueError("Parameter 'lineNumber' is less than 1.")
ex.add_note(f"Got value '{lineNumber}'.")
raise ex
elif lineNumber > self._lastLineNumber:
ex = ValueError(f"Parameter 'lineNumber' is beyond the last line of file '{self.Path.as_posix()}'.")
ex.add_note(f"Got value '{lineNumber}' for {self._lastLineNumber} lines.")
raise ex from IndexError(f"Index {lineNumber} is out of range 1..{self._lastLineNumber}.")
return self._lines[lineNumber]
@readonly
def Units(self) -> list[Unit]:
"""
Read-only property to access the units naming this file (:attr:`_units`).
A Python file is named by its module, its classes and its functions.
:returns: The units.
"""
return self._units
[docs]
def IterateLines(
self,
startLine: Nullable[Line] = None,
endLine: Nullable[Line] = None
) -> Generator[Line, None, None]:
"""
Iterate the executable lines of this file from a first to a last line, both included, by line number.
:param startLine: Optional, the first line. Default: ``None``, the file's first line.
:param endLine: Optional, the last line. Default: ``None``, the file's last line.
:returns: A generator of the lines.
:raises TypeError: If parameter ``startLine`` isn't of type :class:`Line`.
:raises ValueError: If parameter ``startLine`` isn't a line of this file.
:raises TypeError: If parameter ``endLine`` isn't of type :class:`Line`.
:raises ValueError: If parameter ``endLine`` isn't a line of this file.
"""
if startLine is None:
first = 1
elif not isinstance(startLine, Line):
ex = TypeError("Parameter 'startLine' is not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(startLine)}'.")
raise ex
elif startLine._parent is not self:
raise ValueError(f"Parameter 'startLine' is not a line of file '{self.Path.as_posix()}'.")
else:
first = startLine._lineNumber
if endLine is None:
last = self._lastLineNumber
elif not isinstance(endLine, Line):
ex = TypeError("Parameter 'endLine' is not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(endLine)}'.")
raise ex
elif endLine._parent is not self:
raise ValueError(f"Parameter 'endLine' is not a line of file '{self.Path.as_posix()}'.")
else:
last = endLine._lineNumber
for lineNumber in range(first, last + 1):
if (line := self._lines[lineNumber]) is not None:
yield line
[docs]
def Aggregate(self) -> None:
"""
Aggregate the file's lines, then compute the counters from them.
"""
lines = list(self.IterateLines())
for line in lines:
line.Aggregate()
self._CountLines(lines)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the file for debugging.
A file ``src/Counter.vhdl`` reads ``<File src/Counter.vhdl: 80.0%>``.
:returns: The file's path and line coverage.
"""
return f"<File {self.Path.as_posix()}: {self.LineCoverage:.1%}>"
[docs]
@export
class Line(BaseWithStatus):
"""
The coverage of an executable line: its coverage state, how often it ran - if the report says -, and its branches.
A report lists only executable lines; a line it doesn't list - a comment, a declaration - has no :class:`Line`. Its
parent is the :class:`File` it is in.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (File, ) #: A line is in a file.
_lineNumber: int #: Line number, counted from 1.
_branches: list[Branch] #: The branches starting at this line.
_coveredBranches: int #: Number of branches, which were taken; zero until :meth:`Aggregate` computed it.
[docs]
def __init__(
self,
lineNumber: int,
status: LineCoverageStatus,
coverageCount: Nullable[int] = None,
branches: Nullable[Iterable[Branch]] = None,
*,
parent: Nullable[File] = None
) -> None:
"""
Initialize a line's coverage, and add it to its file.
:param lineNumber: Line number, counted from 1.
:param status: Coverage state of the line.
:param coverageCount: Optional, how often the line ran, if the report says. Default: ``None``.
:param branches: Optional, the branches starting at this line. Default: ``None``.
:param parent: Optional, the file the line is in. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`File`.
:raises ValueError: If parameter ``status`` is ``None``.
:raises TypeError: If parameter ``status`` isn't of type :class:`LineCoverageStatus`.
:raises TypeError: If parameter ``coverageCount`` isn't of type :class:`int`.
:raises ValueError: If parameter ``coverageCount`` is negative.
:raises ValueError: If parameter ``coverageCount`` contradicts parameter ``status``.
:raises ValueError: If parameter ``lineNumber`` is ``None``.
:raises TypeError: If parameter ``lineNumber`` isn't of type :class:`int`.
:raises ValueError: If parameter ``lineNumber`` is less than 1.
:raises DuplicateLineError: If the file already has a line of this number.
:raises TypeError: If parameter ``branches`` isn't iterable.
:raises TypeError: If parameter ``branches`` contains an element not of type :class:`Branch`.
"""
super().__init__(status, coverageCount, parent=parent)
if lineNumber is None:
raise ValueError("Parameter 'lineNumber' is None.")
elif not isinstance(lineNumber, int):
ex = TypeError("Parameter 'lineNumber' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(lineNumber)}'.")
raise ex
elif lineNumber < 1:
ex = ValueError("Parameter 'lineNumber' is less than 1.")
ex.add_note(f"Got value '{lineNumber}'.")
raise ex
self._lineNumber = lineNumber
self._branches = []
self._coveredBranches = 0
if parent is not None:
parent._AddElement(self)
if branches is not None:
if not isinstance(branches, Iterable):
ex = TypeError("Parameter 'branches' is not iterable.")
ex.add_note(f"Got type '{getFullyQualifiedName(branches)}'.")
raise ex
for branch in branches:
if not isinstance(branch, Branch):
ex = TypeError("Parameter 'branches' contains an element not of type 'Branch'.")
ex.add_note(f"Got type '{getFullyQualifiedName(branch)}'.")
raise ex
branch._parent = self
branch._root = self._root
self._branches.append(branch)
[docs]
def _AddElement(self, branch: Branch) -> None:
"""
Add a branch, which names this line as its parent.
:param branch: The branch.
"""
self._branches.append(branch)
[docs]
def _SetRoot(self, root: Nullable[CoverageSummary]) -> None:
"""
Set the report's root of this line, and of its branches.
:param root: The report's root, or ``None`` while the line isn't part of a report.
"""
super()._SetRoot(root)
for branch in self._branches:
branch._SetRoot(root)
@readonly
def LineNumber(self) -> int:
"""
Read-only property to access the line number (:attr:`_lineNumber`).
:returns: The line number, counted from 1.
"""
return self._lineNumber
@readonly
def Branches(self) -> list[Branch]:
"""
Read-only property to access the branches starting at this line (:attr:`_branches`).
:returns: The branches; empty for a line, which doesn't branch.
"""
return self._branches
@readonly
def CoveredBranches(self) -> int:
"""
Read-only property to access the number of this line's branches, which were taken (:attr:`_coveredBranches`).
:returns: The number of branches with state :attr:`LineCoverageStatus.Covered`; zero until :meth:`Aggregate`
computed it.
"""
return self._coveredBranches
[docs]
def Aggregate(self) -> None:
"""
Compute the number of this line's branches, which were taken.
"""
self._coveredBranches = sum(1 for branch in self._branches if branch._status is LineCoverageStatus.Covered)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the line's coverage for debugging.
Line 12 with one of two branches taken reads ``<Line 12: PartiallyCovered (1/2 branches)>``.
:returns: The line number, the state and the branches.
"""
branches = f" ({self.CoveredBranches}/{len(self._branches)} branches)" if len(self._branches) > 0 else ""
return f"<Line {self._lineNumber}: {self._status.name}{branches}>"
[docs]
@export
class Branch(BaseWithStatus):
"""
A branch of a line: whether it was taken, how often - if the report says -, and where it goes - if the report says.
Its parent is the :class:`Line` it starts at.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (Line, ) #: A branch starts at a line.
_target: Nullable[Line] #: The line the branch goes to, if the report says.
[docs]
def __init__(
self,
status: LineCoverageStatus,
coverageCount: Nullable[int] = None,
target: Nullable[Line] = None,
*,
parent: Nullable[Line] = None
) -> None:
"""
Initialize a branch, and add it to its line.
:param status: Whether the branch was taken.
:param coverageCount: Optional, how often the branch was taken, if the report says. Default: ``None``.
:param target: Optional, the line the branch goes to, if the report says; ``None`` for an exit of a function.
Default: ``None``.
:param parent: Optional, the line the branch starts at. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Line`.
:raises ValueError: If parameter ``status`` is ``None``.
:raises TypeError: If parameter ``status`` isn't of type :class:`LineCoverageStatus`.
:raises TypeError: If parameter ``coverageCount`` isn't of type :class:`int`.
:raises ValueError: If parameter ``coverageCount`` is negative.
:raises ValueError: If parameter ``coverageCount`` contradicts parameter ``status``.
:raises TypeError: If parameter ``target`` isn't of type :class:`Line`.
"""
super().__init__(status, coverageCount, parent=parent)
if target is not None and not isinstance(target, Line):
ex = TypeError("Parameter 'target' is not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(target)}'.")
raise ex
self._target = target
if parent is not None:
parent._AddElement(self)
@readonly
def Target(self) -> Nullable[Line]:
"""
Read-only property to access the line the branch goes to (:attr:`_target`).
:returns: The line, or ``None`` if the report doesn't say or the branch exits the function.
"""
return self._target
[docs]
@export
class Unit(BaseWithStatus, CoverageCountersMixin):
"""
Base-class of the logical hierarchy: a language unit - a package, a module, a class, a function, a method -, the
units it contains, and the lines it spans.
Its parent is the :class:`Unit` containing it, or the report's :class:`CoverageSummary`. A unit spans the lines of
its file from its first to its last line - a language construct wraps the constructs nested in it -, so the
physical and the logical hierarchy count the same lines. A unit without lines, e.g. a package of several files,
counts the lines of the units it contains, each line once.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: A unit is in a unit or the report's root; assigned below the class.
_name: str #: Name of the unit.
_units: dict[str, Unit] #: The units this one contains, by name.
_file: Nullable[File] #: The source file the unit is in, if the report says.
_startLine: Nullable[Line] #: The unit's first line, if the report says.
_endLine: Nullable[Line] #: The unit's last line, if the report says.
[docs]
def __init__(
self,
name: str,
*,
file: Nullable[File] = None,
startLine: Nullable[Line] = None,
endLine: Nullable[Line] = None,
status: LineCoverageStatus = LineCoverageStatus.Unknown,
coverageCount: Nullable[int] = None,
parent: Nullable[Unit | CoverageSummary] = None
) -> None:
"""
Initialize a unit, and add it to its file and to the unit or report containing it.
:param name: Name of the unit.
:param file: Optional, the source file the unit is in. Default: ``None``.
:param startLine: Optional, the unit's first line. Default: ``None``.
:param endLine: Optional, the unit's last line. Default: ``None``.
:param status: Optional, whether the unit was called. Default: :attr:`LineCoverageStatus.Unknown`.
:param coverageCount: Optional, how often the unit was called. Default: ``None``.
:param parent: Optional, the unit or report containing this unit. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Unit` or :class:`CoverageSummary`.
:raises ValueError: If parameter ``status`` is ``None``.
:raises TypeError: If parameter ``status`` isn't of type :class:`LineCoverageStatus`.
:raises TypeError: If parameter ``coverageCount`` isn't of type :class:`int`.
:raises ValueError: If parameter ``coverageCount`` is negative.
:raises ValueError: If parameter ``coverageCount`` contradicts parameter ``status``.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`str`.
:raises ValueError: If parameter ``name`` is empty.
:raises TypeError: If parameter ``file`` isn't of type :class:`File`.
:raises TypeError: If parameter ``startLine`` isn't of type :class:`Line`.
:raises ValueError: If parameter ``startLine`` isn't a line of parameter ``file``.
:raises TypeError: If parameter ``endLine`` isn't of type :class:`Line`.
:raises ValueError: If parameter ``endLine`` isn't a line of parameter ``file``.
:raises ValueError: If parameter ``endLine`` is before parameter ``startLine``.
:raises DuplicateUnitError: If the parent already contains a unit of this name.
"""
super().__init__(status, coverageCount, parent=parent)
CoverageCountersMixin.__init__(self)
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
elif name == "":
raise ValueError("Parameter 'name' is empty.")
if file is not None and not isinstance(file, File):
ex = TypeError("Parameter 'file' is not of type 'File'.")
ex.add_note(f"Got type '{getFullyQualifiedName(file)}'.")
raise ex
if startLine is not None:
if not isinstance(startLine, Line):
ex = TypeError("Parameter 'startLine' is not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(startLine)}'.")
raise ex
elif startLine._parent is not file:
raise ValueError("Parameter 'startLine' is not a line of parameter 'file'.")
if endLine is not None:
if not isinstance(endLine, Line):
ex = TypeError("Parameter 'endLine' is not of type 'Line'.")
ex.add_note(f"Got type '{getFullyQualifiedName(endLine)}'.")
raise ex
elif endLine._parent is not file:
raise ValueError("Parameter 'endLine' is not a line of parameter 'file'.")
elif startLine is not None and endLine._lineNumber < startLine._lineNumber:
ex = ValueError("Parameter 'endLine' is before parameter 'startLine'.")
ex.add_note(f"Got lines {startLine._lineNumber} to {endLine._lineNumber}.")
raise ex
self._name = name
self._units = {}
self._file = file
self._startLine = startLine
self._endLine = endLine
if parent is not None:
parent._AddElement(self)
if file is not None:
file._units.append(self)
[docs]
def _AddElement(self, unit: Unit) -> None:
"""
Add a unit, which names this unit as its parent.
:param unit: The unit.
:raises DuplicateUnitError: If this unit already contains a unit of this name.
"""
if unit._name in self._units:
raise DuplicateUnitError(f"Unit '{unit._name}' is added twice to '{self._name}'.")
self._units[unit._name] = unit
[docs]
def _SetRoot(self, root: Nullable[CoverageSummary]) -> None:
"""
Set the report's root of this unit, and of the units it contains.
:param root: The report's root, or ``None`` while the unit isn't part of a report.
"""
super()._SetRoot(root)
for unit in self._units.values():
unit._SetRoot(root)
@readonly
def Name(self) -> str:
"""
Read-only property to access the unit's name (:attr:`_name`).
:returns: The name.
"""
return self._name
@readonly
def QualifiedName(self) -> str:
"""
Read-only property to return the names of the units from the top down to this one, joined by ``.``.
A method ``Area`` of a class ``Circle`` in a module ``myPackage.Shapes`` has the qualified name
``myPackage.Shapes.Circle.Area``.
:returns: The qualified name.
"""
if isinstance(self._parent, Unit):
return f"{self._parent.QualifiedName}.{self._name}"
return self._name
@readonly
def Units(self) -> dict[str, Unit]:
"""
Read-only property to access the units this one contains (:attr:`_units`).
:returns: The units, by name.
"""
return self._units
@readonly
def File(self) -> Nullable[File]:
"""
Read-only property to access the source file the unit is in (:attr:`_file`).
:returns: The file, or ``None`` if the report doesn't say.
"""
return self._file
@readonly
def StartLine(self) -> Nullable[Line]:
"""
Read-only property to access the unit's first line (:attr:`_startLine`).
:returns: The line of the unit's file, or ``None`` if the report doesn't say.
"""
return self._startLine
@readonly
def EndLine(self) -> Nullable[Line]:
"""
Read-only property to access the unit's last line (:attr:`_endLine`).
:returns: The line of the unit's file, or ``None`` if the report doesn't say.
"""
return self._endLine
[docs]
def IterateLines(self) -> Generator[Line, None, None]:
"""
Iterate the executable lines of this unit's file from its first to its last line, both included.
:returns: A generator of the lines; nothing, if the unit has no file, or no first or last line.
"""
if self._file is not None and self._startLine is not None and self._endLine is not None:
yield from self._file.IterateLines(self._startLine, self._endLine)
[docs]
def IterateUnits(self, predicate: Nullable[Callable[[Unit], bool]] = None) -> Generator[Unit, None, None]:
"""
Iterate this unit and the units it contains, all or selected ones.
This unit comes first, then the units it contains, each level in the order the units were added. If parameter
``predicate`` is not None, the given filter function is used to skip units in the generator. A skipped unit's units
are still iterated.
:param predicate: Optional, filter function accepting any unit and returning a boolean. Default: ``None``.
:returns: A generator of the units.
"""
if predicate is None:
yield self
for unit in self._units.values():
yield from unit.IterateUnits()
else:
if predicate(self):
yield self
for unit in self._units.values():
yield from unit.IterateUnits(predicate)
[docs]
def Aggregate(self) -> None:
"""
Aggregate the units this one contains, then compute the counters from the lines this unit spans.
A unit without first and last line counts the lines the units below it span, each line once. The lines are
aggregated by their files - :meth:`CoverageSummary.Aggregate` does that first.
"""
for unit in self._units.values():
unit.Aggregate()
if self._startLine is not None and self._endLine is not None:
self._CountLines(self.IterateLines())
else:
lines: dict[int, Line] = {}
for unit in self.IterateUnits():
lines.update((id(line), line) for line in unit.IterateLines())
self._CountLines(lines.values())
[docs]
def __repr__(self) -> str:
"""
Return a representation of the unit for debugging.
A method ``Area`` of class ``Circle`` in module ``Shapes`` reads ``<Function Shapes.Circle.Area: 100.0%>``.
:returns: The unit's kind, qualified name and line coverage.
"""
return f"<{getTypeName(self)} {self.QualifiedName}: {self.LineCoverage:.1%}>"
Unit._PARENT_TYPE = (Unit, CoverageSummary)
[docs]
@export
class Package(Unit):
"""
A package: a unit grouping modules.
Python and Java have packages, VHDL has libraries.
"""
[docs]
@export
class Module(Unit):
"""
A module: a unit of a package.
A Python module is one, and so are a VHDL package and a VHDL entity.
"""
[docs]
@export
class SourceFile(Unit):
"""
A source file as a unit, where the file is the language's unit.
A C translation unit is one, and so is a Bash or TCL script.
"""
[docs]
@export
class Class(Unit):
"""
A class.
Python, Java and C++ have classes.
"""
[docs]
@export
class Function(Unit):
"""
A function.
Python and C have functions, VHDL has functions and procedures.
"""
[docs]
@export
class Method(Unit):
"""A method of a class."""
[docs]
@export
@abstractclass
class Document(metaclass=ExtendedType, slots=True):
"""
A code coverage report file, which is read in two steps: analyzed, then converted.
A format's document derives from this class and mixes in the root of the format's model.
"""
_path: Path #: Path to the report file.
_analysisDuration: Nullable[timedelta] #: Duration of :meth:`Analyze`, or ``None`` before it ran.
_conversionDuration: Nullable[timedelta] #: Duration of :meth:`Convert`, or ``None`` before it ran.
[docs]
def __init__(self, reportFile: Path) -> None:
"""
Initialize the report file.
:param reportFile: Path to the report file.
"""
self._path = reportFile
self._analysisDuration = None
self._conversionDuration = None
@readonly
def ReportFile(self) -> Path:
"""
Read-only property to access the path to the report file (:attr:`_path`).
:returns: The report file's path.
"""
return self._path
@readonly
def AnalysisDuration(self) -> Nullable[timedelta]:
"""
Read-only property to access the duration of :meth:`Analyze`: reading, parsing and validating the file
(:attr:`_analysisDuration`).
:returns: The duration, or ``None`` if the file wasn't analyzed yet.
"""
return self._analysisDuration
@readonly
def ModelConversionDuration(self) -> Nullable[timedelta]:
"""
Read-only property to access the duration of :meth:`Convert`: building the report format's model
(:attr:`_conversionDuration`).
:returns: The duration, or ``None`` if the content wasn't converted yet.
"""
return self._conversionDuration
[docs]
@abstractmethod
def Analyze(self) -> None:
"""
Read, parse and validate the report file.
"""
[docs]
@abstractmethod
def Convert(self) -> None:
"""
Convert the analyzed content to the report format's model.
"""
[docs]
@abstractmethod
def ToCoverageSummary(self) -> CoverageSummary:
"""
Convert the report format's model to the common code coverage model, and aggregate it.
:returns: The report's root of the common model.
"""