API: add abstract open_file method, implement open_file

pkgs/clan-cli/clan_cli/api/directory.py

@@ -8,6 +8,33 @@ from clan_cli.errors import ClanError
 from . import API
 
 
+@dataclass
+class FileFilter:
+    title: str | None
+    mime_types: list[str] | None
+    patterns: list[str] | None
+    suffixes: list[str] | None
+
+
+@dataclass
+class FileRequest:
+    # Mode of the os dialog window
+    mode: Literal["open_file", "select_folder"]
+    # Title of the os dialog window
+    title: str | None = None
+    # Pre-applied filters for the file dialog
+    filters: FileFilter | None = None
+
+
+@API.register
+def open_file(file_request: FileRequest) -> str | None:
+    """
+    Abstract api method to open a file dialog window.
+    It must return the name of the selected file or None if no file was selected.
+    """
+    raise NotImplementedError("Each specific platform should implement this function.")
+
+
 @dataclass
 class File:
     path: str