# ==================================================================================================================== #
# _____ _ _ ____ _ _ #
# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___| _ __ | |__ (_)_ __ __ __ #
# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` | \___ \| '_ \| '_ \| | '_ \\ \/ / #
# | |_) | |_| || | (_) | (_) | | | | | | (_| |_ ___) | |_) | | | | | | | |> < #
# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____/| .__/|_| |_|_|_| |_/_/\_\ #
# |_| |___/ |___/ |_| #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-2026 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 #
# ==================================================================================================================== #
#
"""
A page per directory and per source file of a code coverage report, generated without a source file.
A report declared in ``pyTooling_CodeCoverage_Packages`` with the key ``pages`` gets a document per directory and per
source file, named below that key's document name by its path in the report, e.g. ``<pages>/src/Counter.vhdl``. A
chain of directories holding no file and one directory each is one page, e.g. ``pyTooling/Sphinx`` (see
:func:`~pyTooling.Sphinx.CodeCoverage.compactDirectory`).
* A directory's page shows its counters, and tables of its directories and files, each linked to its page.
* A source file's page shows its counters, its missed lines, and its listing: the source read from the report's
``sources`` directory, syntax highlighted with the Pygments lexer of the file's name, each line marked by its
coverage state.
The pages are built by the machinery of :class:`~pyTooling.Sphinx.Pages.ReportPages`, so they are in the navigation
below the directive ``report:code-coverage``. Every directory and file with a page is an object of domain ``report``,
referred to by the role ``:cov:`` by its path - e.g. ``:cov:`src/Counter.vhdl``` -, which may end in ``#<line>`` to
link to a line of a file's listing.
.. seealso::
:ref:`DIR/CodeCoverage/Pages`
|rarr| The pages and the role, with examples.
:mod:`pyTooling.Sphinx.Pages`
|rarr| The pages of a report: document names, registration, generation and navigation.
"""
from __future__ import annotations
from pathlib import Path
from typing import TYPE_CHECKING, ClassVar, Iterable, Optional as Nullable, Union
from docutils import nodes
from pygments.lexers import get_lexer_for_filename
from pygments.lexers.special import TextLexer
from pygments.token import STANDARD_TYPES, _TokenType
from pygments.util import ClassNotFound
from sphinx.application import Sphinx
from sphinx.util.logging import getLogger
from pyTooling.Common import getTypeName
from pyTooling.Decorators import export
from pyTooling.Sphinx import ReportExtensionError
from pyTooling.Sphinx.CodeCoverage import CodeCoverageBase, compactDirectory, compactedName, isCompacted
from pyTooling.Sphinx.Node import CoverageListing
from pyTooling.Sphinx.Pages import ReportPages
if TYPE_CHECKING: # pragma: no cover
# pyEDAA.Reports is an optional dependency (extra 'reports'), imported where a report is read.
from pyEDAA.Reports.CodeCoverage import BaseWithPath, CoverageSummary, Directory, File
__all__ = ["LINE_STATES"]
#: The state a listing marks a line with, by the name of the line's
#: :class:`~pyEDAA.Reports.CodeCoverage.LineCoverageStatus`.
LINE_STATES = {
"Covered": "covered",
"PartiallyCovered": "partial",
"Uncovered": "uncovered",
"Excluded": "excluded",
"Unknown": "",
}
[docs]
@export
def tokenClass(tokenType: _TokenType) -> str:
"""
Return the short CSS class Pygments writes for a token type, as its HTML formatter does.
A keyword gets ``k``. A token type without a class of its own gets its nearest parent's class, extended by the names
below it.
:param tokenType: The token type.
:returns: The CSS class; empty for plain text.
"""
suffix = ""
while (name := STANDARD_TYPES.get(tokenType)) is None:
suffix = f"-{tokenType[-1]}{suffix}"
tokenType = tokenType.parent
return f"{name}{suffix}"
[docs]
@export
def tokenizeSource(source: str, fileName: str) -> list[list[tuple[str, str]]]:
"""
Lex a source file with the Pygments lexer of its file name, and split the tokens into lines.
The whole file is lexed, as a token may span lines - e.g. a doc-string -; such a token is split at the line ends, each
part keeping its class. A file name without a lexer is lexed as plain text.
:param source: The source file's content.
:param fileName: The source file's name, choosing the lexer.
:returns: Per line, its tokens as ``(CSS class, text)`` pairs.
"""
try:
lexer = get_lexer_for_filename(fileName, stripnl=False, ensurenl=True)
except ClassNotFound:
lexer = TextLexer(stripnl=False, ensurenl=True)
lines: list[list[tuple[str, str]]] = [[]]
for tokenType, value in lexer.get_tokens(source):
cssClass = tokenClass(tokenType)
for index, part in enumerate(value.split("\n")):
if index > 0:
lines.append([])
if part != "":
lines[-1].append((cssClass, part))
return lines[:-1] if len(lines[-1]) == 0 else lines
[docs]
@export
def createListing(file: File, sources: Path, anchors: bool) -> Union[CoverageListing, nodes.paragraph]:
"""
Create a source file's listing: its lines, syntax highlighted, each marked by its coverage state.
A report naming a line beyond the source file's end was measured on another version of the file; this is logged as
a warning.
:param file: The file of the report.
:param sources: The directory the report's file paths are relative to.
:param anchors: Whether a line gets the ID ``L<number>``, so the role ``:cov:`` can link to it.
:returns: The listing; or a paragraph saying so, if the source file can't be read.
"""
sourceFile = sources / file.Path
try:
source = sourceFile.read_text(encoding="utf-8", errors="replace")
except OSError as ex:
getLogger(__name__).warning(f"Source file '{sourceFile}' of the code coverage report can't be read: {ex}")
return nodes.paragraph(text=f"The source file '{file.Path.as_posix()}' can't be read.")
tokens = tokenizeSource(source, file._name)
if (lastLineNumber := file.LastLineNumber) > len(tokens):
getLogger(__name__).warning(
f"The code coverage report names line {lastLineNumber} of '{file.Path.as_posix()}', which has {len(tokens)} "
f"lines: the report wasn't measured on this version of the file."
)
fileLines = file.Lines
lines = []
for number, lineTokens in enumerate(tokens, start=1):
if number > lastLineNumber or (line := fileLines[number]) is None:
lines.append((number, "", None, 0, 0, lineTokens))
else:
state = LINE_STATES[line._status.name]
lines.append((number, state, line._coverageCount, len(line._branches), line.CoveredBranches, lineTokens))
return CoverageListing(source, source, lines=lines, anchors=anchors, path=file.Path.as_posix(), language="text")
[docs]
@export
class CodeCoverageReportPages(ReportPages["BaseWithPath"]):
"""
The pages of one code coverage report: a page per directory and per source file.
"""
_pages: ClassVar[dict[str, CodeCoverageReportPages]] = {} #: The pages of every code coverage report, by ID.
_separator: ClassVar[str] = "/" #: Separator of the names in a path.
_sources: Path #: Directory the report's file paths are relative to.
_levels: dict[Union[int, str], dict[str, str]] #: The report's coverage levels, coloring the tables.
[docs]
def __init__(
self,
reportID: str,
prefix: str,
reportFile: Path,
coverage: CoverageSummary,
sources: Path,
levels: dict[Union[int, str], dict[str, str]]
) -> None:
"""
Compute the document names and entries of a report's directories and source files.
:param reportID: Identifier of the report.
:param prefix: Document name the pages are generated below.
:param reportFile: The report file.
:param coverage: The report's root directory.
:param sources: Directory the report's file paths are relative to.
:param levels: The report's coverage levels.
"""
super().__init__(reportID, prefix, reportFile, self._DirectoryChildren(coverage))
self._sources = sources
self._levels = levels
[docs]
@classmethod
def CreatePages(cls, sphinxApplication: Sphinx) -> None:
"""
Call-back for Sphinx' ``builder-inited`` event, after the reports are read: compute and register the pages.
Only a report with the key ``pages`` gets pages. A report that couldn't be read gets none; this is logged as an
error.
:param sphinxApplication: Sphinx application instance.
"""
cls._pages = {}
for reportID, packageConfiguration in CodeCoverageBase._packageConfigurations.items():
if (prefix := packageConfiguration["pages"]) is None:
continue
try:
coverage = CodeCoverageBase.GetReport(reportID)
except ReportExtensionError as ex:
cause = ex if ex.__cause__ is None else ex.__cause__
getLogger(__name__).error(
f"Caught {getTypeName(ex)} when generating the pages of code coverage report '{reportID}'.\n"
f" {getTypeName(cause)}: {cause}"
)
continue
pages = cls(
reportID, prefix, packageConfiguration["report"], coverage, packageConfiguration["sources"],
packageConfiguration["levels"]
)
cls._pages[reportID] = pages
pages.Register(sphinxApplication.env)
[docs]
@staticmethod
def _DirectoryChildren(directory: Directory) -> list[tuple[str, BaseWithPath]]:
"""
Return a directory's directories - each compacted with its single subdirectories -, then its files, each sorted by
name.
:param directory: The directory.
:returns: The children as ``(role name, object)`` pairs.
"""
children: list[tuple[str, BaseWithPath]] = []
children.extend(("cov", compactDirectory(directory._directories[name])) for name in sorted(directory._directories))
children.extend(("cov", directory._files[name]) for name in sorted(directory._files))
return children
[docs]
def _Name(self, entity: BaseWithPath) -> str:
"""
Return the name a directory or file is shown with; a compacted directory's includes its parents' names.
:param entity: The directory or file.
:returns: The name, e.g. ``Counter.vhdl`` or ``pyTooling/Sphinx``.
"""
return compactedName(entity)
[docs]
def _PathElements(self, name: str) -> tuple[str, ...]:
"""
Return the elements a name adds to the path: a compacted directory's name adds one per directory.
:param name: The directory's or file's name.
:returns: The path elements.
"""
return tuple(name.split("/"))
[docs]
def _Title(self, entity: BaseWithPath) -> Nullable[str]:
"""
Return no title, as a report has none for its directories and files.
:param entity: The directory or file.
:returns: ``None``
"""
return None
[docs]
def _Children(self, roleName: str, entity: BaseWithPath) -> Iterable[tuple[str, BaseWithPath]]:
"""
Return a directory's directories, then its files; a file has none.
:param roleName: The role referring to the object: ``cov``.
:param entity: The directory or file.
:returns: The children as ``(role name, object)`` pairs.
"""
if hasattr(entity, "_directories"):
return self._DirectoryChildren(entity)
return []
[docs]
def _Page(self, docName: str, roleName: str, entity: BaseWithPath) -> nodes.section:
"""
Build a directory's or file's page.
:param docName: Name of the page's document.
:param roleName: The role referring to the object: ``cov``.
:param entity: The directory or file.
:returns: The page's top section.
"""
if hasattr(entity, "_directories"):
return self._DirectoryPage(docName, entity)
else:
return self._FilePage(docName, entity)
[docs]
def _SummarySection(self, docName: str, entity: BaseWithPath) -> tuple[nodes.section, nodes.field_list]:
"""
Create a page's section *Summary*: the line and branch counters, the coverage, and the parent directory.
:param docName: Name of the page's document.
:param entity: The directory or file.
:returns: The section, and its field list, which a page may add fields to.
"""
section = nodes.section("", nodes.title("Summary", "Summary"), ids=["summary"])
section += (fieldList := nodes.field_list(classes=["report-codecov-fields"]))
self._Field(fieldList, "Lines", nodes.Text(
f"{entity.CoveredLines} of {entity.TotalLines} covered ({entity.LineCoverage:.1%})"
))
if entity.ExcludedLines > 0:
self._Field(fieldList, "Excluded lines", nodes.Text(f"{entity.ExcludedLines}"))
if entity.TotalBranches > 0:
self._Field(fieldList, "Branches", nodes.Text(
f"{entity.CoveredBranches} of {entity.TotalBranches} taken ({entity.BranchCoverage:.1%}), "
f"{entity.PartialLines} lines partially"
))
self._Field(fieldList, "Coverage", nodes.Text(f"{entity.Coverage:.1%}"))
parent = entity._parent
while isCompacted(parent):
parent = parent._parent
if parent is not None and parent._parent is not None:
self._Field(fieldList, "Directory", self._Reference("cov", parent, docName))
return section, fieldList
[docs]
def _DirectoryPage(self, docName: str, directory: Directory) -> nodes.section:
"""
Build a directory's page: its counters, then tables of its directories and files, each linked to its page.
:param docName: Name of the page's document.
:param directory: The directory.
:returns: The page's top section.
"""
name = compactedName(directory)
page = nodes.section("", nodes.title(name, name), ids=["report-codecov-page"])
summarySection, _ = self._SummarySection(docName, directory)
page += summarySection
children: list[str] = []
subdirectories = [child for _, child in self._DirectoryChildren(directory) if hasattr(child, "_directories")]
files = [directory._files[fileName] for fileName in sorted(directory._files)]
for title, column, identifier, entities in (
("Directories", "Directory", "directories", subdirectories),
("Files", "File", "files", files),
):
if len(entities) == 0:
continue
page += (section := nodes.section("", nodes.title(title, title), ids=[identifier]))
table, tableBody = self._Table(
[(column, 6), ("Lines", 2), ("Branches", 2), ("Coverage", 1)],
["report-codecov-table", "report-codecov-children"]
)
section += table
for entity in entities:
level = CodeCoverageBase.LevelOf(self._levels, entity.Coverage, "class")
tableBody += (row := nodes.row("", classes=[level]))
row += nodes.entry("", nodes.paragraph("", "", self._Reference("cov", entity, docName)))
row += nodes.entry("", nodes.paragraph("", f"{entity.CoveredLines} of {entity.TotalLines}"))
row += nodes.entry("", nodes.paragraph("", f"{entity.CoveredBranches} of {entity.TotalBranches}"))
row += nodes.entry("", nodes.paragraph("", f"{entity.Coverage:.1%}"))
if (entry := self.Entry(entity)) is not None:
children.append(entry.docName)
if len(children) > 0:
# body elements precede a section's subsections, so the hidden table of contents goes before 'Summary'
page.insert(page.index(summarySection), self._TableOfContents(docName, children))
return page
[docs]
def _FilePage(self, docName: str, file: File) -> nodes.section:
"""
Build a source file's page: its counters, its missed lines, and its listing.
:param docName: Name of the page's document.
:param file: The source file.
:returns: The page's top section.
"""
page = nodes.section("", nodes.title(file._name, file._name), ids=["report-codecov-page"])
summarySection, fieldList = self._SummarySection(docName, file)
page += summarySection
if (missed := self._MissedLines(file)) != "":
self._Field(fieldList, "Missed lines", nodes.Text(missed))
page += (section := nodes.section("", nodes.title("Source", "Source"), ids=["source"]))
section += createListing(file, self._sources, anchors=True)
return page
[docs]
@staticmethod
def _MissedLines(file: File) -> str:
"""
Return a file's lines, which never ran, as ranges of consecutive executable lines, as coverage.py writes them.
:param file: The source file.
:returns: The ranges, e.g. ``8, 14-17``; empty if every executable line ran.
"""
ranges: list[str] = []
start = end = None
for line in file.IterateLines():
number = line._lineNumber
state = line._status.name
if state == "Excluded":
continue
if state == "Uncovered":
start = number if start is None else start
end = number
elif start is not None:
ranges.append(f"{start}" if start == end else f"{start}-{end}")
start = None
if start is not None:
ranges.append(f"{start}" if start == end else f"{start}-{end}")
return ", ".join(ranges)