sgu-client 0.1.0__py3-none-any.whl

sgu_client/__init__.py

@@ -0,0 +1,22 @@
+"""SGU Client - Python library for accessing SGU groundwater data."""
+
+from .config import SGUConfig
+from .exceptions import (
+    SGUAPIError,
+    SGUClientError,
+    SGUConnectionError,
+    SGUTimeoutError,
+    SGUValidationError,
+)
+from .sgu_client import SGUClient
+
+__version__ = "0.1.0"
+__all__ = [
+    "SGUAPIError",
+    "SGUClient",
+    "SGUClientError",
+    "SGUConfig",
+    "SGUConnectionError",
+    "SGUTimeoutError",
+    "SGUValidationError",
+]

sgu_client/client/__init__.py

@@ -0,0 +1,5 @@
+"""Client module for SGU API."""
+
+from .base import BaseClient
+
+__all__ = ["BaseClient"]

sgu_client/client/base.py

@@ -0,0 +1,200 @@
+"""Base HTTP client for SGU API."""
+
+import logging
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from sgu_client.config import SGUConfig
+from sgu_client.exceptions import SGUAPIError, SGUConnectionError, SGUTimeoutError
+
+logger = logging.getLogger(__name__)
+
+
+class BaseClient:
+    """Base HTTP client with common functionality for SGU API."""
+
+    def __init__(self, config: SGUConfig | None = None):
+        """Initialize the base client.
+
+        Args:
+            config: Configuration object. If None, uses default config.
+        """
+        self.config = config or SGUConfig()
+        self._session = self._create_session()
+
+        if self.config.debug:
+            logging.basicConfig(level=logging.DEBUG)
+
+    def _create_session(self) -> requests.Session:
+        """Create and configure a requests session."""
+        session = requests.Session()
+
+        # Set headers
+        session.headers.update(
+            {
+                "User-Agent": self.config.user_agent,
+                "Accept": "application/json",
+            }
+        )
+
+        # Configure retry strategy
+        retry_strategy = Retry(
+            total=self.config.max_retries,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+        )
+
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+
+        return session
+
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        base_url: str | None = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """Make an HTTP request to the SGU API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            endpoint: API endpoint path
+            params: Query parameters
+            data: Request body data
+            base_url: Optional override for base URL (for different API endpoints)
+            **kwargs: Additional arguments passed to requests
+
+        Returns:
+            JSON response data
+
+        Raises:
+            SGUConnectionError: If connection fails
+            SGUTimeoutError: If request times out
+            SGUAPIError: If API returns an error
+        """
+        url = urljoin(base_url or self.config.base_url, endpoint)
+
+        try:
+            if self.config.debug:
+                logger.debug(f"Making {method} request to {url}")
+                if params:
+                    logger.debug(f"Query params: {params}")
+                if data:
+                    logger.debug(f"Request data: {data}")
+
+            response = self._session.request(
+                method=method,
+                url=url,
+                params=params,
+                json=data,
+                timeout=self.config.timeout,
+                **kwargs,
+            )
+
+            if self.config.debug:
+                logger.debug(f"Response status: {response.status_code}")
+
+            # Check for HTTP errors
+            if not response.ok:
+                try:
+                    error_data = response.json()
+                except ValueError:
+                    error_data = {"error": response.text}
+
+                raise SGUAPIError(
+                    f"API request failed with status {response.status_code}",
+                    status_code=response.status_code,
+                    response_data=error_data,
+                )
+
+            return response.json()
+
+        except requests.exceptions.ReadTimeout as e:
+            raise SGUTimeoutError(f"Read timeout after {self.config.timeout}s") from e
+        except requests.exceptions.ConnectTimeout as e:
+            raise SGUTimeoutError(
+                f"Connection timeout after {self.config.timeout}s"
+            ) from e
+        except requests.exceptions.ConnectionError as e:
+            # Check if this is a timeout wrapped in MaxRetryError
+            if "Read timed out" in str(e) or "ReadTimeoutError" in str(e):
+                raise SGUTimeoutError(
+                    f"Read timeout after {self.config.timeout}s"
+                ) from e
+            raise SGUConnectionError(f"Connection failed: {e}") from e
+        except requests.exceptions.RequestException as e:
+            raise SGUAPIError(f"Request failed: {e}") from e
+
+    def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        base_url: str | None = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """Make a GET request.
+
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+            base_url: Optional override for base URL
+            **kwargs: Additional arguments passed to requests
+
+        Returns:
+            JSON response data
+
+        Raises:
+            SGUConnectionError: If connection fails
+            SGUTimeoutError: If request times out
+            SGUAPIError: If API returns an error
+        """
+        return self._make_request(
+            "GET", endpoint, params=params, base_url=base_url, **kwargs
+        )
+
+    def post(
+        self, endpoint: str, data: dict[str, Any] | None = None, **kwargs
+    ) -> dict[str, Any]:
+        """Make a POST request.
+
+        Args:
+            endpoint: API endpoint path
+            data: Request body data
+            **kwargs: Additional arguments passed to requests
+
+        Returns:
+            JSON response data
+
+        Raises:
+            SGUConnectionError: If connection fails
+            SGUTimeoutError: If request times out
+            SGUAPIError: If API returns an error
+        """
+        return self._make_request("POST", endpoint, data=data, **kwargs)
+
+    def __enter__(self):
+        """Context manager entry.
+
+        Returns:
+            The client instance for use in with statements
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - clean up resources.
+
+        Args:
+            exc_type: Exception type (if any)
+            exc_val: Exception value (if any)
+            exc_tb: Exception traceback (if any)
+        """
+        self._session.close()

sgu_client/client/levels/__init__.py

@@ -0,0 +1,30 @@
+"""Levels client module."""
+
+from .modeled import ModeledGroundwaterLevelClient
+from .observed import ObservedGroundwaterLevelClient
+
+
+class LevelsClient:
+    """Client for accessing groundwater level data.
+
+    Provides access to both observed and modeled groundwater levels
+    through a hierarchical API structure.
+
+    Example:
+        >>> client = SGUClient()
+        >>> stations = client.levels.observed.get_stations()
+        >>> areas = client.levels.modeled.get_areas()
+        >>> levels = client.levels.modeled.get_levels()
+    """
+
+    def __init__(self, base_client):
+        """Initialize the levels client.
+
+        Args:
+            base_client: The base HTTP client instance.
+        """
+        self.observed = ObservedGroundwaterLevelClient(base_client)
+        self.modeled = ModeledGroundwaterLevelClient(base_client)
+
+
+__all__ = ["LevelsClient"]

sgu_client/client/levels/modeled.py

@@ -0,0 +1,275 @@
+"""Modeled groundwater level client endpoints."""
+
+import logging
+from typing import Any
+
+from sgu_client.client.base import BaseClient
+from sgu_client.models.modeled import (
+    ModeledArea,
+    ModeledAreaCollection,
+    ModeledGroundwaterLevel,
+    ModeledGroundwaterLevelCollection,
+)
+
+
+class ModeledGroundwaterLevelClient:
+    """Client for modeled groundwater level-related SGU API endpoints."""
+
+    BASE_PATH = "collections"
+    MODELED_BASE_URL = "https://api.sgu.se/oppnadata/grundvattennivaer-sgu-hype-omraden/ogc/features/v1/"
+
+    def __init__(self, base_client: BaseClient):
+        """Initialize modeled groundwater level client.
+
+        Args:
+            base_client: Base HTTP client instance
+        """
+        self._client = base_client
+
+    def get_areas(
+        self,
+        bbox: list[float] | None = None,
+        limit: int | None = None,
+        filter_expr: str | None = None,
+        sortby: list[str] | None = None,
+        **kwargs: Any,
+    ) -> ModeledAreaCollection:
+        """Get modeled groundwater areas.
+
+        Args:
+            bbox: Bounding box as [min_lon, min_lat, max_lon, max_lat]
+            limit: Maximum number of features to return (1-50000, default 50000)
+            filter_expr: CQL filter expression
+            sortby: List of sort expressions (e.g., ['+omrade_id'])
+            **kwargs: Additional query parameters
+
+        Returns:
+            Typed collection of modeled groundwater areas
+        """
+        endpoint = f"{self.BASE_PATH}/omraden/items"
+        params = self._build_query_params(
+            bbox=bbox,
+            limit=limit,
+            filter=filter_expr,
+            sortby=sortby,
+            **kwargs,
+        )
+        response = self._make_request(endpoint, params)
+        return ModeledAreaCollection(**response)
+
+    def get_area(self, area_id: str) -> ModeledArea:
+        """Get a specific modeled groundwater area by ID.
+
+        Args:
+            area_id: Area identifier
+
+        Returns:
+            Typed modeled groundwater area
+
+        Raises:
+            ValueError: If area not found or multiple areas returned
+        """
+        endpoint = f"{self.BASE_PATH}/omraden/items/{area_id}"
+        response = self._make_request(endpoint, {})
+
+        # SGU API returns a FeatureCollection even for single items
+        collection = ModeledAreaCollection(**response)
+        if not collection.features:
+            raise ValueError(f"Area {area_id} not found")
+        if len(collection.features) > 1:
+            raise ValueError(f"Multiple areas returned for ID {area_id}")
+
+        return collection.features[0]
+
+    def get_levels(
+        self,
+        bbox: list[float] | None = None,
+        datetime: str | None = None,
+        limit: int | None = None,
+        filter_expr: str | None = None,
+        sortby: list[str] | None = None,
+        **kwargs: Any,
+    ) -> ModeledGroundwaterLevelCollection:
+        """Get modeled groundwater levels.
+
+        Args:
+            bbox: Bounding box as [min_lon, min_lat, max_lon, max_lat]
+            datetime: Date/time filter (RFC 3339 format or interval)
+            limit: Maximum number of features to return (1-50000, default 50000)
+            filter_expr: CQL filter expression
+            sortby: List of sort expressions (e.g., ['+datum', '-omrade_id'])
+            **kwargs: Additional query parameters
+
+        Returns:
+            Typed collection of modeled groundwater levels
+        """
+        endpoint = f"{self.BASE_PATH}/grundvattennivaer-tidigare/items"
+        params = self._build_query_params(
+            bbox=bbox,
+            datetime=datetime,
+            limit=limit,
+            filter=filter_expr,
+            sortby=sortby,
+            **kwargs,
+        )
+        response = self._make_request(endpoint, params)
+        return ModeledGroundwaterLevelCollection(**response)
+
+    def get_level(self, level_id: str) -> ModeledGroundwaterLevel:
+        """Get a specific modeled groundwater level by ID.
+
+        Args:
+            level_id: Level identifier
+
+        Returns:
+            Typed modeled groundwater level
+
+        Raises:
+            ValueError: If level not found or multiple levels returned
+        """
+        endpoint = f"{self.BASE_PATH}/grundvattennivaer-tidigare/items/{level_id}"
+        response = self._make_request(endpoint, {})
+
+        # SGU API returns a FeatureCollection even for single items
+        collection = ModeledGroundwaterLevelCollection(**response)
+        if not collection.features:
+            raise ValueError(f"Level {level_id} not found")
+        if len(collection.features) > 1:
+            raise ValueError(f"Multiple levels returned for ID {level_id}")
+
+        return collection.features[0]
+
+    def get_levels_by_area(
+        self, area_id: int, **kwargs: Any
+    ) -> ModeledGroundwaterLevelCollection:
+        """Get modeled groundwater levels for a specific area.
+
+        Args:
+            area_id: Area ID to filter by
+            **kwargs: Additional query parameters (limit, datetime, bbox, etc.)
+
+        Returns:
+            Typed collection of modeled groundwater levels for the specified area
+        """
+        filter_expr = f"omrade_id = {area_id}"
+        return self.get_levels(filter_expr=filter_expr, **kwargs)
+
+    def get_levels_by_areas(
+        self, area_ids: list[int], **kwargs: Any
+    ) -> ModeledGroundwaterLevelCollection:
+        """Get modeled groundwater levels for multiple areas.
+
+        Args:
+            area_ids: List of area IDs to filter by
+            **kwargs: Additional query parameters (limit, datetime, bbox, etc.)
+
+        Returns:
+            Typed collection of modeled groundwater levels for the specified areas
+        """
+        if not area_ids:
+            raise ValueError("At least one area ID must be provided")
+
+        # Create CQL filter expression for multiple area IDs
+        if len(area_ids) == 1:
+            filter_expr = f"omrade_id = {area_ids[0]}"
+        else:
+            area_ids_str = ", ".join(str(area_id) for area_id in area_ids)
+            filter_expr = f"omrade_id IN ({area_ids_str})"
+
+        return self.get_levels(filter_expr=filter_expr, **kwargs)
+
+    def get_levels_by_coords(
+        self,
+        lat: float,
+        lon: float,
+        buffer: float = 0.01,
+        **kwargs: Any,
+    ) -> ModeledGroundwaterLevelCollection:
+        """Get modeled groundwater levels for a specific coordinate.
+
+        This convenience function first finds relevant areas containing or near
+        the specified coordinates, then retrieves modeled levels for those areas.
+
+        Args:
+            lat: Latitude coordinate (WGS84)
+            lon: Longitude coordinate (WGS84)
+            buffer: Buffer distance in degrees around the point (default 0.01 ≈ 1km)
+            **kwargs: Additional query parameters (limit, datetime, etc.)
+
+        Returns:
+            Typed collection of modeled groundwater levels for areas near the coordinates
+
+        Raises:
+            ValueError: If no areas found near the specified coordinates
+        """
+        logger = logging.getLogger(__name__)
+
+        # Create bounding box around the point
+        bbox = [
+            lon - buffer,  # min_lon
+            lat - buffer,  # min_lat
+            lon + buffer,  # max_lon
+            lat + buffer,  # max_lat
+        ]
+
+        # Find areas within the bounding box
+        areas = self.get_areas(bbox=bbox, limit=1000)
+
+        if not areas.features:
+            raise ValueError(
+                f"No modeled groundwater areas found near coordinates "
+                f"({lat}, {lon}) within {buffer}° buffer"
+            )
+
+        # Extract area IDs
+        area_ids = [int(area.properties.omrade_id) for area in areas.features]
+
+        # Log warning if multiple areas found (near boundary)
+        if len(area_ids) > 1:
+            logger.warning(
+                f"Found {len(area_ids)} modeled areas near coordinates "
+                f"({lat}, {lon}). This suggests the point is close to an area boundary. "
+                f"Area IDs: {area_ids}. All areas will be included in the results."
+            )
+
+        # Get levels for all found areas
+        return self.get_levels_by_areas(area_ids, **kwargs)
+
+    def _build_query_params(self, **params: Any) -> dict[str, Any]:
+        """Build query parameters for API requests.
+
+        Args:
+            **params: Raw parameter values
+
+        Returns:
+            Cleaned dictionary of query parameters
+        """
+        query_params = {}
+
+        for key, value in params.items():
+            if value is None:
+                continue
+
+            if key == "bbox" and isinstance(value, list):
+                query_params[key] = ",".join(map(str, value))
+            elif key == "sortby" and isinstance(value, list):
+                query_params[key] = ",".join(value)
+            else:
+                query_params[key] = value
+
+        return query_params
+
+    def _make_request(self, endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Make HTTP request to SGU API.
+
+        Args:
+            endpoint: API endpoint path
+            params: Query parameters
+
+        Returns:
+            JSON response data
+
+        Raises:
+            Various HTTP and API exceptions via base client
+        """
+        return self._client.get(endpoint, params=params, base_url=self.MODELED_BASE_URL)