paths are now saved as relative to the project directory

Author: alexhroom

RATapi/project.py

@@ -4,8 +4,10 @@
 import copy
 import functools
 import json
+import warnings
 from enum import Enum
 from pathlib import Path
+from sys import version_info
 from textwrap import indent
 from typing import Annotated, Any, Callable, Union
 
@@ -835,17 +837,18 @@ def classlist_script(name, classlist):
             + "\n)"
         )
 
-    def save(self, path: Union[str, Path], filename: str = "project"):
+    def save(self, filepath: Union[str, Path], filename: str = "project"):
         """Save a project to a JSON file.
 
         Parameters
         ----------
-        path : str or Path
+        filepath : str or Path
             The path in which the project will be written.
         filename : str
             The name of the generated project file.
 
         """
+        filepath = Path(filepath)
         json_dict = {}
         for field in self.model_fields:
             attr = getattr(self, field)
@@ -869,7 +872,7 @@ def make_custom_file_dict(item):
                         "name": item.name,
                         "filename": item.filename,
                         "language": item.language,
-                        "path": str(item.path),
+                        "path": str(try_relative_to(item.path, filepath)),
                     }
 
                 json_dict["custom_files"] = [make_custom_file_dict(file) for file in attr]
@@ -879,7 +882,7 @@ def make_custom_file_dict(item):
             else:
                 json_dict[field] = attr
 
-        file = Path(path, f"{filename.removesuffix('.json')}.json")
+        file = Path(filepath, f"{filename.removesuffix('.json')}.json")
         file.write_text(json.dumps(json_dict))
 
     @classmethod
@@ -892,15 +895,21 @@ def load(cls, path: Union[str, Path]) -> "Project":
             The path to the project file.
 
         """
-        input = Path(path).read_text()
-        model_dict = json.loads(input)
-        for i in range(0, len(model_dict["data"])):
-            if model_dict["data"][i]["name"] == "Simulation":
-                model_dict["data"][i]["data"] = np.empty([0, 3])
-                del model_dict["data"][i]["data_range"]
+        path = Path(path)
+        input_data = path.read_text()
+        model_dict = json.loads(input_data)
+        for dataset in model_dict["data"]:
+            if dataset["name"] == "Simulation":
+                dataset["data"] = np.empty([0, 3])
+                del dataset["data_range"]
             else:
-                data = model_dict["data"][i]["data"]
-                model_dict["data"][i]["data"] = np.array(data)
+                data = dataset["data"]
+                dataset["data"] = np.array(data)
+
+        # file paths are saved as relative to the project directory
+        for file in model_dict["custom_files"]:
+            if not Path(file["path"]).is_absolute():
+                file["path"] = Path(path, file["path"])
 
         return cls.model_validate(model_dict)
 
@@ -943,3 +952,44 @@ def wrapped_func(*args, **kwargs):
             return return_value
 
         return wrapped_func
+
+
+def try_relative_to(path: Path, relative_to: Path) -> Path:
+    """Attempt to create a relative path and warn the user if it isn't possible.
+
+    Parameters
+    ----------
+    path : Path
+        The path to try to find a relative path for.
+    relative_to: Path
+        The path to which we find a relative path for ``path``.
+
+    Returns
+    -------
+    Path
+        The relative path if successful, else the absolute path.
+
+    """
+    # we use the absolute paths to resolve symlinks and so on
+    abs_path = Path(path).resolve()
+    abs_base = Path(relative_to).resolve()
+
+    # 'walking up' paths is only added in Python 3.12
+    if version_info.minor < 12:
+        try:
+            relative_path = abs_path.relative_to(abs_base)
+        except ValueError as err:
+            warnings.warn("Could not save a custom file path as relative to the project directory. "
+                          "This may mean the project may not open on other devices. "
+                          f"Error message: {err}", stacklevel=2)
+            return abs_path 
+    else:
+        try:
+            relative_path = abs_path.relative_to(abs_base, walk_up = True)
+        except ValueError as err:
+            warnings.warn("Could not save a custom file path as relative to the project directory. "
+                          "This may mean the project may not open on other devices. "
+                          f"Error message: {err}", stacklevel=2)
+            return abs_path 
+
+    return relative_path

tests/test_project.py

@@ -2,7 +2,9 @@
 
 import copy
 import tempfile
+import warnings
 from pathlib import Path
+from sys import version_info
 from typing import Callable
 
 import numpy as np
@@ -1556,8 +1558,41 @@ def test_save_load(project, request):
     original_project = request.getfixturevalue(project)
 
     with tempfile.TemporaryDirectory() as tmp:
-        original_project.save(tmp)
+        # ignore relative path warnings
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            original_project.save(tmp)
         converted_project = RATapi.Project.load(Path(tmp, "project.json"))
 
+    # resolve custom files in case the original project had unresolvable relative paths
+    for file in original_project.custom_files:
+        file.path = file.path.resolve()
+
     for field in RATapi.Project.model_fields:
         assert getattr(converted_project, field) == getattr(original_project, field)
+
+
+def test_relative_paths():
+    """Test that ``try_relative_to`` correctly creates relative paths."""
+
+    with tempfile.TemporaryDirectory() as tmp:
+        data_path = Path(tmp, "data/myfile.dat")
+
+        assert RATapi.project.try_relative_to(data_path, tmp) == Path("./data/myfile.dat")
+
+
+def test_relative_paths_version():
+    """Test that we only walk up paths on Python 3.12 or greater."""
+    
+    data_path = "/tmp/project/data/mydata.dat"
+    relative_path = "/tmp/project/project_path/myproj.dat"
+
+    if version_info.minor >= 12:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            assert RATapi.project.try_relative_to(data_path, relative_path) == Path("../../data/mydata.dat")
+    else: 
+        with pytest.warns(match="Could not save a custom file path as relative to the project directory. "
+                          "This may mean the project may not open on other devices. "
+                          "Error message:"):
+            assert RATapi.project.try_relative_to(data_path, relative_path) == Path("/tmp/project/data/mydata.dat")