Is there any interest in having a Github badge for libraries to advertise that they have types?
The last time something like this was proposed there were a lot of questions around how to measure coverage. To avoid this issue, perhaps we could start with a simpler badge that just marks whether something has inline types (self-declared with py.typed), a stubs package, or typeshed. Since those are yes/no questions it should be easy to check for.
Something like this:
Typeshed:
Optionally, we could leverage the coverage figures from typeshed-stats like so:
Inline:
Stubs package:
I think it would be a fairly minor addition, but it might help promote typing and make the presence/location of a package’s type information more obvious instead of scattered in a few different places.
I believe badges can link somewhere, so maybe we could make them link to a new page under typing.readthedocs.io that explains what the badges mean and how to pick the badge to use for your package.
I don’t like the idea. There’s already a trove classifier[1] for typed libraries, and contributors should be noticing the tooling in use in projects they contribute to.
I think placing this here while there are still far too many things that aren’t properly expressible within the type system is just going to turn into people arguing about who should and shouldn’t be using the badge, even in cases that are through no fault of the library author, and may result in people writing type hints that aren’t accurate just to get the number to go up. (If you make things a metric…)
I also think that using Any in cases like that is actually correct, but some people treat Any as evil, rather than as necessary for the idea of gradual typing to even work, and go out of their way to avoid use of it to the point of rewriting working code in less obvious, and sometimes, just worse ways.
For typeshed-stats specifically (since it was mentioned above), FWIW I already list the number of Any and Incomplete parameters/returns separately, so you can fairly easily figure out what percentage of annotated parameters in a package are annotated with Any or Incomplete. E.g. Stats on typeshed's stubs - typeshed-stats. It’s obviously not perfect since there are many cases where it’s valid to annotate a parameter with Any, but if a very high percentage of the parameters in a package are annotated with Any, it’s pretty easy to see from the stats that the annotations in that package might need some work
To prevent concerns with gaming the numbers, maybe we could just stick with a badge that shows whether type information exists and where it lives. It might also be useful to display this information directly on pypi.
Typeshed:
Inline:
Stubs package:
I guess the inline types badge can also be “gamed” by putting a py.typed file without actually having type annotations, but nothing prevents people from doing that today.
It’s very basic and just checks for the “Typing :: Typed” trove classifier on Pypi.
I’m not sure whether providing a py.typed file is a requirement for the classifier, or if it’s entirely independent. If there’s a significant number of packages with py.typed that don’t have this classifier, maybe we can find a way to automatically add the classifier to improve its accuracy.
I thought about signaling the presence of standalone stubs or typeshed packages by searching for types-* or *-stubs modifications of the package name, but I’m worried about the names being occupied by unmaintainer/unofficial stubs or malicious name-squatting. Based on a cursory search of github issues and docs, it doesn’t seem like those namespaces are restricted or reserved to typeshed (yet?).
That’s correct, PyPI does not currently have a notion of namespaces and anyone may make types-* or *-stubs packages. mypy deals with this by having a list of stubs packages it trusts mypy/mypy/stubinfo.py at master · python/mypy · GitHub (in practice, these are either typeshed packages or stubs packages verifiably provided by people involved in the development of the upstream package)
There are a few different ways: @lolpack and I wrote our own script for ad-hoc analyses, mypy/pyright/pyre all generate type coverage metrics/reports, and Alex tracks coverage for typeshed stubs on typeshed-stats (linked in an earlier reply)
Since we don’t all agree on what metric to use, I figured it would be better to at least have a yes/no badge first.
I crunched some numbers to see how accurate the trove classifiers for typing are:
Typing :: Typed
From the top 2k packages on Pypi, 138 have the classifier and are eligible for the badge (~7%).
11 of those packages don’t have py.typed or separate stubs via typeshed or another package
Of the remaining packages that aren’t eligible for the badge:
1101 don’t have py.typed or stubs, so they are probably untyped
688 have py.typed, so in theory they should have the classifier added
the rest either have stubs somewhere or are stubs packages themselves
Typing :: Stubs Only
There are 42 packages with the classifier in the top 2k packages.
Of those, 13 do not follow the types-* or *-stubs naming convention. (I know it’s not required to name it like that, I just wanted to see how ubiquitous the convention was)
There are 3 packages without the classifier that do follow the naming convention - the classifier could potentially be added to those packages
The repo is archived, and issues aren’t enabled, so I’ll post it here:
I’m getting a KeyError: 'non_typeshed_stubs' when running python main.py --package-name scipy-stubs with python==3.13.1. Any idea what I’m doing wrong?
I’d be surprised if just using the badges in a few high profile places isn’t enough for them to go viral organically. People seem to obsessively hoard badges for reasons I don’t understand. [1]
