Add a CLI to invoke entrypoint scripts

[FFY00]

There are a few use-cases where we may want to invoke entrypoint scripts without relying on them being on PATH. Scripts are not required to be installed and operate outside the Python environment, in some systems it's undesirable to install Python entrypoint scripts, and there are some edge cases, like the one highlighted in https://discuss.python.org/t/pep-517-definition-of-isolated-build-environments-breaks-sysconfig-contract/9583, where there may be issues on relying on them to be in PATH. Other example would be environments such as what is proposed on PEP 582, where it's just not possible to update the value of PATH.

I propose the adding a CLI to invoke entrypoint scripts:

$ python -m importlib.invoke_script sphinx-build

This module name is fairly bit and not particularly nice, but I don't really have any better proposal. Please let me know if you have a better one 😅

[FFY00]

This would also simply entrypoint script generation as they could just use this instead.

We are currently doing some very hacky things 😛
https://github.com/pradyunsg/installer/pull/4#issuecomment-623668717

They could be replaced with the following.

#!/bin/sh

exec /path/to/target/python -m importlib.invoke_script sphinx-build --distribution Sphinx

(used a --distribution flag here to remove the ambiguity in case of conflicting scripts)

[jaraco]

I can think of a couple of ways this could be implemented.

• A third party package could implement a top-level module, maybe "epl", shorthand for "entry point launcher", enabling -m epl sphinx-build.
• A Python feature could add a new command-line argument similar to -m, something like python -e sphinx-build.

I wouldn't allow the invocation to take command-line parameters (e.g. --distribution) because the console script can accept parameters as well. I'd suggest instead, if necessary, to indicate the distribution as a prefix (e.g. python -e Sphinx:sphinx-build). Though it may not be necessary as collisions would cause conflicts in traditional installs (overwritten scripts) so are probably rare.

Another concern to consider - scripts come in two flavors: "console" and "gui", with the latter launched under pythonw. Hmm. So I guess the implementation could detect under which python it's launched and select on "console_scripts" or "gui_scripts" based on the executable.

Another factor to consider: many projects have only one console_script entry point and it's obviated by the runpy script. In your example, one can use python -m sphinx to satisfy the above example. In other projects, I've stopped using console scripts and instead am exposing a series of runpy scripts (example: python -m jaraco.develop.add-github-secrets).

Related, some in Setuptools have suggestions on how runpy and console scripts could be unified. If that approach were taken, then the proposals above would be obviated and scripts could be generated from functionality also available via python -m. The biggest weakness is that python -m only allows one entry per module, but *_scripts allows specification of a function and thus multiple executable entry points per module. A Setuptools-only approach would leave other packaging tools without the desired functionality.

I do think it would be nice if a package could somehow (automatically) expose various commands that could be reached through a simple syntax and expose the same name as executables on PATH.

All of this said, this project (importlib_metadata) is probably not the best place to present/discuss these ideas. Probably we should have a design, either a PEP or perhaps just a discussion on discourse, to capture the motivations and goals and implementation options with pros/cons.

I'd be interested in contributing to a design and advising if someone would be willing to spearhead the effort.

[jaraco]

I'm closing this issue as there's nothing particularly pertinent to this project, but I encourage continued work on these ideas.