terrakio-core 0.1.9__py3-none-any.whl

terrakio_core/auth.py

@@ -0,0 +1,237 @@
+import requests
+from typing import Optional, Dict, Any
+from .exceptions import APIError, ConfigurationError
+
+class AuthClient:
+    def __init__(self, base_url: str = "https://dev-au.terrak.io", 
+                 verify: bool = True, timeout: int = 60):
+        """
+        Initialize the Authentication Client for Terrakio API.
+        
+        Args:
+            base_url: Authentication API base URL
+            verify: Verify SSL certificates
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip('/')
+        self.verify = verify
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Content-Type': 'application/json'
+        })
+        self.token = None
+        self.api_key = None
+    
+    def signup(self, email: str, password: str) -> Dict[str, Any]:
+        """
+        Register a new user account.
+        
+        Args:
+            email: User email address
+            password: User password
+        
+        Returns:
+            API response data
+        
+        Raises:
+            APIError: If signup fails
+        """
+        endpoint = f"{self.base_url}/users/signup"
+        
+        payload = {
+            "email": email,
+            "password": password
+        }
+        
+        try:
+            response = self.session.post(
+                endpoint, 
+                json=payload,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+            
+            if not response.ok:
+                error_msg = f"Signup failed: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Signup request failed: {str(e)}")
+    
+    def login(self, email: str, password: str) -> str:
+        """
+        Log in and obtain authentication token.
+        
+        Args:
+            email: User email address
+            password: User password
+        
+        Returns:
+            Authentication token
+        
+        Raises:
+            APIError: If login fails
+        """
+        endpoint = f"{self.base_url}/users/login"
+        
+        payload = {
+            "email": email,
+            "password": password
+        }
+        
+        try:
+            response = self.session.post(
+                endpoint, 
+                json=payload,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+            
+            if not response.ok:
+                error_msg = f"Login failed: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            
+            result = response.json()
+            self.token = result.get("token")
+            
+            # Update session with authorization header
+            if self.token:
+                self.session.headers.update({
+                    "Authorization": self.token
+                })
+            
+            return self.token
+        except requests.RequestException as e:
+            raise APIError(f"Login request failed: {str(e)}")
+    
+    def refresh_api_key(self) -> str:
+        """
+        Generate or refresh API key.
+        
+        Returns:
+            API key
+        
+        Raises:
+            ConfigurationError: If not authenticated
+            APIError: If refresh fails
+        """
+        if not self.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        
+        endpoint = f"{self.base_url}/users/refresh_key"
+        
+        try:
+            # Use session with updated headers from login
+            response = self.session.post(
+                endpoint,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+            
+            if not response.ok:
+                error_msg = f"API key generation failed: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            
+            result = response.json()
+            self.api_key = result.get("apiKey")
+            return self.api_key
+        except requests.RequestException as e:
+            raise APIError(f"API key refresh request failed: {str(e)}")
+    
+    def view_api_key(self) -> str:
+        """
+        Retrieve current API key.
+        
+        Returns:
+            API key
+        
+        Raises:
+            ConfigurationError: If not authenticated
+            APIError: If retrieval fails
+        """
+        if not self.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        
+        endpoint = f"{self.base_url}/users/key"
+        
+        try:
+            # Use session with updated headers from login
+            response = self.session.get(
+                endpoint,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+            
+            if not response.ok:
+                error_msg = f"Failed to retrieve API key: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            
+            result = response.json()
+            self.api_key = result.get("apiKey")
+            return self.api_key
+        except requests.RequestException as e:
+            raise APIError(f"API key retrieval request failed: {str(e)}")
+    
+    def get_user_info(self) -> Dict[str, Any]:
+        """
+        Retrieve the current user's information.
+        
+        Returns:
+            User information data
+        
+        Raises:
+            ConfigurationError: If not authenticated
+            APIError: If retrieval fails
+        """
+        if not self.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        
+        endpoint = f"{self.base_url}/users/info"
+        
+        try:
+            # Use session with updated headers from login
+            response = self.session.get(
+                endpoint,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+            
+            if not response.ok:
+                error_msg = f"Failed to retrieve user info: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"User info retrieval request failed: {str(e)}")

terrakio_core/client.py

@@ -0,0 +1,380 @@
+import requests
+import xarray as xr
+from io import BytesIO
+from typing import Dict, Any, Optional, Union
+import json
+from shapely.geometry import shape
+from shapely.geometry.base import BaseGeometry as ShapelyGeometry
+from .exceptions import APIError, ConfigurationError
+
+class BaseClient:
+    def __init__(self, url: Optional[str] = None, key: Optional[str] = None, 
+                auth_url: Optional[str] = "https://dev-au.terrak.io",
+                quiet: bool = False, config_file: Optional[str] = None,
+                verify: bool = True, timeout: int = 60):
+        self.quiet = quiet
+        self.verify = verify
+        self.timeout = timeout
+        self.auth_client = None
+        if auth_url:
+            from terrakio_core.auth import AuthClient
+            self.auth_client = AuthClient(
+                base_url=auth_url,
+                verify=verify,
+                timeout=timeout
+            )
+        self.url = url
+        self.key = key
+        if self.url is None or self.key is None:
+            from terrakio_core.config import read_config_file, DEFAULT_CONFIG_FILE
+            if config_file is None:
+                config_file = DEFAULT_CONFIG_FILE
+            try:
+                config = read_config_file(config_file)
+                if self.url is None:
+                    self.url = config.get('url')
+                if self.key is None:
+                    self.key = config.get('key')
+            except Exception as e:
+                raise ConfigurationError(
+                    f"Failed to read configuration: {e}\n\n"
+                    "To fix this issue:\n"
+                    "1. Create a file at ~/.terrakioapirc with:\n"
+                    "url: https://api.terrak.io\n"
+                    "key: your-api-key\n\n"
+                    "OR\n\n"
+                    "2. Initialize the client with explicit parameters:\n"
+                    "client = terrakio_api.Client(\n"
+                    "    url='https://api.terrak.io',\n"
+                    "    key='your-api-key'\n"
+                    ")"
+                )
+        if not self.url:
+            raise ConfigurationError("Missing API URL in configuration")
+        if not self.key:
+            raise ConfigurationError("Missing API key in configuration")
+        self.url = self.url.rstrip('/')
+        if not self.quiet:
+            print(f"Using Terrakio API at: {self.url}")
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Content-Type': 'application/json',
+            'x-api-key': self.key
+        })
+        self.user_management = None
+        self.dataset_management = None
+
+    def validate_feature(self, feature: Dict[str, Any]) -> None:
+        if hasattr(feature, 'is_valid'):
+            from shapely.geometry import mapping
+            feature = {
+                "type": "Feature",
+                "geometry": mapping(feature),
+                "properties": {}
+            }
+        if not isinstance(feature, dict):
+            raise ValueError("Feature must be a dictionary or a Shapely geometry")
+        if feature.get("type") != "Feature":
+            raise ValueError("GeoJSON object must be of type 'Feature'")
+        if "geometry" not in feature:
+            raise ValueError("Feature must contain a 'geometry' field")
+        if "properties" not in feature:
+            raise ValueError("Feature must contain a 'properties' field")
+        try:
+            geometry = shape(feature["geometry"])
+        except Exception as e:
+            raise ValueError(f"Invalid geometry format: {str(e)}")
+        if not geometry.is_valid:
+            raise ValueError(f"Invalid geometry: {geometry.is_valid_reason}")
+        geom_type = feature["geometry"]["type"]
+        if geom_type == "Point":
+            if len(feature["geometry"]["coordinates"]) != 2:
+                raise ValueError("Point must have exactly 2 coordinates")
+        elif geom_type == "Polygon":
+            if not geometry.is_simple:
+                raise ValueError("Polygon must be simple (not self-intersecting)")
+            if geometry.area == 0:
+                raise ValueError("Polygon must have non-zero area")
+            coords = feature["geometry"]["coordinates"][0]
+            if coords[0] != coords[-1]:
+                raise ValueError("Polygon must be closed (first and last points must match)")
+
+    def signup(self, email: str, password: str) -> Dict[str, Any]:
+        if not self.auth_client:
+            raise ConfigurationError("Authentication client not initialized. Please provide auth_url during client initialization.")
+        return self.auth_client.signup(email, password)
+
+    def login(self, email: str, password: str) -> str:
+        if not self.auth_client:
+            raise ConfigurationError("Authentication client not initialized. Please provide auth_url during client initialization.")
+        token = self.auth_client.login(email, password)
+        if not self.quiet:
+            print(f"Successfully authenticated as: {email}")
+        return token
+
+    def refresh_api_key(self) -> str:
+        if not self.auth_client:
+            raise ConfigurationError("Authentication client not initialized. Please provide auth_url during client initialization.")
+        if not self.auth_client.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        self.key = self.auth_client.refresh_api_key()
+        self.session.headers.update({'x-api-key': self.key})
+        import os
+        config_path = os.path.join(os.environ.get("HOME", ""), ".tkio_config.json")
+        try:
+            config = {"EMAIL": "", "TERRAKIO_API_KEY": ""}
+            if os.path.exists(config_path):
+                with open(config_path, 'r') as f:
+                    config = json.load(f)
+            config["TERRAKIO_API_KEY"] = self.key
+            os.makedirs(os.path.dirname(config_path), exist_ok=True)
+            with open(config_path, 'w') as f:
+                json.dump(config, f, indent=4)
+            if not self.quiet:
+                print(f"API key generated successfully and updated in {config_path}")
+        except Exception as e:
+            if not self.quiet:
+                print(f"Warning: Failed to update config file: {e}")
+        return self.key
+
+    def view_api_key(self) -> str:
+        if not self.auth_client:
+            raise ConfigurationError("Authentication client not initialized. Please provide auth_url during client initialization.")
+        if not self.auth_client.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        self.key = self.auth_client.view_api_key()
+        self.session.headers.update({'x-api-key': self.key})
+        return self.key
+
+    def get_user_info(self) -> Dict[str, Any]:
+        if not self.auth_client:
+            raise ConfigurationError("Authentication client not initialized. Please provide auth_url during client initialization.")
+        if not self.auth_client.token:
+            raise ConfigurationError("Not authenticated. Call login() first.")
+        return self.auth_client.get_user_info()
+
+    def wcs(self, expr: str, feature: Union[Dict[str, Any], ShapelyGeometry], in_crs: str = "epsg:4326",
+            out_crs: str = "epsg:4326", output: str = "csv", resolution: int = -1,
+            **kwargs):
+        if hasattr(feature, 'is_valid'):
+            from shapely.geometry import mapping
+            feature = {
+                "type": "Feature",
+                "geometry": mapping(feature),
+                "properties": {}
+            }
+        self.validate_feature(feature)
+        payload = {
+            "feature": feature,
+            "in_crs": in_crs,
+            "out_crs": out_crs,
+            "output": output,
+            "resolution": resolution,
+            "expr": expr,
+            **kwargs
+        }
+        if not self.quiet:
+            print(f"Requesting data with expression: {expr}")
+        request_url = f"{self.url}/wcs"
+        try:
+            response = self.session.post(request_url, json=payload, timeout=self.timeout, verify=self.verify)
+            if not response.ok:
+                error_msg = f"API request failed: {response.status_code} {response.reason}"
+                try:
+                    error_data = response.json()
+                    if "detail" in error_data:
+                        error_msg += f" - {error_data['detail']}"
+                except:
+                    pass
+                raise APIError(error_msg)
+            if output.lower() == "csv":
+                import pandas as pd
+                return pd.read_csv(BytesIO(response.content))
+            elif output.lower() == "netcdf":
+                return xr.open_dataset(BytesIO(response.content))
+            else:
+                try:
+                    return xr.open_dataset(BytesIO(response.content))
+                except ValueError:
+                    import pandas as pd
+                    try:
+                        return pd.read_csv(BytesIO(response.content))
+                    except:
+                        return response.content
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    # Admin/protected methods
+    def _get_user_by_id(self, user_id: str):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.get_user_by_id(user_id)
+
+    def _get_user_by_email(self, email: str):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.get_user_by_email(email)
+
+    def _list_users(self, substring: str = None, uid: bool = False):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.list_users(substring=substring, uid=uid)
+
+    def _edit_user(self, user_id: str, uid: str = None, email: str = None, role: str = None, apiKey: str = None, groups: list = None, quota: int = None):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.edit_user(
+            user_id=user_id,
+            uid=uid,
+            email=email,
+            role=role,
+            apiKey=apiKey,
+            groups=groups,
+            quota=quota
+        )
+
+    def _reset_quota(self, email: str, quota: int = None):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.reset_quota(email=email, quota=quota)
+
+    def _delete_user(self, uid: str):
+        if not self.user_management:
+            from terrakio_core.user_management import UserManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("User management client not initialized. Make sure API URL and key are set.")
+            self.user_management = UserManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.user_management.delete_user(uid=uid)
+
+    # Dataset management protected methods
+    def _get_dataset(self, name: str, collection: str = "terrakio-datasets"):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.get_dataset(name=name, collection=collection)
+
+    def _list_datasets(self, substring: str = None, collection: str = "terrakio-datasets"):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.list_datasets(substring=substring, collection=collection)
+
+    def _create_dataset(self, name: str, collection: str = "terrakio-datasets", **kwargs):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.create_dataset(name=name, collection=collection, **kwargs)
+
+    def _update_dataset(self, name: str, append: bool = True, collection: str = "terrakio-datasets", **kwargs):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.update_dataset(name=name, append=append, collection=collection, **kwargs)
+
+    def _overwrite_dataset(self, name: str, collection: str = "terrakio-datasets", **kwargs):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.overwrite_dataset(name=name, collection=collection, **kwargs)
+
+    def _delete_dataset(self, name: str, collection: str = "terrakio-datasets"):
+        if not self.dataset_management:
+            from terrakio_core.dataset_management import DatasetManagement
+            if not self.url or not self.key:
+                raise ConfigurationError("Dataset management client not initialized. Make sure API URL and key are set.")
+            self.dataset_management = DatasetManagement(
+                api_url=self.url,
+                api_key=self.key,
+                verify=self.verify,
+                timeout=self.timeout
+            )
+        return self.dataset_management.delete_dataset(name=name, collection=collection)
+
+    def close(self):
+        self.session.close()
+        if self.auth_client:
+            self.auth_client.session.close()
+    def __enter__(self):
+        return self
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

terrakio_core/config.py

@@ -0,0 +1,81 @@
+import os
+import json
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+from .exceptions import ConfigurationError
+
+# Default configuration file locations
+DEFAULT_CONFIG_FILE = os.path.join(os.environ.get("HOME", ""), ".tkio_config.json")
+DEFAULT_API_URL = "https://api.terrak.io"
+
+def read_config_file(config_file: str = DEFAULT_CONFIG_FILE) -> Dict[str, Any]:
+    """
+    Read and parse the configuration file.
+    
+    Args:
+        config_file: Path to the configuration file
+        
+    Returns:
+        Dict[str, Any]: Configuration parameters
+        
+    Raises:
+        ConfigurationError: If the configuration file can't be read or parsed
+    """
+    config_path = Path(os.path.expanduser(config_file))
+    
+    if not config_path.exists():
+        raise ConfigurationError(
+            f"Configuration file not found: {config_file}\n"
+            f"Please create a file at {config_file} with the following format:\n"
+            '{\n  "EMAIL": "your-email@example.com",\n  "TERRAKIO_API_KEY": "your-api-key-here"\n}'
+        )
+    
+    try:
+        with open(config_path, 'r') as f:
+            config_data = json.load(f)
+            
+        # Convert the JSON config to our expected format
+        config = {
+            # Allow config to override default URL if provided
+            'url': config_data.get('TERRAKIO_API_URL', DEFAULT_API_URL),
+            'key': config_data.get('TERRAKIO_API_KEY')
+        }
+        return config
+            
+    except Exception as e:
+        raise ConfigurationError(f"Failed to parse configuration file: {e}")
+
+def create_default_config(email: str, api_key: str, api_url: Optional[str] = None, config_file: str = DEFAULT_CONFIG_FILE) -> None:
+    """
+    Create a default configuration file in JSON format.
+    
+    Args:
+        email: User email
+        api_key: Terrakio API key
+        api_url: Optional API URL (if different from default)
+        config_file: Path to configuration file
+        
+    Raises:
+        ConfigurationError: If the configuration file can't be created
+    """
+    config_path = Path(os.path.expanduser(config_file))
+    
+    # Ensure directory exists
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    try:
+        config_data = {
+            "EMAIL": email,
+            "TERRAKIO_API_KEY": api_key
+        }
+        
+        # Add API URL if provided
+        if api_url:
+            config_data["TERRAKIO_API_URL"] = api_url
+        
+        with open(config_path, 'w') as f:
+            json.dump(config_data, f, indent=2)
+            
+    except Exception as e:
+        raise ConfigurationError(f"Failed to create configuration file: {e}")

terrakio_core/dataset_management.py

@@ -0,0 +1,235 @@
+import requests
+from typing import Dict, Any, List, Optional
+from .exceptions import APIError
+
+class DatasetManagement:
+    def __init__(self, api_url: str, api_key: str, verify: bool = True, timeout: int = 60):
+        """
+        Initialize the Dataset Management client.
+        
+        Args:
+            api_url: API base URL
+            api_key: API key for authentication
+            verify: Verify SSL certificates
+            timeout: Request timeout in seconds
+        """
+        self.api_url = api_url.rstrip('/')
+        self.api_key = api_key
+        self.verify = verify
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            'x-api-key': self.api_key,
+            'Content-Type': 'application/json'
+        })
+
+    def get_dataset(self, name: str, collection: str = "terrakio-datasets") -> Dict[str, Any]:
+        """
+        Retrieve dataset info by dataset name.
+        
+        Args:
+            name: The name of the dataset (required)
+            collection: The dataset collection (default: 'terrakio-datasets')
+            
+        Returns:
+            Dataset information as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets/{name}"
+        params = {"collection": collection} if collection else {}
+        try:
+            response = self.session.get(
+                endpoint,
+                params=params,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def list_datasets(self, substring: Optional[str] = None, collection: str = "terrakio-datasets") -> List[Dict[str, Any]]:
+        """
+        List datasets, optionally filtering by a substring and collection.
+        
+        Args:
+            substring: Substring to filter by (optional)
+            collection: Dataset collection (default: 'terrakio-datasets')
+            
+        Returns:
+            List of datasets matching the criteria
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets"
+        params = {"collection": collection}
+        if substring:
+            params["substring"] = substring
+        try:
+            response = self.session.get(
+                endpoint,
+                params=params,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def create_dataset(self, name: str, collection: str = "terrakio-datasets", **kwargs) -> Dict[str, Any]:
+        """
+        Create a new dataset.
+        
+        Args:
+            name: Name of the dataset (required)
+            collection: Dataset collection (default: 'terrakio-datasets')
+            **kwargs: Additional dataset parameters including:
+                - products: List of products
+                - dates_iso8601: List of dates
+                - bucket: Storage bucket
+                - path: Storage path
+                - data_type: Data type
+                - no_data: No data value
+                - l_max: Maximum level
+                - y_size: Y size
+                - x_size: X size
+                - proj4: Projection string
+                - abstract: Dataset abstract
+                - geotransform: Geotransform parameters
+                
+        Returns:
+            Created dataset information
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets"
+        params = {"collection": collection}
+        # Create payload with required name parameter
+        payload = {"name": name}
+        
+        # Add optional parameters if provided
+        for param in ["products", "dates_iso8601", "bucket", "path", "data_type", 
+                     "no_data", "l_max", "y_size", "x_size", "proj4", "abstract", "geotransform"]:
+            if param in kwargs:
+                payload[param] = kwargs[param]
+        
+        try:
+            response = self.session.post(
+                endpoint,
+                params=params,
+                json=payload,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def update_dataset(self, name: str, append: bool = True, collection: str = "terrakio-datasets", **kwargs) -> Dict[str, Any]:
+        """
+        Update a dataset. By default, values are appended unless append is set to False.
+        
+        Args:
+            name: Name of the dataset (required)
+            append: Whether to append values (default: True)
+            collection: Dataset collection (default: 'terrakio-datasets')
+            **kwargs: Additional dataset parameters to update
+                
+        Returns:
+            Updated dataset information
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets"
+        params = {"append": str(append).lower(), "collection": collection}
+        payload = {"name": name}
+        payload.update(kwargs)
+        try:
+            response = self.session.patch(
+                endpoint,
+                params=params,
+                json=payload,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def overwrite_dataset(self, name: str, collection: str = "terrakio-datasets", **kwargs) -> Dict[str, Any]:
+        """
+        Overwrite a dataset (replace all values).
+        
+        Args:
+            name: Name of the dataset (required)
+            collection: Dataset collection (default: 'terrakio-datasets')
+            **kwargs: New dataset parameters
+                
+        Returns:
+            Updated dataset information
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets"
+        params = {"collection": collection}
+        payload = {"name": name}
+        payload.update(kwargs)
+        try:
+            response = self.session.put(
+                endpoint,
+                params=params,
+                json=payload,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def delete_dataset(self, name: str, collection: str = "terrakio-datasets") -> Dict[str, Any]:
+        """
+        Delete a dataset by name.
+        
+        Args:
+            name: The name of the dataset (required)
+            collection: Dataset collection (default: 'terrakio-datasets')
+                
+        Returns:
+            API response as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/datasets/{name}"
+        params = {"collection": collection}
+        try:
+            response = self.session.delete(
+                endpoint,
+                params=params,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if response.status_code == 404:
+                return {"status": "error", "message": f"Dataset '{name}' does not exist in collection '{collection}'"}
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}") 

terrakio_core/exceptions.py

@@ -0,0 +1,18 @@
+class APIError(Exception):
+    """Exception raised for errors in the API responses."""
+    pass
+
+
+class ConfigurationError(Exception):
+    """Exception raised for errors in the configuration."""
+    pass
+
+
+class DownloadError(Exception):
+    """Exception raised for errors during data download."""
+    pass
+
+
+class ValidationError(Exception):
+    """Exception raised for invalid request parameters."""
+    pass

terrakio_core/user_management.py

@@ -0,0 +1,227 @@
+import requests
+from typing import Dict, Any, List, Optional
+from .exceptions import APIError, ConfigurationError
+
+class UserManagement:
+    def __init__(self, api_url: str, api_key: str, verify: bool = True, timeout: int = 60):
+        """
+        Initialize the User Management client.
+        
+        Args:
+            api_url: API base URL
+            api_key: API key for authentication
+            verify: Verify SSL certificates
+            timeout: Request timeout in seconds
+        """
+        self.api_url = api_url.rstrip('/')
+        self.api_key = api_key
+        self.verify = verify
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            'x-api-key': self.api_key,
+            'Content-Type': 'application/json'
+        })
+
+    def get_user_by_id(self, user_id: str) -> Dict[str, Any]:
+        """
+        Retrieve user info by user ID.
+        
+        Args:
+            user_id: User ID to retrieve
+        
+        Returns:
+            User information as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/admin/users/{user_id}"
+        try:
+            response = self.session.get(
+                endpoint, 
+                timeout=self.timeout, 
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def get_user_by_email(self, email: str) -> Dict[str, Any]:
+        """
+        Retrieve user info by email.
+        
+        Args:
+            email: User email to retrieve
+            
+        Returns:
+            User information as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+
+        endpoint = f"{self.api_url}/admin/users/email/{email}"
+        try:
+            response = self.session.get(
+                endpoint, 
+                timeout=self.timeout, 
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def edit_user(
+        self,
+        user_id: str,
+        uid: Optional[str] = None,
+        email: Optional[str] = None,
+        role: Optional[str] = None,
+        apiKey: Optional[str] = None,
+        groups: Optional[List[str]] = None,
+        quota: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Edit user info. Only provided fields will be updated.
+        
+        Args:
+            user_id: User ID (required)
+            uid: New user ID (optional)
+            email: New user email (optional)
+            role: New user role (optional)
+            apiKey: New API key (optional)
+            groups: New list of groups (optional)
+            quota: New quota value (optional)
+            
+        Returns:
+            Updated user information
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/admin/users"
+        payload = {"uid": user_id}
+
+        if uid is not None:
+            payload["uid"] = uid
+        if email is not None:
+            payload["email"] = email
+        if role is not None:
+            payload["role"] = role
+        if apiKey is not None:
+            payload["apiKey"] = apiKey
+        if groups is not None:
+            payload["groups"] = groups
+        if quota is not None:
+            payload["quota"] = quota
+
+        try:
+            response = self.session.patch(
+                endpoint,
+                json=payload,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def list_users(self, substring: Optional[str] = None, uid: bool = False) -> List[Dict[str, Any]]:
+        """
+        List users, optionally filtering by a substring.
+        
+        Args:
+            substring: Optional substring to filter users
+            uid: If True, includes the user ID in the response (default: False)
+        
+        Returns:
+            List of users
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        # Use the base API URL instead of hardcoding
+        endpoint = f"{self.api_url}/admin/users"
+
+        params = {}
+        if substring:
+            params["substring"] = substring
+        if uid:
+            params["uid"] = "true"
+
+        try:
+            response = self.session.get(
+                endpoint,
+                params=params,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def reset_quota(self, email: str, quota: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Reset the quota for a user by email.
+        
+        Args:
+            email: The user's email (required)
+            quota: The new quota value (optional)
+            
+        Returns:
+            API response as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/admin/users/reset_quota/{email}"
+        payload = {"email": email}
+        if quota is not None:
+            payload["quota"] = quota
+        try:
+            response = self.session.patch(
+                endpoint,
+                json=payload,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+
+    def delete_user(self, uid: str) -> Dict[str, Any]:
+        """
+        Delete a user by UID.
+        
+        Args:
+            uid: The user's UID (required)
+            
+        Returns:
+            API response as a dictionary
+            
+        Raises:
+            APIError: If the API request fails
+        """
+        endpoint = f"{self.api_url}/admin/users/{uid}"
+        try:
+            response = self.session.delete(
+                endpoint,
+                timeout=self.timeout,
+                verify=self.verify
+            )
+            if not response.ok:
+                raise APIError(f"API request failed: {response.status_code} {response.reason}")
+            return response.json()
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")

terrakio_core-0.1.9.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: terrakio-core
+Version: 0.1.9
+Summary: Core components for Terrakio API clients
+Home-page: https://github.com/HaizeaAnalytics/terrakio-python-api
+Author: Yupeng Chao
+Author-email: Yupeng Chao <yupeng@haizea.com.au>
+Project-URL: Homepage, https://github.com/HaizeaAnalytics/terrakio-python-api
+Project-URL: Bug Tracker, https://github.com/HaizeaAnalytics/terrakio-python-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: xarray>=2023.1.0
+Requires-Dist: shapely>=2.0.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Terrakio Core
+
+Core components for Terrakio API clients. This package provides the foundational classes and utilities used by both the regular and admin API clients.
+
+This package is typically not used directly but is a dependency for:
+- `terrakio-api`: Regular user client
+- `terrakio-admin-api`: Administrative client
+
+For documentation and usage examples, see the [main repository](https://github.com/HaizeaAnalytics/terrakio-python-api). 

terrakio_core-0.1.9.dist-info/RECORD

@@ -0,0 +1,11 @@
+terrakio_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+terrakio_core/auth.py,sha256=Y3X5CcRUO7rAsrv995cSedZFKJAsW6ObDinYCbcQMpc,7605
+terrakio_core/client.py,sha256=hjWxttPlrKfq5myHqWq2GT23pBGxRplm2FAY5j5YHCA,17441
+terrakio_core/config.py,sha256=AwJ1VgR5K7N32XCU5k7_Dp1nIv_FYt8MBonq9yKlGzA,2658
+terrakio_core/dataset_management.py,sha256=hhO35fwStS6HYFQdKP9wkr3DxHgjvpctmIU8UWH6w6U,8742
+terrakio_core/exceptions.py,sha256=9S-I20-QiDRj1qgjFyYUwYM7BLic_bxurcDOIm2Fu_0,410
+terrakio_core/user_management.py,sha256=Sl7wJOg1eUVUpcsgRjeknibYiIleLJk1VgJI7Mdpsss,7345
+terrakio_core-0.1.9.dist-info/METADATA,sha256=AjBJ_avgfU8vz0ZPzHgQEJZMJboE0F3e1ggGRuw6djM,1488
+terrakio_core-0.1.9.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+terrakio_core-0.1.9.dist-info/top_level.txt,sha256=5cBj6O7rNWyn97ND4YuvvXm0Crv4RxttT4JZvNdOG6Q,14
+terrakio_core-0.1.9.dist-info/RECORD,,

terrakio_core-0.1.9.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.3.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

terrakio_core-0.1.9.dist-info/top_level.txt

@@ -0,0 +1 @@
+terrakio_core