wcwidth 0.2.7

Introduction

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.

pip install wcwidth

>>> print(len('コンニチハ'))
5

>>> print('コンニチハ'.rjust(20, '_'))
_______________コンニチハ

>>> def wc_rjust(text, length, padding=' '):
...    from wcwidth import wcswidth
...    return padding * max(0, (length - wcswidth(text))) + text
...

>>> from wcwidth import wcswidth
>>> print(wcswidth('コンニチハ'))
10

>>> print(wc_rjust('コンニチハ', 20, '_'))
__________コンニチハ

$ export UNICODE_VERSION=13.0

Developing

Install wcwidth in editable mode:

pip install -e .

Execute unit tests using tox:

tox -e py27,py35,py36,py37,py38,py39,py310,py311,py312

tox -e update

tox -e sphinx

tox -e update_requirements_update

tox -e update_requirements37,update_requirements39

tox -e update_requirements_docs

python ./bin/wcwidth-browser.py

Uses

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

Other Languages

• timoxley/wcwidth: JavaScript

• janlelis/unicode-display_width: Ruby

• alecrabbit/php-wcwidth: PHP

• Text::CharWidth: Perl

• bluebear94/Terminal-WCWidth: Perl 6

• mattn/go-runewidth: Go

• grepsuzette/wcwidth: Haxe

• aperezdc/lua-wcwidth: Lua

• joachimschmidt557/zig-wcwidth: Zig

• fumiyas/wcwidth-cjk: LD_PRELOAD override

• joshuarubin/wcwidth9: Unicode version 9 in C

History

0.2.7 2023-09-28

• Updated tables to include Unicode Specification 15.1.0.

0.2.6 2023-01-14

• Updated tables to include Unicode Specification 14.0.0 and 15.0.0.

• Changed developer tools to use pip-compile, and to use jinja2 templates for code generation in bin/update-tables.py to prepare for possible compiler optimization release.

0.2.1 .. 0.2.5 2020-06-23

• Repository changes to update tests and packaging issues, and begin tagging repository with matching release versions.

0.2.0 2020-06-01

• Enhancement: Unicode version may be selected by exporting the Environment variable UNICODE_VERSION, such as 13.0, or 6.3.0. See the jquast/ucs-detect CLI utility for automatic detection.

• Enhancement: API Documentation is published to readthedocs.org.

• Updated tables for all Unicode Specifications with files published in a programmatically consumable format, versions 4.1.0 through 13.0

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 https://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.