Add type annotations for files in /utils (#1335)

* Add type annotations for files in /utils

* Remove py35 and add py39 to appveyor config

Python 3.5 was deprecated in #1332.

* Add base image VS 2019 to appveyor to support Python 3.9

appveyor.yml

@@ -1,12 +1,9 @@
 # https://ci.appveyor.com/project/joke2k/faker
 build: false
+image: Visual Studio 2019
 
 environment:
   matrix:
-    - PYTHON: "C:\\Python35"
-      PYTHON_VERSION: "3.5.x"
-      PYTHON_ARCH: "32"
-
     - PYTHON: "C:\\Python36"
       PYTHON_VERSION: "3.6.x"
       PYTHON_ARCH: "32"
@@ -19,9 +16,9 @@ environment:
       PYTHON_VERSION: "3.8.x"
       PYTHON_ARCH: "32"
 
-    - PYTHON: "C:\\Python35-x64"
-      PYTHON_VERSION: "3.5.x"
-      PYTHON_ARCH: "64"
+    - PYTHON: "C:\\Python39"
+      PYTHON_VERSION: "3.9.x"
+      PYTHON_ARCH: "32"
 
     - PYTHON: "C:\\Python36-x64"
       PYTHON_VERSION: "3.6.x"
@@ -35,6 +32,10 @@ environment:
       PYTHON_VERSION: "3.8.x"
       PYTHON_ARCH: "64"
 
+    - PYTHON: "C:\\Python39-x64"
+      PYTHON_VERSION: "3.9.x"
+      PYTHON_ARCH: "64"
+
 init:
   - "ECHO %PYTHON%"
   - ps: "ls C:/Python*"

faker/utils/checksums.py

@@ -1,5 +1,8 @@
-def luhn_checksum(number):
-    def digits_of(n):
+from typing import List
+
+
+def luhn_checksum(number: float) -> int:
+    def digits_of(n: float) -> List[int]:
         return [int(d) for d in str(n)]
 
     digits = digits_of(number)
@@ -12,7 +15,7 @@ def digits_of(n):
     return checksum % 10
 
 
-def calculate_luhn(partial_number):
+def calculate_luhn(partial_number: float) -> int:
     """
     Generates the Checksum using Luhn's algorithm
     """

faker/utils/datasets.py

@@ -2,9 +2,10 @@
 
 from collections import Counter
 from functools import reduce
+from typing import Dict, Tuple
 
 
-def add_dicts(*args):
+def add_dicts(*args: Tuple[Dict, ...]) -> Dict:
     """
     Adds two or more dicts together. Common keys will have their values added.
 

faker/utils/decorators.py

@@ -1,31 +1,32 @@
 from functools import wraps
+from typing import Any, Callable, Dict, Tuple
 
 from faker.utils import text
 
 
-def slugify(fn):
+def slugify(fn: Callable) -> Callable:
     @wraps(fn)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Tuple[Any, ...], **kwargs: Dict[str, Any]) -> str:
         return text.slugify(fn(*args, **kwargs))
     return wrapper
 
 
-def slugify_domain(fn):
+def slugify_domain(fn: Callable) -> Callable:
     @wraps(fn)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Tuple[Any, ...], **kwargs: Dict[str, Any]) -> str:
         return text.slugify(fn(*args, **kwargs), allow_dots=True)
     return wrapper
 
 
-def slugify_unicode(fn):
+def slugify_unicode(fn: Callable) -> Callable:
     @wraps(fn)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Tuple[Any, ...], **kwargs: Dict[str, Any]) -> str:
         return text.slugify(fn(*args, **kwargs), allow_unicode=True)
     return wrapper
 
 
-def lowercase(fn):
+def lowercase(fn: Callable) -> Callable:
     @wraps(fn)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: Tuple[Any, ...], **kwargs: Dict[str, Any]) -> str:
         return fn(*args, **kwargs).lower()
     return wrapper

faker/utils/distribution.py

@@ -1,22 +1,30 @@
 import bisect
 
+from random import Random
+from typing import Generator, Iterable, List, Optional, TypeVar
+
 from faker.generator import random as mod_random
 
 
-def random_sample(random=None):
+def random_sample(random: Optional[Random] = None) -> float:
     if random is None:
         random = mod_random
     return random.uniform(0.0, 1.0)
 
 
-def cumsum(it):
-    total = 0
+def cumsum(it: Iterable[float]) -> Generator[float, None, None]:
+    total: float = 0
     for x in it:
         total += x
         yield total
 
 
-def choices_distribution_unique(a, p, random=None, length=1):
+T = TypeVar('T')
+
+
+def choices_distribution_unique(
+        a: List[T], p: List[float], random: Optional[Random] = None, length: int = 1,
+) -> List[T]:
     # As of Python 3.7, there isn't a way to sample unique elements that takes
     # weight into account.
     if random is None:
@@ -41,7 +49,7 @@ def choices_distribution_unique(a, p, random=None, length=1):
     return choices
 
 
-def choices_distribution(a, p, random=None, length=1):
+def choices_distribution(a: List[T], p: List[float], random: Optional[Random] = None, length: int = 1) -> List[T]:
     if random is None:
         random = mod_random
 

faker/utils/loading.py

@@ -3,9 +3,11 @@
 import sys
 
 from importlib import import_module
+from types import ModuleType
+from typing import List, Set
 
 
-def get_path(module):
+def get_path(module: ModuleType) -> str:
     if getattr(sys, 'frozen', False):
         # frozen
 
@@ -17,15 +19,15 @@ def get_path(module):
             base_dir = os.path.dirname(sys.executable)
             lib_dir = os.path.join(base_dir, "lib")
 
-        module_to_rel_path = os.path.join(*module.__package__.split("."))
+        module_to_rel_path = os.path.join(*module.__package__.split(".")) if module.__package__ else ''
         path = os.path.join(lib_dir, module_to_rel_path)
     else:
         # unfrozen
         path = os.path.dirname(os.path.realpath(module.__file__))
     return path
 
 
-def list_module(module):
+def list_module(module: ModuleType) -> List[str]:
     path = get_path(module)
 
     if getattr(sys, '_MEIPASS', False):
@@ -37,25 +39,26 @@ def list_module(module):
         return [name for _, name, is_pkg in pkgutil.iter_modules([path]) if is_pkg]
 
 
-def find_available_locales(providers):
-    available_locales = set()
+def find_available_locales(providers: List[str]) -> List[str]:
+    available_locales: Set[str] = set()
 
     for provider_path in providers:
 
         provider_module = import_module(provider_path)
         if getattr(provider_module, 'localized', False):
             langs = list_module(provider_module)
             available_locales.update(langs)
-    available_locales = sorted(available_locales)
+    available_locales: List[str] = sorted(available_locales)
     return available_locales
 
 
-def find_available_providers(modules):
+def find_available_providers(modules: List[ModuleType]) -> List[str]:
     available_providers = set()
     for providers_mod in modules:
-        providers = [
-            '.'.join([providers_mod.__package__, mod])
-            for mod in list_module(providers_mod) if mod != '__pycache__'
-        ]
-        available_providers.update(providers)
+        if providers_mod.__package__:
+            providers = [
+                '.'.join([providers_mod.__package__, mod])
+                for mod in list_module(providers_mod) if mod != '__pycache__'
+            ]
+            available_providers.update(providers)
     return sorted(available_providers)

faker/utils/text.py

@@ -6,7 +6,7 @@
 _re_spaces = re.compile(r'[-\s]+', flags=re.U)
 
 
-def slugify(value, allow_dots=False, allow_unicode=False):
+def slugify(value: str, allow_dots: bool = False, allow_unicode: bool = False) -> str:
     """
     Converts to lowercase, removes non-word characters (alphanumerics and
     underscores) and converts spaces to hyphens. Also strips leading and