From a1ee1e84d4a7f467c5df13e54c590345a40b775c Mon Sep 17 00:00:00 2001
From: Florian Rupprecht <floruppr@gmail.com>
Date: Wed, 11 Sep 2024 14:39:03 -0400
Subject: [PATCH] Add resolve_parents flag for input file resolving.

---
 src/styxdefs/dummy_runner.py |  2 +-
 src/styxdefs/local_runner.py |  2 +-
 src/styxdefs/types.py        | 68 ++++++++++++++++++++++++++++--------
 3 files changed, 55 insertions(+), 17 deletions(-)

diff --git a/src/styxdefs/dummy_runner.py b/src/styxdefs/dummy_runner.py
index 226205e..9881cbf 100644
--- a/src/styxdefs/dummy_runner.py
+++ b/src/styxdefs/dummy_runner.py
@@ -18,7 +18,7 @@ def start_execution(self, metadata: Metadata) -> Execution:
         self.last_metadata = metadata
         return self
 
-    def input_file(self, host_file: InputPathType) -> str:
+    def input_file(self, host_file: InputPathType, resolve_parent: bool = False) -> str:
         """Resolve input file."""
         return str(host_file)
 
diff --git a/src/styxdefs/local_runner.py b/src/styxdefs/local_runner.py
index ba94094..a10c90c 100644
--- a/src/styxdefs/local_runner.py
+++ b/src/styxdefs/local_runner.py
@@ -43,7 +43,7 @@ def __init__(
             self.output_dir = self.output_dir.with_name(f"{self.output_dir.name}_1")
         self.output_dir.mkdir(parents=True, exist_ok=True)
 
-    def input_file(self, host_file: InputPathType) -> str:
+    def input_file(self, host_file: InputPathType, resolve_parent: bool = False) -> str:
         """Resolve host input files."""
         return str(pathlib.Path(host_file).absolute())
 
diff --git a/src/styxdefs/types.py b/src/styxdefs/types.py
index 7f7d99f..38b3a9a 100644
--- a/src/styxdefs/types.py
+++ b/src/styxdefs/types.py
@@ -4,10 +4,13 @@
 import shlex
 import typing
 
-InputPathType: typing.TypeAlias = pathlib.Path | str
-"""Input host file type."""
-OutputPathType: typing.TypeAlias = pathlib.Path
-"""Output host file type."""
+if typing.TYPE_CHECKING:
+    InputPathType = pathlib.Path | str
+    """Input host file type."""
+    OutputPathType = pathlib.Path
+    """Output host file type."""
+else:
+    InputPathType = OutputPathType = None
 
 
 class Execution(typing.Protocol):
@@ -16,29 +19,47 @@ class Execution(typing.Protocol):
     Created by `Runner.start_execution()`.
     """
 
-    def input_file(self, host_file: InputPathType) -> str:
+    def input_file(self, host_file: InputPathType, resolve_parent: bool = False) -> str:
         """Resolve host input files.
 
-        Returns a local filepath.
-        Called (potentially multiple times) after
-        `Runner.start_execution()` and before `Runner.run()`.
+        Args:
+            host_file: The input file path on the host system.
+            resolve_parent: If True, resolve the parent directory of the input file.
+
+        Returns:
+            str: A local filepath.
+
+        Note:
+            Called (potentially multiple times) after
+            `Runner.start_execution()` and before `Runner.run()`.
         """
         ...
 
     def run(self, cargs: list[str]) -> None:
         """Run the command.
 
-        Called after all `Execution.input_file()`
-        and `Execution.output_file()` calls.
+        Args:
+            cargs: A list of command arguments.
+
+        Note:
+            Called after all `Execution.input_file()`
+            and `Execution.output_file()` calls.
         """
         ...
 
     def output_file(self, local_file: str, optional: bool = False) -> OutputPathType:
         """Resolve local output files.
 
-        Returns a host filepath.
-        Called (potentially multiple times) after all
-        `Runner.input_file()` calls.
+        Args:
+            local_file: The local file path.
+            optional: If True, the output file is optional.
+
+        Returns:
+            OutputPathType: A host filepath.
+
+        Note:
+            Called (potentially multiple times) after all
+            `Runner.input_file()` calls.
         """
         ...
 
@@ -75,7 +96,14 @@ class Runner(typing.Protocol):
     def start_execution(self, metadata: Metadata) -> Execution:
         """Start an execution.
 
-        Called before any `Execution.input_file()` calls.
+        Args:
+            metadata: Static tool metadata.
+
+        Returns:
+            Execution: An Execution object.
+
+        Note:
+            Called before any `Execution.input_file()` calls.
         """
         ...
 
@@ -84,6 +112,10 @@ class StyxRuntimeError(Exception):
     """Styx runtime error.
 
     Raised when a command reports a non-zero return code.
+
+    Attributes:
+        return_code: The return code of the failed command.
+        command_args: The arguments of the failed command.
     """
 
     def __init__(
@@ -92,7 +124,13 @@ def __init__(
         command_args: list[str] | None = None,
         message_extra: str | None = None,
     ) -> None:
-        """Initialize the error."""
+        """Initialize the error.
+
+        Args:
+            return_code: The return code of the failed command.
+            command_args: The arguments of the failed command.
+            message_extra: Additional error message.
+        """
         self.return_code = return_code
         self.command_args = command_args