Introduction
This API is mainly for Terminal Emulator implementors, or those writing programs that expect to interpreted by a terminal emulator and wish to determine the printable width of a string on a Terminal.
Usually, the length of the string is equivalent to the number of cells
it occupies except that there are are also some categories of characters
which occupy 2 or even 0 cells. POSIX-conforming systems provide
wcwidth(3)
and wcswidth(3)
of which this module's interface mirrors
precisely.
This library aims to be forward-looking, portable, and most correct. The most current release of this API is based from Unicode Standard release files:
EastAsianWidth-8.0.0.txt
- 2015-02-10, 21:00:00 GMT [KW, LI]
DerivedGeneralCategory-8.0.0.txt
- 2015-02-13, 13:47:11 GMT [MD]
Installation
The stable version of this package is maintained on pypi, install using pip:
pip install wcwidth
Example
To Display u'コンニチハ'
right-adjusted on screen of 80 columns:
>>> from wcwidth import wcswidth >>> text = u'コンニチハ' >>> print(u' ' * (80 - wcswidth(text)) + text)
wcwidth, wcswidth
Use function wcwidth()
to determine the length of a single character,
and wcswidth()
to determine the length of a string of characters.
Function wcswidth()
simply returns the sum of all values along a string,
individually mapped over function wcwidth()
, or, -1
in total
if any part of the string's return value from wcwidth()
results in
a value of -1
.
Return values of wcwidth are:
-1
- Indeterminate (not printable).
0
- Does not advance the cursor, such as NULL or Combining.
2
- Characters of category East Asian Wide (W) or East Asian Full-width (F) which are displayed using two terminal cells.
1
- All others.
A more exact list of conditions of these return values may be found in the module docstring:
$ pydoc wcwidth
Caveats
This library does its best to return the most appropriate return value for a very particular terminal user interface where a monospaced fixed-cell rendering is expected. As the POSIX Terminal programming interface does not provide any means to determine the unicode support level of a connecting terminal, we can only do our best to return what we assume to be correct for the given codepoint, and not the result of any terminal emulator particular.
Developing
Execute the command python setup.py develop
to prepare an environment
for running tests (python setup.py test
), updating tables (
python setup.py update
) or using any of the scripts in the bin/
sub-folder. These files are only made available in the source repository.
You may determine an exacting list of these discrepancies using the project file wcwidth-libc-comparator.py.
Updating Tables
The command python setup.py update
will fetch the following resources:
- http://www.unicode.org/Public/UNIDATA/EastAsianWidth.txt
- http://www.unicode.org/Public/UNIDATA/extracted/DerivedGeneralCategory.txt
And generates the table files:
wcwidth.c
This code was originally derived directly from C code of the same name, whose latest version is available at http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c And is authored by Markus Kuhn, 2007-05-26 (Unicode 5.0).
Uses
This library is used in:
- jquast/blessed, a simplified wrapper around curses.
- jonathanslenders/python-prompt-toolkit, a Library for building powerful interactive command lines in Python.
Additional tools for displaying and testing wcwidth are found in the bin/ folder of this project. They are not distributed as a script or part of the module.
History
- 0.1.5 2015-09-13 Alpha
- Bugfix: Resolution of "combining character width" issue, most especially those that previously returned -1 now often (correctly) return 0. resolved by Philip Craig via PR #11.
- Deprecated:
The module path
wcwidth.table_comb
is no longer available, it has been superseded by module pathwcwidth.table_zero
.
- 0.1.4 2014-11-20 Pre-Alpha
- Feature:
wcswidth()
now determines printable length for (most) combining characters. The developer's tool bin/wcwidth-browser.py is improved to display combining characters when provided the--combining
option (Thomas Ballinger and Leta Montopoli PR #5). - Feature: added static analysis (prospector) to testing framework.
- Feature:
- 0.1.3 2014-10-29 Pre-Alpha
- Bugfix: 2nd parameter of wcswidth was not honored. (Thomas Ballinger, PR #4).
- 0.1.2 2014-10-28 Pre-Alpha
- Updated tables to Unicode Specification 7.0.0. (Thomas Ballinger, PR #3).
- 0.1.1 2014-05-14 Pre-Alpha
- Initial release to pypi, Based on Unicode Specification 6.3.0