[issue13522] Document error return values for PyFloat_* and PyComplex_*
New submission from Stefan Krah <stefan-usenet@bytereef.org>: A couple of -1.0 error return codes aren't documented, see for example PyFloat_AsDouble() and PyComplex_AsCComplex(). ---------- assignee: docs@python components: Documentation keywords: easy messages: 148789 nosy: docs@python, mark.dickinson, skrah priority: low severity: normal stage: needs patch status: open title: Document error return values for PyFloat_* and PyComplex_* type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Mark Dickinson <dickinsm@gmail.com> added the comment: Well, it's sort of documented implicitly: from http://docs.python.org/c-api/intro.html#exceptions "In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns an error indicator. If not documented otherwise, this indicator is either NULL or -1, depending on the function’s return type." ---------- versions: -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Stefan Krah <stefan-usenet@bytereef.org> added the comment: Good point. - I just had to figure out if the pattern Py_complex c = PyComplex_AsCComplex(w); if (c.real == -1.0 && PyErr_Occurred()) { ... will always be reliable in the future. The source of PyComplex_AsCComplex() suggests that it will, on the other hand in getargs.c the pattern isn't used. The passage you quoted is quite clear, so I wouldn't mind if you close this. I'm not sure how many people read that passage though. :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: I think it's still a good idea to spell it out explicitly in each function description. The document pointed by Mark is long enough that it's easy to overlook or forget that single important statement. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Arnaud Calmettes <calmettes.arnaud@gmail.com> added the comment: Hi, Here is the patch I propose for this issue. This is my first attempt to contribute to Python, so please don't hit me too hard if I did something wrong. :) When browsing the source code of complexobject.c, I also noticed that the return values of the _Py_c_quot and _Py_c_pow (which return zero in case of error) weren't documented at http://docs.python.org/dev/c-api/complex.html#_Py_c_quot ---------- nosy: +arnaudc Added file: http://bugs.python.org/file24007/patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: There's a typo in the patch: it's PyErr_Occurred (two r's), not PyErr_Occured. Otherwise, looks good to me. ---------- stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Arnaud Calmettes <calmettes.arnaud@gmail.com> added the comment: I fixed the typo and the markup. ---------- Added file: http://bugs.python.org/file24009/patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 68cbf6551710 by Antoine Pitrou in branch '3.2': Issue #13522: document error return values of some float and complex C API functions. http://hg.python.org/cpython/rev/68cbf6551710 New changeset 1f096611baf4 by Antoine Pitrou in branch 'default': Issue #13522: document error return values of some float and complex C API functions. http://hg.python.org/cpython/rev/1f096611baf4 New changeset 059e4d752fbe by Antoine Pitrou in branch '2.7': Issue #13522: document error return values of some float and complex C API functions. http://hg.python.org/cpython/rev/059e4d752fbe ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: Committed now. Thank you for the patch! ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
STINNER Victor <victor.stinner@haypocalc.com> added the comment: _Py_c_pow() doc is wrong: + If :attr:`exp.imag` is not null, or :attr:`exp.real` is negative, + this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`. The function only fails if num=0 and exp.real < 0 or if num=0 and exp.imag != 0. ---------- nosy: +haypo resolution: fixed -> status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Arnaud Calmettes <calmettes.arnaud@gmail.com> added the comment: Fixed. ---------- Added file: http://bugs.python.org/file24014/diff_complex_rst _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Arnaud Calmettes <calmettes.arnaud@gmail.com> added the comment: Previous patch was also wrong, sorry! ---------- keywords: +patch Added file: http://bugs.python.org/file24015/complex.rst-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 67a4e8fe650e by Victor Stinner in branch 'default': Issue #13522: Fix _Py_co_pow() documentation http://hg.python.org/cpython/rev/67a4e8fe650e ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Changes by STINNER Victor <victor.stinner@haypocalc.com>: ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset edc981ce8748 by Victor Stinner in branch '3.2': Issue #13522: Fix _Py_co_pow() documentation http://hg.python.org/cpython/rev/edc981ce8748 New changeset 2863470caebb by Victor Stinner in branch '2.7': Issue #13522: Fix _Py_co_pow() documentation http://hg.python.org/cpython/rev/2863470caebb ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13522> _______________________________________
participants (6)
-
Antoine Pitrou -
Arnaud Calmettes
-
Mark Dickinson
-
Roundup Robot
-
Stefan Krah
-
STINNER Victor