Skip to content

Commit 4bfd88a

Browse files
Pijukatelclaude
andauthored
refactor: type query parameters with a shared QueryParams alias (#1164)
- Adds `QueryParamValue` and `QueryParams` to `apify_client.types` and uses them for every `params` input in the client (`HttpClient.call`, `_build_params`, default params, wait and batch helpers), generalizing the inline type from #1153. - The union is exactly what the client converts or sends unchanged (`str`, `int`, `float`, `bool`, `Decimal`, `datetime`, `list[str]`, `None`); a list of non-strings raised `TypeError`, and a `timedelta`, tuple, enum or dict was sent as its repr, so both are now type errors. - Custom HTTP clients overriding `call` with `params: dict[str, Any] | None` should accept `QueryParams | None`; runtime behavior is unchanged. Co-authored-by: Claude <noreply@anthropic.com>
1 parent 8b71800 commit 4bfd88a

5 files changed

Lines changed: 41 additions & 24 deletions

File tree

‎src/apify_client/_resource_clients/_resource_client.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
if TYPE_CHECKING:
1919
from apify_client._client_registry import ClientRegistry, ClientRegistryAsync
2020
from apify_client.http_clients import HttpClient, HttpClientAsync
21-
from apify_client.types import Timeout
21+
from apify_client.types import QueryParams, QueryParamValue, Timeout
2222

2323
_TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED']
2424
"""Subset of `ActorJobStatus` values that indicate the job has finished and will not change again."""
@@ -41,7 +41,7 @@ def __init__(
4141
resource_path: str,
4242
client_registry: Any,
4343
resource_id: str | None = None,
44-
params: dict | None = None,
44+
params: QueryParams | None = None,
4545
api_base_url: str | None = None,
4646
) -> None:
4747
"""Initialize the resource client.
@@ -63,7 +63,7 @@ def __init__(
6363
self._api_base_url = api_base_url or base_url
6464
self._public_base_url = public_base_url
6565
self._http_client = http_client
66-
self._default_params = params or {}
66+
self._default_params = dict(params) if params else {}
6767
self._resource_path = resource_path
6868
self._resource_id = resource_id
6969
self._client_registry = client_registry
@@ -120,7 +120,7 @@ def _build_url(
120120

121121
return url
122122

123-
def _build_public_url(self, path: str, params: dict[str, Any]) -> str:
123+
def _build_public_url(self, path: str, params: QueryParams) -> str:
124124
"""Build a public resource URL with API-normalized query params.
125125
126126
Normalizes `params` the same way the HTTP request path does (bool -> true/false, list -> comma-joined,
@@ -139,7 +139,7 @@ def _build_public_url(self, path: str, params: dict[str, Any]) -> str:
139139
public_url = public_url._replace(query=urlencode(filtered_params))
140140
return urlunparse(public_url)
141141

142-
def _build_params(self, **kwargs: Any) -> dict:
142+
def _build_params(self, **kwargs: QueryParamValue) -> dict[str, QueryParamValue]:
143143
"""Merge default params with method params, filtering out None values.
144144
145145
Args:
@@ -200,7 +200,7 @@ def __init__(
200200
resource_path: str,
201201
client_registry: ClientRegistry,
202202
resource_id: str | None = None,
203-
params: dict | None = None,
203+
params: QueryParams | None = None,
204204
api_base_url: str | None = None,
205205
) -> None:
206206
"""Initialize the resource client.
@@ -313,7 +313,7 @@ def _wait_for_finish(
313313
self,
314314
*,
315315
url: str,
316-
params: dict,
316+
params: QueryParams,
317317
timeout: Timeout,
318318
wait_duration: timedelta | None = None,
319319
) -> dict | None:
@@ -395,7 +395,7 @@ def __init__(
395395
resource_path: str,
396396
client_registry: ClientRegistryAsync,
397397
resource_id: str | None = None,
398-
params: dict | None = None,
398+
params: QueryParams | None = None,
399399
api_base_url: str | None = None,
400400
) -> None:
401401
"""Initialize the resource client.
@@ -508,7 +508,7 @@ async def _wait_for_finish(
508508
self,
509509
*,
510510
url: str,
511-
params: dict,
511+
params: QueryParams,
512512
timeout: Timeout,
513513
wait_duration: timedelta | None = None,
514514
) -> dict | None:

‎src/apify_client/_resource_clients/request_queue.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
RequestWithoutIdCamelDict,
5757
RequestWithoutIdDict,
5858
)
59-
from apify_client.types import Timeout
59+
from apify_client.types import QueryParams, Timeout
6060

6161
_RQ_MAX_REQUESTS_PER_BATCH = 25
6262
"""Maximum number of requests the API accepts in a single batch call."""
@@ -946,7 +946,7 @@ async def _batch_add_requests_worker(
946946
self,
947947
*,
948948
queue: asyncio.Queue[Iterable[bytes]],
949-
request_params: dict,
949+
request_params: QueryParams,
950950
timeout: Timeout,
951951
) -> BatchAddResponse:
952952
"""Worker function to process a batch of requests.

‎src/apify_client/http_clients/_base.py‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
from typing import Self
4444

4545
from apify_client.http_compressors._base import HttpCompressor
46-
from apify_client.types import JsonSerializable, StreamedBodySource, Timeout
46+
from apify_client.types import JsonSerializable, QueryParams, StreamedBodySource, Timeout
4747

4848
logger = logging.getLogger(logger_name)
4949
logger_once = LoggerOnce(logger)
@@ -227,7 +227,7 @@ def _get_header(headers: dict[str, str], name: str) -> str | None:
227227
return next((value for key, value in headers.items() if key.lower() == name.lower()), None)
228228

229229
@staticmethod
230-
def _parse_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
230+
def _parse_params(params: QueryParams | None) -> dict[str, Any] | None:
231231
"""Convert request parameters to Apify API-compatible formats.
232232
233233
Converts booleans to 'false'/'true', lists to comma-separated strings, datetimes to ISO 8601 Zulu format.
@@ -309,7 +309,7 @@ def _prepare_request_call(
309309
self,
310310
*,
311311
headers: dict[str, str] | None = None,
312-
params: dict[str, Any] | None = None,
312+
params: QueryParams | None = None,
313313
data: str | bytes | bytearray | StreamedBodySource | None = None,
314314
json: JsonSerializable | None = None,
315315
) -> tuple[dict[str, str], dict[str, Any] | None, bytes | StreamedRequestBody | None]:
@@ -504,7 +504,7 @@ def call(
504504
method: str,
505505
url: str,
506506
headers: dict[str, str] | None = None,
507-
params: dict[str, Any] | None = None,
507+
params: QueryParams | None = None,
508508
data: str | bytes | bytearray | StreamedBodySource | None = None,
509509
json: JsonSerializable | None = None,
510510
stream: bool | None = None,
@@ -516,7 +516,8 @@ def call(
516516
method: HTTP method (GET, POST, PUT, DELETE, etc.).
517517
url: Full URL to make the request to.
518518
headers: Additional headers to include.
519-
params: Query parameters to append to the URL.
519+
params: Query parameters to append to the URL. See `QueryParamValue` for how each value is converted
520+
before it is sent.
520521
data: Raw request body. An `io.IOBase` stream such as an open file, an iterable of byte chunks, or a
521522
streamed `HttpResponse` is sent in chunks as it is read, and any other object with a callable `read`
522523
is read whole, see `StreamedRequestBody`. Streaming is experimental, and its behavior may change in
@@ -715,7 +716,7 @@ async def call(
715716
method: str,
716717
url: str,
717718
headers: dict[str, str] | None = None,
718-
params: dict[str, Any] | None = None,
719+
params: QueryParams | None = None,
719720
data: str | bytes | bytearray | StreamedBodySource | None = None,
720721
json: JsonSerializable | None = None,
721722
stream: bool | None = None,
@@ -727,7 +728,8 @@ async def call(
727728
method: HTTP method (GET, POST, PUT, DELETE, etc.).
728729
url: Full URL to make the request to.
729730
headers: Additional headers to include.
730-
params: Query parameters to append to the URL.
731+
params: Query parameters to append to the URL. See `QueryParamValue` for how each value is converted
732+
before it is sent.
731733
data: Raw request body. An `io.IOBase` stream such as an open file, an iterable of byte chunks, or a
732734
streamed `HttpResponse` is sent in chunks as it is read, and any other object with a callable `read`
733735
is read whole, see `StreamedRequestBody`. Streaming is experimental, and its behavior may change in

‎src/apify_client/types.py‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
from __future__ import annotations
22

33
from collections.abc import AsyncIterable, Iterable, Mapping, Sequence
4-
from datetime import timedelta
4+
from datetime import datetime, timedelta
5+
from decimal import Decimal
56
from typing import IO, TYPE_CHECKING, Literal, Protocol
67

78
from apify_client._models import CreateWebhookRequest, WebhookRepresentation
@@ -19,6 +20,18 @@
1920
HttpCompressionAlgorithm = Literal['brotli', 'gzip']
2021
"""Accepted string literals for the `compression` parameter on `ApifyClient` and `ApifyClientAsync`."""
2122

23+
QueryParamValue = str | int | float | bool | Decimal | datetime | list[str] | None
24+
"""Type of one query parameter value accepted by the client.
25+
26+
The HTTP client converts a value before sending it: a `bool` becomes `true` or `false`, a `list[str]` becomes one
27+
comma-separated value, a `datetime` becomes an ISO 8601 string in UTC (a naive one is treated as UTC), and a `None`
28+
value is left out. Any other value is sent as its `str()`. Only a `list` is joined, so pass a `list`, not a tuple
29+
or another sequence.
30+
"""
31+
32+
QueryParams = Mapping[str, QueryParamValue]
33+
"""Type for the `params` parameter on `HttpClient.call` and `HttpClientAsync.call`: query parameters of the request."""
34+
2235
Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long']
2336
"""Type for the `timeout` parameter on resource client methods.
2437
@@ -91,6 +104,8 @@ def read(self) -> bytes | str | Awaitable[bytes | str]:
91104
__all__ = [
92105
'HttpCompressionAlgorithm',
93106
'JsonSerializable',
107+
'QueryParamValue',
108+
'QueryParams',
94109
'StreamedBodySource',
95110
'SupportsRead',
96111
'Timeout',

‎tests/unit/test_pluggable_http_client.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535

3636
from pytest_httpserver import HTTPServer
3737

38-
from apify_client.types import StreamedBodySource, Timeout
38+
from apify_client.types import QueryParams, StreamedBodySource, Timeout
3939

4040

4141
@dataclass
@@ -94,7 +94,7 @@ def call(
9494
method: str,
9595
url: str,
9696
headers: dict[str, str] | None = None,
97-
params: dict[str, Any] | None = None,
97+
params: QueryParams | None = None,
9898
data: str | bytes | bytearray | StreamedBodySource | None = None,
9999
json: Any = None,
100100
stream: bool | None = None,
@@ -128,7 +128,7 @@ async def call(
128128
method: str,
129129
url: str,
130130
headers: dict[str, str] | None = None,
131-
params: dict[str, Any] | None = None,
131+
params: QueryParams | None = None,
132132
data: str | bytes | bytearray | StreamedBodySource | None = None,
133133
json: Any = None,
134134
stream: bool | None = None,
@@ -550,7 +550,7 @@ def call(
550550
method: str,
551551
url: str,
552552
headers: dict[str, str] | None = None,
553-
params: dict[str, Any] | None = None,
553+
params: QueryParams | None = None,
554554
data: str | bytes | bytearray | StreamedBodySource | None = None,
555555
json: Any = None,
556556
**_kwargs: Any,
@@ -575,7 +575,7 @@ async def call(
575575
method: str,
576576
url: str,
577577
headers: dict[str, str] | None = None,
578-
params: dict[str, Any] | None = None,
578+
params: QueryParams | None = None,
579579
data: str | bytes | bytearray | StreamedBodySource | None = None,
580580
json: Any = None,
581581
**_kwargs: Any,

0 commit comments

Comments
 (0)