Apply type hinting across most modules

Author: huangsam

ultimatepython/advanced/async.py

@@ -31,20 +31,20 @@ def _is_valid_record(record):
     return record.queued_at < record.started_at
 
 
-def _current_time():
+def _current_time() -> datetime:
     """Return current time that is timezone-naive."""
     return datetime.now()
 
 
-async def start_job(job_id, delay):
+async def start_job(job_id: str, delay: float) -> JobRecord:
     """Start job ID after a certain amount of delay."""
     queue_time = _current_time()
     await asyncio.sleep(delay)
     start_time = _current_time()
     return JobRecord(job_id, queue_time, start_time)
 
 
-async def schedule_jobs():
+async def schedule_jobs() -> None:
     """Schedule jobs concurrently."""
     # Start a job which also represents a coroutine
     single_job = start_job(uuid4().hex, _DELAY_SMALL)
@@ -77,7 +77,7 @@ async def schedule_jobs():
     assert all(_is_valid_record(record) for record in batch_records)
 
 
-def main():
+def main() -> None:
     asyncio.run(schedule_jobs())
 
 

ultimatepython/advanced/context_manager.py

@@ -8,6 +8,7 @@
 
 from contextlib import contextmanager
 from io import StringIO
+from typing import Generator
 
 # Simple directory with file contents
 _FILESYSTEM = {
@@ -18,7 +19,7 @@
 
 
 @contextmanager
-def file(filename):
+def file(filename: str) -> Generator[StringIO, None, None]:
     """File context manager.
 
     This is the function variant of the context manager. Context managers
@@ -42,19 +43,19 @@ class FileHandler:
     class or simply write a function.
     """
 
-    def __init__(self, filename):
+    def __init__(self, filename: str) -> None:
         self.io_buffer = StringIO(_FILESYSTEM[filename])
 
-    def __enter__(self):
+    def __enter__(self) -> StringIO:
         """Pass the buffer to the context block."""
         return self.io_buffer
 
-    def __exit__(self, *args):
+    def __exit__(self, *args) -> None:
         """Close the buffer unconditionally."""
         self.io_buffer.close()
 
 
-def main():
+def main() -> None:
     # An example of a function-based context manager
     with file("a.txt") as txt_buffer:
         assert txt_buffer.read() == "Hello World"

ultimatepython/advanced/date_time.py

@@ -26,7 +26,7 @@
 from datetime import datetime, timezone
 
 
-def convert_dt_to_utc_epoch(dt):
+def convert_dt_to_utc_epoch(dt: datetime) -> int:
     """Convert datetime to UTC epoch seconds.
 
     Note that the timestamp method assumes that an offset-naive
@@ -36,27 +36,27 @@ def convert_dt_to_utc_epoch(dt):
     return dt.timestamp()
 
 
-def convert_utc_epoch_to_dt(epoch):
+def convert_utc_epoch_to_dt(epoch: int) -> datetime:
     """Convert UTC epoch seconds to datetime."""
     return datetime.fromtimestamp(epoch, tz=timezone.utc)
 
 
-def convert_dt_timezone(dt, tz):
+def convert_dt_timezone(dt: datetime, tz: timezone) -> datetime:
     """Convert datetime timezone."""
     return dt.astimezone(tz=tz)
 
 
-def get_utc_now_as_dt():
+def get_utc_now_as_dt() -> datetime:
     """Get current UTC time as datetime."""
     return datetime.now(tz=timezone.utc)
 
 
-def get_utc_now_as_epoch():
+def get_utc_now_as_epoch() -> int:
     """Get current UTC time as epoch seconds."""
     return convert_dt_to_utc_epoch(get_utc_now_as_dt())
 
 
-def main():
+def main() -> None:
     # Create offset-naive datetime
     naive_dt = datetime.now()
     assert naive_dt.tzinfo is None

ultimatepython/advanced/decorator.py

@@ -6,12 +6,13 @@
 """
 
 from functools import wraps
+from typing import Any, Callable
 
 # Module-level constants
 _MASKING = "*"
 
 
-def run_with_stringy(fn):
+def run_with_stringy(fn: Callable[[str], str]) -> Callable[[Any], Any]:
     """Run a string function with a string or a collection of strings.
 
     We define a custom decorator that allows us to convert a function whose
@@ -40,7 +41,7 @@ def run_with_stringy(fn):
     """
 
     @wraps(fn)
-    def wrapper(obj):
+    def wrapper(obj: Any) -> Any:
         """Apply wrapped function to a string or a collection.
 
         This looks like a policy-based engine which runs a `return` statement
@@ -65,14 +66,14 @@ def wrapper(obj):
 
 
 @run_with_stringy
-def hide_content(content):
+def hide_content(content: str) -> str:
     """Hide half of the string content."""
     start_point = len(content) // 2
     num_of_asterisks = len(content) // 2 + len(content) % 2
     return content[:start_point] + _MASKING * num_of_asterisks
 
 
-def _is_hidden(obj):
+def _is_hidden(obj: Any) -> bool:
     """Check whether string or collection is hidden."""
     if isinstance(obj, str):
         return _MASKING in obj
@@ -81,7 +82,7 @@ def _is_hidden(obj):
     return all(_is_hidden(value) for value in obj)
 
 
-def main():
+def main() -> None:
     # There is so much plain-text data out in the open
     insecure_data = [
         {"username": "johndoe", "country": "USA"},  # User information

ultimatepython/advanced/file_handling.py

@@ -13,34 +13,34 @@
 _TARGET_FILE = "sample.txt"
 
 
-def read_file(filename):
+def read_file(filename: str) -> str:
     """Read content from existing file."""
     with open(filename, "r") as file:
         content = file.read()
         return content
 
 
-def write_file(filename, content):
+def write_file(filename: str, content: str) -> str:
     """Write content to new file."""
     with open(filename, "w") as file:
         file.write(content)
     return f"Content written to '{filename}'."
 
 
-def append_file(filename, content):
+def append_file(filename: str, content: str) -> str:
     """Append content to existing file."""
     with open(filename, "a") as file:
         file.write(content)
     return f"Content appended to '{filename}'."
 
 
-def delete_file(filename):
+def delete_file(filename: str) -> str:
     """Delete content of existing file."""
     os.remove(filename)
     return f"'{filename}' has been deleted."
 
 
-def main():
+def main() -> None:
     result = write_file(_TARGET_FILE, "This is a test.")
     assert result == f"Content written to '{_TARGET_FILE}'."
 

ultimatepython/advanced/thread.py

@@ -24,26 +24,27 @@
 import time
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime
+from typing import Callable, Iterable, Set
 
 # Module-level constants
 _MULTIPLY_DELAY = 0.01  # delay is long enough for threads to be faster
 
 
-def multiply_by_two(item):
+def multiply_by_two(item: int) -> int:
     """This multiplication has a small delay."""
     time.sleep(_MULTIPLY_DELAY)
     return item * 2
 
 
-def run_thread_workers(work, data):
+def run_thread_workers(work: Callable[[int], int], data: Iterable[int]) -> Set[int]:
     """Run thread workers that invoke work on each data element.
 
     The inspiration for this function comes directly from an example
     in the Python 3.x documentation:
 
     https://docs.python.org/3/library/concurrent.futures.html
     """
-    results = set()
+    results: Set[int] = set()
 
     # We can use a with statement to ensure workers are cleaned up promptly
     with ThreadPoolExecutor() as executor:
@@ -55,7 +56,7 @@ def run_thread_workers(work, data):
     return results
 
 
-def main():
+def main() -> None:
     original_data = {num for num in range(5)}
     expected_data = {(item * 2) for item in original_data}
 

ultimatepython/classes/abstract_class.py

@@ -20,20 +20,20 @@ class Employee(ABC):
     can work and relax is different from another type of employee.
     """
 
-    def __init__(self, name, title):
+    def __init__(self, name: str, title: str) -> None:
         self.name = name
         self.title = title
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
     @abstractmethod
-    def do_work(self):
+    def do_work(self) -> str:
         """Do something for work."""
         raise NotImplementedError
 
     @abstractmethod
-    def do_relax(self):
+    def do_relax(self) -> str:
         """Do something to relax."""
         raise NotImplementedError
 
@@ -49,14 +49,14 @@ class Engineer(Employee):
     is something that a manager prefers not to do.
     """
 
-    def __init__(self, name, title, skill):
+    def __init__(self, name: str, title: str, skill: str) -> None:
         super().__init__(name, title)
         self.skill = skill
 
-    def do_work(self):
+    def do_work(self) -> str:
         return f"{self} is coding in {self.skill}"
 
-    def do_relax(self):
+    def do_relax(self) -> str:
         return f"{self} is watching YouTube"
 
     def do_refactor(self):
@@ -73,22 +73,22 @@ class is concrete. Notice that a manager has direct reports and
     engineer.
     """
 
-    def __init__(self, name, title, direct_reports):
+    def __init__(self, name: str, title: str, direct_reports: list) -> None:
         super().__init__(name, title)
         self.direct_reports = direct_reports
 
-    def do_work(self):
+    def do_work(self) -> str:
         return f"{self} is meeting up with {len(self.direct_reports)} reports"
 
-    def do_relax(self):
+    def do_relax(self) -> str:
         return f"{self} is taking a trip to the Bahamas"
 
-    def do_hire(self):
+    def do_hire(self) -> str:
         """Do the hard work of hiring employees, unlike engineers."""
         return f"{self} is hiring employees"
 
 
-def main():
+def main() -> None:
     # Declare two engineers
     engineer_john = Engineer("John Doe", "Software Engineer", "Android")
     engineer_jane = Engineer("Jane Doe", "Software Engineer", "iOS")

ultimatepython/classes/basic_class.py

@@ -15,27 +15,27 @@ class Car:
     class definition.
     """
 
-    def __init__(self, make, model, year, miles):
+    def __init__(self, make: str, model: str, year: int, miles: float) -> None:
         """Constructor logic."""
         self.make = make
         self.model = model
         self.year = year
         self.miles = miles
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """Formal representation for developers."""
         return f"<Car make={self.make} model={self.model} year={self.year}>"
 
-    def __str__(self):
+    def __str__(self) -> str:
         """Informal representation for users."""
         return f"{self.make} {self.model} ({self.year})"
 
-    def drive(self, rate_in_mph):
+    def drive(self, rate_in_mph: int) -> str:
         """Drive car at a certain rate in MPH."""
         return f"{self} is driving at {rate_in_mph} MPH"
 
 
-def main():
+def main() -> None:
     # Create a car with the provided class constructor
     car = Car("Bumble", "Bee", 2000, 200000.0)