Merge pull request #12 from globusonline/sc-46817-willdelete-print-command

Add willdelete print CLI command for OpenAPI target extraction

Author: m1yag1

changelog.d/20260109_172045_derek_willdelete_print_command.rst

@@ -0,0 +1,8 @@
+
+Development
+-----------
+
+*   Add ``willdelete print`` CLI command for OpenAPI target extraction.
+    This temporary development command extracts a targeted endpoint from
+    an OpenAPI spec and outputs it in the format expected by
+    ``POST /registered_api``.

justfile

@@ -5,6 +5,7 @@ help:
 
 # Install a development virtual environment (at `./.venv`).
 install:
+    #!/usr/bin/env bash
     if [ ! -d .venv ]; then
         python -m venv .venv
     fi

pyproject.toml

@@ -20,6 +20,8 @@ classifiers = [
 dependencies = [
     "click >=8,<9",
     "globus-sdk >=4",
+    "openapi-pydantic >=0.5.1,<0.6.0",
+    "pyyaml >=6.0",
 ]
 
 [project.urls]

requirements/mypy/pyproject.toml

@@ -6,4 +6,5 @@ name = "dependencies"
 requires-python = ">=3.10"
 dependencies = [
     "mypy",
+    "types-PyYAML",
 ]

requirements/mypy/requirements.txt

@@ -2,4 +2,5 @@ mypy-extensions==1.1.0 ; python_version >= "3.10"
 mypy==1.18.2 ; python_version >= "3.10"
 pathspec==0.12.1 ; python_version >= "3.10"
 tomli==2.3.0 ; python_version == "3.10"
+types-pyyaml==6.0.12.20250402 ; python_version >= "3.10"
 typing-extensions==4.15.0 ; python_version >= "3.10"

src/globus_registered_api/cli.py

@@ -20,6 +20,11 @@
 from globus_sdk import UserApp
 
 from globus_registered_api.extended_flows_client import ExtendedFlowsClient
+from globus_registered_api.openapi import AmbiguousContentTypeError
+from globus_registered_api.openapi import OpenAPILoadError
+from globus_registered_api.openapi import TargetNotFoundError
+from globus_registered_api.openapi import TargetSpecifier
+from globus_registered_api.openapi import process_target
 
 # Constants
 RAPI_NATIVE_CLIENT_ID = "9dc7dfff-cfe8-4339-927b-28d29e1b2f42"
@@ -202,3 +207,43 @@ def list_registered_apis(
                     click.echo("-------------------------------------|-----")
                     first = False
                 click.echo(f"{api['id']} | {api['name']}")
+
+
+# --- willdelete command group ---
+
+
+@cli.group()
+def willdelete() -> None:
+    """Temporary commands for OpenAPI processing development."""
+
+
+@willdelete.command("print")
+@click.argument("openapi_spec", type=click.Path(exists=False))
+@click.argument("route")
+@click.argument("method")
+@click.option(
+    "--content-type",
+    default="*",
+    help="Content-type for request body (required if multiple exist)",
+)
+def willdelete_print(
+    openapi_spec: str, route: str, method: str, content_type: str
+) -> None:
+    """
+    Print a reduced OpenAPI spec for a target endpoint.
+
+    OPENAPI_SPEC is the path to an OpenAPI specification (JSON or YAML).
+    ROUTE is the path to match (e.g., /items or /items/{id}).
+    METHOD is the HTTP method (e.g., get, post, put, delete).
+    """
+    try:
+        target = TargetSpecifier.create(method, route, content_type)
+    except ValueError as e:
+        raise click.ClickException(str(e))
+
+    try:
+        result = process_target(openapi_spec, target)
+    except (OpenAPILoadError, TargetNotFoundError, AmbiguousContentTypeError) as e:
+        raise click.ClickException(str(e))
+
+    click.echo(json.dumps(result.to_dict(), indent=2))

src/globus_registered_api/openapi/__init__.py

@@ -0,0 +1,20 @@
+# This file is a part of globus-registered-api.
+# https://github.com/globusonline/globus-registered-api
+# Copyright 2025 Globus <support@globus.org>
+# SPDX-License-Identifier: Apache-2.0
+
+from globus_registered_api.openapi.loader import OpenAPILoadError
+from globus_registered_api.openapi.processor import process_target
+from globus_registered_api.openapi.processor import ProcessingResult
+from globus_registered_api.openapi.selector import AmbiguousContentTypeError
+from globus_registered_api.openapi.selector import TargetNotFoundError
+from globus_registered_api.openapi.selector import TargetSpecifier
+
+__all__ = [
+    "OpenAPILoadError",
+    "process_target",
+    "ProcessingResult",
+    "AmbiguousContentTypeError",
+    "TargetNotFoundError",
+    "TargetSpecifier",
+]

src/globus_registered_api/openapi/loader.py

@@ -0,0 +1,61 @@
+# This file is a part of globus-registered-api.
+# https://github.com/globusonline/globus-registered-api
+# Copyright 2025 Globus <support@globus.org>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import openapi_pydantic as oa
+import yaml
+from pydantic import ValidationError
+
+
+class OpenAPILoadError(Exception):
+    """Raised when an OpenAPI spec cannot be loaded or parsed."""
+
+
+def load_openapi_spec(path: str | Path) -> oa.OpenAPI:
+    """
+    Load and parse an OpenAPI specification from a file.
+
+    Supports both JSON and YAML formats. The file format is determined
+    by the file extension (.json, .yaml, or .yml).
+
+    :param path: Path to the OpenAPI specification file
+    :return: Parsed OpenAPI specification object
+    :raises OpenAPILoadError: If the file cannot be found, parsed, or validated
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise OpenAPILoadError(f"File not found: {path}")
+
+    try:
+        content = path.read_text()
+    except OSError as e:
+        raise OpenAPILoadError(f"Failed to read file: {path} - {e}") from e
+
+    suffix = path.suffix.lower()
+    try:
+        if suffix == ".json":
+            data = json.loads(content)
+        elif suffix in (".yaml", ".yml"):
+            data = yaml.safe_load(content)
+        else:
+            # Try JSON first, then YAML
+            try:
+                data = json.loads(content)
+            except json.JSONDecodeError:
+                data = yaml.safe_load(content)
+    except json.JSONDecodeError as e:
+        raise OpenAPILoadError(f"Failed to parse JSON: {e}") from e
+    except yaml.YAMLError as e:
+        raise OpenAPILoadError(f"Failed to parse YAML: {e}") from e
+
+    try:
+        return oa.OpenAPI.model_validate(data)
+    except ValidationError as e:
+        raise OpenAPILoadError(f"Invalid OpenAPI specification: {e}") from e

src/globus_registered_api/openapi/processor.py

@@ -0,0 +1,73 @@
+# This file is a part of globus-registered-api.
+# https://github.com/globusonline/globus-registered-api
+# Copyright 2025 Globus <support@globus.org>
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Facade for OpenAPI target processing.
+
+This module provides a simplified interface for OpenAPI processing
+by coordinating loader, selector, and reducer components.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from pathlib import Path
+from typing import Any
+
+import openapi_pydantic as oa
+
+from globus_registered_api.openapi.loader import load_openapi_spec
+from globus_registered_api.openapi.reducer import OpenAPITarget
+from globus_registered_api.openapi.reducer import reduce_to_target
+from globus_registered_api.openapi.selector import TargetSpecifier
+from globus_registered_api.openapi.selector import find_target
+
+
+@dataclass
+class ProcessingResult:
+    """Result of target processing."""
+
+    target: OpenAPITarget
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to the format expected by POST /registered_api."""
+        return self.target.to_dict()
+
+
+def process_target(
+    spec_or_path: oa.OpenAPI | str | Path,
+    target: TargetSpecifier,
+) -> ProcessingResult:
+    """
+    Process an OpenAPI spec to extract a target endpoint.
+
+    This is the primary entry point for target extraction. It coordinates
+    loading, selection, and reduction into a single operation.
+
+    For fine-grained control, use the underlying modules directly:
+    - `loader.load_openapi_spec()` - Parse OpenAPI files
+    - `selector.find_target()` - Locate targets in a spec
+    - `reducer.reduce_to_target()` - Extract target with dependencies
+
+    :param spec_or_path: OpenAPI spec object or path to spec file
+    :param target: Target specifier (method, path, optional content-type)
+    :return: ProcessingResult containing the reduced spec
+    :raises OpenAPILoadError: If spec file cannot be loaded
+    :raises TargetNotFoundError: If route or method not found
+    :raises AmbiguousContentTypeError: If content-type selection is ambiguous
+    """
+    # Load if given a path
+    if isinstance(spec_or_path, (str, Path)):
+        spec = load_openapi_spec(spec_or_path)
+    else:
+        spec = spec_or_path
+
+    # Find and reduce
+    target_info = find_target(spec, target)
+    openapi_target = reduce_to_target(spec, target_info)
+
+    return ProcessingResult(target=openapi_target)