Public API

This package follows SEMVER rules. Therefore, for the functions of the below list, you may safely use version dependency definition wcwidth<1 in your requirements.txt or equivalent. Their signatures will never change.

wcwidth.wcwidth(wc, unicode_version='auto', ambiguous_width=1)[source]

Given one Unicode codepoint, return its printable length on a terminal.

Parameters:

  • wc (str) – A single Unicode character.

  • unicode_version (str) –

    Ignored. Retained for backwards compatibility.

    Deprecated since version 0.3.0: Only the latest Unicode version is now shipped.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts where ambiguous characters display as double-width. See Ambiguous Width for details.

Return type:

int

Returns:

The width, in cells, necessary to display the character of Unicode string character, wc. Returns 0 if the wc argument has no printable effect on a terminal (such as NUL ‘0’), -1 if wc is not printable, or has an indeterminate effect on the terminal, such as a control character. Otherwise, the number of column positions the character occupies on a graphic terminal (1 or 2) is returned.

See Specification for details of cell measurement.

wcwidth.wcswidth(pwcs, n=None, unicode_version='auto', ambiguous_width=1)[source]

Given a unicode string, return its printable length on a terminal.

See Specification for details of cell measurement.

This implementation differs from Markus Khun’s original POSIX C implementation, in that this wcswidth() processes graphemes strings yielded by wcwidth.iter_graphemes() defined by Unicode Standard Annex #29. POSIX wcswidth(3) is not grapheme-aware and does not measure many kinds of Emojis or complex scripts correctly.

Parameters:

  • pwcs (str) – Measure width of given unicode string.

  • n (Optional[int]) – When n is None (default), return the length of the entire string, otherwise only the first n characters are measured.

  • unicode_version (str) –

    Ignored. Retained for backwards compatibility.

    Deprecated since version 0.3.0: Only the latest Unicode version is now shipped.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

Return type:

int

Returns:

The width, in cells, needed to display the first n characters of the unicode string pwcs. Returns -1 for C0 and C1 control characters!

wcwidth.width(text, *, control_codes='parse', tabsize=8, ambiguous_width=1, term_program=False)[source]

Return printable width of text containing many kinds of control codes and sequences.

Unlike wcswidth(), this function handles most control characters and many popular terminal output sequences. Never returns -1.

Parameters:

  • text (str) – String to measure.

  • control_codes (Literal['parse', 'strict', 'ignore']) –

    How to handle control characters and sequences:

    • 'parse' (default): Track horizontal cursor movement like BS \b, CR \r, TAB \t, cursor left and right movement sequences. Vertical movement (LF, VT, FF) and indeterminate terminal sequences are zero-width. OSC 66 Kitty Text Sizing protocol, OSC 8 Hyperlink, and many other kinds of output sequences are parsed for displayed measurements.

    • 'strict': Like parse, but raises ValueError on control characters with indeterminate results of the screen or cursor, like clear or vertical movement. Generally, these should be handled with a virtual terminal emulator (like ‘pyte’).

    • 'ignore': All C0 and C1 control characters and escape sequences are measured as width 0. This is the fastest measurement for text already filtered or known not to contain any kinds of control codes or sequences. TAB \t is zero-width; to ensure tab expansion, pre-process text using str.expandtabs().

  • tabsize (int) – Tab stop width for 'parse' and 'strict' modes. Default is 8. Must be positive. Has no effect when control_codes='ignore'.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

int

Returns:

Maximum cursor position reached, “extent”, accounting for cursor movement sequences present in text according to given parameters. This represents the rightmost column the cursor reaches. Always a non-negative integer.

Raises:

ValueError – If control_codes='strict' and control characters with indeterminate effects, such as vertical movement or clear sequences are encountered, or on unexpected C0 or C1 control code. Also raised when control_codes is not one of the valid values.

Added in version 0.3.0.

Changed in version 0.7.0: Expanded strict-mode to raise ValueError when cursor-left movement (CSI D) would move beyond the beginning of the string. Previously, cursor-left was silently clamped to column 0 in all modes.

Support horizontal cursor sequences (cub, cuf, hpa). Cursor-left (cub) or backspace (\b) now overwrites text. column_address (hpa) and carriage return (\r) are now parsed, and some values conditionally raise ValueError when control_codes='parse'.

Examples:

>>> width('hello')
5
>>> width('コンニチハ')
10
>>> width('\x1b[31mred\x1b[0m')
3
>>> width('\x1b[31mred\x1b[0m', control_codes='ignore')  # same result (ignored)
3
>>> width('123\b4')     # backspace overwrites previous cell (outputs '124')
3
>>> width('abc\t')      # tab caused cursor to move to column 8
8
>>> width('1\x1b[10C')  # '1' + cursor right 10, cursor ends on column 11
11
>>> width('1\x1b[10C', control_codes='ignore')   # faster but wrong in this case
1
wcwidth.iter_sequences(text)[source]

Iterate through text, yielding segments with sequence identification.

This generator yields tuples of (segment, is_sequence) for each part of the input text, where is_sequence is True if the segment is a recognized terminal escape sequence.

Parameters:

text (str) – String to iterate through.

Return type:

Iterator[Tuple[str, bool]]

Returns:

Iterator of (segment, is_sequence) tuples.

Added in version 0.3.0.

Example:

>>> list(iter_sequences('hello'))
[('hello', False)]
>>> list(iter_sequences('\x1b[31mred'))
[('\x1b[31m', True), ('red', False)]
>>> list(iter_sequences('\x1b[1m\x1b[31m'))
[('\x1b[1m', True), ('\x1b[31m', True)]
wcwidth.iter_graphemes(unistr, start=0, end=None)

Iterate over grapheme clusters using unicodedata.iter_graphemes().

Grapheme clusters are “user-perceived characters” - what a user would consider a single character, which may consist of multiple Unicode codepoints (e.g., a base character with combining marks, emoji sequences).

Parameters:

  • unistr (str) – The Unicode string to segment.

  • start (int) – Starting index (default 0).

  • end (int | None) – Ending index (default len(unistr)).

Yields:

Grapheme cluster substrings.

Example:

>>> list(iter_graphemes('cafe\u0301'))
['c', 'a', 'f', 'e\u0301']
>>> list(iter_graphemes('ok\U0001F468\u200D\U0001F469\u200D\U0001F467'))
['o', 'k', '\U0001F468\u200D\U0001F469\u200D\U0001F467']
>>> list(iter_graphemes('ok\U0001F1FA\U0001F1F8'))
['o', 'k', '\U0001F1FA\U0001F1F8']

Added in version 0.3.0.

wcwidth.iter_graphemes_reverse(unistr, start=0, end=None)[source]

Iterate over grapheme clusters in reverse order (last to first).

Parameters:

  • unistr (str) – The Unicode string to segment.

  • start (int) – Starting index (default 0).

  • end (Optional[int]) – Ending index (default len(unistr)).

Yields:

Grapheme cluster substrings in reverse order.

Example:

>>> list(iter_graphemes_reverse('cafe\u0301'))
['e\u0301', 'f', 'a', 'c']

Added in version 0.3.6.

wcwidth.grapheme_boundary_before(unistr, pos)[source]

Find the grapheme cluster boundary immediately before a position.

Parameters:

  • unistr (str) – The Unicode string to search.

  • pos (int) – Position in the string (0 < pos <= len(unistr)).

Return type:

int

Returns:

Start index of the grapheme cluster containing the character at pos-1.

Example:

>>> grapheme_boundary_before('Hello \U0001F44B\U0001F3FB', 8)
6
>>> grapheme_boundary_before('a\r\nb', 3)
1

Added in version 0.3.6.

wcwidth.ljust(text, dest_width, fillchar=' ', *, control_codes='parse', ambiguous_width=1, term_program=False)[source]

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

Parameters:

  • text (str) – String to justify, may contain terminal sequences.

  • dest_width (int) – Total display width of result in terminal cells.

  • fillchar (str) – Single character for padding (default space). Must have display width of 1 (not wide, not zero-width, not combining). Unicode characters like '·' are acceptable. The width is not validated.

  • control_codes (Literal['parse', 'strict', 'ignore']) – How to handle control sequences when measuring. Passed to width() for measurement.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

str

Returns:

Text padded on the right to reach dest_width.

Added in version 0.3.0.

Example:

>>> wcwidth.ljust('hi', 5)
'hi   '
>>> wcwidth.ljust('\x1b[31mhi\x1b[0m', 5)
'\x1b[31mhi\x1b[0m   '
>>> wcwidth.ljust('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6)
'👨‍👩‍👧    '
wcwidth.rjust(text, dest_width, fillchar=' ', *, control_codes='parse', ambiguous_width=1, term_program=False)[source]

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

Parameters:

  • text (str) – String to justify, may contain terminal sequences.

  • dest_width (int) – Total display width of result in terminal cells.

  • fillchar (str) – Single character for padding (default space). Must have display width of 1 (not wide, not zero-width, not combining). Unicode characters like '·' are acceptable. The width is not validated.

  • control_codes (Literal['parse', 'strict', 'ignore']) – How to handle control sequences when measuring. Passed to width() for measurement.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

str

Returns:

Text padded on the left to reach dest_width.

Added in version 0.3.0.

Example:

>>> wcwidth.rjust('hi', 5)
'   hi'
>>> wcwidth.rjust('\x1b[31mhi\x1b[0m', 5)
'   \x1b[31mhi\x1b[0m'
>>> wcwidth.rjust('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6)
'    👨‍👩‍👧'
wcwidth.center(text, dest_width, fillchar=' ', *, control_codes='parse', ambiguous_width=1, term_program=False)[source]

Return text centered in a string of given display width.

Parameters:

  • text (str) – String to center, may contain terminal sequences.

  • dest_width (int) – Total display width of result in terminal cells.

  • fillchar (str) – Single character for padding (default space). Must have display width of 1 (not wide, not zero-width, not combining). Unicode characters like '·' are acceptable. The width is not validated.

  • control_codes (Literal['parse', 'strict', 'ignore']) – How to handle control sequences when measuring. Passed to width() for measurement.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

str

Returns:

Text padded on both sides to reach dest_width.

For odd-width padding, the extra cell fills in the same cell position as Python’s str.center() behavior (the left side when dest_width is odd, the right side when dest_width is even). See the eccentric str.center.

Added in version 0.3.0.

Example:

>>> wcwidth.center('hi', 6)
'  hi  '
>>> wcwidth.center('\x1b[31mhi\x1b[0m', 6)
'  \x1b[31mhi\x1b[0m  '
>>> wcwidth.center('\U0001F468\u200D\U0001F469\u200D\U0001F467', 6)
'  👨‍👩‍👧  '
wcwidth.wrap(text, width=70, *, control_codes='parse', tabsize=8, expand_tabs=True, replace_whitespace=True, ambiguous_width=1, term_program=False, initial_indent='', subsequent_indent='', fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, drop_whitespace=True, max_lines=None, placeholder=' [...]', propagate_sgr=True)[source]

Wrap text to fit within given width, returning a list of wrapped lines.

Like textwrap.wrap(), but measures width in display cells rather than characters, correctly handling wide characters, combining marks, and terminal escape sequences.

Parameters:

  • text (str) – Text to wrap, may contain terminal sequences.

  • width (int) – Maximum line width in display cells.

  • control_codes (Literal['parse', 'strict', 'ignore']) – How to handle terminal sequences (see width()).

  • tabsize (int) – Tab stop width for tab expansion.

  • expand_tabs (bool) – If True (default), tab characters are expanded to spaces using tabsize.

  • replace_whitespace (bool) – If True (default), each whitespace character is replaced with a single space after tab expansion. When False, control whitespace like \n has zero display width (unlike textwrap.wrap() which counts len()), so wrap points may differ from stdlib for non-space whitespace characters.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

  • initial_indent (str) – String prepended to first line.

  • subsequent_indent (str) – String prepended to subsequent lines.

  • fix_sentence_endings (bool) – If True, ensure sentences are always separated by exactly two spaces.

  • break_long_words (bool) – If True, break words longer than width.

  • break_on_hyphens (bool) – If True, allow breaking at hyphens.

  • drop_whitespace (bool) – If True (default), whitespace at the beginning and end of each line (after wrapping but before indenting) is dropped. Set to False to preserve whitespace.

  • max_lines (Optional[int]) – If set, output contains at most this many lines, with placeholder appended to the last line if the text was truncated.

  • placeholder (str) – String appended to the last line when text is truncated by max_lines. Default is ' [...]'.

  • propagate_sgr (bool) – If True (default), SGR (terminal styling) sequences are propagated across wrapped lines. Each line ends with a reset sequence and the next line begins with the active style restored.

Return type:

list[str]

Returns:

List of wrapped lines without trailing newlines.

SGR (terminal styling) sequences are propagated across wrapped lines by default. Each line ends with a reset sequence and the next line begins with the active style restored:

>>> wrap('\x1b[1;34mHello world\x1b[0m', width=6)
['\x1b[1;34mHello\x1b[0m', '\x1b[1;34mworld\x1b[0m']

Set propagate_sgr=False to disable this behavior.

Like textwrap.wrap(), newlines in the input text are treated as whitespace and collapsed. To preserve paragraph breaks, wrap each paragraph separately:

>>> text = 'First line.\nSecond line.'
>>> wrap(text, 40)  # newline collapsed to space
['First line. Second line.']
>>> [line for para in text.split('\n')
...  for line in (wrap(para, 40) if para else [''])]
['First line.', 'Second line.']

See also

textwrap.wrap(), textwrap.TextWrapper

Standard library text wrapping (character-based).

SequenceTextWrapper

Class interface for advanced wrapping options.

Added in version 0.3.0.

Changed in version 0.5.0: Added propagate_sgr parameter (default True).

Changed in version 0.6.0: Added expand_tabs, replace_whitespace, fix_sentence_endings, drop_whitespace, max_lines, and placeholder parameters.

Example:

>>> from wcwidth import wrap
>>> wrap('hello world', 5)
['hello', 'world']
>>> wrap('中文字符', 4)  # CJK characters (2 cells each)
['中文', '字符']
wcwidth.clip(text, start, end, *, fillchar=' ', tabsize=8, ambiguous_width=1, propagate_sgr=True, control_codes='parse', overtyping=None, term_program=False)[source]

Clip text to display columns (start, end) while preserving all terminal sequences.

This function extracts a substring based on visible column positions rather than character indices. Terminal escape sequences are preserved in the output since they have zero display width. If a wide character (width 2) is split at either boundary, it is replaced with fillchar.

TAB characters (\t) are expanded to spaces up to the next tab stop, controlled by the tabsize parameter. When cursor movement is detected, a “painter’s algorithm” is used, cursor movements actively change the write position, allowing cursor-left and carriage return to overwrite previously written cells. It is assumed that text begins at column 0.

OSC 8 hyperlinks are handled specially: the visible text inside a hyperlink is clipped to the requested column range, and the hyperlink is rebuilt around the clipped text. Empty hyperlinks (those with no remaining visible text after clipping) are removed:

>>> clip('\x1b]8;;http://example.com\x07Click This link\x1b]8;;\x07', 6, 10)
'\x1b]8;;http://example.com\x07This\x1b]8;;\x07'
Parameters:

  • text (str) – String to clip, may contain terminal escape sequences.

  • start (int) – Absolute starting column (inclusive, 0-indexed).

  • end (int) – Absolute ending column (exclusive).

  • fillchar (str) – Character to use when a wide character must be split at a boundary (default space). Must have display width of 1.

  • tabsize (int) – Tab stop width (default 8). Set to 0 to pass tabs through as zero-width (preserved in output but don’t advance column position).

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • propagate_sgr (bool) – If True (default), SGR (terminal styling) sequences are propagated. The result begins with any active style at the start position and ends with a reset sequence if styles are active.

  • control_codes (Literal['parse', 'strict', 'ignore']) –

    How to handle control characters and sequences:

    • 'parse' (default): Track horizontal cursor movement and clip hyperlink text. Cursor overwrite is always allowed, with best effort results; indeterminate sequences (home, clear, reset, etc.) are preserved as zero-width.

    • 'strict': Like parse, but raises ValueError on sequences with indeterminate effects (cursor home, clear screen, reset, vertical movement, etc.) matching width() behavior. Also raises on out-of-bounds horizontal cursor movement.

    • 'ignore': All control characters are treated as zero-width. Cursor movement is not tracked (fastest path).

  • overtyping (Optional[bool]) – Whether to use the painter’s algorithm for cursor movement (\b backspace, \r carriage return, and CSI cursor left/right/position sequences). When None (default), auto-detects by scanning for these characters in text. Set to False for improved performance when the caller knows text contains no cursor movement characters. Set to True to force the painter’s algorithm (useful for testing). Has no effect when control_codes='ignore'.

  • term_program (bool | str) –

    Terminal software identifier for table correction. False (default) disables override lookup. True reads the TERM_PROGRAM or TERM environment variable for auto-detection. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

str

Returns:

Substring of text spanning display columns (start, end), with all terminal sequences preserved and wide characters at boundaries replaced with fillchar.

Raises:

ValueError – If control_codes='strict' and an indeterminate-effect sequence or out-of-bounds cursor movement is encountered.

SGR (terminal styling) sequences are propagated by default. The result begins with any active style and ends with a reset:

>>> clip('\x1b[1;34mHello world\x1b[0m', 6, 11)
'\x1b[1;34mworld\x1b[0m'

Set propagate_sgr=False to disable this behavior.

Added in version 0.3.0.

Changed in version 0.5.0: Added propagate_sgr parameter (default True).

Changed in version 0.7.0: Added control_codes parameter (default ‘parse’). OSC 8 hyperlink-aware clipping. OSC 66 text sizing protocol support. Added overtyping parameter (default None, auto-detect).

Example:

>>> clip('hello world', 0, 5)
'hello'
>>> clip('中文字', 0, 3)  # Wide char split at column 3
'中 '
>>> clip('a\tb', 0, 10)  # Tab expanded to spaces
'a       b'
wcwidth.strip_sequences(text)[source]

Return text with all terminal escape sequences removed.

Unknown or incomplete ESC sequences are preserved.

Parameters:

text (str) – String that may contain terminal escape sequences.

Return type:

str

Returns:

The input text with all escape sequences stripped.

Added in version 0.3.0.

Changed in version 0.7.0: Inner text of OSC 66 (Text sizing protocol) is preserved.

Example:

>>> strip_sequences('\x1b[31mred\x1b[0m')
'red'
>>> strip_sequences('hello')
'hello'
>>> strip_sequences('\x1b[1m\x1b[31mbold red\x1b[0m text')
'bold red text'
>>> strip_sequences('\x1b]66;s=2;hello\x07')
'hello'
>>> strip_sequences('\x1b]8;id=34;https://example.com\x1b\\[view]\x1b]8;;\x1b\\')
'[view]'
wcwidth.propagate_sgr(lines)[source]

Propagate SGR codes across wrapped lines.

When text with SGR styling is wrapped across multiple lines, each line needs to be self-contained for proper display. This function:

  • Ends each line with \x1b[0m if styles are active (prevents bleeding)

  • Starts each subsequent line with the active style restored

Parameters:

lines (Sequence[str]) – List of text lines, possibly containing SGR sequences.

Return type:

list[str]

Returns:

List of lines with SGR codes propagated.

Example:

>>> propagate_sgr(['\x1b[31mhello', 'world\x1b[0m'])
['\x1b[31mhello\x1b[0m', '\x1b[31mworld\x1b[0m']

This is useful in cases of making special editors and viewers, and is used for the default modes (propagate_sgr=True) of wcwidth.wrap() and wcwidth.clip().

When wrapping and clipping text containing SGR sequences, maybe a previous line enabled the BLUE color–if we are viewing only the line following, we would want the carry over the BLUE color, and all lines with sequences should end with terminating reset (\x1b[0m).

wcwidth.list_versions()[source]

Return Unicode version levels supported by this module release.

Changed in version 0.5.0: Now returns a single-element tuple containing only the latest version.

Return type:

tuple[str, ...]

Returns:

Supported Unicode version numbers in ascending sorted order.

wcwidth.list_term_programs()[source]

Return all recognized values for the term_program argument.

Includes canonical terminal names and their TERM/TERM_PROGRAM aliases.

Added in version 0.8.0.

Return type:

tuple[str, ...]

A complete OSC 8 hyperlink with target and inner text.

Parameters:

  • params (HyperlinkParams) – Parsed open sequence parameters.

  • text (str) – Inner text between the open and close sequences.

wcwidth.HyperlinkParams(url: str, params: str = '', terminator: str = '\x07')[source]

Parsed parameters from an OSC 8 hyperlink open sequence.

Parameters:

  • url (str) – The hyperlink URL.

  • params (str) – Colon-separated metadata string (often empty).

  • terminator (str) – Sequence terminator (\x07 or \x1b\\).

wcwidth.TextSizing(params: TextSizingParams, text: str, terminator: str)[source]

Basic horizontal width measurement for kitty text sizing protocol.

wcwidth.TextSizingParams(scale: int = 1, width: int = 0, numerator: int = 0, denominator: int = 0, vertical_align: int = 0, horizontal_align: int = 0)[source]

Parsed parameters from a text sizing escape sequence (OSC 66).

Parameters:

  • scale (int) – Scale factor (1-7). Text occupies scale rows tall and scale * width columns wide.

  • width (int) – Width in cells (0-7). When 0, width is auto-calculated from the inner text.

  • numerator (int) – Fractional scaling numerator (0-15).

  • denominator (int) – Fractional scaling denominator (0-15).

  • vertical_align (int) – Vertical alignment (0=top, 1=bottom, 2=center).

  • horizontal_align (int) – Horizontal alignment (0=left, 1=right, 2=center).

wcwidth.wcstwidth(pwcs, n=None, unicode_version='auto', ambiguous_width=1, term_program=True)[source]

Given a unicode string, return its printable length on a terminal given by term_program.

See Specification for details of cell measurement.

Unlike wcswidth(), this function applies per-terminal correction tables for emoji presentation and grapheme clusters.

Parameters:

  • pwcs (str) – Measure width of given unicode string.

  • n (Optional[int]) – When n is None (default), return the length of the entire string, otherwise only the first n characters are measured.

  • unicode_version (str) – Ignored. Retained for backwards compatibility.

  • ambiguous_width (int) – Width to use for East Asian Ambiguous (A) characters. Default is 1 (narrow). Set to 2 for CJK contexts.

  • term_program (bool | str) –

    Terminal software identifier for table correction. True (default) reads the TERM_PROGRAM or TERM environment variable for auto-detection. False disables override lookup. Accepts a canonical terminal name matching list_term_programs(), such as from XTVERSION, ENQ, or TERM_PROGRAM.

    Added in version 0.8.0.

Return type:

int

Returns:

The width, in cells, needed to display the first n characters of the unicode string pwcs. Returns -1 for C0 and C1 control characters!