That all makes sense, I understand that in the general case you can't
really promise someone that if you mutate global state in-process that the
runpy module has any way of preventing that. Except IMO, the module gives
exactly the impression you're saying is bad (that you want to use it if you
need to do what -m does from Python, assuming you are OK with the
constraints there). And then runpy.run_module is a footgun, because it does
not in fact do what -m does, so it's hard to imagine the kind of person who
*does* want to use runpy -- it's basically "try it on your specific -m, and
possibly it works, and then possibly it will continue to work" (to be
slightly but hopefully not overwhelmingly facetious).

Quoting the docs for it themselves:

See also

The -m <https://docs.python.org/3/using/cmdline.html#cmdoption-m> option
offering equivalent functionality from the command line.
From an external developer's perspective, if some other thing would be
necessary tomorrow that would only be for -m, could one rely on it being
added to any or all of the functions in the runpy module? That sounds
unclear if there isn't a function that represents what -m does and promises
to stay that way.

It seems to me that either exposing a public API that promises to be -m as
much as possible (which means at least if an end-user knows they're just as
"clean" as the process that -m will run, you're probably good), or
otherwise deprecating the functions in here entirely as public, and just
making them all private, would be improvements to being able to understand
if someone wants to use this module or not, but I do appreciate you
explaining how things got here.

-J

On Wed, Sep 11, 2019 at 7:03 PM Nick Coghlan <report@bugs.python.org> wrote:

>
> Nick Coghlan <ncoghlan@gmail.com> added the comment:
>
> There is one, it just isn't public: runpy._run_module_as_main.
>
> It's a private API that the -m switch implementation calls, and was
> introduced after the original runpy.run_module was found not to offer
> everything the switch needed.
>
> It isn't possible to fully emulate -m from Python code though, as the
> lifecycle of the real main module is intertwined with the lifecycle of the
> underlying interpreter.
>
> So if folks really want to try to do this, the source code is there to
> look at, but we're not giving the false impression that it's easy to do
> correctly with no unintended consequences.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue37941>
> _______________________________________
>