Typing [Fixed #1489!]

MANIFEST.in

@@ -5,6 +5,7 @@ include CHANGELOG.md
 include RELEASE_PROCESS.rst
 include VERSION
 include CITATION.cff
+include mypy.ini
 recursive-include tests *.json
 recursive-include tests *.py
 recursive-exclude faker/sphinx *.py

docs/coding_style.rst

@@ -3,7 +3,7 @@ Coding Style
 
 Lines length should not exceed 120 characters. Please use trailing commas.
 
-Plese include `type hints`_ for every provider method you write.
+Please include `type hints`_ for every provider method you write. An overview of generic types is included below.
 
 You can find our complete flake8 configuration in the tox.ini_ file.
 
@@ -22,6 +22,20 @@ Name Lists
 
 When you have long lists of names, please order them alphabetically. Keep the lines length as close as possible to 120 characters, without exceeding the limit.
 
+
+Type Hints 
+----------
+`typing.py` includes generic types that can be re-used throughout the codebase. Moreover, some type definitions are 
+included in other parts of the code. If you add a generic type, please specify its usage below:
+
+| Type | Used for |
+|------|----------|
+| `providers.ElementsType` | When creating a variable in a `Provider` (e.g. for a specific locale), which is not defined in the superclass, `self.random_element()`, `self.random_elements()`, `self.random_choices()` and `self.random_sample()` assume this to be the input format. |
+| `typing.DateParseType` | Input for various `faker.providers.date_time` functions that parse (relative) dates/times. |
+| `typing.HueType` | Hue name, float value or integer range. |
+| `typing.GenderType` | String variable that can only have values `'F'` (female) and `'M'` (male) |
+
+
 .. _`tox.ini`: https://github.com/joke2k/faker/blob/master/tox.ini
 .. _`pep 8`: https://python.org/dev/peps/pep-0008
 .. _`pep 263`: https://python.org/dev/peps/pep-0263

faker/__main__.py

@@ -1,3 +1,3 @@
 if __name__ == "__main__":
-    from faker.cli import execute_from_command_line
+    from .cli import execute_from_command_line
     execute_from_command_line()

faker/cli.py

@@ -4,22 +4,27 @@
 import random
 import sys
 
+from io import TextIOWrapper
 from pathlib import Path
-from typing import Any, Dict, List, Optional, TextIO
+from typing import Dict, List, Optional, TextIO, TypeVar, Union
 
-from faker import VERSION, Faker, documentor, exceptions
-from faker.config import AVAILABLE_LOCALES, DEFAULT_LOCALE, META_PROVIDERS_MODULES
+from . import VERSION, Faker, documentor, exceptions
+from .config import AVAILABLE_LOCALES, DEFAULT_LOCALE, META_PROVIDERS_MODULES
+from .documentor import Documentor
+from .providers import BaseProvider
 
 __author__ = 'joke2k'
 
+T = TypeVar('T')
 
-def print_provider(doc,
-                   provider: List[str],
-                   formatters: Dict[str, Any],
-                   excludes=None,
-                   output: Optional[TextIO] = None) -> None:
 
-    output = output or sys.stdout
+def print_provider(doc: Documentor,
+                   provider: BaseProvider,
+                   formatters: Dict[str, T],
+                   excludes: Optional[List[str]] = None,
+                   output: Optional[TextIO] = None) -> None:
+    if output is None:
+        output = sys.stdout
     if excludes is None:
         excludes = []
 
@@ -48,11 +53,16 @@ def print_provider(doc,
                 signature = separator = ' '
 
 
-def print_doc(provider_or_field=None,
-              args=None, lang: str = DEFAULT_LOCALE, output=None, seed=None,
-              includes=None) -> None:
-    args = args or []
-    output = output or sys.stdout
+def print_doc(provider_or_field: Optional[str] = None,
+              args: Optional[List[T]] = None,
+              lang: str = DEFAULT_LOCALE,
+              output: Optional[Union[TextIO, TextIOWrapper]] = None,
+              seed: Optional[float] = None,
+              includes: Optional[List[str]] = None) -> None:
+    if args is None:
+        args = []
+    if output is None:
+        output = sys.stdout
     fake = Faker(locale=lang, includes=includes)
     fake.seed_instance(seed)
 
@@ -86,7 +96,7 @@ def print_doc(provider_or_field=None,
 
     else:
         doc = documentor.Documentor(fake)
-        unsupported = []
+        unsupported: List[str] = []
 
         while True:
             try:
@@ -97,7 +107,6 @@ def print_doc(provider_or_field=None,
                 break
 
         for provider, fakers in formatters:
-
             print_provider(doc, provider, fakers, output=output)
 
         for language in AVAILABLE_LOCALES:
@@ -117,7 +126,7 @@ def print_doc(provider_or_field=None,
 
 class Command:
 
-    def __init__(self, argv=None) -> None:
+    def __init__(self, argv: Optional[str] = None) -> None:
         self.argv = argv or sys.argv[:]
         self.prog_name = Path(self.argv[0]).name
 
@@ -259,7 +268,7 @@ def execute(self) -> None:
                 break
 
 
-def execute_from_command_line(argv=None) -> None:
+def execute_from_command_line(argv: Optional[str] = None) -> None:
     """A simple method that runs a Command."""
     if sys.stdout.encoding is None:
         print('please set python env PYTHONIOENCODING=UTF-8, example: '

faker/config.py

@@ -1,6 +1,6 @@
 from importlib import import_module
 
-from faker.utils.loading import find_available_locales, find_available_providers
+from .utils.loading import find_available_locales, find_available_providers
 
 DEFAULT_LOCALE = 'en_US'
 

faker/documentor.py

@@ -1,24 +1,33 @@
 import inspect
 import warnings
 
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from .generator import Generator
+from .providers import BaseProvider
+from .proxy import Faker
+
 
 class Documentor:
 
-    def __init__(self, generator):
+    def __init__(self, generator: Union[Generator, Faker]) -> None:
         """
         :param generator: a localized Generator with providers filled,
                           for which to write the documentation
         :type generator: faker.Generator()
         """
         self.generator = generator
-        self.max_name_len = 0
-        self.already_generated = []
+        self.max_name_len: int = 0
+        self.already_generated: List[str] = []
 
-    def get_formatters(self, locale=None, excludes=None, **kwargs):
+    def get_formatters(self,
+                       locale: Optional[str] = None,
+                       excludes: Optional[List[str]] = None,
+                       **kwargs: Any) -> List[Tuple[BaseProvider, Dict[str, str]]]:
         self.max_name_len = 0
         self.already_generated = [] if excludes is None else excludes[:]
         formatters = []
-        providers = self.generator.get_providers()
+        providers: List[BaseProvider] = self.generator.get_providers()
         for provider in providers[::-1]:  # reverse
             if locale and provider.__lang__ != locale:
                 continue
@@ -27,9 +36,11 @@ def get_formatters(self, locale=None, excludes=None, **kwargs):
             )
         return formatters
 
-    def get_provider_formatters(self, provider, prefix='fake.',
-                                with_args=True, with_defaults=True):
-
+    def get_provider_formatters(self,
+                                provider: BaseProvider,
+                                prefix: str = 'fake.',
+                                with_args: bool = True,
+                                with_defaults: bool = True) -> Dict[str, str]:
         formatters = {}
 
         for name, method in inspect.getmembers(provider, inspect.ismethod):
@@ -38,7 +49,7 @@ def get_provider_formatters(self, provider, prefix='fake.',
                 continue
 
             arguments = []
-            faker_args = []
+            faker_args: List[str] = []
             faker_kwargs = {}
 
             if name == 'binary':
@@ -98,5 +109,5 @@ def get_provider_formatters(self, provider, prefix='fake.',
         return formatters
 
     @staticmethod
-    def get_provider_name(provider_class):
+    def get_provider_name(provider_class: BaseProvider) -> str:
         return provider_class.__provider__

faker/exceptions.py

@@ -10,6 +10,7 @@ class UniquenessException(BaseFakerException):
 
 class UnsupportedFeature(BaseFakerException):
     """The requested feature is not available on this system."""
-    def __init__(self, msg, name):
+
+    def __init__(self, msg: str, name: str) -> None:
         self.name = name
         super().__init__(msg)

faker/factory.py

@@ -3,10 +3,11 @@
 import sys
 
 from importlib import import_module
+from typing import Any, List, Optional, Tuple
 
-from faker.config import AVAILABLE_LOCALES, DEFAULT_LOCALE, PROVIDERS
-from faker.generator import Generator
-from faker.utils.loading import list_module
+from .config import AVAILABLE_LOCALES, DEFAULT_LOCALE, PROVIDERS
+from .generator import Generator
+from .utils.loading import list_module
 
 logger = logging.getLogger(__name__)
 
@@ -23,14 +24,14 @@ class Factory:
     @classmethod
     def create(
             cls,
-            locale=None,
-            providers=None,
-            generator=None,
-            includes=None,
+            locale: Optional[str] = None,
+            providers: Optional[List[str]] = None,
+            generator: Generator = None,
+            includes: Optional[List[str]] = None,
             # Should we use weightings (more realistic) or weight every element equally (faster)?
             # By default, use weightings for backwards compatibility & realism
-            use_weighting=True,
-            **config):
+            use_weighting: bool = True,
+            **config: Any) -> Generator:
         if includes is None:
             includes = []
 
@@ -63,7 +64,7 @@ def create(
         return faker
 
     @classmethod
-    def _get_provider_class(cls, provider, locale=''):
+    def _get_provider_class(cls, provider: str, locale: Optional[str] = '') -> Tuple[Any, Optional[str]]:
 
         provider_class = cls._find_provider_class(provider, locale)
 
@@ -85,7 +86,7 @@ def _get_provider_class(cls, provider, locale=''):
         raise ValueError(msg)
 
     @classmethod
-    def _find_provider_class(cls, provider_path, locale=None):
+    def _find_provider_class(cls, provider_path: str, locale: Optional[str] = None) -> Any:
 
         provider_module = import_module(provider_path)
 
@@ -117,4 +118,4 @@ def _find_provider_class(cls, provider_path, locale=None):
             if locale is not None:
                 provider_module = import_module(provider_path)
 
-        return provider_module.Provider
+        return provider_module.Provider  # type: ignore