Spaces:
Running
Running
Metadata-Version: 2.1 | |
Name: wcwidth | |
Version: 0.2.13 | |
Summary: Measures the displayed width of unicode strings in a terminal | |
Home-page: https://github.com/jquast/wcwidth | |
Author: Jeff Quast | |
Author-email: [email protected] | |
License: MIT | |
Keywords: cjk,combining,console,eastasian,emoji,emulator,terminal,unicode,wcswidth,wcwidth,xterm | |
Classifier: Intended Audience :: Developers | |
Classifier: Natural Language :: English | |
Classifier: Development Status :: 5 - Production/Stable | |
Classifier: Environment :: Console | |
Classifier: License :: OSI Approved :: MIT License | |
Classifier: Operating System :: POSIX | |
Classifier: Programming Language :: Python :: 2.7 | |
Classifier: Programming Language :: Python :: 3.5 | |
Classifier: Programming Language :: Python :: 3.6 | |
Classifier: Programming Language :: Python :: 3.7 | |
Classifier: Programming Language :: Python :: 3.8 | |
Classifier: Programming Language :: Python :: 3.9 | |
Classifier: Programming Language :: Python :: 3.10 | |
Classifier: Programming Language :: Python :: 3.11 | |
Classifier: Programming Language :: Python :: 3.12 | |
Classifier: Topic :: Software Development :: Libraries | |
Classifier: Topic :: Software Development :: Localization | |
Classifier: Topic :: Software Development :: Internationalization | |
Classifier: Topic :: Terminals | |
License-File: LICENSE | |
Requires-Dist: backports.functools-lru-cache >=1.2.1 ; python_version < "3.2" | |
|pypi_downloads| |codecov| |license| | |
============ | |
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.* | |
Installation | |
------------ | |
The stable version of this package is maintained on pypi, install using pip:: | |
pip install wcwidth | |
Example | |
------- | |
**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, '_')) | |
__________γ³γ³γγγ | |
Choosing a Version | |
------------------ | |
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. | |
wcwidth, wcswidth | |
----------------- | |
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 | |
========== | |
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 | |
Updating Unicode Version | |
------------------------ | |
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. | |
Building Documentation | |
---------------------- | |
This project is using `sphinx`_ 4.5 to build documentation:: | |
tox -e sphinx | |
The output will be in ``docs/_build/html/``. | |
Updating Requirements | |
--------------------- | |
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 | |
Utilities | |
--------- | |
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 | |
==== | |
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.13 *2024-01-06* | |
* **Bugfix** zero-width support for Hangul Jamo (Korean) | |
0.2.12 *2023-11-21* | |
* re-release to remove .pyi file misplaced in wheel files `Issue #101`_. | |
0.2.11 *2023-11-20* | |
* Include tests files in the source distribution (`PR #98`_, `PR #100`_). | |
0.2.10 *2023-11-13* | |
* **Bugfix** accounting of some kinds of emoji sequences using U+FE0F | |
Variation Selector 16 (`PR #97`_). | |
* **Updated** `Specification <Specification_from_pypi_>`_. | |
0.2.9 *2023-10-30* | |
* **Bugfix** zero-width characters used in Emoji ZWJ sequences, Balinese, | |
Jamo, Devanagari, Tamil, Kannada and others (`PR #91`_). | |
* **Updated** to include `Specification <Specification_from_pypi_>`_ of | |
character measurements. | |
0.2.8 *2023-09-30* | |
* Include requirements files in the source distribution (`PR #82`_). | |
0.2.7 *2023-09-28* | |
* **Updated** tables to include Unicode Specification 15.1.0. | |
* Include ``bin``, ``docs``, and ``tox.ini`` in the source distribution | |
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. | |
.. _`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 | |