Add a new C API tutorial for reference counting and error handling#150090
Add a new C API tutorial for reference counting and error handling#150090ZeroIntensity wants to merge 7 commits into
Conversation
Documentation build overview
17 files changed ·
|
encukou
left a comment
encukou
left a comment
There was a problem hiding this comment.
These look good, but now for the hard part: Could you remove the topics covered here from "Assorted topics"?
| if (bytes == NULL) { | ||
| return NULL; | ||
| } | ||
| const char *command = PyBytes_AS_STRING(bytes); |
There was a problem hiding this comment.
Could you use PyBytes_AsString, to stay within the Limited API?
There was a problem hiding this comment.
I could, but I'm worried it would send the wrong message:
- We know that the result will always be a
bytesobject here, so it's not a great idea to encourage the user to do needless error checking in order to stay compatible with an API layer they haven't learned about yet. - It complicates the example, because it now needs a new error path with a
Py_DECREFin it.
There was a problem hiding this comment.
I want beginners to do more error checking, not less.
The path is longer, but educational: any API call can fail (unless documented otherwise -- but that's the point I would save for later. Also, in this case the docs are currently rather ambiguous).
| } | ||
|
|
||
| If :c:func:`PyUnicode_AsUTF8AndSize` is successful, *command* will point to the | ||
| If :c:func:`PyUnicode_AsUTF8` is successful, *command* will point to the |
There was a problem hiding this comment.
Please keep the Stable ABI function here.
There was a problem hiding this comment.
The code and description here don't match PyUnicode_AsUTF8AndSize. It'd require some rewriting to be correct.
| *************************** | ||
|
|
||
| This chapter covers the details about how Python's C API expresses errors | ||
| and how to interact with Python exceptions. |
There was a problem hiding this comment.
Could you mention that the tutorial builds on the module from "Your first C API extension module"?
| return NULL; | ||
| } | ||
|
|
||
| // Py_NewRef() is just a shorthand for Py_INCREF() with an expression |
There was a problem hiding this comment.
Would it make sense to introduce Py_NewRef in the refcounting chapter?
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Just by deleting the section? Or do you want me to do some refactoring? |
da-woods
left a comment
da-woods
left a comment
There was a problem hiding this comment.
I think it might be worth dealing with stolen references too. In that PyTuple_SetItem and PyList_SetItem are pretty common (and also a bit confusing in the error-handling case)
Co-authored-by: da-woods <dw-git@d-woods.co.uk>
encukou
left a comment
encukou
left a comment
There was a problem hiding this comment.
Just by deleting the section? Or do you want me to do some refactoring?
If you've covered everything the old guide teaches, just delete it. If not, either keep the points this doesn't cover, or add them to the new guide.
| if (bytes == NULL) { | ||
| return NULL; | ||
| } | ||
| const char *command = PyBytes_AS_STRING(bytes); |
There was a problem hiding this comment.
I want beginners to do more error checking, not less.
The path is longer, but educational: any API call can fail (unless documented otherwise -- but that's the point I would save for later. Also, in this case the docs are currently rather ambiguous).
| } | ||
|
|
||
| If :c:func:`PyUnicode_AsUTF8AndSize` is successful, *command* will point to the | ||
| If :c:func:`PyUnicode_AsUTF8` is successful, *command* will point to the |
3 participants
No description provided.