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

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

2from typing import Literal 

3 

4# local 

5from ._width import width 

6 

7 

8def ljust( 

9 text: str, 

10 dest_width: int, 

11 fillchar: str = ' ', 

12 *, 

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

14 ambiguous_width: int = 1, 

15) -> str: 

16 r""" 

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

18 

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

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

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

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

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

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

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

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

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

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

29 

30 .. versionadded:: 0.3.0 

31 

32 Example:: 

33 

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

35 'hi ' 

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

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

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

39 '👨‍👩‍👧 ' 

40 """ 

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

42 text_width = len(text) 

43 else: 

44 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width) 

45 padding_cells = max(0, dest_width - text_width) 

46 return text + fillchar * padding_cells 

47 

48 

49def rjust( 

50 text: str, 

51 dest_width: int, 

52 fillchar: str = ' ', 

53 *, 

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

55 ambiguous_width: int = 1, 

56) -> str: 

57 r""" 

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

59 

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

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

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

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

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

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

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

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

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

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

70 

71 .. versionadded:: 0.3.0 

72 

73 Example:: 

74 

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

76 ' hi' 

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

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

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

80 ' 👨‍👩‍👧' 

81 """ 

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

83 text_width = len(text) 

84 else: 

85 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width) 

86 padding_cells = max(0, dest_width - text_width) 

87 return fillchar * padding_cells + text 

88 

89 

90def center( 

91 text: str, 

92 dest_width: int, 

93 fillchar: str = ' ', 

94 *, 

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

96 ambiguous_width: int = 1, 

97) -> str: 

98 r""" 

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

100 

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

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

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

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

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

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

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

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

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

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

111 

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

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

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

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

116 

117 .. versionadded:: 0.3.0 

118 

119 Example:: 

120 

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

122 ' hi ' 

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

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

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

126 ' 👨‍👩‍👧 ' 

127 """ 

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

129 text_width = len(text) 

130 else: 

131 text_width = width(text, control_codes=control_codes, ambiguous_width=ambiguous_width) 

132 total_padding = max(0, dest_width - text_width) 

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

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

135 right_pad = total_padding - left_pad 

136 return fillchar * left_pad + text + fillchar * right_pad