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')[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'
. A list of version levels suported by wcwidth is returned bylist_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 thewc
argument has no printable effect on a terminal (such as NUL ‘0’), -1 ifwc
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
See Specification for details of cell measurement.
- 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 only the firstn
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
- Returns
The width, in cells, needed to display the first
n
characters of the unicode stringpwcs
. Returns-1
for C0 and C1 control characters!
See Specification for details of cell measurement.
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._wcmatch_version(given_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
and5.0.0
, and a version string of4.9.9
, then4.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
- Returns
unicode string, or non-unicode
str
type for python 2 when givenversion
is also typestr
.