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_source, _read_properties
 
 app = App(
     help="Flower generates human-readable documentation from Data Packages.",
@@ -29,7 +29,7 @@
 
 @app.command()
 def build(
-    uri: str = "datapackage.json",
+    source: str = "datapackage.json",
     style: BuildStyle = BuildStyle.quarto_one_page,
     template_dir: Optional[Path] = None,
     output_dir: Path = Path("docs"),
@@ -38,7 +38,10 @@ def build(
     """Build human-readable documentation from a `datapackage.json` file.
 
     Args:
-        uri: The URI to a datapackage.json file.
+        source: 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
@@ -47,8 +50,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_source(source)
+    properties: dict[str, Any] = _read_properties(uri)
 
     # 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_source(source: str) -> Uri:
+    split_source = parse.urlsplit(source)
+    if split_source.scheme == "":
+        split_source = split_source._replace(scheme="file")
+    match split_source.scheme:
+        case "file":
+            return _convert_to_file_uri(split_source)
+        case "https":
+            return _convert_to_https_uri(split_source)
+        case "gh" | "github":
+            return _convert_to_github_uri(split_source)
+        case _:
+            raise ValueError(
+                "The source 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_source: parse.SplitResult) -> Uri:
+    path = Path(split_file_source.path).resolve()
+    if path.is_dir():
+        path /= "datapackage.json"
+    split_file_source = split_file_source._replace(path=path.as_posix())
+    return Uri(value=split_file_source.geturl(), local=True)
+
+
+def _convert_to_https_uri(split_https_source: parse.SplitResult) -> Uri:
+    return Uri(value=split_https_source.geturl(), local=False)
+
+
+def _convert_to_github_uri(split_gh_source: parse.SplitResult) -> Uri:
+    return Uri(
+        value=split_gh_source._replace(
+            scheme="https",
+            netloc="raw.githubusercontent.com",
+            path=f"/{split_gh_source.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:
+        # TODO read from local file
+        pass
+    else:
+        # TODO read from remote file
+        pass
+    return {"placeholder": uri.value}

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)