Are these two statements in the docs correct?

Documentation
1

I noticed two statements in the Python documentation that I find incorrect/misleading. I’m wondering if they are worth creating issues – so let me list them here, first…

(1) Availability of exception information in finally block

In the “8.4.4. finally clause” section of the language reference, we can read that:

The exception information is not available to the program during execution of the finally clause.

…whereas the exception information is available from within finally – by using sys.exception()/sys.exc_info():

>>> try:
...     1/0
... finally:           
...     sys.exc_info()
...     
(<class 'ZeroDivisionError'>, ZeroDivisionError('division by zero'), <traceback object at 0x7baed9b7ec40>)
Traceback (most recent call last):
  File "<python-input-4>", line 2, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero

Of course, it is true that the finally clause does not provide any syntactic construct equivalent to the except’s as ... one – but is that worth being stated in the docs? (and if it is, it should be more specific then, I belive)

(2) sys.displayhook() availability impact on repr()

In the repr() built-in function description, we can read that:

A class can control what this function returns for its instances by defining a __repr__() method. If sys.displayhook() is not accessible, this function will raise RuntimeError.

I guess I get the intent: if there is no sys.displayhook() callable (e.g., because del sys.displayhook has been executed) then RuntimeError is raised. But it would have no impact on repr() behavior at all. In fact, the relation is the opposite: a problem during repr() execution can influence the behavior of sys.displayhook() (at least if the implementation of the latter makes use of the former, which typically is the case). However, IMHO, none of these facts are worth mentioning specifically in the description of the repr() function.

PS All “–” dashes were entered with Alt+-, no AI was used. :slight_smile:

2 Likes
2

I think you’re right on both counts.

The statement about repr() probably means to talk about the effect on the REPL:

>>> import sys
>>> del sys.displayhook
>>> 3
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    3
RuntimeError: lost sys.displayhook

But that’s REPL behavior; the repr() function itself doesn’t interact with sys.displayhook at all, and its docs don’t need to mention it.

2 Likes