upstream-sdk 1.0.0__py3-none-any.whl

upstream/__init__.py

@@ -0,0 +1,51 @@
+"""
+Upstream Python SDK for environmental sensor data platform and CKAN integration.
+
+This package provides a standardized toolkit for environmental researchers and organizations
+to interact with the Upstream API and CKAN data portals.
+"""
+
+from .auth import AuthManager
+from .campaigns import CampaignManager
+from .client import UpstreamClient
+from .data import DataUploader, DataValidator
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    UploadError,
+    UpstreamError,
+    ValidationError,
+)
+from .stations import StationManager
+
+__version__ = "1.0.0"
+__author__ = "In-For-Disaster-Analytics Team"
+__email__ = "info@tacc.utexas.edu"
+__license__ = "MIT"
+
+__all__ = [
+    # Core client
+    "UpstreamClient",
+    # Authentication
+    "AuthManager",
+    # Campaign management
+    "CampaignManager",
+    # Station management
+    "StationManager",
+    # Data handling
+    "DataUploader",
+    "DataValidator",
+    # CKAN integration
+    "CKANIntegration",
+    # Exceptions
+    "UpstreamError",
+    "AuthenticationError",
+    "ValidationError",
+    "UploadError",
+    "APIError",
+    # Metadata
+    "__version__",
+    "__author__",
+    "__email__",
+    "__license__",
+]

upstream/auth.py

@@ -0,0 +1,153 @@
+"""
+Authentication manager for Upstream SDK using OpenAPI client.
+"""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Any, Dict, Optional
+
+from upstream_api_client import ApiClient, Configuration
+from upstream_api_client.api import AuthApi
+from upstream_api_client.rest import ApiException
+
+from .exceptions import AuthenticationError, ConfigurationError, NetworkError
+from .utils import ConfigManager
+
+logger = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """
+    Manages authentication with the Upstream API using OpenAPI client.
+    """
+
+    def __init__(self, config: ConfigManager) -> None:
+        """
+        Initialize authentication manager.
+
+        Args:
+            config: Configuration manager instance
+        """
+        self.config = config
+        self.configuration = Configuration(host=config.base_url)
+        self.api_client: Optional[ApiClient] = None
+        self.access_token: Optional[str] = None
+        self.token_expires_at: Optional[datetime] = None
+
+        # Validate configuration
+        if not config.username or not config.password:
+            raise ConfigurationError("Username and password are required")
+
+    def authenticate(self) -> bool:
+        """
+        Authenticate with the Upstream API.
+
+        Returns:
+            True if authentication successful
+
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        try:
+            with ApiClient(self.configuration) as api_client:
+                auth_api = AuthApi(api_client)
+                # Attempt login
+                if self.config.username is None or self.config.password is None:
+                    raise AuthenticationError("Username and password are required")
+
+                response = auth_api.login_api_v1_token_post(
+                    username=self.config.username,
+                    password=self.config.password,
+                    grant_type="password",
+                )
+
+                # Store token information
+                self.access_token = response.access_token
+                self.configuration.access_token = response.access_token
+
+                # Calculate expiration time (default to 1 hour if not provided)
+                expires_in = getattr(response, "expires_in", 3600)
+                self.token_expires_at = datetime.now() + timedelta(seconds=expires_in)
+
+                logger.info("Successfully authenticated with Upstream API")
+                return True
+
+        except ApiException as e:
+            if e.status == 401:
+                raise AuthenticationError("Invalid username or password")
+            elif e.status == 422:
+                raise AuthenticationError("Authentication request validation failed")
+            else:
+                raise AuthenticationError(f"Authentication failed: {e}")
+        except Exception as e:
+            raise NetworkError(f"Authentication request failed: {e}")
+
+    def is_authenticated(self) -> bool:
+        """
+        Check if currently authenticated with a valid token.
+
+        Returns:
+            True if authenticated with valid token
+        """
+        if not self.access_token or not self.token_expires_at:
+            return False
+
+        # Consider token expired if it expires within 5 minutes
+        buffer_time = timedelta(minutes=5)
+        return datetime.now() < (self.token_expires_at - buffer_time)
+
+    def get_api_client(self) -> ApiClient:
+        """
+        Get authenticated API client.
+
+        Returns:
+            Configured API client with authentication
+
+        Raises:
+            AuthenticationError: If not authenticated
+        """
+        if not self.is_authenticated():
+            if not self.authenticate():
+                raise AuthenticationError("Failed to authenticate")
+
+        return ApiClient(self.configuration)
+
+    def get_headers(self) -> Dict[str, str]:
+        """
+        Get authentication headers for direct requests.
+
+        Returns:
+            Dictionary of headers including authorization
+        """
+        if not self.is_authenticated():
+            if not self.authenticate():
+                raise AuthenticationError("Failed to authenticate")
+
+        return {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+        }
+
+    def refresh_token(self) -> bool:
+        """
+        Refresh authentication token.
+
+        Returns:
+            True if refresh successful
+        """
+        # For now, just re-authenticate
+        # TODO: Implement proper token refresh if supported by API
+        try:
+            return self.authenticate()
+        except Exception as e:
+            logger.warning(f"Token refresh failed: {e}")
+            return False
+
+    def logout(self) -> None:
+        """
+        Logout and clear authentication tokens.
+        """
+        self.access_token = None
+        self.token_expires_at = None
+        self.configuration.access_token = None
+        logger.info("Successfully logged out")

upstream/campaigns.py

@@ -0,0 +1,223 @@
+"""
+Campaign management module for the Upstream SDK using OpenAPI client.
+
+This module handles creation, retrieval, and management of environmental
+monitoring campaigns using the generated OpenAPI client.
+"""
+
+from typing import Optional
+
+from upstream_api_client.api import CampaignsApi
+from upstream_api_client.models import (
+    CampaignCreateResponse,
+    CampaignsIn,
+    CampaignUpdate,
+)
+from upstream_api_client.models.get_campaign_response import GetCampaignResponse
+from upstream_api_client.models.list_campaigns_response_pagination import (
+    ListCampaignsResponsePagination,
+)
+from upstream_api_client.rest import ApiException
+
+from .auth import AuthManager
+from .exceptions import APIError, ValidationError
+from .utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class CampaignManager:
+    """Manages campaign operations using the OpenAPI client."""
+
+    auth_manager: AuthManager
+
+    def __init__(self, auth_manager: AuthManager) -> None:
+        """Initialize campaign manager.
+
+        Args:
+            auth_manager: Authentication manager instance
+        """
+        self.auth_manager = auth_manager
+
+    def create(self, campaign_in: CampaignsIn) -> CampaignCreateResponse:
+        """
+        Create a new campaign.
+
+        Args:
+            campaign_in: CampaignsIn model instance
+
+        Returns:
+            Created Campaign object
+
+        Raises:
+            ValidationError: If campaign_in is not a CampaignsIn
+            APIError: If API request fails
+        """
+        if not isinstance(campaign_in, CampaignsIn):
+            raise ValidationError(
+                "campaign_in must be a CampaignsIn instance", field="campaign_in"
+            )
+
+        try:
+            with self.auth_manager.get_api_client() as api_client:
+                campaigns_api = CampaignsApi(api_client)
+                response: CampaignCreateResponse = (
+                    campaigns_api.create_campaign_api_v1_campaigns_post(
+                        campaigns_in=campaign_in
+                    )
+                )
+                return response
+        except ApiException as e:
+            if e.status == 422:
+                raise ValidationError(f"Campaign validation failed: {e}")
+            else:
+                raise APIError(f"Failed to create campaign: {e}", status_code=e.status)
+        except Exception as e:
+            raise APIError(f"Failed to create campaign: {e}")
+
+    def get(self, campaign_id: str) -> GetCampaignResponse:
+        """Get campaign by ID.
+
+        Args:
+            campaign_id: Campaign ID
+
+        Returns:
+            Campaign object
+
+        Raises:
+            APIError: If API request fails or campaign not found
+        """
+        try:
+            campaign_id_int = int(campaign_id)
+
+            with self.auth_manager.get_api_client() as api_client:
+                campaigns_api = CampaignsApi(api_client)
+
+                response: GetCampaignResponse = (
+                    campaigns_api.get_campaign_api_v1_campaigns_campaign_id_get(
+                        campaign_id=campaign_id_int
+                    )
+                )
+                return response
+
+        except ValueError:
+            raise ValidationError(f"Invalid campaign ID format: {campaign_id}")
+        except ApiException as e:
+            if e.status == 404:
+                raise APIError(f"Campaign not found: {campaign_id}", status_code=404)
+            else:
+                raise APIError(f"Failed to get campaign: {e}", status_code=e.status)
+        except Exception as e:
+            raise APIError(f"Failed to get campaign: {e}")
+
+    def list(
+        self, limit: int = 50, page: int = 1, search: Optional[str] = None
+    ) -> ListCampaignsResponsePagination:
+        """List campaigns with optional filtering.
+
+        Args:
+            limit: Maximum number of campaigns to return
+            page: Page number for pagination
+            search: Search term for campaign names/descriptions
+
+        Returns:
+            List of Campaign objects
+
+        Raises:
+            APIError: If API request fails
+        """
+        try:
+            with self.auth_manager.get_api_client() as api_client:
+                campaigns_api = CampaignsApi(api_client)
+                response: ListCampaignsResponsePagination = (
+                    campaigns_api.list_campaigns_api_v1_campaigns_get(
+                        limit=limit,
+                        page=page,
+                    )
+                )
+                logger.info(f"Retrieved {response.total} campaigns")
+                return response
+
+        except ApiException as e:
+            raise APIError(f"Failed to list campaigns: {e}", status_code=e.status)
+        except Exception as e:
+            raise APIError(f"Failed to list campaigns: {e}")
+
+    def update(
+        self, campaign_id: str, campaign_update: CampaignUpdate
+    ) -> CampaignCreateResponse:
+        """
+        Update an existing campaign.
+
+        Args:
+            campaign_id: Campaign ID
+            campaign_update: CampaignUpdate model instance
+
+        Returns:
+            Updated Campaign object
+
+        Raises:
+            ValidationError: If campaign_update is not a CampaignUpdate
+            APIError: If API request fails
+        """
+        if not isinstance(campaign_update, CampaignUpdate):
+            raise ValidationError(
+                "campaign_update must be a CampaignUpdate instance",
+                field="campaign_update",
+            )
+        try:
+            campaign_id_int = int(campaign_id)
+            with self.auth_manager.get_api_client() as api_client:
+                campaigns_api = CampaignsApi(api_client)
+                response: CampaignCreateResponse = (
+                    campaigns_api.partial_update_campaign_api_v1_campaigns_campaign_id_patch(
+                        campaign_id=campaign_id_int, campaign_update=campaign_update
+                    )
+                )
+                return response
+        except ValueError:
+            raise ValidationError(f"Invalid campaign ID format: {campaign_id}")
+        except ApiException as e:
+            if e.status == 404:
+                raise APIError(f"Campaign not found: {campaign_id}", status_code=404)
+            elif e.status == 422:
+                raise ValidationError(f"Campaign validation failed: {e}")
+            else:
+                raise APIError(f"Failed to update campaign: {e}", status_code=e.status)
+        except Exception as e:
+            raise APIError(f"Failed to update campaign: {e}")
+
+    def delete(self, campaign_id: str) -> bool:
+        """Delete a campaign.
+
+        Args:
+            campaign_id: Campaign ID
+
+        Returns:
+            True if successful
+
+        Raises:
+            APIError: If API request fails
+        """
+        try:
+            campaign_id_int = int(campaign_id)
+
+            with self.auth_manager.get_api_client() as api_client:
+                campaigns_api = CampaignsApi(api_client)
+
+                campaigns_api.delete_sensor_api_v1_campaigns_campaign_id_delete(
+                    campaign_id=campaign_id_int
+                )
+
+                logger.info(f"Deleted campaign: {campaign_id}")
+                return True
+
+        except ValueError:
+            raise ValidationError(f"Invalid campaign ID format: {campaign_id}")
+        except ApiException as e:
+            if e.status == 404:
+                raise APIError(f"Campaign not found: {campaign_id}", status_code=404)
+            else:
+                raise APIError(f"Failed to delete campaign: {e}", status_code=e.status)
+        except Exception as e:
+            raise APIError(f"Failed to delete campaign: {e}")