I'm a huge fan of typing in Python. I wasn't aware about impact on performance but I think every library should use them. As far as I know, Python 3.4 is no longer maintained so we can drop support for it.
I don't use mypy - I only rely on support in IDE but results are really great, especially in bigger projects.

I think it's a must-have feature for semver 3.0.0 :)

Thanks Karol for your feedback! 👍

The performance depends probably on how difficult the types are and how big the library is. I've read somewhere an article about it. If I remember correctly, the performance penalty isn't big, but measurable.

If we use that, I would suggest to add mypy as an additional check besides black/flake8/docstrings.

I'm just acclimating myself to static typing now and mypy is currently complaining that semver has to typing info.

To minimize the amount of overhead involved in this, it's worth noting there are several ways to get the typing info, among which are:

• Adding type hints to semver
• Creating a complimentary package for type hinting, semver-stubs or somesuch
• Adding type hints to the third-party section of python/typeshed

Anyway I'm really eager to see this added into semver 3 and am rooting for you all the way! 👏

@jwarner112 Many thanks Jeff for your motivating comment and your useful hints. 👍

Do you have any recommendations which of the two (semver-stubs or typeshed) are useful?

I vaguely recall that a stubs package is easier to create than adding the information to typeshed. If I remember correctly, you have more control when creating a stubs package than adding your changes to typeshed (and waiting to be integrated).

Probably my information is incomplete or inaccurate. If you have any hints or tips which could be helpful for this project, I would be very grateful for your help.

I can't say for sure which is better, but I can definitely say that having your own -stubs package would be easier for you due to the control it gives you. With added responsibility, of course 🕷️. I'd probably recommend that, given your situation. I get the idea that typeshed is more for packages that are third-party but so popular/close to the core team that it might be considered second party? Not formally, of course, but in practice.

Edit: As for the implementation of typing stubs themselves, I have absolutely no idea. If my work comes across it though and I have to figure it out, I'll remember to come back here and update.

I'm having trouble finding evidence that type hints have any non-trivial runtime performance penalty.

The best argument I can find is that importing the typing module increases startup time, which is technically true, but can also be said of code comments, longer descriptive identifier names, or organizing semver into a package.

Adding to @jwarner112 's list of alternatives: you can also put type stubs in a separate *.pyi file in semver, next to the *.py files; no -stubs package is necessary. I think this approach may force you to make semver a package, but I'm not sure.

Anecdotally, I find *.pyi files to be a nice concise reference. I often refer to the *.pyi files in typeshed rather than read the standard library documentation.

I'm having trouble finding evidence that type hints have any non-trivial runtime performance penalty.

I've read it somewhere, but can't remember where I've found it. It wasn't much, but it was just a tiny overhead.

ATM I'm working on the 3.0.0 release and I'm publishing the first alpha version soon. Maybe I can add the type hints in one of the next alphas or betas.

I've created tomschr#6 with type hints directly in the code. Do you think I should move them to a *.pyi file instead?

I don't have much experience with type hints yet. From what I've seen, I think a *.pyi file would be worth. So yes, if this is not too much work, please go ahead! 👍

The two main functional uses of *.pyi files are

1. type hinting a c extension
2. type hinting python code targeted for python <3.5

For python <3.5 support, you can also add type hints via inline # type: ... comments, but in practice I don't find these to be very readable.

Not sure which python versions you intend to support in semver 3. But strictly speaking, if you only want to support non-EOL python versions (>=3.6), you don't need a *.pyi file, and could just have type hints inline in the code. Personally, I find inline type hints improve readability.

Thanks @sbrudenell for your input. 👍 We currently would like to support Python >=3.6.

I was under the impression, the *.pyi files are also used for IDEs and editors as type annotations? This would have the benefit that IDEs/editors don't have to parse the complete file. Or am I completely wrong?

Well on pycharm, the inline types are parsed quite well, and it also tries its best to infer type of other parts in the code. I agree with @sbrudenell on the fact that having them inline makes the code more readable, so if you have a more basic editor that doesn't read any type hints, having to open the *.pyi alongside it would be much less ergonomic.

Ok, I had to edit my own comment. I have overlooked some of the comments.

So it seems we don't need a .pyi file. As we don't support Python <3.6, this is probably not necessary.

As Thomas Laferriere already added type hints into #290, I think we can consider this as done now.
Thanks Thomas for all your work! Much appreciated! 👍

Inline type hints LGTM. Just to clarify:

I was under the impression, the *.pyi files are also used for IDEs and editors as type annotations? This would have the benefit that IDEs/editors don't have to parse the complete file. Or am I completely wrong?

*.pyi files are just an alternate delivery mechanism for hints; they should be equivalent to inline hints and editors/etc should treat them so. They also support full python syntax so I don't expect there's a speed benefit for a parser to visit a *.pyi versus a *.py.

I probably caused too much confusion by bringing up *.pyi files at all. I think inline hints are best, but I expected the authors to disagree, so I prematurely offered a compromise.