403

How do I use type hints to annotate a function that returns an Iterable that always yields two values: a bool and a str? The hint Tuple[bool, str] is close, except that it limits the return value type to a tuple, not a generator or other type of iterable.

I'm mostly curious because I would like to annotate a function foo() that is used to return multiple values like this:

always_a_bool, always_a_str = foo()

Usually functions like foo() do something like return a, b (which returns a tuple), but I would like the type hint to be flexible enough to replace the returned tuple with a generator or list or something else.

3

1 Answer 1

559

You are always returning one object; using return one, two simply returns a tuple.

So yes, -> Tuple[bool, str] is entirely correct.

Only the Tuple type lets you specify a fixed number of elements, each with a distinct type. You really should be returning a tuple, always, if your function produces a fixed number of return values, especially when those values are specific, distinct types.

Other sequence types are expected to have one type specification for a variable number of elements, so typing.Sequence is not suitable here. Also see What's the difference between lists and tuples?

Tuples are heterogeneous data structures (i.e., their entries have different meanings), while lists are homogeneous sequences. Tuples have structure, lists have order.

Python's type hint system adheres to that philosophy, there is currently no syntax to specify an iterable of fixed length and containing specific types at specific positions.

If you must specify that any iterable will do, then the best you can do is:

-> Iterable[Union[bool, str]]

at which point the caller can expect booleans and strings in any order, and of unknown length (anywhere between 0 and infinity).

Last but not least, as of Python 3.9, you can use

-> tuple[bool, str]

instead of -> Tuple[bool, str]; support for type hinting notation has been added to most standard-library container types (see PEP 585 for the complete list). In fact, you can use this as of Python 3.7 too provided you use the from __future__ import annotations compiler switch for your modules and a type checker that supports the syntax.

15
  • 5
    The language specification allows returning other iterables; foo() could do yield True; yield "blah" and a, b = foo() would still work. Or foo() could return a list. I reworded my question to make it clear that I'm interested in hinting an arbitrary iterable, not a tuple. Commented Oct 21, 2016 at 16:46
  • 2
    @RichardHansen: that may well be, but type hinting only provides you with Tuple to express a heterogenous, fixed length return value. Commented Oct 21, 2016 at 16:51
  • 5
    "What you want is not possible" is a good answer, assuming it's correct. :) Commented Oct 21, 2016 at 17:02
  • 4
    @RichardHansen: I've re-checked the PEPs and documentation of typing and mypy another 2 times since posting; I'm pretty confident I didn't miss anything. That said, there are several regulars here on SO with plenty of Python type hinting experience that won't hesitate to correct me if turn out to be wrong, or will post a better answer. Commented Oct 21, 2016 at 17:06
  • 5
    In order to run this code in python 3.8 you may have to add from typing import Tuple, List
    – Joel
    Commented Sep 8, 2021 at 7:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.