Setuptools: Support module __main__.py through python -m (entry points/console scripts)

[SoniEx2]

-m is a python standard (PEP 338) and we should support and encourage it. best way to do that is to defer to it when asked to. we should ideally also deprecate the old ways to further encourage -m usage.

[jaraco]

The behavior is largely documented in the runpy module. Setuptools supports this for its easy_install behavior as python -m easy_install. Is there other behavior you're expecting?

[SoniEx2]

No, the original title is correct. I want entry points/console scripts that use -m behaviour.

[jaraco]

Can you give an example of what you're after?

[SoniEx2]

ideally something along the lines of:

setup.py:

runpy_scripts={"ganarchy": "ganarchy"}

ganarchy/__main__.py:

import ganarchy.cli
import ganarchy.cli.debug
# import other ganarchy.cli.* modules etc

ganarchy.cli.main()

but idk how the setup.py should look for it.

[jaraco]

I think I understand. So you want setuptools to accept a mapping of package name to console_script entrypoint name and from that, it will generate a __main__ in the package that loads that entry point and invokes it?

Note that the generated module would always be essentially boilerplate:

# ganarchy/__main__.py
import ganarchy.cli
if __name__ == '__main__':
  ganarchy.cli.main()

I'm a little wary of generating modules in a package. I'm also uneasy coupling console_scripts to another feature (runpy module generation).

I think I'd rather solicit a separate entry point for runpy indication:

# setup.cfg
[options.entry_points]
console_scripts =
  ganarchy = ganarchy.cli:main
runpy_modules =
  ganarchy = ganarchy.cli:main

This approach has the advantage of supplying the two similar features in a parallel way.

The biggest disadvantage to this approach is that, similar to console_scripts, it would be the responsibility of the installer to generate these runpy modules.

I wouldn't restrict the design to just package modules (__main__). Any module could be suitable, including top-level unimportable modules (like in pip-run) and submodules (like pep517.build).

The main reason I'm wary to generate content is because it's not obvious when that content should be generated (should it appear in the sdist, in the built module, only at install time, is it optional?). Lots of design considerations.

I'm more inclined to think that the package should simply supply the runpy script as part of the source, that the advantage of making it declarative is more trouble than than the value it provides.

Can you elaborate on what problem you're trying to solve and what design you have in mind?

[SoniEx2]

nonono, no __main__ generator.

it should install in the PATH (or equivalent) the following script:

ganarchy (shell script in PATH):

#!/usr/bin/env python -m ganarchy

or equivalent.

no if __name__=="__main__":. also note that the ganarchy.cli.* imports are used for side-effects (they modify ganarchy.cli.main)

[SoniEx2]

this is for existing __main__.py that can already be used from python -m.

[dbivolaru]

Was looking for a similar solution and stumbled upon this question.
My solution is as follows.

setup.py:

setup(
    # other arguments here...
    entry_points={
        'console_scripts': ['ganarchy=ganarchy.cli:entry_point']
    }
    # yet some other arguments here...
)

And add at the end of ganarchy/cli/__init__.py:

# your original code...

def entry_point():
    import runpy
    runpy.run_module(__name__)

This ensures both $ python -m ganarchy.cli and $ ganarchy will be doing the same thing.
This is tested and working (for posterity in case someone else also stumbles upon this from a search engine).

In terms of integrating this in setuptools as a feature, the API could look like (my proposal):

    entry_points={
        'console_scripts': ['ganarchy:=ganarchy.cli']
    }

The := instead of = would signify that setuptools would generate the entry_point() stub, as above, that calls runpy.run_module with the string after the :=.

[jaraco]

The := instead of = would signify that setuptools would generate the entry_point() stub, as above, that calls runpy.run_module with the string after the :=.

Interesting idea. Unfortunately, I don't think it's compatible with other syntaxes supported. I believe, for example, a dictionary is supported for the value for console_scripts. There may also be syntaxes in setup.cfg that would not support this syntax.

it should install in the PATH (or equivalent) the following script:

Oh. That's interesting too. The biggest problem I see with that approach is it may not be compatible with executable wrappers like those used on Windows. It would still definitely require some support from pip (and other installers).

[Xophmeister]

Similar to @dbivolaru, I "solved" this by using:

[options.entry_points]
console_scripts =
  my_script = my.module.name.__main__:main

i.e., Explicitly addressing the main function in my __main__.py, whereas it could have simply been invoked with python -m my.module.name. It's ugly and took a bit of trial-and-error, but it works.

In the current system, you have to delimit module and the entrypoint callable with a colon. What if the logic was something like:

• Split on :
  
  
  
  • If there are two components, then proceed as currently;
  
  
  • If there is only one component, then interpret this as a direct module invocation?