OP#10283: Say in which way reading a track file failed

The message goes straight to the user, and it claimed the file did not say
which video it belonged to whichever way reading it had failed. A file that
never arrived was reported as one whose metadata was lacking, which sends
whoever reads it looking inside a file that is not there. That is how the
recent CI failure came to be read as a format problem rather than a missing
one.

Missing, unopenable, unparseable and lacking video metadata now each say so.
The parser's own complaint is left out of the unparseable case: ijson quotes
the offending line and points a caret into it, which is a diagram nobody can
read in a popup, and the traceback still carries it to the log.

Also ignore the directory S3_USER_SOURCE stages downloads in, so a stray
`git add -A` cannot commit a bucket's worth of tracks and videos.

Author: randy-seng

.gitignore

@@ -4,6 +4,8 @@ data/
 tests/data/OTCamera19_FR20_2023-05-24*
 tests/scripts/
 .envrc
+# Where S3_USER_SOURCE stages downloaded tracks and videos while running
+.cache-otanalytics/
 
 # Anthropic Claude
 .claude/rules/shared

OTAnalytics/plugin_s3/s3_file_providers.py

@@ -66,15 +66,31 @@ def read_video_name(ottrk: Path) -> str:
         str: the video file name, with extension.
 
     Raises:
-        UnreadableTrackFile: if the file carries no video metadata.
+        UnreadableTrackFile: if the file is missing, cannot be read, or carries
+            no video metadata. Each says which of the three it was, because the
+            message is what the user is shown and they lead to different places
+            to look.
     """
     try:
         metadata = metadata_from_json_events(parse_json_bz2_events(ottrk))
+    except FileNotFoundError as cause:
+        raise UnreadableTrackFile(f"'{ottrk.name}' is missing: {ottrk}.") from cause
+    except OSError as cause:
+        raise UnreadableTrackFile(
+            f"'{ottrk.name}' could not be read: {cause}."
+        ) from cause
+    except ijson.JSONError as cause:
+        # The parser reports the offending line with a caret pointing into it,
+        # which belongs in the log, not in a dialog the user has to read.
+        raise UnreadableTrackFile(
+            f"'{ottrk.name}' is not a valid track file."
+        ) from cause
+    try:
         video = metadata[ottrk_dataformat.VIDEO]
         return str(video[ottrk_dataformat.FILENAME]) + str(
             video[ottrk_dataformat.FILETYPE]
         )
-    except (KeyError, TypeError, OSError, ijson.JSONError) as cause:
+    except (KeyError, TypeError) as cause:
         raise UnreadableTrackFile(
             f"'{ottrk.name}' does not say which video it belongs to."
         ) from cause

tests/unit/OTAnalytics/plugin_s3/test_read_video_name.py

@@ -66,15 +66,50 @@ def test_a_track_file_without_video_metadata_is_reported(
     ) -> None:
         given = create_given(tmp_path, {"metadata": {}})
 
-        with pytest.raises(UnreadableTrackFile):
+        with pytest.raises(UnreadableTrackFile, match="does not say which video"):
             read_video_name(given.ottrk)
 
-    def test_an_unreadable_track_file_is_reported(self, tmp_path: Path) -> None:
+    def test_a_track_file_that_is_not_valid_json_is_reported(
+        self, tmp_path: Path
+    ) -> None:
+        """Naming the content as the problem, not the video metadata."""
+        given = create_given(tmp_path, None)
+
+        with pytest.raises(UnreadableTrackFile, match="is not a valid track file"):
+            read_video_name(given.ottrk)
+
+    def test_a_track_file_that_cannot_be_opened_is_reported(
+        self, tmp_path: Path
+    ) -> None:
+        given = Given(ottrk=tmp_path / "plain.ottrk")
+        given.ottrk.write_bytes(b"not compressed at all")
+
+        with pytest.raises(UnreadableTrackFile, match="could not be read"):
+            read_video_name(given.ottrk)
+
+    def test_every_report_stays_on_one_line(self, tmp_path: Path) -> None:
+        """The message is shown in a dialog, so a parser dump does not belong.
+
+        ijson names the offending line and points a caret into it, which is
+        several lines of diagram nobody can read in a popup.
+        """
         given = create_given(tmp_path, None)
 
-        with pytest.raises(UnreadableTrackFile):
+        with pytest.raises(UnreadableTrackFile) as reported:
             read_video_name(given.ottrk)
 
-    def test_a_missing_track_file_is_reported(self, tmp_path: Path) -> None:
-        with pytest.raises(UnreadableTrackFile):
-            read_video_name(tmp_path / "absent.ottrk")
+        assert "\n" not in str(reported.value)
+
+    def test_a_missing_track_file_says_it_is_missing(self, tmp_path: Path) -> None:
+        """A file that never arrived is a different problem from a corrupt one.
+
+        Reporting it as missing video metadata sends whoever reads the message
+        looking inside a file that is not there.
+        """
+        absent = tmp_path / "absent.ottrk"
+
+        with pytest.raises(UnreadableTrackFile, match="is missing") as reported:
+            read_video_name(absent)
+
+        assert str(absent) in str(reported.value)
+        assert isinstance(reported.value.__cause__, FileNotFoundError)