gh-142411: Change documentation to reflect the new docstring adjustments in 3.13

[decorator-factory]

See issue #142411 for details.

1. Document that compile can now raise UnicodeDecodeError

2. Fix paragraph about docstring indentation in the tutorial. The REPL output was fixed in Docs: Fix indent in controlflow.rst #134008, but the preceding paragraph hasn't been adjusted

I believe this should be backported to 3.13 and 3.14, not sure how that works.

• Issue: Indicate that surrogate literals are not allowed in docstrings since Python 3.13 #142411

---

📚 Documentation preview 📚: https://cpython-previews--142413.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[nedbat]

TIL!

[nedbat]

I wouldn't try to keep this list precise and complete. The exceptions change over time, and it's not like people are going to write except blocks for these specific exceptions. Details are in the versionchanged blocks below. Here can we say that SyntaxError happens if the source is invalid, and other exceptions if the text can't be read in various ways?

[decorator-factory]

I now changed the description to this:

This function raises :exc:`SyntaxError` or :exc:`ValueError` if the compiled source is invalid.

To summarize some things about compile's interface:

• If the source contains null bytes (whether it's a bytes object or a str object), SyntaxError is raised since Python 3.11, and not ValueError, contrary to current documentation.
• If the source is an ast.Module, null bytes and surrogates seem to be allowed (but lead to bizzarre behaviour)
• If the source is a bytes, SyntaxError will be raise if the source is encoded incorrectly
• If the source is valid, -OO is not enabled, and any docstings would have a surrogate, UnicodeDecodeError (subclass of ValueError) is raised

It seems like the error conditions are a bit complicated and may change from version to version, so maybe it's good to keep it a bit opaque? Meaning: if you want to use this function and you expect the input to sometimes be invalid, prepare to catch both SyntaxError and ValueError