classification
Title: Documentation example of module init function lacks error handling
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cajetan.rodrigues, docs@python, scoder
Priority: normal Keywords: easy, newcomer friendly, patch

Created on 2020-04-14 06:08 by scoder, last changed 2020-04-25 05:46 by scoder. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 19705 merged cajetan.rodrigues, 2020-04-24 23:50
PR 19710 merged miss-islington, 2020-04-25 05:30
Messages (5)
msg366368 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2020-04-14 06:08
The example in the docs that shows how to initialise an embedded module gives a wrong impression about error handling. Most of the functions that it calls return error codes, but those do not get looked at. Innocent users who copy and paste the example may miss some of them when adapting the code, thus ending up with an unsafe implementation.

The example should at least make it clear where error handling is needed.

https://docs.python.org/3/extending/extending.html#the-module-s-method-table-and-initialization-function

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);
    }

    /* Add a built-in module, before Py_Initialize */
    PyImport_AppendInittab("spam", PyInit_spam);

    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(program);

    /* Initialize the Python interpreter.  Required. */
    Py_Initialize();

    /* Optionally import the module; alternatively,
       import can be deferred until the embedded script
       imports it. */
    PyImport_ImportModule("spam");

    ...

    PyMem_RawFree(program);
    return 0;
}
msg367234 - (view) Author: Cajetan Rodrigues (cajetan.rodrigues) * Date: 2020-04-24 22:33
At the risk of sounding like a jerk, I'd very much want to say that copy-pasters should get what they deserve :) But then I remember I was once a copy-paster too!

Hello again, Stefan :)

Thanks for watching out for the community - I'll be happy to fix this!
msg367257 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2020-04-25 05:28
New changeset d4f3923d5901ef1ccdbe6ad6c5a753af90832a0f by Cajetan Rodrigues in branch 'master':
bpo-40279: Add some error-handling to the module initialisation docs example (GH-19705)
https://github.com/python/cpython/commit/d4f3923d5901ef1ccdbe6ad6c5a753af90832a0f
msg367258 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2020-04-25 05:45
New changeset 882a7f44da08c6fb210bd9a17f80903cbca84034 by Miss Islington (bot) in branch '3.8':
bpo-40279: Add some error-handling to the module initialisation docs example (GH-19705) (GH-19710)
https://github.com/python/cpython/commit/882a7f44da08c6fb210bd9a17f80903cbca84034
msg367259 - (view) Author: Stefan Behnel (scoder) * (Python committer) Date: 2020-04-25 05:46
Hi Cajetan, thank you for your contribution! That's a nice documentation improvement.
History
Date User Action Args
2020-04-25 05:46:25scodersetstatus: open -> closed

nosy: - miss-islington
messages: + msg367259

resolution: fixed
stage: patch review -> resolved
2020-04-25 05:45:54scodersetmessages: + msg367258
2020-04-25 05:30:50miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request19031
2020-04-25 05:28:02scodersetmessages: + msg367257
2020-04-24 23:50:03cajetan.rodriguessetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request19024
2020-04-24 22:33:47cajetan.rodriguessetnosy: + cajetan.rodrigues
messages: + msg367234
2020-04-14 06:08:29scodercreate