Returning Data of Alternative Types

00:00 Returning Data of Alternative Types In this part of the course, you’ll see how to write type hints for functions that return data of different types. First, you’ll see how to do this when there is a single piece of data, and later on, how to do this when there are multiple return values.

00:17 You’ll sometimes find situations when a function will return one piece of data that could be of different types. The scenarios for considering multiple return types include: Conditional Statements.

00:28 When a function uses conditional statements that return different types of results, you can convey this by specifying the alternative return types for your function using type hints. Optional Values.

00:39 A function may sometimes return no value, in which case you can use type hints to signal the occasional absence of a return value. Error Handling. When a function encounters an error, you may want to return a specific error object that’s different from the normal results return type.

00:55 Doing so can make it easier for other developers to handle errors in the code. Flexibility. When designing and writing code, you generally want it to be versatile, flexible, and reusable.

01:07 This could mean writing functions that can handle a range of data types. Specifying this in type hints helps other developers understand your code’s versatility and its intended different use cases.

01:19 A practical situation is often the best way to illustrate a concept. Imagine that you are processing customer data and want to write a function to parse users’ email addresses, to extract their usernames. To represent one piece of data of multiple type using type hints in Python 3.10 or newer, you can use the pipe operator.

01:39 Here’s how you’d use type hints in a function that typically returns a string containing the username, but can also return None if the corresponding email address is incomplete.

01:52 In this example, the parse_email function has a conditional statement that checks if the email address parsed as an argument contains the @ sign.

02:00 If it does, then the function splits on that symbol to extract the elements before and after the @ sign, stores them in local variables and returns the username.

02:09 If the argument doesn’t contain an @ sign, then the return value is None, indicating an invalid email address.

02:17 In practice, the validation rules for email addresses are much more complicated than this, but this function has been left simple to concentrate on the return values.

02:26 The return value of this function is either a string containing a username or None if the email address is incomplete. The type hint for the return value uses the pipe operator to indicate alternative types of the single value that the function returns.

02:41 But Python versions older than 3.10 don’t have this syntax, but you can still do it with the code seen on screen.

02:54 This function uses the Union type from the typing module to indicate that parse_email returns either a string or None, depending on the input value.

03:03 Whether you use the old or new syntax, a Union type hint can combine more than two data types.

03:12 Even when using a modern Python release, you may still prefer the Union type over the pipe operator if your code needs to run in older Python versions.

03:21 One challenge with functions that may return different types is that you need to check the return type when you call the function. In the code you’ve just seen, you’d need to test whether you’ve got None or a username when calling the function. You now know how to define a function that returns a single value of potentially different types.

03:39 But what about when your function needs to return multiple values? Fortunately, Python has you covered using type hints for this as well. You can use a tuple to indicate the types of the individual pieces of data that a function returns at once.

03:53 In Python 3.9 and later, you can use the built-in tuple data structure. On older versions, you’ll need to use typing.Tuple in your annotations.

04:03 Now, consider the situation where you want to build on the previous example. You want to declare a function whose return value incorporates multiple pieces of data of various types.

04:14 In addition to returning the username obtained from the email address, you want to update the function to return the domain as well.

04:22 Here’s how you’d use type hints to indicate that the function returns a tuple with a string for the username and another string for the domain.

04:33 The function’s return type is a pair of two strings that correspond to the username and domain of the email address. Alternatively, if the input value doesn’t constitute a valid email address, then the function returns None.

04:45 The type hint for the return value contains a tuple with two comma-separated string elements inside square brackets, which tells you that the tuple has exactly two elements and they’re both strings.

04:56 Then a pipe operator followed by None indicates that the return value could be either a two-string tuple, or None depending on the input value.

05:05 To implement the same function in Python earlier than 3.10, you can use the Tuple and Union types from the typing module.

05:23 This notation is slightly more verbose and requires importing two additional types from the typing module, but on the upside, you can use it in older Python versions.

05:33 As with alternative types in a Union, you can have an arbitrary number of elements and types in a tuple to combine multiple pieces of data in a type hint.

05:42 You can see an example of this on screen. Here, the function returns three values. One is a string, the next is an integer, and the third is a Boolean value.

05:54 So now you’ve seen how to use type hints for single and multiple return values of different types. In the next section of the course, you’ll look at using type hints when declaring functions to take callbacks.