Outdated recommendation about scripts in wheel spec?

In this pip issue, Eli Schwartz requests for pip to generate .exe wrappers on Windows when installing packages with (legacy) setuptools scripts, which correspond to the contents of foo-1.0.data/scripts/ in a wheel. My instinctive reaction was “of course not, that’s what console_scripts entry points are supposed to do, not scripts”. That also seems to be the shared understanding reflected in the thread What's the status of scripts vs entry_points?, which includes comments from multiple pip maintainers.

However, the Recommended installer features sections of the wheel spec actually says the following, which was a total surprise to me:

Generate script wrappers.

In wheel, scripts packaged on Unix systems will certainly not have accompanying .exe wrappers. Windows installers may want to add them during install.

which implies that .exe generation for plain scripts placed under foo-1.0.data/scripts/ would be not only standards-compliant, but recommended by the standards.

I assume this is just an outdated detail in the wheel spec, and pip should not start generating exes for scripts. It’s not that easy to understand how packaging evolved ~12 years ago, but I guess there must be good reasons why console_scripts entry points were introduced instead of piggybacking on scripts.

Is that right? Should the spec be changed?

The scripts key in setuptools allows for arbitrary scripts with arbitrary shebangs, whereas entry points (eg: console_scripts / gui_scripts) are guaranteed to be a Python executable launched in a specific manner.

1 Like

So does that imply that the scripts folder of the wheel is intended to hold only platform-specific scripts? After all, it doesn’t seem like “arbitrary scripts with arbitrary shebangs” have any hope of being platform-agnostic.

In that case, I should think that developers packaging pure-Python projects, as -none-any- wheels, should be warned not to use that feature. It would appear to break the intended platform-agnosticism, and is likely an error on the part of someone who should be doing something with console_scripts entry points instead.

Granted, it’s unlikely that they have an enduring need to use setup.py in the first place. But clearly, not everyone who could do everything necessary with pyproject.toml is actually doing so yet; and it doesn’t seem like they’ll be pressured or expected to migrate any time soon.

1 Like

I guess? AFAIK, it’s a hold-over from an older era of Python packaging, where it was primarily meant for Unix-based operating systems.

That seems reasonable, although that’s a choice for the build-backends to make.


Scripts can indeed be any type of script, not just Python, and are notoriously non-portable. But they do have uses, I believe, even though entry point scripts are usually better.

I read the spec as suggesting installers could generate wrappers for Python scripts when the shebang suggests that’s appropriate. Personally I don’t think it’s worth the effort, and I’d downgrade the recommendation to a simple “you can if you want”, but that’s all.

A warning about the non-portability, with a suggestion to look at entry points as an alternative, seems fair. But it should probably go in the backend docs for any backend that allows adding scripts, rather than in the spec.


FYI this is how CLIs written in other languages are usually shipped:

Theoretically, one could save to a location within the package directory and use a proper entry point but this is far more efficient as Python doesn’t have to be invoked.

Please don’t remove this :slightly_smiling_face:

1 Like

There are no plans to do that.

1 Like