codekingpro/portable-devtools

1"""2This is a python implementation of wcwidth() and wcswidth().3 4https://github.com/jquast/wcwidth5 6Derived from Markus Kuhn's C code,7 8This is an implementation of wcwidth() and wcswidth() (defined in9IEEE Std 1002.1-2001) for Unicode.10 11http://www.opengroup.org/onlinepubs/007904975/functions/wcwidth.html12http://www.opengroup.org/onlinepubs/007904975/functions/wcswidth.html13 14In fixed-width output devices, Latin characters all occupy a single15"cell" position of equal width, whereas ideographic CJK characters16occupy two such cells. Interoperability between terminal-line17applications and (teletype-style) character terminals using the18UTF-8 encoding requires agreement on which character should advance19the cursor by how many cell positions. No established formal20standards exist at present on which Unicode character shall occupy21how many cell positions on character terminals. These routines are22a first attempt of defining such behavior based on simple rules23applied to data provided by the Unicode Consortium.24 25For some graphical characters, the Unicode standard explicitly26defines a character-cell width via the definition of the East Asian27FullWidth (F), Wide (W), Half-width (H), and Narrow (Na) classes.28In all these cases, there is no ambiguity about which width a29terminal shall use. For characters in the East Asian Ambiguous (A)30class, the width choice depends purely on a preference of backward31compatibility with either historic CJK or Western practice.32Choosing single-width for these characters is easy to justify as33the appropriate long-term solution, as the CJK practice of34displaying these characters as double-width comes from historic35implementation simplicity (8-bit encoded characters were displayed36single-width and 16-bit ones double-width, even for Greek,37Cyrillic, etc.) and not any typographic considerations.38 39Much less clear is the choice of width for the Not East Asian40(Neutral) class. Existing practice does not dictate a width for any41of these characters. It would nevertheless make sense42typographically to allocate two character cells to characters such43as for instance EM SPACE or VOLUME INTEGRAL, which cannot be44represented adequately with a single-width glyph. The following45routines at present merely assign a single-cell width to all46neutral characters, in the interest of simplicity. This is not47entirely satisfactory and should be reconsidered before48establishing a formal standard in this area. At the moment, the49decision which Not East Asian (Neutral) characters should be50represented by double-width glyphs cannot yet be answered by51applying a simple rule from the Unicode database content. Setting52up a proper standard for the behavior of UTF-8 character terminals53will require a careful analysis not only of each Unicode character,54but also of each presentation form, something the author of these55routines has avoided to do so far.56 57http://www.unicode.org/unicode/reports/tr11/58 59Latest version: http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c60"""61 62from __future__ import annotations63 64# std imports65from functools import lru_cache66 67# local68from .bisearch import bisearch69from ._constants import _LATEST_VERSION, _AMBIGUOUS_TABLE, _ZERO_WIDTH_TABLE, _WIDE_EASTASIAN_TABLE70 71 72@lru_cache(maxsize=128)73def _wcversion_value(ver_string: str) -> tuple[int, ...]:  # pragma: no cover74    """75    Integer-mapped value of given dotted version string.76 77    .. deprecated:: 0.3.078 79        This function is no longer used internally by wcwidth but is retained80        for API compatibility with external tools.81 82    :param ver_string: Unicode version string, of form ``n.n.n``.83    :returns: tuple of digit tuples, ``tuple(int, [...])``.84    """85    retval = tuple(map(int, (ver_string.split('.'))))86    return retval87 88 89@lru_cache(maxsize=8)90def _wcmatch_version(given_version: str) -> str:  # pylint: disable=unused-argument91    """92    Return the supported Unicode version level.93 94    .. deprecated:: 0.3.095        This function now always returns the latest version.96 97        This function is no longer used internally by wcwidth but is retained98        for API compatibility with external tools.99 100    :param given_version: Ignored. Any value is accepted for compatibility.101    :returns: The latest unicode version string.102    """103    return _LATEST_VERSION104 105 106# maxsize=1024: western scripts need ~64 unique codepoints per session, but107# CJK sessions may use ~2000 of ~3500 common hanzi/kanji. 1024 accommodates108# heavy CJK use. Performance floor at 32; bisearch is ~100ns per miss.109 110@lru_cache(maxsize=1024)111def wcwidth(wc: str, unicode_version: str = 'auto', ambiguous_width: int = 1) -> int:  # pylint: disable=unused-argument112    r"""113    Given one Unicode codepoint, return its printable length on a terminal.114 115    :param wc: A single Unicode character.116    :param unicode_version: Ignored. Retained for backwards compatibility.117 118        .. deprecated:: 0.3.0119           Only the latest Unicode version is now shipped.120 121    :param ambiguous_width: Width to use for East Asian Ambiguous (A)122        characters. Default is ``1`` (narrow). Set to ``2`` for CJK contexts123        where ambiguous characters display as double-width. See124        :ref:`ambiguous_width` for details.125    :returns: The width, in cells, necessary to display the character of126        Unicode string character, ``wc``.  Returns 0 if the ``wc`` argument has127        no printable effect on a terminal (such as NUL '\0'), -1 if ``wc`` is128        not printable, or has an indeterminate effect on the terminal, such as129        a control character.  Otherwise, the number of column positions the130        character occupies on a graphic terminal (1 or 2) is returned.131 132    See :ref:`Specification` for details of cell measurement.133    """134    ucs = ord(wc) if wc else 0135 136    # small optimization: early return of 1 for printable ASCII, this provides137    # approximately 40% performance improvement for mostly-ascii documents, with138    # less than 1% impact to others.139    if 32 <= ucs < 0x7f:140        return 1141 142    # C0/C1 control characters are -1 for compatibility with POSIX-like calls143    if ucs and ucs < 32 or 0x07F <= ucs < 0x0A0:144        return -1145 146    # Zero width147    if bisearch(ucs, _ZERO_WIDTH_TABLE):148        return 0149 150    # Wide (F/W categories)151    if bisearch(ucs, _WIDE_EASTASIAN_TABLE):152        return 2153 154    # Ambiguous width (A category) - only when ambiguous_width=2155    if ambiguous_width == 2 and bisearch(ucs, _AMBIGUOUS_TABLE):156        return 2157 158    return 1159