feat: ✨ _parse_uri()

src/seedcase_flower/cli.py

@@ -1,12 +1,12 @@
 """Functions for the exposed CLI."""
 
 from pathlib import Path
-from typing import Any, Optional
+from typing import Optional
 
 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, _resolve_uri
 
 app = App(
     help="Flower generates human-readable documentation from Data Packages.",
@@ -47,8 +47,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)
+    properties = _resolve_uri(uri)
+    # properties = _read_properties(path)
 
     # One item per section, rendered from template.
     # Internally uses Jinja2 to render templates with metadata, which

src/seedcase_flower/internals.py

@@ -3,7 +3,27 @@
 import json
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Annotated, Any
+from urllib import parse
+
+from pydantic import AnyUrl, FileUrl, TypeAdapter, UrlConstraints
+
+_AnnotatedHttps = Annotated[AnyUrl, UrlConstraints(allowed_schemes=["https"])]
+_adapter = TypeAdapter(_AnnotatedHttps)
+
+
+class HttpsUrl(str):
+    """Type and class with validation for https URLs."""
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source, handler):  # type: ignore[no-untyped-def]
+        """Initialize adapter core schema."""
+        return _adapter.core_schema
+
+    def __new__(cls, value: str):  # type: ignore[no-untyped-def]
+        """Setup validation."""
+        validated = _adapter.validate_python(value)
+        return str.__new__(cls, validated)
 
 
 class BuildStyle(Enum):
@@ -14,11 +34,53 @@ 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)
+type HttpsUrl_or_FileUrl = HttpsUrl | FileUrl
+
+
+def _resolve_uri(uri_or_path: str) -> HttpsUrl_or_FileUrl:
+    split_uri = parse.urlsplit(uri_or_path)
+    match split_uri.scheme:
+        case "":
+            return _check_path(uri_or_path)
+        case "file":
+            return _check_file_uri(split_uri)
+        case "https":
+            return _check_https_uri(split_uri)
+        case "gh" | "github":
+            return _check_github_uri(split_uri)
+        case _:
+            raise ValueError(
+                "The URI must be either a path to an existing file/folder "
+                "or have one of the following URI prefixes: "
+                "`file:`, `https:`, `gh:`, `github:`"
+            )
+
+
+def _check_path(uri_or_path: str) -> FileUrl:
+    path = Path(uri_or_path).resolve()
+    if path.is_dir():
+        path = path / "datapackage.json"
+    if not path.exists():
+        raise OSError(f"{path} does not exist.")
+    return FileUrl(path.as_uri())
+
+
+def _check_file_uri(split_uri: parse.SplitResult) -> FileUrl:
+    return FileUrl(split_uri.geturl())
+
+
+def _check_https_uri(split_uri: parse.SplitResult) -> HttpsUrl:
+    return HttpsUrl(split_uri.geturl())
+
+
+def _check_github_uri(split_uri: parse.SplitResult) -> HttpsUrl:
+    return HttpsUrl(
+        split_uri._replace(
+            scheme="https",
+            netloc="raw.githubusercontent.com",
+            path=f"/{split_uri.path}/refs/heads/main/datapackage.json",
+        ).geturl()
+    )
 
 
 # TODO Extend to also read properties from URLs

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)