Readme
|pypi_downloads| |codecov| |license|
This library is mainly for CLI programs that carefully produce output for Terminals, or make pretend to be an emulator.
Problem Statement: The printable length of most strings are equal to the
number of cells they occupy on the screen 1 character : 1 cell. 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.
The stable version of this package is maintained on pypi, install using pip::
pip install wcwidth
Problem: given the following phrase (Japanese),
text = u'コンニチハ'
Python incorrectly uses the string length of 5 codepoints rather than the
printable length of 10 cells, so that when using the rjust function, the
output length is wrong::
>>> print(len('コンニチハ'))
5
>>> print('コンニチハ'.rjust(20, '_'))
_______________コンニチハ
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('コンニチハ', 20, '_')) __________コンニチハ
Export an environment variable, UNICODE_VERSION. This should be done by
terminal emulators or those developers experimenting with authoring one of
their own, from shell::
$ export UNICODE_VERSION=13.0
If unspecified, the latest version is used. If your Terminal Emulator does not
export this variable, you can use the jquast/ucs-detect_ utility to
automatically detect and export it to your shell.
Use function wcwidth() to determine the length of a single unicode
character, and wcswidth() to determine the length of many, 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.
Full API Documentation at https://wcwidth.readthedocs.org
Install wcwidth in editable mode::
pip install -e .
Execute unit tests using tox_::
tox -e py27,py35,py36,py37,py38,py39,py310,py311,py312
Regenerate python code tables from latest Unicode Specification data files::
tox -e update
The script is located at bin/update-tables.py, requires Python 3.9 or
later. It is recommended but not necessary to run this script with the newest
Python, because the newest Python has the latest unicodedata for generating
comments.
This project is using sphinx_ 4.5 to build documentation::
tox -e sphinx
The output will be in docs/_build/html/.
This project is using pip-tools_ to manage requirements.
To upgrade requirements for updating unicode version, run::
tox -e update_requirements_update
To upgrade requirements for testing, run::
tox -e update_requirements37,update_requirements39
To upgrade requirements for building documentation, run::
tox -e update_requirements_docs
Supplementary tools for browsing and testing terminals for wide unicode
characters are found in the bin/_ of this project's source code. Just ensure
to first pip install -r requirements-develop.txt from this projects main
folder. For example, an interactive browser for testing::
python ./bin/wcwidth-browser.py
This library is used in:
jquast/blessed_: a thin, practical wrapper around terminal capabilities in
Python.
prompt-toolkit/python-prompt-toolkit_: a Library for building powerful
interactive command lines in Python.
dbcli/pgcli_: Postgres CLI with autocompletion and syntax highlighting.
thomasballinger/curtsies_: a Curses-like terminal wrapper with a display
based on compositing 2d arrays of text.
selectel/pyte_: Simple VTXXX-compatible linux terminal emulator.
astanin/python-tabulate_: Pretty-print tabular data in Python, a library
and a command-line utility.
rspeer/python-ftfy_: Fixes mojibake and other glitches in Unicode
text.
nbedos/termtosvg_: Terminal recorder that renders sessions as SVG
animations.
peterbrittain/asciimatics_: Package to help people create full-screen text
UIs.
python-cmd2/cmd2_: A tool for building interactive command line apps
stratis-storage/stratis-cli_: CLI for the Stratis project
ihabunek/toot_: A Mastodon CLI/TUI client
saulpw/visidata_: Terminal spreadsheet multitool for discovering and
arranging data
timoxley/wcwidth_: JavaScriptjanlelis/unicode-display_width_: Rubyalecrabbit/php-wcwidth_: PHPText::CharWidth_: Perlbluebear94/Terminal-WCWidth_: Perl 6mattn/go-runewidth_: Gogrepsuzette/wcwidth_: Haxeaperezdc/lua-wcwidth_: Luajoachimschmidt557/zig-wcwidth_: Zigfumiyas/wcwidth-cjk_: LD_PRELOAD overridejoshuarubin/wcwidth9_: Unicode version 9 in C0.2.13 2024-01-06
0.2.12 2023-11-21
Issue #101_.0.2.11 2023-11-20
PR #98, PR #100).0.2.10 2023-11-13
PR #97_).Specification <Specification_from_pypi_>_.0.2.9 2023-10-30
PR #91_).Specification <Specification_from_pypi_>_ of
character measurements.0.2.8 2023-09-30
PR #82_).0.2.7 2023-09-28
bin, docs, and tox.ini in the source distribution0.2.6 2023-01-14
bin/update-tables.py to prepare for possible
compiler optimization release.0.2.1 .. 0.2.5 2020-06-23
0.2.0 2020-06-01
UNICODE_VERSION, such as 13.0, or 6.3.0.
See the jquast/ucs-detect_ CLI utility for automatic detection.0.1.9 2020-03-22
Avram Lubkin, PR #35.0.1.8 2020-01-01
PR #30_).0.1.7 2016-07-01
PR #18_).0.1.6 2016-01-08 Production/Stable
LICENSE file now included with distribution.0.1.5 2015-09-13 Alpha
Philip Craig_ via PR #11_.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
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_).0.1.3 2014-10-29 Pre-Alpha
Thomas Ballinger, PR #4).0.1.2 2014-10-28 Pre-Alpha
Thomas Ballinger, PR #3).0.1.1 2014-05-14 Pre-Alpha
This code was originally derived directly from C code of the same name, whose latest version is available at https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c::
.. _Specification_from_pypi: https://wcwidth.readthedocs.io/en/latest/specs.html
.. _tox: https://tox.wiki/en/latest/
.. _prospector: https://github.com/landscapeio/prospector
.. _combining: https://en.wikipedia.org/wiki/Combining_character
.. _bin/: https://github.com/jquast/wcwidth/tree/master/bin
.. _bin/wcwidth-browser.py: https://github.com/jquast/wcwidth/blob/master/bin/wcwidth-browser.py
.. _Thomas Ballinger: https://github.com/thomasballinger
.. _Leta Montopoli: https://github.com/lmontopo
.. _Philip Craig: https://github.com/philipc
.. _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
.. _PR #82: https://github.com/jquast/wcwidth/pull/82
.. _PR #91: https://github.com/jquast/wcwidth/pull/91
.. _PR #97: https://github.com/jquast/wcwidth/pull/97
.. _PR #98: https://github.com/jquast/wcwidth/pull/98
.. _PR #100: https://github.com/jquast/wcwidth/pull/100
.. _Issue #101: https://github.com/jquast/wcwidth/issues/101
.. _jquast/blessed: https://github.com/jquast/blessed
.. _selectel/pyte: https://github.com/selectel/pyte
.. _thomasballinger/curtsies: https://github.com/thomasballinger/curtsies
.. _dbcli/pgcli: https://github.com/dbcli/pgcli
.. _prompt-toolkit/python-prompt-toolkit: https://github.com/prompt-toolkit/python-prompt-toolkit
.. _timoxley/wcwidth: https://github.com/timoxley/wcwidth
.. _wcwidth(3): https://man7.org/linux/man-pages/man3/wcwidth.3.html
.. _wcswidth(3): https://man7.org/linux/man-pages/man3/wcswidth.3.html
.. _astanin/python-tabulate: https://github.com/astanin/python-tabulate
.. _janlelis/unicode-display_width: https://github.com/janlelis/unicode-display_width
.. _rspeer/python-ftfy: https://github.com/rspeer/python-ftfy
.. _alecrabbit/php-wcwidth: https://github.com/alecrabbit/php-wcwidth
.. _Text::CharWidth: https://metacpan.org/pod/Text::CharWidth
.. _bluebear94/Terminal-WCWidth: https://github.com/bluebear94/Terminal-WCWidth
.. _mattn/go-runewidth: https://github.com/mattn/go-runewidth
.. _grepsuzette/wcwidth: https://github.com/grepsuzette/wcwidth
.. _jquast/ucs-detect: https://github.com/jquast/ucs-detect
.. _Avram Lubkin: https://github.com/avylove
.. _nbedos/termtosvg: https://github.com/nbedos/termtosvg
.. _peterbrittain/asciimatics: https://github.com/peterbrittain/asciimatics
.. _aperezdc/lua-wcwidth: https://github.com/aperezdc/lua-wcwidth
.. _joachimschmidt557/zig-wcwidth: https://github.com/joachimschmidt557/zig-wcwidth
.. _fumiyas/wcwidth-cjk: https://github.com/fumiyas/wcwidth-cjk
.. _joshuarubin/wcwidth9: https://github.com/joshuarubin/wcwidth9
.. _python-cmd2/cmd2: https://github.com/python-cmd2/cmd2
.. _stratis-storage/stratis-cli: https://github.com/stratis-storage/stratis-cli
.. _ihabunek/toot: https://github.com/ihabunek/toot
.. _saulpw/visidata: https://github.com/saulpw/visidata
.. _pip-tools: https://pip-tools.readthedocs.io/
.. _sphinx: https://www.sphinx-doc.org/
.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/wcwidth.svg?logo=pypi
:alt: Downloads
:target: https://pypi.org/project/wcwidth/
.. |codecov| image:: https://codecov.io/gh/jquast/wcwidth/branch/master/graph/badge.svg
:alt: codecov.io Code Coverage
:target: https://app.codecov.io/gh/jquast/wcwidth/
.. |license| image:: https://img.shields.io/pypi/l/wcwidth.svg
:target: https://pypi.org/project/wcwidth/
:alt: MIT License
FAQs
Measures the displayed width of unicode strings in a terminal
We found that wcwidth demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers have uncovered 3.7 million fake GitHub stars, highlighting a growing threat linked to scams, fraud, and malware, with these campaigns rapidly increasing over the last six months.
Security News
Deno's Standard Library has stabilized after four years of development, offering developers a collection of well-maintained tools compatible with Deno, Node.js, Cloudflare Workers, and browsers with bundlers.
Security News
Trivial packages, while convenient, can introduce significant risks such as dependency bloat, security vulnerabilities, and performance issues in modern software projects.