feat: ✨ implement resolve uri

src/seedcase_flower/cli.py

@@ -6,7 +6,7 @@
 from cyclopts import App, Parameter, config
 
 # from seedcase_flower.config import Config as FlowerConfig
-from seedcase_flower.internals import BuildStyle, _read_properties, _resolve_uri
+from seedcase_flower.internals import BuildStyle, Uri, _parse_uri, _read_properties
 
 app = App(
     name="seedcase-flower",
@@ -39,7 +39,10 @@ def build(
     """Build human-readable documentation from a `datapackage.json` file.
 
     Args:
-        uri: The URI to a datapackage.json file.
+        uri: The path to a local `datapackage.json` file or its parent folder.
+            Can also be an `https:` URL to a remote `datapackage.json` or a
+            `github:` / `gh:` URI pointing to a repo with a `datapackage.json`
+            in the repo root (in the format `gh:org/repo`).
         style: The style used to structure the output. If a template directory
             is given, this parameter will be ignored.
         template_dir: The directory that contains the Jinja template
@@ -48,8 +51,8 @@ def build(
         output_dir: The directory to save the generated files in.
         verbose: If True, prints additional information to the console.
     """
-    path: Path = _resolve_uri(uri)
-    properties: dict[str, Any] = _read_properties(path)
+    uri: Uri = _parse_uri(uri)  # type: ignore # TODO fix in read_prop PR
+    properties: dict[str, Any] = _read_properties(uri)  # type: ignore # TODO fix in read_prop PR
 
     # One item per section, rendered from template.
     # Internally uses Jinja2 to render templates with metadata, which

src/seedcase_flower/internals.py

@@ -1,9 +1,11 @@
 """Helper functions for private use."""
 
 import json
+from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 from typing import Any
+from urllib import parse
 
 
 class BuildStyle(Enum):
@@ -14,15 +16,62 @@ class BuildStyle(Enum):
     quarto_resource_tables = "quarto_resource_tables"
 
 
-# Output maybe str? Path?
-# Use `match` inside for strictness on URI types? Or use a library for URI parsing?
-# TODO Extend to parse strings and return either URL or Path
-def _resolve_uri(uri: str) -> Path:
-    return Path(uri)
+@dataclass(frozen=True)
+class Uri:
+    """A parsed URI with its normalised value and locality flag."""
+
+    value: str
+    local: bool
+
+
+def _parse_uri(uri: str) -> Uri:
+    split_uri = parse.urlsplit(uri)
+    if split_uri.scheme == "":
+        split_uri = split_uri._replace(scheme="file")
+    match split_uri.scheme:
+        case "file":
+            return _convert_to_file_uri(split_uri)
+        case "https":
+            return _convert_to_https_uri(split_uri)
+        case "gh" | "github":
+            return _convert_to_github_uri(split_uri)
+        case _:
+            raise ValueError(
+                "The uri must be either a path to an existing file/folder "
+                "or a URI with one of the following URI prefixes: "
+                "`file:`, `https:`, `gh:`, `github:`"
+            )
+
+
+def _convert_to_file_uri(split_file_uri: parse.SplitResult) -> Uri:
+    path = Path(split_file_uri.path).resolve()
+    if path.is_dir():
+        path /= "datapackage.json"
+    split_file_uri = split_file_uri._replace(path=path.as_posix())
+    return Uri(value=split_file_uri.geturl(), local=True)
+
+
+def _convert_to_https_uri(split_https_uri: parse.SplitResult) -> Uri:
+    return Uri(value=split_https_uri.geturl(), local=False)
+
+
+def _convert_to_github_uri(split_gh_uri: parse.SplitResult) -> Uri:
+    return Uri(
+        value=split_gh_uri._replace(
+            scheme="https",
+            netloc="raw.githubusercontent.com",
+            path=f"/{split_gh_uri.path}/refs/heads/main/datapackage.json",
+        ).geturl(),
+        local=False,
+    )
 
 
 # TODO Extend to also read properties from URLs
-def _read_properties(path: Path) -> dict[str, Any]:
-    with open(path) as properties_file:
-        datapackage: dict[str, Any] = json.load(properties_file)
-        return datapackage
+def _read_properties(uri: Uri) -> dict[str, Any]:
+    if uri.local:
+        path = Path(parse.urlsplit(uri.value).path)
+        with open(path) as properties_file:
+            return json.load(properties_file)  # type: ignore # TODO fix in read_prop PR
+    else:
+        # TODO read from remote file
+        return {"placeholder": uri.value}

tests/test_cli.py

@@ -7,7 +7,7 @@
 import pytest
 
 from seedcase_flower.cli import app, view
-from seedcase_flower.internals import BuildStyle
+from seedcase_flower.internals import BuildStyle, Uri
 
 _DATAPACKAGE_DATA = {
     "name": "placeholder",
@@ -29,9 +29,9 @@ def datapackage_path(tmp_path):
 
 
 @pytest.fixture
-def mock_resolve_uri(mocker):
-    """Mock _resolve_uri to isolate CLI tests from filesystem resolution."""
-    return mocker.patch("seedcase_flower.cli._resolve_uri")
+def mock_parse_uri(mocker):
+    """Mock _parse_uri to isolate CLI tests from filesystem resolution."""
+    return mocker.patch("seedcase_flower.cli._parse_uri")
 
 
 @pytest.fixture
@@ -43,16 +43,16 @@ def mock_read_properties(mocker):
 # Testing CLI invocation ====
 
 
-def test_build_with_mocked_internals(mock_resolve_uri, mock_read_properties):
+def test_build_with_mocked_internals(mock_parse_uri, mock_read_properties):
     """Isolate CLI behaviour by mocking internal helpers."""
-    fake_path = Path("datapackage.json")
-    mock_resolve_uri.return_value = fake_path
+    fake_uri = Uri(value="file:///datapackage.json", local=True)
+    mock_parse_uri.return_value = fake_uri
     # Simulate running the app from the command line (but without calling sys.exit())
     app(["build", "datapackage.json"], result_action="return_value")
 
     # Checking that the correct values were passed to the internal functions
-    mock_resolve_uri.assert_called_once_with("datapackage.json")
-    mock_read_properties.assert_called_once_with(fake_path)
+    mock_parse_uri.assert_called_once_with("datapackage.json")
+    mock_read_properties.assert_called_once_with(fake_uri)
 
 
 # Checking stdout ====
@@ -122,8 +122,11 @@ def test_build_reads_uri_from_flower_toml(tmp_path, monkeypatch):
     Build human-readable documentation from a datapackage.json file.
 
     ╭─ Parameters ───────────────────────────────────────────────────────────────────────────╮
-    │ URI --uri                    The URI to a datapackage.json file. [default:             │
-    │                              datapackage.json]                                         │
+    │ URI --uri                    The path to a local datapackage.json file or its parent   │
+    │                              folder. Can also be an https: URL to a remote             │
+    │                              datapackage.json or a github: / gh: URI pointing to a     │
+    │                              repo with a datapackage.json in the repo root (in the     │
+    │                              format gh:org/repo). [default: datapackage.json]          │
     │ STYLE --style                The style used to structure the output. If a template     │
     │                              directory is given, this parameter will be ignored.       │
     │                              [choices: quarto-one-page, quarto-resource-listing,       │

tests/test_internals.py

@@ -0,0 +1,117 @@
+"""Tests for internal helper functions."""
+
+import pytest
+
+from seedcase_flower.internals import Uri, _parse_uri
+
+# _parse_uri: plain path (no scheme) ====
+
+
+def test_parse_uri_plain_file_path_is_local(tmp_path):
+    """A plain file path with no scheme should return a local Uri."""
+    result = _parse_uri(str(tmp_path / "datapackage.json"))
+    assert result.local is True
+
+
+def test_parse_uri_plain_file_path_has_file_scheme(tmp_path):
+    """A plain file path should be normalised to a file:// URI."""
+    result = _parse_uri(str(tmp_path / "datapackage.json"))
+    assert result.value.startswith("file://")
+
+
+def test_parse_uri_directory_path_appends_datapackage_json(tmp_path):
+    """Passing a directory path should append datapackage.json to the URI."""
+    result = _parse_uri(str(tmp_path))
+    assert result.value.endswith("datapackage.json")
+
+
+def test_parse_uri_directory_path_is_local(tmp_path):
+    """Passing a directory path should return a local Uri."""
+    result = _parse_uri(str(tmp_path))
+    assert result.local is True
+
+
+# _parse_uri: file:// scheme ====
+
+
+def test_parse_uri_file_scheme_is_local(tmp_path):
+    """A file:// URI should return a local Uri."""
+    result = _parse_uri(f"file://{tmp_path / 'datapackage.json'}")
+    assert result.local is True
+
+
+def test_parse_uri_file_scheme_preserves_path(tmp_path):
+    """A file:// URI pointing to a file should preserve the path."""
+    file = tmp_path / "datapackage.json"
+    result = _parse_uri(f"file://{file}")
+    assert str(file) in result.value
+
+
+# _parse_uri: https:// scheme ====
+
+
+def test_parse_uri_https_is_not_local():
+    """An https:// URI should return a non-local Uri."""
+    result = _parse_uri("https://example.com/datapackage.json")
+    assert result.local is False
+
+
+def test_parse_uri_https_preserves_url():
+    """An https:// URI should be returned unchanged."""
+    url = "https://example.com/datapackage.json"
+    result = _parse_uri(url)
+    assert result.value == url
+
+
+# _parse_uri: gh:// / github:// scheme ====
+
+
+def test_parse_uri_gh_scheme_converts_to_raw_githubusercontent():
+    """A gh:// URI should be converted to a raw.githubusercontent.com URL."""
+    result = _parse_uri("gh://owner/repo")
+    assert "raw.githubusercontent.com" in result.value
+
+
+def test_parse_uri_gh_scheme_is_not_local():
+    """A gh:// URI should return a non-local Uri."""
+    result = _parse_uri("gh://owner/repo")
+    assert result.local is False
+
+
+def test_parse_uri_gh_scheme_appends_datapackage_json():
+    """A gh:// URI should point to the datapackage.json on the main branch."""
+    result = _parse_uri("gh://owner/repo")
+    assert result.value.endswith("datapackage.json")
+
+
+def test_parse_uri_github_scheme_converts_to_raw_githubusercontent():
+    """A github:// URI should be converted to a raw.githubusercontent.com URL."""
+    result = _parse_uri("github://owner/repo")
+    assert "raw.githubusercontent.com" in result.value
+
+
+def test_parse_uri_github_scheme_is_not_local():
+    """A github:// URI should return a non-local Uri."""
+    result = _parse_uri("github://owner/repo")
+    assert result.local is False
+
+
+def test_parse_uri_github_scheme_appends_datapackage_json():
+    """A github:// URI should point to the datapackage.json on the main branch."""
+    result = _parse_uri("github://owner/repo")
+    assert result.value.endswith("datapackage.json")
+
+
+# _parse_uri: unsupported scheme ====
+
+
+def test_parse_uri_unsupported_scheme_raises_value_error():
+    """An unsupported URI scheme should raise a ValueError."""
+    with pytest.raises(ValueError, match="uri must be either"):
+        _parse_uri("ftp://example.com/datapackage.json")
+
+
+def test_parse_uri_returns_uri_instance(tmp_path):
+    """_parse_uri should always return a Uri instance."""
+    result = _parse_uri(str(tmp_path / "datapackage.json"))
+    assert isinstance(result, Uri)

tools/vulture-allowlist.py

@@ -7,3 +7,6 @@
 _check_jsonpath  # unused method (src/seedcase_flower/section.py:83)
 quarto_resource_tables  # unused variable (src/seedcase_flower/internals.py:14)
 cls  # unused variable (src/seedcase_flower/section.py:85)
+target  # unused variable (src/seedcase_flower/.venv/lib/python3.12/site-packages/_virtualenv.py:50)
+handler  # unused variable (src/seedcase_flower/internals.py:20)
+source  # unused variable (src/seedcase_flower/internals.py:20)