RFC: Refactoring of return values to Enums or Exceptions

[jmcnamara]

Request for Comment

The underlying design for error handling in XlsxWriter is that actions that could cause file corruption or an Excel error (such as duplicate worksheet names) are raised as exceptions. Other "recoverable" actions such as writing to a cell beyond the Excel range are ignored and a negative return value is returned along with a warning. The rationale for return codes/warnings was to allow the overall file creation to complete for more harmless input/parameter errors.

In pratice the return code approach isn't useful for folks who want to handle them programattically due to two issues: the first is that the codes aren't obvioius (-1, -2, etc.) and the second is that they don't correspond to the standard Python exception handling idiom.

As part of the XlsxWriter v2 refactoring/improvements I would like to refactor/improve this in one of two ways:

• Replace the return codes with IntEnum values like XlsxWriterWarning.RowColumnOutOfBounds. These can be treated as integers or as literals and allows for backward compatibility. This fixes the return code naming issue.
• Replace the return codes with Exceptions. This is clearly not backward compatible but aligns to the more standard error handling idiom that folks are used to. This will probably cause existing code to break as ignored warnings become exceptions.

I am looking for opinions on this and you can weigh in below if you wish.

See also the previous discussion on this at #892

[wilcoxon]

Personally, I strongly prefer return IntEnum. I'm not a fan of raising Exceptions for non-fatal errors.

[ijustlovemath]

I think the principle of least surprise would dictate exceptions, but that's just me. Raising and handling exceptions is about as Pythonic as it gets (see: how for loops actually work)

[matthew-epg]

I would prefer exceptions, personally. It's pretty easy to write a wrapper that traps the exception and returns an error code, for compatibility with old code.