tangle-cli 0.0.1a1__py3-none-any.whl

tangle_cli/components_cli.py

@@ -0,0 +1,269 @@
+import pathlib
+import sys
+from typing import Annotated, Any
+
+from cyclopts import App, Parameter
+
+from .cli_helpers import load_args_or_exit, optional_path
+from .cli_options import ConfigOption, LogTypeOption
+from .logger import logger_for_log_type
+
+app = App(name="components", help="Work with Tangle component definitions.")
+
+generate_app = App(name="generate", help="Generate component definition files.")
+app.command(generate_app)
+
+component_references_app = App(
+    name="component-references", help="Work with component reference metadata."
+)
+app.command(component_references_app)
+
+annotations_app = App(name="annotations", help="Work with component annotations.")
+app.command(annotations_app)
+
+# region components
+
+
+@app.command(name="validate")
+def components_validate(component_path: str):
+    raise NotImplementedError()
+
+
+@app.command(name="set-container-image")
+def components_set_container_image(component_path: str):
+    raise NotImplementedError()
+
+
+# endregion
+
+
+# region components/annotations
+
+
+def _missing_required_args(command_name: str, provided: dict[str, object]) -> None:
+    """Print help for truly empty commands, but error on partial invocations."""
+
+    if all(value is None for value in provided.values()):
+        annotations_app.help_print([command_name])
+        raise SystemExit(0)
+
+    missing = [name for name, value in provided.items() if value is None]
+    print(f"Missing required argument(s): {', '.join(missing)}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+@annotations_app.command(name="set")
+def components_annotations_set(
+    component_path: str | None = None,
+    key: str | None = None,
+    value: str | None = None,
+    output_component_path: str | None = None,
+):
+    """Sets annotation value in component file."""
+    if component_path is None or key is None or value is None:
+        _missing_required_args(
+            "set",
+            {"component_path": component_path, "key": key, "value": value},
+        )
+    raise NotImplementedError()
+
+
+@annotations_app.command(name="get")
+def components_annotations_get(
+    component_path: str | None = None, keys: list[str] | None = None
+):
+    """Gets annotation values from component file."""
+    if component_path is None or keys is None:
+        _missing_required_args("get", {"component_path": component_path, "keys": keys})
+    raise NotImplementedError()
+
+
+# endregion
+
+
+# region components/generate
+
+
+@generate_app.command(name="from-template", show=False)
+def components_generate_from_template(
+    template_name: str,
+    output_component_path: pathlib.Path,
+):
+    raise NotImplementedError()
+
+
+def _components_generate_from_python_impl(
+    *,
+    python_file: pathlib.Path | None = None,
+    output: pathlib.Path | None = None,
+    name: str | None = None,
+    function_name: str | None = None,
+    image: str | None = None,
+    dependencies_from: pathlib.Path | None = None,
+    strip_code: bool | None = None,
+    use_legacy_naming: bool | None = None,
+    mode: str | None = None,
+    resolve_root: pathlib.Path | None = None,
+    config: str | None = None,
+    log_type: str = "console",
+) -> None:
+    all_args = load_args_or_exit(
+        config,
+        python_file=("python_file", python_file, None, False, True, optional_path),
+        output=(output, None, optional_path),
+        name=(name, None),
+        function_name=("function", function_name, None, False),
+        image=(image, None),
+        dependencies_from=(dependencies_from, None, optional_path),
+        strip_code=(strip_code, None),
+        use_legacy_naming=(use_legacy_naming, None),
+        mode=(mode, None),
+        resolve_root=(resolve_root, None, optional_path),
+        log_type=(log_type, "console"),
+    )
+    for args in all_args:
+        logger, finalize_logs = logger_for_log_type(args.log_type)
+        from .component_generator import ComponentGenerator
+
+        generator = ComponentGenerator(logger=logger, verbose=True)
+        selected_mode = args.mode or "inline"
+        if selected_mode not in {"inline", "bundle"}:
+            raise SystemExit("--mode must be 'inline' or 'bundle'")
+        python_path = pathlib.Path(args.python_file)
+        output_path = generator.determine_output_path(
+            python_path,
+            args.output,
+            output_is_dir=False,
+            use_legacy_naming=bool(args.use_legacy_naming),
+        )
+        try:
+            success = generator.regenerate_yaml(
+                python_file=python_path,
+                output_path=output_path,
+                function_name=args.function_name,
+                custom_name=args.name,
+                image=args.image,
+                dependencies_from=args.dependencies_from,
+                strip_code=bool(args.strip_code),
+                mode=selected_mode,
+                resolve_root=args.resolve_root,
+            )
+            if not success:
+                raise SystemExit(1)
+        finally:
+            finalize_logs()
+
+
+@generate_app.command(name="from-python")
+def components_generate_from_python(
+    python_file: pathlib.Path | None = None,
+    *,
+    output: pathlib.Path | None = None,
+    name: str | None = None,
+    function_name: Annotated[
+        str | None,
+        Parameter(name="--function", alias="-f", help="Function name to extract."),
+    ] = None,
+    image: str | None = None,
+    dependencies_from: pathlib.Path | None = None,
+    strip_code: bool | None = None,
+    use_legacy_naming: bool | None = None,
+    mode: str | None = None,
+    resolve_root: pathlib.Path | None = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Generate a component YAML file from a local Python function."""
+
+    _components_generate_from_python_impl(
+        python_file=python_file,
+        output=output,
+        name=name,
+        function_name=function_name,
+        image=image,
+        dependencies_from=dependencies_from,
+        strip_code=strip_code,
+        use_legacy_naming=use_legacy_naming,
+        mode=mode,
+        resolve_root=resolve_root,
+        config=config,
+        log_type=log_type,
+    )
+
+
+@generate_app.command(name="from-python-function")
+def components_generate_from_python_function(
+    python_file: pathlib.Path | None = None,
+    *,
+    output: pathlib.Path | None = None,
+    name: str | None = None,
+    function_name: Annotated[
+        str | None,
+        Parameter(name="--function", alias="-f", help="Function name to extract."),
+    ] = None,
+    image: str | None = None,
+    dependencies_from: pathlib.Path | None = None,
+    strip_code: bool | None = None,
+    use_legacy_naming: bool | None = None,
+    mode: str | None = None,
+    resolve_root: pathlib.Path | None = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Compatibility alias for `generate from-python`."""
+
+    _components_generate_from_python_impl(
+        python_file=python_file,
+        output=output,
+        name=name,
+        function_name=function_name,
+        image=image,
+        dependencies_from=dependencies_from,
+        strip_code=strip_code,
+        use_legacy_naming=use_legacy_naming,
+        mode=mode,
+        resolve_root=resolve_root,
+        config=config,
+        log_type=log_type,
+    )
+
+
+# endregion
+
+
+@app.command(name="bump-version")
+def components_bump_version(
+    yaml_file: pathlib.Path | None = None,
+    *,
+    set_version: str | None = None,
+    update_timestamp: bool | None = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Bump version metadata in a component YAML file."""
+
+    all_args = load_args_or_exit(
+        config,
+        yaml_file=("yaml_file", yaml_file, None, False, True, optional_path),
+        set_version=(set_version, None),
+        update_timestamp=(update_timestamp, None),
+        log_type=(log_type, "console"),
+    )
+    result: dict[str, Any] = {}
+    from .version_manager import bump_version
+
+    for args in all_args:
+        logger, finalize_logs = logger_for_log_type(args.log_type)
+        try:
+            result = bump_version(
+                args.yaml_file,
+                set_version=args.set_version,
+                update_timestamp=bool(args.update_timestamp),
+                logger=logger,
+            )
+            if result.get("status") != "success":
+                raise SystemExit(1)
+        finally:
+            finalize_logs()
+    if result:
+        print(result)

tangle_cli/dynamic_discovery_client.py

@@ -0,0 +1,296 @@
+"""Programmatic dynamic-discovery client for Tangle backends."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from .api_schema import (
+    OperationCommand,
+    fetch_schema,
+    load_cached_schema,
+    operation_aliases,
+    operation_map,
+    refresh_schema,
+    resolve_operation,
+)
+from .api_transport import (
+    DEFAULT_TIMEOUT_SECONDS,
+    _normalize_base_url,
+    default_base_url,
+    request_operation,
+)
+
+
+class TangleDynamicDiscoveryClient:
+    """Dynamic-discovery client generated from a Tangle OpenAPI schema.
+
+    The client intentionally reuses the same schema cache, operation naming,
+    parameter mapping, URL construction, and auth/header handling as
+    ``tangle api ...``. No network or cache work happens at import time; choose
+    one of the ``from_*`` constructors to provide or load a schema.
+    """
+
+    def __init__(
+        self,
+        schema: dict[str, Any],
+        *,
+        base_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        token: str | None = None,
+        auth_header: str | None = None,
+        header: list[str] | str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self.schema = schema
+        self.base_url = _normalize_base_url(base_url or default_base_url())
+        self.headers = dict(headers or {})
+        self.token = token
+        self.auth_header = auth_header
+        self.header = _header_list(header)
+        self.timeout = timeout
+        self._operations = operation_map(schema)
+        self._aliases = self._build_alias_map(self._operations)
+        self._groups = self._build_groups(self._operations)
+
+    @classmethod
+    def from_schema(
+        cls,
+        schema: dict[str, Any],
+        *,
+        base_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        token: str | None = None,
+        auth_header: str | None = None,
+        header: list[str] | str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> TangleDynamicDiscoveryClient:
+        """Create a client from an already loaded OpenAPI schema."""
+
+        return cls(
+            schema,
+            base_url=base_url,
+            headers=headers,
+            token=token,
+            auth_header=auth_header,
+            header=header,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_cache(
+        cls,
+        base_url: str | None = None,
+        *,
+        headers: dict[str, str] | None = None,
+        token: str | None = None,
+        auth_header: str | None = None,
+        header: list[str] | str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> TangleDynamicDiscoveryClient:
+        """Create a client from the local schema cache without network access."""
+
+        normalized_base_url = _normalize_base_url(base_url or default_base_url())
+        schema = load_cached_schema(normalized_base_url)
+        if schema is None:
+            raise FileNotFoundError(
+                f"No cached OpenAPI schema for {normalized_base_url}; "
+                "call TangleDynamicDiscoveryClient.from_cache_or_refresh(...) or run `tangle api refresh`."
+            )
+        return cls.from_schema(
+            schema,
+            base_url=normalized_base_url,
+            headers=headers,
+            token=token,
+            auth_header=auth_header,
+            header=header,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_url(
+        cls,
+        base_url: str | None = None,
+        *,
+        headers: dict[str, str] | None = None,
+        token: str | None = None,
+        auth_header: str | None = None,
+        header: list[str] | str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> TangleDynamicDiscoveryClient:
+        """Fetch ``/openapi.json`` and create a client without writing the cache."""
+
+        normalized_base_url = _normalize_base_url(base_url or default_base_url())
+        schema = fetch_schema(
+            normalized_base_url,
+            token=token,
+            header=header,
+            auth_header=auth_header,
+            headers=headers,
+        )
+        return cls.from_schema(
+            schema,
+            base_url=normalized_base_url,
+            headers=headers,
+            token=token,
+            auth_header=auth_header,
+            header=header,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def from_cache_or_refresh(
+        cls,
+        base_url: str | None = None,
+        *,
+        headers: dict[str, str] | None = None,
+        token: str | None = None,
+        auth_header: str | None = None,
+        header: list[str] | str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> TangleDynamicDiscoveryClient:
+        """Create a client from cache, fetching and caching the schema on miss."""
+
+        normalized_base_url = _normalize_base_url(base_url or default_base_url())
+        schema = load_cached_schema(normalized_base_url)
+        if schema is None:
+            schema, _ = refresh_schema(
+                normalized_base_url,
+                token=token,
+                header=header,
+                auth_header=auth_header,
+                headers=headers,
+            )
+        return cls.from_schema(
+            schema,
+            base_url=normalized_base_url,
+            headers=headers,
+            token=token,
+            auth_header=auth_header,
+            header=header,
+            timeout=timeout,
+        )
+
+    @property
+    def operations(self) -> tuple[str, ...]:
+        """Canonical operation names exposed by this schema."""
+
+        return tuple(sorted(self._operations))
+
+    def request(self, operation_name: str, **params: Any) -> httpx.Response:
+        """Perform an operation and return the raw ``httpx.Response``.
+
+        Operation parameters are passed as keyword arguments. Per-call overrides
+        for ``base_url``, ``token``, ``auth_header``, ``header``, ``headers``,
+        ``body``, and ``timeout`` are also supported.
+        """
+
+        operation = self._resolve(operation_name)
+        base_url = params.pop("base_url", self.base_url)
+        token = params.pop("token", self.token)
+        auth_header = params.pop("auth_header", self.auth_header)
+        header_override = params.pop("header", None)
+        header = self.header + _header_list(header_override)
+        headers_override = params.pop("headers", None)
+        headers = {**self.headers, **dict(headers_override or {})}
+        body = params.pop("body", None)
+        timeout = params.pop("timeout", self.timeout)
+        return request_operation(
+            operation,
+            params,
+            base_url=base_url,
+            token=token,
+            auth_header=auth_header,
+            header_entries=header,
+            headers=headers,
+            body=body,
+            timeout=timeout,
+        )
+
+    def call(self, operation_name: str, **params: Any) -> Any:
+        """Perform an operation and decode the response body.
+
+        JSON responses return decoded JSON; text responses return ``str``;
+        non-text responses return ``bytes``; empty responses return ``None``.
+        """
+
+        return decode_response(self.request(operation_name, **params))
+
+    def __getattr__(self, name: str) -> _OperationGroup:
+        canonical_group = self._groups.get(name) or self._groups.get(name.replace("_", "-"))
+        if canonical_group is None:
+            raise AttributeError(name)
+        return _OperationGroup(self, canonical_group)
+
+    def _resolve(self, operation_name: str) -> OperationCommand:
+        return self._aliases.get(operation_name) or resolve_operation(self._operations, operation_name)
+
+    @staticmethod
+    def _build_alias_map(
+        operations: dict[str, OperationCommand]
+    ) -> dict[str, OperationCommand]:
+        aliases: dict[str, OperationCommand] = {}
+        for name, operation in operations.items():
+            for alias in operation_aliases(name):
+                aliases.setdefault(alias, operation)
+        return aliases
+
+    @staticmethod
+    def _build_groups(
+        operations: dict[str, OperationCommand]
+    ) -> dict[str, str]:
+        groups: dict[str, str] = {}
+        for operation in operations.values():
+            groups.setdefault(operation.group_name, operation.group_name)
+            groups.setdefault(operation.group_name.replace("-", "_"), operation.group_name)
+        return groups
+
+
+class _OperationGroup:
+    """Dynamic operation namespace returned by ``client.<resource>``."""
+
+    def __init__(self, client: TangleDynamicDiscoveryClient, group_name: str) -> None:
+        self._client = client
+        self._group_name = group_name
+
+    def call(self, command_name: str, **params: Any) -> Any:
+        return self._client.call(f"{self._group_name}.{command_name}", **params)
+
+    def request(self, command_name: str, **params: Any) -> httpx.Response:
+        return self._client.request(f"{self._group_name}.{command_name}", **params)
+
+    def __getattr__(self, name: str) -> Callable[..., Any]:
+        operation_name = f"{self._group_name}.{name}"
+        try:
+            self._client._resolve(operation_name)
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+        def operation(**params: Any) -> Any:
+            return self._client.call(operation_name, **params)
+
+        operation.__name__ = name
+        return operation
+
+
+def _header_list(header: list[str] | str | None) -> list[str]:
+    if header is None:
+        return []
+    if isinstance(header, str):
+        return [header]
+    return list(header)
+
+
+def decode_response(response: httpx.Response) -> Any:
+    """Decode an ``httpx.Response`` into JSON, text, bytes, or ``None``."""
+
+    if not response.content:
+        return None
+    content_type = response.headers.get("Content-Type", "").lower()
+    if "json" in content_type:
+        return response.json()
+    if content_type.startswith("text/") or "charset=" in content_type:
+        return response.text
+    return response.content