ukfuelfinder 1.0.0__py3-none-any.whl

ukfuelfinder/http_client.py

@@ -0,0 +1,116 @@
+"""
+HTTP client for UK Fuel Finder API.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+import requests
+from .auth import OAuth2Authenticator
+from .rate_limiter import RateLimiter
+from .exceptions import (
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    TimeoutError as FuelFinderTimeoutError,
+    ConnectionError as FuelFinderConnectionError,
+    ResponseParseError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPClient:
+    """HTTP client with authentication and error handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+        authenticator: OAuth2Authenticator,
+        rate_limiter: RateLimiter,
+        timeout: int = 30,
+    ):
+        self.base_url = base_url
+        self.authenticator = authenticator
+        self.rate_limiter = rate_limiter
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """Make GET request to API."""
+        return self._make_request("GET", endpoint, params=params)
+
+    def _make_request(
+        self, method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, retries: int = 3
+    ) -> Any:
+        """Make HTTP request with retries and error handling."""
+        url = f"{self.base_url}{endpoint}"
+
+        for attempt in range(retries):
+            try:
+                # Acquire rate limit permission
+                self.rate_limiter.acquire()
+
+                # Get valid token
+                token = self.authenticator.get_token()
+
+                # Make request
+                headers = {"Authorization": f"Bearer {token}"}
+                logger.debug(f"{method} {url} params={params}")
+
+                response = self.session.request(
+                    method, url, headers=headers, params=params, timeout=self.timeout
+                )
+
+                return self._handle_response(response)
+
+            except RateLimitError as e:
+                if attempt < retries - 1:
+                    self.rate_limiter.handle_rate_limit_error(e.retry_after)
+                    continue
+                raise
+
+            except requests.Timeout:
+                if attempt < retries - 1:
+                    continue
+                raise FuelFinderTimeoutError(f"Request to {url} timed out")
+
+            except requests.ConnectionError as e:
+                if attempt < retries - 1:
+                    continue
+                raise FuelFinderConnectionError(f"Connection to {url} failed: {e}")
+
+        raise ServerError("Max retries exceeded")
+
+    def _handle_response(self, response: requests.Response) -> Any:
+        """Handle HTTP response and errors."""
+        logger.debug(f"Response: {response.status_code} in {response.elapsed.total_seconds():.2f}s")
+
+        if response.status_code == 200:
+            try:
+                data = response.json()
+                # Handle nested response structure with "data" wrapper
+                if isinstance(data, dict) and "data" in data:
+                    return data["data"]
+                return data
+            except ValueError as e:
+                raise ResponseParseError(f"Failed to parse JSON response: {e}")
+
+        elif response.status_code == 400:
+            raise ValidationError(f"Invalid request: {response.text}")
+
+        elif response.status_code == 401:
+            raise ValidationError("Unauthorized - token may be invalid")
+
+        elif response.status_code == 404:
+            raise NotFoundError(f"Resource not found: {response.url}")
+
+        elif response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 0))
+            raise RateLimitError("Rate limit exceeded", retry_after=retry_after)
+
+        elif response.status_code >= 500:
+            raise ServerError(f"Server error: {response.status_code} - {response.text}")
+
+        else:
+            raise ServerError(f"Unexpected status code: {response.status_code}")

ukfuelfinder/models.py

@@ -0,0 +1,154 @@
+"""
+Data models for UK Fuel Finder API responses.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+from dateutil import parser
+
+
+@dataclass
+class FuelPrice:
+    """Fuel price information."""
+
+    fuel_type: str
+    price: Optional[float]  # Can be null
+    price_last_updated: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FuelPrice":
+        """Create FuelPrice from API response dictionary."""
+        price = None
+        if data.get("price"):
+            # Price comes as string like "0120.0000"
+            price = float(data["price"])
+
+        price_last_updated = None
+        if data.get("price_last_updated"):
+            price_last_updated = parser.parse(data["price_last_updated"])
+
+        return cls(
+            fuel_type=data["fuel_type"],
+            price=price,
+            price_last_updated=price_last_updated,
+        )
+
+
+@dataclass
+class PFS:
+    """Petrol Filling Station with fuel prices."""
+
+    node_id: str
+    mft_organisation_name: str
+    trading_name: str
+    public_phone_number: Optional[str]
+    fuel_prices: List[FuelPrice]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PFS":
+        """Create PFS from API response dictionary."""
+        fuel_prices = [FuelPrice.from_dict(fp) for fp in data.get("fuel_prices", [])]
+        return cls(
+            node_id=data["node_id"],
+            mft_organisation_name=data["mft_organisation_name"],
+            trading_name=data["trading_name"],
+            public_phone_number=data.get("public_phone_number"),
+            fuel_prices=fuel_prices,
+        )
+
+
+@dataclass
+class Address:
+    """Station address information."""
+
+    address_line_1: str
+    address_line_2: Optional[str]
+    city: str
+    country: str
+    county: Optional[str]
+    postcode: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Address":
+        """Create Address from API response dictionary."""
+        return cls(
+            address_line_1=data["address_line_1"],
+            address_line_2=data.get("address_line_2"),
+            city=data["city"],
+            country=data["country"],
+            county=data.get("county"),
+            postcode=data["postcode"],
+        )
+
+
+@dataclass
+class Location:
+    """Geographic coordinates."""
+
+    latitude: float
+    longitude: float
+    address_line_1: Optional[str] = None
+    address_line_2: Optional[str] = None
+    city: Optional[str] = None
+    country: Optional[str] = None
+    county: Optional[str] = None
+    postcode: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Location":
+        """Create Location from API response dictionary."""
+        return cls(
+            latitude=float(data["latitude"]),
+            longitude=float(data["longitude"]),
+            address_line_1=data.get("address_line_1"),
+            address_line_2=data.get("address_line_2"),
+            city=data.get("city"),
+            country=data.get("country"),
+            county=data.get("county"),
+            postcode=data.get("postcode"),
+        )
+
+
+@dataclass
+class PFSInfo:
+    """Petrol Filling Station information (without prices)."""
+
+    node_id: str
+    mft_organisation_name: str
+    trading_name: str
+    public_phone_number: Optional[str]
+    is_same_trading_and_brand_name: Optional[bool] = None
+    brand_name: Optional[str] = None
+    temporary_closure: Optional[bool] = None
+    permanent_closure: Optional[bool] = None
+    permanent_closure_date: Optional[str] = None
+    is_motorway_service_station: Optional[bool] = None
+    is_supermarket_service_station: Optional[bool] = None
+    location: Optional[Location] = None
+    amenities: Optional[List[str]] = None
+    opening_times: Optional[Dict[str, Any]] = None
+    fuel_types: Optional[List[str]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PFSInfo":
+        """Create PFSInfo from API response dictionary."""
+        location = Location.from_dict(data["location"]) if "location" in data else None
+
+        return cls(
+            node_id=data["node_id"],
+            mft_organisation_name=data["mft_organisation_name"],
+            trading_name=data["trading_name"],
+            public_phone_number=data.get("public_phone_number"),
+            is_same_trading_and_brand_name=data.get("is_same_trading_and_brand_name"),
+            brand_name=data.get("brand_name"),
+            temporary_closure=data.get("temporary_closure"),
+            permanent_closure=data.get("permanent_closure"),
+            permanent_closure_date=data.get("permanent_closure_date"),
+            is_motorway_service_station=data.get("is_motorway_service_station"),
+            is_supermarket_service_station=data.get("is_supermarket_service_station"),
+            location=location,
+            amenities=data.get("amenities"),
+            opening_times=data.get("opening_times"),
+            fuel_types=data.get("fuel_types"),
+        )

ukfuelfinder/rate_limiter.py

@@ -0,0 +1,72 @@
+"""
+Rate limiting for UK Fuel Finder API client.
+"""
+
+import time
+import threading
+from collections import deque
+from typing import Deque
+from .exceptions import RateLimitError
+
+
+class RateLimiter:
+    """Rate limiter with sliding window and exponential backoff."""
+
+    def __init__(self, requests_per_minute: int, daily_limit: int):
+        self.requests_per_minute = requests_per_minute
+        self.daily_limit = daily_limit
+        self._minute_window: Deque[float] = deque()
+        self._daily_count = 0
+        self._daily_reset = time.time() + 86400  # 24 hours
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        """Acquire permission to make a request, blocking if necessary."""
+        with self._lock:
+            self._reset_daily_if_needed()
+            self._wait_if_needed()
+            self._record_request()
+
+    def _reset_daily_if_needed(self) -> None:
+        """Reset daily counter if 24 hours have passed."""
+        if time.time() >= self._daily_reset:
+            self._daily_count = 0
+            self._daily_reset = time.time() + 86400
+
+    def _wait_if_needed(self) -> None:
+        """Wait if rate limits would be exceeded."""
+        now = time.time()
+
+        # Remove requests older than 1 minute
+        while self._minute_window and self._minute_window[0] < now - 60:
+            self._minute_window.popleft()
+
+        # Check daily limit
+        if self._daily_count >= self.daily_limit:
+            wait_time = self._daily_reset - now
+            raise RateLimitError(
+                f"Daily limit of {self.daily_limit} requests exceeded. "
+                f"Resets in {int(wait_time)} seconds",
+                retry_after=int(wait_time),
+            )
+
+        # Check per-minute limit
+        if len(self._minute_window) >= self.requests_per_minute:
+            oldest = self._minute_window[0]
+            wait_time = 60 - (now - oldest)
+            if wait_time > 0:
+                time.sleep(wait_time)
+
+    def _record_request(self) -> None:
+        """Record a request in the sliding window."""
+        now = time.time()
+        self._minute_window.append(now)
+        self._daily_count += 1
+
+    def handle_rate_limit_error(self, retry_after: int) -> None:
+        """Handle 429 rate limit error with exponential backoff."""
+        if retry_after > 0:
+            time.sleep(retry_after)
+        else:
+            # Default exponential backoff
+            time.sleep(1)

ukfuelfinder/services/__init__.py

@@ -0,0 +1 @@
+"""Services for UK Fuel Finder API."""

ukfuelfinder/services/forecourt_service.py

@@ -0,0 +1,108 @@
+"""
+Forecourt service for UK Fuel Finder API.
+"""
+
+from typing import List, Optional, Dict, Any, Iterator
+from ..http_client import HTTPClient
+from ..cache import ResponseCache
+from ..models import PFSInfo
+
+
+class ForecourtService:
+    """Service for forecourt/PFS information operations."""
+
+    def __init__(self, http_client: HTTPClient, cache: ResponseCache):
+        self.http_client = http_client
+        self.cache = cache
+        self.cache_ttl = 3600  # 1 hour for forecourt info
+
+    def get_all_pfs(
+        self, batch_number: Optional[int] = None, use_cache: bool = True
+    ) -> List[PFSInfo]:
+        """
+        Get all PFS information.
+
+        Args:
+            batch_number: Batch number for pagination (500 per batch)
+            use_cache: Whether to use cached response
+
+        Returns:
+            List of PFS information
+        """
+        params: Dict[str, Any] = {}
+        if batch_number:
+            params["batch-number"] = batch_number
+
+        cache_key = self.cache.generate_key("/pfs", params)
+
+        if use_cache:
+            cached = self.cache.get(cache_key)
+            if cached is not None:
+                return [PFSInfo.from_dict(item) for item in cached]
+
+        response = self.http_client.get("/pfs", params=params)
+        self.cache.set(cache_key, response, self.cache_ttl)
+
+        return [PFSInfo.from_dict(item) for item in response]
+
+    def get_incremental_pfs(
+        self,
+        effective_start_timestamp: str,
+        batch_number: Optional[int] = None,
+        use_cache: bool = True,
+    ) -> List[PFSInfo]:
+        """
+        Get incremental PFS information updates.
+
+        Args:
+            effective_start_timestamp: Timestamp in YYYY-MM-DD HH:MM:SS format
+            batch_number: Batch number for pagination
+            use_cache: Whether to use cached response
+
+        Returns:
+            List of updated PFS information
+        """
+        params: Dict[str, Any] = {"effective-start-timestamp": effective_start_timestamp}
+        if batch_number:
+            params["batch-number"] = batch_number
+
+        cache_key = self.cache.generate_key("/pfs", params)
+
+        if use_cache:
+            cached = self.cache.get(cache_key)
+            if cached is not None:
+                return [PFSInfo.from_dict(item) for item in cached]
+
+        response = self.http_client.get("/pfs", params=params)
+        self.cache.set(cache_key, response, self.cache_ttl)
+
+        return [PFSInfo.from_dict(item) for item in response]
+
+    def get_pfs_by_node_id(self, node_id: str, pfs_list: List[PFSInfo]) -> Optional[PFSInfo]:
+        """Get specific PFS by node ID from a list."""
+        for pfs in pfs_list:
+            if pfs.node_id == node_id:
+                return pfs
+        return None
+
+    def get_all_pfs_paginated(self, use_cache: bool = True) -> Iterator[List[PFSInfo]]:
+        """
+        Get all PFS information with automatic pagination.
+
+        Yields batches of up to 500 PFS records until no more data is available.
+
+        Args:
+            use_cache: Whether to use cached responses
+
+        Yields:
+            Lists of PFS information (up to 500 per batch)
+        """
+        batch = 1
+        while True:
+            pfs_list = self.get_all_pfs(batch_number=batch, use_cache=use_cache)
+            if not pfs_list:
+                break
+            yield pfs_list
+            if len(pfs_list) < 500:
+                break
+            batch += 1

ukfuelfinder/services/price_service.py

@@ -0,0 +1,72 @@
+"""
+Price service for UK Fuel Finder API.
+"""
+
+from typing import List, Optional, Dict, Any
+from ..http_client import HTTPClient
+from ..cache import ResponseCache
+from ..models import PFS, FuelPrice
+
+
+class PriceService:
+    """Service for fuel price operations."""
+
+    def __init__(self, http_client: HTTPClient, cache: ResponseCache):
+        self.http_client = http_client
+        self.cache = cache
+        self.cache_ttl = 900  # 15 minutes for prices
+
+    def get_all_pfs_prices(
+        self,
+        batch_number: Optional[int] = None,
+        effective_start_timestamp: Optional[str] = None,
+        use_cache: bool = True,
+    ) -> 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 format for incremental updates
+            use_cache: Whether to use cached response
+
+        Returns:
+            List of PFS with fuel prices
+        """
+        params: Dict[str, Any] = {}
+        if batch_number:
+            params["batch-number"] = batch_number
+        if effective_start_timestamp:
+            params["effective-start-timestamp"] = effective_start_timestamp
+
+        cache_key = self.cache.generate_key("/pfs/fuel-prices", params)
+
+        if use_cache:
+            cached = self.cache.get(cache_key)
+            if cached is not None:
+                return [PFS.from_dict(item) for item in cached]
+
+        response = self.http_client.get("/pfs/fuel-prices", params=params)
+        self.cache.set(cache_key, response, self.cache_ttl)
+
+        return [PFS.from_dict(item) for item in response]
+
+    def get_pfs_by_node_id(self, node_id: str, pfs_list: List[PFS]) -> Optional[PFS]:
+        """Get specific PFS by node ID from a list."""
+        for pfs in pfs_list:
+            if pfs.node_id == node_id:
+                return pfs
+        return None
+
+    def get_prices_by_fuel_type(self, fuel_type: str, pfs_list: List[PFS]) -> List[FuelPrice]:
+        """Get all prices for a specific fuel type."""
+        prices = []
+        for pfs in pfs_list:
+            for price in pfs.fuel_prices:
+                if price.fuel_type == fuel_type:
+                    prices.append(price)
+        return prices
+
+    def get_incremental_updates(self, since_timestamp: str, **kwargs: Any) -> List[PFS]:
+        """Get incremental price updates since a specific timestamp."""
+        return self.get_all_pfs_prices(effective_start_timestamp=since_timestamp, **kwargs)