Add typehint annotations

Makefile

@@ -47,7 +47,7 @@ lint:
 	isort --check brazilcep tests
 	black --check brazilcep tests
 	ruff check brazilcep tests
-	CUDA_VISIBLE_DEVICES='' pytest -v --color=yes --doctest-modules tests/ brazilcep/
+	mypy brazilcep
 
 .PHONY : docs
 docs:
@@ -67,6 +67,7 @@ setup:
 	pre-commit install --hook-type pre-commit
 	pre-commit install --hook-type pre-push
 	pre-commit autoupdate
+	mypy --install-types
 
 .PHONY : test
 test:

brazilcep/apicep.py

@@ -9,6 +9,7 @@
 """
 
 import json
+from typing import Union
 
 import requests
 
@@ -17,17 +18,17 @@
 URL = "https://ws.apicep.com/cep/{}.json"
 
 
-def fetch_address(cep, timeout, proxies):
+def fetch_address(cep: str, timeout: Union[None, int], proxies: Union[None, dict]) -> dict:
     """Fetch VIACEP webservice for CEP address. VIACEP provide
     a REST API to query CEP requests.
 
     Args:
-        cep (str):CEP to be searched.
-        timeout (int): How many seconds to wait for the server to return data before giving up.
-        proxies (dict):  Dictionary mapping protocol to the URL of the proxy.
+        cep: CEP to be searched.
+        timeout: How many seconds to wait for the server to return data before giving up.
+        proxies:  Dictionary mapping protocol to the URL of the proxy.
 
     Returns:
-        address (dict): respective address data from CEP.
+        Respective address data from CEP.
     """
 
     response = requests.get(URL.format(cep), timeout=timeout, proxies=proxies)

brazilcep/client.py

@@ -11,12 +11,13 @@
 
 import enum
 import re
+from typing import Optional
 from warnings import warn
 
 from . import apicep, opencep, viacep
 
 NUMBERS = re.compile(r"[^0-9]")
-DEFAULT_TIMEOUT = 5  # in seconds
+DEFAULT_TIMEOUT: int = 5  # in seconds
 
 
 class WebService(enum.Enum):
@@ -32,7 +33,7 @@ class WebService(enum.Enum):
     OPENCEP = 3
 
 
-services = {
+services: dict = {
     # TOFIX: compatibility adjust. remove CORREIOS in next version
     WebService.CORREIOS: opencep.fetch_address,
     WebService.VIACEP: viacep.fetch_address,
@@ -41,13 +42,18 @@ class WebService(enum.Enum):
 }
 
 
-def get_address_from_cep(cep, webservice=WebService.APICEP, timeout=None, proxies=None):
+def get_address_from_cep(
+    cep: str,
+    webservice: WebService = WebService.APICEP,
+    timeout: Optional[int] = None,
+    proxies: Optional[dict] = None,
+) -> dict:
     """Returns the address corresponding to the zip (cep) code entered.
 
     Args:
-        cep (str): CEP to be queried.
-        timeout (int): How many seconds to wait for the server to return data before giving up.
-        proxies (dict):  Dictionary mapping protocol to the URL of the proxy.
+        cep: CEP to be queried.
+        timeout: How many seconds to wait for the server to return data before giving up.
+        proxies:  Dictionary mapping protocol to the URL of the proxy.
 
     Raises:
         RequestError: When connection error occurs in CEP query
@@ -57,8 +63,7 @@ def get_address_from_cep(cep, webservice=WebService.APICEP, timeout=None, proxie
         Exception: When any error occurs in the CEP query
 
     returns:
-        address (dict): Address data of the queried CEP.
-
+        Address data of the queried CEP.
     """
 
     if webservice == WebService.CORREIOS:
@@ -76,7 +81,7 @@ def get_address_from_cep(cep, webservice=WebService.APICEP, timeout=None, proxie
     return services[webservice](_format_cep(cep), timeout=timeout, proxies=proxies)
 
 
-def _format_cep(cep):
+def _format_cep(cep: str) -> str:
     """Format CEP, removing any non-numeric characters.
 
     Args:

brazilcep/opencep.py

@@ -9,6 +9,7 @@
 """
 
 import json
+from typing import Union
 
 import requests
 
@@ -17,17 +18,17 @@
 URL = "https://opencep.com/v1/{}"
 
 
-def fetch_address(cep, timeout=None, proxies=None):
+def fetch_address(cep: str, timeout: Union[None, int], proxies: Union[None, dict]) -> dict:
     """Fetch OpenCEP webservice for CEP address. OpenCEP provide
     a REST API to query CEP requests.
 
     Args:
-        cep (str):CEP to be searched.
-        timeout (int): How many seconds to wait for the server to return data before giving up.
-        proxies (dict):  Dictionary mapping protocol to the URL of the proxy.
+        cep: CEP to be searched.
+        timeout: How many seconds to wait for the server to return data before giving up.
+        proxies: Dictionary mapping protocol to the URL of the proxy.
 
     Returns:
-        address (dict): respective address data from CEP.
+        Respective address data from CEP.
     """
 
     response = requests.get(URL.format(cep), timeout=timeout, proxies=proxies)

brazilcep/py.typed

@@ -0,0 +1,3 @@
+# Required by PEP 561 to show that we have static types
+# See https://www.python.org/dev/peps/pep-0561/#packaging-type-information.
+# Enables mypy to discover type hints.

brazilcep/viacep.py

@@ -9,6 +9,7 @@
 """
 
 import json
+from typing import Union
 
 import requests
 
@@ -17,18 +18,17 @@
 URL = "http://www.viacep.com.br/ws/{}/json"
 
 
-def fetch_address(cep, timeout, proxies):
+def fetch_address(cep: str, timeout: Union[None, int], proxies: Union[None, dict]) -> dict:
     """Fetch APICEP webservice for CEP address. APICEP provide
     a REST API to query CEP requests.
 
     Args:
-        cep (str):CEP to be searched.
-        timeout (int): How many seconds to wait for the server to return data before giving up.
-        proxies (dict):  Dictionary mapping protocol to the URL of the proxy.
-
+        cep: CEP to be searched.
+        timeout: How many seconds to wait for the server to return data before giving up.
+        proxies:  Dictionary mapping protocol to the URL of the proxy.
 
     Returns:
-        address (dict): respective address data from CEP.
+        Respective address data from CEP.
     """
 
     response = requests.get(URL.format(cep), timeout=timeout, proxies=proxies)

pyproject.toml

@@ -37,6 +37,8 @@ dependencies = ["requests>=2.28.2"]
 dev = [
   "tox>=4.23.2",
   "pytest>=7.3.1",
+  "mypy>=1.0,<1.5",
+  "types-requests",
   "requests-mock>=1.10.0",
   "black>=23.0,<24.0",
   "isort>=5.12,<5.13",
@@ -79,6 +81,12 @@ ignore = [
 [tool.setuptools]
 include-package-data = true
 
+[tool.setuptools.packages.find]
+exclude = ["*.tests", "*.tests.*", "tests.*", "tests", "docs*", "scripts*"]
+
+[tool.setuptools.package-data]
+brazilcep = ["py.typed"]
+
 [tool.setuptools.dynamic]
 version = { attr = "brazilcep.__version__.__version__" }
 
@@ -116,6 +124,16 @@ target-version = "py39"
 [tool.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 
+[tool.mypy]
+# ignore_missing_imports = true
+# no_site_packages = true
+# check_untyped_defs = true
+strict = false
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+strict_optional = false
+
 [tool.coverage.run]
 branch = true
 omit = ["tests/*"]