OTAnalytics 0.7.4__tar.gz → 0.7.5__tar.gz

otanalytics-0.7.5/.github/workflows/system-test.yml

@@ -0,0 +1,34 @@
+---
+name: System Test With Pytest
+
+on:
+  # Run tests each time a PR is opened or changed.
+  # Allow other Workflows (e.g., build workflows) to call this workflow.
+  pull_request:
+  workflow_call:
+
+permissions: read-all
+
+jobs:
+  test:
+    name: Execute system tests across various operating systems and Python versions.
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        py: ["3.12"]
+      fail-fast: true
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.py }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.py }}
+      - name: Run Python System Tests
+        uses: platomo/test-python-app-action@v4
+        timeout-minutes: 60
+        with:
+          py-version: ${{ matrix.py }}
+          package-path: OTAnalytics
+          test-path: tests/system

{otanalytics-0.7.4 → otanalytics-0.7.5}/.github/workflows/test.yml

@@ -25,7 +25,7 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.py }}
-      - name: Run Python Tests
+      - name: Run Python Unit Tests
         uses: platomo/test-python-app-action@v4
         timeout-minutes: 60
         with:

{otanalytics-0.7.4 → otanalytics-0.7.5}/.gitignore

@@ -3,6 +3,12 @@ data/
 !tests/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
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

{otanalytics-0.7.4 → otanalytics-0.7.5}/.pre-commit-config.yaml

@@ -47,6 +47,7 @@ repos:
           - interrogate==1.7.0
           - isort==6.0.1
           - matplotlib==3.10.0
+          - minio==7.2.20
           - more-itertools==10.7.0
           - mypy==1.16.1
           - nicegui==2.24.1
@@ -66,8 +67,11 @@ repos:
           - pytest-timeout==2.4.0
           - pytest==8.3.4
           - starlette==0.49.1
+          - testcontainers==4.13.1
           - twine==6.2.0
           - types-PyYAML
+          - types-aioboto3
+          - types-aiobotocore-s3==2.26.0
           - types-flake8
           - types-openpyxl
           - types-pillow

otanalytics-0.7.5/CONTEXT.md

@@ -0,0 +1,56 @@
+# OTAnalytics
+
+Traffic analysis on road user trajectories: OTAnalytics loads Tracks recorded by
+OTVision, lets a user define Sections and Flows over them, and counts the road
+users crossing those Sections.
+
+## Language
+
+### Obtaining input files
+
+**Transfer Mode**:
+Where an OTAnalytics instance obtains its Track and Video files — the local
+filesystem, or an S3 bucket. Fixed for the lifetime of the process by the
+startup configuration; it is not something a user switches while working.
+_Avoid_: storage backend, data source (both suggest a per-load choice).
+
+**Startup Configuration**:
+The environment variables naming the Transfer Mode and, in S3 mode, the bucket
+and credentials. Fixed for the lifetime of the process. Deliberately not a file.
+Says what a deployment may authenticate to, never which project it holds: the
+Key Prefix comes from the **otconfig** instead, because that is per-project and
+varies per lease. Credentials must never travel in an otconfig, since users save
+and share those files.
+_Avoid_: config file (there isn't one, and it invites confusion with otconfig).
+
+**Key Prefix**:
+The S3 prefix a project's Tracks and Videos live under, covering one camera or
+site. A property of the project, declared by its otconfig, and required there in
+S3 mode — so opening a different project moves where an instance reads from,
+within the one configured bucket. Until a project is loaded there is no Key
+Prefix and nothing can be listed.
+_Avoid_: path, folder (S3 has neither); startup configuration (it is per-project,
+unlike the bucket and credentials).
+
+**User Source**:
+The local directory that downloaded objects are written into, mirroring their S3
+keys, so that a Track file and its Video land side by side. Named after
+OTCloud's `S3_USER_SOURCE` for cross-repo consistency, though the name conveys
+little on its own. Its contents do not survive a restart.
+_Avoid_: cache (implies reuse across runs, which there is none of).
+
+**Load Window**:
+The start and end time a user selects to decide which Tracks and Videos to load.
+Bounded by a configured maximum duration, because continuous processing produces
+far more data than can be held at once. An over-long selection is _clamped_ —
+its end snaps to the maximum and the user is told — never rejected.
+_Avoid_: time range, date range (`DateRange` already means the filter applied to
+already-loaded Tracks, which is a different thing).
+
+**Track File Provider** / **Video File Provider**:
+What a request for input files is asked of. Each implementation owns its own way
+of asking the user, so nothing downstream knows where files came from: the local
+one opens a file chooser, the S3 one asks for a Load Window and downloads. This
+is the seam that makes the Transfer Mode interchangeable.
+_Avoid_: file loader, importer (both suggest they also parse, which they do not —
+they only obtain paths).

{otanalytics-0.7.4 → otanalytics-0.7.5}/OTAnalytics/adapter_ui/dummy_viewmodel.py

@@ -3,7 +3,7 @@ import functools
 from datetime import datetime
 from pathlib import Path
 from time import sleep
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Iterable, Optional, Sequence
 
 from OTAnalytics.adapter_ui.abstract_button_quick_save_config import (
     AbstractButtonQuickSaveConfig,
@@ -33,6 +33,7 @@ from OTAnalytics.adapter_ui.default_values import (
     RELATIVE_SECTION_OFFSET,
     SUPPORTED_FORMATS,
 )
+from OTAnalytics.adapter_ui.file_export_dto import ExportFileDto
 from OTAnalytics.adapter_ui.flow_adapter import (
     GeometricCenterCalculator,
     InnerSegmentsCenterCalculator,
@@ -61,6 +62,7 @@ from OTAnalytics.application.application import (
 )
 from OTAnalytics.application.config import (
     CONTEXT_FILE_TYPE_EVENTS,
+    CONTEXT_FILE_TYPE_ROAD_USER_ASSIGNMENTS,
     CONTEXT_FILE_TYPE_TRACK_STATISTICS,
     CUTTING_SECTION_MARKER,
     OTCONFIG_FILE_TYPE,
@@ -68,7 +70,10 @@ from OTAnalytics.application.config import (
 )
 from OTAnalytics.application.export_formats.export_mode import OVERWRITE
 from OTAnalytics.application.logger import logger
-from OTAnalytics.application.parser.config_parser import StartDateMissing
+from OTAnalytics.application.parser.config_parser import (
+    StartDateMissing,
+    SubstitutedFile,
+)
 from OTAnalytics.application.parser.flow_parser import FlowParser
 from OTAnalytics.application.playback import SkipTime
 from OTAnalytics.application.project import (
@@ -88,6 +93,7 @@ from OTAnalytics.application.project import (
     SvzMetadata,
     WeatherType,
 )
+from OTAnalytics.application.project_location import UnsupportedProjectLocation
 from OTAnalytics.application.use_cases.config import ConfigValidationError
 from OTAnalytics.application.use_cases.config_has_changed import NoExistingConfigFound
 from OTAnalytics.application.use_cases.cut_tracks_with_sections import CutTracksDto
@@ -97,11 +103,17 @@ from OTAnalytics.application.use_cases.editor.section_editor import (
     UpdateSectionCoordinates,
 )
 from OTAnalytics.application.use_cases.export_events import (
+    EventExportSpecification,
     EventListExporter,
     ExporterNotFoundError,
 )
 from OTAnalytics.application.use_cases.flow_repository import FlowAlreadyExists
 from OTAnalytics.application.use_cases.generate_flows import FlowNameGenerator
+from OTAnalytics.application.use_cases.load_otconfig import UnableToLoadOtconfigFile
+from OTAnalytics.application.use_cases.provide_input_files import (
+    ProvideTrackFiles,
+    ProvideVideoFiles,
+)
 from OTAnalytics.application.use_cases.quick_save_configuration import (
     NoExistingFileToSave,
 )
@@ -109,6 +121,7 @@ from OTAnalytics.application.use_cases.road_user_assignment_export import (
     ExportSpecification,
 )
 from OTAnalytics.application.use_cases.save_otflow import NoSectionsToSave
+from OTAnalytics.application.use_cases.suggest_save_path import SavePathSuggestion
 from OTAnalytics.application.use_cases.track_statistics_export import (
     TrackStatisticsExportSpecification,
 )
@@ -140,12 +153,27 @@ from OTAnalytics.domain.types import EventType
 from OTAnalytics.domain.video import Video, VideoListObserver
 
 MESSAGE_CONFIGURATION_NOT_SAVED = "The configuration has not been saved.\n"
-SUPPORTED_VIDEO_FILE_TYPES = [".mp4", ".avi", ".mkv", ".mov"]
+MESSAGE_CONFIGURATION_NOT_LOADED = "The configuration has not been loaded.\n"
+MESSAGE_CONFIGURATION_FILES_SUBSTITUTED = (
+    "The configuration references files that were not found.\n"
+)
 LINE_SECTION: str = "line_section"
 TO_SECTION = "to_section"
 FROM_SECTION = "from_section"
 
 
+def _explain(cause: BaseException) -> str:
+    """Name the underlying failure, not the wrapper.
+
+    `UnableToLoadOtconfigFile` carries a fixed string and keeps the real reason
+    in `__cause__`, so reporting the wrapper alone tells the user nothing they
+    can act on.
+    """
+    if cause.__cause__ is not None:
+        return f"{cause} {cause.__cause__}"
+    return f"{cause}"
+
+
 class MissingInjectedInstanceError(Exception):
     """Raise when no instance of an object was injected before referencing it"""
 
@@ -310,9 +338,13 @@ class DummyViewModel(
         show_svz: bool,
         add_new_section: AddNewSection,
         update_section_coordinates: UpdateSectionCoordinates,
+        provide_track_files: ProvideTrackFiles,
+        provide_video_files: ProvideVideoFiles,
     ) -> None:
         self._application = application
         self._ui_factory = ui_factory
+        self._provide_track_files = provide_track_files
+        self._provide_video_files = provide_video_files
         self._flow_parser: FlowParser = flow_parser
         self._name_generator = name_generator
         self._event_list_export_formats = event_list_export_formats
@@ -553,24 +585,7 @@ class DummyViewModel(
         self._update_enabled_video_buttons()
 
     async def add_video(self) -> None:
-        # Generate extension_options dynamically from SUPPORTED_VIDEO_FILE_TYPES
-        extension_options: Dict[str, Optional[List[str]]] = {}
-
-        # Convert "*.ext" format to ".ext" format for extension_options
-        clean_extensions = [ext for ext in SUPPORTED_VIDEO_FILE_TYPES]
-
-        # Add "All File Endings" option with all supported extensions
-        extension_options["All File Endings"] = clean_extensions
-
-        # Add individual extension options
-        for ext in clean_extensions:
-            extension_options[ext] = [ext]
-
-        video_files = await self._ui_factory.askopenfilenames(
-            title="Load video files",
-            filetypes=[("video file", SUPPORTED_VIDEO_FILE_TYPES)],
-            extension_options=extension_options,
-        )
+        video_files = await self._provide_video_files.provide()
         if not video_files:
             return
         logger().info(f"Video files to load: {video_files}")
@@ -611,19 +626,25 @@ class DummyViewModel(
         self.frame_project.update(name=project.name, start_date=project.start_date)
 
     async def save_otconfig(self) -> None:
-        suggested_save_path = self._application.suggest_save_path(OTCONFIG_FILE_TYPE)
+        save_suggestion = self._application.suggest_save_path(OTCONFIG_FILE_TYPE)
+        if self._application.get_current_key_prefix() is not None:
+            # A project that names a location was opened by an operator naming
+            # it, not chosen from a picker (OP#10323 decision 1), so it always
+            # re-saves to its own name and place with no new UI.
+            await self._save_otconfig(save_suggestion.file_path)
+            return
         configuration_file = await self._ui_factory.ask_for_save_file_path(
             title="Save configuration as",
             filetypes=[(f"{OTCONFIG_FILE_TYPE} file", f"*.{OTCONFIG_FILE_TYPE}")],
             defaultextension=f".{OTCONFIG_FILE_TYPE}",
-            initialfile=suggested_save_path.name,
-            initialdir=suggested_save_path.parent,
+            initialfile=save_suggestion.file_path.name,
+            initialdir=save_suggestion.save_directory,
         )
         if not configuration_file:
             return
-        self._save_otconfig(configuration_file)
+        await self._save_otconfig(configuration_file)
 
-    def _save_otconfig(self, otconfig_file: Path) -> None:
+    async def _save_otconfig(self, otconfig_file: Path) -> None:
         # Ensure the file has the correct extension
         otconfig_file_str = ensure_file_extension_is_present(
             str(otconfig_file), [f"*.{OTCONFIG_FILE_TYPE}"], f".{OTCONFIG_FILE_TYPE}"
@@ -632,7 +653,7 @@ class DummyViewModel(
 
         logger().info(f"Config file to save: {otconfig_file}")
         try:
-            self._application.save_otconfig(otconfig_file)
+            await self._application.save_otconfig(otconfig_file)
         except NoSectionsToSave:
             message = (
                 f"{MESSAGE_CONFIGURATION_NOT_SAVED}"
@@ -692,9 +713,9 @@ class DummyViewModel(
         )
         if not otconfig_file:
             return
-        self._load_otconfig(otconfig_file)
+        await self._load_otconfig(otconfig_file)
 
-    def _load_otconfig(self, otconfig_file: Path) -> None:
+    async def _load_otconfig(self, otconfig_file: Path) -> None:
         proceed = self._ui_factory.info_box(
             message=(
                 "This will load a stored configuration from file. \n"
@@ -707,10 +728,73 @@ class DummyViewModel(
         if proceed.canceled:
             return
         logger().info(f"{OTCONFIG_FILE_TYPE} file to load: {otconfig_file}")
-        self._application.load_otconfig(file=Path(otconfig_file))
+        try:
+            await self._application.load_otconfig_async(file=Path(otconfig_file))
+        except (
+            UnableToLoadOtconfigFile,
+            UnsupportedProjectLocation,
+            OSError,
+        ) as cause:
+            # A file the config references is missing, the config contradicts
+            # itself, or its data lives where this installation cannot read it.
+            # All are the user's to act on, so name the cause.
+            self._report_load_failure(_explain(cause))
+            return
+        except Exception as cause:
+            # The boundary of a user action: without this, a malformed config
+            # reaches the browser as a traceback. The traceback still logs.
+            logger().exception("Failed to load configuration file", exc_info=cause)
+            self._report_load_failure("An unexpected error occurred.")
+            return
         self.show_current_project()
         self.update_svz_metadata_view()
 
+    def report_substituted_files(
+        self, substitutions: Sequence[SubstitutedFile]
+    ) -> None:
+        """Tell the user which references were rebound while loading.
+
+        The parser resolves a missing reference to a same-named file beside the
+        otconfig. The names match but the contents need not: re-detected or
+        re-tracked output reuses the filename with different detections. So the
+        project is loaded, and the user is told what it actually holds.
+        """
+        if not substitutions:
+            return
+        rebound = "\n".join(
+            f"• '{substitution.requested}' → '{substitution.used}'"
+            for substitution in substitutions
+        )
+        self._tell_user(
+            f"{MESSAGE_CONFIGURATION_FILES_SUBSTITUTED}"
+            f"The files below were not found where the configuration says, so a "
+            f"file of the same name next to the configuration was loaded "
+            f"instead. Check that this is the data you meant:\n{rebound}"
+        )
+
+    def _report_load_failure(self, reason: str) -> None:
+        self._tell_user(f"{MESSAGE_CONFIGURATION_NOT_LOADED}{reason}")
+
+    def _tell_user(self, message: str) -> None:
+        """Log a message and show it if the ui can be reached.
+
+        Reporting must never break what it reports on. Nicegui resolves the
+        client through the slot stack and raises when that stack is empty, so
+        `info_box` fails whenever no browser is attached — during the startup
+        preload of a `--config` file, for one. Left unguarded, reporting a
+        substitution there would propagate out of the parse and stop the server
+        from starting. The log is the guarantee; the box is best effort.
+        """
+        logger().warning(message)
+        try:
+            self._ui_factory.info_box(
+                message=message, initial_position=self._get_window_position()
+            )
+        except Exception as cause:
+            logger().exception(
+                "Could not show this message to the user", exc_info=cause
+            )
+
     def set_tracks_frame(self, frame: AbstractFrame) -> None:
         self._frame_tracks = frame
 
@@ -815,17 +899,11 @@ class DummyViewModel(
 
     @action
     async def load_tracks(self) -> None:
-        track_files = await self._ui_factory.askopenfilenames(
-            title="Load track files",
-            filetypes=[
-                ("tracks file", "*.ottrk"),
-            ],
-        )
+        track_files = await self._provide_track_files.provide()
         if not track_files:
             return
         logger().info(f"Tracks files to load: {track_files}")
-        track_paths = [Path(file) for file in track_files]
-        self._application.add_tracks_of_files(track_files=track_paths)
+        await self._application.add_tracks_of_files_async(track_files=track_files)
 
     async def load_configuration(self) -> None:  # sourcery skip: avoid-builtin-shadow
         # INFO: Current behavior: Overwrites existing sections
@@ -844,7 +922,7 @@ class DummyViewModel(
         elif configuration_file.suffix == f".{OTFLOW_FILE_TYPE}":
             self._load_otflow(configuration_file)
         elif configuration_file.suffix == f".{OTCONFIG_FILE_TYPE}":
-            self._load_otconfig(configuration_file)
+            await self._load_otconfig(configuration_file)
         else:
             raise ValueError("Configuration file to load has unknown file extension")
 
@@ -870,7 +948,13 @@ class DummyViewModel(
         self.refresh_items_on_canvas()
 
     async def save_configuration(self) -> None:
-        suggested_save_path = self._application.suggest_save_path(OTCONFIG_FILE_TYPE)
+        save_suggestion = self._application.suggest_save_path(OTCONFIG_FILE_TYPE)
+        if self._application.get_current_key_prefix() is not None:
+            # A project that names a location is always an otconfig and always
+            # re-saves to its own name and place with no new UI (OP#10323
+            # decision 1 & 5).
+            await self._save_otconfig(save_suggestion.file_path)
+            return
         configuration_file = await self._ui_factory.ask_for_save_file_path(
             title="Save configuration as",
             filetypes=[
@@ -878,8 +962,8 @@ class DummyViewModel(
                 (f"{OTFLOW_FILE_TYPE} file", f"*.{OTFLOW_FILE_TYPE}"),
             ],
             defaultextension=f".{OTCONFIG_FILE_TYPE}",
-            initialfile=suggested_save_path.name,
-            initialdir=suggested_save_path.parent,
+            initialfile=save_suggestion.file_path.name,
+            initialdir=save_suggestion.save_directory,
         )
         if not configuration_file.stem:
             return
@@ -895,13 +979,13 @@ class DummyViewModel(
         if configuration_file.suffix == f".{OTFLOW_FILE_TYPE}":
             self._save_otflow(configuration_file)
         elif configuration_file.suffix == f".{OTCONFIG_FILE_TYPE}":
-            self._save_otconfig(configuration_file)
+            await self._save_otconfig(configuration_file)
         else:
             raise ValueError("Configuration file to save has unknown file extension")
 
     async def quick_save_configuration(self) -> None:
         try:
-            self._application.quick_save_configuration()
+            await self._application.quick_save_configuration()
         except NoExistingFileToSave:
             await self.save_configuration()
 
@@ -1389,33 +1473,40 @@ class DummyViewModel(
             for key, exporter in self._event_list_export_formats.items()
         }
         try:
-            event_list_exporter, file = await self._configure_event_exporter(
+            event_list_exporter, export_config = await self._configure_event_exporter(
                 export_format_extensions
             )
-            self._application.export_events(Path(file), event_list_exporter)
+            specification = EventExportSpecification(
+                export_directory=export_config.export_directory,
+                export_filename_stem=export_config.file_stem,
+                export_mode=OVERWRITE,
+            )
+            self._application.export_events(specification, event_list_exporter)
             logger().info(
-                f"Exporting eventlist using {event_list_exporter.get_name()} to {file}"
+                f"Exporting eventlist using {event_list_exporter.get_name()} to "
+                f"{export_config.as_file_path()}"
             )
         except CancelExportFile:
             logger().info("User canceled configuration of export")
 
     async def _configure_event_exporter(
         self, export_format_extensions: dict[str, str]
-    ) -> tuple[EventListExporter, Path]:
+    ) -> tuple[EventListExporter, ExportFileDto]:
         export_config = await self._ui_factory.configure_export_file(
             title="Export events",
             export_format_extensions=export_format_extensions,
-            initial_file_stem=CONTEXT_FILE_TYPE_EVENTS,
+            context_file_type=CONTEXT_FILE_TYPE_EVENTS,
             viewmodel=self,
         )
-        file = export_config.file
-        export_format = export_config.export_format
-        event_list_exporter = self._event_list_export_formats.get(export_format, None)
+        event_list_exporter = self._event_list_export_formats.get(
+            export_config.export_format, None
+        )
         if event_list_exporter is None:
             raise ExporterNotFoundError(
                 f"{event_list_exporter} is not a valid export format"
             )
-        return event_list_exporter, file
+
+        return event_list_exporter, export_config
 
     def set_track_offset(self, offset_x: float, offset_y: float) -> None:
         start_msg_popup = self._ui_factory.minimal_info_box(
@@ -1697,18 +1788,20 @@ class DummyViewModel(
             export_config = await self._ui_factory.configure_export_file(
                 title="Export road user assignments",
                 export_format_extensions=export_formats,
-                initial_file_stem="road_user_assignments",
+                context_file_type=CONTEXT_FILE_TYPE_ROAD_USER_ASSIGNMENTS,
                 viewmodel=self,
             )
             logger().debug(export_config)
-            save_path = export_config.file
-            export_format = export_config.export_format
-
             export_specification = ExportSpecification(
-                save_path, export_format, OVERWRITE
+                export_directory=export_config.export_directory,
+                export_filename_stem=export_config.file_stem,
+                format=export_config.export_format,
+                export_mode=OVERWRITE,
             )
             self._application.export_road_user_assignments(export_specification)
-            logger().info(f"Exporting road user assignments to {save_path}")
+            logger().info(
+                f"Exporting road user assignments to {export_config.as_file_path()}"
+            )
         except CancelExportFile:
             logger().info("User canceled configuration of export")
 
@@ -1776,7 +1869,9 @@ class DummyViewModel(
     def update_remark_view(self, _: Any = None) -> None:
         self.frame_remark.load_remark()
 
-    def get_save_path_suggestion(self, file_type: str, context_file_type: str) -> Path:
+    def get_save_path_suggestion(
+        self, file_type: str, context_file_type: str
+    ) -> SavePathSuggestion:
         return self._application.suggest_save_path(file_type, context_file_type)
 
     def set_frame_track_statistics(self, frame: AbstractFrameTrackStatistics) -> None:
@@ -1808,17 +1903,19 @@ class DummyViewModel(
             export_config = await self._ui_factory.configure_export_file(
                 title="Export track statistics",
                 export_format_extensions=export_formats,
-                initial_file_stem=CONTEXT_FILE_TYPE_TRACK_STATISTICS,
+                context_file_type=CONTEXT_FILE_TYPE_TRACK_STATISTICS,
                 viewmodel=self,
             )
             logger().debug(export_config)
-            save_path = export_config.file
-            export_format = export_config.export_format
-
             export_specification = TrackStatisticsExportSpecification(
-                save_path, export_format, OVERWRITE
+                export_directory=export_config.export_directory,
+                export_filename_stem=export_config.file_stem,
+                format=export_config.export_format,
+                export_mode=OVERWRITE,
+            )
+            destination = self._application.export_track_statistics(
+                export_specification
             )
-            self._application.export_track_statistics(export_specification)
-            logger().info(f"Exporting track statistics to {save_path}")
+            logger().info(f"Exporting track statistics to {destination}")
         except CancelExportFile:
             logger().info("User canceled configuration of export")

otanalytics-0.7.5/OTAnalytics/adapter_ui/file_export_dto.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ExportFileDto:
+    """
+    Data transfer object for file export information.
+
+    Attributes:
+        export_directory (Path): The directory where the file will be exported.
+        file_stem (str): The stem of the file name (without extension).
+        export_format (str): The format of the exported file. The file extension.
+    """
+
+    export_directory: Path
+    file_stem: str
+    export_format_extension: str
+    export_format: str
+
+    @classmethod
+    def from_file_path(cls, file_path: Path, export_format: str) -> "ExportFileDto":
+        return cls(
+            export_directory=file_path.parent,
+            file_stem=file_path.stem,
+            export_format_extension=file_path.suffix,
+            export_format=export_format,
+        )
+
+    def as_file_path(self) -> Path:
+        return self.export_directory / f"{self.file_stem}{self.export_format_extension}"

otanalytics-0.7.5/OTAnalytics/adapter_ui/local_file_providers.py

@@ -0,0 +1,57 @@
+"""Local-filesystem implementations of the input file providers."""
+
+from pathlib import Path
+
+from OTAnalytics.adapter_ui.ui_factory import UiFactory
+from OTAnalytics.application.config import SUPPORTED_VIDEO_FILE_TYPES
+from OTAnalytics.application.use_cases.provide_input_files import (
+    ProvideTrackFiles,
+    ProvideVideoFiles,
+)
+
+ALL_FILE_ENDINGS = "All File Endings"
+
+
+class LocalTrackFileProvider(ProvideTrackFiles):
+    """Asks the user to pick ottrk files from the local filesystem.
+
+    Args:
+        ui_factory (UiFactory): builds the file chooser for the active front-end.
+    """
+
+    def __init__(self, ui_factory: UiFactory) -> None:
+        self._ui_factory = ui_factory
+
+    async def provide(self) -> list[Path]:
+        return await self._ui_factory.askopenfilenames(
+            title="Load track files",
+            filetypes=[("tracks file", "*.ottrk")],
+        )
+
+
+class LocalVideoFileProvider(ProvideVideoFiles):
+    """Asks the user to pick video files from the local filesystem.
+
+    Args:
+        ui_factory (UiFactory): builds the file chooser for the active front-end.
+    """
+
+    def __init__(self, ui_factory: UiFactory) -> None:
+        self._ui_factory = ui_factory
+
+    async def provide(self) -> list[Path]:
+        return await self._ui_factory.askopenfilenames(
+            title="Load video files",
+            filetypes=[("video file", SUPPORTED_VIDEO_FILE_TYPES)],
+            extension_options=_video_extension_options(),
+        )
+
+
+def _video_extension_options() -> dict[str, list[str] | None]:
+    """One entry offering every supported type, then one per type."""
+    options: dict[str, list[str] | None] = {
+        ALL_FILE_ENDINGS: list(SUPPORTED_VIDEO_FILE_TYPES)
+    }
+    for extension in SUPPORTED_VIDEO_FILE_TYPES:
+        options[extension] = [extension]
+    return options