# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2024-2026 Electronic Design Automation Abstraction (EDA²) #
# Copyright 2023-2023 Patrick Lehmann - Bötzingen, Germany #
# #
# 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 code documentation coverage data model for Python code.**
"""
from pathlib import Path
from typing import Optional as Nullable, Iterable, Dict, Union, Tuple, List
from pyTooling.Decorators import export, readonly
from pyTooling.MetaClasses import ExtendedType
from pyEDAA.Reports.DocumentationCoverage import Class, Module, Package, CoverageState, DocCoverageException
[docs]
@export
class Coverage(metaclass=ExtendedType, mixin=True):
"""
This base-class for :class:`ClassCoverage` and :class:`AggregatedCoverage` represents a basic set of documentation coverage metrics.
Besides the *total* number of coverable items, it distinguishes items as *excluded*, *ignored*, and *expected*. |br|
Expected items are further distinguished into *covered* and *uncovered* items. |br|
If no item is expected, then *coverage* is always 100 |%|.
All coverable items
total = excluded + ignored + expected
All expected items
expected = covered + uncovered
Coverage [0.00..1.00]
coverage = covered / expected
"""
_total: int
_excluded: int
_ignored: int
_expected: int
_covered: int
_uncovered: int
_coverage: float
[docs]
def __init__(self) -> None:
self._total = 0
self._excluded = 0
self._ignored = 0
self._expected = 0
self._covered = 0
self._uncovered = 0
self._coverage = -1.0
@readonly
def Total(self) -> int:
return self._total
@readonly
def Excluded(self) -> int:
return self._excluded
@readonly
def Ignored(self) -> int:
return self._ignored
@readonly
def Expected(self) -> int:
return self._expected
@readonly
def Covered(self) -> int:
return self._covered
@readonly
def Uncovered(self) -> int:
return self._uncovered
@readonly
def Coverage(self) -> float:
return self._coverage
def CalculateCoverage(self) -> None:
self._uncovered = self._expected - self._covered
if self._expected != 0:
self._coverage = self._covered / self._expected
else:
self._coverage = 1.0
def _CountCoverage(self, iterator: Iterable[CoverageState]) -> Tuple[int, int, int, int, int]:
total = 0
excluded = 0
ignored = 0
expected = 0
covered = 0
for coverageState in iterator:
if coverageState is CoverageState.Unknown:
raise Exception(f"")
total += 1
if CoverageState.Excluded in coverageState:
excluded += 1
elif CoverageState.Ignored in coverageState:
ignored += 1
expected += 1
if CoverageState.Covered in coverageState:
covered += 1
return total, excluded, ignored, expected, covered
[docs]
@export
class AggregatedCoverage(Coverage, mixin=True):
"""
This base-class for :class:`ModuleCoverage` and :class:`PackageCoverage` represents an extended set of documentation coverage metrics, especially with aggregated metrics.
As inherited from :class:`~Coverage`, it provides the *total* number of coverable items, which are distinguished into
*excluded*, *ignored*, and *expected* items. |br|
Expected items are further distinguished into *covered* and *uncovered* items. |br|
If no item is expected, then *coverage* and *aggregated coverage* are always 100 |%|.
In addition, all previously mentioned metrics are collected as *aggregated...*, too. |br|
All coverable items
total = excluded + ignored + expected
All expected items
expected = covered + uncovered
Coverage [0.00..1.00]
coverage = covered / expected
"""
_file: Path
_aggregatedTotal: int
_aggregatedExcluded: int
_aggregatedIgnored: int
_aggregatedExpected: int
_aggregatedCovered: int
_aggregatedUncovered: int
_aggregatedCoverage: float
[docs]
def __init__(self, file: Path) -> None:
super().__init__()
self._file = file
@readonly
def File(self) -> Path:
return self._file
@readonly
def AggregatedTotal(self) -> int:
return self._aggregatedTotal
@readonly
def AggregatedExcluded(self) -> int:
return self._aggregatedExcluded
@readonly
def AggregatedIgnored(self) -> int:
return self._aggregatedIgnored
@readonly
def AggregatedExpected(self) -> int:
return self._aggregatedExpected
@readonly
def AggregatedCovered(self) -> int:
return self._aggregatedCovered
@readonly
def AggregatedUncovered(self) -> int:
return self._aggregatedUncovered
@readonly
def AggregatedCoverage(self) -> float:
return self._aggregatedCoverage
def Aggregate(self) -> None:
if self._aggregatedExpected != 0:
self._aggregatedCoverage = self._aggregatedCovered / self._aggregatedExpected
else:
self._aggregatedCoverage = 1.0
[docs]
@export
class ClassCoverage(Class, Coverage):
"""
This class represents the class documentation coverage for Python classes.
"""
_fields: Dict[str, CoverageState]
_methods: Dict[str, CoverageState]
_classes: Dict[str, "ClassCoverage"]
[docs]
def __init__(self, name: str, parent: Union["PackageCoverage", "ClassCoverage", None] = None) -> None:
super().__init__(name, parent)
Coverage.__init__(self)
if parent is not None:
parent._classes[name] = self
self._fields = {}
self._methods = {}
self._classes = {}
@readonly
def Fields(self) -> Dict[str, CoverageState]:
return self._fields
@readonly
def Methods(self) -> Dict[str, CoverageState]:
return self._methods
@readonly
def Classes(self) -> Dict[str, "ClassCoverage"]:
return self._classes
def CalculateCoverage(self) -> None:
for cls in self._classes.values():
cls.CalculateCoverage()
self._total, self._excluded, self._ignored, self._expected, self._covered = \
self._CountCoverage(zip(
self._fields.values(),
self._methods.values()
))
super().CalculateCoverage()
[docs]
def __str__(self) -> str:
return f"<ClassCoverage - tot:{self._total}, ex:{self._excluded}, ig:{self._ignored}, exp:{self._expected}, cov:{self._covered}, un:{self._uncovered} => {self._coverage:.1%}>"
[docs]
@export
class ModuleCoverage(Module, AggregatedCoverage):
"""
This class represents the module documentation coverage for Python modules.
"""
_variables: Dict[str, CoverageState]
_functions: Dict[str, CoverageState]
_classes: Dict[str, ClassCoverage]
[docs]
def __init__(self, name: str, file: Path, parent: Nullable["PackageCoverage"] = None) -> None:
super().__init__(name, parent)
AggregatedCoverage.__init__(self, file)
if parent is not None:
parent._modules[name] = self
self._file = file
self._variables = {}
self._functions = {}
self._classes = {}
@readonly
def Variables(self) -> Dict[str, CoverageState]:
return self._variables
@readonly
def Functions(self) -> Dict[str, CoverageState]:
return self._functions
@readonly
def Classes(self) -> Dict[str, ClassCoverage]:
return self._classes
def CalculateCoverage(self) -> None:
for cls in self._classes.values():
cls.CalculateCoverage()
self._total, self._excluded, self._ignored, self._expected, self._covered = \
self._CountCoverage(zip(
self._variables.values(),
self._functions.values()
))
super().CalculateCoverage()
def Aggregate(self) -> None:
self._aggregatedTotal = self._total
self._aggregatedExcluded = self._excluded
self._aggregatedIgnored = self._ignored
self._aggregatedExpected = self._expected
self._aggregatedCovered = self._covered
self._aggregatedUncovered = self._uncovered
for cls in self._classes.values():
self._aggregatedTotal += cls._total
self._aggregatedExcluded += cls._excluded
self._aggregatedIgnored += cls._ignored
self._aggregatedExpected += cls._expected
self._aggregatedCovered += cls._covered
self._aggregatedUncovered += cls._uncovered
super().Aggregate()
[docs]
def __str__(self) -> str:
return f"<ModuleCoverage - tot:{self._total}|{self._aggregatedTotal}, ex:{self._excluded}|{self._aggregatedExcluded}, ig:{self._ignored}|{self._aggregatedIgnored}, exp:{self._expected}|{self._aggregatedExpected}, cov:{self._covered}|{self._aggregatedCovered}, un:{self._uncovered}|{self._aggregatedUncovered} => {self._coverage:.1%}|{self._aggregatedCoverage:.1%}>"
[docs]
@export
class PackageCoverage(Package, AggregatedCoverage):
"""
This class represents the package documentation coverage for Python packages.
"""
_fileCount: int
_variables: Dict[str, CoverageState]
_functions: Dict[str, CoverageState]
_classes: Dict[str, ClassCoverage]
_modules: Dict[str, ModuleCoverage]
_packages: Dict[str, "PackageCoverage"]
[docs]
def __init__(self, name: str, file: Path, parent: Nullable["PackageCoverage"] = None) -> None:
super().__init__(name, parent)
AggregatedCoverage.__init__(self, file)
if parent is not None:
parent._packages[name] = self
self._file = file
self._fileCount = 1
self._variables = {}
self._functions = {}
self._classes = {}
self._modules = {}
self._packages = {}
@readonly
def FileCount(self) -> int:
return self._fileCount
@readonly
def Variables(self) -> Dict[str, CoverageState]:
return self._variables
@readonly
def Functions(self) -> Dict[str, CoverageState]:
return self._functions
@readonly
def Classes(self) -> Dict[str, ClassCoverage]:
return self._classes
@readonly
def Modules(self) -> Dict[str, ModuleCoverage]:
return self._modules
@readonly
def Packages(self) -> Dict[str, "PackageCoverage"]:
return self._packages
def __getitem__(self, key: str) -> Union["PackageCoverage", ModuleCoverage]:
try:
return self._modules[key]
except KeyError:
return self._packages[key]
def CalculateCoverage(self) -> None:
for cls in self._classes.values():
cls.CalculateCoverage()
for mod in self._modules.values():
mod.CalculateCoverage()
for pkg in self._packages.values():
pkg.CalculateCoverage()
self._total, self._excluded, self._ignored, self._expected, self._covered = \
self._CountCoverage(zip(
self._variables.values(),
self._functions.values()
))
super().CalculateCoverage()
def Aggregate(self) -> None:
self._fileCount = len(self._modules) + 1
self._aggregatedTotal = self._total
self._aggregatedExcluded = self._excluded
self._aggregatedIgnored = self._ignored
self._aggregatedExpected = self._expected
self._aggregatedCovered = self._covered
self._aggregatedUncovered = self._uncovered
for pkg in self._packages.values():
pkg.Aggregate()
self._fileCount += pkg._fileCount
self._aggregatedTotal += pkg._total
self._aggregatedExcluded += pkg._excluded
self._aggregatedIgnored += pkg._ignored
self._aggregatedExpected += pkg._expected
self._aggregatedCovered += pkg._covered
self._aggregatedUncovered += pkg._uncovered
for mod in self._modules.values():
mod.Aggregate()
self._aggregatedTotal += mod._total
self._aggregatedExcluded += mod._excluded
self._aggregatedIgnored += mod._ignored
self._aggregatedExpected += mod._expected
self._aggregatedCovered += mod._covered
self._aggregatedUncovered += mod._uncovered
super().Aggregate()
[docs]
def __str__(self) -> str:
return f"<PackageCoverage - tot:{self._total}|{self._aggregatedTotal}, ex:{self._excluded}|{self._aggregatedExcluded}, ig:{self._ignored}|{self._aggregatedIgnored}, exp:{self._expected}|{self._aggregatedExpected}, cov:{self._covered}|{self._aggregatedCovered}, un:{self._uncovered}|{self._aggregatedUncovered} => {self._coverage:.1%}|{self._aggregatedCoverage:.1%}>"
[docs]
@export
class DocStrCoverageError(DocCoverageException):
pass
[docs]
@export
class DocStrCoverage(metaclass=ExtendedType):
"""
A wrapper class for the docstr_coverage package and it's analyzer producing a documentation coverage model.
"""
from docstr_coverage import ResultCollection
_packageName: str
_searchDirectory: Path
_moduleFiles: List[Path]
_coverageReport: ResultCollection
[docs]
def __init__(self, packageName: str, directory: Path) -> None:
if not directory.exists():
raise DocStrCoverageError(f"Package source directory '{directory}' does not exist.") from FileNotFoundError(f"Directory '{directory}' does not exist.")
self._searchDirectory = directory
self._packageName = packageName
self._moduleFiles = [file for file in directory.glob("**/*.py")]
@readonly
def SearchDirectories(self) -> Path:
return self._searchDirectory
@readonly
def PackageName(self) -> str:
return self._packageName
@readonly
def ModuleFiles(self) -> List[Path]:
return self._moduleFiles
@readonly
def CoverageReport(self) -> ResultCollection:
return self._coverageReport
def Analyze(self) -> ResultCollection:
from docstr_coverage import analyze, ResultCollection
self._coverageReport: ResultCollection = analyze(self._moduleFiles, show_progress=False)
return self._coverageReport
def Convert(self) -> PackageCoverage:
from docstr_coverage.result_collection import FileCount
rootPackageCoverage = PackageCoverage(self._packageName, self._searchDirectory / "__init__.py")
for key, value in self._coverageReport.files():
path: Path = key.relative_to(self._searchDirectory)
perFileResult: FileCount = value.count_aggregate()
moduleName = path.stem
modulePath = path.parent.parts
currentCoverageObject: AggregatedCoverage = rootPackageCoverage
for packageName in modulePath:
try:
currentCoverageObject = currentCoverageObject[packageName]
except KeyError:
currentCoverageObject = PackageCoverage(packageName, path, currentCoverageObject)
if moduleName != "__init__":
currentCoverageObject = ModuleCoverage(moduleName, path, currentCoverageObject)
currentCoverageObject._expected = perFileResult.needed
currentCoverageObject._covered = perFileResult.found
currentCoverageObject._uncovered = perFileResult.missing
if currentCoverageObject._expected != 0:
currentCoverageObject._coverage = currentCoverageObject._covered / currentCoverageObject._expected
else:
currentCoverageObject._coverage = 1.0
if currentCoverageObject._uncovered != currentCoverageObject._expected - currentCoverageObject._covered:
currentCoverageObject._coverage = -2.0
return rootPackageCoverage
del ResultCollection