Using Type Hints

00:00 Use Type Hints to Provide Automatic Type Information. As you may have noticed, in the docstrings you’ve written so far, you declared that the input variables should be of the type float. However, the functions work just as well when you use integers.

00:15 You even have proof of that through the function calls that you wrote in your doctests. You should probably update the argument types in your docstrings accordingly.

00:24 But instead of doing so in your docstrings, you’ll use Python type hints to declare the argument and return types of your functions. First, you import Union from the built-in typing module, which allows you to specify multiple types for an argument.

00:43 Then, change the first line of your function definition by adding type hints to your parameters and the return value.

00:59 Note that starting with Python 3.10, you can alternatively use the pipe operator (|) as a type union alias, as seen on-screen. This more succinct syntax also allows you to remove the import statement from the top of your file.

01:19 However, to keep type hints more compatible with older versions of type-checking tools, you’ll stick with Union in this example project. Adding type hints to your code allows you to use type checkers such as mypy to catch type-related errors that might otherwise go unnoticed.

01:39 If you want to learn more about writing type hints and type checking your Python code using third-party libraries, then you can refresh your memory in the Python Type Checking Guide.

01:50 Did you notice you’ve introduced some repeated information and inconsistencies regarding the types you’re mentioning in the docstring? Fortunately, mkdocstrings understands type hints and can infer typing from them.

02:02 This means you don’t need to add type information to the docstring. Google-style docstrings don’t have to contain type information if you use type hints in your code.

02:13 You can therefore remove the duplicated type information from the docstrings.

02:29 This change gives you a clean and descriptive docstring with an accurate representation of the expected types for your arguments and the return value of your function.

02:40 Documenting the types using type hints gives you the advantage that you can now use type checker tools to assure correct usage of your functions and hedge yourself against accidental misuse.

02:50 It also allows you to record type information in only one place, which removes repetition and keeps your code base DRY. Revisit calculations.py and add type hints to all of the functions.

04:17 With these updates, you’ve completed writing a solid suite of docstrings for all of the functions in the Python module. But what about the module itself?

04:27 In the next section, you’ll see how to add module docstrings.