Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/wcwidth/align.py: 29%

1"""Python grapheme, emoji, and sequence-aware ljust, rjust, center().""" 

2from __future__ import annotations 

3 

4from typing import Literal 

5 

6# local 

7from ._width import width 

8 

9 

10def ljust( 

11 text: str, 

12 dest_width: int, 

13 fillchar: str = ' ', 

14 *, 

15 control_codes: Literal['parse', 'strict', 'ignore'] = 'parse', 

16 ambiguous_width: int = 1, 

17 term_program: bool | str = False, 

18) -> str: 

19 r""" 

20 Return text left-justified in a string of given display width. 

21 

22 :param text: String to justify, may contain terminal sequences. 

23 :param dest_width: Total display width of result in terminal cells. 

24 :param fillchar: Single character for padding (default space). Must have 

25 display width of 1 (not wide, not zero-width, not combining). Unicode 

26 characters like ``'·'`` are acceptable. The width is not validated. 

27 :param control_codes: How to handle control sequences when measuring. 

28 Passed to :func:`width` for measurement. 

29 :param ambiguous_width: Width to use for East Asian Ambiguous (A) 

30 characters. Default is ``1`` (narrow). Set to ``2`` for CJK contexts. 

31 :param term_program: Terminal software identifier for table correction. 

32 ``False`` (default) disables override lookup. ``True`` reads the 

33 ``TERM_PROGRAM`` or ``TERM`` environment variable for auto-detection. 

34 Accepts a canonical terminal name matching :func:`list_term_programs`, 

35 such as from XTVERSION_, ENQ_, or ``TERM_PROGRAM``. 

36 

37 .. versionadded:: 0.8.0 

38 :returns: Text padded on the right to reach ``dest_width``. 

39 

40 .. versionadded:: 0.3.0 

41 

42 Example:: 

43 

44 >>> wcwidth.ljust('hi', 5) 

45 'hi ' 

46 >>> wcwidth.ljust('\x1b[31mhi\x1b[0m', 5) 

47 '\x1b[31mhi\x1b[0m ' 

48 >>> wcwidth.ljust('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6) 

49 '👨‍👩‍👧 ' 

50 """ 

51 if text.isascii() and text.isprintable(): 

52 text_width = len(text) 

53 else: 

54 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width, 

55 term_program=term_program) 

56 padding_cells = max(0, dest_width - text_width) 

57 return text + fillchar * padding_cells 

58 

59 

60def rjust( 

61 text: str, 

62 dest_width: int, 

63 fillchar: str = ' ', 

64 *, 

65 control_codes: Literal['parse', 'strict', 'ignore'] = 'parse', 

66 ambiguous_width: int = 1, 

67 term_program: bool | str = False, 

68) -> str: 

69 r""" 

70 Return text right-justified in a string of given display width. 

71 

72 :param text: String to justify, may contain terminal sequences. 

73 :param dest_width: Total display width of result in terminal cells. 

74 :param fillchar: Single character for padding (default space). Must have 

75 display width of 1 (not wide, not zero-width, not combining). Unicode 

76 characters like ``'·'`` are acceptable. The width is not validated. 

77 :param control_codes: How to handle control sequences when measuring. 

78 Passed to :func:`width` for measurement. 

79 :param ambiguous_width: Width to use for East Asian Ambiguous (A) 

80 characters. Default is ``1`` (narrow). Set to ``2`` for CJK contexts. 

81 :param term_program: Terminal software identifier for table correction. 

82 ``False`` (default) disables override lookup. ``True`` reads the 

83 ``TERM_PROGRAM`` or ``TERM`` environment variable for auto-detection. 

84 Accepts a canonical terminal name matching :func:`list_term_programs`, 

85 such as from XTVERSION_, ENQ_, or ``TERM_PROGRAM``. 

86 

87 .. versionadded:: 0.8.0 

88 :returns: Text padded on the left to reach ``dest_width``. 

89 

90 .. versionadded:: 0.3.0 

91 

92 Example:: 

93 

94 >>> wcwidth.rjust('hi', 5) 

95 ' hi' 

96 >>> wcwidth.rjust('\x1b[31mhi\x1b[0m', 5) 

97 ' \x1b[31mhi\x1b[0m' 

98 >>> wcwidth.rjust('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6) 

99 ' 👨‍👩‍👧' 

100 """ 

101 if text.isascii() and text.isprintable(): 

102 text_width = len(text) 

103 else: 

104 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width, 

105 term_program=term_program) 

106 padding_cells = max(0, dest_width - text_width) 

107 return fillchar * padding_cells + text 

108 

109 

110def center( 

111 text: str, 

112 dest_width: int, 

113 fillchar: str = ' ', 

114 *, 

115 control_codes: Literal['parse', 'strict', 'ignore'] = 'parse', 

116 ambiguous_width: int = 1, 

117 term_program: bool | str = False, 

118) -> str: 

119 r""" 

120 Return text centered in a string of given display width. 

121 

122 :param text: String to center, may contain terminal sequences. 

123 :param dest_width: Total display width of result in terminal cells. 

124 :param fillchar: Single character for padding (default space). Must have 

125 display width of 1 (not wide, not zero-width, not combining). Unicode 

126 characters like ``'·'`` are acceptable. The width is not validated. 

127 :param control_codes: How to handle control sequences when measuring. 

128 Passed to :func:`width` for measurement. 

129 :param ambiguous_width: Width to use for East Asian Ambiguous (A) 

130 characters. Default is ``1`` (narrow). Set to ``2`` for CJK contexts. 

131 :param term_program: Terminal software identifier for table correction. 

132 ``False`` (default) disables override lookup. ``True`` reads the 

133 ``TERM_PROGRAM`` or ``TERM`` environment variable for auto-detection. 

134 Accepts a canonical terminal name matching :func:`list_term_programs`, 

135 such as from XTVERSION_, ENQ_, or ``TERM_PROGRAM``. 

136 

137 .. versionadded:: 0.8.0 

138 :returns: Text padded on both sides to reach ``dest_width``. 

139 

140 For odd-width padding, the extra cell fills in the same cell position as 

141 Python's :meth:`str.center` behavior (the left side when ``dest_width`` is 

142 odd, the right side when ``dest_width`` is even). 

143 See `the eccentric str.center <https://jazcap53.github.io/pythons-eccentric-strcenter.html>`_. 

144 

145 .. versionadded:: 0.3.0 

146 

147 Example:: 

148 

149 >>> wcwidth.center('hi', 6) 

150 ' hi ' 

151 >>> wcwidth.center('\x1b[31mhi\x1b[0m', 6) 

152 ' \x1b[31mhi\x1b[0m ' 

153 >>> wcwidth.center('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6) 

154 ' 👨‍👩‍👧 ' 

155 """ 

156 if text.isascii() and text.isprintable(): 

157 text_width = len(text) 

158 else: 

159 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width, 

160 term_program=term_program) 

161 total_padding = max(0, dest_width - text_width) 

162 # matching https://jazcap53.github.io/pythons-eccentric-strcenter.html 

163 left_pad = total_padding // 2 + (total_padding & dest_width & 1) 

164 right_pad = total_padding - left_pad 

165 return fillchar * left_pad + text + fillchar * right_pad