Skip to content

Commit 21c2e53

Browse files
committed
Merge remote-tracking branch 'origin/master' into iterable-list-methods-2
2 parents 2d123f3 + 3a74e1f commit 21c2e53

25 files changed

Lines changed: 299 additions & 127 deletions

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,15 @@ All notable changes to this project will be documented in this file.
2323
- Treat naive datetime query params as UTC ([#752](https://github.com/apify/apify-client-python/pull/752)) ([9ab096a](https://github.com/apify/apify-client-python/commit/9ab096a7453080a3079c7459079f99a30bd6a7cb)) by [@vdusek](https://github.com/vdusek)
2424
- Raise NotFoundError on ambiguous 404 responses ([#755](https://github.com/apify/apify-client-python/pull/755)) ([701185e](https://github.com/apify/apify-client-python/commit/701185e6e8a98f0b14d83cab10139f1e19be3f47)) by [@vdusek](https://github.com/vdusek)
2525
- Correct deadline logic in _wait_for_finish ([#749](https://github.com/apify/apify-client-python/pull/749)) ([fd0663e](https://github.com/apify/apify-client-python/commit/fd0663e22b31ddd289325146c9750ff07c068d6b)) by [@vdusek](https://github.com/vdusek)
26+
- Preserve count=0 in RunClient's charge ([#751](https://github.com/apify/apify-client-python/pull/751)) ([0a8942c](https://github.com/apify/apify-client-python/commit/0a8942c3a5728689e28e0273938a3509ebb5f58d)) by [@vdusek](https://github.com/vdusek)
2627

2728
### 🚜 Refactor
2829

2930
- [**breaking**] Introduce fully typed clients ([#604](https://github.com/apify/apify-client-python/pull/604)) ([81ee194](https://github.com/apify/apify-client-python/commit/81ee1943b400b49797868fe4dfa52d1662e09370)) by [@vdusek](https://github.com/vdusek), closes [#21](https://github.com/apify/apify-client-python/issues/21), [#481](https://github.com/apify/apify-client-python/issues/481)
3031
- [**breaking**] Drop support for Python 3.10 ([#636](https://github.com/apify/apify-client-python/pull/636)) ([7895a4e](https://github.com/apify/apify-client-python/commit/7895a4e60145f490911044da4aa7e3c1c424d416)) by [@vdusek](https://github.com/vdusek)
3132
- [**breaking**] Update default timeout tiers on non-storage resource clients ([#664](https://github.com/apify/apify-client-python/pull/664)) ([0b35bbe](https://github.com/apify/apify-client-python/commit/0b35bbe212a8a64c5aea5d5d813315252760b055)) by [@vdusek](https://github.com/vdusek)
3233
- [**breaking**] Use snake case for `actors().list(sort_by=...)` ([#736](https://github.com/apify/apify-client-python/pull/736)) ([eb70b64](https://github.com/apify/apify-client-python/commit/eb70b64eac86faba5cbe943845ad144ec0277896)) by [@vdusek](https://github.com/vdusek), closes [#700](https://github.com/apify/apify-client-python/issues/700)
34+
- [**breaking**] Mark secondary arguments as keyword-only ([#766](https://github.com/apify/apify-client-python/pull/766)) ([4ca99fd](https://github.com/apify/apify-client-python/commit/4ca99fd6a442ad12adbdfc866e72543c0feaf96b)) by [@vdusek](https://github.com/vdusek)
3335

3436

3537
<!-- git-cliff-unreleased-end -->

‎docs/04_upgrading/upgrading_to_v3.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,44 @@ except NotFoundError:
249249

250250
Direct `.get()` also now swallows every 404 regardless of the `error.type` string in the response body (previously only `record-not-found` and `record-or-token-not-found` types were swallowed). If your code needs to distinguish between "resource missing" and "404 with an unexpected type", inspect `.type` on a caught <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> from a non-`.get()` call path.
251251

252+
## Keyword-only arguments for secondary parameters
253+
254+
Several methods and utility functions had additional `*` separators inserted into their signatures, so optional/secondary parameters can no longer be passed positionally. The "subject" arguments (e.g. `key` on KVS record methods, `event_name` on `charge()`) remain positional; only the parameters that follow them are affected.
255+
256+
### Affected APIs
257+
258+
<ApiLink to="class/KeyValueStoreClient">`KeyValueStoreClient`</ApiLink> / <ApiLink to="class/KeyValueStoreClientAsync">`KeyValueStoreClientAsync`</ApiLink>:
259+
260+
- `get_record(key, *, signature=None, timeout='long')`
261+
- `get_record_as_bytes(key, *, signature=None, timeout='long')`
262+
- `stream_record(key, *, signature=None, timeout='long')`
263+
- `set_record(key, value, *, content_type=None, timeout='long')`
264+
265+
<ApiLink to="class/RunClient">`RunClient`</ApiLink> / <ApiLink to="class/RunClientAsync">`RunClientAsync`</ApiLink>:
266+
267+
- `charge(event_name, *, count=1, idempotency_key=None, timeout='short')`
268+
- `get_status_message_watcher(*, to_logger=None, check_period=..., timeout='long')`
269+
270+
<ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> constructor:
271+
272+
- `ApifyApiError(response, attempt, *, method='GET')`
273+
274+
### Migration
275+
276+
Before (v2):
277+
278+
```python
279+
client.key_value_store('my-store').set_record('my-key', {'data': 1}, 'application/json')
280+
client.run('my-run').charge('my-event', 5, 'my-idempotency-key')
281+
```
282+
283+
After (v3):
284+
285+
```python
286+
client.key_value_store('my-store').set_record('my-key', {'data': 1}, content_type='application/json')
287+
client.run('my-run').charge('my-event', count=5, idempotency_key='my-idempotency-key')
288+
```
289+
252290
## Snake_case `sort_by` values on `actors().list()`
253291

254292
The `sort_by` parameter of <ApiLink to="class/ActorCollectionClient#list">`ActorCollectionClient.list()`</ApiLink> and <ApiLink to="class/ActorCollectionClientAsync#list">`ActorCollectionClientAsync.list()`</ApiLink> now accepts pythonic snake_case values instead of the raw camelCase values used by the API.

‎pyproject.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,9 @@ python-version = "3.11"
186186
include = ["src", "tests", "scripts", "docs", "website"]
187187
exclude = ["website/versioned_docs"]
188188

189+
[tool.ty.rules]
190+
unused-ignore-comment = "error"
191+
189192
[[tool.ty.overrides]]
190193
include = ["docs/**/*.py", "website/**/*.py"]
191194
[tool.ty.overrides.rules]

‎src/apify_client/_http_clients/_base.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ def _parse_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
167167

168168
return parsed_params
169169

170-
def _compute_timeout(self, timeout: Timeout, attempt: int) -> int | float | None:
170+
def _compute_timeout(self, timeout: Timeout, *, attempt: int) -> int | float | None:
171171
"""Resolve a timeout tier and compute the timeout for a request attempt with exponential increase.
172172
173173
For `no_timeout`, returns `None` to indicate no timeout. For tier literals and explicit `timedelta` values,
@@ -197,6 +197,7 @@ def _compute_timeout(self, timeout: Timeout, attempt: int) -> int | float | None
197197

198198
def _prepare_request_call(
199199
self,
200+
*,
200201
headers: dict[str, str] | None = None,
201202
params: dict[str, Any] | None = None,
202203
data: str | bytes | bytearray | None = None,
@@ -221,7 +222,7 @@ def _prepare_request_call(
221222

222223
return (headers, self._parse_params(params), data)
223224

224-
def _build_url_with_params(self, url: str, params: dict[str, Any] | None = None) -> str:
225+
def _build_url_with_params(self, url: str, *, params: dict[str, Any] | None = None) -> str:
225226
"""Build a URL with query parameters appended. List values are expanded into multiple key=value pairs."""
226227
if not params:
227228
return url

‎src/apify_client/_http_clients/_impit.py‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,12 @@ def call(
142142

143143
self._statistics.calls += 1
144144

145-
prepared_headers, prepared_params, content = self._prepare_request_call(headers, params, data, json)
145+
prepared_headers, prepared_params, content = self._prepare_request_call(
146+
headers=headers,
147+
params=params,
148+
data=data,
149+
json=json,
150+
)
146151

147152
return self._retry_with_exp_backoff(
148153
lambda stop_retrying, attempt: self._make_request(
@@ -198,12 +203,12 @@ def _make_request(
198203
self._statistics.requests += 1
199204

200205
try:
201-
url_with_params = self._build_url_with_params(url, params)
206+
url_with_params = self._build_url_with_params(url, params=params)
202207

203208
# Impit treats timeout=None as "use client default (30s)", not "no timeout".
204209
# Use a large value (24 hours) to effectively disable the timeout.
205210
# This can be removed once impit updates its behaviour: https://github.com/apify/impit/issues/401
206-
computed_timeout = self._compute_timeout(timeout, attempt)
211+
computed_timeout = self._compute_timeout(timeout, attempt=attempt)
207212
impit_timeout = 86_400 if computed_timeout is None else computed_timeout
208213

209214
response = self._impit_client.request(
@@ -384,7 +389,12 @@ async def call(
384389

385390
self._statistics.calls += 1
386391

387-
prepared_headers, prepared_params, content = self._prepare_request_call(headers, params, data, json)
392+
prepared_headers, prepared_params, content = self._prepare_request_call(
393+
headers=headers,
394+
params=params,
395+
data=data,
396+
json=json,
397+
)
388398

389399
return await self._retry_with_exp_backoff(
390400
lambda stop_retrying, attempt: self._make_request(
@@ -440,12 +450,12 @@ async def _make_request(
440450
self._statistics.requests += 1
441451

442452
try:
443-
url_with_params = self._build_url_with_params(url, params)
453+
url_with_params = self._build_url_with_params(url, params=params)
444454

445455
# Impit treats timeout=None as "use client default (30s)", not "no timeout".
446456
# Use a large value (24 hours) to effectively disable the timeout.
447457
# This can be removed once impit updates its behaviour: https://github.com/apify/impit/issues/401
448-
computed_timeout = self._compute_timeout(timeout, attempt)
458+
computed_timeout = self._compute_timeout(timeout, attempt=attempt)
449459
impit_timeout = 86_400 if computed_timeout is None else computed_timeout
450460

451461
response = await self._impit_async_client.request(

‎src/apify_client/_models_generated.py‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1897,6 +1897,15 @@ class ListOfVersionsResponse(BaseModel):
18971897
data: ListOfVersions
18981898

18991899

1900+
@docs_group('Models')
1901+
class ListOfWebhookDispatchesResponse(BaseModel):
1902+
model_config = ConfigDict(
1903+
extra='allow',
1904+
populate_by_name=True,
1905+
)
1906+
data: ListOfWebhookDispatches
1907+
1908+
19001909
@docs_group('Models')
19011910
class ListOfWebhooksResponse(BaseModel):
19021911
model_config = ConfigDict(
@@ -3951,6 +3960,37 @@ class WebhookEventType(StrEnum):
39513960
TEST = 'TEST'
39523961

39533962

3963+
@docs_group('Models')
3964+
class WebhookRepresentation(BaseModel):
3965+
"""Minimal representation of an ad-hoc webhook attached to a single Actor run or build via the
3966+
`webhooks` query parameter. The query parameter value is a Base64-encoded JSON array whose
3967+
items match this schema. Persistent webhook fields (e.g. `condition`) are not used here.
3968+
3969+
"""
3970+
3971+
model_config = ConfigDict(
3972+
extra='allow',
3973+
populate_by_name=True,
3974+
)
3975+
event_types: Annotated[list[WebhookEventType], Field(alias='eventTypes', examples=[['ACTOR.RUN.SUCCEEDED']])]
3976+
request_url: Annotated[str, Field(alias='requestUrl', examples=['http://example.com/'])]
3977+
"""
3978+
The URL to which the webhook sends its payload.
3979+
"""
3980+
payload_template: Annotated[
3981+
str | None, Field(alias='payloadTemplate', examples=['{\\n "userId": {{userId}}...'])
3982+
] = None
3983+
"""
3984+
Optional template for the JSON payload sent by the webhook.
3985+
"""
3986+
headers_template: Annotated[
3987+
str | None, Field(alias='headersTemplate', examples=['{\\n "Authorization": "Bearer ..."}'])
3988+
] = None
3989+
"""
3990+
Optional template for the HTTP headers sent by the webhook.
3991+
"""
3992+
3993+
39543994
@docs_group('Models')
39553995
class WebhookResponse(BaseModel):
39563996
"""Response containing webhook data."""

‎src/apify_client/_resource_clients/actor.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ def start(
266266
Returns:
267267
The run object.
268268
"""
269-
run_input, content_type = encode_key_value_store_record_value(run_input, content_type)
269+
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
270270

271271
request_params = self._build_params(
272272
build=build,
@@ -543,7 +543,7 @@ def validate_input(
543543
Returns:
544544
True if the input is valid, else raise an exception with validation error details.
545545
"""
546-
run_input, content_type = encode_key_value_store_record_value(run_input, content_type)
546+
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
547547

548548
self._http_client.call(
549549
url=self._build_url('validate-input'),
@@ -762,7 +762,7 @@ async def start(
762762
Returns:
763763
The run object.
764764
"""
765-
run_input, content_type = encode_key_value_store_record_value(run_input, content_type)
765+
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
766766

767767
request_params = self._build_params(
768768
build=build,
@@ -1043,7 +1043,7 @@ async def validate_input(
10431043
Returns:
10441044
True if the input is valid, else raise an exception with validation error details.
10451045
"""
1046-
run_input, content_type = encode_key_value_store_record_value(run_input, content_type)
1046+
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
10471047

10481048
await self._http_client.call(
10491049
url=self._build_url('validate-input'),

‎src/apify_client/_resource_clients/dataset.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -736,8 +736,8 @@ def create_items_public_url(
736736

737737
if dataset and dataset.url_signing_secret_key:
738738
signature = create_storage_content_signature(
739-
resource_id=dataset.id,
740-
url_signing_secret_key=dataset.url_signing_secret_key,
739+
dataset.id,
740+
dataset.url_signing_secret_key,
741741
expires_in=expires_in,
742742
)
743743
request_params['signature'] = signature
@@ -1323,8 +1323,8 @@ async def create_items_public_url(
13231323

13241324
if dataset and dataset.url_signing_secret_key:
13251325
signature = create_storage_content_signature(
1326-
resource_id=dataset.id,
1327-
url_signing_secret_key=dataset.url_signing_secret_key,
1326+
dataset.id,
1327+
dataset.url_signing_secret_key,
13281328
expires_in=expires_in,
13291329
)
13301330
request_params['signature'] = signature

‎src/apify_client/_resource_clients/key_value_store.py‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,7 @@ def iterate_keys(
271271
timeout=timeout,
272272
)
273273

274-
def get_record(self, key: str, signature: str | None = None, *, timeout: Timeout = 'long') -> dict | None:
274+
def get_record(self, key: str, *, signature: str | None = None, timeout: Timeout = 'long') -> dict | None:
275275
"""Retrieve the given record from the key-value store.
276276
277277
https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record
@@ -330,7 +330,7 @@ def record_exists(self, key: str, *, timeout: Timeout = 'long') -> bool:
330330

331331
return response.status_code == HTTPStatus.OK
332332

333-
def get_record_as_bytes(self, key: str, signature: str | None = None, *, timeout: Timeout = 'long') -> dict | None:
333+
def get_record_as_bytes(self, key: str, *, signature: str | None = None, timeout: Timeout = 'long') -> dict | None:
334334
"""Retrieve the given record from the key-value store, without parsing it.
335335
336336
https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record
@@ -364,7 +364,7 @@ def get_record_as_bytes(self, key: str, signature: str | None = None, *, timeout
364364

365365
@contextmanager
366366
def stream_record(
367-
self, key: str, signature: str | None = None, *, timeout: Timeout = 'long'
367+
self, key: str, *, signature: str | None = None, timeout: Timeout = 'long'
368368
) -> Iterator[dict | None]:
369369
"""Retrieve the given record from the key-value store, as a stream.
370370
@@ -405,8 +405,8 @@ def set_record(
405405
self,
406406
key: str,
407407
value: Any,
408-
content_type: str | None = None,
409408
*,
409+
content_type: str | None = None,
410410
timeout: Timeout = 'long',
411411
) -> None:
412412
"""Set a value to the given record in the key-value store.
@@ -419,7 +419,7 @@ def set_record(
419419
content_type: The content type of the saved value.
420420
timeout: Timeout for the API HTTP request.
421421
"""
422-
value, content_type = encode_key_value_store_record_value(value, content_type)
422+
value, content_type = encode_key_value_store_record_value(value, content_type=content_type)
423423

424424
headers = {'content-type': content_type}
425425

@@ -522,8 +522,8 @@ def create_keys_public_url(
522522

523523
if metadata and metadata.url_signing_secret_key:
524524
signature = create_storage_content_signature(
525-
resource_id=metadata.id,
526-
url_signing_secret_key=metadata.url_signing_secret_key,
525+
metadata.id,
526+
metadata.url_signing_secret_key,
527527
expires_in=expires_in,
528528
)
529529
request_params['signature'] = signature
@@ -727,7 +727,7 @@ async def iterate_keys(
727727
):
728728
yield key
729729

730-
async def get_record(self, key: str, signature: str | None = None, *, timeout: Timeout = 'long') -> dict | None:
730+
async def get_record(self, key: str, *, signature: str | None = None, timeout: Timeout = 'long') -> dict | None:
731731
"""Retrieve the given record from the key-value store.
732732
733733
https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record
@@ -787,7 +787,7 @@ async def record_exists(self, key: str, *, timeout: Timeout = 'long') -> bool:
787787
return response.status_code == HTTPStatus.OK
788788

789789
async def get_record_as_bytes(
790-
self, key: str, signature: str | None = None, *, timeout: Timeout = 'long'
790+
self, key: str, *, signature: str | None = None, timeout: Timeout = 'long'
791791
) -> dict | None:
792792
"""Retrieve the given record from the key-value store, without parsing it.
793793
@@ -822,7 +822,7 @@ async def get_record_as_bytes(
822822

823823
@asynccontextmanager
824824
async def stream_record(
825-
self, key: str, signature: str | None = None, *, timeout: Timeout = 'long'
825+
self, key: str, *, signature: str | None = None, timeout: Timeout = 'long'
826826
) -> AsyncIterator[dict | None]:
827827
"""Retrieve the given record from the key-value store, as a stream.
828828
@@ -863,8 +863,8 @@ async def set_record(
863863
self,
864864
key: str,
865865
value: Any,
866-
content_type: str | None = None,
867866
*,
867+
content_type: str | None = None,
868868
timeout: Timeout = 'long',
869869
) -> None:
870870
"""Set a value to the given record in the key-value store.
@@ -877,7 +877,7 @@ async def set_record(
877877
content_type: The content type of the saved value.
878878
timeout: Timeout for the API HTTP request.
879879
"""
880-
value, content_type = encode_key_value_store_record_value(value, content_type)
880+
value, content_type = encode_key_value_store_record_value(value, content_type=content_type)
881881

882882
headers = {'content-type': content_type}
883883

@@ -980,8 +980,8 @@ async def create_keys_public_url(
980980

981981
if metadata and metadata.url_signing_secret_key:
982982
signature = create_storage_content_signature(
983-
resource_id=metadata.id,
984-
url_signing_secret_key=metadata.url_signing_secret_key,
983+
metadata.id,
984+
metadata.url_signing_secret_key,
985985
expires_in=expires_in,
986986
)
987987
request_params['signature'] = signature

‎src/apify_client/_resource_clients/request_queue.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -927,6 +927,7 @@ async def delete_request_lock(
927927

928928
async def _batch_add_requests_worker(
929929
self,
930+
*,
930931
queue: asyncio.Queue[Iterable[dict]],
931932
request_params: dict,
932933
timeout: Timeout,
@@ -1043,7 +1044,9 @@ async def batch_add_requests(
10431044
async with asyncio.TaskGroup() as tg:
10441045
workers = [
10451046
tg.create_task(
1046-
self._batch_add_requests_worker(asyncio_queue, request_params, timeout),
1047+
self._batch_add_requests_worker(
1048+
queue=asyncio_queue, request_params=request_params, timeout=timeout
1049+
),
10471050
name=f'batch_add_requests_worker_{i}',
10481051
)
10491052
for i in range(max_parallel)

0 commit comments

Comments
 (0)