test_wcwidth.py

Overview

The [test_wcwidth.py](/projects/286/67408) file contains automated tests for verifying the correctness of two functions, `wcwidth` and `wcswidth`, imported from the `_pytest._io.wcwidth` module. These functions are used to measure the display width of Unicode characters and strings, respectively. The file ensures that these functions correctly compute the terminal column width of individual characters and entire strings, including handling special cases like control characters, zero-width characters, and wide characters (e.g., East Asian full-width characters and emojis).

This test file leverages the `pytest` framework for parametrized testing, providing multiple input cases and their expected output widths to validate the behavior of the width calculation functions.

Detailed Explanation

Imports

• wcswidth and wcwidth: Functions under test, which compute the visual width of strings and characters.

• pytest: Testing framework used to define and run test cases.

Function: test_wcwidth

@pytest.mark.parametrize(
    ("c", "expected"),
    [
        ("\0", 0),
        ("\n", -1),
        ("a", 1),
        ("1", 1),
        ("א", 1),
        ("\u200b", 0),
        ("\u1abe", 0),
        ("\u0591", 0),
        ("🉐", 2),
        ("＄", 2),  # noqa: RUF001
    ],
)
def test_wcwidth(c: str, expected: int) -> None:
    assert wcwidth(c) == expected

• Purpose: Tests the wcwidth function on individual Unicode characters.

• Parameters:

  • c (str): A single Unicode character to test.

  • expected (int): The expected terminal column width of the character.

• Return: None (raises assertion error if the test fails).

• Behavior: Calls wcwidth(c) and asserts the result matches the expected width.

• Usage Example:

  test_wcwidth("a", 1)  # Passes if wcwidth("a") == 1
  test_wcwidth("\n", -1)  # Passes if wcwidth("\n") == -1 (non-printable)
  

• Test Cases Include:

  • Null character \0 with width 0.

  • Newline \n with width -1 (non-printable).

  • Latin letters and digits with width 1.

  • Hebrew letter א with width 1.

  • Zero-width characters (e.g., zero-width space \u200b) with width 0.

  • Combining characters with width 0.

  • Emoji and full-width characters (e.g., 🉐, ＄) with width 2.

Function: test_wcswidth

@pytest.mark.parametrize(
    ("s", "expected"),
    [
        ("", 0),
        ("hello, world!", 13),
        ("hello, world!\n", -1),
        ("0123456789", 10),
        ("שלום, עולם!", 11),
        ("שְבֻעָיים", 6),
        ("🉐🉐🉐", 6),
    ],
)
def test_wcswidth(s: str, expected: int) -> None:
    assert wcswidth(s) == expected

• Purpose: Tests the wcswidth function on entire Unicode strings.

• Parameters:

  • s (str): A Unicode string to test.

  • expected (int): The expected total terminal column width of the string.

• Return: None (raises assertion error if the test fails).

• Behavior: Calls wcswidth(s) and checks if the result matches the expected width.

• Usage Example:

  test_wcswidth("hello", 5)  # Passes if wcswidth("hello") == 5
  test_wcswidth("hello\n", -1)  # Passes if wcswidth("hello\n") == -1 (invalid string)
  

• Test Cases Include:

  • Empty string with width 0.

  • ASCII strings with known length.

  • String containing newline character returns -1.

  • Hebrew strings with combined characters.

  • Strings of repeated emoji characters with double width.

Implementation Details

• Both wcwidth and wcswidth are functions typically implemented to comply with the Unicode Standard Annex #11, which defines the East Asian Width property.

• wcwidth computes the width of a single character:

  • Returns 0 for non-spacing, zero-width characters.

  • Returns 1 for regular-width characters.

  • Returns 2 for wide characters (e.g., CJK ideographs, emojis).

  • Returns -1 for control characters or non-printable characters.

• wcswidth computes the sum of wcwidth for all characters in a string:

  • Returns the sum if all characters are printable.

  • Returns -1 if any character is non-printable.

This file does not implement these functions but tests their correctness using representative samples.

Interaction with Other Parts of the System

• This file is part of the test suite for the _pytest package, particularly testing internal utilities related to terminal output formatting.

• The _pytest._io.wcwidth module provides the wcwidth and wcswidth functions, which are used by pytest's output formatting to correctly align and display Unicode characters in test output.

• The tests help ensure that the terminal width calculations remain accurate across multiple platforms and Python versions, preventing misaligned or broken output in the pytest console interface.

Visual Diagram

flowchart TD
    A[Test_wcwidth.py]
    A --> B[wcwidth function]
    A --> C[wcswidth function]

    B --> D[Input: single character (str)]
    B --> E[Output: int (width or -1)]
    C --> F[Input: string (str)]
    C --> G[Output: int (total width or -1)]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333
    style C fill:#bbf,stroke:#333

Summary

[test_wcwidth.py](/projects/286/67408) is a utility test module that validates the behavior of Unicode character width calculation functions crucial for proper terminal display in pytest. By covering a wide range of character types, including control, combining, and wide characters, it ensures reliable width computations that help maintain a consistent and readable test output interface.

If you need further details or examples, feel free to ask!