[issue13561] os.listdir documentation should mention surrogateescape
New submission from Michael Foord michael@voidspace.org.uk:
Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example).
This should be documented.
---------- assignee: docs@python components: Documentation messages: 149070 nosy: docs@python, michael.foord priority: normal severity: normal stage: needs patch status: open title: os.listdir documentation should mention surrogateescape versions: Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue13561 _______________________________________
Changes by Éric Araujo merwok@netwok.org:
---------- nosy: +eric.araujo, haypo, loewis
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue13561 _______________________________________
STINNER Victor victor.stinner@haypocalc.com added the comment:
Can you please write a doc patch?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue13561 _______________________________________
misdre misdre+python@gmail.com added the comment:
Added a small patch to mention surrogateescape and PEP 383.
---------- keywords: +patch nosy: +misdre Added file: http://bugs.python.org/file23998/listdir-pep383.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue13561 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Patch looks good, apart from a missing “the”, but I think it should be expanded: Right now it tells that surrogateescape is used, but IMO it would be more useful if it also mentioned practical implications, i.e. what Michael “The Beard” Foord says in the first message.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue13561 _______________________________________
Irit Katriel iritkatriel@yahoo.com added the comment:
I think this was added in another section of this doc. See the second paragraph in https://docs.python.org/3/library/os.html#file-names-command-line-arguments-...
---------- nosy: +iritkatriel
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue13561 _______________________________________
STINNER Victor vstinner@python.org added the comment:
I think this was added in another section of this doc. See the second paragraph in https://docs.python.org/3/library/os.html#file-names-command-line-arguments-...
Right, this section now explains encodings and the error handler.
Moreover, I recently reworked the documentation of the filesystem encoding and error handler: * https://docs.python.org/dev/glossary.html#term-filesystem-encoding-and-error... * https://docs.python.org/dev/library/os.html#python-utf-8-mode * https://docs.python.org/dev/library/sys.html#sys.getfilesystemencoding * etc.
I consider that it's now enough, I close the issue ;-) If someone wants to enhance the doc, please submit a PR. This issue is now quite old :-)
---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue13561 _______________________________________
participants (5)
-
Irit Katriel -
Michael Foord
-
misdre
-
STINNER Victor
-
Éric Araujo