1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
Metadata-Version: 1.1
Name: wcwidth
Version: 0.1.9
Summary: Measures number of Terminal column cells of wide-character codes
Home-page: https://github.com/jquast/wcwidth
Author: Jeff Quast
Author-email: contact@jeffquast.com
License: MIT
Description: ============
Introduction
============
This Library is mainly for those implementing a Terminal Emulator, or programs
that carefully produce output to mimick or to be interpreted by an emulator.
**Problem Statement**: The printible length of *most* strings are equal to the
number of cells they occupy on the screen. However, there are categories of
characters that *occupy 2 cells* (full-wide), and others that *occupy 0* cells
(zero-width).
**Solution**: POSIX.1-2001 and POSIX.1-2008 conforming systems provide
`wcwidth(3)`_ and `wcswidth(3)`_ C functions of which this python module's
functions precisely copy. *These functions return the number of cells a
unicode string is expected to occupy.*
Installation
------------
The stable version of this package is maintained on pypi, install or upgrade using pip::
pip install --upgrade wcwidth
Example
-------
**Problem**: given the following phrase (Japanese),
>>> text = u'コンニチハ'
Python **incorrectly** uses the *string length* of 5 codepoints rather than the
*printible length* of 10 cells, so that when using the `rjust` function, the
output length is wrong::
>>> print(len('コンニチハ'))
5
>>> print('コンニチハ'.rjust(11, '_'))
______コンニチハ
By defining our own "rjust" function that uses wcwidth, we can correct this::
>>> def wc_rjust(text, length, padding=' '):
... from wcwidth import wcswidth
... return padding * max(0, (length - wcswidth(text))) + text
...
Our **Solution** uses wcswidth to determine the string length correctly::
>>> from wcwidth import wcswidth
>>> print(wcswidth('コンニチハ'))
10
>>> print(wc_rjust('コンニチハ', 11, '_'))
_コンニチハ
Uses
----
This library is used in:
- asciimatics_: Package to help people create full-screen text UIs.
- blessed_: a simplified wrapper around curses.
- curtsies_: Curses wrapper with a display based on compositing 2d arrays of text.
- ftfy_: Fixes mojibake and other glitches in Unicode text, after the fact.
- pyte_: a Simple VTXXX-compatible linux terminal emulator.
- python-prompt-toolkit_: a Powerful interactive command line building library.
- termtosvg_: Terminal recorder that renders sessions as SVG animations.
wcwidth, wcswidth
-----------------
Use function ``wcwidth()`` to determine the length of a *single unicode
character*, and ``wcswidth()`` to determine the length of a several, or a
*string of unicode characters*.
Briefly, return values of function ``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.
Function ``wcswidth()`` simply returns the sum of all values for each character
along a string, or ``-1`` when it occurs anywhere along a string.
More documentation is available using pydoc::
$ pydoc wcwidth
=======
Caveats
=======
This library attempts to determine the printable width by a fictional terminal,
using the very latest Unicode specification, though some work is in progress for
the ability to select a version, there is no standards conforming ability to
discern what the target emulator software, version, of level of support is.
Results may vary!
A `crude method
<http://blessed.readthedocs.org/en/latest/examples.html#detect-multibyte-py>`_
of determining the level of unicode support by the target emulator may be
performed using the VT100 Query Cursor Position sequence.
The libc version of `wcwidth(3)`_ is often several unicode releases behind,
and therefor several levels of support lower than this python library.
==========
Developing
==========
Install wcwidth in editable mode::
pip install -e.
Install developer requirements::
pip install -r requirements-develop.txt
Execute unit tests using tox::
tox
Use the interactive browser::
python bin/wcwidth-browser.py
This library aims to be forward-looking, portable, and most correct. The most
current release of this API is based on the Unicode Standard release files:
``DerivedGeneralCategory-13.0.0.txt``
*Date: 2019-10-21, 14:30:32 GMT*
© 2019 Unicode®, Inc.
``EastAsianWidth-13.0.0.txt``
*Date: 2020-01-21, 18:14:00 GMT [KW, LI]*
© 2020 Unicode®, Inc.
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/table_wide.py <https://github.com/jquast/wcwidth/tree/master/wcwidth/table_wide.py>`_
- `wcwidth/table_zero.py <https://github.com/jquast/wcwidth/tree/master/wcwidth/table_zero.py>`_
=======
History
=======
0.1.9 *2020-03-22*
* **Performance** optimization by `Avram Lubkin`_, `PR #35`_.
* **Updated** tables to Unicode Specification 13.0.0.
0.1.8 *2020-01-01*
* **Updated** tables to Unicode Specification 12.0.0. (`PR #30`_).
0.1.7 *2016-07-01*
* **Updated** tables to Unicode Specification 9.0.0. (`PR #18`_).
0.1.6 *2016-01-08 Production/Stable*
* ``LICENSE`` file now included with distribution.
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 path ``wcwidth.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.
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
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::
* Markus Kuhn -- 2007-05-26 (Unicode 5.0)
*
* Permission to use, copy, modify, and distribute this software
* for any purpose and without fee is hereby granted. The author
* disclaims all warranties with regard to this software.
.. _`prospector`: https://github.com/landscapeio/prospector
.. _`combining`: https://en.wikipedia.org/wiki/Combining_character
.. _`bin/wcwidth-browser.py`: https://github.com/jquast/wcwidth/tree/master/bin/wcwidth-browser.py
.. _`Thomas Ballinger`: https://github.com/thomasballinger
.. _`Leta Montopoli`: https://github.com/lmontopo
.. _`Philip Craig`: https://github.com/philipc
.. _`Avram Lubkin`: https://github.com/avylove
.. _`PR #3`: https://github.com/jquast/wcwidth/pull/3
.. _`PR #4`: https://github.com/jquast/wcwidth/pull/4
.. _`PR #5`: https://github.com/jquast/wcwidth/pull/5
.. _`PR #11`: https://github.com/jquast/wcwidth/pull/11
.. _`PR #18`: https://github.com/jquast/wcwidth/pull/18
.. _`PR #30`: https://github.com/jquast/wcwidth/pull/30
.. _`PR #35`: https://github.com/jquast/wcwidth/pull/35
.. _blessed: https://github.com/jquast/blessed
.. _python-prompt-toolkit: https://github.com/prompt-toolkit/python-prompt-toolkit
.. _pyte: https://github.com/selectel/pyte
.. _asciimatics: https://github.com/peterbrittain/asciimatics
.. _ftfy: https://github.com/LuminosoInsight/python-ftfy
.. _curtsies: https://github.com/bpython/curtsies
.. _bpython: https://github.com/bpython/bpython
.. _termtosvg: https://github.com/nbedos/termtosvg
.. _`wcwidth(3)`: http://man7.org/linux/man-pages/man3/wcwidth.3.html
.. _`wcswidth(3)`: http://man7.org/linux/man-pages/man3/wcswidth.3.html
Keywords: terminal,emulator,wcwidth,wcswidth,cjk,combining,xterm,console
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Terminals
|
