# Code generated by protoc-gen-meshpy. DO NOT EDIT.
# source: meshtrade/iam/api_user/v1/service.proto

"""
APIUserService gRPC service wrapper with authentication, timeouts, and resource management.

This module provides a high-level gRPC service for the APIUserService service that combines
the service interface with resource management capabilities, providing authentication,
timeouts, and proper connection handling.
"""

from collections.abc import Iterator
from datetime import timedelta
from typing import Optional

from meshtrade.common import BaseGRPCClient
from .api_credentials import find_credentials

from .api_user_pb2 import APIUser
from meshtrade.common.service_options import ServiceOptions
from .service_pb2 import (
ActivateAPIUserRequest,
AssignRolesToAPIUserRequest,
CreateAPIUserRequest,
DeactivateAPIUserRequest,
GetAPIUserByKeyHashRequest,
GetAPIUserRequest,
ListAPIUsersRequest,
ListAPIUsersResponse,
RevokeRolesFromAPIUserRequest,
SearchAPIUsersRequest,
SearchAPIUsersResponse,
)
from .service_pb2_grpc import APIUserServiceStub


def _create_apiuserservice_stub(channel):
    """Factory function to create APIUserServiceStub from gRPC channel."""
    return APIUserServiceStub(channel)


class APIUserService(BaseGRPCClient):
    """APIUserService gRPC service with authentication, timeouts, and resource management.

    This service provides a complete implementation of the APIUserService with proper authentication, timeout handling, and automatic resource cleanup.

    Full Service documentation: https://meshtrade.github.io/api/docs/api-reference/iam/api_user/v1

    Basic service usage with default SDK Configuration:
    ```python
    service = APIUserService()

    with service:   # `with` ensures proper clean up of underlying connection after use
        response = service.get_api_user(request)
    ```
        
    With default configuration API credentials are searched for using the standard discovery hierarchy:
    
    1. MESH_API_CREDENTIALS environment variable
    
    2. Default credential file location:
    
    - Linux:   `$XDG_CONFIG_HOME/mesh/credentials.json` or fallback to `$HOME/.config/mesh/credentials.json`
    - macOS:   `$HOME/Library/Application Support/mesh/credentials.json`
    - Windows: `C:\\Users\\<user>\\AppData\\Roaming\\mesh\\credentials.json`
    
    For more information on authentication: https://meshtrade.github.io/api/docs/architecture/authentication

    The service may also be configured with custom options:
    ```python
    from .service_options_meshpy import ServiceOptions
    from datetime import timedelta

    options = ServiceOptions(
        url="api.staging.example.com",
        port=443,
        api_key="your-api-key",
        group="groups/your-group-id",
        timeout=timedelta(seconds=60)
    )

    service = APIUserService(options)

    with service: # `with` ensures proper clean up of underlying connection after use
        response = service.get_api_user(request)
    ```

    For more information on service configuration: https://meshtrade.github.io/api/docs/architecture/sdk-configuration
    """

    def __init__(self, options: Optional[ServiceOptions] = None):
        """Construct and initialize the APIUserService service.

        Full Service documentation: https://meshtrade.github.io/api/docs/api-reference/iam/api_user/v1

        Args:
            options: Optional ServiceOptions for configuring the service.
                    If None, service is constructed with default configuration.
                    With default configuration API credentials are searched for using the standard discovery hierarchy:
                    
                    1. MESH_API_CREDENTIALS environment variable
                    
                    2. Default credential file location:
                    
                    - Linux:   `$XDG_CONFIG_HOME/mesh/credentials.json` or fallback to `$HOME/.config/mesh/credentials.json`
                    - macOS:   `$HOME/Library/Application Support/mesh/credentials.json`
                    - Windows: `C:\\Users\\<user>\\AppData\\Roaming\\mesh\\credentials.json`      

                    For more information on authentication: https://meshtrade.github.io/api/docs/architecture/authentication

                    For more information on service configuration: https://meshtrade.github.io/api/docs/architecture/sdk-configuration            

        Example:
        ```python
        # construct with default configuration
        service = APIUserService()

        # construct with custom configuration
        options = ServiceOptions(
            url="api.example.com",
            api_key="your-key",
            group="groups/your-group"
        )
        service = APIUserService(options)
        ```
        """
        if options is None:
            options = ServiceOptions()

        # Initialize the base client with all common functionality
        super().__init__(
            service_name="APIUserService",
            stub_factory=_create_apiuserservice_stub,
            find_credentials_func=find_credentials,
            url=options.url,
            port=options.port,
            api_key=options.api_key,
            group=options.group,
            timeout=options.timeout,
            tls=options.tls,
        )

    def get_apiuser(self, request: GetAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """GetAPIUser method.

        Args:
            request: The GetAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The GetAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("GetAPIUser", request, timeout)

    def create_apiuser(self, request: CreateAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """CreateAPIUser method.

        Args:
            request: The CreateAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The CreateAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("CreateAPIUser", request, timeout)

    def assign_roles_to_apiuser(self, request: AssignRolesToAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """AssignRolesToAPIUser method.

        Args:
            request: The AssignRolesToAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The AssignRolesToAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("AssignRolesToAPIUser", request, timeout)

    def revoke_roles_from_apiuser(self, request: RevokeRolesFromAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """RevokeRolesFromAPIUser method.

        Args:
            request: The RevokeRolesFromAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The RevokeRolesFromAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("RevokeRolesFromAPIUser", request, timeout)

    def list_apiusers(self, request: ListAPIUsersRequest, timeout: Optional[timedelta] = None) -> ListAPIUsersResponse:
        """ListAPIUsers method.

        Args:
            request: The ListAPIUsers request message
            timeout: Optional timeout override for this call

        Returns:
            The ListAPIUsers response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("ListAPIUsers", request, timeout)

    def search_apiusers(self, request: SearchAPIUsersRequest, timeout: Optional[timedelta] = None) -> SearchAPIUsersResponse:
        """SearchAPIUsers method.

        Args:
            request: The SearchAPIUsers request message
            timeout: Optional timeout override for this call

        Returns:
            The SearchAPIUsers response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("SearchAPIUsers", request, timeout)

    def activate_apiuser(self, request: ActivateAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """ActivateAPIUser method.

        Args:
            request: The ActivateAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The ActivateAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("ActivateAPIUser", request, timeout)

    def deactivate_apiuser(self, request: DeactivateAPIUserRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """DeactivateAPIUser method.

        Args:
            request: The DeactivateAPIUser request message
            timeout: Optional timeout override for this call

        Returns:
            The DeactivateAPIUser response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("DeactivateAPIUser", request, timeout)

    def get_apiuser_by_key_hash(self, request: GetAPIUserByKeyHashRequest, timeout: Optional[timedelta] = None) -> APIUser:
        """GetAPIUserByKeyHash method.

        Args:
            request: The GetAPIUserByKeyHash request message
            timeout: Optional timeout override for this call

        Returns:
            The GetAPIUserByKeyHash response message

        Raises:
            grpc.RpcError: If the gRPC call fails
            ValueError: If authentication credentials are missing
        """
        return self._execute_method("GetAPIUserByKeyHash", request, timeout)


# Create aliases to match expected exports
APIUserServiceGRPCClient = APIUserService
APIUserServiceGRPCClientInterface = APIUserService
