[docs] [issue10912] PyObject_RichCompare differs in behaviour from PyObject_RichCompareBool ; difference not noted in documentation

[Devin Jeanpierre]

New submission from Devin Jeanpierre <jeanpierreda at gmail.com>:

PyObject_RichCoareBool is, according to the documentation in trunk (Doc\c-api\object.rst), exactly the same as PyObject_RichCompare, except it 1, 0, or -1 for error, false, and true respectively. However, it differs in behavior by both that, and also by assuming that identity implies equality. This noted in a two year-old ML post (sadly, no bug report was posted as best as I can find): http://mail.python.org/pipermail/python-list/2009-March/1195170.html

Ideally PyObject_RichCompareBool should probably be named something else, since it can no longer be used, strictly, as "PyObject_RichCompare, but returning a C bool" (or, rather, a C int). Some suggestions were offered in the mailing list thread above.

I'm filing this as a documentation bug because I find that outcome unlikely. At least the documentation should note the difference in behavior, so that people do not accidentally write C code that does not behave as intended.

This issue is related to, but different from issue 4296, which objected to the new container behavior created by the change to PyObject_RichCompareBool. My only objection here is that the latter change does not appear to be documented.

I would supply a patch for the tests, but PyObject_RichCompareBool is apparently not directly tested anywhere, just tested obliquely through testing the containment operator, and this was changed by the same commit that changed PyObject_RichCompareBool. I don't know how to word the (very small!) change to the docs.

----------
assignee: docs at python
components: Documentation
messages: 126306
nosy: Devin Jeanpierre, docs at python
priority: normal
severity: normal
status: open
title: PyObject_RichCompare differs in behaviour from PyObject_RichCompareBool ; difference not noted in documentation

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10912>
_______________________________________