uipath 2.1.131__py3-none-any.whl → 2.1.133__py3-none-any.whl

uipath/_cli/__init__.py

@@ -4,6 +4,7 @@ import sys
 import click
 
 from ._utils._common import add_cwd_to_path, load_environment_variables
+from ._utils._context import CliContext
 from .cli_add import add as add
 from .cli_auth import auth as auth
 from .cli_debug import debug as debug  # type: ignore
@@ -20,6 +21,9 @@ from .cli_push import push as push  # type: ignore
 from .cli_register import register as register  # type: ignore
 from .cli_run import run as run  # type: ignore
 
+load_environment_variables()
+add_cwd_to_path()
+
 
 def _get_safe_version() -> str:
     """Get the version of the uipath package."""
@@ -46,9 +50,39 @@ def _get_safe_version() -> str:
     is_flag=True,
     help="Display the current version of uipath.",
 )
-def cli(lv: bool, v: bool) -> None:
-    load_environment_variables()
-    add_cwd_to_path()
+@click.option(
+    "--format",
+    type=click.Choice(["json", "table", "csv"]),
+    default="table",
+    help="Output format for commands",
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Enable debug logging and show stack traces",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    lv: bool,
+    v: bool,
+    format: str,
+    debug: bool,
+) -> None:
+    """UiPath CLI - Automate everything.
+
+    \b
+    Examples:
+        uipath new my-project
+        uipath dev
+        uipath deploy
+        uipath buckets list --folder-path "Shared"
+    """  # noqa: D301
+    ctx.obj = CliContext(
+        output_format=format,
+        debug=debug,
+    )
+
     if lv:
         try:
             version = importlib.metadata.version("uipath-langchain")
@@ -64,6 +98,10 @@ def cli(lv: bool, v: bool) -> None:
             click.echo("uipath is not installed", err=True)
             sys.exit(1)
 
+    # Show help if no command was provided (matches docker, kubectl, git behavior)
+    if ctx.invoked_subcommand is None and not lv and not v:
+        click.echo(ctx.get_help())
+
 
 cli.add_command(new)
 cli.add_command(init)
@@ -80,3 +118,7 @@ cli.add_command(dev)
 cli.add_command(add)
 cli.add_command(register)
 cli.add_command(debug)
+
+from .services import register_service_commands  # noqa: E402
+
+register_service_commands(cli)

uipath/_cli/_runtime/_contracts.py

@@ -384,6 +384,7 @@ class UiPathRuntimeContext(BaseModel):
     chat_handler: Optional[UiPathConversationHandler] = None
     is_conversational: Optional[bool] = None
     breakpoints: Optional[List[str] | Literal["*"]] = None
+    intercept_logs: bool = True
 
     model_config = {"arbitrary_types_allowed": True, "extra": "allow"}
 
@@ -631,16 +632,17 @@ class UiPathBaseRuntime(ABC):
 
         # Intercept all stdout/stderr/logs
         # write to file (runtime) or stdout (debug)
-        self.logs_interceptor = LogsInterceptor(
-            min_level=self.context.logs_min_level,
-            dir=self.context.runtime_dir,
-            file=self.context.logs_file,
-            job_id=self.context.job_id,
-            execution_id=self.context.execution_id,
-            is_debug_run=self.is_debug_run(),
-            log_handler=self.context.log_handler,
-        )
-        self.logs_interceptor.setup()
+        if self.context.intercept_logs:
+            self.logs_interceptor = LogsInterceptor(
+                min_level=self.context.logs_min_level,
+                dir=self.context.runtime_dir,
+                file=self.context.logs_file,
+                job_id=self.context.job_id,
+                execution_id=self.context.execution_id,
+                is_debug_run=self.is_debug_run(),
+                log_handler=self.context.log_handler,
+            )
+            self.logs_interceptor.setup()
 
         logger.debug(f"Starting runtime with job id: {self.context.job_id}")
 

uipath/_cli/_utils/_context.py

@@ -0,0 +1,65 @@
+"""Type-safe context management for Click commands.
+
+This module provides type-safe access to CLI context across all commands,
+improving developer experience and enabling better IDE autocomplete.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import click
+
+
+@dataclass
+class CliContext:
+    """CLI global context object.
+
+    This provides type-safe access to configuration shared across all commands.
+    Using a dataclass ensures all attributes are properly typed and documented.
+
+    Attributes:
+        output_format: Output format (table, json, csv)
+        debug: Enable debug logging
+
+    Note:
+        Authentication (URL and secret) are always read from environment variables
+        (UIPATH_URL and UIPATH_ACCESS_TOKEN).
+    """
+
+    output_format: str = "table"
+    debug: bool = False
+
+    _client: Any = field(default=None, init=False, repr=False)
+
+
+def get_cli_context(ctx: click.Context) -> CliContext:
+    """Type-safe helper to retrieve CliContext from Click context.
+
+    This eliminates repeated cast() calls and provides autocompletion
+    for CLI context attributes.
+
+    Args:
+        ctx: Click context object
+
+    Returns:
+        Typed CliContext object
+
+    Raises:
+        click.ClickException: If context object is not properly initialized
+
+    Example:
+        >>> @buckets.command()
+        >>> @click.pass_context
+        >>> def list(ctx):
+        ...     cli_ctx = get_cli_context(ctx)  # Fully typed!
+        ...     print(cli_ctx.output_format)  # Autocomplete works
+    """
+    if not isinstance(ctx.obj, CliContext):
+        raise click.ClickException(
+            "Internal error: CLI context not initialized. "
+            "This is a bug - please report it."
+        )
+    return ctx.obj
+
+
+pass_cli_context = click.make_pass_decorator(CliContext, ensure=True)

uipath/_cli/_utils/_formatters.py

@@ -0,0 +1,173 @@
+"""Output formatting for different output modes.
+
+This module provides consistent output formatting across all CLI commands,
+supporting multiple formats (table, JSON, CSV) with proper handling of
+Pydantic models, iterators, and large datasets.
+"""
+
+import csv
+import json
+from collections.abc import Generator, Iterator
+from io import StringIO
+from pathlib import Path
+from typing import Any, Optional
+
+import click
+
+
+def format_output(
+    data: Any,
+    fmt: str = "table",
+    output: Optional[str] = None,
+    no_color: bool = False,
+) -> None:
+    """Format and output data to stdout or file.
+
+    Handles:
+    - Pydantic models (via model_dump())
+    - Iterators and generators (converts to list)
+    - Lists, dicts, primitives
+    - Large datasets (warns at 10k+ items)
+
+    Args:
+        data: Data to format
+        fmt: Output format (json, table, csv)
+        output: Optional file path to write to
+        no_color: Disable colored output for table format
+
+    Example:
+        >>> format_output([{"name": "bucket1"}, {"name": "bucket2"}], fmt="table")
+        name
+        --------
+        bucket1
+        bucket2
+    """
+    if isinstance(data, (Iterator, Generator)):
+        data = list(data)
+        # Warn about large datasets
+        if len(data) > 10000:
+            click.echo(
+                f"Warning: Loading {len(data)} items into memory for formatting. "
+                "This may be slow or cause memory issues. "
+                "Consider using --limit or redirecting output for large datasets.",
+                err=True,
+            )
+
+    if hasattr(data, "model_dump"):
+        data = data.model_dump()
+    elif isinstance(data, list) and len(data) > 0 and hasattr(data[0], "model_dump"):
+        data = [item.model_dump() for item in data]
+
+    if hasattr(data, "__aiter__"):
+        raise TypeError(
+            "Async iterators not supported in CLI output. "
+            "Use synchronous methods or convert to list first."
+        )
+
+    if output and fmt == "table":
+        no_color = True
+
+    if fmt == "json":
+        text = _format_json(data)
+    elif fmt == "table":
+        text = _format_table(data, no_color=no_color)
+    elif fmt == "csv":
+        text = _format_csv(data)
+    else:
+        text = str(data)
+
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+        click.echo(f"Output written to {output}", err=True)
+    else:
+        click.echo(text)
+
+
+def _format_json(data: Any) -> str:
+    """Format data as JSON.
+
+    Args:
+        data: Data to format
+
+    Returns:
+        JSON string with 2-space indentation
+    """
+    return json.dumps(data, indent=2, default=str)
+
+
+def _format_table(data: Any, no_color: bool = False) -> str:
+    """Format data as simple table (AWS/Azure CLI style).
+
+    Uses a simple ASCII table format with column alignment similar to
+    AWS CLI and Azure CLI, avoiding fancy box-drawing characters.
+
+    Args:
+        data: Data to format
+        no_color: Disable colored output (ignored, kept for API compatibility)
+
+    Returns:
+        Formatted table string
+    """
+    items = data if isinstance(data, list) else [data]
+    if not items:
+        return "No results"
+
+    if not isinstance(items[0], dict):
+        items = [{"value": str(item)} for item in items]
+
+    columns = list(items[0].keys())
+
+    str_items = []
+    for item in items:
+        str_items.append({col: str(item.get(col, "")) for col in columns})
+
+    col_widths = {}
+    for col in columns:
+        col_widths[col] = len(col)
+        for item in str_items:
+            col_widths[col] = max(col_widths[col], len(item[col]))
+
+    header_parts = []
+    separator_parts = []
+    for col in columns:
+        header_parts.append(col.ljust(col_widths[col]))
+        separator_parts.append("-" * col_widths[col])
+
+    header = "  ".join(header_parts)
+    separator = "  ".join(separator_parts)
+
+    rows = []
+    for item in str_items:
+        row_parts = [item[col].ljust(col_widths[col]) for col in columns]
+        rows.append("  ".join(row_parts))
+
+    return "\n".join([header, separator, *rows])
+
+
+def _format_csv(data: Any) -> str:
+    """Format data as CSV.
+
+    Args:
+        data: Data to format
+
+    Returns:
+        CSV string with header
+    """
+    items = data if isinstance(data, list) else [data]
+    if not items:
+        return ""
+
+    if not isinstance(items[0], dict):
+        items = [{"value": str(item)} for item in items]
+
+    columns = list(items[0].keys())
+
+    output = StringIO()
+    writer = csv.DictWriter(output, fieldnames=columns, extrasaction="ignore")
+    writer.writeheader()
+
+    for item in items:
+        normalized_row = {col: item.get(col, "") for col in columns}
+        writer.writerow(normalized_row)
+
+    return output.getvalue()

uipath/_cli/_utils/_service_base.py

@@ -0,0 +1,340 @@
+"""Base utilities for service commands.
+
+This module provides decorators and utilities for implementing service-specific
+CLI commands with consistent error handling, async support, and output formatting.
+
+Key features:
+- Sequential decorator composition
+- Type-safe context access
+- Enhanced Click exception handling
+- Async/await support
+- Consistent error messages
+"""
+
+import asyncio
+import inspect
+from functools import wraps
+from typing import Any, Callable
+
+import click
+from httpx import HTTPError
+
+from ...models.errors import BaseUrlMissingError, SecretMissingError
+from ...models.exceptions import EnrichedException
+from ._context import get_cli_context
+
+
+def handle_not_found_error(
+    resource: str, identifier: str, error: Exception | None = None
+) -> None:
+    """Handle 404/LookupError and raise consistent ClickException.
+
+    Args:
+        resource: The resource type (e.g., "Bucket", "Asset", "Queue")
+        identifier: The resource identifier (name, key, etc.)
+        error: Optional original error for chaining
+
+    Raises:
+        click.ClickException: Always raises with consistent message
+    """
+    message = f"{resource} '{identifier}' not found."
+    if error:
+        raise click.ClickException(message) from error
+    else:
+        raise click.ClickException(message) from None
+
+
+def service_command(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator for service commands with async support, error handling, and output.
+
+    This decorator handles:
+    - Sync and async function execution
+    - Output formatting (JSON, table, CSV)
+    - Error handling with proper Click exceptions
+    - Separation of logs (stderr) from data (stdout)
+    - Type-safe context access via get_cli_context()
+    - Enhanced Click exception handling (don't catch Click's own exceptions)
+    - Domain errors converted to click.ClickException
+    - Automatic context injection (no need for @click.pass_context)
+
+    Example:
+        >>> @buckets.command()
+        >>> @service_command
+        >>> async def list_async(ctx):
+        ...     # Context is automatically passed - no @click.pass_context needed
+        ...     return await client.buckets.list_async()
+
+    Note:
+        Do NOT stack @click.pass_context with this decorator - context is
+        already injected by the @wraps(f) and @click.pass_context inside
+        service_command.
+    """
+
+    @wraps(f)
+    @click.pass_context
+    def wrapper(ctx, *args, **kwargs):
+        cli_ctx = get_cli_context(ctx)
+
+        try:
+            result = f(ctx, *args, **kwargs)
+
+            if inspect.isawaitable(result):
+                try:
+                    result = asyncio.run(result)  # type: ignore[arg-type]
+                except RuntimeError as e:
+                    if "cannot be called from a running event loop" in str(e).lower():
+                        prev_loop = asyncio.get_event_loop()
+                        if prev_loop.is_running():
+                            loop = asyncio.new_event_loop()
+                            try:
+                                asyncio.set_event_loop(loop)
+                                result = loop.run_until_complete(result)
+                            finally:
+                                try:
+                                    loop.close()
+                                finally:
+                                    asyncio.set_event_loop(prev_loop)
+                        else:
+                            result = prev_loop.run_until_complete(result)
+                    else:
+                        raise
+
+            # Format and output result
+            if result is not None:
+                from ._formatters import format_output
+
+                fmt = kwargs.get("format") or cli_ctx.output_format
+                output = kwargs.get("output")
+
+                format_output(
+                    result,
+                    fmt=fmt,
+                    output=output,
+                    no_color=False,  # Auto-detected for file output
+                )
+
+            return result
+
+        except click.ClickException:
+            raise
+
+        except BaseUrlMissingError:
+            raise click.ClickException(
+                "UIPATH_URL not configured. Set the UIPATH_URL environment variable or run 'uipath auth'."
+            ) from None
+
+        except SecretMissingError:
+            raise click.ClickException(
+                "Authentication required. Set the UIPATH_ACCESS_TOKEN environment variable or run 'uipath auth'."
+            ) from None
+
+        except EnrichedException as e:
+            if cli_ctx.debug:
+                raise
+
+            if e.status_code == 401:
+                raise click.ClickException(
+                    "Authentication failed (401). Your access token may have expired or is invalid.\n"
+                    "Please run 'uipath auth' to re-authenticate."
+                ) from e
+
+            if e.status_code == 400:
+                try:
+                    import json
+
+                    error_data = json.loads(e.response_content)
+                    if (
+                        isinstance(error_data, dict)
+                        and error_data.get("errorCode") == 1101
+                    ):
+                        raise click.ClickException(
+                            "Folder context required (400). The command requires a folder to be specified.\n"
+                            'Set UIPATH_FOLDER_PATH environment variable (e.g., export UIPATH_FOLDER_PATH="Shared") '
+                            'or use the --folder-path option (e.g., --folder-path "Shared").'
+                        ) from e
+                except (ValueError, json.JSONDecodeError):
+                    pass
+
+            raise click.ClickException(str(e)) from e
+
+        except HTTPError as e:
+            if cli_ctx.debug:
+                raise
+            response = getattr(e, "response", None)
+
+            if response and response.status_code == 401:
+                raise click.ClickException(
+                    "Authentication failed (401). Your access token may have expired or is invalid.\n"
+                    "Please run 'uipath auth' to re-authenticate."
+                ) from e
+
+            if response and response.status_code == 400:
+                try:
+                    error_data = response.json()
+                    if (
+                        isinstance(error_data, dict)
+                        and error_data.get("errorCode") == 1101
+                    ):
+                        raise click.ClickException(
+                            "Folder context required (400). The command requires a folder to be specified.\n"
+                            'Set UIPATH_FOLDER_PATH environment variable (e.g., export UIPATH_FOLDER_PATH="Shared") '
+                            'or use the --folder-path option (e.g., --folder-path "Shared").'
+                        ) from e
+                except ValueError:
+                    pass
+
+            if response:
+                error_msg = f"HTTP Error {response.status_code}: {response.url}"
+                if hasattr(response, "text"):
+                    try:
+                        import json
+
+                        response_data = response.json()
+                        sensitive_fields = {
+                            "access_token",
+                            "refresh_token",
+                            "password",
+                            "secret",
+                            "api_key",
+                            "authorization",
+                        }
+                        if isinstance(response_data, dict):
+                            for key in list(response_data.keys()):
+                                if any(
+                                    sensitive in key.lower()
+                                    for sensitive in sensitive_fields
+                                ):
+                                    response_data[key] = "***REDACTED***"
+                        error_details = json.dumps(response_data, indent=2)
+                        error_msg += f"\nResponse:\n{error_details[:500]}"
+                    except Exception:
+                        error_msg += f"\nResponse: {response.text[:200]}"
+            else:
+                error_msg = f"HTTP Error: {str(e)}"
+            raise click.ClickException(error_msg) from e
+
+        except Exception as e:
+            if cli_ctx.debug:
+                raise
+            raise click.ClickException(str(e)) from e
+
+    return wrapper
+
+
+def common_service_options(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Add common options for service commands.
+
+    Adds:
+    - --folder-path: Folder path (e.g., "Shared") with validation
+    - --folder-key: Folder key (UUID) with validation
+    - --format: Output format override
+    - --output: Output file override
+    """
+    from ._validators import validate_folder_path, validate_uuid
+
+    decorators = [
+        click.option(
+            "--folder-path",
+            callback=validate_folder_path,
+            help='Folder path (e.g., "Shared"). Can also be set via UIPATH_FOLDER_PATH environment variable.',
+        ),
+        click.option("--folder-key", callback=validate_uuid, help="Folder key (UUID)"),
+        click.option(
+            "--format",
+            type=click.Choice(["json", "table", "csv"]),
+            help="Output format (overrides global)",
+        ),
+        click.option(
+            "--output", "-o", type=click.Path(), help="Output file (overrides global)"
+        ),
+    ]
+
+    for decorator in reversed(decorators):
+        f = decorator(f)
+
+    return f
+
+
+def standard_service_command(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Convenience decorator for standard service commands.
+
+    This composes decorators in explicit, sequential order:
+    1. service_command (execution & error handling)
+    2. common_service_options (folder, format, output)
+
+    The sequential pattern makes the decorator stack more readable
+    and easier for AI agents to understand.
+
+    Usage:
+        >>> # Simple command
+        >>> @buckets.command()
+        >>> @standard_service_command
+        >>> def retrieve(ctx, name, folder_path, ...):
+        ...     pass
+
+        >>> # Custom composition (when you need flexibility)
+        >>> @buckets.command()
+        >>> @service_command
+        >>> @click.option('--custom-flag', ...)
+        >>> @common_service_options
+        >>> @click.pass_context
+        >>> def special(ctx, custom_flag, ...):
+        ...     pass
+    """
+    decorated_func = f
+
+    decorated_func = service_command(decorated_func)
+
+    decorated_func = common_service_options(decorated_func)
+
+    return decorated_func
+
+
+class ServiceCommandBase:
+    """Base class for service command utilities."""
+
+    @staticmethod
+    def get_client(ctx):
+        """Get or create UiPath client from context.
+
+        This caches the client in the CLI context to avoid recreating
+        it for every command invocation.
+
+        Args:
+            ctx: Click context
+
+        Returns:
+            UiPath client instance
+
+        Raises:
+            click.ClickException: If required environment variables are not set
+        """
+        import os
+
+        import click
+
+        cli_ctx = get_cli_context(ctx)
+
+        if cli_ctx._client is None:
+            from ..._uipath import UiPath
+
+            base_url = os.environ.get("UIPATH_URL")
+            secret = os.environ.get("UIPATH_ACCESS_TOKEN")
+
+            if not base_url:
+                raise click.ClickException(
+                    "UIPATH_URL not configured. Set the UIPATH_URL environment variable or run 'uipath auth'."
+                )
+
+            if not secret:
+                raise click.ClickException(
+                    "Authentication required. Set the UIPATH_ACCESS_TOKEN environment variable or run 'uipath auth'."
+                )
+
+            cli_ctx._client = UiPath(
+                base_url=base_url,
+                secret=secret,
+                debug=cli_ctx.debug,
+            )
+
+        return cli_ctx._client