Public API

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

wcwidth.wcwidth(wc, unicode_version='auto')

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'. A list of version levels suported by wcwidth is returned by 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

See Specification for details of cell measurement.

wcwidth.wcswidth(pwcs, n=None, unicode_version='auto')

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 only the first n characters are measured. This argument exists only for compatibility with the C POSIX function signature. It is suggested instead to use python’s string slicing capability, wcswidth(pwcs[:n])

• 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, needed to display the first n characters of the unicode string pwcs. Returns -1 for C0 and C1 control characters!

See Specification for details of cell measurement.

wcwidth.list_versions()

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)

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(ver_string)

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(given_version)

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.