Merge branch 'main' into feat/beautify-cli-help

Author: joelostblom

.github/workflows/release-package.yml

@@ -34,7 +34,7 @@ jobs:
     if: ${{ needs.release.outputs.previous_version != needs.release.outputs.current_version }}
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1
+        uses: step-security/harden-runner@a90bcbc6539c36a85cdfeb73f7e2f433735f215b # v2.15.0
         with:
           egress-policy: audit
 
@@ -50,7 +50,7 @@ jobs:
       # - https://www.andrlik.org/dispatches/til-use-uv-for-build-and-publish-github-actions/
       # - https://github.com/astral-sh/trusted-publishing-examples
       - name: Set up uv
-        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098 # v7.3.1
 
       - name: Build distributions
         # Builds dists from source and stores them in the dist/ directory.

CHANGELOG.md

@@ -16,6 +16,12 @@ individual release will not have many changes within it. Below is a list
 of the releases we've made so far, along with what was changed within
 each release.
 
+## 0.7.0 (2026-03-02)
+
+### Feat
+
+- ✨ `_parse_uri()` (#152)
+
 ## 0.6.0 (2026-02-23)
 
 ### Feat

docs/design/interface/cli.qmd

@@ -53,7 +53,8 @@ There will be two commands available:
 
 ## {{< var wip >}} `build`
 
-The `build` command has the following signature, that is positional as well as keyword-based:
+The `build` command has the following signature, that is positional as
+well as keyword-based:
 
 ``` {.bash filename="Terminal"}
 seedcase-flower build [URI] [STYLE] [TEMPLATE-DIR] [OUTPUT-DIR] [VERBOSE]
@@ -210,7 +211,8 @@ override the corresponding settings in the configuration file.
 
 ## {{< var planned >}} `view`
 
-The `view` command has the following signature, that is positional as well as keyword-based:
+The `view` command has the following signature, that is positional as
+well as keyword-based:
 
 ``` {.bash filename="Terminal"}
 seedcase-flower view [URI] [STYLE]

docs/includes/_contributors.qmd

@@ -1,3 +1,3 @@
 The following people have contributed to this project by submitting pull requests :tada:
 
- [\@lwjohnst86](https://github.com/lwjohnst86), [\@signekb](https://github.com/signekb), [\@joelostblom](https://github.com/joelostblom), [\@martonvago](https://github.com/martonvago)
+ [\@lwjohnst86](https://github.com/lwjohnst86), [\@joelostblom](https://github.com/joelostblom), [\@signekb](https://github.com/signekb), [\@martonvago](https://github.com/martonvago)

justfile

@@ -137,6 +137,10 @@ build-readme:
 build-contributors:
     sh ./tools/get-contributors.sh seedcase-project/seedcase-flower > docs/includes/_contributors.qmd
 
+# Generate updated help-output strings for copy-pasting into test_cli.py
+generate-help-strings:
+    PYTHONPATH=. uv run python tools/generate-help-strings.py
+
 # Preview the documentation website with automatic reload on changes
 preview-website: build-quartodoc
     uv run quarto preview --execute

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "seedcase-flower"
-version = "0.6.0"
+version = "0.7.0"
 # TODO: Add a description of the package.
 description = ""
 authors = [
@@ -56,6 +56,7 @@ dev = [
     "pre-commit>=4.5.0",
     "pytest>=9.0.1",
     "pytest-cov>=7.0.0",
+    "pytest-mock>=3.14.0",
     "quartodoc>=0.11.1",
     "ruff>=0.14.7",
     "types-tabulate>=0.9.0.20241207",

src/seedcase_flower/cli.py

@@ -9,12 +9,14 @@
 # from seedcase_flower.config import Config as FlowerConfig
 from seedcase_flower.internals import (
     BuildStyle,
+    Uri,
     _format_param_help,
+    _parse_uri,
     _read_properties,
-    _resolve_uri,
 )
 
 app = App(
+    name="seedcase-flower",
     help="Flower generates human-readable documentation from Data Packages.",
     help_formatter=DefaultFormatter(
         column_specs=(
@@ -31,7 +33,7 @@
         ),
         config.Toml(
             "pyproject.toml",
-            root_keys="tool.seedcase-flower",
+            root_keys=["tool", "seedcase-flower"],
             search_parents=True,
             use_commands_as_keys=False,
         ),
@@ -50,7 +52,12 @@ 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`, which can also include
+            reference to a tag or branch, such as `gh:org/repo@main` or
+            `gh:org/repo@1.0.1).
         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
@@ -59,8 +66,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,10 +1,12 @@
 """Helper functions for private use."""
 
 import json
+from dataclasses import dataclass
 from enum import Enum
 from itertools import repeat
 from pathlib import Path
 from typing import Any
+from urllib import parse
 
 from cyclopts.annotations import get_hint_name
 from cyclopts.help import HelpEntry
@@ -18,18 +20,54 @@ 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
 
-# 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 _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,
+    )
 
 
 def _format_param_help(entry: HelpEntry) -> str:
@@ -51,3 +89,13 @@ def _add_highlight_syntax(name: str, entry_type: type | None) -> str:
         if get_hint_name(entry_type) == "bool":
             formatted_name = ""
     return formatted_name
+
+
+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}