terrakio-api 0.1.0__tar.gz

terrakio_api-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: terrakio_api
+Version: 0.1.0
+Summary: A client library for Terrakio's WCS API service
+Home-page: https://github.com/HaizeaAnalytics/terrakio-python-api
+Author: Yupeng Chao
+Author-email: yupeng@haizea.com.au
+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
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: xarray>=2023.1.0
+Requires-Dist: netcdf4>=1.6.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: scipy>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
+Requires-Dist: black>=20.8b1; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Terrakio API Client
+
+A Python client for Terrakio's Web Coverage Service (WCS) API.
+
+## Installation
+
+```bash
+pip install terrakio-api

terrakio_api-0.1.0/README.md

@@ -0,0 +1,8 @@
+# Terrakio API Client
+
+A Python client for Terrakio's Web Coverage Service (WCS) API.
+
+## Installation
+
+```bash
+pip install terrakio-api

terrakio_api-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

terrakio_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

terrakio_api-0.1.0/setup.py

@@ -0,0 +1,48 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setup(
+    name="terrakio_api",
+    version="0.1.0",
+    author="Yupeng Chao",
+    author_email="yupeng@haizea.com.au",
+    description="A client library for Terrakio's WCS API service",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/HaizeaAnalytics/terrakio-python-api",
+    # packages=find_packages(),
+    packages=["terrakio_api", "terrakio_api.utils"],  # Explicitly list packages instead of find_packages()
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering",
+    ],
+    python_requires=">=3.7",
+    install_requires=[
+        "requests>=2.25.0",
+        "pyyaml>=5.1",
+        "xarray>=2023.1.0",
+        "netcdf4>=1.6.0",
+        "pandas>=1.5.0",
+        "numpy>=1.22.0",
+        "scipy>=1.8.0",  # Added SciPy dependency
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=6.0.0",
+            "pytest-cov>=2.10.0",
+            "black>=20.8b1",
+            "flake8>=3.8.0",
+        ],
+    },
+    metadata_version='2.2'
+)

terrakio_api-0.1.0/terrakio_api/__init__.py

@@ -0,0 +1,20 @@
+"""
+Terrakio API Client
+
+A Python client for accessing Terrakio's Web Coverage Service (WCS) API.
+"""
+
+__version__ = "0.1.0"
+
+from .client import Client
+from .config import create_default_config
+from .exceptions import APIError, ConfigurationError, DownloadError, ValidationError
+
+__all__ = [
+    'Client',
+    'create_default_config',
+    'APIError',
+    'ConfigurationError',
+    'DownloadError',
+    'ValidationError',
+]

terrakio_api-0.1.0/terrakio_api/api.py

@@ -0,0 +1,48 @@
+import requests
+import json
+from typing import Dict, Any, Tuple, Optional
+
+from .exceptions import APIError
+
+def make_request(session: requests.Session, url: str, payload: Dict[str, Any], 
+                timeout: int = 60, verify: bool = True):
+    """
+    Make an API request to the Terrakio API.
+    
+    Args:
+        session: Requests session with authentication
+        url: API endpoint URL
+        payload: Request payload
+        timeout: Request timeout in seconds
+        verify: Verify SSL certificates
+        
+    Returns:
+        Response object
+        
+    Raises:
+        APIError: If the API returns an error
+    """
+    try:
+        response = session.post(
+            url,
+            json=payload,
+            timeout=timeout,
+            verify=verify
+        )
+        
+        # Handle HTTP errors
+        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)
+        
+        return response
+            
+    except requests.RequestException as e:
+        raise APIError(f"Request failed: {str(e)}")

terrakio_api-0.1.0/terrakio_api/client.py

@@ -0,0 +1,158 @@
+import requests
+import xarray as xr
+import time
+from io import BytesIO
+from pathlib import Path
+from typing import Dict, Any, Optional, Union, BinaryIO
+
+from .config import read_config_file, DEFAULT_CONFIG_FILE
+from .exceptions import APIError, ConfigurationError, DownloadError
+from .api import make_request
+from .utils.validation import validate_feature
+
+class Client:
+    def __init__(self, url: Optional[str] = None, key: Optional[str] = None, 
+                 quiet: bool = False, config_file: Optional[str] = None,
+                 verify: bool = True, timeout: int = 60):
+        """
+        Initialize the Terrakio API client.
+        
+        Args:
+            url: API base URL (optional, will use config file if not provided)
+            key: API key or token (optional, will use config file if not provided)
+            quiet: If True, suppress progress messages
+            config_file: Path to configuration file (default is ~/.terrakioapirc)
+            verify: Verify SSL certificates
+            timeout: Request timeout in seconds
+        """
+        self.quiet = quiet
+        self.verify = verify
+        self.timeout = timeout
+        
+        # Try to get config from parameters first, then config file
+        if url is not None and key is not None:
+            self.url = url
+            self.key = key
+        else:
+            if config_file is None:
+                config_file = DEFAULT_CONFIG_FILE
+            
+            try:
+                config = read_config_file(config_file)
+                self.url = config.get('url')
+                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://terrakio-server-candidate-d4w6vamyxq-ts.a.run.app/wcs_secure\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://terrakio-server-candidate-d4w6vamyxq-ts.a.run.app/wcs_secure',\n"
+                    "    key='your-api-key'\n"
+                    ")"
+                )
+        
+        # Validate configuration
+        if not self.url:
+            raise ConfigurationError("Missing API URL in configuration")
+        if not self.key:
+            raise ConfigurationError("Missing API key in configuration")
+            
+        # Ensure URL doesn't end with slash
+        self.url = self.url.rstrip('/')
+        
+        if not self.quiet:
+            print(f"Using Terrakio API at: {self.url}")
+        
+        # Initialize session for connection pooling
+        self.session = requests.Session()
+        self.session.headers.update({
+            'Content-Type': 'application/json',
+            'x-api-key': self.key
+        })
+    
+    def wcs(self, expr: str, feature: Dict[str, Any], in_crs: str = "epsg:4326",
+            out_crs: str = "epsg:4326", output: str = "csv", resolution: int = -1,
+            **kwargs):
+        """
+        Make a WCS request to the Terrakio API.
+        
+        Args:
+            expr: Expression string for data selection
+            feature: GeoJSON Feature dictionary containing geometry information
+            in_crs: Input coordinate reference system (default: "epsg:4326")
+            out_crs: Output coordinate reference system (default: "epsg:4326")
+            output: Output format (default: "csv")
+            resolution: Resolution value (default: -1)
+            **kwargs: Additional parameters to pass to the API
+            
+        Returns:
+            Data in the requested format (xr.Dataset for netcdf, pd.DataFrame for csv)
+        """
+        # Validate the feature object
+        validate_feature(feature)
+        
+        # Prepare the payload
+        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}")
+        
+        try:
+            # Make the API request
+            response = self.session.post(self.url, json=payload, timeout=self.timeout, verify=self.verify)
+            
+            # Handle HTTP errors
+            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)
+            
+            # Handle different output formats
+            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 to determine the format and use appropriate reader
+                try:
+                    return xr.open_dataset(BytesIO(response.content))
+                except ValueError:
+                    import pandas as pd
+                    try:
+                        return pd.read_csv(BytesIO(response.content))
+                    except:
+                        # If all else fails, return the raw content
+                        return response.content
+            
+        except requests.RequestException as e:
+            raise APIError(f"Request failed: {str(e)}")
+    
+    def close(self):
+        """Close the client session."""
+        self.session.close()
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

terrakio_api-0.1.0/terrakio_api/config.py

@@ -0,0 +1,81 @@
+import os
+import yaml
+from pathlib import Path
+from typing import Dict, Any
+
+from .exceptions import ConfigurationError
+
+# Default configuration file location
+DEFAULT_CONFIG_FILE = os.path.expanduser("~/.tkioapirc")
+
+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"
+            "url: https://terrakio-server-candidate-d4w6vamyxq-ts.a.run.app/wcs_secure\n"
+            "key: your-api-key-here"
+        )
+    
+    try:
+        with open(config_path, 'r') as f:
+            content = f.read().strip()
+            
+            # Support both YAML and simple key: value format
+            if ':' in content and '{' not in content:
+                # Simple key: value format (like CDSAPI uses)
+                config = {}
+                for line in content.split('\n'):
+                    line = line.strip()
+                    if line and not line.startswith('#'):
+                        try:
+                            key, value = [x.strip() for x in line.split(':', 1)]
+                            config[key] = value
+                        except ValueError:
+                            # Skip lines that don't have a colon
+                            pass
+                return config
+            else:
+                # YAML format for more complex configuration
+                return yaml.safe_load(content) or {}
+    except Exception as e:
+        raise ConfigurationError(f"Failed to parse configuration file: {e}")
+
+def create_default_config(url: str, key: str, config_file: str = DEFAULT_CONFIG_FILE) -> None:
+    """
+    Create a default configuration file.
+    
+    Args:
+        url: API base URL
+        key: API key
+        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:
+        with open(config_path, 'w') as f:
+            f.write(f"url: {url}\n")
+            f.write(f"key: {key}\n")
+            f.write("# Configuration file for Terrakio API\n")
+    except Exception as e:
+        raise ConfigurationError(f"Failed to create configuration file: {e}")

terrakio_api-0.1.0/terrakio_api/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_api-0.1.0/terrakio_api/utils/__init__.py

@@ -0,0 +1,9 @@
+"""Utility functions for the Terrakio API client."""
+
+from .validation import validate_feature, create_point_feature, create_polygon_feature
+
+__all__ = [
+    'validate_feature',
+    'create_point_feature',
+    'create_polygon_feature',
+]

terrakio_api-0.1.0/terrakio_api/utils/download.py

@@ -0,0 +1,51 @@
+import requests
+from typing import Union, BinaryIO
+from pathlib import Path
+
+from ..exceptions import DownloadError
+
+def download_file(url: str, target: Union[str, Path, BinaryIO], 
+                session: requests.Session = None, chunk_size: int = 8192,
+                timeout: int = 60, verify: bool = True) -> None:
+    """
+    Download a file from a URL.
+    
+    Args:
+        url: URL to download from
+        target: Path or file-like object to write to
+        session: Optional requests session to use
+        chunk_size: Size of chunks to download
+        timeout: Request timeout
+        verify: Verify SSL certificates
+        
+    Raises:
+        DownloadError: If download fails
+    """
+    try:
+        # Use provided session or create a new one
+        if session is None:
+            _session = requests.Session()
+        else:
+            _session = session
+        
+        # Stream the download
+        with _session.get(url, stream=True, timeout=timeout, verify=verify) as response:
+            if not response.ok:
+                raise DownloadError(f"Download failed: {response.status_code} {response.reason}")
+            
+            # Handle different target types
+            if isinstance(target, (str, Path)):
+                with open(target, 'wb') as f:
+                    for chunk in response.iter_content(chunk_size=chunk_size):
+                        f.write(chunk)
+            else:
+                # Assume file-like object
+                for chunk in response.iter_content(chunk_size=chunk_size):
+                    target.write(chunk)
+                    
+    except requests.RequestException as e:
+        raise DownloadError(f"Download failed: {str(e)}")
+    finally:
+        # Close the session if we created it
+        if session is None and '_session' in locals():
+            _session.close()

terrakio_api-0.1.0/terrakio_api/utils/validation.py

@@ -0,0 +1,85 @@
+from typing import Dict, Any, List
+from ..exceptions import ValidationError
+
+def validate_feature(feature: Dict[str, Any]) -> None:
+    """
+    Validate a GeoJSON Feature object.
+    
+    Args:
+        feature: GeoJSON Feature dictionary
+        
+    Raises:
+        ValidationError: If the feature is invalid
+    """
+    if not isinstance(feature, dict):
+        raise ValidationError("Feature must be a dictionary")
+    
+    if feature.get('type') != 'Feature':
+        raise ValidationError("Feature must have 'type' property set to 'Feature'")
+    
+    if 'geometry' not in feature:
+        raise ValidationError("Feature must have a 'geometry' property")
+    
+    geometry = feature['geometry']
+    if not isinstance(geometry, dict):
+        raise ValidationError("Feature geometry must be a dictionary")
+    
+    if 'type' not in geometry:
+        raise ValidationError("Geometry must have a 'type' property")
+    
+    if 'coordinates' not in geometry:
+        raise ValidationError("Geometry must have a 'coordinates' property")
+    
+    # Add more specific validation based on geometry type if needed
+
+def create_point_feature(lon: float, lat: float, properties: Dict[str, Any] = None) -> Dict[str, Any]:
+    """
+    Create a GeoJSON Point Feature object.
+    
+    Args:
+        lon: Longitude coordinate
+        lat: Latitude coordinate
+        properties: Optional properties dictionary (default: empty dict)
+        
+    Returns:
+        Dict: GeoJSON Feature object
+    """
+    if properties is None:
+        properties = {}
+        
+    return {
+        "type": "Feature",
+        "properties": properties,
+        "geometry": {
+            "type": "Point",
+            "coordinates": [lon, lat]
+        }
+    }
+
+
+def create_polygon_feature(coordinates: List[List[float]], properties: Dict[str, Any] = None) -> Dict[str, Any]:
+    """
+    Create a GeoJSON Polygon Feature object.
+    
+    Args:
+        coordinates: List of [lon, lat] coordinate pairs forming a polygon (first and last must be identical)
+        properties: Optional properties dictionary (default: empty dict)
+        
+    Returns:
+        Dict: GeoJSON Feature object
+    """
+    if properties is None:
+        properties = {}
+    
+    # Check if polygon is closed
+    if coordinates[0] != coordinates[-1]:
+        coordinates.append(coordinates[0])  # Close the polygon
+        
+    return {
+        "type": "Feature",
+        "properties": properties,
+        "geometry": {
+            "type": "Polygon",
+            "coordinates": [coordinates]
+        }
+    }

terrakio_api-0.1.0/terrakio_api.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: terrakio_api
+Version: 0.1.0
+Summary: A client library for Terrakio's WCS API service
+Home-page: https://github.com/HaizeaAnalytics/terrakio-python-api
+Author: Yupeng Chao
+Author-email: yupeng@haizea.com.au
+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
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: xarray>=2023.1.0
+Requires-Dist: netcdf4>=1.6.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: scipy>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.10.0; extra == "dev"
+Requires-Dist: black>=20.8b1; extra == "dev"
+Requires-Dist: flake8>=3.8.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Terrakio API Client
+
+A Python client for Terrakio's Web Coverage Service (WCS) API.
+
+## Installation
+
+```bash
+pip install terrakio-api

terrakio_api-0.1.0/terrakio_api.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+terrakio_api/__init__.py
+terrakio_api/api.py
+terrakio_api/client.py
+terrakio_api/config.py
+terrakio_api/exceptions.py
+terrakio_api.egg-info/PKG-INFO
+terrakio_api.egg-info/SOURCES.txt
+terrakio_api.egg-info/dependency_links.txt
+terrakio_api.egg-info/requires.txt
+terrakio_api.egg-info/top_level.txt
+terrakio_api/utils/__init__.py
+terrakio_api/utils/download.py
+terrakio_api/utils/validation.py

terrakio_api-0.1.0/terrakio_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

terrakio_api-0.1.0/terrakio_api.egg-info/requires.txt

@@ -0,0 +1,13 @@
+requests>=2.25.0
+pyyaml>=5.1
+xarray>=2023.1.0
+netcdf4>=1.6.0
+pandas>=1.5.0
+numpy>=1.22.0
+scipy>=1.8.0
+
+[dev]
+pytest>=6.0.0
+pytest-cov>=2.10.0
+black>=20.8b1
+flake8>=3.8.0

terrakio_api-0.1.0/terrakio_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+terrakio_api