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

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.

Author: Alexis Simon

.gitignore

@@ -7,3 +7,6 @@ python/benchmark/*.html
 .env
 .vscode
 env
+# pixi environments
+.pixi/*
+!.pixi/config.toml

python/.gitignore

@@ -5,3 +5,6 @@ build
 .*.swp
 .*.swo
 */.ipynb_checkpoints
+# pixi environments
+.pixi/*
+!.pixi/config.toml

python/tests/test_file_format.py

@@ -261,12 +261,12 @@ def test_format_too_old_raised_for_hdf5(self):
 
             with pytest.raises(
                 exceptions.FileFormatError,
-                match="appears to be in HDF5 format",
+                match=f"{filename}.*appears to be in HDF5 format",
             ):
                 tskit.load(path)
             with pytest.raises(
                 exceptions.FileFormatError,
-                match="appears to be in HDF5 format",
+                match=f"{filename}.*appears to be in HDF5 format",
             ):
                 tskit.TableCollection.load(path)
 
@@ -284,9 +284,15 @@ class TestErrors(TestFileFormat):
     def test_tszip_file(self):
         ts = msprime.simulate(5)
         tszip.compress(ts, self.temp_file)
-        with pytest.raises(tskit.FileFormatError, match="appears to be in zip format"):
+        with pytest.raises(
+            tskit.FileFormatError,
+            match=f"{self.temp_file}.*appears to be in zip format",
+        ):
             tskit.load(self.temp_file)
-        with pytest.raises(tskit.FileFormatError, match="appears to be in zip format"):
+        with pytest.raises(
+            tskit.FileFormatError,
+            match=f"{self.temp_file}.*appears to be in zip format",
+        ):
             tskit.TableCollection.load(self.temp_file)
 
 
@@ -781,7 +787,10 @@ def verify_equal_length_columns(self, ts, table):
                 data = dict(all_data)
                 data[col] = bad_val
                 kastore.dump(data, self.temp_file)
-                with pytest.raises(exceptions.FileFormatError):
+                with pytest.raises(
+                    exceptions.FileFormatError,
+                    match=f"While trying to load {self.temp_file}",
+                ):
                     tskit.load(self.temp_file)
 
     def test_equal_length_columns(self):
@@ -805,7 +814,10 @@ def verify_offset_columns(self, ts):
             for bad_col_length in [[], range(2 * num_rows)]:
                 data[offset_col] = bad_col_length
                 kastore.dump(data, self.temp_file)
-                with pytest.raises(exceptions.FileFormatError):
+                with pytest.raises(
+                    exceptions.FileFormatError,
+                    match=f"While trying to load {self.temp_file}",
+                ):
                     tskit.load(self.temp_file)
 
             # Check for a bad offset
@@ -853,13 +865,17 @@ def test_index_columns(self):
         data = dict(all_data)
         data[edge_insertion_order] = data[edge_insertion_order][:1]
         kastore.dump(data, self.temp_file)
-        with pytest.raises(exceptions.FileFormatError):
+        with pytest.raises(
+            exceptions.FileFormatError, match=f"While trying to load {self.temp_file}"
+        ):
             tskit.load(self.temp_file)
 
         data = dict(all_data)
         data[edge_removal_order] = data[edge_removal_order][:1]
         kastore.dump(data, self.temp_file)
-        with pytest.raises(exceptions.FileFormatError):
+        with pytest.raises(
+            exceptions.FileFormatError, match=f"While trying to load {self.temp_file}"
+        ):
             tskit.load(self.temp_file)
 
     def test_load_empty_kastore(self):
@@ -897,7 +913,10 @@ def test_format_name_error(self):
                 data = dict(store)
             data["format/name"] = np.array(bytearray(bad_name.encode()), dtype=np.int8)
             kastore.dump(data, self.temp_file)
-            with pytest.raises(exceptions.FileFormatError):
+            with pytest.raises(
+                exceptions.FileFormatError,
+                match=f"While trying to load {self.temp_file}",
+            ):
                 tskit.load(self.temp_file)
 
     def test_load_bad_formats(self):
@@ -908,12 +927,16 @@ def test_load_bad_formats(self):
         # Now some ascii text
         with open(self.temp_file, "wb") as f:
             f.write(b"Some ASCII text")
-        with pytest.raises(exceptions.FileFormatError):
+        with pytest.raises(
+            exceptions.FileFormatError, match=f"While trying to load {self.temp_file}"
+        ):
             tskit.load(self.temp_file)
         # Now write 8k of random bytes
         with open(self.temp_file, "wb") as f:
             f.write(os.urandom(8192))
-        with pytest.raises(exceptions.FileFormatError):
+        with pytest.raises(
+            exceptions.FileFormatError, match=f"While trying to load {self.temp_file}"
+        ):
             tskit.load(self.temp_file)
 
     def test_load_bad_formats_fileobj(self):
@@ -925,7 +948,9 @@ def load():
             load()
         with open(self.temp_file, "wb") as f:
             f.write(b"Some ASCII text")
-        with pytest.raises(exceptions.FileFormatError):
+        with pytest.raises(
+            exceptions.FileFormatError, match=f"While trying to load {self.temp_file}"
+        ):
             load()
 
 
@@ -978,7 +1003,9 @@ def test_ts_twofile_stream_fails(self, tmp_path, ts_fixture):
             ts_fixture.dump(f)
         with open(save_path, "rb") as f:
             tskit.load(f, skip_tables=True)
-            with pytest.raises(exceptions.FileFormatError):
+            with pytest.raises(
+                exceptions.FileFormatError, match=f"While trying to load {save_path}"
+            ):
                 tskit.load(f)
 
     def test_table_collection_load_path(self, tmp_path, ts_fixture):
@@ -1033,7 +1060,9 @@ def test_ts_twofile_stream_fails(self, tmp_path, ts_fixture):
             ts_fixture.dump(f)
         with open(save_path, "rb") as f:
             tskit.load(f, skip_reference_sequence=True)
-            with pytest.raises(exceptions.FileFormatError):
+            with pytest.raises(
+                exceptions.FileFormatError, match=f"While trying to load {save_path}"
+            ):
                 tskit.load(f)
 
     def test_table_collection_load_path(self, tmp_path, ts_fixture):

python/tskit/util.py

@@ -30,6 +30,7 @@
 import json
 import numbers
 import os
+import sys
 import textwrap
 from typing import Union
 
@@ -878,6 +879,10 @@ def raise_known_file_format_errors(open_file, existing_exception):
     Sniffs the file for pk-zip or hdf header bytes, then raises an exception
     if these are detected, if not raises the existing exception.
     """
+    if sys.version_info[0] >= 3 and sys.version_info[1] > 10:
+        # add_note has been added in python 3.11
+        # This condition can be removed once 3.10 is end-of-life
+        existing_exception.add_note(f"While trying to load {open_file.name}")
     # Check for HDF5 header bytes
     try:
         open_file.seek(0)
@@ -887,16 +892,16 @@ def raise_known_file_format_errors(open_file, existing_exception):
         raise existing_exception
     if header == b"\x89HDF":
         raise tskit.FileFormatError(
-            "The specified file appears to be in HDF5 format. This file "
+            f"The file {open_file.name} appears to be in HDF5 format. This file "
             "may have been generated by msprime < 0.6.0 (June 2018) which "
             "can no longer be read directly. Please convert to the new "
             "kastore format using the ``tskit upgrade`` command from tskit version<0.6.2"
         ) from existing_exception
     if header[:2] == b"\x50\x4b":
         raise tskit.FileFormatError(
-            "The specified file appears to be in zip format, so may be a compressed "
-            "tree sequence. Try using the tszip module to decompress this file before "
-            "loading. `pip install tszip; tsunzip <filename>` or use "
+            f"The file {open_file.name} appears to be in zip format, so may be a "
+            "compressed tree sequence. Try using the tszip module to decompress this "
+            "file before loading. `pip install tszip; tsunzip <filename>` or use "
             "`tszip.decompress` in Python code."
         ) from existing_exception
     raise existing_exception