Improve exceptions and the error messages

[ikondov]

Closes #568

Summary

Exceptions and error messages should be sufficiently specific to allow the API users decide what exactly did not work and to make corrections (i.e. to handle the exceptions) accordingly. Catching and raising broad exceptions is not helpful for the correct handling.

Major changes:

• feature 1: exception module with basic exceptions:

  • FWError: base exception that may be caught by a handler but not raised
  • FWConfigurationError: exception that can be rased e.g. in fw_config.py
  • FWSerializationError: exception that can be raised e.g. in fw_serializers.py
  • FWFormatError: exception due to unsuported format in file readers
  • FWValueError: specializes to FireWorks but maintains compatibility to ValueError

• fix 1: raise exception when the read content is not a dict but obvious has to be

Disclaimer: The backward compatibility of the API is not fully maintained for all new exceptions. But the messages of all exceptions stay unchanged.

Todos

If this is work in progress, what else needs to be done?

• feature 2:
• fix 2:

Checklist

• Google format doc strings added. Check with ruff.
• Type annotations included. Check with mypy.
• Tests added for new features/fixes.
• If applicable, new classes/functions/modules have duecredit @due.dcite decorators to reference relevant papers by DOI (example)

Tip: Install pre-commit hooks to auto-check types and linting before every commit:

pip install -U pre-commit
pre-commit install

[computron]

Thanks! Can you rename the exceptions either according to:

FWSerializationError (similar to FWAction)
or
FireWorksSerializationError (this is a subtle point, but we have "Firework" be the "Job" and "FireWorks" be the package overall

[ikondov]

@computron Thank you for your prompt response! I hezitate to change everywhere inspecific exceptions are raised. Mainly due to backwards compatibility of the API because user codes may rely on certain type of exceptions. But I did replace ValueError at places it should not be raised and replaced with FWValueError. This will not break any API calls. In the fw_serializable and fw_config modules I changed ValueError to some of the new exceptions. The latter may break some code if ValueError is expected in try-except blocks.

[computron]

The latter may break some code if ValueError is expected in try-except blocks.

I think we are OK since FWValueError inherits from ValueError