data-annotations 2.1.2__py3-none-any.whl

data_annotations/cli_app/common.py

@@ -0,0 +1,276 @@
+import json
+import shlex
+from pathlib import Path
+from typing import Annotated, Any, NoReturn, cast
+
+import typer
+
+from data_annotations.provenance.models import ArtifactKind
+from data_annotations.provenance import git as provenance_git
+from data_annotations.provenance import recovery as provenance_recovery
+
+_ARTIFACT_KINDS: tuple[ArtifactKind, ...] = (
+    "plot",
+    "model",
+    "table",
+    "dataset",
+    "report",
+    "other",
+)
+_DIRECTORY_SIDECARS = frozenset({"manifest.json", "README.md", "schema.json"})
+_ANNOTATION_SUFFIXES = (".meta.json", ".README.md", ".prov.json", ".schema.json")
+_UNKNOWN_SELECTION = "__unknown__"
+
+INPUT_OPTION = typer.Option(
+    "--input",
+    help="Input file path or URI used to generate the artifact. Repeatable.",
+)
+PARAM_OPTION = typer.Option(
+    "--param",
+    help="Generation parameter as KEY=VALUE. Repeatable.",
+)
+SCRIPT_OPTION = typer.Option(
+    "--script",
+    help="Original script path used to generate the artifact.",
+)
+SCRIPT_REPO_PATH_OPTION = typer.Option(
+    "--script-repo-path",
+    help="Original generating script path relative to the repository root.",
+)
+COMMAND_OPTION = typer.Option(
+    "--command",
+    help="Original command used to generate the artifact, as one quoted string.",
+)
+FUNCTION_OPTION = typer.Option(
+    "--function",
+    help="Generating function to record in the manifest.",
+)
+GIT_SHA_OPTION = typer.Option("--git-sha", help="Original Git SHA.")
+GIT_BRANCH_OPTION = typer.Option(
+    "--git-branch",
+    help="Original Git branch.",
+)
+GIT_REMOTE_NAME_OPTION = typer.Option(
+    "--git-remote-name",
+    help="Original Git remote name.",
+)
+GIT_REMOTE_URL_OPTION = typer.Option(
+    "--git-remote-url",
+    help="Original Git remote URL.",
+)
+GIT_DIRTY_OPTION = typer.Option(
+    "--git-dirty/--no-git-dirty",
+    help="Whether the original working tree was dirty.",
+)
+FORCE_OPTION = typer.Option(
+    "--force",
+    help="Overwrite any existing annotation sidecars.",
+)
+
+InputValuesOption = Annotated[list[str] | None, INPUT_OPTION]
+ParamValuesOption = Annotated[list[str] | None, PARAM_OPTION]
+ScriptOption = Annotated[str | None, SCRIPT_OPTION]
+ScriptRepoPathOption = Annotated[str | None, SCRIPT_REPO_PATH_OPTION]
+CommandOption = Annotated[str | None, COMMAND_OPTION]
+FunctionOption = Annotated[str | None, FUNCTION_OPTION]
+GitShaOption = Annotated[str | None, GIT_SHA_OPTION]
+GitBranchOption = Annotated[str | None, GIT_BRANCH_OPTION]
+GitRemoteNameOption = Annotated[str | None, GIT_REMOTE_NAME_OPTION]
+GitRemoteUrlOption = Annotated[str | None, GIT_REMOTE_URL_OPTION]
+GitDirtyOption = Annotated[bool | None, GIT_DIRTY_OPTION]
+ForceOption = Annotated[bool, FORCE_OPTION]
+
+
+def _error(message: str, *, code: int = 2) -> NoReturn:
+    typer.secho(f"Error: {message}", err=True, fg=typer.colors.RED)
+    raise typer.Exit(code=code)
+
+
+def _is_manifest_path(path: Path) -> bool:
+    return path.name == "manifest.json" or str(path).endswith(".meta.json")
+
+
+def _resolved_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve()
+
+
+def _resolve_manifest_path(target: Path, manifest: Path | None) -> Path:
+    if manifest is not None:
+        manifest_path = _resolved_path(manifest)
+        if not manifest_path.is_file():
+            _error(f"manifest not found: {manifest_path}")
+        return manifest_path
+
+    target_path = _resolved_path(target)
+    if _is_manifest_path(target_path):
+        if not target_path.is_file():
+            _error(f"manifest not found: {target_path}")
+        return target_path
+
+    if target_path.is_file():
+        manifest_path = Path(str(target_path) + ".meta.json")
+        if manifest_path.is_file():
+            return manifest_path.resolve()
+        _error(f"no annotation sidecar found for file: {target_path}")
+
+    if target_path.is_dir():
+        manifest_path = (target_path / "manifest.json").resolve()
+        if manifest_path.is_file():
+            return manifest_path
+        _error(f"no manifest.json found in directory: {target_path}")
+
+    _error(f"target does not exist: {target_path}")
+
+
+def _match_target_path(target: Path, manifest: Path | None) -> Path:
+    if manifest is not None:
+        target_path = _resolved_path(target)
+        if not target_path.exists():
+            _error(f"target does not exist: {target_path}")
+        return target_path
+
+    target_path = _resolved_path(target)
+    if not _is_manifest_path(target_path):
+        if not target_path.exists():
+            _error(f"target does not exist: {target_path}")
+        return target_path
+
+    loaded_manifest = provenance_recovery._load_manifest(target_path)
+    derived_target = (
+        _resolved_path(loaded_manifest.artifact_path)
+        if isinstance(loaded_manifest, provenance_recovery.FileManifest)
+        else _resolved_path(loaded_manifest.output_dir)
+    )
+    if not derived_target.exists():
+        _error(
+            f"recorded artifact path from manifest does not exist locally: {derived_target}"
+        )
+    return derived_target
+
+
+def _echo_entries(title: str, entries: tuple[str, ...]) -> None:
+    if not entries:
+        return
+    typer.echo(f"{title}:")
+    for entry in entries:
+        typer.echo(f"  - {entry}")
+
+
+def _checkout_hint(target: str, manifest: str | None) -> str:
+    parts = [
+        "data-annotations",
+        "provenance",
+        "checkout",
+        shlex.quote(target),
+    ]
+    if manifest is not None:
+        parts.extend(["--manifest", shlex.quote(manifest)])
+    return " ".join(parts)
+
+
+def _missing_checkout_fields(
+    manifest: provenance_recovery.FileManifest | provenance_recovery.DirectoryManifest,
+) -> tuple[str, ...]:
+    missing: list[str] = []
+    if manifest.git_remote_url is None:
+        missing.append("git_remote_url")
+    if manifest.git_sha is None:
+        missing.append("git_sha")
+    return tuple(missing)
+
+
+def _annotation_paths_for_file(artifact_path: Path) -> tuple[Path, Path]:
+    return (
+        Path(str(artifact_path) + ".meta.json"),
+        Path(str(artifact_path) + ".README.md"),
+    )
+
+
+def _annotation_paths_for_directory(output_dir: Path) -> tuple[Path, Path]:
+    return (
+        output_dir / "manifest.json",
+        output_dir / "README.md",
+    )
+
+
+def _ensure_annotation_outputs_available(
+    paths: tuple[Path, ...],
+    *,
+    force: bool,
+) -> None:
+    existing_paths = [path for path in paths if path.exists()]
+    if existing_paths and not force:
+        formatted_paths = ", ".join(str(path) for path in existing_paths)
+        _error(
+            "annotation sidecars already exist; rerun with --force to overwrite: "
+            + formatted_paths,
+            code=1,
+        )
+
+
+def _is_annotation_sidecar(path: Path) -> bool:
+    return path.name in _DIRECTORY_SIDECARS or path.name.endswith(_ANNOTATION_SUFFIXES)
+
+
+def _discover_directory_files(output_dir: Path) -> list[Path]:
+    return sorted(
+        [
+            candidate.resolve()
+            for candidate in output_dir.iterdir()
+            if candidate.is_file() and not _is_annotation_sidecar(candidate)
+        ],
+        key=lambda candidate: candidate.name,
+    )
+
+
+def _validate_artifact_kind(value: str) -> ArtifactKind:
+    normalized = value.strip().lower()
+    if normalized not in _ARTIFACT_KINDS:
+        allowed = ", ".join(_ARTIFACT_KINDS)
+        _error(f"invalid artifact kind {value!r}; expected one of: {allowed}")
+    return cast(ArtifactKind, normalized)
+
+
+def _parse_command_string(value: str) -> list[str]:
+    try:
+        return shlex.split(value)
+    except ValueError as exc:
+        _error(f"invalid shell command: {exc}")
+
+
+def _parse_param_entry(entry: str) -> tuple[str, Any]:
+    if "=" not in entry:
+        _error(f"invalid --param value {entry!r}; expected KEY=VALUE")
+    key, raw_value = entry.split("=", 1)
+    key = key.strip()
+    if not key:
+        _error(f"invalid --param value {entry!r}; key cannot be empty")
+    try:
+        value = json.loads(raw_value)
+    except json.JSONDecodeError:
+        value = raw_value
+    return key, value
+
+
+def _collect_params(param_entries: list[str] | None) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    for entry in param_entries or []:
+        key, value = _parse_param_entry(entry)
+        params[key] = value
+    return params
+
+
+def _normalize_script_path(value: str) -> str:
+    return str(_resolved_path(value))
+
+
+def _normalize_remote_url(value: str) -> str:
+    sanitized = provenance_git._sanitize_remote_url(value)
+    return value if sanitized is None else sanitized
+
+
+def _is_current_annotation_command(command: list[str]) -> bool:
+    if len(command) < 2:
+        return False
+    first = Path(command[0]).name
+    return first == "data-annotations" and command[1] == "annotate"