Added unique return codes

[fra87]

Added return codes as anticipated in #884

This pull request is the one including the new modifications to main introduced after PR #887

The return codes are now an Enum inheriting from str, so an explicative message can be automatically printed without helper functions.

The return codes are in file returncodes.py

84 new dedicated tests are added to test/core/test_returncodes.py

Documentation has been updated

At the end I run make test, make test_flake8 and make docs. All tests succeeded and flake8 did not report anything. Development and tests were done with Python 3.9.2

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[fra87]

@jmcnamara do you think this can be merged in the main branch or you reconsidered it?

[jmcnamara]

do you think this can be merged in the main branch or you reconsidered it?

I'm worried about backward compatibility so I really need to consider this one carefully before I merge.

[wkschwartz]

One way to maintain backward compatibility would be to replace the Enums with IntEnums.

>>> from enum import IntEnum
>>> class E(IntEnum):
...     A = 0
...     B = -1
...
>>> E.A == 0
True
>>> E.B == -1
True
>>> class F(IntEnum):
...     C = 0
...
>>> F.C == E.A
True
>>> F.C is E.A
False

You can always implement __repr__ or __str__ if you want nice string representations.

[wkschwartz]

I should say though that I find the indication of errors by using warnings and return codes instead of raising exceptions makes using xlsxwriter as a library rather difficult. It means I have to catch warnings and sometimes read the text rather than catching exceptions. If you're going to break backward compatibility, I'd suggest considering making more complete use of (ideally highly specific) exception classes.

[jmcnamara]

@wkschwartz Thanks for the input.

One way to maintain backward compatibility would be to replace the Enums with IntEnums.

Thanks that is interesting.

If you're going to break backward compatibility, I'd suggest considering making more complete use of (ideally highly specific) exception classes.

Yes, if it was to redo the error handling in XlsxWriter then I would probably ditch the return values and go with Exceptions throughout. When I added Exceptions it was from a viewpoint of things that were actually exceptions and some of the more minor warnings don't really fall into that category but maybe I should have just made all warning an exception.

I don't know if I will revisit that though in the future. I may but I may not.

[jmcnamara]

I have circled back to this as part of the XlsxWriter v2 refactoring. See the discussion at: Request for Comments: Refactoring of return values to Enums or Exceptions #1100