Coverage for src / tracekit / reporting / formatting / __init__.py: 96%

1"""Formatting utilities for reports.""" 

2 

3from tracekit.reporting.formatting.emphasis import ( 

4 VisualEmphasis, 

5 format_callout_box, 

6 format_severity, 

7) 

8from tracekit.reporting.formatting.numbers import ( 

9 NumberFormatter, 

10 format_percentage, 

11 format_range, 

12 format_value, 

13 format_with_context, 

14 format_with_locale, 

15 format_with_units, 

16) 

17from tracekit.reporting.formatting.standards import ( 

18 ColorScheme, 

19 FormatStandards, 

20 Severity, 

21 apply_formatting_standards, 

22) 

23 

24 

25def format_margin( 

26 value: float, 

27 limit: float, 

28 unit: str = "", 

29 limit_type: str = "upper", 

30) -> str: 

31 """Format a margin value with pass/fail indication. 

32 

33 Calculates the margin between a measured value and its specification limit, 

34 then categorizes it as good (>20%), ok (10-20%), marginal (0-10%), or violation. 

35 

36 Args: 

37 value: Measured value. 

38 limit: Limit value (specification). 

39 unit: Unit of measurement. 

40 limit_type: Type of limit ("upper" or "lower"). 

41 

42 Returns: 

43 Formatted margin string with status indication. 

44 

45 Examples: 

46 >>> format_margin(70, 100, limit_type="upper") 

47 '30.0% margin (good)' 

48 >>> format_margin(95, 100, limit_type="upper") 

49 '5.0% margin (marginal)' 

50 """ 

51 # Calculate margin percentage 

52 if limit != 0: 

53 if limit_type == "upper": 

54 margin = limit - value 

55 margin_pct = (margin / limit) * 100 

56 is_passing = value < limit 

57 else: # lower 

58 margin = value - limit 

59 margin_pct = (margin / limit) * 100 

60 is_passing = value > limit 

61 else: 

62 margin_pct = 0 

63 is_passing = False 

64 

65 # Determine status based on margin percentage 

66 if not is_passing: 

67 status = "violation" 

68 elif margin_pct >= 20: 

69 status = "good" 

70 elif margin_pct >= 10: 

71 status = "ok" 

72 else: 

73 status = "marginal" 

74 

75 return f"{abs(margin_pct):.1f}% margin ({status})" 

76 

77 

78def format_pass_fail(passed: bool, message: str = "", with_symbol: bool = True) -> str: 

79 """Format pass/fail status. 

80 

81 Args: 

82 passed: Whether the test passed. 

83 message: Optional message to append. 

84 with_symbol: Whether to include Unicode symbol (checkmark/cross). 

85 

86 Returns: 

87 Formatted pass/fail string. 

88 

89 Examples: 

90 >>> format_pass_fail(True) 

91 'PASS ✓' 

92 >>> format_pass_fail(False, with_symbol=False) 

93 'FAIL' 

94 """ 

95 status = "PASS" if passed else "FAIL" 

96 

97 if with_symbol: 

98 symbol = "\u2713" if passed else "\u2717" 

99 result = f"{status} {symbol}" 

100 else: 

101 result = status 

102 

103 if message: 103 ↛ 104line 103 didn't jump to line 104 because the condition on line 103 was never true

104 return f"{result}: {message}" 

105 return result 

106 

107 

108__all__ = [ 

109 "ColorScheme", 

110 # Standards 

111 "FormatStandards", 

112 # Numbers 

113 "NumberFormatter", 

114 "Severity", 

115 # Emphasis 

116 "VisualEmphasis", 

117 "apply_formatting_standards", 

118 "format_callout_box", 

119 # Convenience 

120 "format_margin", 

121 "format_pass_fail", 

122 "format_percentage", 

123 "format_range", 

124 "format_severity", 

125 "format_value", 

126 "format_with_context", 

127 "format_with_locale", 

128 "format_with_units", 

129]