Added utility to unpack a Gobbler path to its project/asset/version details.

Author: LTLA

src/pygobbler/__init__.py

@@ -41,3 +41,4 @@
 from .approve_probation import approve_probation
 from .reject_probation import reject_probation
 from .set_permissions import set_permissions
+from .unpack_path import unpack_path

src/pygobbler/unpack_path.py

@@ -0,0 +1,26 @@
+from typing import Dict
+
+#' @export
+#' @importFrom utils tail
+def unpack_path(path: str) -> Dict[str, str]:
+    """Unpack a path to its combination of project, asset, version, and
+    (optionally) path, for easier use in the various pygobbler functions.
+
+    Args:
+        path: 
+            Relative path within the Gobbler registry. 
+
+    Return:
+        Dictionary with the ``project``, ``asset``, ``version`` and ``path`` keys.
+        All values are strings except for ``path``, which may be None.
+    """
+    components = path.split("/")
+    if len(components) < 3:
+        raise ValueError("expected at least 3 path components in 'path'")
+
+    if len(components) == 3 or components[3] == "":
+        path = None
+    else:
+        path = "/".join(components[3:])
+
+    return { "project": components[0], "asset": components[1], "version": components[2], "path": path }

tests/test_unpack_path.py

@@ -0,0 +1,27 @@
+import pygobbler as pyg
+
+
+def test_unpack_path():
+    out = pyg.unpack_path("project/asset/version/path")
+    assert out["project"] == "project"
+    assert out["asset"] == "asset"
+    assert out["version"] == "version"
+    assert out["path"] == "path"
+
+    out = pyg.unpack_path("project/asset/version/foo/bar")
+    assert out["project"] == "project"
+    assert out["asset"] == "asset"
+    assert out["version"] == "version"
+    assert out["path"] == "foo/bar"
+
+    out = pyg.unpack_path("project/asset/version/")
+    assert out["project"] == "project"
+    assert out["asset"] == "asset"
+    assert out["version"] == "version"
+    assert out["path"] is None
+
+    out = pyg.unpack_path("project/asset/version")
+    assert out["project"] == "project"
+    assert out["asset"] == "asset"
+    assert out["version"] == "version"
+    assert out["path"] is None