René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Document the preferred style for API functions with three, four or five-way returns","articleBody":"Most C API functions either succeed or fail. Those functions return `NULL`/not-`NULL` or 0/-1. No problem there.\r\n\r\nHowever there are functions that can have three or more return kinds.\r\nFor example, `found/not-found/error`, `yield/return/raise`, or even `less-than/equal/greater-than/unordered/error` in the case of comparisons.\r\n\r\nFor those functions we want to return the kind as an `int`, setting any `PyObject *` results through an out pointer.\r\n\r\nThe devguide should document the preferred way to do this, to avoid endless debate for each new C API function.\r\n\r\nSee https://github.com/python/cpython/issues/105201#issuecomment-1578342058 for my preferred approach for three-way return values.\r\n\r\nFour and five way return values other than for comparisons are sufficiently uncommon that they can be dealt with on an individual basis.\r\n\r\nFor comparisons, a slightly strange [enum based on powers-of-two](https://github.com/python/cpython/blob/main/Include/internal/pycore_code.h#L469) is to be used for efficient selection of the desired result by masking.","author":{"url":"https://github.com/markshannon","@type":"Person","name":"markshannon"},"datePublished":"2023-06-22T10:06:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":15},"url":"https://github.com/1121/devguide/issues/1121"}