If you have an undecodable filenames on UNIX, Python 3 escapes undecodable bytes using surrogates. pydoc: HTMLDoc.index() uses indirectly os.listdir() which does such operation, and later filenames are encoded to UTF-8 (the whole HTML content is encoded to UTF-8).

In practice, you cannot import such .py file, you run them using "python script.py", so we can maybe just ignore modules with undecodable filenames. For example:

def isUndecodableFilename(filename):
  return any((0xD800 <= ord(ch) <= 0xDFFF) for ch in filename)

Or we can escape the surrogate characters, but I don't know how. Write "\uDC80" in a HTML document is not a good idea, especially in an URL (e.g. Firefox replaces \ by / in URLs).

Oops, my isUndecodableFilename() example is wrong. PEP 383 only uses U+DC80..U+DCFF range:

def isUndecodableFilename(filename):
  return any((0xDC80 <= ord(ch) <= 0xDCFF) for ch in filename)

Example of undecodable filename: b'bla\xe9\xff.py' with UTF-8 filesystem encoding is decoded as 'bla\uDCE9\uDCFF.py'.

New changeset 506cab8fc329 by Victor Stinner in branch 'default':
Issue #11186: pydoc ignores a module if its name contains a surrogate character
http://hg.python.org/cpython/rev/506cab8fc329

The wording “pydoc ignores a module” is confusing to me: I can’t tell whether it is a description of the bug (“pydoc ignored a module”) or the new, correct behavior (“pydoc now ignores a module”).

Regarding the problem and fix itself, I’m wondering.  If a user unknowingly creates such a module with an unencodable filename, will they understand why pydoc does not display it?

> If a user unknowingly creates such a module with an unencodable
> filename, will they understand why pydoc does not display it?

It is really a bad idea to choose an *undecodable* name for a module. You will not be able to write its name using "import name" syntax.

(It is possible to import such module using __import__, but it is just ugly)

For the changelog, feel free to rephrase it.

> It is really a bad idea to choose an *undecodable* name for a module.
> You will not be able to write its name using "import name" syntax.

Okay, makes sense that pydoc ignores those.  You speak about a user choosing to create such a filename though; is it possible to create such a name without knowing it?

> For the changelog, feel free to rephrase it.

I don’t currently have SSH access, so please do it.