Further improve error and warning infrastructure

[tovrstra]

Here is another PR corresponding to two tasks in #191, i.e. to make all warnings and errors consistent with the previous PR that improved the LoadError logic: #345. It was difficult to split this up in one PR per error or warning class because they make use of the same machinery.

Main improvements:

• Where relevant, all file-related warnings and errors mention the file (and line number). The LineIterator methods for errors and warnings are gone.
• Warnings are now raised with the correct stacklevel. (For more details, see https://docs.python.org/3/library/warnings.html#warnings.warn and https://stackoverflow.com/a/71635963/494584)

Related points deferred to later pull requests:

• Update of the dump_* sections in CONTRIBUTING.md. This will be done after the prepare_dump API has been completed.

I will YOLO-merge this on Friday, June 28, unless reviewed earlier.

Summary by Sourcery

This pull request improves the error and warning infrastructure by standardizing messages to include file and line number information, introducing base classes for file-related errors and warnings, and refactoring functions to handle warnings more effectively. It also updates the prepare_dump function signatures and adds tests for the new warning behaviors.

• Enhancements:
  • Standardized error and warning messages to include file and line number information where relevant.
  • Introduced a base class for file-related errors and warnings to streamline error handling.
  • Updated the prepare_dump function signatures to include the filename parameter for better error context.
  • Implemented a decorator to correct the stack level of warnings raised in deeper function calls.
  • Refactored the LineIterator class to remove the warn method and handle warnings directly using the warn function.
• Tests:
  • Added tests to ensure warnings are raised correctly when loading files with unrecognized elements or bond types.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request improves the error and warning infrastructure by making all warnings and errors consistent with the previous PR that improved the 'LoadError' logic. Key changes include adding 'filename' parameters to various functions for better error messages, replacing 'warn' calls with 'LoadWarning' instances, and introducing helper functions and base classes for errors and warnings. Additionally, the '_reissue_warnings' decorator was applied to several API functions to correct the stacklevel of warnings.

File-Level Changes

Files	Changes
iodata/formats/json.py iodata/formats/molden.py iodata/formats/wfx.py iodata/formats/pdb.py iodata/formats/molekel.py iodata/formats/wfn.py iodata/formats/fchk.py iodata/formats/mol2.py	Updated various functions to include 'filename' parameter for error messages and replaced 'warn' calls with 'LoadWarning' instances.
iodata/utils.py iodata/api.py	Introduced helper functions and base classes for errors and warnings, and applied '_reissue_warnings' decorator to API functions.
iodata/test/test_mol2.py iodata/test/test_iodata.py	Added tests for new warning and error handling logic.

---

Tips

• Trigger a new Sourcery review by commenting @sourcery-ai review on the pull request.
• You can change your review settings at any time by accessing your dashboard:
  • Enable or disable the Sourcery-generated pull request summary or reviewer's guide;
  • Change the review language;
• You can always contact us if you have any questions or feedback.

[deepsource-io]

Here's the code health analysis summary for commits b5bccd9..fd0f2ea. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
Shell	✅ Success		View Check ↗
Python	✅ Success	🎯 2 occurences resolved	View Check ↗

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[sourcery-ai]

Hey @tovrstra - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟡 Testing: 2 issues found
• 🟡 Complexity: 1 issue found
• 🟡 Documentation: 1 issue found

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment to tell me if it was helpful.}

[PaulWAyers]

I just skimmed it but I think you can merge it after a final read-through, Toon.

[tovrstra]

Thanks for reviewing, Paul. I've gone through it and spotted some very minor things. I'll merge right away.