Coverage for little_loops / cli / output.py: 96%

1"""Shared CLI output utilities: terminal width, text wrapping, and ANSI color.""" 

2 

3from __future__ import annotations 

4 

5import json 

6import os 

7import shutil 

8import sys 

9import textwrap 

10from typing import TYPE_CHECKING, Any 

11 

12if TYPE_CHECKING: 

13 from little_loops.config import CliConfig 

14 

15 

16def terminal_width(default: int = 80) -> int: 

17 """Return the current terminal column width, falling back to *default*.""" 

18 return shutil.get_terminal_size((default, 24)).columns 

19 

20 

21def wrap_text(text: str, indent: str = " ", width: int | None = None) -> str: 

22 """Wrap *text* at terminal width with consistent *indent* on every line.""" 

23 w = width or terminal_width() 

24 return textwrap.fill(text, width=w, initial_indent=indent, subsequent_indent=indent) 

25 

26 

27# --------------------------------------------------------------------------- 

28# ANSI color helpers — suppressed when NO_COLOR=1 or stdout is not a TTY 

29# --------------------------------------------------------------------------- 

30 

31_USE_COLOR: bool = sys.stdout.isatty() and os.environ.get("NO_COLOR", "") == "" 

32 

33PRIORITY_COLOR: dict[str, str] = { 

34 "P0": "38;5;208;1", 

35 "P1": "38;5;208", 

36 "P2": "33", 

37 "P3": "0", 

38 "P4": "2", 

39 "P5": "2", 

40} 

41TYPE_COLOR: dict[str, str] = { 

42 "BUG": "38;5;208", 

43 "FEAT": "32", 

44 "ENH": "34", 

45 "EPIC": "35", 

46} 

47 

48 

49def configure_output(config: CliConfig | None = None) -> None: 

50 """Apply CLI color configuration to module-level color state. 

51 

52 Call this once at startup after loading BRConfig. Updates _USE_COLOR, 

53 PRIORITY_COLOR, and TYPE_COLOR based on config and NO_COLOR env var. 

54 

55 Args: 

56 config: CliConfig from BRConfig.cli, or None for defaults. 

57 """ 

58 global _USE_COLOR, PRIORITY_COLOR, TYPE_COLOR 

59 

60 # NO_COLOR env var always takes precedence (industry convention) 

61 no_color_env = os.environ.get("NO_COLOR", "") != "" 

62 

63 if config is None: 

64 _USE_COLOR = sys.stdout.isatty() and not no_color_env 

65 return 

66 

67 _USE_COLOR = config.color and sys.stdout.isatty() and not no_color_env 

68 

69 # Merge custom priority colors 

70 PRIORITY_COLOR.update( 

71 { 

72 "P0": config.colors.priority.P0, 

73 "P1": config.colors.priority.P1, 

74 "P2": config.colors.priority.P2, 

75 "P3": config.colors.priority.P3, 

76 "P4": config.colors.priority.P4, 

77 "P5": config.colors.priority.P5, 

78 } 

79 ) 

80 

81 # Merge custom type colors 

82 TYPE_COLOR.update( 

83 { 

84 "BUG": config.colors.type.BUG, 

85 "FEAT": config.colors.type.FEAT, 

86 "ENH": config.colors.type.ENH, 

87 "EPIC": config.colors.type.EPIC, 

88 } 

89 ) 

90 

91 

92def use_color_enabled() -> bool: 

93 """Return the current module-level color state set by configure_output().""" 

94 return _USE_COLOR 

95 

96 

97def colorize(text: str, code: str) -> str: 

98 """Wrap *text* in the given ANSI escape *code*, or return it unchanged.""" 

99 if not _USE_COLOR: 

100 return text 

101 return f"\033[{code}m{text}\033[0m" 

102 

103 

104def print_json(data: Any) -> None: 

105 """Print *data* as formatted JSON to stdout.""" 

106 print(json.dumps(data, indent=2)) 

107 

108 

109def format_relative_time(seconds: float) -> str: 

110 """Format seconds as a human-readable relative time string (e.g., '3m ago').""" 

111 total = int(seconds) 

112 if total < 60: 

113 return f"{total}s ago" 

114 if total < 3600: 

115 m, s = divmod(total, 60) 

116 return f"{m}m ago" if s == 0 else f"{m}m {s}s ago" 

117 if total < 86400: 

118 h, rem = divmod(total, 3600) 

119 m = rem // 60 

120 return f"{h}h ago" if m == 0 else f"{h}h {m}m ago" 

121 d, rem = divmod(total, 86400) 

122 h = rem // 3600 

123 return f"{d}d ago" if h == 0 else f"{d}d {h}h ago"