# ==================================================================================================================== #
# _____ ____ _ _ ____ _ #
# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ #
# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| #
# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ #
# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ #
# |_| |___/ |_| #
# ==================================================================================================================== #
# 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 documentation coverage, the common model every language's reader fills.
The model has two hierarchies over the same documentable items:
* The **physical** hierarchy - :class:`DocumentationReport`, :class:`Directory` and :class:`File` - is built from the
source files a reader analyzed. A file counts the items declared in it; a directory sums its directories and files.
* The **logical** hierarchy holds the documentable items of a language - :class:`Item` -, each with its kind, its
documentation state, its source file and lines, and the items it contains. The report holds its top-level items too.
An item - a package, a class, a method, a field, a VHDL entity, ... - names the source file it is declared in and its
first and last line, where the reader knows them.
An item's :class:`ItemKind` names the language construct, e.g. a class, a method or a VHDL entity. Each kind belongs to
an :class:`ItemCategory` shared by all languages - containers, types, callables, fields, variables, parameters -, so
the counters can be broken down the same way for every language.
An item's :class:`CoverageState` says, whether it is documented, and whether it is expected to be. The counters
(:class:`CoverageCounters`) of an item, a file, a directory or the whole analysis are computed from these states by
``Aggregate()``.
.. seealso::
:mod:`pyEDAA.Reports.DocumentationCoverage.Python`
|rarr| The reader of Python source files.
:mod:`pyEDAA.Reports.DocumentationCoverage.DocStrCoverage`
|rarr| The converter of docstr_coverage's analysis.
"""
from __future__ import annotations
from datetime import timedelta
from enum import Enum, Flag
from pathlib import Path
from typing import Callable, ClassVar, Generator, Iterator, 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, abstractmethod
from pyTooling.Warning import CriticalWarning
from pyEDAA.Reports import ReportException
[docs]
@export
class DocCoverageError(ReportException):
"""Base-exception of the documentation coverage data model and its readers."""
[docs]
@export
class AlreadyInDocumentationReportError(DocCoverageError, AlreadyInHierarchyError):
"""The exception is raised when an element is added to an element, but it already has a parent."""
[docs]
@export
class DuplicateDirectoryError(DocCoverageError, DuplicateElementError):
"""The exception is raised when a directory already contains a directory or a file of the same name."""
[docs]
@export
class DuplicateFileError(DocCoverageError, 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 SourceFileWarning(CriticalWarning):
"""
A source file can't be analyzed: it can't be read, decoded or parsed.
The reader excludes the file's item from the analysis, and continues with the next file. The cause is the exception
reading, decoding or parsing raised.
.. important::
This warning is critical: it must be collected by a :class:`~pyTooling.Warning.WarningCollector` up the
call-hierarchy, otherwise :meth:`~pyTooling.Warning.WarningCollector.Raise` raises an
:exc:`~pyTooling.Warning.UnhandledCriticalWarningError`.
"""
_file: Nullable[_File] #: The report's file of the source file.
[docs]
def __init__(self, message: str, /, *, file: Nullable[_File] = None) -> None:
"""
Initializes the warning with the report's file of the source file that can't be analyzed.
:param message: The warning's message.
:param file: Optional, the report's file of the source file.
"""
super().__init__(message)
self._file = file
@readonly
def File(self) -> Nullable[_File]:
"""
Read-only property to access the report's file of the source file that can't be analyzed (:attr:`_file`).
Its path, relative to the analyzed directory, is
:attr:`File.Path <pyEDAA.Reports.DocumentationCoverage.File.Path>`.
:returns: The file, or ``None`` if it wasn't recorded.
"""
return self._file
[docs]
@export
class CoverageState(Flag):
"""
The documentation state of an item, as flags.
:class:`CoverageCounters` counts an item by the first of these flags it has:
* :attr:`Empty`: not counted.
* :attr:`Excluded`: counted as excluded.
* :attr:`Ignored`: counted as ignored.
* :attr:`Covered`: counted as expected and covered.
* None of them: counted as expected and uncovered.
"""
Unknown = 0 #: No state; an item can't have it.
Excluded = 1 #: Excluded from the analysis, e.g. by a name pattern.
Ignored = 2 #: Needs no documentation by the reader's rules, e.g. a property's setter.
Empty = 4 #: Has nothing to document, e.g. an empty module; not counted.
Covered = 8 #: Counts as documented.
Weak = 16 #: Documented, but too briefly.
Incomplete = 32 #: Documented, but not every part of it.
Inherited = 64 #: Undocumented, but takes the documentation of what it overrides, as a comment states.
Detailed = 128 #: Documented in detail.
Undocumented = 256 #: Has no documentation.
Documented = 512 #: Has documentation.
Parameters = 1024 #: Its parameters are documented.
ReturnValue = 2048 #: Its return value is documented.
Exceptions = 8192 #: The exceptions it raises are documented.
Types = 16384 #: Its types are documented.
Excused = 32768 #: Undocumented, but a comment excuses the missing documentation.
[docs]
@export
class ItemCategory(Enum):
"""
The category of a documentable item, shared by all languages.
Each :class:`ItemKind` belongs to one category (:attr:`ItemKind.Category`), so the counters of every language break
down the same way.
"""
Container = 1 #: Contains other items, e.g. a package, a module, a namespace or a VHDL entity.
Type = 2 #: Declares a type, e.g. a class, a struct, an enumeration or a type alias.
Callable = 3 #: Can be called, e.g. a function, a method, a procedure or a property.
Field = 4 #: Data of a type, e.g. a class' field, a record's element or an enumeration's member.
Variable = 5 #: Data of a container, whose value can change, e.g. a module's variable or a VHDL signal.
Constant = 6 #: Data of a container, whose value can't change, e.g. a constant of C or VHDL.
Generic = 7 #: A compile-time parameter, e.g. a VHDL generic or a C++ template parameter.
Parameter = 8 #: A run-time parameter declared as an item of its own, e.g. a VHDL port.
Other = 9 #: Belongs to no other category.
DEFAULT = Other #: The category of an item, which belongs to no other category.
[docs]
@export
class ItemKind(Enum):
"""
The kind of a documentable item: the language construct it is.
Languages share a kind, where they share the construct, e.g. a package of Python, Java and Go. A construct only one
language has, has a kind of its own, e.g. a VHDL entity. Each kind belongs to an :class:`ItemCategory`
(:attr:`Category`).
"""
Library = 1 #: A library of design units, e.g. a VHDL library.
Package = 2 #: A package, e.g. of Python, Java or Go, or a VHDL package.
PackageBody = 3 #: The body of a VHDL package.
Namespace = 4 #: A namespace, e.g. of C++ or TCL.
Module = 5 #: A module, e.g. a Python module.
SourceFile = 6 #: A source file, where the file is the language's unit, e.g. in C.
Entity = 7 #: A VHDL entity.
Architecture = 8 #: A VHDL architecture.
Configuration = 9 #: A VHDL configuration.
Context = 10 #: A VHDL context.
Class = 11 #: A class.
Struct = 12 #: A structure, e.g. of C, C++ or Go.
Union = 13 #: A union of C or C++.
Interface = 14 #: An interface, e.g. of Java or Go.
Enumeration = 15 #: An enumeration.
Record = 16 #: A record, e.g. of Java or a VHDL record type.
Type = 17 #: Any other type declaration, e.g. a VHDL type or subtype.
TypeAlias = 18 #: A type alias, e.g. a C ``typedef`` or Python's ``type`` statement.
TypeVariable = 19 #: A type variable, e.g. Python's ``TypeVar``.
Component = 20 #: A VHDL component declaration.
Function = 21 #: A function.
Method = 22 #: A method of a type.
Constructor = 23 #: A type's constructor, e.g. Python's ``__init__``.
Destructor = 24 #: A type's destructor, e.g. of C++, or Python's ``__del__``.
Property = 25 #: A property: a method accessed like a field.
Procedure = 26 #: A procedure, e.g. of VHDL or TCL.
Macro = 27 #: A preprocessor macro, e.g. of C.
Process = 28 #: A VHDL process.
Field = 29 #: A field of a type, e.g. a class' field or a record's element.
EnumerationMember = 30 #: A member of an enumeration.
Variable = 31 #: A variable of a container, e.g. a module's variable.
Signal = 32 #: A VHDL signal.
FileObject = 33 #: A file object, e.g. declared by a VHDL file declaration.
Constant = 34 #: A constant.
Generic = 35 #: A VHDL generic.
TypeParameter = 36 #: A type parameter, e.g. of a C++ template or a Java generic class.
Parameter = 37 #: A parameter declared as an item of its own, e.g. of a VHDL subprogram.
Port = 38 #: A VHDL port.
Alias = 39 #: An alias, e.g. a VHDL alias declaration.
Attribute = 40 #: A VHDL attribute declaration.
Other = 41 #: Any other documentable item.
DEFAULT = Other #: The kind of an item, which is no other kind.
__CATEGORIES: ClassVar[dict[int, ItemCategory]] = {
Library: ItemCategory.Container,
Package: ItemCategory.Container,
PackageBody: ItemCategory.Container,
Namespace: ItemCategory.Container,
Module: ItemCategory.Container,
SourceFile: ItemCategory.Container,
Entity: ItemCategory.Container,
Architecture: ItemCategory.Container,
Configuration: ItemCategory.Container,
Context: ItemCategory.Container,
Class: ItemCategory.Type,
Struct: ItemCategory.Type,
Union: ItemCategory.Type,
Interface: ItemCategory.Type,
Enumeration: ItemCategory.Type,
Record: ItemCategory.Type,
Type: ItemCategory.Type,
TypeAlias: ItemCategory.Type,
TypeVariable: ItemCategory.Type,
Component: ItemCategory.Type,
Function: ItemCategory.Callable,
Method: ItemCategory.Callable,
Constructor: ItemCategory.Callable,
Destructor: ItemCategory.Callable,
Property: ItemCategory.Callable,
Procedure: ItemCategory.Callable,
Macro: ItemCategory.Callable,
Process: ItemCategory.Callable,
Field: ItemCategory.Field,
EnumerationMember: ItemCategory.Field,
Variable: ItemCategory.Variable,
Signal: ItemCategory.Variable,
FileObject: ItemCategory.Variable,
Constant: ItemCategory.Constant,
Generic: ItemCategory.Generic,
TypeParameter: ItemCategory.Generic,
Parameter: ItemCategory.Parameter,
Port: ItemCategory.Parameter,
Alias: ItemCategory.Other,
Attribute: ItemCategory.Other,
Other: ItemCategory.Other,
} #: The category of each kind, by the kind's value.
@readonly
def Category(self) -> ItemCategory:
"""
Read-only property to return the category this kind belongs to.
:returns: The kind's category.
"""
return self.__CATEGORIES[self.value]
[docs]
@export
class CoverageCounters(metaclass=ExtendedType, slots=True):
"""
The numbers of documentable items by their coverage state, and the coverage computed from them.
* An item is *expected* to be documented, unless it is *ignored* or *excluded*; an item without anything to document
(:attr:`CoverageState.Empty`) isn't counted at all.
* An expected item is either *covered* or *uncovered*.
.. code-block:: text
total = expected + ignored + excluded
expected = covered + uncovered
coverage = covered / expected
"""
_expected: int #: Number of items expected to be documented.
_covered: int #: Number of expected items, which count as documented.
_ignored: int #: Number of items, which need no documentation by the reader's rules.
_excluded: int #: Number of items excluded from the analysis.
[docs]
def __init__(self) -> None:
"""
Initializes counters of zero items.
"""
self._expected = 0
self._covered = 0
self._ignored = 0
self._excluded = 0
@readonly
def Total(self) -> int:
"""
Read-only property to return the number of counted items.
:returns: The sum of expected, ignored and excluded items.
"""
return self._expected + self._ignored + self._excluded
@readonly
def Expected(self) -> int:
"""
Read-only property to access the number of items expected to be documented (:attr:`_expected`).
:returns: The number of expected items.
"""
return self._expected
@readonly
def Covered(self) -> int:
"""
Read-only property to access the number of expected items, which count as documented (:attr:`_covered`).
:returns: The number of covered items.
"""
return self._covered
@readonly
def Uncovered(self) -> int:
"""
Read-only property to return the number of expected items, which don't count as documented.
:returns: :attr:`Expected` minus :attr:`Covered`.
"""
return self._expected - self._covered
@readonly
def Ignored(self) -> int:
"""
Read-only property to access the number of items, which need no documentation by the reader's rules
(:attr:`_ignored`).
:returns: The number of ignored items.
"""
return self._ignored
@readonly
def Excluded(self) -> int:
"""
Read-only property to access the number of items excluded from the analysis (:attr:`_excluded`).
:returns: The number of excluded items.
"""
return self._excluded
@readonly
def Coverage(self) -> float:
"""
Read-only property to return the documentation coverage: the ratio of covered to expected items.
:returns: The coverage in range 0.0..1.0; ``1.0`` if no item is expected.
"""
return 1.0 if self._expected == 0 else self._covered / self._expected
[docs]
def _Count(self, status: CoverageState) -> None:
"""
Count one item of a coverage state.
:param status: The item's coverage state.
"""
if CoverageState.Empty in status:
return
elif CoverageState.Excluded in status:
self._excluded += 1
elif CoverageState.Ignored in status:
self._ignored += 1
else:
self._expected += 1
if CoverageState.Covered in status:
self._covered += 1
[docs]
def _Add(self, other: CoverageCounters) -> None:
"""
Add the numbers of other counters to these.
:param other: The other counters.
"""
self._expected += other._expected
self._covered += other._covered
self._ignored += other._ignored
self._excluded += other._excluded
[docs]
def __repr__(self) -> str:
"""
Return a representation of the counters for debugging.
Counters of 3 covered out of 4 expected items, 1 ignored item and no excluded item read
``<CoverageCounters 3/4, ignored 1, excluded 0: 75.0%>``.
:returns: The covered, expected, ignored and excluded items and the coverage.
"""
return (
f"<CoverageCounters {self._covered}/{self._expected}, ignored {self._ignored}, excluded {self._excluded}: "
f"{self.Coverage:.1%}>"
)
[docs]
@export
class Base(metaclass=ExtendedType, slots=True):
"""
Base-class of every element of the documentation coverage model: a reference to the element containing it and to
the analysis' root, and the counters computed by :meth:`Aggregate`.
"""
_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[DocumentationReport] #: The report, or ``None`` while the element isn't part of one.
_counters: CoverageCounters #: The counters of the items this element counts.
_categories: dict[ItemCategory, CoverageCounters] #: The counters per category of the items.
[docs]
def __init__(self, *, parent: Nullable[Base] = None) -> None:
"""
Initializes an element with its parent, the parent's root, and counters of zero items.
The parent doesn't list the element yet: the class setting the field the parent stores it by - a name - 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
self._counters = CoverageCounters()
self._categories = {}
@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:`DocumentationReport`, which has no
parent.
:raises AlreadyInDocumentationReportError: If the element already has a parent.
:raises DuplicateDirectoryError: If the assigned parent is a directory, which already contains a directory
of this name.
:raises DuplicateFileError: If the assigned parent is a directory, which already contains a file of
this name.
"""
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 AlreadyInDocumentationReportError(f"{getTypeName(self)} already has a parent.")
parent._AddElement(self)
self._parent = parent
self._SetRoot(parent._root)
@readonly
def Root(self) -> Nullable[DocumentationReport]:
"""
Read-only property to access the analysis' 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 an analysis.
"""
return self._root
@readonly
def Counters(self) -> CoverageCounters:
"""
Read-only property to access the counters of the items this element counts (:attr:`_counters`).
They are zero until :meth:`Aggregate` computed them.
:returns: The counters.
"""
return self._counters
@readonly
def Categories(self) -> dict[ItemCategory, CoverageCounters]:
"""
Read-only property to access the counters per category of the items this element counts (:attr:`_categories`).
A category without items has no entry. The counters are computed by :meth:`Aggregate`.
:returns: The counters, by category.
"""
return self._categories
[docs]
def _ResetCounters(self) -> None:
"""
Set the counters to zero items.
"""
self._counters = CoverageCounters()
self._categories = {}
[docs]
def _CountItem(self, item: Item) -> None:
"""
Count an item's own coverage state, in the counters and in the counters of its category.
:param item: The item.
"""
self._counters._Count(item._status)
category = item._kind.Category
if (counters := self._categories.get(category, None)) is None:
counters = CoverageCounters()
self._categories[category] = counters
counters._Count(item._status)
[docs]
def _AddCounters(self, other: Base) -> None:
"""
Add the counters of another element to this one's.
:param other: The other element, aggregated.
"""
self._counters._Add(other._counters)
for category, otherCounters in other._categories.items():
if (counters := self._categories.get(category, None)) is None:
counters = CoverageCounters()
self._categories[category] = counters
counters._Add(otherCounters)
[docs]
def _SetRoot(self, root: Nullable[DocumentationReport]) -> None:
"""
Set the analysis' root of this element.
A class containing elements overrides it, to set the root of those too.
:param root: The root, or ``None`` while the element isn't part of an analysis.
"""
self._root = root
[docs]
@abstractmethod
def Aggregate(self) -> None:
"""
Compute the counters.
"""
# A class with a property named like a class - ``Path`` - 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.
_Path = Path
[docs]
@export
class BaseWithPath(Base):
"""
Base-class of the physical hierarchy - directories and source files -: a name and a path below the report.
Its parent is the :class:`Directory` containing it.
"""
_name: _Path #: Name of the directory or file: a path of one component.
[docs]
def __init__(self, name: Path, *, parent: Nullable[Directory]) -> None:
"""
Initializes the parent, the name and the counters.
:param name: Name of the directory or file: a path of one component.
: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:`~pathlib.Path`.
:raises ValueError: If parameter ``name`` is empty or ``.``.
:raises ValueError: If parameter ``name`` has more than one component.
"""
super().__init__(parent=parent)
if name is None:
raise ValueError("Parameter 'name' is None.")
elif not isinstance(name, Path):
ex = TypeError("Parameter 'name' is not of type 'Path'.")
ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
raise ex
elif name.name == "":
ex = ValueError("Parameter 'name' is empty.")
ex.add_note(f"Got path '{name}'.")
raise ex
elif len(name.parts) > 1:
ex = ValueError("Parameter 'name' has more than one component.")
ex.add_note(f"Got path '{name.as_posix()}'.")
raise ex
self._name = name
@readonly
def Name(self) -> Path:
"""
Read-only property to access the name of the directory or file (:attr:`_name`).
:returns: The name: a path of one component.
"""
return self._name
@readonly
def Path(self) -> Path:
"""
Read-only property to return the path below the report: the names of the parent directories and the own name.
A file ``Shapes.py`` in a directory ``myPackage`` has the path ``myPackage/Shapes.py``.
:returns: The path; the name, if there is no parent.
"""
if self._parent is None:
return self._name
return self._parent.Path / self._name
[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[_Path, Directory] #: The directories in this directory, by name.
_files: dict[_Path, File] #: The source files in this directory, by name.
[docs]
def __init__(self, name: Path, *, parent: Nullable[Directory] = None) -> None:
"""
Initializes a directory, and adds it to its parent directory.
:param name: Name of the directory: a path of one component.
: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:`~pathlib.Path`.
:raises ValueError: If parameter ``name`` is empty or ``.``.
:raises ValueError: If parameter ``name`` has more than one component.
: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.as_posix()}'.")
elements[element._name] = element
[docs]
def _SetRoot(self, root: Nullable[DocumentationReport]) -> None:
"""
Set the analysis' root of this directory, and of the directories and files below it.
:param root: The root, or ``None`` while the directory isn't part of an analysis.
"""
self._root = root
for directory in self._directories.values():
directory._SetRoot(root)
for file in self._files.values():
file._SetRoot(root)
@readonly
def Directories(self) -> dict[Path, 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[Path, 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) -> File:
"""
Return the source file at a path below this directory, adding it and the directories on its way, if missing.
:param path: The file's path relative to this directory, e.g. ``myPackage/Shapes.py``.
:returns: The file.
:raises ValueError: If parameter ``path`` is ``None``.
:raises TypeError: If parameter ``path`` isn't of type :class:`~pathlib.Path`.
:raises ValueError: If parameter ``path`` names no file.
:raises DocCoverageError: 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 not isinstance(path, Path):
ex = TypeError("Parameter 'path' is not of type 'Path'.")
ex.add_note(f"Got type '{getFullyQualifiedName(path)}'.")
raise ex
parts = [Path(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 DocCoverageError(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) -> Generator[File, None, None]:
"""
Iterate the source files in this directory and below.
A directory's files come before its directories' files, each in the order they were added.
:returns: A generator of the files.
"""
yield from self._files.values()
for directory in self._directories.values():
yield from directory.IterateFiles()
[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._AddCounters(child)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the directory for debugging.
A directory ``myPackage`` of 3 files reads ``<Directory myPackage: 3 files, 75.0%>``.
:returns: The directory's path, its number of files and its documentation coverage.
"""
return f"<Directory {self.Path.as_posix()}: {self.FileCount} files, {self._counters.Coverage:.1%}>"
Directory._PARENT_TYPE = (Directory, )
[docs]
@export
class DocumentationReport(Directory):
"""
The report of a documentation coverage analysis: the directory the source files' paths are relative to, and the
top-level items of the logical hierarchy.
It is its own root. Its counters count every item of the logical hierarchy; its directories and files count only
the items declared in a source file.
"""
_items: list[Item] #: The top-level items, in the order they were added.
_analysisDuration: Nullable[timedelta] #: Duration of the analysis, which produced the report, if measured.
[docs]
def __init__(self, name: Path) -> None:
"""
Initializes the report of a documentation coverage analysis.
:param name: Name of the report: a path of one component, e.g. the analyzed package's name.
:raises ValueError: If parameter ``name`` is ``None``.
:raises TypeError: If parameter ``name`` isn't of type :class:`~pathlib.Path`.
:raises ValueError: If parameter ``name`` is empty or ``.``.
:raises ValueError: If parameter ``name`` has more than one component.
"""
super().__init__(name)
self._root = self
self._items = []
self._analysisDuration = None
@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 | Item) -> None:
"""
Add a top-level item, a directory or a file, which names the report as its parent.
:param element: The item, directory or file.
:raises DuplicateDirectoryError: If the report already contains a directory of this name.
:raises DuplicateFileError: If the report already contains a file of this name.
"""
if isinstance(element, BaseWithPath):
super()._AddElement(element)
else:
self._items.append(element)
@readonly
def Path(self) -> Path:
"""
Read-only property to return the path below the report, which is the report's own: ``.``.
So the paths of the directories and files below are relative to the report, without its name.
:returns: ``.``
"""
return Path(".")
@readonly
def Items(self) -> list[Item]:
"""
Read-only property to access the top-level items of the logical hierarchy (:attr:`_items`).
:returns: The items, in the order they were added.
"""
return self._items
@readonly
def AnalysisDuration(self) -> Nullable[timedelta]:
"""
Read-only property to access the duration of the analysis, which produced the report (:attr:`_analysisDuration`).
A reader measures it; a report built otherwise has none.
:returns: The duration, or ``None`` if it wasn't measured.
"""
return self._analysisDuration
[docs]
def Aggregate(self) -> None:
"""
Aggregate the physical hierarchy - directories and files -, then the items of the logical hierarchy, which the
report's counters sum.
"""
super().Aggregate()
self._ResetCounters()
for item in self._items:
item.Aggregate()
self._AddCounters(item)
[docs]
@export
class File(BaseWithPath):
"""
A source file: the items declared in it, and their counters.
The items are those of the logical hierarchy naming this file; the file counts each item's own state, not the items
it contains, which name their file themselves.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] = (Directory, ) #: A file is in a directory.
_items: list[Item] #: The items declared in this file, in the order they were added.
[docs]
def __init__(self, name: Path, *, parent: Nullable[Directory] = None) -> None:
"""
Initializes a source file, and adds it to its directory.
:param name: Name of the file: a path of one component.
: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:`~pathlib.Path`.
:raises ValueError: If parameter ``name`` is empty or ``.``.
:raises ValueError: If parameter ``name`` has more than one component.
:raises DuplicateFileError: If the directory already contains a file or directory of this name.
"""
super().__init__(name, parent=parent)
self._items = []
if parent is not None:
parent._AddElement(self)
@readonly
def Items(self) -> list[Item]:
"""
Read-only property to access the items declared in this file (:attr:`_items`).
:returns: The items, in the order they were added.
"""
return self._items
[docs]
def Aggregate(self) -> None:
"""
Count the own coverage state of each item declared in this file.
"""
self._ResetCounters()
for item in self._items:
self._CountItem(item)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the file for debugging.
A file ``Shapes.py`` of 4 items reads ``<File myPackage/Shapes.py: 4 items, 75.0%>``.
:returns: The file's path, its number of items and its documentation coverage.
"""
return f"<File {self.Path.as_posix()}: {len(self._items)} items, {self._counters.Coverage:.1%}>"
# A class with a property named like a class - ``File`` - 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.
_File = File
[docs]
@export
class Item(Base):
"""
A documentable item of a language, its coverage state, and the items it contains.
Its parent is the :class:`Item` containing it, or the :class:`DocumentationReport` for a top-level item. Items of one
parent may share a name, e.g. a property's getter and setter.
A container's own documentation - a module's or a class' doc-string - is the container's own coverage state; the
items it contains have states of their own. So an item's counters count the item itself and every item below it.
"""
_PARENT_TYPE: ClassVar[tuple[type, ...]] #: An item is in an item or the report; assigned below the class.
_name: str #: Name of the item.
_kind: ItemKind #: The language construct the item is.
_status: CoverageState #: The item's own coverage state.
_file: Nullable[_File] #: The source file the item is declared in, if the reader knows it.
_startLine: Nullable[int] #: The item's first line, if the reader knows it.
_endLine: Nullable[int] #: The item's last line, if the reader knows it.
_items: list[Item] #: The items this one contains, in the order they were added.
[docs]
def __init__(
self,
name: str,
kind: ItemKind,
status: CoverageState,
*,
file: Nullable[File] = None,
startLine: Nullable[int] = None,
endLine: Nullable[int] = None,
parent: Nullable[Item | DocumentationReport] = None
) -> None:
"""
Initializes an item, and adds it to its file and to the item or report containing it.
:param name: Name of the item.
:param kind: The language construct the item is.
:param status: The item's own coverage state.
:param file: Optional, the source file the item is declared in. Default: ``None``.
:param startLine: Optional, the item's first line. Default: ``None``.
:param endLine: Optional, the item's last line. Default: ``None``.
:param parent: Optional, the item or report containing this item. Default: ``None``.
:raises TypeError: If parameter ``parent`` isn't of type :class:`Item` or :class:`DocumentationReport`.
: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 ValueError: If parameter ``kind`` is ``None``.
:raises TypeError: If parameter ``kind`` isn't of type :class:`ItemKind`.
:raises ValueError: If parameter ``status`` is ``None``.
:raises TypeError: If parameter ``status`` isn't of type :class:`CoverageState`.
:raises ValueError: If parameter ``status`` is ``CoverageState.Unknown``.
:raises TypeError: If parameter ``file`` isn't of type :class:`File`.
:raises TypeError: If parameter ``startLine`` isn't of type :class:`int`.
:raises ValueError: If parameter ``startLine`` is less than 1.
:raises TypeError: If parameter ``endLine`` isn't of type :class:`int`.
:raises ValueError: If parameter ``endLine`` is before parameter ``startLine``, or less than 1.
"""
super().__init__(parent=parent)
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 kind is None:
raise ValueError("Parameter 'kind' is None.")
elif not isinstance(kind, ItemKind):
ex = TypeError("Parameter 'kind' is not of type 'ItemKind'.")
ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
raise ex
if status is None:
raise ValueError("Parameter 'status' is None.")
elif not isinstance(status, CoverageState):
ex = TypeError("Parameter 'status' is not of type 'CoverageState'.")
ex.add_note(f"Got type '{getFullyQualifiedName(status)}'.")
raise ex
elif status is CoverageState.Unknown:
raise ValueError("Parameter 'status' is 'Unknown'.")
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, int):
ex = TypeError("Parameter 'startLine' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(startLine)}'.")
raise ex
elif startLine < 1:
ex = ValueError("Parameter 'startLine' is less than 1.")
ex.add_note(f"Got value '{startLine}'.")
raise ex
if endLine is not None:
if not isinstance(endLine, int):
ex = TypeError("Parameter 'endLine' is not of type 'int'.")
ex.add_note(f"Got type '{getFullyQualifiedName(endLine)}'.")
raise ex
elif endLine < (1 if startLine is None else startLine):
ex = ValueError("Parameter 'endLine' is before parameter 'startLine', or less than 1.")
ex.add_note(f"Got lines {startLine} to {endLine}.")
raise ex
self._name = name
self._kind = kind
self._status = status
self._file = file
self._startLine = startLine
self._endLine = endLine
self._items = []
if parent is not None:
parent._AddElement(self)
if file is not None:
file._items.append(self)
[docs]
def _AddElement(self, item: Item) -> None:
"""
Add an item, which names this item as its parent.
:param item: The item.
"""
self._items.append(item)
[docs]
def _SetRoot(self, root: Nullable[DocumentationReport]) -> None:
"""
Set the analysis' root of this item, and of the items below it.
:param root: The root, or ``None`` while the item isn't part of an analysis.
"""
self._root = root
for item in self._items:
item._SetRoot(root)
[docs]
def IterateDescendants(self, predicate: Nullable[Callable[[Item], bool]] = None) -> Generator[Item, None, None]:
"""
Iterate all or selected items below this one - the items it contains, theirs, ... -, depth-first: each item
followed by the items below it.
If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator. A skipped
item's items are still iterated.
:param predicate: Optional, filter function accepting an item and returning a boolean. Default: ``None``.
:returns: A generator of the items below this one.
"""
if predicate is None:
for item in self._items:
yield item
yield from item.IterateDescendants()
else:
for item in self._items:
if predicate(item):
yield item
yield from item.IterateDescendants(predicate)
@readonly
def Name(self) -> str:
"""
Read-only property to access the item's name (:attr:`_name`).
:returns: The name.
"""
return self._name
@readonly
def Kind(self) -> ItemKind:
"""
Read-only property to access the language construct the item is (:attr:`_kind`).
:returns: The item's kind.
"""
return self._kind
@readonly
def Category(self) -> ItemCategory:
"""
Read-only property to access the category of the item's kind (:attr:`_kind`).
:returns: The item's category.
"""
return self._kind.Category
@readonly
def Status(self) -> CoverageState:
"""
Read-only property to access the item's own coverage state (:attr:`_status`).
:returns: The coverage state.
"""
return self._status
@readonly
def File(self) -> Nullable[File]:
"""
Read-only property to access the source file the item is declared in (:attr:`_file`).
:returns: The file, or ``None`` if the reader doesn't know it.
"""
return self._file
@readonly
def StartLine(self) -> Nullable[int]:
"""
Read-only property to access the item's first line (:attr:`_startLine`).
:returns: The line number, or ``None`` if the reader doesn't know it.
"""
return self._startLine
@readonly
def EndLine(self) -> Nullable[int]:
"""
Read-only property to access the item's last line (:attr:`_endLine`).
:returns: The line number, or ``None`` if the reader doesn't know it.
"""
return self._endLine
@readonly
def Items(self) -> list[Item]:
"""
Read-only property to access the items this one contains (:attr:`_items`).
:returns: The items, in the order they were added.
"""
return self._items
@readonly
def QualifiedName(self) -> str:
"""
Read-only property to return the names of the items 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, Item):
return f"{self._parent.QualifiedName}.{self._name}"
return self._name
[docs]
def __len__(self) -> int:
"""
Return the number of items this one contains.
:returns: The number of items.
"""
return len(self._items)
[docs]
def __iter__(self) -> Iterator[Item]:
"""
Iterate the items this one contains.
:returns: An iterator of the items, in the order they were added.
"""
return iter(self._items)
[docs]
def __contains__(self, name: str) -> bool:
"""
Return whether this item contains an item of a name.
:param name: The name.
:returns: ``True``, if an item of this name is contained.
"""
return any(item._name == name for item in self._items)
[docs]
def __getitem__(self, name: str) -> Item:
"""
Return the contained item of a name; the first one, if several share it.
A property's getter is added before its setter, so it is the one returned.
:param name: The name.
:returns: The item.
:raises KeyError: If no item of this name is contained.
"""
for item in self._items:
if item._name == name:
return item
raise KeyError(f"Item '{self.QualifiedName}' contains no item '{name}'.")
[docs]
def Aggregate(self) -> None:
"""
Aggregate the items this one contains, then count this item's own coverage state and add their counters.
"""
self._ResetCounters()
self._CountItem(self)
for item in self._items:
item.Aggregate()
self._AddCounters(item)
[docs]
def __repr__(self) -> str:
"""
Return a representation of the item for debugging.
A method ``Area`` of class ``Circle`` in module ``Shapes`` reads ``<Item Method Shapes.Circle.Area: 100.0%>``.
:returns: The item's kind, qualified name and documentation coverage.
"""
return f"<Item {self._kind.name} {self.QualifiedName}: {self._counters.Coverage:.1%}>"
Item._PARENT_TYPE = (Item, DocumentationReport)