add typing and py.typed

.github/workflows/ci.yml

@@ -167,3 +167,16 @@ jobs:
           name: html-report
           path: htmlcov
         if: ${{ failure() }}
+
+  typing:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+      - run: pip install mypy
+      - run: pip install -e .
+      - name: Run tests
+        run: stubtest wcwidth

docs/requirements.txt

@@ -6,11 +6,11 @@
 #
 alabaster==0.7.13
     # via sphinx
-babel==2.12.1
+babel==2.13.1
     # via sphinx
 certifi==2023.7.22
     # via requests
-charset-normalizer==3.3.0
+charset-normalizer==3.3.2
     # via requests
 docutils==0.17.1
     # via

requirements-tests37.in

@@ -4,3 +4,5 @@ pytest-cov
 coverage[toml]<6
 importlib_metadata; python_version < '3.8'
 pytest-benchmark
+mypy
+typing; python_version < '3.5'

requirements-tests37.txt

@@ -18,6 +18,10 @@ importlib-metadata==6.7.0 ; python_version < "3.8"
     #   pytest
 iniconfig==2.0.0
     # via pytest
+mypy==1.4.1
+    # via -r requirements-tests37.in
+mypy-extensions==1.0.0
+    # via mypy
 packaging==23.2
     # via pytest
 pluggy==1.2.0
@@ -39,7 +43,13 @@ toml==0.10.2
     # via
     #   coverage
     #   pytest
+tomli==2.0.1
+    # via mypy
+typed-ast==1.5.5
+    # via mypy
 typing-extensions==4.7.1
-    # via importlib-metadata
+    # via
+    #   importlib-metadata
+    #   mypy
 zipp==3.15.0
     # via importlib-metadata

requirements-tests39.in

@@ -13,3 +13,4 @@ pylint>=2.15
 astroid>=2.11
 wrapt>=1.14
 pytest-benchmark
+mypy

requirements-tests39.txt

@@ -10,7 +10,7 @@ astroid==3.0.1
     #   pylint
 autopep8==2.0.4
     # via -r requirements-tests39.in
-charset-normalizer==3.3.0
+charset-normalizer==3.3.2
     # via docformatter
 coverage==7.3.2
     # via pytest-cov
@@ -38,6 +38,10 @@ mccabe==0.7.0
     # via
     #   flake8
     #   pylint
+mypy==1.6.1
+    # via -r requirements-tests39.in
+mypy-extensions==1.0.0
+    # via mypy
 packaging==23.2
     # via pytest
 pbr==5.11.1
@@ -60,9 +64,9 @@ pygments==2.16.1
     # via
     #   -r requirements-tests39.in
     #   doc8
-pylint==3.0.1
+pylint==3.0.2
     # via -r requirements-tests39.in
-pytest==7.4.2
+pytest==7.4.3
     # via
     #   -r requirements-tests39.in
     #   pytest-benchmark
@@ -84,13 +88,15 @@ tomli==2.0.1
     #   autopep8
     #   coverage
     #   doc8
+    #   mypy
     #   pylint
     #   pytest
-tomlkit==0.12.1
+tomlkit==0.12.2
     # via pylint
 typing-extensions==4.8.0
     # via
     #   astroid
+    #   mypy
     #   pylint
 untokenize==0.1.1
     # via docformatter

requirements-update.txt

@@ -6,7 +6,7 @@
 #
 certifi==2023.7.22
     # via requests
-charset-normalizer==3.3.0
+charset-normalizer==3.3.2
     # via requests
 idna==3.4
     # via requests

setup.py

@@ -58,6 +58,7 @@ def main():
         url='https://github.com/jquast/wcwidth',
         package_data={
             '': ['LICENSE', '*.rst'],
+            'wcwidth': ['py.typed', '*.pyi'],
         },
         zip_safe=True,
         classifiers=[

tests/typing/test_success.py

@@ -0,0 +1,63 @@
+import sys
+import wcwidth
+from typing import Tuple
+
+
+if sys.version_info >= (3,):
+    unicode = str
+
+
+def test_list_versions():  # type: () -> None
+    versions = wcwidth.list_versions()  # type: Tuple[str, ...]
+    assert isinstance(versions, tuple)
+    for version in versions:
+        assert isinstance(version, str)
+
+
+def test_wcwidth():  # type: () -> None
+    width = wcwidth.wcwidth("a")  # type: int
+    assert isinstance(width, int)
+    width = wcwidth.wcwidth(u"啊")
+    assert isinstance(width, int)
+
+    width = wcwidth.wcwidth("b", "9.0")
+    assert isinstance(width, int)
+    width = wcwidth.wcwidth("b", u"9.0")
+    assert isinstance(width, int)
+
+
+def test_wcswidth():  # type: () -> None
+    width = wcwidth.wcswidth("hello, world")  # type: int
+    assert isinstance(width, int)
+    width = wcwidth.wcswidth(u"你好，世界")
+    assert isinstance(width, int)
+
+    width = wcwidth.wcswidth(u"你好，世界", 5)
+    assert isinstance(width, int)
+
+    width = wcwidth.wcswidth("hello, world", unicode_version="9.0")
+    assert isinstance(width, int)
+    width = wcwidth.wcswidth("hello, world", unicode_version=u"9.0")
+    assert isinstance(width, int)
+
+    width = wcwidth.wcswidth(u"你好，世界", 5, "9.0")
+    assert isinstance(width, int)
+
+
+def test__bisearch():  # type: () -> None
+    found = wcwidth._bisearch(6, [(1, 2), (4, 7)])  # type: int
+    assert isinstance(found, int)
+
+
+def test__wcversion_value():  # type: () -> None
+    version = wcwidth._wcversion_value("12.1.0")  # type: Tuple[int, ...]
+    assert isinstance(version, tuple)
+    for number in version:
+        assert isinstance(number, int)
+
+
+def test__wcmatch_version():  # type: () -> None
+    version_str = wcwidth._wcmatch_version("auto")  # type: str
+    assert isinstance(version_str, str)
+    version_unicode = wcwidth._wcmatch_version(u"auto")  # type: unicode
+    assert isinstance(version_unicode, unicode)

tox.ini

@@ -16,6 +16,7 @@ commands = {envpython} -m pytest --cov-config={toxinidir}/tox.ini {posargs:\
              } \
           --log-format='%(levelname)s %(relativeCreated)2.2f %(filename)s:%(lineno)d %(message)s' \
           tests
+          {envpython} -m mypy tests/typing
 passenv = TEST_QUICK,TEST_KEYBOARD,TEST_RAW
 
 
@@ -193,3 +194,8 @@ basepython = python{env:TOXPYTHON:{env:TRAVIS_PYTHON_VERSION:3.10}}
 passenv = TOXENV,CI,TRAVIS,TRAVIS_*,CODECOV_*
 deps = codecov
 commands = codecov -e TOXENV
+
+[testenv:typing]
+basepython = python3.12
+deps = mypy
+commands = stubtest wcwidth

wcwidth/__init__.py

@@ -9,15 +9,11 @@
 # any future version.
 
 # local
-from .wcwidth import ZERO_WIDTH  # noqa
-from .wcwidth import (WIDE_EASTASIAN,
-                      VS16_NARROW_TO_WIDE,
-                      wcwidth,
-                      wcswidth,
-                      _bisearch,
-                      list_versions,
-                      _wcmatch_version,
-                      _wcversion_value)
+from .unicode_versions import list_versions
+from .table_zero import ZERO_WIDTH  # noqa
+from .table_wide import WIDE_EASTASIAN  # noqa
+from .table_vs16 import VS16_NARROW_TO_WIDE  # noqa
+from .wcwidth import wcwidth, wcswidth, _bisearch, _wcmatch_version, _wcversion_value
 
 # The __all__ attribute defines the items exported from statement,
 # 'from wcwidth import *', but also to say, "This is the public API".

wcwidth/unicode_versions.py

@@ -13,7 +13,7 @@ def list_versions():
     ``unicode_version`` to the ``wcwidth()`` family of functions.
 
     :returns: Supported Unicode version numbers in ascending sorted order.
-    :rtype: list[str]
+    :rtype: tuple[str, ...]
     """
     return (
         "4.1.0",

wcwidth/unicode_versions.pyi

@@ -0,0 +1,2 @@
+def list_versions() -> tuple[str, ...]:
+    ...

wcwidth/wcwidth.pyi

@@ -0,0 +1,21 @@
+from typing import Optional
+
+
+def wcwidth(wc: str, unicode_version: str = ...) -> int:
+    ...
+
+
+def wcswidth(pwcs: str, n: Optional[int] = None, unicode_version: str = ...):
+    ...
+
+
+def _bisearch(ucs: int, table: list[tuple[int, int]]) -> int:
+    ...
+
+
+def _wcversion_value(ver_string: str) -> tuple[int, ...]:
+    ...
+
+
+def _wcmatch_version(given_version: str) -> str:
+    ...