Package: wcwidth
IntroductionThis library is mainly for CLI programs that carefully produce output for
Terminals, or make pretend to be an emulator.Problem Statement: The printable length ofmoststrings are equal to the
number of cells they occupy on the screen1 character : 1 cell.  However,
there are categories of characters thatoccupy 2 cells(full-wide), and
others thatoccupy 0cells (zero-width).Solution: POSIX.1-2001 and POSIX.1-2008 conforming systems providewcwidth(3)andwcswidth(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.InstallationThe stable version of this package is maintained on pypi, install using pip:pip install wcwidthExampleProblem: given the following phrase (Japanese),>>>  text = u'コンニチハ'Pythonincorrectlyuses thestring lengthof 5 codepoints rather than theprintable lengthof 10 cells, so that when using therjustfunction, 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
...OurSolutionuses wcswidth to determine the string length correctly:>>> from wcwidth import wcswidth
>>> print(wcswidth('コンニチハ'))
10

>>> print(wc_rjust('コンニチハ', 20, '_'))
__________コンニチハChoosing a VersionExport an environment variable,UNICODE_VERSION. This should be done byterminal emulatorsor those developers experimenting with authoring one of
their own, from shell:$ export UNICODE_VERSION=13.0If unspecified, the latest version is used. If your Terminal Emulator does not
export this variable, you can use thejquast/ucs-detectutility to
automatically detect and export it to your shell.wcwidth, wcswidthUse functionwcwidth()to determine the length of asingle unicode
character, andwcswidth()to determine the length of many, astring
of unicode characters.Briefly, return values of functionwcwidth()are:-1Indeterminate (not printable).0Does not advance the cursor, such as NULL or Combining.2Characters of category East Asian Wide (W) or East Asian
Full-width (F) which are displayed using two terminal cells.1All others.Functionwcswidth()simply returns the sum of all values for each character
along a string, or-1when it occurs anywhere along a string.Full API Documentation athttps://wcwidth.readthedocs.orgDevelopingInstall wcwidth in editable mode:pip install -e .Execute unit tests usingtox:tox -e py27,py35,py36,py37,py38,py39,py310,py311,py312Updating Unicode VersionRegenerate python code tables from latest Unicode Specification data files:tox -e updateThe script is located atbin/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 latestunicodedatafor generating
comments.Building DocumentationThis project is usingsphinx4.5 to build documentation:tox -e sphinxThe output will be indocs/_build/html/.Updating RequirementsThis project is usingpip-toolsto manage requirements.To upgrade requirements for updating unicode version, run:tox -e update_requirements_updateTo upgrade requirements for testing, run:tox -e update_requirements37,update_requirements39To upgrade requirements for building documentation, run:tox -e update_requirements_docsUtilitiesSupplementary tools for browsing and testing terminals for wide unicode
characters are found in thebin/of this project’s source code.  Just ensure
to firstpip install-rrequirements-develop.txtfrom this projects main
folder. For example, an interactive browser for testing:python ./bin/wcwidth-browser.pyUsesThis 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 appsstratis-storage/stratis-cli: CLI for the Stratis projectihabunek/toot: A Mastodon CLI/TUI clientsaulpw/visidata: Terminal spreadsheet multitool for discovering and
arranging dataOther Languagestimoxley/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_PRELOADoverridejoshuarubin/wcwidth9: Unicode version 9 in CHistory0.2.132024-01-06Bugfixzero-width support for Hangul Jamo (Korean)0.2.122023-11-21re-release to remove .pyi file misplaced in wheel filesIssue #101.0.2.112023-11-20Include tests files in the source distribution (PR #98,PR #100).0.2.102023-11-13Bugfixaccounting of some kinds of emoji sequences using U+FE0F
Variation Selector 16 (PR #97).UpdatedSpecification.0.2.92023-10-30Bugfixzero-width characters used in Emoji ZWJ sequences, Balinese,
Jamo, Devanagari, Tamil, Kannada and others (PR #91).Updatedto includeSpecificationof
character measurements.0.2.82023-09-30Include requirements files in the source distribution (PR #82).0.2.72023-09-28Updatedtables to include Unicode Specification 15.1.0.Includebin,docs, andtox.iniin the source distribution0.2.62023-01-14Updatedtables to include Unicode Specification 14.0.0 and 15.0.0.Changeddeveloper tools to use pip-compile, and to use jinja2 templates
for code generation inbin/update-tables.pyto prepare for possible
compiler optimization release.0.2.1 .. 0.2.52020-06-23Repositorychanges to update tests and packaging issues, and
begin tagging repository with matching release versions.0.2.02020-06-01Enhancement: Unicode version may be selected by exporting the
Environment variableUNICODE_VERSION, such as13.0, or6.3.0.
See thejquast/ucs-detectCLI utility for automatic detection.Enhancement:
API Documentation is published to readthedocs.org.Updatedtables forallUnicode Specifications with files
published in a programmatically consumable format, versions 4.1.0
through 13.00.1.92020-03-22Performanceoptimization byAvram Lubkin,PR #35.Updatedtables to Unicode Specification 13.0.0.0.1.82020-01-01Updatedtables to Unicode Specification 12.0.0. (PR #30).0.1.72016-07-01Updatedtables to Unicode Specification 9.0.0. (PR #18).0.1.62016-01-08 Production/StableLICENSEfile now included with distribution.0.1.52015-09-13 AlphaBugfix:
Resolution of “combiningcharacter width” issue, most especially
those that previously returned -1 now often (correctly) return 0.
resolved byPhilip CraigviaPR #11.Deprecated:
The module pathwcwidth.table_combis no longer available,
it has been superseded by module pathwcwidth.table_zero.0.1.42014-11-20 Pre-AlphaFeature:wcswidth()now determines printable length
for (most)combiningcharacters.  The developer’s toolbin/wcwidth-browser.pyis improved to displaycombiningcharacters when provided the--combiningoption
(Thomas BallingerandLeta MontopoliPR #5).Feature: added static analysis (prospector) to testing
framework.0.1.32014-10-29 Pre-AlphaBugfix: 2nd parameter of wcswidth was not honored.
(Thomas Ballinger,PR #4).0.1.22014-10-28 Pre-AlphaUpdatedtables to Unicode Specification 7.0.0.
(Thomas Ballinger,PR #3).0.1.12014-05-14 Pre-AlphaInitial release to pypi, Based on Unicode Specification 6.3.0This code was originally derived directly from C code of the same name,
whose latest version is available athttps://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.