repeaterbook 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

repeaterbook/__init__.py

@@ -5,7 +5,17 @@ from __future__ import annotations
 __all__: tuple[str, ...] = (
     "Repeater",
     "RepeaterBook",
+    "RepeaterBookAPIError",
+    "RepeaterBookCacheError",
+    "RepeaterBookError",
+    "RepeaterBookValidationError",
 )
 
 from repeaterbook.database import RepeaterBook
+from repeaterbook.exceptions import (
+    RepeaterBookAPIError,
+    RepeaterBookCacheError,
+    RepeaterBookError,
+    RepeaterBookValidationError,
+)
 from repeaterbook.models import Repeater

repeaterbook/exceptions.py

@@ -0,0 +1,44 @@
+"""Custom exceptions for RepeaterBook library."""
+
+from __future__ import annotations
+
+__all__: tuple[str, ...] = (
+    "RepeaterBookAPIError",
+    "RepeaterBookCacheError",
+    "RepeaterBookError",
+    "RepeaterBookValidationError",
+)
+
+
+class RepeaterBookError(Exception):
+    """Base exception for RepeaterBook library.
+
+    All RepeaterBook-specific exceptions inherit from this class,
+    making it easy to catch all library errors with a single except clause.
+    """
+
+
+class RepeaterBookAPIError(RepeaterBookError):
+    """Error returned by the RepeaterBook API.
+
+    Raised when the API returns an error response (status: "error").
+    The error message from the API is preserved in the exception message.
+    """
+
+
+class RepeaterBookCacheError(RepeaterBookError):
+    """Error during cache operations.
+
+    Raised when reading from or writing to the cache fails,
+    such as file permission issues or disk full errors.
+    """
+
+
+class RepeaterBookValidationError(RepeaterBookError):
+    """Invalid data or response format.
+
+    Raised when:
+    - API response is not in expected format (not a dict)
+    - Required fields are missing from the response
+    - Data values fail validation (e.g., invalid coordinates)
+    """

repeaterbook/models.py

@@ -34,6 +34,7 @@ from typing import Literal, TypeAlias, TypedDict
 
 import attrs
 from pycountry.db import Country  # noqa: TC002
+from pydantic import field_validator
 from sqlmodel import Field, SQLModel
 
 
@@ -103,7 +104,6 @@ class Repeater(SQLModel, table=True):
     races: str | None
     skywarn: str | None
     canwarn: str | None
-    #' operating_mode: str
     allstar_node: str | None
     echolink_node: str | None
     irlp_node: str | None
@@ -129,6 +129,33 @@ class Repeater(SQLModel, table=True):
     notes: str | None
     last_update: date
 
+    @field_validator("latitude")
+    @classmethod
+    def validate_latitude(cls, v: Decimal) -> Decimal:
+        """Validate latitude is within valid range."""
+        if not Decimal(-90) <= v <= Decimal(90):
+            msg = f"Latitude must be between -90 and 90, got {v}"
+            raise ValueError(msg)
+        return v
+
+    @field_validator("longitude")
+    @classmethod
+    def validate_longitude(cls, v: Decimal) -> Decimal:
+        """Validate longitude is within valid range."""
+        if not Decimal(-180) <= v <= Decimal(180):
+            msg = f"Longitude must be between -180 and 180, got {v}"
+            raise ValueError(msg)
+        return v
+
+    @field_validator("frequency", "input_frequency")
+    @classmethod
+    def validate_frequency(cls, v: Decimal) -> Decimal:
+        """Validate frequency is positive."""
+        if v <= 0:
+            msg = f"Frequency must be positive, got {v}"
+            raise ValueError(msg)
+        return v
+
 
 ZeroOneJSON: TypeAlias = Literal[
     0,

repeaterbook/services.py

@@ -16,7 +16,7 @@ import hashlib
 import json
 import time
 from datetime import date, timedelta
-from typing import Any, ClassVar, Final, cast
+from typing import Any, Final, cast
 
 import aiohttp
 import attrs
@@ -25,6 +25,10 @@ from loguru import logger
 from tqdm import tqdm
 from yarl import URL
 
+from repeaterbook.exceptions import (
+    RepeaterBookAPIError,
+    RepeaterBookValidationError,
+)
 from repeaterbook.models import (
     Emergency,
     EmergencyJSON,
@@ -51,7 +55,7 @@ async def fetch_json(
     cache_dir: Path | None = None,
     max_cache_age: timedelta = timedelta(seconds=3600),
     chunk_size: int = 1024,
-) -> Any:  # noqa: ANN401
+) -> Any:  # noqa: ANN401 - json.loads() returns Any; validation done by callers
     """Fetches JSON data from the specified URL using a streaming response.
 
     - If a cached copy exists and is recent (not older than max_cache_age seconds) and
@@ -62,17 +66,19 @@ async def fetch_json(
     # Create a unique filename for caching based on the URL hash.
     if cache_dir is None:
         cache_dir = Path()
-    hashed_url = hashlib.md5(str(url).encode("utf-8")).hexdigest()  # noqa: S324
+    hashed_url = hashlib.sha256(str(url).encode("utf-8")).hexdigest()
     cache_file = cache_dir / f"api_cache_{hashed_url}.json"
+    temp_file = cache_dir / f"api_cache_{hashed_url}.tmp"
 
-    # Check if fresh cached data exists.
-    if await cache_file.exists():
-        file_age = time.time() - (await cache_file.stat()).st_mtime
+    # Check if fresh cached data exists using a single stat call.
+    try:
+        stat = await cache_file.stat()
+        file_age = time.time() - stat.st_mtime
         if file_age < max_cache_age.total_seconds():
             logger.info("Using cached data.")
             return json.loads(await cache_file.read_text(encoding="utf-8"))
-
-    await cache_file.unlink(missing_ok=True)
+    except FileNotFoundError:
+        pass  # Cache doesn't exist, continue to fetch
 
     logger.info("Fetching new data from API...")
     async with (
@@ -80,8 +86,8 @@ async def fetch_json(
         session.get(url, headers=headers) as response,
     ):
         response.raise_for_status()
-        # Open file for writing in binary mode and stream content into it.
-        async with await cache_file.open("wb") as f:
+        # Write to temp file first for atomic cache updates.
+        async with await temp_file.open("wb") as f:
             with tqdm(
                 total=response.content_length,
                 unit="B",
@@ -91,6 +97,11 @@ async def fetch_json(
                     await f.write(chunk)
                     progress.update(len(chunk))
 
+    # Atomic rename from temp file to cache file.
+    # This prevents race conditions where concurrent requests might read
+    # a partially written cache file.
+    await temp_file.rename(cache_file)
+
     # After saving the file, load and parse the JSON data.
     return json.loads(await cache_file.read_text(encoding="utf-8"))
 
@@ -209,6 +220,16 @@ class RepeaterBookAPI:
     """RepeaterBook API client.
 
     Must read https://www.repeaterbook.com/wiki/doku.php?id=api before using.
+
+    Attributes:
+        base_url: The RepeaterBook API base URL.
+        app_name: Application name for User-Agent header.
+        app_email: Contact email for User-Agent header.
+        working_dir: Directory for cache and database files.
+        max_cache_age: Maximum age of cached API responses before refresh.
+            Defaults to 1 hour.
+        max_count: Maximum expected results per API request. Used to warn
+            when response may have been trimmed. Defaults to 3500.
     """
 
     base_url: URL = attrs.Factory(lambda: URL("https://repeaterbook.com"))
@@ -217,7 +238,8 @@ class RepeaterBookAPI:
 
     working_dir: Path = attrs.Factory(Path)
 
-    MAX_COUNT: ClassVar[int] = 3500
+    max_cache_age: timedelta = timedelta(hours=1)
+    max_count: int = 3500
 
     async def cache_dir(self) -> Path:
         """Cache directory for API responses."""
@@ -246,11 +268,26 @@ class RepeaterBookAPI:
         """Rest of world (not north-america) export URL."""
         return self.url_api / "exportROW.php"
 
+    # North America countries served by export.php endpoint
+    NA_COUNTRIES: frozenset[str] = frozenset({
+        "United States",
+        "Canada",
+        "Mexico",
+    })
+
     def urls_export(
         self,
         query: ExportQuery,
     ) -> set[URL]:
-        """Generate export URLs for given query."""
+        """Generate export URLs for given query.
+
+        Smart routing logic:
+        - If NA-specific fields are used (state_id, county, emcomm, stype),
+          only query the NA endpoint
+        - If ROW-specific fields are used (region), only query the ROW endpoint
+        - If countries are specified, route based on whether they're NA or ROW
+        - If no routing hints, query both endpoints
+        """
         mode_map: dict[Mode, ModeJSON] = {
             Mode.ANALOG: "analog",
             Mode.DMR: "DMR",
@@ -268,6 +305,33 @@ class RepeaterBookAPI:
             ServiceType.GMRS: "GMRS",
         }
 
+        # Determine which endpoints to query based on the query parameters
+        has_na_specific = bool(
+            query.state_ids or query.counties or
+            query.emergency_services or query.service_types
+        )
+        has_row_specific = bool(query.regions)
+
+        # Check if countries are specified and categorize them
+        query_countries = {country.name for country in query.countries}
+        has_na_countries = bool(query_countries & self.NA_COUNTRIES)
+        has_row_countries = bool(query_countries - self.NA_COUNTRIES)
+
+        # Determine which endpoints to query
+        query_na_endpoint = True
+        query_row_endpoint = True
+
+        if has_na_specific and not has_row_specific:
+            # NA-specific fields used, only query NA
+            query_row_endpoint = False
+        elif has_row_specific and not has_na_specific:
+            # ROW-specific fields used, only query ROW
+            query_na_endpoint = False
+        elif query_countries:
+            # Countries specified - route based on country location
+            query_na_endpoint = has_na_countries
+            query_row_endpoint = has_row_countries
+
         query_na = ExportNorthAmericaQuery(
             callsign=list(query.callsigns),
             city=list(query.cities),
@@ -280,6 +344,8 @@ class RepeaterBookAPI:
             emcomm=[emergency_map[emergency] for emergency in query.emergency_services],
             stype=[type_map[service_type] for service_type in query.service_types],
         )
+        # Safe cast: dict comprehension preserves TypedDict structure, only removes
+        # empty values (which are optional in ExportNorthAmericaQuery).
         query_na = cast(
             "ExportNorthAmericaQuery", {k: v for k, v in query_na.items() if v}
         )
@@ -293,14 +359,22 @@ class RepeaterBookAPI:
             mode=[mode_map[mode] for mode in query.modes],
             region=list(query.regions),
         )
+        # Safe cast: dict comprehension preserves TypedDict structure, only removes
+        # empty values (which are optional in ExportWorldQuery).
         query_world = cast(
             "ExportWorldQuery", {k: v for k, v in query_world.items() if v}
         )
 
-        return {
-            #' self.url_export_north_america % cast("dict[str, str]", query_na),
-            self.url_export_rest_of_world % cast("dict[str, str]", query_world),
-        }
+        # Safe casts: URL % operator expects dict[str, str], and TypedDict values
+        # are all list[str] which serialize correctly for query parameters.
+        urls: set[URL] = set()
+        if query_na_endpoint:
+            na_params = cast("dict[str, str]", query_na)
+            urls.add(self.url_export_north_america % na_params)
+        if query_row_endpoint:
+            row_params = cast("dict[str, str]", query_world)
+            urls.add(self.url_export_rest_of_world % row_params)
+        return urls
 
     async def export_json(self, url: URL) -> ExportJSON:
         """Export data for given URL."""
@@ -308,20 +382,23 @@ class RepeaterBookAPI:
             url,
             headers={"User-Agent": f"{self.app_name} <{self.app_email}>"},
             cache_dir=await self.cache_dir(),
+            max_cache_age=self.max_cache_age,
         )
 
         if not isinstance(data, dict):
-            raise TypeError
+            msg = f"Expected dict response from API, got {type(data).__name__}"
+            raise RepeaterBookValidationError(msg)
 
         if data.get("status") == "error":
-            raise ValueError(data.get("message"))
+            raise RepeaterBookAPIError(data.get("message", "Unknown API error"))
 
         if "count" not in data or "results" not in data:
-            raise ValueError
+            msg = "API response missing required 'count' or 'results' field"
+            raise RepeaterBookValidationError(msg)
 
         data = cast("ExportJSON", data)
 
-        if data["count"] >= self.MAX_COUNT:
+        if data["count"] >= self.max_count:
             logger.warning(
                 "Reached max count for API response. Response may have been trimmed."
             )

{repeaterbook-0.3.0.dist-info → repeaterbook-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repeaterbook
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python utility to work with data from RepeaterBook.
 Project-URL: homepage, https://github.com/MicaelJarniac/repeaterbook
 Project-URL: source, https://github.com/MicaelJarniac/repeaterbook

repeaterbook-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+repeaterbook/__init__.py,sha256=GXcMvuiPupnrlC6YJPiPSSKWM8Kmx9ZWOqASXW-bh_0,519
+repeaterbook/database.py,sha256=oAqCKGWjD4bQk62rsHTZQO0ESzn7UDrmNg78TZVznjY,1954
+repeaterbook/exceptions.py,sha256=yUR_9Lj5PmYc5UcC1O_Om6OfNK4rk1tAiAlNDNA9LC8,1229
+repeaterbook/models.py,sha256=lQjE2Vld4GCSNaXcpsP0v0-Zo-C9N9DpeJ6nV3FVVBw,7840
+repeaterbook/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+repeaterbook/queries.py,sha256=1VgGNviH5NDCBjc4Q1rt3ORmbrzRsdL2_X_yxGc86DA,3100
+repeaterbook/services.py,sha256=_nMGOiBKGtfkoW1fhEbZnWXZ5JeTVo1GOH7yrF7JMXs,15048
+repeaterbook/utils.py,sha256=QI5aWci8b3GAIi7l3PfT51sg4TTlwzoHtamNKTGkaaI,1453
+repeaterbook-0.4.0.dist-info/METADATA,sha256=VUJco99MK9a5WI_ba17n-KdkSRyN-COXAvyZzV9n9tY,7990
+repeaterbook-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+repeaterbook-0.4.0.dist-info/licenses/LICENSE,sha256=TtbMt69RbQyifR_It2bTHKdlLR1Dj6x2A5y_oLOyoVk,1071
+repeaterbook-0.4.0.dist-info/RECORD,,

repeaterbook-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-repeaterbook/__init__.py,sha256=EGIRvLGcrzX5ZD8ZoU13XyL825rFS9zPNRS1RSQwilg,251
-repeaterbook/database.py,sha256=oAqCKGWjD4bQk62rsHTZQO0ESzn7UDrmNg78TZVznjY,1954
-repeaterbook/models.py,sha256=a3-_t6Q6h3kvbOvPiqwMFUN_ZgNMthtuUgjyXEvjv0w,6868
-repeaterbook/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-repeaterbook/queries.py,sha256=1VgGNviH5NDCBjc4Q1rt3ORmbrzRsdL2_X_yxGc86DA,3100
-repeaterbook/services.py,sha256=lb7KZxwM5pCA7tms4LTYh-I0XRG0sq-Uogd_3FCmS8U,11480
-repeaterbook/utils.py,sha256=QI5aWci8b3GAIi7l3PfT51sg4TTlwzoHtamNKTGkaaI,1453
-repeaterbook-0.3.0.dist-info/METADATA,sha256=L4hSRnqgWlWuebn2cnhuX47qZOnIFydmH46iPEqJ2LI,7990
-repeaterbook-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-repeaterbook-0.3.0.dist-info/licenses/LICENSE,sha256=TtbMt69RbQyifR_It2bTHKdlLR1Dj6x2A5y_oLOyoVk,1071
-repeaterbook-0.3.0.dist-info/RECORD,,