diff options
author | shadchin <shadchin@yandex-team.ru> | 2022-02-10 16:44:30 +0300 |
---|---|---|
committer | Daniil Cherednik <dcherednik@yandex-team.ru> | 2022-02-10 16:44:30 +0300 |
commit | 2598ef1d0aee359b4b6d5fdd1758916d5907d04f (patch) | |
tree | 012bb94d777798f1f56ac1cec429509766d05181 /contrib/python/wcwidth/README.rst | |
parent | 6751af0b0c1b952fede40b19b71da8025b5d8bcf (diff) | |
download | ydb-2598ef1d0aee359b4b6d5fdd1758916d5907d04f.tar.gz |
Restoring authorship annotation for <shadchin@yandex-team.ru>. Commit 1 of 2.
Diffstat (limited to 'contrib/python/wcwidth/README.rst')
-rw-r--r-- | contrib/python/wcwidth/README.rst | 560 |
1 files changed, 280 insertions, 280 deletions
diff --git a/contrib/python/wcwidth/README.rst b/contrib/python/wcwidth/README.rst index 8b87732ad5..497b97f364 100644 --- a/contrib/python/wcwidth/README.rst +++ b/contrib/python/wcwidth/README.rst @@ -1,280 +1,280 @@ -|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 charater : 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 -*printible 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 http://wcwidth.readthedocs.org - -========== -Developing -========== - -Install wcwidth in editable mode:: - - pip install -e. - -Execute unit tests using tox_:: - - tox - -Regenerate python code tables from latest Unicode Specification data files:: - - tox -eupdate - -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 -erequirements-develop.txt`` from this projects main -folder. For example, an interactive browser for testing:: - - ./bin/wcwidth-browser.py - -Uses ----- - -This library is used in: - -- `jquast/blessed`_: a thin, practical wrapper around terminal capabilities in - Python. - -- `jonathanslenders/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. - -- `LuminosoInsight/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. - -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 -- `emugel/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.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 - that are published - , versions - -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 -http://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. - -.. _`tox`: https://testrun.org/tox/latest/install.html -.. _`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/tree/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 -.. _`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 -.. _`jonathanslenders/python-prompt-toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit -.. _`timoxley/wcwidth`: https://github.com/timoxley/wcwidth -.. _`wcwidth(3)`: http://man7.org/linux/man-pages/man3/wcwidth.3.html -.. _`wcswidth(3)`: http://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 -.. _`LuminosoInsight/python-ftfy`: https://github.com/LuminosoInsight/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 -.. _`emugel/wcwidth`: https://github.com/emugel/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 -.. _`fumiyas/wcwidth-cjk`: https://github.com/fumiyas/wcwidth-cjk -.. |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://codecov.io/gh/jquast/wcwidth/ -.. |license| image:: https://img.shields.io/github/license/jquast/wcwidth.svg - :target: https://pypi.python.org/pypi/wcwidth/ - :alt: MIT License +|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 charater : 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 +*printible 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 http://wcwidth.readthedocs.org + +========== +Developing +========== + +Install wcwidth in editable mode:: + + pip install -e. + +Execute unit tests using tox_:: + + tox + +Regenerate python code tables from latest Unicode Specification data files:: + + tox -eupdate + +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 -erequirements-develop.txt`` from this projects main +folder. For example, an interactive browser for testing:: + + ./bin/wcwidth-browser.py + +Uses +---- + +This library is used in: + +- `jquast/blessed`_: a thin, practical wrapper around terminal capabilities in + Python. + +- `jonathanslenders/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. + +- `LuminosoInsight/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. + +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 +- `emugel/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.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 + that are published + , versions + +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 +http://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. + +.. _`tox`: https://testrun.org/tox/latest/install.html +.. _`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/tree/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 +.. _`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 +.. _`jonathanslenders/python-prompt-toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit +.. _`timoxley/wcwidth`: https://github.com/timoxley/wcwidth +.. _`wcwidth(3)`: http://man7.org/linux/man-pages/man3/wcwidth.3.html +.. _`wcswidth(3)`: http://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 +.. _`LuminosoInsight/python-ftfy`: https://github.com/LuminosoInsight/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 +.. _`emugel/wcwidth`: https://github.com/emugel/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 +.. _`fumiyas/wcwidth-cjk`: https://github.com/fumiyas/wcwidth-cjk +.. |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://codecov.io/gh/jquast/wcwidth/ +.. |license| image:: https://img.shields.io/github/license/jquast/wcwidth.svg + :target: https://pypi.python.org/pypi/wcwidth/ + :alt: MIT License |