Detached mode

[Gautzilla]

🪽 Local project, distant audio files!

This PR resolves #492 by allowing the original AudioDataset to be located outside the project folder: possibly on another disk or partition.

Basic PublicAPI usage

It adds a Project.build_from_audio_dataset_json() method in the PublicAPI to ease the build of a project in such detached mode:

from pathlib import Path

from osekit.public.project import Project

project = Project(
    folder=Path(r"C:\Users\berthoga\Documents\Datasets\detached"),
)

# The JSON can be written with the AudioDataset.write_json() method,
# see the Core API documentation for more info
ads_json_path = Path(
    r"C:\Users\berthoga\Documents\Datasets\cool_dataset\data\audio\original\original.json"
)

project.build_from_audio_dataset_json(
    audio_dataset_json=ads_json_path,
)

How does it work? (CoreAPI implementation)

The main issue with implementing this was the serialization of paths, which was exclusively done with relative string paths before and needed more flexibility here.

Basically, I've reworked the serialization of paths and added the osekit.core.json_serializer.anchor_path context manager that works like this:

• If the anchor_path context is not used, the serialization is as before (paths are serialized as relative to the folder in which the json file is written. If this is not possible (e.g. if the serialized path is on another partition), it is written as absolute.
• with the anchor_path context, paths that are relative to the anchor path are serialized as relative, and paths that aren't relative to the anchor path are written as absolute paths.

Example

from pathlib import Path
from osekit.core.json_serializer import path_anchor
from osekit.core.json_serializer import _serialize_path

anchor = Path(r"C:/Users/cool")
path_inside_anchor = Path(r"C:/Users/cool/fun.txt")
path_outside_anchor = Path(r"C:/Users/not_cool/fun.txt")

root_path = Path(r"C:/Users")

serialized = {}

# No anchor context: paths are relative
serialized["No anchor context, inside"] = _serialize_path(path_inside_anchor, root_path)
serialized["No anchor context, outside"] = _serialize_path(path_outside_anchor, root_path)

# Anchor context: paths that are not relative to the anchor are serialized as absolute
with path_anchor(anchor=anchor):
    serialized["Anchor context, inside"] = _serialize_path(
        path_inside_anchor, root_path
    )
    serialized["Anchor context, outside"] = _serialize_path(
        path_outside_anchor, root_path
    )

for key, value in serialized.items():
    print(f"{key:<30}{value:>30}")

> No anchor context, inside                       cool/fun.txt
> No anchor context, outside                  not_cool/fun.txt
> Anchor context, inside                          cool/fun.txt
> Anchor context, outside            C:/Users/not_cool/fun.txt

[coveralls]

Coverage is 98.932% — Gautzilla:detached-mode into Project-OSmOSE:main. No base build found for Project-OSmOSE:main.