python/tskit/util.py: Add a file name to FileFormatError

[alxsimon]

Closes #2467
Uses the .add_note method of exception, introduced in Python 3.11. Also hardcodes the file name in
the raised from exceptions for HDF5 or zip.
Until 3.10 is EOF, needs the sys module.

Description

Would fix #2467

I'll tidy up (changelog and linting) if you think this change is ok.

PR Checklist:

• Tests that fully cover new/changed functionality.
• Documentation including tutorial content if appropriate.
• Changelogs, if there are API changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.33%. Comparing base (b7fd993) to head (a2c1361).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3366      +/-   ##
==========================================
+ Coverage   89.76%   90.33%   +0.56%     
==========================================
  Files          29       28       -1     
  Lines       31292    25694    -5598     
  Branches     5738     4742     -996     
==========================================
- Hits        28089    23210    -4879     
+ Misses       1794     1367     -427     
+ Partials     1409     1117     -292     

Flag	Coverage Δ
c-tests	86.77% <ø> (ø)
lwt-tests	80.38% <ø> (ø)
python-c-tests	?
python-tests	98.82% <100.00%> (-0.03%)	⬇️
python-tests-no-jit	33.51% <0.00%> (-0.01%)	⬇️
python-tests-numpy1	50.27% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/tskit/util.py	99.28% <100.00%> (+<0.01%)	⬆️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jeromekelleher]

LGTM. Can we add a unit test please, checking that the filename goes into the exception as expected, and validating what happens when we use something that doesn't have a name? (Although, it's not obvious to me how you could have a seekable stream that doesn't have a name, but we need to do due diligence here.)

You can pytest.skip for Python < 310.

@benjeffery shall we just ditch Python 3.10 altogether?

[alxsimon]

LGTM. Can we add a unit test please, checking that the filename goes into the exception as expected, and validating what happens when we use something that doesn't have a name? (Although, it's not obvious to me how you could have a seekable stream that doesn't have a name, but we need to do due diligence here.)

You can pytest.skip for Python < 310.

@benjeffery shall we just ditch Python 3.10 altogether?

Thanks for taking a look, I've trying modifying the existing tests in test_utils.py.
I'm not sure if you'd prefer some dedicated tests that don't touch the existing ones? Especially if we consider keeping some skip for python 3.11 (which I guess would skip each test with the modification for this version of Python).

I could use some pointers on how to test the stream side of things, where should it go and how do you generally do this?

[jeromekelleher]

I think we're going to drop 3.10 ASAP, so let's not worry about the failures on 3.10 CI (and we can remove the conditional at the top). The tests you have look good, updating the existing ones here is fine (although may not need to check the filename on every downstream check for FileFormatError (as that's not what most of the tests are about).

Have a look at tests/test_fileobj.py for what happens in the stream case and see what kind of error messages we get.

[alxsimon]

Thanks, reduced the number of tests of FileFormatError.

In the TestBadStream, the error_text for matching does not seem to be used as modifying it to something that shouldn't be in the error does not fail the test.

For instance:

    def test_bad_stream(self, tmp_path):
        fifo_path = tmp_path / "fifo"
        bad_file_path = tmp_path / "bad_file"
        bad_file_path.write_bytes(b"bad data")
        write_and_read_from_fifo(
            fifo_path, bad_file_path, tskit.FileFormatError, "foo"
        )

Still passes