Missing type annotations


I’m going through Python track right now and noticed that types for arguments and return values are written in the docstrings instead of a proper Python type annotation.

What is the rationale behind this decision?

Best Regards,
Kirill Morozov.

See [Feature Request] [Python] Include the most important modules as concepts in the syllabus - #6 by BethanyG

See [Log-levels]: Add Formal Docstrings to exemplar.py and stub files · Issue #2642 · exercism/python · GitHub

Type annotations are not checked by Python. The language allows you to add annotations but Python itself doesn’t do any enforcements so they aren’t “part” of the language in many respects. They aren’t checked by the test runner. They don’t have any impact on the exercise solution and tests. They’re also not a beginner topic. As such, they are intentionally not included in the exercises.

Yeah, but type information is still included into every(almost) docstring so I though it might be a good idea to do it properly so students can get a glimpse of how modern python code looks like and later when there will be a Typing concept exercise for Python it won’t come as a surprise for them that Python had a nice syntax for type annotation all that time. And who knows maybe later Exercism team could switch on type checking as a part of automated feedback.

TL;DR: I though it would be a great addition to the Python track and if Exercism team is open for that I could volunteer to implement it.

Plenty of projects do types in docstrings. The current is correct, too.

This may or may not happen. If it does happen, there may be a decision to update other exercises with type annotations. Or not. The exercises often are meant to focus on specific topics. Enforcing or even introducing type annotations can distract from that. When the types are complicated or people aren’t familiar, they can over shadow the rest of the exercise in a way which takes away from what is supposed to be the focus.

Personally, I already use annotations. I think they are great. I often suggest people look into them as part of my mentoring sessions. Type annotations were previously discussed and considered. And a decision has been made. It might change in the future, but at the moment, that is the current decision.

Got it.

Thanks for the clarification, Isaac.

There is no one way of doing it ‘properly’. See Flatten Array in Python on Exercism for a relatively clear example.

Moreover, there are multiple, mutually incompatible type checkers in use. I don’t think we should go lightly about privileging one.

I’m curious: what do you find nice about Python’s annotations?

Never had this such need in a wild but it looks like for the flatten array you could do something like this:

T: TypeAlias = List[Union[int, "T"]]

Sorry, I though that typing module in the standard library is de facto standard way of doing annotation and is the one to privilege but it seems I’m not well informed in this topic.

They exist as part of the language syntax and I find it way nicer than type info in a docstring.

But you’d still need to use docstrings, right? How are you going to describe what the function does?


Arguably, it should be polymorphic instead of monomorphic over int. Last time I tried that (context) with mypy there was only fairly new and experimental support for such types.

However, such a polymorphic type would be a tad wrong: the type variable could be instantiated at a list type, in which case the type signature would be a lie. Maybe this can be prevented somehow; I don’t know.

Yes, typing is not the issue here. At the end of the day it is just a bunch of names. It is up to the type checker to give meaning to these names. Various type checkers use various, incompatible type systems.

I do not expect it to matter a lot, by the way. Most problems on the platform are rather tame, types-wise.

I found/find Python’s annotations annoyingly noisy, but now it seems that the following is allowed (by mypy), which seems like a significant improvement:

a: int
a = 5

Yes, exactly.

My only suggestion was to move type annotations from doctrings to the function signature. When I’ve started the python track I was so unused to unannoted code, some of the useful features of the modern language servers(which I’ve learnt to rely on) suddenly stopped working and I thought it is the area for improvement.

Today I showed a mentored student a snippet of code which contained a type annotated function signature and he sad he does not understand it. Now I get Isaac’s point but it could also be because he was not aware of this feature from the beginning. Perhaps if he had been shown only type annotated code from the start his perspective would be different.

Most the docstrings I write doesn’t list the function arguments. Their meaning is usually apparent from the function signature. More often than not, my docstrings are a single line.