ukfuelfinder 1.0.0__py3-none-any.whl

ukfuelfinder/__init__.py

@@ -0,0 +1,47 @@
+"""
+UK Fuel Finder Python Library
+
+Python library for accessing the UK Government Fuel Finder API.
+"""
+
+__version__ = "1.0.0"
+
+from .client import FuelFinderClient
+from .exceptions import (
+    FuelFinderError,
+    AuthenticationError,
+    InvalidCredentialsError,
+    TokenExpiredError,
+    APIError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    NetworkError,
+    TimeoutError,
+    ConnectionError,
+    ResponseParseError,
+)
+from .models import PFS, PFSInfo, FuelPrice, Address, Location
+
+__all__ = [
+    "FuelFinderClient",
+    "FuelFinderError",
+    "AuthenticationError",
+    "InvalidCredentialsError",
+    "TokenExpiredError",
+    "APIError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "NetworkError",
+    "TimeoutError",
+    "ConnectionError",
+    "ResponseParseError",
+    "PFS",
+    "PFSInfo",
+    "FuelPrice",
+    "Address",
+    "Location",
+]

ukfuelfinder/auth.py

@@ -0,0 +1,111 @@
+"""
+OAuth 2.0 authentication for UK Fuel Finder API.
+"""
+
+import time
+import threading
+from typing import Optional
+import requests
+from .exceptions import AuthenticationError, InvalidCredentialsError
+
+
+class OAuth2Authenticator:
+    """Manages OAuth 2.0 authentication and token lifecycle."""
+
+    def __init__(self, client_id: str, client_secret: str, token_url: str, refresh_url: str):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.token_url = token_url
+        self.refresh_url = refresh_url
+        self._access_token: Optional[str] = None
+        self._refresh_token: Optional[str] = None
+        self._token_expiry: float = 0
+        self._lock = threading.Lock()
+
+    def get_token(self) -> str:
+        """Get valid access token, refreshing if necessary."""
+        with self._lock:
+            if self._is_token_valid():
+                return self._access_token  # type: ignore
+
+            # Try refresh token first if available
+            if self._refresh_token:
+                try:
+                    return self._refresh_access_token()
+                except AuthenticationError:
+                    # Fall back to generating new token
+                    pass
+
+            return self._generate_token()
+
+    def _is_token_valid(self) -> bool:
+        """Check if current token is valid and not expiring soon."""
+        if not self._access_token:
+            return False
+        # Refresh 60 seconds before expiry
+        return time.time() < (self._token_expiry - 60)
+
+    def _generate_token(self) -> str:
+        """Generate new access token using client credentials."""
+        try:
+            response = requests.post(
+                self.token_url,
+                json={"client_id": self.client_id, "client_secret": self.client_secret},
+                headers={"Content-Type": "application/json"},
+                timeout=30,
+            )
+
+            if response.status_code == 401:
+                raise InvalidCredentialsError("Invalid client credentials")
+
+            response.raise_for_status()
+            data = response.json()
+
+            # Handle nested response structure
+            if "data" in data:
+                token_data = data["data"]
+            else:
+                token_data = data
+
+            self._access_token = token_data["access_token"]
+            self._refresh_token = token_data.get("refresh_token")
+            self._token_expiry = time.time() + token_data["expires_in"]
+
+            return self._access_token
+
+        except requests.RequestException as e:
+            raise AuthenticationError(f"Failed to generate access token: {e}")
+
+    def _refresh_access_token(self) -> str:
+        """Refresh access token using refresh token."""
+        if not self._refresh_token:
+            raise AuthenticationError("No refresh token available")
+
+        try:
+            response = requests.post(
+                self.refresh_url,
+                json={"client_id": self.client_id, "refresh_token": self._refresh_token},
+                headers={"Content-Type": "application/json"},
+                timeout=30,
+            )
+
+            if response.status_code in (400, 401):
+                raise AuthenticationError("Refresh token expired or invalid")
+
+            response.raise_for_status()
+            data = response.json()
+
+            # Handle nested response structure
+            if "data" in data:
+                token_data = data["data"]
+            else:
+                token_data = data
+
+            self._access_token = token_data["access_token"]
+            self._refresh_token = token_data.get("refresh_token", self._refresh_token)
+            self._token_expiry = time.time() + token_data["expires_in"]
+
+            return self._access_token
+
+        except requests.RequestException as e:
+            raise AuthenticationError(f"Failed to refresh access token: {e}")

ukfuelfinder/cache.py

@@ -0,0 +1,70 @@
+"""
+Response caching for UK Fuel Finder API client.
+"""
+
+import time
+import threading
+import hashlib
+import json
+from typing import Optional, Dict, Any
+
+
+class ResponseCache:
+    """In-memory cache with TTL support."""
+
+    def __init__(self) -> None:
+        self._cache: Dict[str, tuple[Any, float]] = {}
+        self._lock = threading.Lock()
+        self._hits = 0
+        self._misses = 0
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache if not expired."""
+        with self._lock:
+            if key in self._cache:
+                value, expiry = self._cache[key]
+                if time.time() < expiry:
+                    self._hits += 1
+                    return value
+                else:
+                    del self._cache[key]
+
+            self._misses += 1
+            return None
+
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Store value in cache with TTL in seconds."""
+        with self._lock:
+            expiry = time.time() + ttl
+            self._cache[key] = (value, expiry)
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        with self._lock:
+            self._cache.clear()
+            self._hits = 0
+            self._misses = 0
+
+    def generate_key(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> str:
+        """Generate cache key from endpoint and parameters."""
+        if params:
+            # Sort params for consistent key generation
+            sorted_params = json.dumps(params, sort_keys=True)
+            key_str = f"{endpoint}:{sorted_params}"
+        else:
+            key_str = endpoint
+
+        return hashlib.md5(key_str.encode()).hexdigest()
+
+    def get_stats(self) -> Dict[str, int]:
+        """Get cache statistics."""
+        with self._lock:
+            total = self._hits + self._misses
+            hit_rate = (self._hits / total * 100) if total > 0 else 0
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "total": total,
+                "hit_rate": round(hit_rate, 2),
+                "size": len(self._cache),
+            }

ukfuelfinder/client.py

@@ -0,0 +1,257 @@
+"""
+Main client for UK Fuel Finder API.
+"""
+
+from typing import List, Optional, Iterator, Any, Tuple
+from math import radians, cos, sin, asin, sqrt
+from .config import Config
+from .auth import OAuth2Authenticator
+from .http_client import HTTPClient
+from .cache import ResponseCache
+from .rate_limiter import RateLimiter
+from .services.price_service import PriceService
+from .services.forecourt_service import ForecourtService
+from .models import PFS, PFSInfo, FuelPrice
+
+
+class FuelFinderClient:
+    """
+    Client for accessing the UK Government Fuel Finder API.
+
+    Example:
+        >>> client = FuelFinderClient(
+        ...     client_id="your_client_id",
+        ...     client_secret="your_client_secret"
+        ... )
+        >>> prices = client.get_all_pfs_prices()
+    """
+
+    def __init__(
+        self,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        environment: str = "production",
+        cache_enabled: bool = True,
+        timeout: int = 30,
+    ):
+        """
+        Initialize Fuel Finder client.
+
+        Args:
+            client_id: OAuth client ID (reads from env if not provided)
+            client_secret: OAuth client secret (reads from env if not provided)
+            environment: "production" or "test"
+            cache_enabled: Enable response caching
+            timeout: Request timeout in seconds
+        """
+        if client_id and client_secret:
+            self.config = Config(
+                client_id=client_id,
+                client_secret=client_secret,
+                environment=environment,
+                timeout=timeout,
+                cache_enabled=cache_enabled,
+            )
+        else:
+            self.config = Config.from_env(environment)
+
+        # Initialize components
+        self.authenticator = OAuth2Authenticator(
+            client_id=self.config.client_id,
+            client_secret=self.config.client_secret,
+            token_url=self.config.token_url,
+            refresh_url=self.config.refresh_url,
+        )
+
+        self.rate_limiter = RateLimiter(
+            requests_per_minute=self.config.rate_limit_rpm,
+            daily_limit=self.config.rate_limit_daily,
+        )
+
+        self.http_client = HTTPClient(
+            base_url=self.config.base_url,
+            authenticator=self.authenticator,
+            rate_limiter=self.rate_limiter,
+            timeout=self.config.timeout,
+        )
+
+        self.cache = ResponseCache() if self.config.cache_enabled else None
+
+        # Initialize services
+        self.price_service = PriceService(self.http_client, self.cache or ResponseCache())
+        self.forecourt_service = ForecourtService(self.http_client, self.cache or ResponseCache())
+
+    # Price methods
+    def get_all_pfs_prices(
+        self,
+        batch_number: Optional[int] = None,
+        effective_start_timestamp: Optional[str] = None,
+        **kwargs: Any,
+    ) -> List[PFS]:
+        """
+        Get all PFS fuel prices.
+
+        Args:
+            batch_number: Batch number for pagination
+            effective_start_timestamp: Timestamp in YYYY-MM-DD HH:MM:SS for incremental updates
+            **kwargs: Additional parameters
+
+        Returns:
+            List of PFS with fuel prices
+        """
+        return self.price_service.get_all_pfs_prices(
+            batch_number=batch_number, effective_start_timestamp=effective_start_timestamp, **kwargs
+        )
+
+    def get_pfs(self, node_id: str) -> Optional[PFS]:
+        """
+        Get specific PFS by node ID.
+
+        Args:
+            node_id: Unique PFS identifier
+
+        Returns:
+            PFS object or None if not found
+        """
+        all_pfs = self.get_all_pfs_prices()
+        return self.price_service.get_pfs_by_node_id(node_id, all_pfs)
+
+    def get_prices_by_fuel_type(self, fuel_type: str) -> List[FuelPrice]:
+        """
+        Get all prices for a specific fuel type.
+
+        Args:
+            fuel_type: Fuel type (e.g., "unleaded", "diesel")
+
+        Returns:
+            List of fuel prices
+        """
+        all_pfs = self.get_all_pfs_prices()
+        return self.price_service.get_prices_by_fuel_type(fuel_type, all_pfs)
+
+    def get_incremental_price_updates(self, since_timestamp: str, **kwargs: Any) -> List[PFS]:
+        """
+        Get incremental price updates since a specific timestamp.
+
+        Args:
+            since_timestamp: Timestamp in YYYY-MM-DD HH:MM:SS format
+            **kwargs: Additional parameters
+
+        Returns:
+            List of PFS with updated prices
+        """
+        return self.price_service.get_incremental_updates(since_timestamp, **kwargs)
+
+    # Forecourt methods
+    def get_all_pfs_info(self, batch_number: Optional[int] = None, **kwargs: Any) -> List[PFSInfo]:
+        """
+        Get all PFS information.
+
+        Args:
+            batch_number: Batch number for pagination (500 per batch)
+            **kwargs: Additional parameters
+
+        Returns:
+            List of PFS information
+        """
+        return self.forecourt_service.get_all_pfs(batch_number=batch_number, **kwargs)
+
+    def get_incremental_pfs_info(self, since_timestamp: str, **kwargs: Any) -> List[PFSInfo]:
+        """
+        Get incremental PFS information updates.
+
+        Args:
+            since_timestamp: Timestamp in YYYY-MM-DD HH:MM:SS format
+            **kwargs: Additional parameters
+
+        Returns:
+            List of updated PFS information
+        """
+        return self.forecourt_service.get_incremental_pfs(
+            effective_start_timestamp=since_timestamp, **kwargs
+        )
+
+    def get_pfs_info(self, node_id: str) -> Optional[PFSInfo]:
+        """
+        Get specific PFS information by node ID.
+
+        Args:
+            node_id: Unique PFS identifier
+
+        Returns:
+            PFSInfo object or None if not found
+        """
+        all_pfs = self.get_all_pfs_info()
+        return self.forecourt_service.get_pfs_by_node_id(node_id, all_pfs)
+
+    def get_all_pfs_paginated(self) -> Iterator[List[PFSInfo]]:
+        """
+        Get all PFS information with automatic pagination.
+
+        Yields:
+            Lists of PFS information (up to 500 per batch)
+        """
+        return self.forecourt_service.get_all_pfs_paginated()
+
+    # Utility methods
+    def clear_cache(self) -> None:
+        """Clear all cached responses."""
+        if self.cache:
+            self.cache.clear()
+
+    def set_cache_ttl(self, resource_type: str, ttl: int) -> None:
+        """
+        Set cache TTL for a resource type.
+
+        Args:
+            resource_type: "prices" or "forecourts"
+            ttl: Time to live in seconds
+        """
+        if resource_type == "prices":
+            self.price_service.cache_ttl = ttl
+        elif resource_type == "forecourts":
+            self.forecourt_service.cache_ttl = ttl
+
+    def get_cache_stats(self) -> dict:
+        """Get cache statistics."""
+        if self.cache:
+            return self.cache.get_stats()
+        return {}
+
+    def search_by_location(
+        self, latitude: float, longitude: float, radius_km: float = 5.0
+    ) -> List[Tuple[float, PFSInfo]]:
+        """
+        Search for fuel stations near a location.
+
+        Args:
+            latitude: Search center latitude
+            longitude: Search center longitude
+            radius_km: Search radius in kilometers (default: 5.0)
+
+        Returns:
+            List of tuples (distance_km, PFSInfo) sorted by distance
+        """
+        sites = self.get_all_pfs_info()
+        nearby = []
+
+        for site in sites:
+            if site.location and site.location.latitude and site.location.longitude:
+                distance = self._haversine(
+                    longitude, latitude, site.location.longitude, site.location.latitude
+                )
+                if distance <= radius_km:
+                    nearby.append((distance, site))
+
+        nearby.sort(key=lambda x: x[0])
+        return nearby
+
+    @staticmethod
+    def _haversine(lon1: float, lat1: float, lon2: float, lat2: float) -> float:
+        """Calculate distance between two points in kilometers using Haversine formula."""
+        lon1, lat1, lon2, lat2 = map(radians, [lon1, lat1, lon2, lat2])
+        dlon = lon2 - lon1
+        dlat = lat2 - lat1
+        a = sin(dlat / 2) ** 2 + cos(lat1) * cos(lat2) * sin(dlon / 2) ** 2
+        c = 2 * asin(sqrt(a))
+        return 6371 * c

ukfuelfinder/config.py

@@ -0,0 +1,62 @@
+"""
+Configuration management for UK Fuel Finder API client.
+"""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Config:
+    """Configuration for Fuel Finder API client."""
+
+    client_id: str
+    client_secret: str
+    environment: str = "production"
+    timeout: int = 30
+    cache_enabled: bool = True
+    rate_limit_rpm: int = 120
+    rate_limit_daily: int = 10000
+
+    @property
+    def base_url(self) -> str:
+        """Get base URL for the environment."""
+        if self.environment == "test":
+            return "https://test.fuel-finder.service.gov.uk/api/v1"
+        return "https://www.fuel-finder.service.gov.uk/api/v1"
+
+    @property
+    def token_url(self) -> str:
+        """Get token URL for the environment."""
+        return f"{self.base_url}/oauth/generate_access_token"
+
+    @property
+    def refresh_url(self) -> str:
+        """Get refresh token URL for the environment."""
+        return f"{self.base_url}/oauth/regenerate_access_token"
+
+    @classmethod
+    def from_env(cls, environment: Optional[str] = None) -> "Config":
+        """Create configuration from environment variables."""
+        client_id = os.getenv("FUEL_FINDER_CLIENT_ID")
+        client_secret = os.getenv("FUEL_FINDER_CLIENT_SECRET")
+        env = environment or os.getenv("FUEL_FINDER_ENVIRONMENT", "production")
+
+        if not client_id or not client_secret:
+            raise ValueError(
+                "FUEL_FINDER_CLIENT_ID and FUEL_FINDER_CLIENT_SECRET "
+                "environment variables must be set"
+            )
+
+        # Adjust rate limits for test environment
+        rate_limit_rpm = 30 if env == "test" else 120
+        rate_limit_daily = 5000 if env == "test" else 10000
+
+        return cls(
+            client_id=client_id,
+            client_secret=client_secret,
+            environment=env,
+            rate_limit_rpm=rate_limit_rpm,
+            rate_limit_daily=rate_limit_daily,
+        )

ukfuelfinder/exceptions.py

@@ -0,0 +1,83 @@
+"""
+Exceptions for the UK Fuel Finder API client.
+"""
+
+
+class FuelFinderError(Exception):
+    """Base exception for all Fuel Finder errors."""
+
+    pass
+
+
+class AuthenticationError(FuelFinderError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class InvalidCredentialsError(AuthenticationError):
+    """Raised when client credentials are invalid."""
+
+    pass
+
+
+class TokenExpiredError(AuthenticationError):
+    """Raised when access token has expired."""
+
+    pass
+
+
+class APIError(FuelFinderError):
+    """Base exception for API-related errors."""
+
+    pass
+
+
+class NotFoundError(APIError):
+    """Raised when requested resource is not found (404)."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded (429)."""
+
+    def __init__(self, message: str, retry_after: int = 0) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    """Raised when API returns a server error (5xx)."""
+
+    pass
+
+
+class ValidationError(APIError):
+    """Raised when request validation fails (400)."""
+
+    pass
+
+
+class NetworkError(FuelFinderError):
+    """Base exception for network-related errors."""
+
+    pass
+
+
+class TimeoutError(NetworkError):
+    """Raised when a request times out."""
+
+    pass
+
+
+class ConnectionError(NetworkError):
+    """Raised when connection to API fails."""
+
+    pass
+
+
+class ResponseParseError(FuelFinderError):
+    """Raised when API response cannot be parsed."""
+
+    pass