v0.6.0 (#54)

* Query parameter validation (#53)

* add validator functions

* fix datetime validator to support python 3.10

* Type checking coverage (#55)

* type fixes

* restructure and add typing for mypy reporting

* Mypy action (#56)

* add types action, py.typed file and updates to pyproject

* type fixes

* mypy ignores

* fix orjson import for mypy

* property tests initial (#57)

* Validation test (#58)

* add tests

* basic sync resource validation check test

* addtional locations tests

* tests

* locations parameters tests

* parameters tests

* countries and licenses tests

* instruments tests

* manufacturers test

* remove unecessary mocks and remove hypothesis test

* remove unused function paraeters in tests

* add owners tests

* providers test

* fix licenses mock

* fix license

* refactor resource tests initial

* refactor sync resource tests

* add measurements and locations latest tests

* add async resource tests

* bump version and changelog

Author: russbiggs

.github/workflows/types.yml

@@ -0,0 +1,29 @@
+name: MyPy Type Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install Hatch
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Run mypy
+        run: |
+          hatch run types:ci

.gitignore

@@ -6,4 +6,5 @@ __pycache__
 .ruff_cache
 site
 .vscode
-coverage.xml
+coverage.xml
+.hypothesis

CHANGELOG.md

@@ -4,7 +4,16 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [0.5.0] - Unreleased
+## [0.6.0] - 2025-11-26
+
+### Added
+
+- Query parameter validation
+- Additional test coverage
+- mypy typing coverage
+- `py.typed` file
+
+## [0.5.0] - 2025-10-31
 
 ### Updated
 
@@ -13,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- Additional checks to validate query parameters.
 - Additional checks to prevent out of range identifiers.
 - `TimeoutError` HTTP error exception.
 

openaq/__init__.py

@@ -2,7 +2,7 @@
 
 import logging
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 
 logger = logging.getLogger("openaq")

openaq/_async/client.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import httpx
+
+from types import TracebackType
 from typing import Any, Mapping
 
 from openaq._async.models.countries import Countries
@@ -85,9 +88,11 @@ async def _do(
         method: str,
         path: str,
         *,
-        params: Mapping[str, Any] | None = None,
-        headers: Mapping[str, str] | None = None,
-    ):
+        params: (
+            httpx.QueryParams | Mapping[str, str | int | float | bool] | None
+        ) = None,
+        headers: httpx.Headers | Mapping[str, str] | None = None,
+    ) -> httpx.Response:
         self._check_rate_limit()
         request_headers = self.build_request_headers(headers)
         url = self._base_url + path
@@ -100,16 +105,24 @@ async def _get(
         self,
         path: str,
         *,
-        params: Mapping[str, str] | None = None,
-        headers: Mapping[str, Any] | None = None,
-    ):
+        params: (
+            httpx.QueryParams | Mapping[str, str | int | float | bool] | None
+        ) = None,
+        headers: httpx.Headers | Mapping[str, str] | None = None,
+    ) -> httpx.Response:
         return await self._do("get", path, params=params, headers=headers)
 
-    async def close(self):
-        await self._transport.close()
+    async def close(self) -> None:
+        """Closes transport connection."""
+        return await self.transport.close()
 
     async def __aenter__(self) -> AsyncOpenAQ:
         return self
 
-    async def __aexit__(self, *_: Any):
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         await self.close()

openaq/_async/models/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -17,7 +19,7 @@ class AsyncResourceBase:
 
     def __init__(
         self,
-        client: "AsyncOpenAQ",
+        client: AsyncOpenAQ,
     ):
         """Initialize the SyncResourceBase.
 

openaq/_async/models/countries.py

@@ -1,7 +1,14 @@
 from openaq.shared.models import build_query_params
 from openaq.shared.responses import CountriesResponse
-from openaq.shared.utils import validate_integer_id
-
+from openaq.shared.types import SortOrder
+from openaq.shared.validators import (
+    validate_integer_id,
+    validate_integer_or_list_integer_params,
+    validate_limit_param,
+    validate_order_by,
+    validate_page_param,
+    validate_sort_order,
+)
 from .base import AsyncResourceBase
 
 
@@ -42,33 +49,25 @@ async def list(
         page: int = 1,
         limit: int = 1000,
         order_by: str | None = None,
-        sort_order: str | None = None,
-        parameters_id: int | None = None,
-        providers_id: int | None = None,
+        sort_order: SortOrder | None = None,
+        parameters_id: int | list[int] | None = None,
+        providers_id: int | list[int] | None = None,
     ) -> CountriesResponse:
         """List countries based on provided filters.
 
-        Provides the ability to filter the countries resource by the given arguments.
-
-        * `page` - Specifies the page number of results to retrieve
-        * `limit` - Sets the number of results generated per page
-        * `providers_id` - Filter results by selected providers ID(s)
-        * `parameters_id` - Filters results by selected parameters ID(s)
-        * `order_by` - Determines the fields by which results are sorted; available values are `id`
-        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)
-
         Args:
-            page: The page number. Page count is countries found / limit.
-            limit: The number of results returned per page.
+            page: The page number, must be greater than zero. Page count is countries found / limit.
+            limit: The number of results returned per page. Must be between 1 and 1,000.
             order_by: Order by operators for results.
-            sort_order: Sort order (asc/desc).
+            sort_order: Order for sorting results (asc/desc).
             parameters_id: Single parameters ID or an array of IDs.
             providers_id: Single providers ID or an array of IDs.
 
         Returns:
             CountriesResponse: An instance representing the list of retrieved countries.
 
         Raises:
+            InvalidParameterError: Client validation error, query parameter is not correct type or value.
             IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
             ApiKeyMissingError: Authentication error, missing API Key credentials.
             BadRequestError: Raised for HTTP 400 error, indicating a client request error.
@@ -84,6 +83,28 @@ async def list(
             ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
             GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
         """
+        page = validate_page_param(page)
+        limit = validate_limit_param(limit)
+        if sort_order is not None:
+            sort_order = validate_sort_order(sort_order)
+        if order_by is not None:
+            order_by = validate_order_by(order_by)
+        if parameters_id is not None:
+            parameters_id = validate_integer_or_list_integer_params(
+                'parameters_id', parameters_id
+            )
+        if providers_id is not None:
+            providers_id = validate_integer_or_list_integer_params(
+                'providers_id', providers_id
+            )
+        params = build_query_params(
+            page=page,
+            limit=limit,
+            order_by=order_by,
+            sort_order=sort_order,
+            parameters_id=parameters_id,
+            providers_id=providers_id,
+        )
         params = build_query_params(
             page=page,
             limit=limit,

openaq/_async/models/instruments.py

@@ -1,18 +1,24 @@
 from openaq.shared.models import build_query_params
 from openaq.shared.responses import InstrumentsResponse
-from openaq.shared.utils import validate_integer_id
-
+from openaq.shared.types import SortOrder
+from openaq.shared.validators import (
+    validate_integer_id,
+    validate_limit_param,
+    validate_order_by,
+    validate_page_param,
+    validate_sort_order,
+)
 from .base import AsyncResourceBase
 
 
 class Instruments(AsyncResourceBase):
     """This provides methods to retrieve instrument data from the OpenAQ API."""
 
     async def get(self, instruments_id: int) -> InstrumentsResponse:
-        """Retrieve specific instrument data by its providers ID.
+        """Retrieve specific instrument data by its instruments ID.
 
         Args:
-            instruments_id: The providers ID of the instrument to retrieve.
+            instruments_id: The instruments ID of the instrument to retrieve.
 
         Returns:
             InstrumentsResponse: An instance representing the retrieved instrument.
@@ -42,27 +48,21 @@ async def list(
         page: int = 1,
         limit: int = 1000,
         order_by: str | None = None,
-        sort_order: str | None = None,
+        sort_order: SortOrder | None = None,
     ) -> InstrumentsResponse:
         """List instruments based on provided filters.
 
-        Provides the ability to filter the instruments resource by the given arguments.
-
-        * `page` - Specifies the page number of results to retrieve.
-        * `limit` - Sets the number of results generated per page
-        * `order_by` - Determines the fields by which results are sorted; available values are `id`
-        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)
-
         Args:
-            page: The page number. Page count is instruments found / limit.
-            limit: The number of results returned per page.
+            page: The page number, must be greater than zero. Page count is instruments found / limit.
+            limit: The number of results returned per page. Must be between 1 and 1,000.
             order_by: Order by operators for results.
-            sort_order: Sort order (asc/desc).
+            sort_order: Order for sorting results (asc/desc).
 
         Returns:
             InstrumentsResponse: An instance representing the list of retrieved instruments.
 
         Raises:
+            InvalidParameterError: Client validation error, query parameter is not correct type or value.
             IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
             ApiKeyMissingError: Authentication error, missing API Key credentials.
             BadRequestError: Raised for HTTP 400 error, indicating a client request error.
@@ -78,6 +78,12 @@ async def list(
             ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
             GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
         """
+        page = validate_page_param(page)
+        limit = validate_limit_param(limit)
+        if sort_order is not None:
+            sort_order = validate_sort_order(sort_order)
+        if order_by is not None:
+            order_by = validate_order_by(order_by)
         params = build_query_params(
             page=page, limit=limit, order_by=order_by, sort_order=sort_order
         )

openaq/_async/models/licenses.py

@@ -1,7 +1,13 @@
 from openaq.shared.models import build_query_params
 from openaq.shared.responses import LicensesResponse
-from openaq.shared.utils import validate_integer_id
-
+from openaq.shared.types import SortOrder
+from openaq.shared.validators import (
+    validate_integer_id,
+    validate_limit_param,
+    validate_order_by,
+    validate_page_param,
+    validate_sort_order,
+)
 from .base import AsyncResourceBase
 
 
@@ -42,27 +48,21 @@ async def list(
         page: int = 1,
         limit: int = 1000,
         order_by: str | None = None,
-        sort_order: str | None = None,
+        sort_order: SortOrder | None = None,
     ) -> LicensesResponse:
         """List licenses based on provided filters.
 
-        Provides the ability to filter the locations resource by the given arguments.
-
-        * `page` - Specifies the page number of results to retrieve
-        * `limit` - Sets the number of results generated per page
-        * `order_by` - Determines the fields by which results are sorted; available values are `id`
-        * `sort_order` - Works in tandem with `order_by` to specify the direction: either `asc` (ascending) or `desc` (descending)
-
         Args:
-            page: The page number. Page count is locations found / limit.
-            limit: The number of results returned per page.
+            page: The page number, must be greater than zero. Page count is licenses found / limit.
+            limit: The number of results returned per page. Must be between 1 and 1,000.
             order_by: Order by operators for results.
-            sort_order: Sort order (asc/desc).
+            sort_order: Order for sorting results (asc/desc).
 
         Returns:
             LicensesReponse: An instance representing the list of retrieved licenses.
 
         Raises:
+            InvalidParameterError: Client validation error, query parameter is not correct type or value.
             IdentifierOutOfBoundsError: Client validation error, identifier outside support int32 range.
             ApiKeyMissingError: Authentication error, missing API Key credentials.
             BadRequestError: Raised for HTTP 400 error, indicating a client request error.
@@ -78,6 +78,12 @@ async def list(
             ServiceUnavailableError: Raised for HTTP 503, indicating that the server is not ready to handle the request.
             GatewayTimeoutError: Raised for HTTP 504 error, indicating a gateway timeout.
         """
+        page = validate_page_param(page)
+        limit = validate_limit_param(limit)
+        if sort_order is not None:
+            sort_order = validate_sort_order(sort_order)
+        if order_by is not None:
+            order_by = validate_order_by(order_by)
         params = build_query_params(
             page=page,
             limit=limit,