Coverage for pyEDAA/Reports/DocumentationCoverage/__init__.py: 100%

1# ==================================================================================================================== # 

2# _____ ____ _ _ ____ _ # 

3# _ __ _ _| ____| _ \ / \ / \ | _ \ ___ _ __ ___ _ __| |_ ___ # 

4# | '_ \| | | | _| | | | |/ _ \ / _ \ | |_) / _ \ '_ \ / _ \| '__| __/ __| # 

5# | |_) | |_| | |___| |_| / ___ \ / ___ \ _| _ < __/ |_) | (_) | | | |_\__ \ # 

6# | .__/ \__, |_____|____/_/ \_\/_/ \_(_)_| \_\___| .__/ \___/|_| \__|___/ # 

7# |_| |___/ |_| # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2021-2026 Electronic Design Automation Abstraction (EDA²) # 

15# # 

16# Licensed under the Apache License, Version 2.0 (the "License"); # 

17# you may not use this file except in compliance with the License. # 

18# You may obtain a copy of the License at # 

19# # 

20# http://www.apache.org/licenses/LICENSE-2.0 # 

21# # 

22# Unless required by applicable law or agreed to in writing, software # 

23# distributed under the License is distributed on an "AS IS" BASIS, # 

24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

25# See the License for the specific language governing permissions and # 

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31"""Abstraction of code documentation coverage data model.""" 

32from enum import Flag 

33from typing import Optional as Nullable 

34 

35from pyTooling.Decorators import export, readonly 

36from pyTooling.MetaClasses import ExtendedType 

37 

38from pyEDAA.Reports import ReportException 

39 

40 

41@export 

42class DocCoverageException(ReportException): 

43 pass 

44 

45 

46@export 

47class CoverageState(Flag): 

48 Unknown = 0 

49 Excluded = 1 

50 Ignored = 2 

51 Empty = 4 

52 Covered = 8 

53 

54 Weak = 16 

55 Incomplete = 32 

56 Inherited = 64 

57 Detailed = 128 

58 

59 Undocumented = 256 

60 Documented = 512 

61 

62 Parameters = 1024 

63 ReturnValue = 2048 

64 Exceptions = 8192 

65 Types = 16384 

66 

67# unrequiredButDocumented 

68# wrongly documented 

69 

70 

71@export 

72class Base(metaclass=ExtendedType, slots=True): 

73 _parent: Nullable["Base"] 

74 _name: str 

75 _status: CoverageState 

76 

77 def __init__(self, name: str, parent: Nullable["Base"] = None) -> None: 

78 if name is None: 

79 raise ValueError(f"Parameter 'name' must not be None.") 

80 

81 self._parent = parent 

82 self._name = name 

83 self._status = CoverageState.Unknown 

84 

85 @readonly 

86 def Parent(self) -> Nullable["Base"]: 

87 """ 

88 Read-only property to access the reference to the parent coverage entity. 

89 

90 :returns: Reference to the parent entity, or ``None`` for the root entity. 

91 """ 

92 return self._parent 

93 

94 @readonly 

95 def Name(self) -> str: 

96 """ 

97 Read-only property to access the coverage entity's name. 

98 

99 :returns: Name of the coverage entity. 

100 """ 

101 return self._name 

102 

103 @readonly 

104 def Status(self) -> CoverageState: 

105 """ 

106 Read-only property to access the coverage entity's state. 

107 

108 :returns: Coverage state of the entity. 

109 """ 

110 return self._status 

111 

112 

113@export 

114class _Type(Base): 

115 pass 

116 

117 

118@export 

119class Class(_Type): 

120 pass 

121 

122 

123@export 

124class _Unit(Base): 

125 pass 

126 

127 

128@export 

129class Module(_Unit): 

130 pass 

131 

132 

133@export 

134class Package(_Unit): 

135 pass