Typing [Fixed #1489!]

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 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) -> 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 List, Optional
 
-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,13 +24,13 @@ 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,
+            use_weighting: bool = True,
             **config):
         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] = ''):
 
         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):
 
         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

faker/generator.py

@@ -1,24 +1,29 @@
 import random as random_module
 import re
 
+from typing import Callable, Dict, Hashable, List, Optional, TypeVar
+
 _re_token = re.compile(r'\{\{\s*(\w+)(:\s*\w+?)?\s*\}\}')
 random = random_module.Random()
 mod_random = random  # compat with name released in 0.8
 
+T = TypeVar('T')
+BaseProvider = TypeVar('BaseProvider')
+
 
 class Generator:
 
-    __config = {
+    __config: Dict[str, Dict[Hashable, T]] = {
         'arguments': {},
     }
 
-    def __init__(self, **config):
-        self.providers = []
+    def __init__(self, **config) -> None:
+        self.providers: List[BaseProvider] = []
         self.__config = dict(
             list(self.__config.items()) + list(config.items()))
         self.__random = random
 
-    def add_provider(self, provider):
+    def add_provider(self, provider: BaseProvider) -> None:
 
         if isinstance(provider, type):
             provider = provider(self)
@@ -36,27 +41,27 @@ def add_provider(self, provider):
                 # add all faker method to generator
                 self.set_formatter(method_name, faker_function)
 
-    def provider(self, name):
+    def provider(self, name: str) -> Optional[BaseProvider]:
         try:
             lst = [p for p in self.get_providers()
-                   if p.__provider__ == name.lower()]
+                   if hasattr(p, '__provider__') and p.__provider__ == name.lower()]  # type: ignore[attr-defined]
             return lst[0]
         except IndexError:
             return None
 
-    def get_providers(self):
+    def get_providers(self) -> List[BaseProvider]:
         """Returns added providers."""
         return self.providers
 
     @property
-    def random(self):
+    def random(self) -> random_module.Random:
         return self.__random
 
     @random.setter
-    def random(self, value):
+    def random(self, value: random_module.Random) -> None:
         self.__random = value
 
-    def seed_instance(self, seed=None):
+    def seed_instance(self, seed: Optional[Hashable] = None):
         """Calls random.seed"""
         if self.__random == random:
             # create per-instance random obj when first time seed_instance() is
@@ -66,16 +71,16 @@ def seed_instance(self, seed=None):
         return self
 
     @classmethod
-    def seed(cls, seed=None):
+    def seed(cls, seed: Optional[Hashable] = None):
         random.seed(seed)
 
-    def format(self, formatter, *args, **kwargs):
+    def format(self, formatter: str, *args, **kwargs) -> str:
         """
         This is a secure way to make a fake from another Provider.
         """
         return self.get_formatter(formatter)(*args, **kwargs)
 
-    def get_formatter(self, formatter):
+    def get_formatter(self, formatter: str) -> Callable:
         try:
             return getattr(self, formatter)
         except AttributeError:
@@ -85,14 +90,14 @@ def get_formatter(self, formatter):
                 raise AttributeError(f'Unknown formatter {formatter!r}')
             raise AttributeError(msg)
 
-    def set_formatter(self, name, method):
+    def set_formatter(self, name: str, method: Callable) -> None:
         """
         This method adds a provider method to generator.
         Override this method to add some decoration or logging stuff.
         """
         setattr(self, name, method)
 
-    def set_arguments(self, group, argument, value=None):
+    def set_arguments(self, group: str, argument: str, value: T = None):
         """
         Creates an argument group, with an individual argument or a dictionary
         of arguments. The argument groups is used to apply arguments to tokens,
@@ -112,7 +117,7 @@ def set_arguments(self, group, argument, value=None):
         else:
             self.__config['arguments'][group][argument] = value
 
-    def get_arguments(self, group, argument=None):
+    def get_arguments(self, group: str, argument: Optional[str] = None):
         """
         Get the value of an argument configured within a argument group, or
         the entire group as a dictionary. Used in conjunction with the
@@ -122,13 +127,13 @@ def get_arguments(self, group, argument=None):
         generator.get_arguments('small')
         """
         if group in self.__config['arguments'] and argument:
-            result = self.__config['arguments'][group].get(argument)
+            result = self.__config['arguments'][group].get(argument)  # type: ignore[attr-defined]
         else:
             result = self.__config['arguments'].get(group)
 
         return result
 
-    def del_arguments(self, group, argument=None):
+    def del_arguments(self, group: str, argument: Optional[str] = None):
         """
         Delete an argument from an argument group or the entire argument group.
         Used in conjunction with the set_arguments() method.
@@ -138,15 +143,15 @@ def del_arguments(self, group, argument=None):
         """
         if group in self.__config['arguments']:
             if argument:
-                result = self.__config['arguments'][group].pop(argument)
+                result = self.__config['arguments'][group].pop(argument)  # type: ignore[attr-defined]
             else:
                 result = self.__config['arguments'].pop(group)
         else:
             result = None
 
         return result
 
-    def parse(self, text):
+    def parse(self, text: str) -> str:
         """
         Replaces tokens like '{{ tokenName }}' or '{{tokenName}}' in a string with
         the result from the token method call. Arguments can be parsed by using an