| 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: contact@jeffquast.com | |
| 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 | |