meshtrade 1.21.0__tar.gz → 1.23.0__tar.gz

{meshtrade-1.21.0 → meshtrade-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshtrade
-Version: 1.21.0
+Version: 1.23.0
 Summary: Integration SDK for Mesh API Services
 Author-email: Bernard Bussy <bernard@meshtrade.co>
 License: LicenseRef-My-Custom-License

{meshtrade-1.21.0 → meshtrade-1.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshtrade"
-version = "1.21.0"
+version = "1.23.0"
 authors = [
     { name = "Bernard Bussy", email = "bernard@meshtrade.co" },
 ]

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/common/grpc_client.py

@@ -146,6 +146,99 @@ class BaseGRPCClient(GRPCClient):
             raise ValueError("Group not configured. Provide via constructor or set MESH_API_CREDENTIALS environment variable.")
         return self._group
 
+    @property
+    def url(self) -> str:
+        """Get the gRPC server URL.
+
+        Returns:
+            The gRPC server URL
+        """
+        return self._url
+
+    @property
+    def port(self) -> int:
+        """Get the gRPC server port.
+
+        Returns:
+            The gRPC server port
+        """
+        return self._port
+
+    @property
+    def api_key(self) -> str | None:
+        """Get the API key used for authentication.
+
+        Returns:
+            The API key, or None if not configured
+        """
+        return self._api_key
+
+    @property
+    def timeout(self) -> timedelta:
+        """Get the request timeout.
+
+        Returns:
+            The request timeout
+        """
+        return self._timeout
+
+    @property
+    def tls(self) -> bool:
+        """Get the TLS setting.
+
+        Returns:
+            True if TLS is enabled, False otherwise
+        """
+        return self._tls
+
+    def with_group(self, group: str):
+        """Return a new client instance configured with a different group context.
+
+        This enables convenient group context switching without reconstructing the entire client.
+        All other configuration (URL, port, timeout, API key, TLS) is preserved.
+
+        The group parameter must be in the format 'groups/{group_id}' where group_id is a valid
+        group identifier (typically a ULID). The new client instance shares no state with the
+        original client, allowing safe concurrent usage.
+
+        Args:
+            group: The group resource name in format 'groups/{group_id}'
+
+        Returns:
+            A new client instance of the same service type with updated group context.
+
+        Raises:
+            ValueError: If group is empty or not in correct format
+
+        Example:
+            >>> service = GroupService()
+            >>> alt_service = service.with_group("groups/01ARZ3NDEKTSV4RRFFQ69G5FAV")
+            >>> resp1 = service.some_method(request)      # Uses original group
+            >>> resp2 = alt_service.some_method(request)  # Uses alternative group
+        """
+        # Validation
+        if not group:
+            raise ValueError("Group parameter cannot be empty")
+        if not group.startswith("groups/"):
+            raise ValueError("Group must be in format 'groups/{group_id}'")
+
+        # Import ServiceOptions from common module
+        from meshtrade.common.service_options import ServiceOptions
+
+        # Create new options with all config preserved except group
+        options = ServiceOptions(
+            url=self._url,
+            port=self._port,
+            api_key=self._api_key,
+            group=group,
+            timeout=self._timeout,
+            tls=self._tls,
+        )
+
+        # Create new instance of actual runtime class (GroupService, AccountService, etc.)
+        # type(self) returns the actual class, and all services accept ServiceOptions
+        return type(self)(options)
+
     def validator(self) -> Validator:
         """Get the protovalidate validator for request validation.
 

meshtrade-1.23.0/python/src/meshtrade/common/service_options.py

@@ -0,0 +1,46 @@
+"""
+Shared configuration options for all gRPC services.
+
+This module provides a clean, extensible way to configure services with optional
+parameters while maintaining backward compatibility and readability.
+"""
+
+from datetime import timedelta
+
+
+class ServiceOptions:
+    """Configuration options for gRPC services.
+
+    This class provides a clean, extensible way to configure services with optional
+    parameters while maintaining backward compatibility and readability.
+    """
+
+    def __init__(
+        self,
+        tls: bool = True,
+        url: str | None = None,
+        port: int | None = None,
+        api_key: str | None = None,
+        group: str | None = None,
+        timeout: timedelta = timedelta(seconds=30),
+    ):
+        """Initialize service options.
+
+        Args:
+            tls: Whether to use TLS encryption for the gRPC connection.
+            url: The server hostname or IP address.
+            port: The server port number.
+            api_key: The API key for authentication.
+            group: The group resource name in format groups/{group_id}.
+            timeout: The default timeout for all gRPC method calls.
+        """
+        self.tls = tls
+        self.url = url
+        self.port = port
+        self.api_key = api_key
+        self.group = group
+        self.timeout = timeout
+
+
+# Create alias to match expected exports
+ClientOptions = ServiceOptions

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/compliance/client/v1/__init__.py

@@ -40,7 +40,6 @@ from .service_meshpy import (
     ClientServiceGRPCClient,
     ClientServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -63,7 +62,6 @@ from .service_options_meshpy import ClientOptions
 __all__ = [
     # Generated exports
     "Client",
-    "ClientOptions",
     "ClientService",
     "ClientServiceGRPCClient",
     "ClientServiceGRPCClientInterface",

meshtrade-1.23.0/python/src/meshtrade/compliance/client/v1/client_roles.py

@@ -0,0 +1,123 @@
+"""Client roles utility functions."""
+
+from meshtrade.compliance.client.v1.client_pb2 import Client
+from meshtrade.iam.role.v1 import role_pb2
+from meshtrade.iam.role.v1.role_pb2 import Role
+
+# Cache for client default roles extracted from protobuf
+_client_default_roles: list[Role] | None = None
+_client_default_roles_error: str | None = None
+
+
+def _initialize_client_default_roles() -> None:
+    """Initialize client default roles from protobuf extensions.
+
+    This function is called once to extract roles from the Client message's
+    message_roles extension. Results are cached for subsequent calls.
+    """
+    global _client_default_roles, _client_default_roles_error
+
+    if _client_default_roles is not None or _client_default_roles_error is not None:
+        return
+
+    try:
+        # Get the Client message descriptor
+        client_descriptor = Client.DESCRIPTOR
+
+        # Get message options
+        options = client_descriptor.GetOptions()
+
+        # Get the message_roles extension descriptor
+        message_roles_ext = role_pb2.message_roles
+
+        # Check if extension is present
+        # Type ignore: protobuf extension API has overly strict type stubs
+        if not options.HasExtension(message_roles_ext):  # type: ignore[arg-type]
+            _client_default_roles_error = f"proto message {client_descriptor.full_name} does not define extension {message_roles_ext.full_name}"
+            return
+
+        # Get the RoleList from the extension
+        # Type ignore: protobuf extension API has overly strict type stubs
+        role_list = options.Extensions[message_roles_ext]  # type: ignore[arg-type]
+
+        # Extract roles and make a copy
+        _client_default_roles = list(role_list.roles)
+
+    except Exception as e:
+        _client_default_roles_error = f"failed to extract roles from Client message: {e}"
+
+
+def get_client_default_roles() -> list[Role]:
+    """Get default roles for a client.
+
+    Returns the roles declared on the meshtrade.compliance.client.v1.Client
+    message via the meshtrade.iam.role.v1.message_roles option. The returned
+    list is a copy so callers can safely mutate it without affecting subsequent reads.
+
+    Returns:
+        List of default Role values for clients
+        Empty list if retrieval fails
+    """
+    try:
+        return must_get_client_default_roles()
+    except ValueError:
+        return []
+
+
+def must_get_client_default_roles() -> list[Role]:
+    """Get default roles for a client, raising error on failure.
+
+    Returns the roles declared on the meshtrade.compliance.client.v1.Client
+    message via the meshtrade.iam.role.v1.message_roles option. The returned
+    list is a copy so callers can safely mutate it without affecting subsequent reads.
+
+    Returns:
+        List of default Role values for clients
+
+    Raises:
+        ValueError: If default roles cannot be determined
+    """
+    _initialize_client_default_roles()
+
+    if _client_default_roles_error is not None:
+        raise ValueError(_client_default_roles_error)
+
+    if _client_default_roles is None:
+        raise ValueError("client default roles not initialized")
+
+    # Return a copy to prevent mutation
+    return list(_client_default_roles)
+
+
+def get_client_default_role_index() -> dict[Role, bool]:
+    """Get default roles as a lookup index.
+
+    Builds a set-like map keyed by roles declared on the
+    meshtrade.compliance.client.v1.Client message. The map's values are always
+    True; the structure is intended for efficient membership checks.
+
+    Returns:
+        Dictionary mapping Role to True for default roles
+        Empty dict if retrieval fails
+    """
+    try:
+        return must_get_client_default_role_index()
+    except ValueError:
+        return {}
+
+
+def must_get_client_default_role_index() -> dict[Role, bool]:
+    """Get default roles as lookup index, raising error on failure.
+
+    Builds a set-like map keyed by roles declared on the
+    meshtrade.compliance.client.v1.Client message. The map's values are always
+    True; the structure is intended for efficient membership checks.
+
+    Returns:
+        Dictionary mapping Role to True for default roles
+
+    Raises:
+        ValueError: If default roles cannot be determined
+    """
+    roles = must_get_client_default_roles()
+    return dict.fromkeys(roles, True)

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/compliance/client/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .client_pb2 import Client
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 CreateClientRequest,
 GetClientRequest,

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/api_user/v1/__init__.py

@@ -35,7 +35,6 @@ from .service_meshpy import (
     ApiUserServiceGRPCClient,
     ApiUserServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -81,7 +80,6 @@ __all__ = [
     "ApiUserServiceGRPCClient",
     "ApiUserServiceGRPCClientInterface",
     "AssignRoleToAPIUserRequest",
-    "ClientOptions",
     "CreateApiUserRequest",
     "DeactivateApiUserRequest",
     "GetApiUserByKeyHashRequest",

meshtrade-1.23.0/python/src/meshtrade/iam/api_user/v1/api_user_state_machine.py

@@ -0,0 +1,104 @@
+"""API User state machine validation and transition logic.
+
+This module provides validation and state machine functions for API User states
+and actions, implementing the API User lifecycle management logic.
+"""
+
+from meshtrade.iam.api_user.v1.api_user_pb2 import APIUserAction, APIUserState
+
+
+def api_user_state_is_valid(state: APIUserState | None) -> bool:
+    """Check if the APIUserState is a valid enum value.
+
+    Args:
+        state: The APIUserState to validate (can be None)
+
+    Returns:
+        True if the state is a valid enum value, False otherwise
+
+    None Safety:
+        Returns False if state is None
+
+    Example:
+        >>> api_user_state_is_valid(APIUserState.API_USER_STATE_ACTIVE)
+        True
+        >>> api_user_state_is_valid(999)  # Invalid enum value
+        False
+        >>> api_user_state_is_valid(None)
+        False
+    """
+    if state is None:
+        return False
+    return state in APIUserState.values()
+
+
+def api_user_state_is_valid_and_defined(state: APIUserState) -> bool:
+    """Check if the APIUserState is valid and not unspecified.
+
+    Args:
+        state: The APIUserState to validate
+
+    Returns:
+        True if the state is valid and not UNSPECIFIED, False otherwise
+
+    Example:
+        >>> api_user_state_is_valid_and_defined(APIUserState.API_USER_STATE_ACTIVE)
+        True
+        >>> api_user_state_is_valid_and_defined(APIUserState.API_USER_STATE_UNSPECIFIED)
+        False
+    """
+    return api_user_state_is_valid(state) and state != APIUserState.API_USER_STATE_UNSPECIFIED
+
+
+def api_user_state_can_perform_action_at_state(state: APIUserState | None, action: APIUserAction | None) -> bool:
+    """Check if the given action can be performed at the current state.
+
+    This implements the state machine logic for API User lifecycle management.
+
+    State Transitions:
+    - INACTIVE -> ACTIVATE -> ACTIVE
+    - ACTIVE -> DEACTIVATE -> INACTIVE
+    - UPDATE action allowed in any state
+
+    Args:
+        state: The current APIUserState (can be None)
+        action: The APIUserAction to perform (can be None)
+
+    Returns:
+        True if the action can be performed at the given state, False otherwise
+
+    None Safety:
+        Returns False if either state or action is None
+
+    Example:
+        >>> can_perform_action_at_state(
+        ...     APIUserState.API_USER_STATE_INACTIVE,
+        ...     APIUserAction.API_USER_ACTION_ACTIVATE
+        ... )
+        True
+        >>> can_perform_action_at_state(
+        ...     APIUserState.API_USER_STATE_INACTIVE,
+        ...     APIUserAction.API_USER_ACTION_DEACTIVATE
+        ... )
+        False
+    """
+    if state is None or action is None:
+        return False
+
+    # Define actions that are allowed regardless of state (update operations)
+    general_update_actions = {
+        APIUserAction.API_USER_ACTION_UPDATE: True,
+    }
+
+    if state == APIUserState.API_USER_STATE_INACTIVE:
+        if action == APIUserAction.API_USER_ACTION_ACTIVATE:
+            return True
+        return general_update_actions.get(action, False)
+
+    elif state == APIUserState.API_USER_STATE_ACTIVE:
+        if action == APIUserAction.API_USER_ACTION_DEACTIVATE:
+            return True
+        return general_update_actions.get(action, False)
+
+    else:
+        return False

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/api_user/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from .api_credentials import find_credentials
 
 from .api_user_pb2 import APIUser
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 ActivateApiUserRequest,
 AssignRoleToAPIUserRequest,

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/group/v1/__init__.py

@@ -30,7 +30,6 @@ from .service_meshpy import (
     GroupServiceGRPCClient,
     GroupServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -52,7 +51,6 @@ from .service_options_meshpy import ClientOptions
 # Combined auto-generated and manual exports
 __all__ = [
     # Generated exports
-    "ClientOptions",
     "CreateGroupRequest",
     "GetGroupRequest",
     "Group",

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/group/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .group_pb2 import Group
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 CreateGroupRequest,
 GetGroupRequest,

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/role/v1/__init__.py

@@ -29,7 +29,7 @@ from .role_pb2 import Role, RoleList
 #
 # ===================================================================
 
-from .role import full_resource_name_from_group_name
+from .role import role_full_resource_name_from_group
 
 # ===================================================================
 # MODULE EXPORTS
@@ -40,5 +40,5 @@ __all__ = [
     "Role",
     "RoleList",
     # Manual exports
-    "full_resource_name_from_group_name",
+    "role_full_resource_name_from_group",
 ]

meshtrade-1.23.0/python/src/meshtrade/iam/role/v1/role.py

@@ -0,0 +1,174 @@
+"""Role utility functions for Mesh API.
+
+This module provides helper functions for working with Role enums and their resource names.
+All functions use the 3-part integer format: groups/{groupID}/{roleNumber}
+for cross-language compatibility.
+"""
+
+from meshtrade.iam.role.v1.role_pb2 import Role
+
+
+def role_is_valid(role: Role) -> bool:
+    """Check if role value is valid (within enum range).
+
+    Args:
+        role: Role enum value (integer)
+
+    Returns:
+        True if role is a valid enum value
+
+    Example:
+        >>> role_is_valid(Role.ROLE_IAM_ADMIN)
+        True
+        >>> role_is_valid(99999999)
+        False
+    """
+    return role in Role.values()
+
+
+def role_is_valid_and_specified(role: Role) -> bool:
+    """Check if role is valid and not UNSPECIFIED.
+
+    Args:
+        role: Role enum value (integer)
+
+    Returns:
+        True if role is valid and not ROLE_UNSPECIFIED
+
+    Example:
+        >>> role_is_valid_and_specified(Role.ROLE_IAM_ADMIN)
+        True
+        >>> role_is_valid_and_specified(Role.ROLE_UNSPECIFIED)
+        False
+    """
+    return role_is_valid(role) and role != Role.ROLE_UNSPECIFIED
+
+
+def role_full_resource_name_from_group_id(role: Role, group_id: str) -> str:
+    """Generate full resource name from role and group ID.
+
+    Format: groups/{group_id}/{role_int}
+
+    Args:
+        role: Role enum value (integer)
+        group_id: Group ID (UUID)
+
+    Returns:
+        Full resource name string using integer format
+
+    Example:
+        >>> role_full_resource_name_from_group_id(Role.ROLE_IAM_ADMIN, "01DD32GZ7R0000000000000001")
+        'groups/01DD32GZ7R0000000000000001/3000000'
+    """
+    return f"groups/{group_id}/{int(role)}"
+
+
+def role_full_resource_name_from_group(role: Role, group: str) -> str:
+    """Generate full resource name from role and group resource name.
+
+    Args:
+        role: Role enum value (integer)
+        group: Group resource name (e.g., "groups/{id}")
+
+    Returns:
+        Full resource name string using integer format
+
+    Raises:
+        ValueError: If group format is invalid
+
+    Example:
+        >>> role_full_resource_name_from_group(Role.ROLE_IAM_ADMIN, "groups/01DD32GZ7R0000000000000001")
+        'groups/01DD32GZ7R0000000000000001/3000000'
+    """
+    if not group.startswith("groups/"):
+        raise ValueError(f"invalid group format, expected groups/{{groupID}}, got: {group}")
+
+    group_id = group[len("groups/") :]
+    if not group_id:
+        raise ValueError(f"group ID cannot be empty in group resource name: {group}")
+
+    return role_full_resource_name_from_group_id(role, group_id)
+
+
+def role_from_full_resource_name(full_resource_name: str) -> Role:
+    """Extract Role from full resource name.
+
+    Args:
+        full_resource_name: Full resource name (e.g., "groups/{id}/{role_int}")
+
+    Returns:
+        Role enum value (integer), or ROLE_UNSPECIFIED if parsing fails
+
+    Example:
+        >>> role_from_full_resource_name("groups/01DD32GZ7R0000000000000001/3000000")
+        3000000
+        >>> role_from_full_resource_name("invalid/format")
+        0
+    """
+    from typing import cast
+
+    try:
+        _, role_int = parse_role_parts(full_resource_name)
+        # Python protobuf enums are integers, safe to cast
+        return cast(Role, role_int)
+    except ValueError:
+        return Role.ROLE_UNSPECIFIED
+
+
+def parse_role_parts(role_full_resource_name: str) -> tuple[str, int]:
+    """Parse full resource name into group ID and Role.
+
+    Expected format: groups/{group_id}/{role_int}
+
+    Args:
+        role_full_resource_name: Full resource name
+
+    Returns:
+        Tuple of (group_id, role_int)
+
+    Raises:
+        ValueError: If format is invalid or role number cannot be parsed
+
+    Example:
+        >>> parse_role_parts("groups/01DD32GZ7R0000000000000001/3000000")
+        ('01DD32GZ7R0000000000000001', 3000000)
+    """
+    parts = role_full_resource_name.split("/")
+    if len(parts) != 3 or parts[0] != "groups":
+        raise ValueError(f"invalid role format, expected groups/{{groupID}}/{{role}}, got {role_full_resource_name}")
+
+    group_id = parts[1]
+    if not group_id:
+        raise ValueError("group ID cannot be empty")
+
+    try:
+        role_int = int(parts[2])
+    except ValueError as e:
+        raise ValueError(f"error parsing role enum value '{parts[2]}'") from e
+
+    if role_int < 0:
+        raise ValueError(f"invalid role number in full resource name: {role_full_resource_name}")
+
+    return group_id, role_int
+
+
+def must_parse_role_parts(role_full_resource_name: str) -> tuple[str, int]:
+    """Parse role parts, raising error on failure.
+
+    This is an alias for parse_role_parts.
+    Both functions raise ValueError on parsing errors.
+
+    Args:
+        role_full_resource_name: Full resource name
+
+    Returns:
+        Tuple of (group_id, role_int)
+
+    Raises:
+        ValueError: If format is invalid
+
+    Example:
+        >>> must_parse_role_parts("groups/01DD32GZ7R0000000000000001/3000000")
+        ('01DD32GZ7R0000000000000001', 3000000)
+    """
+    return parse_role_parts(role_full_resource_name)

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/user/v1/__init__.py

@@ -31,7 +31,6 @@ from .service_meshpy import (
     UserServiceGRPCClient,
     UserServiceGRPCClientInterface,
 )
-from .service_options_meshpy import ClientOptions
 
 # ===================================================================
 # END OF AUTO-GENERATED SECTION
@@ -54,7 +53,6 @@ from .service_options_meshpy import ClientOptions
 __all__ = [
     # Generated exports
     "AssignRoleToUserRequest",
-    "ClientOptions",
     "CreateUserRequest",
     "GetUserRequest",
     "ListUsersRequest",

{meshtrade-1.21.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/user/v1/service_meshpy.py

@@ -16,7 +16,7 @@ from meshtrade.common import BaseGRPCClient
 from meshtrade.iam.api_user.v1.api_credentials import find_credentials
 
 from .user_pb2 import User
-from .service_options_meshpy import ServiceOptions
+from meshtrade.common.service_options import ServiceOptions
 from .service_pb2 import (
 AssignRoleToUserRequest,
 CreateUserRequest,