{"id":1720,"date":"2024-04-19T20:25:48","date_gmt":"2024-04-19T14:55:48","guid":{"rendered":"https:\/\/geekpython.in\/?p=1720"},"modified":"2024-04-19T20:25:49","modified_gmt":"2024-04-19T14:55:49","slug":"type-hinting-in-python","status":"publish","type":"post","link":"https:\/\/geekpython.in\/type-hinting-in-python","title":{"rendered":"Python Type Hints: Functions, Return Values, Variable"},"content":{"rendered":"\n

Python is a dynamically typed language, meaning you do not need to specify the type of variables, parameters or return values. This is determined during program execution based on the values assigned to the variable or passed as the argument.<\/p>\n\n\n\n

Python introduced type hints<\/strong> or static typing<\/strong> with version 3.5, allowing developers to declare the data type of variables, parameters, etc.<\/p>\n\n\n\n

What are Type Hints?<\/h2>\n\n\n\n
x: int = 5\ny: str = \"5\"<\/pre><\/div>\n\n\n\n
In this example, the variable x<\/code> expects to be an integer value while the variable y<\/code> expects to be a string value.<\/p>\n\n\n\n
This is called type hint<\/strong> or static typing<\/strong> where you specify the expected data type<\/strong> for a variable, parameter or return value of a function.<\/p>\n\n\n\n
Python has a different way of declaring type hints for the variables, return values, collections, etc.<\/p>\n\n\n\n
Consider the following example:<\/p>\n\n\n\n
def circle(radius: float) -> str:\n    area = 3.14 * radius ** 2\n    return f\"Area of circle: {area}\"<\/pre><\/div>\n\n\n\n
In this example, the function circle accepts an argument radius<\/code> which is expected to be a float value as indicated by type hint radius: float<\/code>, and the return value of this function is expected to be a string, as indicated by the -> str<\/code> hint.<\/p>\n\n\n\n
Performing a Check<\/h2>\n\n\n\n
What if you pass the argument of a different type which is not expected? Consider the function below:<\/p>\n\n\n\n
def date(dd: str, mm: str, yyyy: str) -> str:\n    return f\"Current Date: {dd}-{mm}-{yyyy}\"\n\ncurr_date = date(22, 9, 2024)  # expected 'str' got 'int'\nprint(curr_date)<\/pre><\/div>\n\n\n\n
The function date()<\/code> accepts three arguments and expects all of them to be a string value, however, integer values are supplied when the function is called.<\/p>\n\n\n\n
What do you think? Will this program throw an error? Well, it looks like but Python or specifically interpreter completely ignores the type hints as this is not its purpose.<\/p>\n\n\n\n
Current Date: 22-9-2024<\/pre><\/div>\n\n\n\n
The type of arguments was decided in the runtime that is why no error is thrown, however, you may see a warning in your IDE or code editor.<\/p>\n\n\n\n
Annotating Multiple Return Types<\/h2>\n\n\n\n
In this section, you’ll learn how to annotate multiple return types for a single value of alternative types and multiple values of different types.<\/p>\n\n\n\n
Alternative Types for a Return Value<\/h3>\n\n\n\n
def cart(item: str) -> str | None:\n    if item == \"\":\n        return None\n    return \"Item added in the cart\"<\/pre><\/div>\n\n\n\n
The function cart()<\/code> accepts an argument item and returns None<\/code> if it is not supplied, otherwise, it returns a string.<\/p>\n\n\n\n
To represent multiple return types for a function, the (|<\/code>) pipe can be used. It means either str<\/code> or None<\/code>. So, when you call the function, it indicates that the return value of the function can be a str<\/code> or None<\/code>.<\/p>\n\n\n\n
You can also use typing.Union<\/code> to accomplish the same task you’ve done using the (|<\/code>).<\/p>\n\n\n\n
from typing import Union\n\ndef cart(item: str) -> Union[None, str]:\n    if item == \"\":\n        return None\n    return \"Item added in the cart\"<\/pre><\/div>\n\n\n\n
The Union[None, str]<\/code> is equivalent to None | str<\/code>. None | str<\/code> is a shorthand and it is a recommended way.<\/p>\n\n\n\n
Return Values of Different Types<\/h3>\n\n\n\n
def cart(item: str, quantity: int) -> dict[str, int] | None:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}<\/pre><\/div>\n\n\n\n
The function cart()<\/code> has been updated to accept an additional argument quantity<\/code> and returns None<\/code> if any of the arguments are left empty, otherwise, it returns a dictionary containing a key (str<\/code>) and value (int<\/code>).<\/p>\n\n\n\n
If you look at the type hint for the return value, this time different types (str<\/code> and int<\/code>) are expected to return in a dictionary (dict<\/code>).<\/p>\n\n\n\n
You can do this in the following way.<\/p>\n\n\n\n
from typing import Union, Dict\n\ndef cart(item: str, quantity: int) -> Union[Dict[str, int], None]:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}<\/pre><\/div>\n\n\n\n
You can use Mapping<\/code> instead of Dict<\/code> to represent the dictionary.<\/p>\n\n\n\n
from typing import Union, Mapping\n\ndef cart(item: str, quantity: int) -> Union[Mapping[str, int], None]:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}<\/pre><\/div>\n\n\n\n
But all this seems a bit verbose so you can go for shorthand syntax.<\/p>\n\n\n\n
Type Hinting Functions<\/h2>\n\n\n\n
from collections.abc import Callable\n\ndef apply_cart(\n        func: Callable[[str, int], dict[str, int]],\n        item: str,\n        quantity: int\n) -> dict[str, int]:\n    return func(item, quantity)\n\ndef cart(item: str, quantity: int) -> dict[str, int] | None:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}<\/pre><\/div>\n\n\n\n
The function apply_cart()<\/code> accepts a callable object (which can be a function or any other callable object) and two arguments (item<\/code> and quantity<\/code>) and returns a dictionary containing the key and value.<\/p>\n\n\n\n
The Callable<\/code> type hint provides a list of arguments ([str, int]<\/code>) that the callable object accepts. In this case, func()<\/code> expects strings and integers. Callable’s second parameter is the return value (dict[str, int]<\/code>), which is a dictionary.<\/p>\n\n\n\n
The second function, cart()<\/code>, is identical to the previous example and returns a dictionary if everything is correct.<\/p>\n\n\n\n
cart_item = apply_cart(cart, \"Mouse\", 2)\nprint(cart_item)\n--------------------\n{'Mouse': 2}<\/pre><\/div>\n\n\n\n
The apply_cart()<\/code> function is invoked with the cart<\/code> (a function) and two arguments ('Mouse'<\/code>, 2<\/code>).<\/p>\n\n\n\n
The apply_cart()<\/code> function calls the cart()<\/code> function with the given arguments and returns a result.<\/p>\n\n\n\n
Here’s an optimisation, if you have many arguments of different types, you can use ellipsis<\/strong> (...<\/code>) rather than passing different input types.<\/p>\n\n\n\n
The ellipsis literal (...<\/code>) indicates that callable can accept any arbitrary list of arguments.<\/p>\n\n\n\n
from collections.abc import Callable\nfrom typing import TypeVar, Any\n\nT = TypeVar(\"T\")\n\ndef apply_cart(\n        func: Callable[..., T],\n        *args: Any\n) -> T:\n    return func(*args)<\/pre><\/div>\n\n\n\n
The apply_cart()<\/code> function has been updated and now accepts an arbitrary list of arguments of any type ([..., T]<\/code>) as well as variadic argument (*args<\/code>) of any type (Any<\/code>).<\/p>\n\n\n\n
The first parameter in the Callable<\/code> is an ellipsis (...<\/code>), suggesting that any arbitrary parameter list is permitted.<\/p>\n\n\n\n
The second parameter is a type variable<\/strong> (T = TypeVar(\"T\")<\/code>) that can work with any type. It indicates that the callable can accept any type and return an element of that type.<\/p>\n\n\n\n
You can also use a parameter specification variable<\/strong> (ParamSpec<\/code>) instead of an ellipsis to make callable objects accept any number of positional or keyword arguments.<\/p>\n\n\n\n
from collections.abc import Callable\nfrom typing import TypeVar, ParamSpec\n\nP = ParamSpec(\"P\")\nT = TypeVar(\"T\")\n\ndef apply_cart(\n        func: Callable[P, T],\n        *args: P.args\n) -> T:\n    return func(*args)<\/pre><\/div>\n\n\n\n
In this case, the first parameter of Callable<\/code> is a parameter specification variable<\/strong> (P = ParamSpec(\"P\")<\/code>) indicating an arbitrary list of arguments is acceptable. The second parameter (T<\/code>) indicates that any type is acceptable.<\/p>\n\n\n\n
The function apply_cart()<\/code> also accepts a variadic argument (*args<\/code>) of type P.args<\/code> that represents a tuple of any number and type of positional arguments. To annotate **kwargs<\/code>, P.kwargs<\/code> must be used that represent the mapping of keyword parameters to their values.<\/p>\n\n\n\n
Instead of using the ellipsis literal, you may now utilise ParamSpec<\/code> and TypeVar<\/code> to enable callable objects to accept any number of positional or keyword arguments of any type.<\/p>\n\n\n\n
The code is further updated by adding **kwargs<\/code>, which allows the function to accept keyword arguments of arbitrary length.<\/p>\n\n\n\n
from collections.abc import Callable\nfrom typing import TypeVar, ParamSpec\n\nP = ParamSpec(\"P\")\nT = TypeVar(\"T\")\n\ndef apply_cart(\n        func: Callable[P, T],\n        *args: P.args,\n        **kwargs: P.kwargs\n) -> T:\n    return func(*args, **kwargs)\n\n\ndef cart(item: str, quantity: int) -> dict[str, int] | None:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}\n\ncart_item = apply_cart(cart, \"Mouse\", quantity=2)\nprint(cart_item)<\/pre><\/div>\n\n\n\n
Type Hinting Iterables<\/h2>\n\n\n\n
Consider the following function that takes a list of names and sorts them in ascending order.<\/p>\n\n\n\n
def sort_student(names: list[str]) -> None:\n    sorting = sorted(names)\n    for name in sorting:\n        print(name)\n\nn = [\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\"]\nsort_student(n)<\/pre><\/div>\n\n\n\n
The list[str]<\/code> type is used to type hint the parameter names<\/code> to indicate that it expects a list of strings.<\/p>\n\n\n\n
But what if you want names<\/code> to be a type tuple<\/strong> or set<\/strong> instead? You need to refactor your code. In this case, you need to change the type in one location, however, this might be hard in complex and big projects.<\/p>\n\n\n\n
You can use the type Iterable<\/code> to make the function accept any iterable object.<\/p>\n\n\n\n
from collections.abc import Iterable\n\ndef sort_student(names: Iterable[str]) -> None:\n    sorting = sorted(names)\n    for name in sorting:\n        print(name)\n\nn1 = (\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\") # No error\nn2 = [\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\"] # No error\nn3 = {\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\"} # No error<\/pre><\/div>\n\n\n\n
Type Aliases for Better Readability<\/h2>\n\n\n\n
The complex type hints for callable objects like in the above case, arguments, and return values of the functions kind of feel cumbersome to write.<\/p>\n\n\n\n
Why can’t simplify the complex type by giving them an alias<\/strong>(name)? You can create an alias for the type in the same way you would create a variable.<\/p>\n\n\n\n
type ReturnCart = dict[str, int] | None\n\ndef cart(item: str, quantity: int) -> ReturnCart:\n    if item == \"\" or quantity == 0:\n        return None\n    return {item: quantity}\n\ncart_item = apply_cart(cart, \"Mouse\", quantity=2)\nprint(cart_item)<\/pre><\/div>\n\n\n\n
In the above example, an alias ReturnCart<\/code> is created and contains the type of return value (dict[str, int] | None<\/code>).<\/p>\n\n\n\n
The alias is defined with the soft keyword<\/a> type<\/code><\/a>, which creates an instance of TypeAliasType<\/code><\/a>. This keyword was added in Python 3.12. If you are using an older version of Python, you can choose an alternate method.<\/p>\n\n\n\n
Type aliases can also be created like you would create a variable using a simple assignment.<\/p>\n\n\n\n
ReturnCart = dict[str, int] | None<\/pre><\/div>\n\n\n\n
To clarify, you can mark it with TypeAlias<\/code> to explicitly show this as a type alias, not a simple variable.<\/p>\n\n\n\n
from typing import TypeAlias\n\nReturnCart: TypeAlias = dict[str, int] | None<\/pre><\/div>\n\n\n\n
The methods described above will assist you in simplifying complex types, and the key benefit is that you will only need to edit the type in one spot, eliminating the need for refactoring.<\/p>\n\n\n\n
Another advantage of using type aliases is that they can be reused in other portions of your code, which improves code readability.<\/p>\n\n\n\n
Type Checker Tools<\/h2>\n\n\n\n
Python entirely ignores type hints and determines the type of variables, function arguments, and return values at runtime.<\/p>\n\n\n\n
Mypy<\/a>, a popular third-party tool, can enforce type-checking in Python. Since it is a third-party tool, you must install it using the following command.<\/p>\n\n\n\n
python -m pip install mypy<\/pre><\/div>\n\n\n\n
This will provide you access to the mypy<\/code> command to type-check your program.<\/p>\n\n\n\n
Static Type Checking Using Mypy<\/h3>\n\n\n\n
The function sort_student()<\/code> takes an iterable object and sorts the student names in ascending order. Save this function to a file, such as student.py<\/code>.<\/p>\n\n\n\n
# student.py\nfrom collections.abc import Iterable\n\ndef sort_student(names: Iterable[str]) -> None:\n    sorting = sorted(names)\n    for name in sorting:\n        print(name)\n\nn1 = (\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\")\nsort_student(n1)<\/pre><\/div>\n\n\n\n
To type check your program using mypy<\/code>, enter the command mypy<\/code> followed by the file name you want to check in the terminal.<\/p>\n\n\n\n
> mypy student.py \nSuccess: no issues found in 1 source file<\/pre><\/div>\n\n\n\n
The type checker identified no errors. One thing you may have noticed is that the code contains the function call (sort_student(n1)<\/code>), which should have created the output, but there was none in the terminal except the message created by mypy<\/code>.<\/p>\n\n\n\n
This means that mypy<\/code> does not execute your code, instead, it examines if the values match the expected type based on the type hints.<\/p>\n\n\n\n
What if you made a mistake and the actual values do not match the expected type?<\/p>\n\n\n\n
# student.py\ndef sort_student(names: list[str]) -> None:\n    sorting = sorted(names)\n    for name in sorting:\n        print(name)\n\nn1 = (\"Gojo\", \"Yuta\", \"Yuji\", \"Megumi\")\nsort_student(n1)<\/pre><\/div>\n\n\n\n
This function expects a list of strings but the tuple was passed. If you now check your code, it will generate the following error.<\/p>\n\n\n\n
> mypy student.py\nstudent.py:8: error: Argument 1 to \"sort_student\" has incompatible type \"tuple[str, str, str, str]\"; expected \"list[str]\"  [arg-type]\nFound 1 error in 1 file (checked 1 source file)<\/pre><\/div>\n\n\n\n
Mypy has identified the error on line number 8 saying that the argument passed to sort_student()<\/code> has an incompatible type tuple[str, str, str, str]<\/code>, it is expected to be a list[str]<\/code>.<\/p>\n\n\n\n
Resources<\/h2>\n\n\n\n