dataspace-sdk 0.4.2__py3-none-any.whl

dataspace_sdk/__init__.py

@@ -0,0 +1,18 @@
+"""DataSpace Python SDK for programmatic access to DataSpace resources."""
+
+from dataspace_sdk.__version__ import __version__
+from dataspace_sdk.client import DataSpaceClient
+from dataspace_sdk.exceptions import (
+    DataSpaceAPIError,
+    DataSpaceAuthError,
+    DataSpaceNotFoundError,
+    DataSpaceValidationError,
+)
+
+__all__ = [
+    "DataSpaceClient",
+    "DataSpaceAPIError",
+    "DataSpaceAuthError",
+    "DataSpaceNotFoundError",
+    "DataSpaceValidationError",
+]

dataspace_sdk/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for DataSpace SDK."""
+
+__version__ = "0.4.2"

dataspace_sdk/auth.py

@@ -0,0 +1,470 @@
+"""Authentication module for DataSpace SDK."""
+
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+from dataspace_sdk.exceptions import DataSpaceAuthError
+
+
+class AuthClient:
+    """Handles authentication with DataSpace API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        keycloak_url: Optional[str] = None,
+        keycloak_realm: Optional[str] = None,
+        keycloak_client_id: Optional[str] = None,
+        keycloak_client_secret: Optional[str] = None,
+    ):
+        """
+        Initialize the authentication client.
+
+        Args:
+            base_url: Base URL of the DataSpace API
+            keycloak_url: Keycloak server URL (e.g., "https://opub-kc.civicdatalab.in")
+            keycloak_realm: Keycloak realm name (e.g., "DataSpace")
+            keycloak_client_id: Keycloak client ID (e.g., "dataspace")
+            keycloak_client_secret: Optional client secret for confidential clients
+        """
+        self.base_url = base_url.rstrip("/")
+        self.keycloak_url = keycloak_url.rstrip("/") if keycloak_url else None
+        self.keycloak_realm = keycloak_realm
+        self.keycloak_client_id = keycloak_client_id
+        self.keycloak_client_secret = keycloak_client_secret
+
+        # Session state
+        self.access_token: Optional[str] = None
+        self.refresh_token: Optional[str] = None
+        self.keycloak_access_token: Optional[str] = None
+        self.keycloak_refresh_token: Optional[str] = None
+        self.token_expires_at: Optional[float] = None
+        self.user_info: Optional[Dict] = None
+
+        # Stored credentials for auto-relogin
+        self._username: Optional[str] = None
+        self._password: Optional[str] = None
+
+    def login(self, username: str, password: str) -> Dict[str, Any]:
+        """
+        Login using username and password via Keycloak.
+
+        Args:
+            username: User's username or email
+            password: User's password
+
+        Returns:
+            Dictionary containing user info and tokens
+
+        Raises:
+            DataSpaceAuthError: If authentication fails
+        """
+        if not all([self.keycloak_url, self.keycloak_realm, self.keycloak_client_id]):
+            raise DataSpaceAuthError(
+                "Keycloak configuration missing. Please provide keycloak_url, "
+                "keycloak_realm, and keycloak_client_id when initializing the client."
+            )
+
+        # Store credentials for auto-relogin
+        self._username = username
+        self._password = password
+
+        # Get Keycloak token
+        keycloak_token = self._get_keycloak_token(username, password)
+
+        # Login to DataSpace backend
+        return self._login_with_keycloak_token(keycloak_token)
+
+    def login_as_service_account(self) -> Dict[str, Any]:
+        """
+        Login using client credentials (service account).
+
+        This method authenticates the client itself (not a user) using
+        the client_id and client_secret. Requires the Keycloak client
+        to have "Service Accounts Enabled".
+
+        Returns:
+            Dictionary containing user info and tokens
+
+        Raises:
+            DataSpaceAuthError: If authentication fails
+        """
+        if not all(
+            [
+                self.keycloak_url,
+                self.keycloak_realm,
+                self.keycloak_client_id,
+                self.keycloak_client_secret,
+            ]
+        ):
+            raise DataSpaceAuthError(
+                "Service account authentication requires keycloak_url, "
+                "keycloak_realm, keycloak_client_id, and keycloak_client_secret."
+            )
+
+        # Get Keycloak token using client credentials
+        keycloak_token = self._get_service_account_token()
+
+        # Login to DataSpace backend
+        return self._login_with_keycloak_token(keycloak_token)
+
+    def _get_keycloak_token(self, username: str, password: str) -> str:
+        """
+        Get Keycloak access token using username and password.
+
+        Args:
+            username: User's username or email
+            password: User's password
+
+        Returns:
+            Keycloak access token
+
+        Raises:
+            DataSpaceAuthError: If authentication fails
+        """
+        token_url = (
+            f"{self.keycloak_url}/auth/realms/{self.keycloak_realm}/"
+            f"protocol/openid-connect/token"
+        )
+
+        data = {
+            "grant_type": "password",
+            "client_id": self.keycloak_client_id,
+            "username": username,
+            "password": password,
+        }
+
+        if self.keycloak_client_secret:
+            data["client_secret"] = self.keycloak_client_secret
+
+        try:
+            response = requests.post(
+                token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code == 200:
+                token_data = response.json()
+                self.keycloak_access_token = token_data.get("access_token")
+                self.keycloak_refresh_token = token_data.get("refresh_token")
+
+                # Calculate token expiration time
+                expires_in = token_data.get("expires_in", 300)
+                self.token_expires_at = time.time() + expires_in
+
+                if not self.keycloak_access_token:
+                    raise DataSpaceAuthError("No access token in Keycloak response")
+
+                return self.keycloak_access_token
+            else:
+                error_data = response.json()
+                error_msg = error_data.get(
+                    "error_description",
+                    error_data.get("error", "Keycloak authentication failed"),
+                )
+                raise DataSpaceAuthError(
+                    f"Keycloak login failed: {error_msg}",
+                    status_code=response.status_code,
+                    response=error_data,
+                )
+        except requests.RequestException as e:
+            raise DataSpaceAuthError(f"Network error during Keycloak authentication: {str(e)}")
+
+    def _get_service_account_token(self) -> str:
+        """
+        Get Keycloak access token using client credentials (service account).
+
+        Returns:
+            Keycloak access token
+
+        Raises:
+            DataSpaceAuthError: If authentication fails
+        """
+        token_url = (
+            f"{self.keycloak_url}/auth/realms/{self.keycloak_realm}/"
+            f"protocol/openid-connect/token"
+        )
+
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.keycloak_client_id,
+            "client_secret": self.keycloak_client_secret,
+        }
+
+        try:
+            response = requests.post(
+                token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code == 200:
+                token_data = response.json()
+                self.keycloak_access_token = token_data.get("access_token")
+                self.keycloak_refresh_token = token_data.get("refresh_token")
+
+                # Calculate token expiration time
+                expires_in = token_data.get("expires_in", 300)
+                self.token_expires_at = time.time() + expires_in
+
+                if not self.keycloak_access_token:
+                    raise DataSpaceAuthError("No access token in Keycloak response")
+
+                return self.keycloak_access_token
+            else:
+                error_data = response.json()
+                error_msg = error_data.get(
+                    "error_description",
+                    error_data.get("error", "Service account authentication failed"),
+                )
+                raise DataSpaceAuthError(
+                    f"Service account login failed: {error_msg}. "
+                    f"Ensure 'Service Accounts Enabled' is ON in Keycloak client settings.",
+                    status_code=response.status_code,
+                    response=error_data,
+                )
+        except requests.RequestException as e:
+            raise DataSpaceAuthError(
+                f"Network error during service account authentication: {str(e)}"
+            )
+
+    def _refresh_keycloak_token(self) -> str:
+        """
+        Refresh Keycloak access token using refresh token.
+
+        Returns:
+            New Keycloak access token
+
+        Raises:
+            DataSpaceAuthError: If token refresh fails
+        """
+        if not self.keycloak_refresh_token:
+            # If no refresh token, try to relogin with stored credentials
+            if self._username and self._password:
+                return self._get_keycloak_token(self._username, self._password)
+            raise DataSpaceAuthError("No refresh token or credentials available")
+
+        token_url = (
+            f"{self.keycloak_url}/auth/realms/{self.keycloak_realm}/"
+            f"protocol/openid-connect/token"
+        )
+
+        data = {
+            "grant_type": "refresh_token",
+            "client_id": self.keycloak_client_id,
+            "refresh_token": self.keycloak_refresh_token,
+        }
+
+        if self.keycloak_client_secret:
+            data["client_secret"] = self.keycloak_client_secret
+
+        try:
+            response = requests.post(
+                token_url,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code == 200:
+                token_data = response.json()
+                self.keycloak_access_token = token_data.get("access_token")
+                self.keycloak_refresh_token = token_data.get("refresh_token")
+
+                expires_in = token_data.get("expires_in", 300)
+                self.token_expires_at = time.time() + expires_in
+
+                if not self.keycloak_access_token:
+                    raise DataSpaceAuthError("No access token in refresh response")
+
+                return self.keycloak_access_token
+            else:
+                # Refresh failed, try to relogin with stored credentials
+                if self._username and self._password:
+                    return self._get_keycloak_token(self._username, self._password)
+                raise DataSpaceAuthError("Keycloak token refresh failed")
+        except requests.RequestException as e:
+            # Network error, try to relogin with stored credentials
+            if self._username and self._password:
+                return self._get_keycloak_token(self._username, self._password)
+            raise DataSpaceAuthError(f"Network error during token refresh: {str(e)}")
+
+    def _ensure_valid_keycloak_token(self) -> str:
+        """
+        Ensure we have a valid Keycloak token, refreshing if necessary.
+
+        Returns:
+            Valid Keycloak access token
+
+        Raises:
+            DataSpaceAuthError: If unable to get valid token
+        """
+        # Check if token is expired or about to expire (within 30 seconds)
+        if (
+            not self.keycloak_access_token
+            or not self.token_expires_at
+            or time.time() >= (self.token_expires_at - 30)
+        ):
+            # Token expired or about to expire, refresh it
+            if self.keycloak_refresh_token or (self._username and self._password):
+                return self._refresh_keycloak_token()
+            raise DataSpaceAuthError("No valid token or credentials available")
+
+        return self.keycloak_access_token
+
+    def _login_with_keycloak_token(self, keycloak_token: str) -> Dict[str, Any]:
+        """
+        Login using a Keycloak token.
+
+        Args:
+            keycloak_token: Valid Keycloak access token
+
+        Returns:
+            Dictionary containing user info and tokens
+
+        Raises:
+            DataSpaceAuthError: If authentication fails
+        """
+        url = f"{self.base_url}/api/auth/keycloak/login/"
+
+        try:
+            response = requests.post(
+                url,
+                json={"token": keycloak_token},
+                headers={"Content-Type": "application/json"},
+            )
+
+            if response.status_code == 200:
+                data: Dict[str, Any] = response.json()
+                self.access_token = data.get("access")
+                self.refresh_token = data.get("refresh")
+                self.user_info = data.get("user")
+                return data
+            else:
+                error_msg = response.json().get("error", "Authentication failed")
+                raise DataSpaceAuthError(
+                    error_msg,
+                    status_code=response.status_code,
+                    response=response.json(),
+                )
+        except requests.RequestException as e:
+            raise DataSpaceAuthError(f"Network error during authentication: {str(e)}")
+
+    def refresh_access_token(self) -> str:
+        """
+        Refresh the access token using the refresh token.
+
+        Returns:
+            New access token
+
+        Raises:
+            DataSpaceAuthError: If token refresh fails
+        """
+        if not self.refresh_token:
+            raise DataSpaceAuthError("No refresh token available")
+
+        url = f"{self.base_url}/api/auth/token/refresh/"
+
+        try:
+            response = requests.post(
+                url,
+                json={"refresh": self.refresh_token},
+                headers={"Content-Type": "application/json"},
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                self.access_token = data.get("access")
+                if self.access_token is None:
+                    raise DataSpaceAuthError("Token refresh returned no access token")
+                return self.access_token
+            else:
+                raise DataSpaceAuthError(
+                    "Token refresh failed",
+                    status_code=response.status_code,
+                    response=response.json(),
+                )
+        except requests.RequestException as e:
+            raise DataSpaceAuthError(f"Network error during token refresh: {str(e)}")
+
+    def get_user_info(self) -> Dict[str, Any]:
+        """
+        Get current user information.
+
+        Returns:
+            Dictionary containing user information
+
+        Raises:
+            DataSpaceAuthError: If request fails
+        """
+        if not self.access_token:
+            raise DataSpaceAuthError("Not authenticated. Please login first.")
+
+        url = f"{self.base_url}/api/auth/user/info/"
+
+        try:
+            response = requests.get(
+                url,
+                headers=self._get_auth_headers(),
+            )
+
+            if response.status_code == 200:
+                user_info: Dict[str, Any] = response.json()
+                self.user_info = user_info
+                return self.user_info
+            else:
+                raise DataSpaceAuthError(
+                    "Failed to get user info",
+                    status_code=response.status_code,
+                    response=response.json(),
+                )
+        except requests.RequestException as e:
+            raise DataSpaceAuthError(f"Network error getting user info: {str(e)}")
+
+    def _get_auth_headers(self) -> Dict[str, str]:
+        """Get headers with authentication token."""
+        if not self.access_token:
+            return {}
+        return {"Authorization": f"Bearer {self.access_token}"}
+
+    def is_authenticated(self) -> bool:
+        """Check if the client is authenticated."""
+        return self.access_token is not None
+
+    def ensure_authenticated(self) -> None:
+        """
+        Ensure the client is authenticated, attempting auto-relogin if needed.
+
+        Raises:
+            DataSpaceAuthError: If unable to authenticate
+        """
+        if not self.is_authenticated():
+            # Try to relogin with stored credentials
+            if self._username and self._password:
+                self.login(self._username, self._password)
+            else:
+                raise DataSpaceAuthError("Not authenticated. Please call login() first.")
+
+    def get_valid_token(self) -> str:
+        """
+        Get a valid access token, refreshing if necessary.
+
+        Returns:
+            Valid access token
+
+        Raises:
+            DataSpaceAuthError: If unable to get valid token
+        """
+        # First ensure we have a valid Keycloak token
+        if self.keycloak_url and self.keycloak_realm:
+            keycloak_token = self._ensure_valid_keycloak_token()
+            # Re-login to backend with fresh Keycloak token if needed
+            if not self.access_token:
+                self._login_with_keycloak_token(keycloak_token)
+
+        if not self.access_token:
+            raise DataSpaceAuthError("No access token available")
+
+        return self.access_token

dataspace_sdk/base.py

@@ -0,0 +1,160 @@
+"""Base client for making API requests."""
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from dataspace_sdk.exceptions import (
+    DataSpaceAPIError,
+    DataSpaceAuthError,
+    DataSpaceNotFoundError,
+    DataSpaceValidationError,
+)
+
+
+class BaseAPIClient:
+    """Base client for making API requests to DataSpace."""
+
+    def __init__(self, base_url: str, auth_client: Any = None):
+        """
+        Initialize the base API client.
+
+        Args:
+            base_url: Base URL of the DataSpace API
+            auth_client: Authentication client instance
+        """
+        self.base_url = base_url.rstrip("/")
+        self.auth_client = auth_client
+
+    def _get_headers(self, additional_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """
+        Get request headers including authentication.
+
+        Args:
+            additional_headers: Additional headers to include
+
+        Returns:
+            Dictionary of headers
+        """
+        headers = {"Content-Type": "application/json"}
+
+        if self.auth_client and self.auth_client.is_authenticated():
+            headers["Authorization"] = f"Bearer {self.auth_client.access_token}"
+
+        if additional_headers:
+            headers.update(additional_headers)
+
+        return headers
+
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make an HTTP request to the API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint
+            params: Query parameters
+            data: Form data
+            json_data: JSON data
+            headers: Additional headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            DataSpaceAPIError: For API errors
+            DataSpaceAuthError: For authentication errors
+            DataSpaceNotFoundError: For 404 errors
+            DataSpaceValidationError: For validation errors
+        """
+        url = f"{self.base_url}{endpoint}"
+        request_headers = self._get_headers(headers)
+
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                params=params,
+                data=data,
+                json=json_data,
+                headers=request_headers,
+            )
+
+            # Handle different status codes
+            if response.status_code == 200 or response.status_code == 201:
+                result: Dict[str, Any] = response.json() if response.content else {}
+                return result
+            elif response.status_code == 204:
+                return {}
+            elif response.status_code == 401:
+                raise DataSpaceAuthError(
+                    "Authentication required or token expired",
+                    status_code=response.status_code,
+                    response=response.json() if response.content else {},
+                )
+            elif response.status_code == 404:
+                raise DataSpaceNotFoundError(
+                    "Resource not found",
+                    status_code=response.status_code,
+                    response=response.json() if response.content else {},
+                )
+            elif response.status_code == 400:
+                raise DataSpaceValidationError(
+                    "Validation error",
+                    status_code=response.status_code,
+                    response=response.json() if response.content else {},
+                )
+            else:
+                raise DataSpaceAPIError(
+                    f"API request failed with status {response.status_code}",
+                    status_code=response.status_code,
+                    response=response.json() if response.content else {},
+                )
+
+        except requests.RequestException as e:
+            raise DataSpaceAPIError(f"Network error: {str(e)}")
+
+    def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make a GET request."""
+        return self._make_request("GET", endpoint, params=params)
+
+    def post(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a POST request."""
+        return self._make_request("POST", endpoint, data=data, json_data=json_data)
+
+    def put(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a PUT request."""
+        return self._make_request("PUT", endpoint, data=data, json_data=json_data)
+
+    def patch(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make a PATCH request."""
+        return self._make_request("PATCH", endpoint, data=data, json_data=json_data)
+
+    def delete(self, endpoint: str) -> Dict[str, Any]:
+        """Make a DELETE request."""
+        response = self._make_request("DELETE", endpoint)
+        result: Dict[str, Any] = response if isinstance(response, dict) else {}
+        return result