Add type hints

.pre-commit-config.yaml

@@ -56,6 +56,13 @@ repos:
         args: ["--convention", "google"]
         files: "src/"
 
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v0.942
+    hooks:
+      - id: mypy
+        additional_dependencies: [pytest, types-freezegun, types-setuptools]
+        args: [--strict]
+
   - repo: https://github.com/asottile/setup-cfg-fmt
     rev: v1.20.1
     hooks:

src/humanize/__init__.py

@@ -24,7 +24,7 @@
     import importlib.metadata as importlib_metadata
 except ImportError:
     # <Python 3.7 and lower
-    import importlib_metadata
+    import importlib_metadata  # type: ignore
 
 __version__ = importlib_metadata.version(__name__)
 

src/humanize/filesize.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 
 """Bits and bytes related humanization."""
+from __future__ import annotations
 
 suffixes = {
     "decimal": ("kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"),
@@ -9,7 +10,12 @@
 }
 
 
-def naturalsize(value, binary=False, gnu=False, format="%.1f"):
+def naturalsize(
+    value: int | float | str,
+    binary: bool = False,
+    gnu: bool = False,
+    format: str = "%.1f",
+) -> str:
     """Format a number of bytes like a human readable filesize (e.g. 10 kB).
 
     By default, decimal suffixes (kB, MB) are used.

src/humanize/i18n.py

@@ -1,11 +1,15 @@
 """Activate, get and deactivate translations."""
+from __future__ import annotations
+
 import gettext as gettext_module
 import os.path
 from threading import local
 
 __all__ = ["activate", "deactivate", "thousands_separator"]
 
-_TRANSLATIONS = {None: gettext_module.NullTranslations()}
+_TRANSLATIONS: dict[str | None, gettext_module.NullTranslations] = {
+    None: gettext_module.NullTranslations()
+}
 _CURRENT = local()
 
 
@@ -15,7 +19,7 @@
 }
 
 
-def _get_default_locale_path():
+def _get_default_locale_path() -> str | None:
     try:
         if __file__ is None:
             return None
@@ -24,14 +28,14 @@ def _get_default_locale_path():
         return None
 
 
-def get_translation():
+def get_translation() -> gettext_module.NullTranslations:
     try:
         return _TRANSLATIONS[_CURRENT.locale]
     except (AttributeError, KeyError):
         return _TRANSLATIONS[None]
 
 
-def activate(locale, path=None):
+def activate(locale: str, path: str | None = None) -> gettext_module.NullTranslations:
     """Activate internationalisation.
 
     Set `locale` as current locale. Search for locale in directory `path`.
@@ -61,12 +65,12 @@ def activate(locale, path=None):
     return _TRANSLATIONS[locale]
 
 
-def deactivate():
+def deactivate() -> None:
     """Deactivate internationalisation."""
     _CURRENT.locale = None
 
 
-def _gettext(message):
+def _gettext(message: str) -> str:
     """Get translation.
 
     Args:
@@ -78,7 +82,7 @@ def _gettext(message):
     return get_translation().gettext(message)
 
 
-def _pgettext(msgctxt, message):
+def _pgettext(msgctxt: str, message: str) -> str:
     """Fetches a particular translation.
 
     It works with `msgctxt` .po modifiers and allows duplicate keys with different
@@ -103,13 +107,13 @@ def _pgettext(msgctxt, message):
         return message if translation == key else translation
 
 
-def _ngettext(message, plural, num):
+def _ngettext(message: str, plural: str, num: int) -> str:
     """Plural version of _gettext.
 
     Args:
         message (str): Singular text to translate.
         plural (str): Plural text to translate.
-        num (str): The number (e.g. item count) to determine translation for the
+        num (int): The number (e.g. item count) to determine translation for the
             respective grammatical number.
 
     Returns:
@@ -118,7 +122,7 @@ def _ngettext(message, plural, num):
     return get_translation().ngettext(message, plural, num)
 
 
-def _gettext_noop(message):
+def _gettext_noop(message: str) -> str:
     """Mark a string as a translation string without translating it.
 
     Example usage:
@@ -137,7 +141,7 @@ def num_name(n):
     return message
 
 
-def _ngettext_noop(singular, plural):
+def _ngettext_noop(singular: str, plural: str) -> tuple[str, str]:
     """Mark two strings as pluralized translations without translating them.
 
     Example usage:
@@ -154,7 +158,7 @@ def num_name(n):
     Returns:
         tuple: Original text, unchanged.
     """
-    return (singular, plural)
+    return singular, plural
 
 
 def thousands_separator() -> str: