Expand type hints across projects

[jaraco]

I received this inquiry in discord:

i want to put some effort into an initiative of filling jaraco.* and related projects with full-fledged type hints. would you mind helping me by providing a short list of the most important projects that i should focus on in the first place? thanks in advance! my intention is to make those projects play nicely with mypy, because i find them very useful, but i also value fully typed code.

[jaraco]

I'm happy to accept contributions! I tried to find a popularity ranking of all Python packages, but I didn't succeed. I did find snyk Advisor provides a quick and easy way to find packages by first letter (https://snyk.io/advisor/packages/python/j). You could go through the list of packages there and look at the popularity of each. It also sounds as if the pypi downloads tables are available to be queried (https://pypistats.org/api/#etiquette), so you could probably construct a query to do that. You might also search Github for projects with the skeleton badge - that's a pretty good indicator that it's following my best practices.

Tips

• These projects do already run mypy checks, so are nominally typed (at least as far as mypy can infer types). Running tox will cause the type checks to be run via pytest-mypy. Running tox -- -k mypy will run mainly just the mypy tests.
• Avoid changing the implementation (in theory, hints should reflect the current, desired behavior and not require restructuring of the implementation); change the implementation only if mypy is revealing a legitimate flaw (and even then, it's better to contribute the fix in a separate commit or PR).
• I don't subscribe to email notifications on my github projects (because I'm too busy to get to them in a timely fashion), so you'll need to be patient. If you need my attention for something urgent (you're blocked or you've waited a while), it's okay to mention me to get my attention.
• I'm not a fan of type hinting noise (e.g. -> None for two-line private methods with no return). Try to focus on adding type hints that add value - that communicate something additional and non-obvious. I won't reject a PR based on this condition, but it'll be more easily accepted if it's clearly adding value and not lint.

[bswck]

I am used to type checking my code with mypy in strict mode. While some may see the strict mode as too aggressive, I will have no problem adjusting a bigger codebase to pass strict type checking. This is what I had in mind during writing the message.

I'm not a fan of type hinting noise (e.g. -> None for two-line private methods with no return). Try to focus on adding type hints that add value - that communicate something additional and non-obvious. I won't reject a PR based on this condition, but it'll be more easily accepted if it's clearly adding value and not lint.

mypy disallows untyped definitions in the strict mode. A private function without the return statement is still assumed to return Any, which is untrue, since None is the desired return type:

class Foo:
    def _bar(self):  # seen by mypy as untyped
        pass

reveal_type(Foo()._bar())  # Revealed type is "Any"

class Spam:
    def _eggs(self, biz: int):  # seen as typed, return assumed to be Any
        pass

reveal_type(Spam()._eggs(5))  # Revealed type is "Any"

[!Note] The only exceptions from the behavior above are __init__ and __init_subclass__ methods where -> None can be omitted, provided the function has at least one type hint in the signature.

Relevant resources:

• https://github.com/python/mypy/issues/604,
• mypy docs: Annotating __init__ methods.

While no presence of the return statement in a method may be an obvious sign that the return type of that method does not matter, which is a logical reason not to leave a type hint there, even a return None statement with an unequivocal implication of the None return type is still seen as Any by mypy:

class Example:
    def _com(self, port: int):
        return None

reveal_type(Example()._com(43))  # Revealed type is "Any"

In places where the value of such a method is being used, the type hinting noise is then simply necessary to inform mypy about the actual return type that affects other scopes of the codebase.

I firmly believe that the best option would be being as explicit as possible when annotating types, because, as it seems, there are too few obvious cases at the end of the day.

The Zen of Python, by Tim Peters:

Beautiful is better than ugly. Explicit is better than implicit.

_{Note: The examples were tested on mypy 1.7.0.}

[bswck]

I'm happy to accept contributions! I tried to find a popularity ranking of all Python packages, but I didn't succeed. I did find snyk Advisor provides a quick and easy way to find packages by first letter (snyk.io/advisor/packages/python/j). You could go through the list of packages there and look at the popularity of each. It also sounds as if the pypi downloads tables are available to be queried (pypistats.org/api/#etiquette), so you could probably construct a query to do that. You might also search Github for projects with the skeleton badge - that's a pretty good indicator that it's following my best practices.

Thank you for your time spent on the research. I will use these resources and compile a TO-DO list of the projects to work on in this issue. Every subsequent PR will reference this issue.

[bswck]

I firmly believe that the best option would be being as explicit as possible when annotating types, because, as it seems, there are too few obvious cases at the end of the day.

Of course if the new type hints would appear too intricate for the eye, which I can totally understand, there is always an option of creating stubs to isolate two worlds of the implementation and the type hints, like in https://github.com/jaraco/jaraco.functools/pull/22. What are your thoughts on this @jaraco?

[bswck]

The roadmap is ready! 🎉

I wrote a script that extracted all jaraco projects from PyPI and sorted them by the total of downloads in the last month. The last two projects—Distutils and backports—have 0 downloads only because checking pypi stats on them causes an HTTP 404 error. I don't think inspecting that issue is necessary.

[!Note] Skeleton badges come from the PyPI latest releases, not the projects' repositories. As a result, these badges are valid indicators of the years all the relevant latest PyPI releases took place.

The script produced the following table:

| | downloads last month | jaraco's role | uses skeleton? | |:------------------------------------------------------------------------------------------------------------|-----------------------:|:----------------|:----------------------------------------------------------------------| | [setuptools](https://pypi.org/project/setuptools) | 322655647 | Owner |  | | [importlib-metadata](https://pypi.org/project/importlib-metadata) | 180078405 | Owner |  | | [zipp](https://pypi.org/project/zipp) | 162258510 | Owner |  | | [importlib-resources](https://pypi.org/project/importlib-resources) | 65910632 | Owner |  | | [keyring](https://pypi.org/project/keyring) | 40286684 | Owner |  | | [jaraco.classes](https://pypi.org/project/jaraco.classes) | 37033262 | Owner |  | | [setuptools-scm](https://pypi.org/project/setuptools-scm) | 25467595 | Owner | ❌ | | [pytest-runner](https://pypi.org/project/pytest-runner) | 16293153 | Owner |  | | [configparser](https://pypi.org/project/configparser) | 10187739 | Owner |  | | [jsonpickle](https://pypi.org/project/jsonpickle) | 9339847 | Owner | ❌ | | [pep517](https://pypi.org/project/pep517) | 6590096 | Owner | ❌ | | [inflect](https://pypi.org/project/inflect) | 4843645 | Maintainer |  | | [twine](https://pypi.org/project/twine) | 3678588 | Owner | ❌ | | [backports.functools-lru-cache](https://pypi.org/project/backports.functools-lru-cache) | 2285253 | Owner |  | | [singledispatch](https://pypi.org/project/singledispatch) | 2269372 | Owner |  | | [comtypes](https://pypi.org/project/comtypes) | 1732642 | Owner | ❌ | | [cssutils](https://pypi.org/project/cssutils) | 1668764 | Owner |  | | [jaraco.functools](https://pypi.org/project/jaraco.functools) | 1623127 | Owner |  | | [path](https://pypi.org/project/path) | 1583434 | Owner |  | | [cheroot](https://pypi.org/project/cheroot) | 1482151 | Owner | ❌ | | [tempora](https://pypi.org/project/tempora) | 890592 | Owner |  | | [portend](https://pypi.org/project/portend) | 829890 | Owner |  | | [jaraco.collections](https://pypi.org/project/jaraco.collections) | 795281 | Owner |  | | [CherryPy](https://pypi.org/project/CherryPy) | 790657 | Owner | ❌ | | [distribute](https://pypi.org/project/distribute) | 741920 | Owner | ❌ | | [jaraco.text](https://pypi.org/project/jaraco.text) | 739296 | Owner |  | | [jaraco.context](https://pypi.org/project/jaraco.context) | 733410 | Owner |  | | [keyrings.alt](https://pypi.org/project/keyrings.alt) | 614293 | Owner |  | | [backports.entry-points-selectable](https://pypi.org/project/backports.entry-points-selectable) | 564770 | Owner |  | | [path.py](https://pypi.org/project/path.py) | 333772 | Owner | ❌ | | [Tempita](https://pypi.org/project/Tempita) | 202581 | Maintainer | ❌ | | [Fuzzy](https://pypi.org/project/Fuzzy) | 120698 | Owner | ❌ | | [datadiff](https://pypi.org/project/datadiff) | 117694 | Owner | ❌ | | [wolframalpha](https://pypi.org/project/wolframalpha) | 51502 | Owner | ❌ | | [oathtool](https://pypi.org/project/oathtool) | 34623 | Owner |  | | [jaraco.logging](https://pypi.org/project/jaraco.logging) | 27595 | Owner |  | | [irc](https://pypi.org/project/irc) | 22739 | Owner |  | | [cherrypy-cors](https://pypi.org/project/cherrypy-cors) | 18930 | Owner |  | | [jaraco.stream](https://pypi.org/project/jaraco.stream) | 18120 | Owner |  | | [pytest-checkdocs](https://pypi.org/project/pytest-checkdocs) | 14617 | Owner |  | | [pytest-enabler](https://pypi.org/project/pytest-enabler) | 14499 | Owner |  | | [pip-run](https://pypi.org/project/pip-run) | 10838 | Owner |  | | [jaraco.env](https://pypi.org/project/jaraco.env) | 9083 | Owner |  | | [jaraco.itertools](https://pypi.org/project/jaraco.itertools) | 8260 | Owner |  | | [hgtools](https://pypi.org/project/hgtools) | 7996 | Owner | ❌ | | [pytest-ignore-flaky](https://pypi.org/project/pytest-ignore-flaky) | 7441 | Maintainer | ❌ | | [jaraco.path](https://pypi.org/project/jaraco.path) | 7331 | Owner |  | | [jaraco.envs](https://pypi.org/project/jaraco.envs) | 6930 | Owner |  | | [backports.datetime-timestamp](https://pypi.org/project/backports.datetime-timestamp) | 6897 | Owner |  | | [jaraco.versioning](https://pypi.org/project/jaraco.versioning) | 6230 | Owner |  | | [mongo-connector](https://pypi.org/project/mongo-connector) | 5814 | Owner | ❌ | | [pytest-perf](https://pypi.org/project/pytest-perf) | 5729 | Owner |  | | [jaraco.ui](https://pypi.org/project/jaraco.ui) | 5272 | Owner | ❌ | | [jaraco.packaging](https://pypi.org/project/jaraco.packaging) | 4884 | Owner |  | | [jaraco.develop](https://pypi.org/project/jaraco.develop) | 4502 | Owner |  | | [jaraco.structures](https://pypi.org/project/jaraco.structures) | 4416 | Owner |  | | [pytest-services](https://pypi.org/project/pytest-services) | 4205 | Maintainer | ❌ | | [rst.linker](https://pypi.org/project/rst.linker) | 3714 | Owner |  | | [jaraco.windows](https://pypi.org/project/jaraco.windows) | 3706 | Owner |  | | [jaraco.vcs](https://pypi.org/project/jaraco.vcs) | 3633 | Owner |  | | [backports.unittest-mock](https://pypi.org/project/backports.unittest-mock) | 3263 | Owner |  | | [jaraco.docker](https://pypi.org/project/jaraco.docker) | 2477 | Owner |  | | [suds-bis](https://pypi.org/project/suds-bis) | 2094 | Owner |  | | [jaraco.abode](https://pypi.org/project/jaraco.abode) | 1941 | Owner |  | | [jaraco.email](https://pypi.org/project/jaraco.email) | 1704 | Owner | ❌ | | [jaraco.net](https://pypi.org/project/jaraco.net) | 1697 | Owner |  | | [MagicBus](https://pypi.org/project/MagicBus) | 1478 | Owner | ❌ | | [svg.charts](https://pypi.org/project/svg.charts) | 1416 | Owner |  | | [jaraco.mongodb](https://pypi.org/project/jaraco.mongodb) | 1336 | Owner |  | | [calendra](https://pypi.org/project/calendra) | 1242 | Owner |  | | [jaraco.services](https://pypi.org/project/jaraco.services) | 768 | Owner |  | | [pmxbot](https://pypi.org/project/pmxbot) | 740 | Owner |  | | [jaraco.tidelift](https://pypi.org/project/jaraco.tidelift) | 718 | Owner |  | | [event](https://pypi.org/project/event) | 673 | Owner | ❌ | | [jaraco.clipboard](https://pypi.org/project/jaraco.clipboard) | 560 | Owner | ❌ | | [openpack](https://pypi.org/project/openpack) | 526 | Owner |  | | [elastic2-doc-manager](https://pypi.org/project/elastic2-doc-manager) | 504 | Owner | ❌ | | [jaraco.test](https://pypi.org/project/jaraco.test) | 499 | Owner |  | | [jaraco.pmxbot](https://pypi.org/project/jaraco.pmxbot) | 439 | Owner |  | | [dynpool](https://pypi.org/project/dynpool) | 312 | Owner | ❌ | | [pytest-black-multipy](https://pypi.org/project/pytest-black-multipy) | 307 | Owner | ❌ | | [cherrypy-dynpool](https://pypi.org/project/cherrypy-dynpool) | 307 | Owner | ❌ | | [jaraco.modb](https://pypi.org/project/jaraco.modb) | 269 | Owner |  | | [yg.lockfile](https://pypi.org/project/yg.lockfile) | 239 | Owner | ❌ | | [chucknorris](https://pypi.org/project/chucknorris) | 236 | Owner |  | | [nspektr](https://pypi.org/project/nspektr) | 225 | Owner |  | | [xlsxcessive](https://pypi.org/project/xlsxcessive) | 203 | Owner |  | | [cmdix](https://pypi.org/project/cmdix) | 189 | Owner |  | | [googlevoice](https://pypi.org/project/googlevoice) | 188 | Owner |  | | [jaraco.financial](https://pypi.org/project/jaraco.financial) | 175 | Owner |  | | [jaraco.timing](https://pypi.org/project/jaraco.timing) | 171 | Owner | ❌ | | [jaraco.postgres](https://pypi.org/project/jaraco.postgres) | 164 | Owner | ❌ | | [jaraco.compat](https://pypi.org/project/jaraco.compat) | 163 | Owner | ❌ | | [paradocx](https://pypi.org/project/paradocx) | 162 | Owner |  | | [http-okapi](https://pypi.org/project/http-okapi) | 142 | Owner | ❌ | | [jaraco.geo](https://pypi.org/project/jaraco.geo) | 137 | Owner |  | | [elastic-doc-manager](https://pypi.org/project/elastic-doc-manager) | 132 | Owner | ❌ | | [jaraco.util](https://pypi.org/project/jaraco.util) | 131 | Owner |  | | [compilers](https://pypi.org/project/compilers) | 129 | Owner | ❌ | | [jaraco.apt](https://pypi.org/project/jaraco.apt) | 122 | Owner | ❌ | | [setuptools-svn](https://pypi.org/project/setuptools-svn) | 103 | Owner | ❌ | | [jaraco.xonsh](https://pypi.org/project/jaraco.xonsh) | 98 | Owner |  | | [vr.cli](https://pypi.org/project/vr.cli) | 96 | Owner | ❌ | | [vr.runners](https://pypi.org/project/vr.runners) | 96 | Owner | ❌ | | [lpaste](https://pypi.org/project/lpaste) | 92 | Owner |  | | [rwt](https://pypi.org/project/rwt) | 92 | Owner | ❌ | | [jaraco.fabric](https://pypi.org/project/jaraco.fabric) | 83 | Owner |  | | [NAT-PMP](https://pypi.org/project/NAT-PMP) | 83 | Owner | ❌ | | [vr.common](https://pypi.org/project/vr.common) | 81 | Owner | ❌ | | [pytest-home](https://pypi.org/project/pytest-home) | 74 | Owner |  | | [fogbugz-bis](https://pypi.org/project/fogbugz-bis) | 68 | Owner |  | | [backports.hook-compressed](https://pypi.org/project/backports.hook-compressed) | 66 | Owner |  | | [jaraco.nxt](https://pypi.org/project/jaraco.nxt) | 61 | Owner |  | | [motivation](https://pypi.org/project/motivation) | 60 | Owner | ❌ | | [jaraco.video](https://pypi.org/project/jaraco.video) | 57 | Owner | ❌ | | [eggmonster](https://pypi.org/project/eggmonster) | 56 | Owner | ❌ | | [jaraco.site](https://pypi.org/project/jaraco.site) | 55 | Owner |  | | [vr.server](https://pypi.org/project/vr.server) | 53 | Owner | ❌ | | [vr.imager](https://pypi.org/project/vr.imager) | 51 | Owner | ❌ | | [backports.print_function](https://pypi.org/project/backports.print_function) | 49 | Owner | ❌ | | [librarypaste](https://pypi.org/project/librarypaste) | 47 | Owner |  | | [backports.method_request](https://pypi.org/project/backports.method_request) | 45 | Owner | ❌ | | [excuses](https://pypi.org/project/excuses) | 44 | Owner |  | | [jaraco.translate](https://pypi.org/project/jaraco.translate) | 43 | Owner | ❌ | | [backports.pdb](https://pypi.org/project/backports.pdb) | 43 | Owner |  | | [jaraco.media](https://pypi.org/project/jaraco.media) | 41 | Owner |  | | [jaraco.crypto](https://pypi.org/project/jaraco.crypto) | 39 | Owner |  | | [pmxbot.webhooks](https://pypi.org/project/pmxbot.webhooks) | 39 | Owner | ❌ | | [popquotes](https://pypi.org/project/popquotes) | 38 | Owner | ❌ | | [vr.builder](https://pypi.org/project/vr.builder) | 37 | Owner | ❌ | | [solr-doc-manager](https://pypi.org/project/solr-doc-manager) | 33 | Owner | ❌ | | [jaraco.input](https://pypi.org/project/jaraco.input) | 32 | Owner | ❌ | | [jaraco.home](https://pypi.org/project/jaraco.home) | 31 | Owner |  | | [jaraco.imaging](https://pypi.org/project/jaraco.imaging) | 30 | Owner | ❌ | | [vr.agent](https://pypi.org/project/vr.agent) | 29 | Owner | ❌ | | [jaraco.keyring](https://pypi.org/project/jaraco.keyring) | 28 | Owner | ❌ | | [vr.events](https://pypi.org/project/vr.events) | 28 | Owner | ❌ | | [pmxbot.rss](https://pypi.org/project/pmxbot.rss) | 28 | Owner | ❌ | | [jaraco.xkcd](https://pypi.org/project/jaraco.xkcd) | 27 | Owner | ❌ | | [jaraco.office](https://pypi.org/project/jaraco.office) | 26 | Owner | ❌ | | [freedompop](https://pypi.org/project/freedompop) | 26 | Owner | ❌ | | [treehouse](https://pypi.org/project/treehouse) | 26 | Owner | ❌ | | [dropbox-index](https://pypi.org/project/dropbox-index) | 26 | Owner |  | | [jaraco.zstd](https://pypi.org/project/jaraco.zstd) | 24 | Owner |  | | [recapturedocs](https://pypi.org/project/recapturedocs) | 24 | Owner |  | | [setuptools-hacks.bypass-summary-newline](https://pypi.org/project/setuptools-hacks.bypass-summary-newline) | 21 | Owner |  | | [pmxbot.nsfw](https://pypi.org/project/pmxbot.nsfw) | 20 | Owner | ❌ | | [vr.launch](https://pypi.org/project/vr.launch) | 18 | Owner | ❌ | | [pmxbot.saysomething](https://pypi.org/project/pmxbot.saysomething) | 13 | Owner | ❌ | | [jaraco.parables](https://pypi.org/project/jaraco.parables) | 11 | Owner | ❌ | | [yg.thumpy](https://pypi.org/project/yg.thumpy) | 11 | Owner | ❌ | | [yg.eventful](https://pypi.org/project/yg.eventful) | 7 | Owner | ❌ | | [Distutils](https://pypi.org/project/Distutils) | 0 | Owner | ❌ | | [backports](https://pypi.org/project/backports) | 0 | Owner | ❌ |

In order to make tracking the progress significantly easier, I've generated the following checklist-form roadmap.

# Roadmap **TODO for every project linked below**: - ensure a `py.typed` marker is present, - modernize type hinting, - ensure that `mypy --strict` passes successfully. ---- - [ ] [setuptools](https://pypi.org/project/setuptools) [](https://pepy.tech/projects/setuptools)  - [ ] [importlib-metadata](https://pypi.org/project/importlib-metadata) [](https://pepy.tech/projects/importlib-metadata)  - [ ] [zipp](https://pypi.org/project/zipp) [](https://pepy.tech/projects/zipp)  - [ ] [importlib-resources](https://pypi.org/project/importlib-resources) [](https://pepy.tech/projects/importlib-resources)  - [ ] [keyring](https://pypi.org/project/keyring) [](https://pepy.tech/projects/keyring)  - [ ] [jaraco.classes](https://pypi.org/project/jaraco.classes) [](https://pepy.tech/projects/jaraco.classes)  - [ ] [setuptools-scm](https://pypi.org/project/setuptools-scm) [](https://pepy.tech/projects/setuptools-scm) - [ ] [pytest-runner](https://pypi.org/project/pytest-runner) [](https://pepy.tech/projects/pytest-runner)  - [ ] [configparser](https://pypi.org/project/configparser) [](https://pepy.tech/projects/configparser)  - [ ] [jsonpickle](https://pypi.org/project/jsonpickle) [](https://pepy.tech/projects/jsonpickle) - [ ] [pep517](https://pypi.org/project/pep517) [](https://pepy.tech/projects/pep517) - [ ] [inflect](https://pypi.org/project/inflect) [](https://pepy.tech/projects/inflect)  - [ ] [twine](https://pypi.org/project/twine) [](https://pepy.tech/projects/twine) - [ ] [backports.functools-lru-cache](https://pypi.org/project/backports.functools-lru-cache) [](https://pepy.tech/projects/backports.functools-lru-cache)  - [ ] [singledispatch](https://pypi.org/project/singledispatch) [](https://pepy.tech/projects/singledispatch)  - [ ] [comtypes](https://pypi.org/project/comtypes) [](https://pepy.tech/projects/comtypes) - [ ] [cssutils](https://pypi.org/project/cssutils) [](https://pepy.tech/projects/cssutils)  - [x] [jaraco.functools](https://pypi.org/project/jaraco.functools) [](https://pepy.tech/projects/jaraco.functools)  - [ ] [path](https://pypi.org/project/path) [](https://pepy.tech/projects/path)  - [ ] [cheroot](https://pypi.org/project/cheroot) [](https://pepy.tech/projects/cheroot) - [ ] [tempora](https://pypi.org/project/tempora) [](https://pepy.tech/projects/tempora)  - [ ] [portend](https://pypi.org/project/portend) [](https://pepy.tech/projects/portend)  - [ ] [jaraco.collections](https://pypi.org/project/jaraco.collections) [](https://pepy.tech/projects/jaraco.collections)  - [ ] [CherryPy](https://pypi.org/project/CherryPy) [](https://pepy.tech/projects/CherryPy) - [ ] [distribute](https://pypi.org/project/distribute) [](https://pepy.tech/projects/distribute) - [ ] [jaraco.text](https://pypi.org/project/jaraco.text) [](https://pepy.tech/projects/jaraco.text)  - [ ] [jaraco.context](https://pypi.org/project/jaraco.context) [](https://pepy.tech/projects/jaraco.context)  - [ ] [keyrings.alt](https://pypi.org/project/keyrings.alt) [](https://pepy.tech/projects/keyrings.alt)  - [ ] [backports.entry-points-selectable](https://pypi.org/project/backports.entry-points-selectable) [](https://pepy.tech/projects/backports.entry-points-selectable)  - [ ] [path.py](https://pypi.org/project/path.py) [](https://pepy.tech/projects/path.py) - [ ] [Tempita](https://pypi.org/project/Tempita) [](https://pepy.tech/projects/Tempita) - [ ] [Fuzzy](https://pypi.org/project/Fuzzy) [](https://pepy.tech/projects/Fuzzy) - [ ] [datadiff](https://pypi.org/project/datadiff) [](https://pepy.tech/projects/datadiff) - [ ] [wolframalpha](https://pypi.org/project/wolframalpha) [](https://pepy.tech/projects/wolframalpha) - [ ] [oathtool](https://pypi.org/project/oathtool) [](https://pepy.tech/projects/oathtool)  - [ ] [jaraco.logging](https://pypi.org/project/jaraco.logging) [](https://pepy.tech/projects/jaraco.logging)  - [ ] [irc](https://pypi.org/project/irc) [](https://pepy.tech/projects/irc)  - [ ] [cherrypy-cors](https://pypi.org/project/cherrypy-cors) [](https://pepy.tech/projects/cherrypy-cors)  - [ ] [jaraco.stream](https://pypi.org/project/jaraco.stream) [](https://pepy.tech/projects/jaraco.stream)  - [ ] [pytest-checkdocs](https://pypi.org/project/pytest-checkdocs) [](https://pepy.tech/projects/pytest-checkdocs)  - [ ] [pytest-enabler](https://pypi.org/project/pytest-enabler) [](https://pepy.tech/projects/pytest-enabler)  - [ ] [pip-run](https://pypi.org/project/pip-run) [](https://pepy.tech/projects/pip-run)  - [ ] [jaraco.env](https://pypi.org/project/jaraco.env) [](https://pepy.tech/projects/jaraco.env)  - [ ] [jaraco.itertools](https://pypi.org/project/jaraco.itertools) [](https://pepy.tech/projects/jaraco.itertools)  - [ ] [hgtools](https://pypi.org/project/hgtools) [](https://pepy.tech/projects/hgtools) - [ ] [pytest-ignore-flaky](https://pypi.org/project/pytest-ignore-flaky) [](https://pepy.tech/projects/pytest-ignore-flaky) - [ ] [jaraco.path](https://pypi.org/project/jaraco.path) [](https://pepy.tech/projects/jaraco.path)  - [ ] [jaraco.envs](https://pypi.org/project/jaraco.envs) [](https://pepy.tech/projects/jaraco.envs)  - [ ] [backports.datetime-timestamp](https://pypi.org/project/backports.datetime-timestamp) [](https://pepy.tech/projects/backports.datetime-timestamp)  - [ ] [jaraco.versioning](https://pypi.org/project/jaraco.versioning) [](https://pepy.tech/projects/jaraco.versioning)  - [ ] [mongo-connector](https://pypi.org/project/mongo-connector) [](https://pepy.tech/projects/mongo-connector) - [ ] [pytest-perf](https://pypi.org/project/pytest-perf) [](https://pepy.tech/projects/pytest-perf)  - [ ] [jaraco.ui](https://pypi.org/project/jaraco.ui) [](https://pepy.tech/projects/jaraco.ui) - [ ] [jaraco.packaging](https://pypi.org/project/jaraco.packaging) [](https://pepy.tech/projects/jaraco.packaging)  - [ ] [jaraco.develop](https://pypi.org/project/jaraco.develop) [](https://pepy.tech/projects/jaraco.develop)  - [ ] [jaraco.structures](https://pypi.org/project/jaraco.structures) [](https://pepy.tech/projects/jaraco.structures)  - [ ] [pytest-services](https://pypi.org/project/pytest-services) [](https://pepy.tech/projects/pytest-services) - [ ] [rst.linker](https://pypi.org/project/rst.linker) [](https://pepy.tech/projects/rst.linker)  - [ ] [jaraco.windows](https://pypi.org/project/jaraco.windows) [](https://pepy.tech/projects/jaraco.windows)  - [ ] [jaraco.vcs](https://pypi.org/project/jaraco.vcs) [](https://pepy.tech/projects/jaraco.vcs)  - [ ] [backports.unittest-mock](https://pypi.org/project/backports.unittest-mock) [](https://pepy.tech/projects/backports.unittest-mock)  - [ ] [jaraco.docker](https://pypi.org/project/jaraco.docker) [](https://pepy.tech/projects/jaraco.docker)  - [ ] [suds-bis](https://pypi.org/project/suds-bis) [](https://pepy.tech/projects/suds-bis)  - [ ] [jaraco.abode](https://pypi.org/project/jaraco.abode) [](https://pepy.tech/projects/jaraco.abode)  - [ ] [jaraco.email](https://pypi.org/project/jaraco.email) [](https://pepy.tech/projects/jaraco.email) - [ ] [jaraco.net](https://pypi.org/project/jaraco.net) [](https://pepy.tech/projects/jaraco.net)  - [ ] [MagicBus](https://pypi.org/project/MagicBus) [](https://pepy.tech/projects/MagicBus) - [ ] [svg.charts](https://pypi.org/project/svg.charts) [](https://pepy.tech/projects/svg.charts)  - [ ] [jaraco.mongodb](https://pypi.org/project/jaraco.mongodb) [](https://pepy.tech/projects/jaraco.mongodb)  - [ ] [calendra](https://pypi.org/project/calendra) [](https://pepy.tech/projects/calendra)  - [ ] [jaraco.services](https://pypi.org/project/jaraco.services) [](https://pepy.tech/projects/jaraco.services)  - [ ] [pmxbot](https://pypi.org/project/pmxbot) [](https://pepy.tech/projects/pmxbot)  - [ ] [jaraco.tidelift](https://pypi.org/project/jaraco.tidelift) [](https://pepy.tech/projects/jaraco.tidelift)  - [ ] [event](https://pypi.org/project/event) [](https://pepy.tech/projects/event) - [ ] [jaraco.clipboard](https://pypi.org/project/jaraco.clipboard) [](https://pepy.tech/projects/jaraco.clipboard) - [ ] [openpack](https://pypi.org/project/openpack) [](https://pepy.tech/projects/openpack)  - [ ] [elastic2-doc-manager](https://pypi.org/project/elastic2-doc-manager) [](https://pepy.tech/projects/elastic2-doc-manager) - [ ] [jaraco.test](https://pypi.org/project/jaraco.test) [](https://pepy.tech/projects/jaraco.test)  - [ ] [jaraco.pmxbot](https://pypi.org/project/jaraco.pmxbot) [](https://pepy.tech/projects/jaraco.pmxbot)  - [ ] [dynpool](https://pypi.org/project/dynpool) [](https://pepy.tech/projects/dynpool) - [ ] [pytest-black-multipy](https://pypi.org/project/pytest-black-multipy) [](https://pepy.tech/projects/pytest-black-multipy) - [ ] [cherrypy-dynpool](https://pypi.org/project/cherrypy-dynpool) [](https://pepy.tech/projects/cherrypy-dynpool) - [ ] [jaraco.modb](https://pypi.org/project/jaraco.modb) [](https://pepy.tech/projects/jaraco.modb)  - [ ] [yg.lockfile](https://pypi.org/project/yg.lockfile) [](https://pepy.tech/projects/yg.lockfile) - [ ] [chucknorris](https://pypi.org/project/chucknorris) [](https://pepy.tech/projects/chucknorris)  - [ ] [nspektr](https://pypi.org/project/nspektr) [](https://pepy.tech/projects/nspektr)  - [ ] [xlsxcessive](https://pypi.org/project/xlsxcessive) [](https://pepy.tech/projects/xlsxcessive)  - [ ] [cmdix](https://pypi.org/project/cmdix) [](https://pepy.tech/projects/cmdix)  - [ ] [googlevoice](https://pypi.org/project/googlevoice) [](https://pepy.tech/projects/googlevoice)  - [ ] [jaraco.financial](https://pypi.org/project/jaraco.financial) [](https://pepy.tech/projects/jaraco.financial)  - [ ] [jaraco.timing](https://pypi.org/project/jaraco.timing) [](https://pepy.tech/projects/jaraco.timing) - [ ] [jaraco.postgres](https://pypi.org/project/jaraco.postgres) [](https://pepy.tech/projects/jaraco.postgres) - [ ] [jaraco.compat](https://pypi.org/project/jaraco.compat) [](https://pepy.tech/projects/jaraco.compat) - [ ] [paradocx](https://pypi.org/project/paradocx) [](https://pepy.tech/projects/paradocx)  - [ ] [http-okapi](https://pypi.org/project/http-okapi) [](https://pepy.tech/projects/http-okapi) - [ ] [jaraco.geo](https://pypi.org/project/jaraco.geo) [](https://pepy.tech/projects/jaraco.geo)  - [ ] [elastic-doc-manager](https://pypi.org/project/elastic-doc-manager) [](https://pepy.tech/projects/elastic-doc-manager) - [ ] [jaraco.util](https://pypi.org/project/jaraco.util) [](https://pepy.tech/projects/jaraco.util)  - [ ] [compilers](https://pypi.org/project/compilers) [](https://pepy.tech/projects/compilers) - [ ] [jaraco.apt](https://pypi.org/project/jaraco.apt) [](https://pepy.tech/projects/jaraco.apt) - [ ] [setuptools-svn](https://pypi.org/project/setuptools-svn) [](https://pepy.tech/projects/setuptools-svn) - [ ] [jaraco.xonsh](https://pypi.org/project/jaraco.xonsh) [](https://pepy.tech/projects/jaraco.xonsh)  - [ ] [vr.cli](https://pypi.org/project/vr.cli) [](https://pepy.tech/projects/vr.cli) - [ ] [vr.runners](https://pypi.org/project/vr.runners) [](https://pepy.tech/projects/vr.runners) - [ ] [lpaste](https://pypi.org/project/lpaste) [](https://pepy.tech/projects/lpaste)  - [ ] [rwt](https://pypi.org/project/rwt) [](https://pepy.tech/projects/rwt) - [ ] [jaraco.fabric](https://pypi.org/project/jaraco.fabric) [](https://pepy.tech/projects/jaraco.fabric)  - [ ] [NAT-PMP](https://pypi.org/project/NAT-PMP) [](https://pepy.tech/projects/NAT-PMP) - [ ] [vr.common](https://pypi.org/project/vr.common) [](https://pepy.tech/projects/vr.common) - [ ] [pytest-home](https://pypi.org/project/pytest-home) [](https://pepy.tech/projects/pytest-home)  - [ ] [fogbugz-bis](https://pypi.org/project/fogbugz-bis) [](https://pepy.tech/projects/fogbugz-bis)  - [ ] [backports.hook-compressed](https://pypi.org/project/backports.hook-compressed) [](https://pepy.tech/projects/backports.hook-compressed)  - [ ] [jaraco.nxt](https://pypi.org/project/jaraco.nxt) [](https://pepy.tech/projects/jaraco.nxt)  - [ ] [motivation](https://pypi.org/project/motivation) [](https://pepy.tech/projects/motivation) - [ ] [jaraco.video](https://pypi.org/project/jaraco.video) [](https://pepy.tech/projects/jaraco.video) - [ ] [eggmonster](https://pypi.org/project/eggmonster) [](https://pepy.tech/projects/eggmonster) - [ ] [jaraco.site](https://pypi.org/project/jaraco.site) [](https://pepy.tech/projects/jaraco.site)  - [ ] [vr.server](https://pypi.org/project/vr.server) [](https://pepy.tech/projects/vr.server) - [ ] [vr.imager](https://pypi.org/project/vr.imager) [](https://pepy.tech/projects/vr.imager) - [ ] [backports.print_function](https://pypi.org/project/backports.print_function) [](https://pepy.tech/projects/backports.print_function) - [ ] [librarypaste](https://pypi.org/project/librarypaste) [](https://pepy.tech/projects/librarypaste)  - [ ] [backports.method_request](https://pypi.org/project/backports.method_request) [](https://pepy.tech/projects/backports.method_request) - [ ] [excuses](https://pypi.org/project/excuses) [](https://pepy.tech/projects/excuses)  - [ ] [jaraco.translate](https://pypi.org/project/jaraco.translate) [](https://pepy.tech/projects/jaraco.translate) - [ ] [backports.pdb](https://pypi.org/project/backports.pdb) [](https://pepy.tech/projects/backports.pdb)  - [ ] [jaraco.media](https://pypi.org/project/jaraco.media) [](https://pepy.tech/projects/jaraco.media)  - [ ] [jaraco.crypto](https://pypi.org/project/jaraco.crypto) [](https://pepy.tech/projects/jaraco.crypto)  - [ ] [pmxbot.webhooks](https://pypi.org/project/pmxbot.webhooks) [](https://pepy.tech/projects/pmxbot.webhooks) - [ ] [popquotes](https://pypi.org/project/popquotes) [](https://pepy.tech/projects/popquotes) - [ ] [vr.builder](https://pypi.org/project/vr.builder) [](https://pepy.tech/projects/vr.builder) - [ ] [solr-doc-manager](https://pypi.org/project/solr-doc-manager) [](https://pepy.tech/projects/solr-doc-manager) - [ ] [jaraco.input](https://pypi.org/project/jaraco.input) [](https://pepy.tech/projects/jaraco.input) - [ ] [jaraco.home](https://pypi.org/project/jaraco.home) [](https://pepy.tech/projects/jaraco.home)  - [ ] [jaraco.imaging](https://pypi.org/project/jaraco.imaging) [](https://pepy.tech/projects/jaraco.imaging) - [ ] [vr.agent](https://pypi.org/project/vr.agent) [](https://pepy.tech/projects/vr.agent) - [ ] [jaraco.keyring](https://pypi.org/project/jaraco.keyring) [](https://pepy.tech/projects/jaraco.keyring) - [ ] [vr.events](https://pypi.org/project/vr.events) [](https://pepy.tech/projects/vr.events) - [ ] [pmxbot.rss](https://pypi.org/project/pmxbot.rss) [](https://pepy.tech/projects/pmxbot.rss) - [ ] [jaraco.xkcd](https://pypi.org/project/jaraco.xkcd) [](https://pepy.tech/projects/jaraco.xkcd) - [ ] [jaraco.office](https://pypi.org/project/jaraco.office) [](https://pepy.tech/projects/jaraco.office) - [ ] [freedompop](https://pypi.org/project/freedompop) [](https://pepy.tech/projects/freedompop) - [ ] [treehouse](https://pypi.org/project/treehouse) [](https://pepy.tech/projects/treehouse) - [ ] [dropbox-index](https://pypi.org/project/dropbox-index) [](https://pepy.tech/projects/dropbox-index)  - [ ] [jaraco.zstd](https://pypi.org/project/jaraco.zstd) [](https://pepy.tech/projects/jaraco.zstd)  - [ ] [recapturedocs](https://pypi.org/project/recapturedocs) [](https://pepy.tech/projects/recapturedocs)  - [ ] [setuptools-hacks.bypass-summary-newline](https://pypi.org/project/setuptools-hacks.bypass-summary-newline) [](https://pepy.tech/projects/setuptools-hacks.bypass-summary-newline)  - [ ] [pmxbot.nsfw](https://pypi.org/project/pmxbot.nsfw) [](https://pepy.tech/projects/pmxbot.nsfw) - [ ] [vr.launch](https://pypi.org/project/vr.launch) [](https://pepy.tech/projects/vr.launch) - [ ] [pmxbot.saysomething](https://pypi.org/project/pmxbot.saysomething) [](https://pepy.tech/projects/pmxbot.saysomething) - [ ] [jaraco.parables](https://pypi.org/project/jaraco.parables) [](https://pepy.tech/projects/jaraco.parables) - [ ] [yg.thumpy](https://pypi.org/project/yg.thumpy) [](https://pepy.tech/projects/yg.thumpy) - [ ] [yg.eventful](https://pypi.org/project/yg.eventful) [](https://pepy.tech/projects/yg.eventful) - [ ] [Distutils](https://pypi.org/project/Distutils) [](https://pepy.tech/projects/Distutils) - [ ] [backports](https://pypi.org/project/backports) [](https://pepy.tech/projects/backports)

@jaraco, could you please let me know if you want to apply some additional filtering/sorting to the roadmap above?

[bswck]

An interesting approach would be to measure—for every project—how many PyPI projects depend on it, using libraries.io. But I think it would more or less correlate with downloads/month anyway, as I am assuming (without having done any research) that most of these downloads come from pipelines that install every dependency for the first time, and dependencies referencing the same project being together aren't that common (so like, when for two projects A and B sharing the same project X as a dependency, X in fact gets installed "twice less", because only once, as it is reused in the same environment by A and B, even though I would technically call X more popular in this case). This can get even more interesting if we add distinction between pip-like and pipx-like installation methods, where a shared dependency would be installed twice for separate environments of A and B, assuming A and B are CLI applications... I could be pointing out all the things that come to my mind further, and it gets very complicated and multilayered as I dig in the rabbit hole.

Yeah, so all in all I've learned that "package popularity" isn't trivial, because both the convergence in the web of dependencies as well as the statistics of total downloads in time play a role in the correct evaluation of how popular a package really is.

Anyway though, this is just an attempt to prioritize the tasks. Since some most popular jaraco projects commonly depend on some less popular jaraco projects (downloads/month-wise!), I started off from jaraco.functools and jaraco.classes.

[jaraco]

Amazing analysis. Thanks!

You'll notice that libraries.io is a project by Tidelift. You may have noticed that I also work with them as they work to garner support for open source maintainers from the enterprise users. They've probably built other tooling and may even be interested in collaborating on tooling to support open source maintenance. You may want to consider signing up with them as a maintainer (there's no cost and could potentially pay) and engaging on the forums to see if there is interest in collaborating. If you need a referral or anything to get signed up, let me know.

[bswck]

You may want to consider signing up with them as a maintainer

Thank you! I've just applied to lift a few of my projects!

---

Due to a considerable number of projects that need similar work, I created a project that aims to automate the whole process as much as possible—autorefine.

MonkeyType will turn out very handy when it comes to type hints generation. I will take care of making them as sophisticated as needed. I think all these projects have enough coverage, so I will simply generate the types by running tests.

I will leverage LibCST and create custom rules if needed for modernizing the projects (some had their last releases a few years ago)—but this is out of scope at the moment.

Contributions & suggestions very, very welcome—I am learning.

Hopefully the tool will speed up more_itertools.consume(map(functools.partial(refine, scope="typing"), jaraco_projects)).

[bswck]

I've made a Coherent OSS project for the initiative: https://github.com/orgs/coherent-oss/projects/3/views/2

[jaraco]

I firmly believe that the best option would be being as explicit as possible when annotating types, because, as it seems, there are too few obvious cases at the end of the day.

Of course if the new type hints would appear too intricate for the eye, which I can totally understand, there is always an option of creating stubs to isolate two worlds of the implementation and the type hints, like in jaraco/jaraco.functools#22. What are your thoughts on this @jaraco?

I guess that's fine. I should probably get used to Python being more verbose and less essential.

[bswck]

I firmly believe that the best option would be being as explicit as possible when annotating types, because, as it seems, there are too few obvious cases at the end of the day.

Of course if the new type hints would appear too intricate for the eye, which I can totally understand, there is always an option of creating stubs to isolate two worlds of the implementation and the type hints, like in jaraco/jaraco.functools#22. What are your thoughts on this @jaraco?

I guess that's fine. I should probably get used to Python being more verbose and less essential.

Well, I guess it's just that Python wasn't built for being statically typed. 🤷‍♀️ The good news is that due to its continuous development, the unfortunate effect of verbosity over essentialness in typing slowly decreases: take PEP 695 as an example.

[Avasam]

As more skeleton-based projects get typed (with a py.typed marker), I'd recommend requesting them to https://github.com/hauntsaninja/mypy_primer/blob/master/mypy_primer/projects.py . Especially for projects that are widely used in the ecosystem.