Overload hash generation functions to make return types more specific

Before this change, the return type for these functions was always
`bytes| str`. However, the type can be narrowed based on the value
passed to `raw_output`.

This change adds overload annotations for the two allowable values to
allow type checkers to narrow the type and correctly infer the exact
return type.

Resolves #2046

faker/providers/misc/__init__.py

@@ -9,7 +9,7 @@
 import uuid
 import zipfile
 
-from typing import Any, Callable, Dict, List, Optional, Sequence, Set, Tuple, Type, Union
+from typing import Any, Callable, Dict, List, Literal, Optional, Sequence, Set, Tuple, Type, Union, overload
 
 from faker.exceptions import UnsupportedFeature
 
@@ -56,6 +56,14 @@ def binary(self, length: int = (1 * 1024 * 1024)) -> bytes:
  # Generator is unseeded anyway, just use urandom
  return os.urandom(length)
 
+ @overload
+ def md5(self, raw_output: Literal[True]) -> bytes:
+ ...
+
+ @overload
+ def md5(self, raw_output: Literal[False]) -> str:
+ ...
+
  def md5(self, raw_output: bool = False) -> Union[bytes, str]:
  """Generate a random MD5 hash.
 
@@ -70,6 +78,14 @@ def md5(self, raw_output: bool = False) -> Union[bytes, str]:
  return res.digest()
  return res.hexdigest()
 
+ @overload
+ def sha1(self, raw_output: Literal[True]) -> bytes:
+ ...
+
+ @overload
+ def sha1(self, raw_output: Literal[False]) -> str:
+ ...
+
  def sha1(self, raw_output: bool = False) -> Union[bytes, str]:
  """Generate a random SHA-1 hash.
 
@@ -84,6 +100,14 @@ def sha1(self, raw_output: bool = False) -> Union[bytes, str]:
  return res.digest()
  return res.hexdigest()
 
+ @overload
+ def sha256(self, raw_output: Literal[True]) -> bytes:
+ ...
+
+ @overload
+ def sha256(self, raw_output: Literal[False]) -> str:
+ ...
+
  def sha256(self, raw_output: bool = False) -> Union[bytes, str]:
  """Generate a random SHA-256 hash.
 

faker/proxy.pyi

@@ -20,6 +20,7 @@ from typing import (
  Type,
  TypeVar,
  Union,
+ overload,
 )
 from uuid import UUID
 
@@ -1944,7 +1945,20 @@ class Faker:
  :meth:`json() <faker.providers.misc.Provider.json>` which is used under the hood.
  """
  ...
- def md5(self, raw_output: bool = ...) -> Union[bytes, str]:
+ @overload
+ def md5(self, raw_output: Literal[True]) -> bytes:
+ """
+ Generate a random MD5 hash.
+
+ If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the MD5 hash
+ will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+ :sample: raw_output=False
+ :sample: raw_output=True
+ """
+ ...
+ @overload
+ def md5(self, raw_output: Literal[False]) -> str:
  """
  Generate a random MD5 hash.
 
@@ -2001,7 +2015,20 @@ class Faker:
  num_rows=10, include_row_ids=True
  """
  ...
- def sha1(self, raw_output: bool = ...) -> Union[bytes, str]:
+ @overload
+ def sha1(self, raw_output: Literal[True]) -> bytes:
+ """
+ Generate a random SHA-1 hash.
+
+ If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the SHA-1 hash
+ will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+ :sample: raw_output=False
+ :sample: raw_output=True
+ """
+ ...
+ @overload
+ def sha1(self, raw_output: Literal[False]) -> str:
  """
  Generate a random SHA-1 hash.
 
@@ -2012,7 +2039,20 @@ class Faker:
  :sample: raw_output=True
  """
  ...
- def sha256(self, raw_output: bool = ...) -> Union[bytes, str]:
+ @overload
+ def sha256(self, raw_output: Literal[True]) -> bytes:
+ """
+ Generate a random SHA-256 hash.
+
+ If ``raw_output`` is ``False`` (default), a hexadecimal string representation of the SHA-256 hash
+ will be returned. If ``True``, a ``bytes`` object representation will be returned instead.
+
+ :sample: raw_output=False
+ :sample: raw_output=True
+ """
+ ...
+ @overload
+ def sha256(self, raw_output: Literal[False]) -> str:
  """
  Generate a random SHA-256 hash.