curses.setupterm can raise _curses.error

[JulienPalard]

BPO	39433
Nosy	@serhiy-storchaka, @JulienPalard

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['type-bug', 'library'] title = 'curses.setupterm can raise _curses.error' updated_at = user = 'https://github.com/JulienPalard' ``` bugs.python.org fields: ```python activity = actor = 'serhiy.storchaka' assignee = 'none' closed = False closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'mdk' dependencies = [] files = [] hgrepos = [] issue_num = 39433 keywords = [] message_count = 2.0 messages = ['360556', '360596'] nosy_count = 2.0 nosy_names = ['serhiy.storchaka', 'mdk'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'behavior' url = 'https://bugs.python.org/issue39433' versions = [] ```

[JulienPalard]

Currently the curses module can raise some _curses.error exception directly inheriting Exception.

This make it non-trivial for a newcomer to catch (they think they need a from _curses import error, or an except Exception, but in fact error is imported, in curses/__init__.py, in an _curses import *).

The curses.error is documented, but it's not documented that curses.setupterm can raise it and what the user sees on the exception message is "_curses.error" not "curses.error".

Questions:

• Should we create a properly named curse.CurseException, inheriting from _curses.error, so people can slowly migrate to use a "properly" named exception class?
• Should we document that setupterm can raise it?
• Should we introduce a dedicated sphinx directive to document exceptions?

I know the third question opens a whole field of work in the doc, it's only an anecdote but a student of mine pointed out yesterday that the doc is not telling what int() raises when an invalid argument is given. It's obvious for "us", but not for everybody (Yes I can teach it, yes he can just try it, but I'm not behind everyone on earth learning Python, some are learning alone, and I also want them to succeed).

[serhiy-storchaka]

curses.error is documented as an exception raised when a curses library function returns an error. No need to repeat this for every curses function.

It is very uncommon to document all exceptions that can be raised by a particular function in Python. Because of dynamic nature of Python virtually any function can raise arbitrary exception.