I am afraid that while documentation is welcomed its existence does not magically creates an API.
Will all respect, but I was a core I would have blocked it by asking to add a test that validates the runpy can really do that. The only way to implement a reliable API is to add tests. In fact tests are the only contracts an API can really provide, documentation is like a promise made during a political campaign.
Would anyone be against a PR that would add such test?
I personally do not find the runpy very nice-looking but it clearly is a very good start.
I also have another question related to future. I see extensive use of “unsupported” and “unsafe”. We do all understand that evolution does not happen over night and there are lots of broken-use-case and that it may take many years to reach a “supported” status. Still, why not using “experimental” term.
There is a big difference between telling people something is not production ready and discouraging them to do something. API will never happen if we do not start with something and slowly improve it.
If someone wants to fix one of the issues related to in-process use, they will be welcomed to raise PRs, with tests. The current test suites should assure that their changes do not break other random bits. It is a long process but it needs to starts somewhere.