New: ljust(), rjust(), center() justify text (#168)

Justify text with control-code and sequence-awareness, requires #166 

Example,

        >>> wcwidth.center('hi', 6)
        '  hi  '
        >>> wcwidth.center('\\x1b[31mhi\\x1b[0m', 6)
        '  \\x1b[31mhi\\x1b[0m  '
        >>> wcwidth.center('\\U0001F468\\u200D\\U0001F469\\u200D\\U0001F467', 6)
        '  👨‍👩‍👧  '

Author: jquast

docs/api.rst

@@ -12,10 +12,16 @@ requirements.txt or equivalent. Their signatures will never change.
 
 .. autofunction:: wcwidth.width
 
-.. autofunction:: wcwidth.iter_sequences
+.. autofunction:: wcwidth.ljust
+
+.. autofunction:: wcwidth.rjust
+
+.. autofunction:: wcwidth.center
 
 .. autofunction:: wcwidth.iter_graphemes
 
+.. autofunction:: wcwidth.iter_sequences
+
 .. autofunction:: wcwidth.list_versions
 
 .. _SEMVER: https://semver.org

docs/intro.rst

@@ -32,13 +32,18 @@ Some examples of **incorrect results**:
     >>> 'café'.center(6, 'X')
     'caféX'
 
+    >>> # result consumes 4 total cells, 2 expected
+    >>> '🇿🇼'.ljust(2, 'X')
+    '🇿🇼  '
+
     >>> # result consumes 2 total cells, 4 expected.
     >>> print('👨‍👩‍👧'.center(4, 'X'))
     👨‍👩‍👧
 
 Solution
 --------
 
+
 The base functions of this library are the POSIX.1-2001 and POSIX.1-2008 `wcwidth(3)`_ and
 `wcswidth(3)`_, which this library precisely copies by interface as `wcwidth()`_ and `wcswidth()`_.
 These functions return -1 when C0 and C1 control codes are present.
@@ -48,7 +53,8 @@ the displayed width of most C0 and C1 control codes, and measuring many kinds of
 like colors, bold, tabstops, and horizontal cursor movement. This is aided by the
 `iter_sequences()`_ function that provides an iterator over terminal sequences.
 
-A ``iter_graphemes()`` iterator function is provided to help format strings for a terminal.
+To solve the justification problem, this library provides `ljust()`_, `rjust()`_, and `center()`_
+functions that properly handle Unicode character widths and terminal escape sequences.
 
 Discrepancies
 -------------
@@ -78,23 +84,8 @@ Measures width of a single codepoint,
     >>> wcwidth.wcwidth('\u2640')
     1
 
-Use function ``wcwidth()`` to determine the length of a *single unicode character*.
-
-See `Specification <Specification_from_pypi_>`_ of character measurements. More
-briefly, return values of function ``wcwidth()`` are:
-
-``-1``
-  Indeterminate (not printable) control codes (C0 and C1).
-
-``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.
+Use function `wcwidth()`_ to determine the length of a *single unicode character*.
+See `Specification <Specification_from_pypi_>`_ of character measurements.
 
 wcswidth()
 ----------
@@ -107,11 +98,97 @@ Measures width of a string, returns -1 for control codes.
     >>> wcwidth.wcswidth('♀️')
     2
 
-Use function ``wcswidth()`` to determine the length of many, a *string of unicode characters*
+Use function `wcswidth()`_ to determine the length of many, a *string of unicode characters*
+
+See `Specification <Specification_from_pypi_>`_ of character measurements. Note that
+``-1`` is returned if control codes occurs anywhere in the string.
+
+width()
+-------
+
+Measures width of a string with improved handling of ``control_codes``
+
+.. code-block:: python
+
+    >>> # same support as wcswidth(), eg. regional indicator flag:
+    >>> wcwidth.width('\U0001F1FF\U0001F1FC')
+    2
+    >>> # SGR colored text, 'WARN', followed by SGR reset
+    >>> wcwidth.width('\x1b[38;2;255;150;100mWARN\x1b[0m')
+    4
+    >>> # customized tabsize and location
+    >>> wcwidth.width('\t', tabsize=4, column=1)
+    3
+    >>> # tab and all other control characters ignored
+    >>> wcwidth.width('\t', control_codes='ignore')
+    0
+    >>> # "vertical" movement and control characters are always ignored
+    >>> wcwidth.width('\n')
+    0
+    >>> # as well as sequences with "indeterminate" effects like Home + Clear
+    >>> wcwidth.width('\x1b[H\x1b[2J')
+    0
+    >>> # ValueError may raise when control_codes='strict'
+    >>> wcwidth.width('\n', control_codes='strict')
+    Traceback (most recent call last):
+    ...
+    ValueError: Vertical movement character 0xa at position 0
+    >>> wcwidth.width('\x1b[H\x1b[2J', control_codes='strict')
+    Traceback (most recent call last):
+    ...
+    ValueError: Indeterminate cursor sequence at position 0
+
+iter_sequences()
+----------------
+
+Iterates through text, yielding segments with escape sequence identification.
+
+.. code-block:: python
+
+    >>> list(wcwidth.iter_sequences('hello'))
+    [('hello', False)]
+    >>> list(wcwidth.iter_sequences('\x1b[31mred\x1b[0m'))
+    [('\x1b[31m', True), ('red', False), ('\x1b[0m', True)]
+
+Use `iter_sequences()`_ to split text into segments of plain text and escape sequences. Each tuple
+contains the segment string and a boolean indicating whether it is an escape sequence (``True``) or
+plain text (``False``).
+
+ljust()
+-------
+
+Use `ljust()`_ as replacement of `str.ljust()`_:
+
+.. code-block:: python
+
+    >>> 'コンニチハ'.ljust(11, '*')             # don't do this
+    'コンニチハ******'
+    >>> wcwidth.ljust('コンニチハ', 11, '*')    # do this!
+    'コンニチハ*'
+
+rjust()
+-------
+
+Use `rjust()`_ as replacement of `str.rjust()`_:
+
+.. code-block:: python
+
+    >>> 'コンニチハ'.rjust(11, '*')             # don't do this
+    '******コンニチハ'
+    >>> wcwidth.rjust('コンニチハ', 11, '*')    # do this!
+    '*コンニチハ'
+
+center()
+--------
+
+Use `center()`_ as replacement of `str.center()`_:
+
+.. code-block:: python
 
-See `Specification <Specification_from_pypi_>`_ of character measurements. More briefly, return
-values of function ``wcswidth()`` is the sum of ``wcwidth()`` with some additional account for some
-kinds of sequences.  Similarly, ``-1`` is returned if control codes occurs anywhere in the string.
+    >>> 'cafe\u0301'.center(6, '*')             # don't do this
+    'café*'
+    >>> wcwidth.center('cafe\u0301', 6, '*')
+    '*café*'                                    # do this!
 
 width()
 -------
@@ -293,6 +370,8 @@ History
 
 0.2.15 **next version**
   * **New** Function `iter_graphemes()`_. `PR #165`_.
+  * **New** Functions `width()`_ and `iter_sequences()`_. `PR #166`_.
+  * **New** Functions `ljust()`_, `rjust()`_, `center()`_. `PR #168`_.
 
 0.2.14 *2025-09-22*
   * **Drop Support** for Python 2.7 and 3.5. `PR #117`_.
@@ -425,6 +504,8 @@ https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c::
 .. _`PR #146`: https://github.com/jquast/wcwidth/pull/146
 .. _`PR #149`: https://github.com/jquast/wcwidth/pull/149
 .. _`PR #165`: https://github.com/jquast/wcwidth/pull/165
+.. _`PR #166`: https://github.com/jquast/wcwidth/pull/166
+.. _`PR #168`: https://github.com/jquast/wcwidth/pull/168
 .. _`Issue #101`: https://github.com/jquast/wcwidth/issues/101
 .. _`jquast/blessed`: https://github.com/jquast/blessed
 .. _`selectel/pyte`: https://github.com/selectel/pyte
@@ -461,7 +542,12 @@ https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c::
 .. _`str.ljust()`: https://docs.python.org/3/library/stdtypes.html#str.ljust
 .. _`str.rjust()`: https://docs.python.org/3/library/stdtypes.html#str.rjust
 .. _`str.center()`: https://docs.python.org/3/library/stdtypes.html#str.center
-.. _`Annex #29`: https://www.unicode.org/reports/tr29/
+.. _`wcwidth()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.wcwidth
+.. _`wcswidth()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.wcswidth
+.. _`iter_sequences()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.iter_sequences
+.. _`ljust()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.ljust
+.. _`rjust()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.rjust
+.. _`center()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.center
 .. _`General Tabulated Summary`: https://ucs-detect.readthedocs.io/results.html
 .. |pypi_downloads| image:: https://img.shields.io/pypi/dm/wcwidth.svg?logo=pypi
     :alt: Downloads

tests/test_justify.py

@@ -0,0 +1,55 @@
+"""Tests for text justification functions."""
+from wcwidth import ljust, rjust, center, width
+
+SGR_RED = '\x1b[31m'
+SGR_RESET = '\x1b[0m'
+CJK_WORD = '\u4e2d\u6587'
+CAFE_COMBINING = 'cafe\u0301'
+EMOJI_FAMILY = '\U0001F468\u200D\U0001F469\u200D\U0001F467'
+
+
+def test_ljust():
+    assert ljust('hi', 5) == 'hi   '
+    assert ljust('', 5) == '     '
+    assert ljust('hello', 3) == 'hello'
+    assert ljust('hello', 5) == 'hello'
+    assert ljust('\x1b[31mhi\x1b[0m', 5) == '\x1b[31mhi\x1b[0m   '
+    assert ljust('\u4e2d', 4) == '\u4e2d  '
+    assert ljust('hi', 5, fillchar='-') == 'hi---'
+    assert ljust('hi', 5, fillchar='\u00b7') == 'hi\u00b7\u00b7\u00b7'
+    assert ljust(CJK_WORD, 8) == CJK_WORD + '    '
+    assert width(ljust(CJK_WORD, 8)) == 8
+    assert width(ljust(CAFE_COMBINING, 8)) == 8
+    assert width(ljust(EMOJI_FAMILY, 6)) == 6
+    text = f'{SGR_RED}hi{SGR_RESET}'
+    assert len(ljust(text, 6, control_codes='ignore')) - len(SGR_RED) - len(SGR_RESET) == 6
+
+
+def test_rjust():
+    assert rjust('hi', 5) == '   hi'
+    assert rjust('', 5) == '     '
+    assert rjust('hello', 3) == 'hello'
+    assert rjust('hello', 5) == 'hello'
+    assert rjust('\x1b[31mhi\x1b[0m', 5) == '   \x1b[31mhi\x1b[0m'
+    assert rjust('\u4e2d', 4) == '  \u4e2d'
+    assert rjust('hi', 5, fillchar='-') == '---hi'
+    assert rjust('hi', 5, fillchar='\u00b7') == '\u00b7\u00b7\u00b7hi'
+    assert rjust(CJK_WORD, 8) == '    ' + CJK_WORD
+    assert width(rjust(CAFE_COMBINING, 8)) == 8
+    assert width(rjust(EMOJI_FAMILY, 6)) == 6
+
+
+def test_center():
+    assert center('hi', 6) == '  hi  '
+    assert center('hi', 5) == ' hi  '
+    assert center('', 4) == '    '
+    assert center('hello', 3) == 'hello'
+    assert center('hello', 5) == 'hello'
+    assert center('\x1b[31mhi\x1b[0m', 6) == '  \x1b[31mhi\x1b[0m  '
+    assert center('\u4e2d', 6) == '  \u4e2d  '
+    assert center('hi', 6, fillchar='-') == '--hi--'
+    assert center('hi', 6, fillchar='\u00b7') == '\u00b7\u00b7hi\u00b7\u00b7'
+    assert center('x', 4) == ' x  '
+    assert width(center(CJK_WORD, 8)) == 8
+    assert width(center(CAFE_COMBINING, 8)) == 8
+    assert width(center(EMOJI_FAMILY, 6)) == 6

wcwidth/__init__.py

@@ -10,22 +10,24 @@
 
 # local
 from .wcwidth import ZERO_WIDTH  # noqa
+from .grapheme import iter_graphemes  # noqa
 from .wcwidth import (WIDE_EASTASIAN,
                       VS16_NARROW_TO_WIDE,
                       width,
                       wcwidth,
                       wcswidth,
                       list_versions,
                       iter_sequences,
+                      ljust,
+                      rjust,
+                      center,
                       _wcmatch_version,
                       _wcversion_value)
-from .bisearch import bisearch as _bisearch
-
-from .grapheme import iter_graphemes
 
 # The __all__ attribute defines the items exported from statement,
 # 'from wcwidth import *', but also to say, "This is the public API".
-__all__ = ('wcwidth', 'wcswidth', 'width', 'iter_sequences',  'list_versions', 'iter_graphemes')
+__all__ = ('wcwidth', 'wcswidth', 'width', 'iter_sequences', 'iter_graphemes'
+           'ljust', 'rjust', 'center', 'list_versions')
 
 # We also used pkg_resources to load unicode version tables from version.json,
 # generated by bin/update-tables.py, but some environments are unable to

wcwidth/wcwidth.py

@@ -539,3 +539,107 @@ def width(text, control_codes='parse', tabsize=8):
         idx += 1
 
     return max_extent
+
+
+def ljust(text, dest_width, fillchar=' ', control_codes='parse'):
+    """
+    Return text left-justified in a string of given display width.
+
+    :param str text: String to justify, may contain terminal sequences.
+    :param int dest_width: Total display width of result in terminal cells.
+    :param str fillchar: Single character for padding (default space). Must have
+        display width of 1 (not wide, not zero-width, not combining). Unicode
+        characters like ``'·'`` are acceptable. The width is not validated.
+    :param str control_codes: How to handle control sequences when measuring.
+        Passed to :func:`width` for measurement.
+    :returns: Text padded on the right to reach ``dest_width``.
+    :rtype: str
+
+    .. versionadded:: 0.2.15
+
+    Example::
+
+        >>> wcwidth.ljust('hi', 5)
+        'hi   '
+        >>> wcwidth.ljust('\\x1b[31mhi\\x1b[0m', 5)
+        '\\x1b[31mhi\\x1b[0m   '
+        >>> wcwidth.ljust('\\U0001F468\\u200D\\U0001F469\\u200D\\U0001F467', 6)
+        '👨‍👩‍👧    '
+    """
+    if text.isascii() and text.isprintable():
+        text_width = len(text)
+    else:
+        text_width = width(text, control_codes=control_codes)
+    padding_cells = max(0, dest_width - text_width)
+    return text + fillchar * padding_cells
+
+
+def rjust(text, dest_width, fillchar=' ', control_codes='parse'):
+    """
+    Return text right-justified in a string of given display width.
+
+    :param str text: String to justify, may contain terminal sequences.
+    :param int dest_width: Total display width of result in terminal cells.
+    :param str fillchar: Single character for padding (default space). Must have
+        display width of 1 (not wide, not zero-width, not combining). Unicode
+        characters like ``'·'`` are acceptable. The width is not validated.
+    :param str control_codes: How to handle control sequences when measuring.
+        Passed to :func:`width` for measurement.
+    :returns: Text padded on the left to reach ``dest_width``.
+    :rtype: str
+
+    .. versionadded:: 0.2.15
+
+    Example::
+
+        >>> wcwidth.rjust('hi', 5)
+        '   hi'
+        >>> wcwidth.rjust('\\x1b[31mhi\\x1b[0m', 5)
+        '   \\x1b[31mhi\\x1b[0m'
+        >>> wcwidth.rjust('\\U0001F468\\u200D\\U0001F469\\u200D\\U0001F467', 6)
+        '    👨‍👩‍👧'
+    """
+    if text.isascii() and text.isprintable():
+        text_width = len(text)
+    else:
+        text_width = width(text, control_codes=control_codes)
+    padding_cells = max(0, dest_width - text_width)
+    return fillchar * padding_cells + text
+
+
+def center(text, dest_width, fillchar=' ', control_codes='parse'):
+    """
+    Return text centered in a string of given display width.
+
+    :param str text: String to center, may contain terminal sequences.
+    :param int dest_width: Total display width of result in terminal cells.
+    :param str fillchar: Single character for padding (default space). Must have
+        display width of 1 (not wide, not zero-width, not combining). Unicode
+        characters like ``'·'`` are acceptable. The width is not validated.
+    :param str control_codes: How to handle control sequences when measuring.
+        Passed to :func:`width` for measurement.
+    :returns: Text padded on both sides to reach ``dest_width``.
+    :rtype: str
+
+    For odd-width padding, the extra cell goes on the right (matching
+    Python's :meth:`str.center` behavior).
+
+    .. versionadded:: 0.2.15
+
+    Example::
+
+        >>> wcwidth.center('hi', 6)
+        '  hi  '
+        >>> wcwidth.center('\\x1b[31mhi\\x1b[0m', 6)
+        '  \\x1b[31mhi\\x1b[0m  '
+        >>> wcwidth.center('\\U0001F468\\u200D\\U0001F469\\u200D\\U0001F467', 6)
+        '  👨‍👩‍👧  '
+    """
+    if text.isascii() and text.isprintable():
+        text_width = len(text)
+    else:
+        text_width = width(text, control_codes=control_codes)
+    total_padding = max(0, dest_width - text_width)
+    left_pad = total_padding // 2
+    right_pad = total_padding - left_pad
+    return fillchar * left_pad + text + fillchar * right_pad