[issue45246] the sorted() documentation should refer to operator
New submission from Dimitri Papadopoulos Orfanos : The documentation of sorted() lacks any reference to the comparison mechanism between items. Compare with the documentation of list.sort(), which starts with: using only < comparisons between items This is mentioned in the "Sorting HOW TO", under "Odd and Ends": The sort routines are guaranteed to use __lt__() when making comparisons between two objects. However, the "Sorting HOW TO" is "a brief sorting tutorial", not the reference documentation. This property needs to be documented in the reference documentation of sorted(). -- assignee: docs@python components: Documentation messages: 402209 nosy: DimitriPapadopoulosOrfanos, docs@python priority: normal severity: normal status: open title: the sorted() documentation should refer to operator < versions: Python 3.10, Python 3.11, Python 3.9 ___ Python tracker <https://bugs.python.org/issue45246> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45246] the sorted() documentation should refer to operator
Change by Dimitri Papadopoulos Orfanos : -- keywords: +patch pull_requests: +26871 stage: -> patch review pull_request: https://github.com/python/cpython/pull/28472 ___ Python tracker <https://bugs.python.org/issue45246> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45246] the sorted() documentation should refer to operator
Dimitri Papadopoulos Orfanos added the comment: Then what about removing it from the list.sort() documentation too? Note that maintainers of other PEPs insist that this is a known fact and base their code on that: https://github.com/python/peps/pull/2077 -- ___ Python tracker <https://bugs.python.org/issue45246> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45246] the sorted() documentation should refer to operator
Dimitri Papadopoulos Orfanos added the comment: I would recommend the wording in the "Sorting HOW TO" from: The sort routines are guaranteed to use __lt__() when making comparisons between two objects. to: The sort routines happen to use __lt__() when making comparisons between two objects. -- ___ Python tracker <https://bugs.python.org/issue45246> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45246] the sorted() documentation should refer to operator
Dimitri Papadopoulos Orfanos added the comment: I've seen the new PR for sorted(), thank you for looking into this. Would it make sense to change list.sort() in the same way? -- ___ Python tracker <https://bugs.python.org/issue45246> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45815] Document exceptions raised by fnmtach
New submission from Dimitri Papadopoulos Orfanos : The fnmatch documentation should explicitly mention the type of exceptions raised by fnmatch.fnmatch(): https://docs.python.org/3/library/fnmatch.html In my case it raised sre_constants.error, and it took some time to understand that the proper way to catch this type of exceptions is to catch the re.error superclass, by reading https://bugs.python.org/issue795379. Actually that would be the case for any module using the re module under the hood, possibly passing an ill-formed regex to a re function. -- assignee: docs@python components: Documentation, Library (Lib), Regular Expressions files: sre_constants.error_stderr.txt messages: 406396 nosy: DimitriPapadopoulosOrfanos, docs@python, ezio.melotti, mrabarnett priority: normal severity: normal status: open title: Document exceptions raised by fnmtach versions: Python 3.11 Added file: https://bugs.python.org/file50442/sre_constants.error_stderr.txt ___ Python tracker <https://bugs.python.org/issue45815> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25433] whitespace in strip()/lstrip()/rstrip()
Dimitri Papadopoulos Orfanos added the comment: I agree on avoiding a link to str.isspace() and defining "whitespace" instead. However please note there are many de facto definitions of "whitespace". All of them must be documented - or at least the conceptual classes of "whitespace" and clarify which class each of the following belongs to: * Unicode whitespaces are by very far the most common: str.isspace(), strip()/lstrip()/rstrip(), Py_UNICODE_ISSPACE. * Py_ISSPACE targets byte/bytearray but is never used! * bytearray.strip() does not use Py_ISSPACE but a hardcoded list of ASCII whitespaces instead. * finally string.whitespace is probably equivalent to the list used by bytearray.strip(). Beyond the docs, I think Python 3 should rationalize bytearray.strip() / Py_ISSPACE / string.whitespace, probably having bytearray.strip() rely on Py_ISSPACE, and Py_ISSPACE rely on string.whitespace unless string.whitespace is obsoleted. -- ___ Python tracker <https://bugs.python.org/issue25433> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25433] whitespace in strip()/lstrip()/rstrip()
New submission from Dimitri Papadopoulos Orfanos: The documentation of strip() / lstrip() / rstrip() should define "whitespace" more precisely. The Python 3 documentation refers to "ASCII whitespace" for bytes.strip() / bytes.lstrip() / bytes.rstrip() and "whitespace" for str.strip() / str.lstrip() / str.rstrip(). I suggest the following improvements: * add a link from "ASCII whitespace" to string.whitespace or bytes.isspace(), * define plain "whitespace" more precisely (possibly with a link to str.isspace()). The Python 2 documentation refers to plain "whitespace". As far as I know strip() removes ASCII whitespaces only. If so, please: * add a link to string.whitespace or str.isspace(), * improve the string.whitespace documentation and explain that it is locale-dependent (see documentation of str.isspace()). -- assignee: docs@python components: Documentation messages: 253152 nosy: Dimitri Papadopoulos Orfanos, docs@python priority: normal severity: normal status: open title: whitespace in strip()/lstrip()/rstrip() type: enhancement versions: Python 2.7, Python 3.5 ___ Python tracker <http://bugs.python.org/issue25433> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue26001] Tutorial: write() does not expect string in binary mode
New submission from Dimitri Papadopoulos Orfanos: About section "7.2.1. Methods of File Objects" of the tutorial: 1. Method read() is documented as follows: reads some quantity of data and returns it as a string or bytes object. Indeed read() returns a string in text mode and bytes in binary mode. For the sake of clarity, I suggest changing to: reads some quantity of data and returns it as a string (in text mode) or bytes object (in binary mode). This might seem long-winded but I believe it would help those moving from Python 2 to Python 3. 2. Method write() is documented as follows: To write something other than a string, it needs to be converted to a string first While this is correct in text mode, it is wrong in binary mode. May I suggest: To write something other than a string (in text mode) or bytes object (in binary mode), it needs to be converted first -- assignee: docs@python components: Documentation messages: 257418 nosy: Dimitri Papadopoulos Orfanos, docs@python priority: normal severity: normal status: open title: Tutorial: write() does not expect string in binary mode versions: Python 3.5 ___ Python tracker <http://bugs.python.org/issue26001> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25433] whitespace in strip()/lstrip()/rstrip()
Dimitri Papadopoulos Orfanos added the comment:
In Python 2, as far as I can understand, string.whitespace and str.isspace()
are different:
* str.isspace() is built upon the C isspace() function and is therefore
locale-dependant. Python heavily relies on isspace() to detect "whitespace"
characters.
* string.whitespace is a list of "ASCII whitespace characters" carved in stone.
As far as I can see string.whitespace is defined but not used anywhere in
Python source code.
See source code:
* Modules/stringobject.c around line 3319:
[...]
string_isspace(PyStringObject *self)
{
[...]
e = p + PyString_GET_SIZE(self);
for (; p < e; p++) {
if (!isspace(*p))
return PyBool_FromLong(0);
}
return PyBool_FromLong(1);
[...]
* Lib/string.py near line 23:
whitespace = ' \t\n\r\v\f'
Functions strip()/lstrip()/rstrip() use str.isspace() and have nothing to do
with string.whitespace:
* Modules/stringobject.c around line 1861:
[...]
do_strip(PyStringObject *self, int striptype)
{
[...]
i = 0;
if (striptype != RIGHTSTRIP) {
while (i < len && isspace(Py_CHARMASK(s[i]))) {
i++;
}
}
[...]
Therefore I suggest the documentation of Python 2.7 points to str.isspace()
wherever the term "whitespace" is used in the documentation - including this
specific case of strip()/lstrip()/rstrip().
--
___
Python tracker
<http://bugs.python.org/issue25433>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25433] whitespace in strip()/lstrip()/rstrip()
Dimitri Papadopoulos Orfanos added the comment: In Python 3 the situation is similar: * The Py_UNICODE_ISSPACE macro is used internally to define str.isspace() and wherever Python needs to detect "whitespace" characters in strings. * There is an equivalent function Py_ISSPACE for bytes/bytearray. * The bytearray.strip() implementation for bytearray relies on hardcoded ASCII whitespaces instead of Py_ISSPACE. * string.whitespace is a list of "ASCII whitespace characters" carved in stone. As far as I can see string.whitespace is defined but not used anywhere in Python source code. Therefore I suggest the documentation of Python 3 points to str.isspace() wherever the term "whitespace" is used in any documentation related to strings - including this specific case of strip()/lstrip()/rstrip(). -- ___ Python tracker <http://bugs.python.org/issue25433> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
