[Python-Dev] Usability of the limited API

[Paul Moore]

With Python 3.5 shipping an embeddable copy of the interpreter on
Windows, I thought I'd try out a simple embedded interpreter as an
experiment. I wanted to use the limited API, as I'd rather it were
easy to upgrade the interpreter without recompiling the embedding app.

But the "Very high-level embedding" example in the docs doesn't
compile with the limited API.

#include <Python.h>

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }
    Py_SetProgramName(program);  /* optional but recommended */
    Py_Initialize();
    PyRun_SimpleString("from time import time,ctime\n"
                       "print('Today is', ctime(time()))\n");
    Py_Finalize();
    PyMem_RawFree(program);
    return 0;
}

The Py_DecodeLocale/Py_SetProgramName/PyMem_RawFree bit can probably
be replaced by a Py_SetProgramName call specifying a static value,
it's not exactly crucial. (Py_DecodeLocale appears to be defined as in
the limited API by the headers, but not exported from python3.dll, by
the way, which implies that something's out of sync).

But PyRun_SimpleString doesn't appear to be exposed in the limited
API, even though https://docs.python.org/3/c-api/veryhigh.html doesn't
mention this, and https://docs.python.org/3/c-api/stable.html says
that functions not part of the stable API will be marked as such.

I dumped out the exported symbols from python3.dll, which is the
simplest way I could think of finding out what is in the limited API
(it's hardly user friendly, but never mind). And frustratingly, none
of the very high level PyRun_XXX APIs are available.

At this point, I think I'll probably just give up and use the full
API, but it does make me question whether the limited API is actually
usable as it stands.

I was hoping to be able to suggest as an application bundling option
that people could write a trivial wrapper script in C to fire up a
Python script, and bundle that along with its dependencies and the
embeddable Python distribution. Looks like that's doable, but only
using the full API, which makes upgrading the bundled Python
interpreter a bit messier. Ah, well, no huge loss :-(

But after this experiment, I do wonder - is the limited API really a
viable option for embedders?

Paul