Mypy: Clarify `zip_safe=False` recommendation for PEP 561

[bhrutledge]

In https://github.com/pypa/twine/pull/618, I'm adding py.typed so that Twine's type annotations are recognized when it's used as an installed package. I've set zip_safe=False as suggested by the mypy docs:

If you use setuptools, you must pass the option zip_safe=False to setup(), or mypy will not be able to find the installed package.

However, one of the other maintainers has requested removing this: https://github.com/pypa/twine/pull/618#discussion_r422654712

The only references I've found to zip_safe in the mypy repo are:

• mypy cannot find module installed as editable by pip · Issue #7508
• Support egg installs with PEP 561 searching · Issue #5007

I've done some cursory testing without setting zip_safe, including using pip install -e path/to/twine, and it doesn't seem to be necessary. However, the note quoted above seems unequivocal. Is it still accurate? Could it be expanded?

Caveat: I've only skimmed the issues above, and am far from an expert on the various use cases of setuptools, esp. editable installs.

[ethanhs]

Hi! Yeah this is a weirder edge of setuptools. For mypy to work, it needs to be able to read files off the disk, and it currently won't unzip eggs (this is something that mypy could support, but makes our already very complicated module searching code even more complicated). My understanding is that in some cases, such as running python3 setup.py install, if your package doesn't opt out, it will be installed as an egg and things won't work. In the linked issue I likely misremembered, as pip install -e just makes an egg link, which I added support for.

E: also, I'm a bit surprised that Jason said the flag shouldn't be passed, because when I talked to him at PyCon a couple of years back, he seemed to indicate that packaging tools are moving away from doing egg installs.

[bhrutledge]

Thanks, @ethanhs. What do you think about adding this sort of detail to the mypy docs?

Also, @jaraco, is there anything you'd like to add?

[ethanhs]

What do you think about adding this sort of detail to the mypy docs?

Yeah that seems like a good idea. I'd be happy to review a PR if you'd like to make one.

[jaraco]

Eggs are deprecated. As is setup.py install. If users are using that, it's their responsibility to install with --zip-safe=false or similar. But for projects that are not reliant on deprecated installer techniques, it should be possible for them to omit this cruft and instead rely on best practices when running mypy. By recommending zip_safe=False, it signals support for a deprecated workflow even if that workflow is unsupported. For that reason, I would strongly recommend against recommending use of it as a matter of course. You _may_ want to include a note that if the package is installed using legacy behaviors (setup.py install), that one _may_ want to set zip_safe=False somehow... but I would strongly discourage dragging this historical artifact into modern packages.

[ethanhs]

Eggs are deprecated. As is setup.py install

Hm, unfortunately a lot of people still use setup.py install. So I mostly have written the advisory to add this as a defensive measure to prevent someone from hitting a bad interaction. And its a lot easier to get packagers to do something "the right way" than get every user of every package to do so. I do think the docs could explain more about this.

[YodaEmbedding]

Eggs are deprecated. As is setup.py install.

What's the recommended alternative?

[ethanhs]

@YodaEmbedding most people probably should be using pip install . and wheels. The only real use left for eggs is setup.py develo (but you should probably use pip install -e . anyway).