Public API

This package follows SEMVER rules for version, therefor, for all of the given functions signatures, at example version 1.1.1, you may use version dependency >=1.1.1,<2.0 for forward compatibility of future wcwidth versions.

wcwidth.wcwidth()[source]

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

Parameters:
  • wc (str) – A single Unicode character.
  • unicode_version (str) –

    A Unicode version number, such as '6.0.0', the list of available version levels may be listed by pairing function list_versions().

    Any version string may be specified without error – the nearest matching version is selected. When latest (default), the highest Unicode version level is used.

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.

Return type:

int

The following have a column width of -1:

  • C0 control characters (U+001 through U+01F).
  • C1 control characters and DEL (U+07F through U+0A0).

The following have a column width of 0:

  • Non-spacing and enclosing combining characters (general category code Mn or Me in the Unicode database).
  • NULL (U+0000).
  • COMBINING GRAPHEME JOINER (U+034F).
  • ZERO WIDTH SPACE (U+200B) through RIGHT-TO-LEFT MARK (U+200F).
  • LINE SEPARATOR (U+2028) and PARAGRAPH SEPARATOR (U+2029).
  • LEFT-TO-RIGHT EMBEDDING (U+202A) through RIGHT-TO-LEFT OVERRIDE (U+202E).
  • WORD JOINER (U+2060) through INVISIBLE SEPARATOR (U+2063).

The following have a column width of 1:

  • SOFT HYPHEN (U+00AD).
  • All remaining characters, including all printable ISO 8859-1 and WGL4 characters, Unicode control characters, etc.

The following have a column width of 2:

  • Spacing characters in the East Asian Wide (W) or East Asian Full-width (F) category as defined in Unicode Technical Report #11 have a column width of 2.
  • Some kinds of Emoji or symbols.
wcwidth.wcswidth(pwcs, n=None, unicode_version='auto')[source]

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

Parameters:
  • pwcs (str) – Measure width of given unicode string.
  • n (int) – When n is None (default), return the length of the entire string, otherwise width the first n characters specified.
  • unicode_version (str) – An explicit definition of the unicode version level to use for determination, may be auto (default), which uses the Environment Variable, UNICODE_VERSION if defined, or the latest available unicode version, otherwise.
Return type:

int

Returns:

The width, in cells, necessary to display the first n characters of the unicode string pwcs. Returns -1 if a non-printable character is encountered.

wcwidth.list_versions()[source]

Return Unicode version levels supported by this module release.

Any of the version strings returned may be used as keyword argument unicode_version to the wcwidth() family of functions.

Returns:Supported Unicode version numbers in ascending sorted order.
Return type:list[str]

Private API

These functions should only be used for wcwidth development, and not used by dependent packages except with care and by use of frozen version dependency, as these functions may change names, signatures, or disappear entirely at any time in the future, and not reflected by SEMVER rules.

If stable public API for any of the given functions is needed, please suggest a Pull Request!

wcwidth._bisearch(ucs, table)[source]

Auxiliary function for binary search in interval table.

Parameters:
  • ucs (int) – Ordinal value of unicode character.
  • table (list) – List of starting and ending ranges of ordinal values, in form of [(start, end), ...].
Return type:

int

Returns:

1 if ordinal value ucs is found within lookup table, else 0.

wcwidth._wcversion_value()[source]

Integer-mapped value of given dotted version string.

Parameters:ver_string (str) – Unicode version string, of form n.n.n.
Return type:tuple(int)
Returns:tuple of digit tuples, tuple(int, [...]).
wcwidth._wcmatch_version()[source]

Return nearest matching supported Unicode version level.

If an exact match is not determined, the nearest lowest version level is returned after a warning is emitted. For example, given supported levels 4.1.0 and 5.0.0, and a version string of 4.9.9, then 4.1.0 is selected and returned:

>>> _wcmatch_version('4.9.9')
'4.1.0'
>>> _wcmatch_version('8.0')
'8.0.0'
>>> _wcmatch_version('1')
'4.1.0'
Parameters:given_version (str) – given version for compare, may be auto (default), to select Unicode Version from Environment Variable, UNICODE_VERSION. If the environment variable is not set, then the latest is used.
Return type:str
Returns:unicode string, or non-unicode str type for python 2 when given version is also type str.
wcwidth._wcmatch_version()[source]

Return nearest matching supported Unicode version level.

If an exact match is not determined, the nearest lowest version level is returned after a warning is emitted. For example, given supported levels 4.1.0 and 5.0.0, and a version string of 4.9.9, then 4.1.0 is selected and returned:

>>> _wcmatch_version('4.9.9')
'4.1.0'
>>> _wcmatch_version('8.0')
'8.0.0'
>>> _wcmatch_version('1')
'4.1.0'
Parameters:given_version (str) – given version for compare, may be auto (default), to select Unicode Version from Environment Variable, UNICODE_VERSION. If the environment variable is not set, then the latest is used.
Return type:str
Returns:unicode string, or non-unicode str type for python 2 when given version is also type str.