{"id":5893,"library":"cwcwidth","title":"cwcwidth","description":"cwcwidth provides efficient Python bindings for the POSIX wcwidth and wcswidth functions, which calculate the printable length of Unicode characters and strings on a terminal. It is actively maintained with version 0.1.12 being the latest, featuring regular updates that often include support for new Python versions, dropping support for older ones, and updating to the latest Unicode definitions.","status":"active","version":"0.1.12","language":"en","source_language":"en","source_url":"https://github.com/sebastinas/cwcwidth","tags":["string-width","unicode","terminal","c-bindings","character-width","posix"],"install":[{"cmd":"pip install cwcwidth","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Imports the function to calculate the width of a single Unicode character.","symbol":"wcwidth","correct":"from cwcwidth import wcwidth"},{"note":"Imports the function to calculate the width of a Unicode string.","symbol":"wcswidth","correct":"from cwcwidth import wcswidth"}],"quickstart":{"code":"from cwcwidth import wcwidth, wcswidth\n\n# Calculate width of a single character\nchar_width_a = wcwidth('a')\nchar_width_kanji = wcwidth('語')\n\n# Calculate width of a string\nstring_width_hello = wcswidth('Hello')\nstring_width_japanese = wcswidth('コンニチハ, セカイ!')\n\n# Calculate width of a substring (first 5 characters)\nstring_width_partial = wcswidth('コンニチハ, セカイ!', 5)\n\nprint(f\"Width of 'a': {char_width_a}\")\nprint(f\"Width of '語': {char_width_kanji}\")\nprint(f\"Width of 'Hello': {string_width_hello}\")\nprint(f\"Width of 'コンニチハ, セカイ!': {string_width_japanese}\")\nprint(f\"Width of first 5 chars of 'コンニチハ, セカイ!': {string_width_partial}\")\n\n# Example with a non-printable character (returns -1)\nnon_printable_width = wcwidth('\\x01') # Start of Heading control character\nprint(f\"Width of non-printable char '\\x01': {non_printable_width}\")","lang":"python","description":"This quickstart demonstrates how to use `wcwidth` for single Unicode characters and `wcswidth` for entire strings or substrings, calculating their display width on a terminal. It also shows the behavior with non-printable control characters."},"warnings":[{"fix":"Always check the `requires_python` metadata for the specific cwcwidth version you intend to use and upgrade your Python environment if necessary. Consider using a virtual environment to manage dependencies.","message":"cwcwidth frequently drops support for older Python versions with new releases. For example, version 0.1.12 dropped Python 3.10 support, 0.1.11 dropped 3.9, and 0.1.10 dropped 3.8. Ensure your Python environment meets the `requires_python` specification for the installed library version.","severity":"breaking","affected_versions":"0.1.6 and later"},{"fix":"Implement checks for -1 return values, especially when processing user-generated or external string inputs, to correctly handle or filter out non-printable characters.","message":"The `wcwidth` and `wcswidth` functions return -1 if they encounter non-printable C0 or C1 control characters within the input string. This behavior is consistent with the underlying POSIX C functions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If precise, consistent width calculation across different environments or library versions is critical, consider pinning the `cwcwidth` version. Be aware that upgrading may alter width calculations for recently added or reclassified Unicode characters.","message":"The library updates its internal Unicode definition periodically (e.g., version 0.1.10 updated to Unicode 15.1). This might lead to subtle changes in width calculations for certain characters if your application relies on a specific Unicode version or if the terminal's Unicode interpretation differs.","severity":"gotcha","affected_versions":"All versions (behavior can change across updates)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}