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

uipath/_cli/_utils/_service_metadata.py

@@ -0,0 +1,218 @@
+"""Service metadata models using Pydantic.
+
+This module defines the metadata structure for CLI service command generation.
+All models are immutable (frozen) to prevent accidental modification after creation.
+
+The metadata describes:
+- Service identification (name, resource type)
+- CRUD operation parameters
+- Command configuration (confirmation, dry-run support)
+
+Example:
+    >>> from ._service_metadata import ServiceMetadata, CreateParameter
+    >>>
+    >>> BUCKETS_METADATA = ServiceMetadata(
+    ...     service_name="buckets",
+    ...     service_attr="buckets",
+    ...     resource_type="Bucket",
+    ...     create_params={
+    ...         "description": CreateParameter(
+    ...             type="str",
+    ...             required=False,
+    ...             help="Bucket description",
+    ...         )
+    ...     },
+    ... )
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class CreateParameter(BaseModel):
+    """Metadata for a single create command parameter.
+
+    This defines how a parameter should appear in the CLI command.
+
+    Attributes:
+        type: Type name from TYPE_REGISTRY (e.g., "str", "int", "bool", "float")
+        required: Whether the parameter is required (default: False)
+        help: Help text shown in --help output
+        default: Default value if not provided by user
+        option_name: CLI option name (default: derived from field name)
+
+    Example:
+        >>> description_param = CreateParameter(
+        ...     type="str",
+        ...     required=False,
+        ...     help="Resource description",
+        ...     default=None,
+        ... )
+    """
+
+    type: str
+    required: bool = False
+    help: str = ""
+    default: Any = None
+    option_name: str | None = None
+
+    class Config:
+        """Pydantic configuration."""
+
+        frozen = True
+
+
+class DeleteCommandConfig(BaseModel):
+    """Configuration for delete command behavior.
+
+    Attributes:
+        confirmation_required: Whether to require --confirm flag (default: True)
+        dry_run_supported: Whether to support --dry-run flag (default: True)
+        confirmation_prompt: Custom confirmation prompt template
+
+    Example:
+        >>> delete_config = DeleteCommandConfig(
+        ...     confirmation_required=True,
+        ...     dry_run_supported=True,
+        ...     confirmation_prompt="Delete {resource} '{identifier}'?",
+        ... )
+    """
+
+    confirmation_required: bool = True
+    dry_run_supported: bool = True
+    confirmation_prompt: str | None = None
+
+    class Config:
+        """Pydantic configuration."""
+
+        frozen = True
+
+
+class ExistsCommandConfig(BaseModel):
+    """Configuration for exists command behavior.
+
+    Attributes:
+        identifier_arg_name: Name of the identifier argument (default: "name")
+        return_format: Format of the return value ("bool", "dict", "text")
+
+    Example:
+        >>> exists_config = ExistsCommandConfig(
+        ...     identifier_arg_name="key",
+        ...     return_format="dict",
+        ... )
+    """
+
+    identifier_arg_name: str = "name"
+    return_format: str = "dict"  # "bool", "dict", or "text"
+
+    class Config:
+        """Pydantic configuration."""
+
+        frozen = True
+
+
+class ServiceMetadata(BaseModel):
+    """Complete metadata for a service's CLI commands.
+
+    This metadata is used by ServiceCLIGenerator to auto-generate standard
+    CRUD commands (list, retrieve, create, delete, exists).
+
+    Attributes:
+        service_name: CLI command group name (e.g., "buckets", "assets")
+        service_attr: Attribute name on UiPath client (e.g., client.buckets)
+        resource_type: Human-readable resource name (e.g., "Bucket", "Asset")
+        resource_plural: Plural form of resource type (auto-generated if not provided)
+        create_params: Dictionary of parameters for create command
+        delete_cmd: Configuration for delete command behavior
+        exists_cmd: Configuration for exists command behavior
+        list_supports_filters: Whether list command supports additional filters
+        retrieve_identifier: Name of the identifier argument for retrieve
+
+    Example:
+        >>> metadata = ServiceMetadata(
+        ...     service_name="buckets",
+        ...     service_attr="buckets",
+        ...     resource_type="Bucket",
+        ...     create_params={
+        ...         "description": CreateParameter(
+        ...             type="str",
+        ...             required=False,
+        ...             help="Bucket description",
+        ...         )
+        ...     },
+        ... )
+        >>> metadata.resource_plural
+        'Buckets'
+    """
+
+    service_name: str
+    service_attr: str
+    resource_type: str
+    resource_plural: str | None = None
+    create_params: dict[str, CreateParameter] = Field(default_factory=dict)
+    delete_cmd: DeleteCommandConfig = Field(default_factory=DeleteCommandConfig)
+    exists_cmd: ExistsCommandConfig = Field(default_factory=ExistsCommandConfig)
+    list_supports_filters: bool = False
+    retrieve_identifier: str = "name"
+
+    class Config:
+        """Pydantic configuration."""
+
+        frozen = True
+
+    @model_validator(mode="after")
+    def set_defaults(self) -> "ServiceMetadata":
+        """Set default values that depend on other fields.
+
+        This validator runs after model creation to set derived defaults:
+        - resource_plural from resource_type
+        - delete_cmd defaults if not explicitly set
+
+        Note:
+            Since the model is frozen, we use object.__setattr__ to modify fields.
+        """
+        if self.resource_plural is None:
+            object.__setattr__(self, "resource_plural", f"{self.resource_type}s")
+
+        return self
+
+    def validate_types(self) -> None:
+        """Validate that all parameter types are in TYPE_REGISTRY.
+
+        Raises:
+            ValueError: If any parameter type is not registered
+
+        Example:
+            >>> metadata = ServiceMetadata(
+            ...     service_name="test",
+            ...     service_attr="test",
+            ...     resource_type="Test",
+            ...     create_params={
+            ...         "invalid": CreateParameter(type="InvalidType", required=False)
+            ...     },
+            ... )
+            >>> metadata.validate_types()
+            Traceback (most recent call last):
+            ...
+            ValueError: Invalid type 'InvalidType' for parameter 'invalid' in service 'test'...
+        """
+        from ._type_registry import is_valid_type
+
+        for param_name, param in self.create_params.items():
+            if not is_valid_type(param.type):
+                from ._type_registry import TYPE_REGISTRY
+
+                valid_types = ", ".join(sorted(TYPE_REGISTRY.keys()))
+                raise ValueError(
+                    f"Invalid type '{param.type}' for parameter '{param_name}' "
+                    f"in service '{self.service_name}'. Valid types: {valid_types}"
+                )
+
+
+__all__ = [
+    "CreateParameter",
+    "DeleteCommandConfig",
+    "ExistsCommandConfig",
+    "ServiceMetadata",
+]

uipath/_cli/_utils/_service_protocol.py

@@ -0,0 +1,223 @@
+"""Protocol definition for CRUD services.
+
+This module defines the CRUDServiceProtocol that services must implement
+to be compatible with the CLI command generator.
+
+The protocol uses Python's Protocol (PEP 544) for structural subtyping,
+allowing duck-typing without requiring explicit inheritance.
+
+Example:
+    >>> from typing import Protocol, runtime_checkable
+    >>> from ._service_protocol import CRUDServiceProtocol
+    >>>
+    >>> # A service that implements the protocol
+    >>> class BucketsService:
+    ...     def list(self, folder_path=None, folder_key=None):
+    ...         return iter([])
+    ...
+    ...     def retrieve(self, name, folder_path=None, folder_key=None):
+    ...         return {"name": name}
+    ...
+    ...     # ... other CRUD methods
+    >>>
+    >>> # No explicit inheritance needed - structural typing
+    >>> def use_service(service: CRUDServiceProtocol):
+    ...     return list(service.list())
+"""
+
+from typing import Any, Iterator, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CRUDServiceProtocol(Protocol):
+    """Protocol for services that support standard CRUD operations.
+
+    Services implementing this protocol can use the ServiceCLIGenerator
+    to automatically generate CLI commands.
+
+    All methods support folder-scoped operations via folder_path or folder_key
+    parameters. This matches the UiPath platform's hierarchical folder structure.
+
+    Required Methods:
+        list: List all resources (returns iterator)
+        retrieve: Get a single resource by identifier
+        create: Create a new resource
+        delete: Delete a resource by identifier
+
+    Optional Methods (NOT in protocol, checked separately):
+        exists: Check if a resource exists (will be used if present on service)
+
+    Note:
+        This is a Protocol, not a base class. Services don't need to inherit
+        from it; they just need to implement the required methods with
+        compatible signatures.
+
+        The exists() method is NOT part of the protocol to allow optional
+        implementation. Use hasattr(service, 'exists') to check for it.
+    """
+
+    def list(
+        self,
+        *,
+        folder_path: str | None = None,
+        folder_key: str | None = None,
+        **kwargs: Any,
+    ) -> Iterator[Any]:
+        """List all resources in the specified folder.
+
+        Args:
+            folder_path: Folder path (e.g., "Shared")
+            folder_key: Folder UUID key
+            **kwargs: Additional service-specific parameters
+
+        Returns:
+            Iterator of resource objects
+
+        Example:
+            >>> buckets_service.list(folder_path="Shared")
+            <iterator of Bucket objects>
+        """
+        ...
+
+    def retrieve(
+        self,
+        name: str,
+        *,
+        folder_path: str | None = None,
+        folder_key: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Retrieve a single resource by identifier.
+
+        Args:
+            name: Resource identifier (usually name, but could be key)
+            folder_path: Folder path (e.g., "Shared")
+            folder_key: Folder UUID key
+            **kwargs: Additional service-specific parameters
+
+        Returns:
+            Resource object
+
+        Raises:
+            LookupError: If resource not found
+
+        Example:
+            >>> buckets_service.retrieve("my-bucket", folder_path="Shared")
+            Bucket(name="my-bucket", ...)
+        """
+        ...
+
+    def create(
+        self,
+        name: str,
+        *,
+        folder_path: str | None = None,
+        folder_key: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Create a new resource.
+
+        Args:
+            name: Resource name
+            folder_path: Folder path (e.g., "Shared")
+            folder_key: Folder UUID key
+            **kwargs: Additional service-specific parameters (from metadata)
+
+        Returns:
+            Created resource object
+
+        Example:
+            >>> buckets_service.create(
+            ...     "my-bucket",
+            ...     folder_path="Shared",
+            ...     description="My bucket"
+            ... )
+            Bucket(name="my-bucket", description="My bucket", ...)
+        """
+        ...
+
+    def delete(
+        self,
+        name: str,
+        *,
+        folder_path: str | None = None,
+        folder_key: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Delete a resource by identifier.
+
+        Args:
+            name: Resource identifier to delete
+            folder_path: Folder path (e.g., "Shared")
+            folder_key: Folder UUID key
+            **kwargs: Additional service-specific parameters
+
+        Raises:
+            LookupError: If resource not found
+
+        Example:
+            >>> buckets_service.delete("my-bucket", folder_path="Shared")
+        """
+        ...
+
+
+def has_exists_method(service: Any) -> bool:
+    """Check if a service has the optional exists() method.
+
+    This is separate from the Protocol because exists() is optional.
+    Not all services need to implement it.
+
+    Args:
+        service: Service instance to check
+
+    Returns:
+        True if service has a callable exists() method
+
+    Example:
+        >>> class ServiceWithExists:
+        ...     def exists(self, name, **kwargs):
+        ...         return True
+        >>>
+        >>> service = ServiceWithExists()
+        >>> has_exists_method(service)
+        True
+    """
+    return hasattr(service, "exists") and callable(service.exists)
+
+
+def validate_service_protocol(service: Any, service_name: str) -> None:
+    """Validate that a service implements the CRUDServiceProtocol.
+
+    Args:
+        service: Service instance to validate
+        service_name: Name of the service for error messages
+
+    Raises:
+        TypeError: If service doesn't implement required methods
+
+    Example:
+        >>> class IncompleteService:
+        ...     def list(self):
+        ...         pass
+        ...     # Missing other methods
+        >>>
+        >>> validate_service_protocol(IncompleteService(), "incomplete")
+        Traceback (most recent call last):
+        ...
+        TypeError: Service 'incomplete' must implement: retrieve, create, delete
+    """
+    required_methods = ["list", "retrieve", "create", "delete"]
+    missing_methods = []
+    for method_name in required_methods:
+        if not hasattr(service, method_name) or not callable(
+            getattr(service, method_name)
+        ):
+            missing_methods.append(method_name)
+
+    if missing_methods:
+        raise TypeError(
+            f"Service '{service_name}' must implement: {', '.join(missing_methods)}"
+        )
+
+
+__all__ = ["CRUDServiceProtocol", "validate_service_protocol", "has_exists_method"]

uipath/_cli/_utils/_type_registry.py

@@ -0,0 +1,106 @@
+"""Type registry for safe parameter type resolution.
+
+This module provides a safe way to resolve type strings to Python types,
+replacing the use of eval() which is a security vulnerability.
+
+The TYPE_REGISTRY is used by the ServiceMetadata system to convert type
+strings (e.g., "str", "int") to actual Python types for Click parameter
+validation.
+
+Security Note:
+    This registry approach prevents arbitrary code execution that would be
+    possible with eval(). Only explicitly registered types can be used.
+
+Example:
+    >>> from ._type_registry import get_type
+    >>> str_type = get_type("str")
+    >>> str_type is str
+    True
+    >>> get_type("InvalidType")  # Raises ValueError
+    ValueError: Unknown type: 'InvalidType'. Valid types: bool, float, int, str
+"""
+
+from typing import Any, Type
+
+TYPE_REGISTRY: dict[str, Type[Any]] = {
+    "str": str,
+    "int": int,
+    "bool": bool,
+    "float": float,
+}
+
+
+def get_type(type_name: str) -> Type[Any]:
+    """Get Python type from string name safely.
+
+    Args:
+        type_name: String name of the type (e.g., "str", "int", "bool", "float")
+
+    Returns:
+        The Python type corresponding to the type name
+
+    Raises:
+        ValueError: If type_name is not in the registry
+
+    Example:
+        >>> get_type("str")
+        <class 'str'>
+        >>> get_type("int")
+        <class 'int'>
+        >>> get_type("InvalidType")
+        Traceback (most recent call last):
+        ...
+        ValueError: Unknown type: 'InvalidType'. Valid types: bool, float, int, str
+    """
+    param_type = TYPE_REGISTRY.get(type_name)
+    if param_type is None:
+        valid_types = ", ".join(sorted(TYPE_REGISTRY.keys()))
+        raise ValueError(f"Unknown type: '{type_name}'. Valid types: {valid_types}")
+    return param_type
+
+
+def register_type(type_name: str, type_class: Type[Any]) -> None:
+    """Register a new type in the registry.
+
+    This function allows extending the registry with custom types if needed.
+    Use with caution and only register types that are safe for CLI parameters.
+
+    Args:
+        type_name: String name for the type
+        type_class: The Python type class
+
+    Raises:
+        ValueError: If type_name already exists in registry
+
+    Example:
+        >>> from pathlib import Path
+        >>> register_type("path", Path)
+        >>> get_type("path")
+        <class 'pathlib.Path'>
+    """
+    if type_name in TYPE_REGISTRY:
+        raise ValueError(
+            f"Type '{type_name}' is already registered as {TYPE_REGISTRY[type_name]}"
+        )
+    TYPE_REGISTRY[type_name] = type_class
+
+
+def is_valid_type(type_name: str) -> bool:
+    """Check if a type name is registered.
+
+    Args:
+        type_name: String name to check
+
+    Returns:
+        True if type is registered, False otherwise
+
+    Example:
+        >>> is_valid_type("str")
+        True
+        >>> is_valid_type("InvalidType")
+        False
+    """
+    return type_name in TYPE_REGISTRY
+
+
+__all__ = ["TYPE_REGISTRY", "get_type", "register_type", "is_valid_type"]

uipath/_cli/_utils/_validators.py

@@ -0,0 +1,127 @@
+"""Common validators for CLI commands.
+
+This module provides reusable validation functions for common CLI inputs
+like folder paths, UUIDs, and resource names.
+"""
+
+import re
+from typing import Optional
+
+import click
+
+
+def validate_folder_path(ctx, param, value: Optional[str]) -> Optional[str]:
+    """Validate folder path format.
+
+    Folder paths should be in the format: "Folder1/Subfolder2"
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: Folder path to validate
+
+    Returns:
+        Validated folder path
+
+    Raises:
+        click.BadParameter: If folder path is invalid
+    """
+    if value is None:
+        return None
+
+    if value == "":
+        return value
+
+    if value.startswith("/") or value.endswith("/"):
+        raise click.BadParameter("Folder path should not start or end with '/'")
+
+    return value
+
+
+def validate_uuid(ctx, param, value: Optional[str]) -> Optional[str]:
+    """Validate UUID format.
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: UUID to validate
+
+    Returns:
+        Validated UUID
+
+    Raises:
+        click.BadParameter: If UUID is invalid
+    """
+    if value is None:
+        return None
+
+    # UUID regex pattern
+    uuid_pattern = re.compile(
+        r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+    )
+
+    if not uuid_pattern.match(value):
+        raise click.BadParameter(
+            f"'{value}' is not a valid UUID. "
+            "Expected format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+        )
+
+    return value
+
+
+def validate_resource_name(ctx, param, value: Optional[str]) -> Optional[str]:
+    """Validate resource name.
+
+    Resource names should:
+    - Not be empty
+    - Not contain special characters that might cause issues
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: Resource name to validate
+
+    Returns:
+        Validated resource name
+
+    Raises:
+        click.BadParameter: If resource name is invalid
+    """
+    if value is None:
+        return None
+
+    if not value.strip():
+        raise click.BadParameter("Resource name cannot be empty")
+
+    invalid_chars = ["<", ">", ":", '"', "|", "?", "*"]
+    for char in invalid_chars:
+        if char in value:
+            raise click.BadParameter(
+                f"Resource name contains invalid character: '{char}'"
+            )
+
+    return value
+
+
+def validate_mutually_exclusive(ctx, param, value, exclusive_with: str):
+    """Validate that two options are mutually exclusive.
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: Current parameter value (can be any type)
+        exclusive_with: Name of the mutually exclusive parameter
+
+    Returns:
+        Validated value
+
+    Raises:
+        click.UsageError: If both parameters are provided
+    """
+    if value is not None and ctx.params.get(exclusive_with) is not None:
+        raise click.UsageError(
+            f"--{param.name} and --{exclusive_with} are mutually exclusive. "
+            "Provide only one."
+        )
+
+    return value