Add type hints

.github/workflows/test.yml

@@ -30,7 +30,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        tox_job: [docs, flake8, headers]
+        tox_job: [docs, flake8, mypy, headers]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python

.gitignore

@@ -6,7 +6,10 @@ __pycache__
 
 # /
 /.coverage
+/.mypy_cache
+/.ruff_cache
 /.tox
+/.venv
 /build
 /coverage
 /dist

mypy.ini

@@ -0,0 +1,4 @@
+[mypy]
+python_version = 3.9
+strict = True
+warn_unreachable = True

setup.cfg

@@ -6,11 +6,14 @@ owner=root
 group=root
 
 [tool:pytest]
-addopts = --doctest-modules --doctest-glob="*.doctest" stdnum tests --ignore=stdnum/iso9362.py --cov=stdnum --cov-report=term-missing:skip-covered --cov-report=html
+addopts = --doctest-modules --doctest-glob="*.doctest" stdnum tests --ignore=stdnum/iso9362.py --ignore=stdnum/_types.py --cov=stdnum --cov-report=term-missing:skip-covered --cov-report=html
 doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL
 
 [coverage:run]
 branch = true
+omit =
+  _types.py
+  _typing.py
 
 [coverage:report]
 fail_under=100
@@ -32,16 +35,26 @@ ignore =
   Q003  # don't force "" strings to avoid escaping quotes
   T001,T201  # we use print statements in the update scripts
   W504  # we put the binary operator on the preceding line
+per-file-ignores =
+  # typing re-exports
+  stdnum/_typing.py: F401,I250
 max-complexity = 15
 max-line-length = 120
 extend-exclude =
   .github
+  .mypy_cache
   .pytest_cache
+  .ruff_cache
+  .venv
   build
 
 [isort]
 lines_after_imports = 2
 multi_line_output = 4
+extra_standard_library =
+  typing_extensions
+classes =
+  IO
 known_third_party =
   lxml
   openpyxl

setup.py

@@ -75,8 +75,11 @@
         'Topic :: Text Processing :: General',
     ],
     packages=find_packages(),
-    install_requires=[],
-    package_data={'': ['*.dat', '*.crt']},
+    python_requires='>=3.7',
+    install_requires=[
+        'importlib_resources >= 1.3  ; python_version < "3.9"',
+    ],
+    package_data={'': ['*.dat', '*.crt', 'py.typed']},
     extras_require={
         # The SOAP feature is only required for a number of online tests
         # of numbers such as the EU VAT VIES lookup, the Dominican Republic

stdnum/__init__.py

@@ -36,6 +36,7 @@
 Apart from the validate() function, many modules provide extra
 parsing, validation, formatting or conversion functions.
 """
+from __future__ import annotations
 
 from stdnum.util import get_cc_module
 

stdnum/_types.py

@@ -0,0 +1,77 @@
+# _types.py - module for defining custom types
+#
+# Copyright (C) 2025 David Salvisberg
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 USA
+
+"""Module containing custom types.
+
+This module is designed to be accessed through `stdnum._typing` so
+you only have the overhead and runtime requirement of Python 3.9
+and `typing_extensions`, when that type is introspected at runtime.
+
+As such this module should never be accessed directly.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+from typing_extensions import Required, TypedDict
+
+
+class NumberValidationModule(Protocol):
+    """Minimal interface for a number validation module."""
+
+    def compact(self, number: str) -> str:
+        """Convert the number to the minimal representation."""
+
+    def validate(self, number: str) -> str:
+        """Check if the number provided is a valid number of its type."""
+
+    def is_valid(self, number: str) -> bool:
+        """Check if the number provided is a valid number of its type."""
+
+
+class IMSIInfo(TypedDict, total=False):
+    """Info `dict` returned by `stdnum.imsi.info`."""
+
+    number: Required[str]
+    mcc: Required[str]
+    mnc: Required[str]
+    msin: Required[str]
+    country: str
+    cc: str
+    brand: str
+    operator: str
+    status: str
+    bands: str
+
+
+class GSTINInfo(TypedDict):
+    """Info `dict` returned by `stdnum.in_.gstin.info`."""
+
+    state: str | None
+    pan: str
+    holder_type: str
+    initial: str
+    registration_count: int
+
+
+class PANInfo(TypedDict):
+    """Info `dict` returned by `stdnum.in_.pan.info`."""
+
+    holder_type: str
+    initial: str

stdnum/_typing.py

@@ -0,0 +1,119 @@
+# _typing.py - module for typing shims with reduced runtime overhead
+#
+# Copyright (C) 2025 David Salvisberg
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 USA
+
+"""Compatibility shims for the Python typing module.
+
+This module is designed in a way, such, that runtime use of
+annotations is possible starting with Python 3.9, but it still
+supports Python 3.6 - 3.8 if the package is used normally without
+introspecting the annotations of the API.
+
+You should never import *from* this module, you should always import
+the entire module and then access the members via attribute access.
+
+I.e. use the module like this:
+```python
+from stdnum import _typing as t
+
+foo: t.Any = ...
+```
+
+Instead of like this:
+```python
+from stdnum._typing import Any
+
+foo: Any = ...
+```
+
+The exception to that rule are `TYPE_CHECKING` `cast` and `deprecated`
+which can be used at runtime.
+"""
+
+from __future__ import annotations
+
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Generator as Generator
+    from collections.abc import Iterable as Iterable
+    from collections.abc import Mapping as Mapping
+    from collections.abc import Sequence as Sequence
+    from typing import Any as Any
+    from typing import IO as IO
+    from typing import Literal as Literal
+    from typing import cast as cast
+    from typing_extensions import TypeAlias as TypeAlias
+    from typing_extensions import deprecated as deprecated
+
+    from stdnum._types import GSTINInfo as GSTINInfo
+    from stdnum._types import IMSIInfo as IMSIInfo
+    from stdnum._types import NumberValidationModule as NumberValidationModule
+    from stdnum._types import PANInfo as PANInfo
+else:
+    def cast(typ, val):
+        """Cast a value to a type."""
+        return val
+
+    class deprecated:  # noqa: N801
+        """Simplified backport of `warnings.deprecated`.
+
+        This backport doesn't handle classes or async functions.
+        """
+
+        def __init__(self, message, category=DeprecationWarning, stacklevel=1):  # noqa: D107
+            self.message = message
+            self.category = category
+            self.stacklevel = stacklevel
+
+        def __call__(self, func):  # noqa: D102
+            func.__deprecated__ = self.message
+
+            if self.category is None:
+                return func
+
+            import functools
+            import warnings
+
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                warnings.warn(self.message, category=self.category, stacklevel=self.stacklevel + 1)
+                return func(*args, **kwargs)
+
+            wrapper.__deprecated__ = self.message
+            return wrapper
+
+    def __getattr__(name):
+        if name in {'Generator', 'Iterable', 'Mapping', 'Sequence'}:
+            import collections.abc
+            return getattr(collections.abc, name)
+        elif name in {'Any', 'IO', 'Literal'}:
+            import typing
+            return getattr(typing, name)
+        elif name == 'TypeAlias':
+            import sys
+            if sys.version_info >= (3, 10):
+                import typing
+            else:
+                import typing_extensions as typing
+            return getattr(typing, name)
+        elif name in {'GSTINInfo', 'IMSIInfo', 'NumberValidationModule', 'PANInfo'}:
+            import stdnum._types
+            return getattr(stdnum._types, name)
+        else:
+            raise AttributeError(name)

stdnum/ad/__init__.py

@@ -19,6 +19,7 @@
 # 02110-1301 USA
 
 """Collection of Andorran numbers."""
+from __future__ import annotations
 
 # Provide aliases.
 from stdnum.ad import nrt as vat  # noqa: F401

stdnum/ad/nrt.py

@@ -43,12 +43,13 @@
 >>> format('D059888N')
 'D-059888-N'
 """  # noqa: E501
+from __future__ import annotations
 
 from stdnum.exceptions import *
 from stdnum.util import clean, isdigits
 
 
-def compact(number):
+def compact(number: str) -> str:
     """Convert the number to the minimal representation.
 
     This strips the number of any valid separators and removes surrounding
@@ -57,7 +58,7 @@ def compact(number):
     return clean(number, ' -.').upper().strip()
 
 
-def validate(number):
+def validate(number: str) -> str:
     """Check if the number is a valid Andorra NRT number.
 
     This checks the length, formatting and other constraints. It does not check
@@ -79,15 +80,15 @@ def validate(number):
     return number
 
 
-def is_valid(number):
+def is_valid(number: str) -> bool:
     """Check if the number is a valid Andorra NRT number."""
     try:
         return bool(validate(number))
     except ValidationError:
         return False
 
 
-def format(number):
+def format(number: str) -> str:
     """Reformat the number to the standard presentation format."""
     number = compact(number)
     return '-'.join([number[0], number[1:-1], number[-1]])

stdnum/al/__init__.py

@@ -19,6 +19,7 @@
 # 02110-1301 USA
 
 """Collection of Albanian numbers."""
+from __future__ import annotations
 
 # provide vat as an alias
 from stdnum.al import nipt as vat  # noqa: F401

stdnum/al/nipt.py

@@ -49,6 +49,7 @@
     ...
 InvalidFormat: ...
 """
+from __future__ import annotations
 
 import re
 
@@ -60,7 +61,7 @@
 _nipt_re = re.compile(r'^[A-M][0-9]{8}[A-Z]$')
 
 
-def compact(number):
+def compact(number: str) -> str:
     """Convert the number to the minimal representation. This strips the
     number of any valid separators and removes surrounding whitespace."""
     number = clean(number, ' ').upper().strip()
@@ -71,7 +72,7 @@ def compact(number):
     return number
 
 
-def validate(number):
+def validate(number: str) -> str:
     """Check if the number is a valid VAT number. This checks the length and
     formatting."""
     number = compact(number)
@@ -82,7 +83,7 @@ def validate(number):
     return number
 
 
-def is_valid(number):
+def is_valid(number: str) -> bool:
     """Check if the number is a valid VAT number."""
     try:
         return bool(validate(number))

stdnum/ar/__init__.py

@@ -19,6 +19,7 @@
 # 02110-1301 USA
 
 """Collection of Argentinian numbers."""
+from __future__ import annotations
 
 # provide aliases
 from stdnum.ar import cuit as vat  # noqa: F401