Add type hints

Closes #467
Closes #433

Author: Daverball

.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

docs/index.rst

@@ -9,7 +9,7 @@ Common Interface
 
 Most of the number format modules implement the following functions:
 
-.. function:: module.validate(number)
+.. function:: module.validate(number: str) -> str
 
    Validate the number and return a compact, consistent representation of
    the number or code. If the validation fails,
@@ -19,23 +19,23 @@ Most of the number format modules implement the following functions:
    :raises ValidationError: When the specified number is invalid
    :returns:  str -- A compact (canonical) representation of the number
 
-.. function:: module.is_valid(number)
+.. function:: module.is_valid(number: str) -> bool
 
    Return either ``True`` or ``False`` depending on whether the passed number
    is in any supported and valid form and passes all embedded checks of the
    number. This function should never raise an exception.
 
    :returns: bool -- ``True`` if validated, ``False`` otherwise
 
-.. function:: module.compact(number)
+.. function:: module.compact(number: str) -> str
 
    Return a compact representation of the number or code. This function
    generally does not do validation but may raise exceptions for wildly
    invalid numbers.
 
    :returns: str -- The compacted number
 
-.. function:: module.format(number)
+.. function:: module.format(number: str) -> str
 
    Return a formatted version of the number in the preferred format.
    This function generally expects to be passed a valid number or code and
@@ -45,15 +45,15 @@ Most of the number format modules implement the following functions:
 
 The check digit modules generally also provide the following functions:
 
-.. function:: module.checksum(number)
+.. function:: module.checksum(number: str) -> int
 
    Calculate the checksum over the provided number. This is generally a
    number that can be used to determine whether the provided number is
    valid. It depends on the algorithm which checksum is considered valid.
 
    :returns: int -- A numeric checksum over the number
 
-.. function:: module.calc_check_digit(number)
+.. function:: module.calc_check_digit(number: str) -> str
 
    Calculate the check digit that should be added to the number to make it
    valid.

setup.cfg

@@ -36,7 +36,10 @@ max-complexity = 15
 max-line-length = 120
 extend-exclude =
   .github
+  .mypy_cache
   .pytest_cache
+  .ruff_cache
+  .venv
   build
 
 [isort]
@@ -47,3 +50,8 @@ known_third_party =
   openpyxl
   requests
   xlrd
+
+[mypy]
+python_version = 3.9
+strict = True
+warn_unreachable = True

setup.py

@@ -76,7 +76,7 @@
     ],
     packages=find_packages(),
     install_requires=[],
-    package_data={'': ['*.dat', '*.crt']},
+    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

@@ -37,6 +37,8 @@
 parsing, validation, formatting or conversion functions.
 """
 
+from __future__ import annotations
+
 from stdnum.util import get_cc_module
 
 

stdnum/ad/__init__.py

@@ -20,5 +20,7 @@
 
 """Collection of Andorran numbers."""
 
+from __future__ import annotations
+
 # Provide aliases.
 from stdnum.ad import nrt as vat  # noqa: F401

stdnum/ad/nrt.py

@@ -44,11 +44,13 @@
 '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 +59,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 +81,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

@@ -20,5 +20,7 @@
 
 """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

@@ -50,6 +50,8 @@
 InvalidFormat: ...
 """
 
+from __future__ import annotations
+
 import re
 
 from stdnum.exceptions import *
@@ -60,7 +62,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 +73,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 +84,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))