scrapely-client-python 1.0.11__tar.gz → 1.0.13__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/CHANGELOG.md +12 -0
  2. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/PKG-INFO +1 -1
  3. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/pyproject.toml +3 -3
  4. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/pyproject.toml.orig +3 -3
  5. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/__init__.py +4 -0
  6. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_charging.py +14 -1
  7. scrapely_client_python-1.0.13/src/scrapely_client/_credit_unlock.py +64 -0
  8. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_literals.py +16 -0
  9. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_models.py +124 -1
  10. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/run.py +13 -6
  11. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_scrapely_client.py +16 -20
  12. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/errors.py +19 -20
  13. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/CONTRIBUTING.md +0 -0
  14. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/LICENSE +0 -0
  15. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/NOTICE +0 -0
  16. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/README.md +0 -0
  17. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_client_registry.py +0 -0
  18. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_consts.py +0 -0
  19. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_docs.py +0 -0
  20. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_logging.py +0 -0
  21. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_pagination.py +0 -0
  22. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/__init__.py +0 -0
  23. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/_resource_client.py +0 -0
  24. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor.py +0 -0
  25. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor_collection.py +0 -0
  26. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor_env_var.py +0 -0
  27. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor_env_var_collection.py +0 -0
  28. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor_version.py +0 -0
  29. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/actor_version_collection.py +0 -0
  30. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/automation.py +0 -0
  31. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/automation_collection.py +0 -0
  32. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/build.py +0 -0
  33. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/build_collection.py +0 -0
  34. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/dataset.py +0 -0
  35. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/dataset_collection.py +0 -0
  36. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/key_value_store.py +0 -0
  37. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/key_value_store_collection.py +0 -0
  38. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/log.py +0 -0
  39. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/request_queue.py +0 -0
  40. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/request_queue_collection.py +0 -0
  41. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/run_collection.py +0 -0
  42. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/schedule.py +0 -0
  43. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/schedule_collection.py +0 -0
  44. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/store_collection.py +0 -0
  45. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/task.py +0 -0
  46. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/task_collection.py +0 -0
  47. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/user.py +0 -0
  48. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/webhook.py +0 -0
  49. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/webhook_collection.py +0 -0
  50. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/webhook_dispatch.py +0 -0
  51. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_resource_clients/webhook_dispatch_collection.py +0 -0
  52. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_statistics.py +0 -0
  53. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_status_message_watcher.py +0 -0
  54. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_streamed_log.py +0 -0
  55. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_typeddicts.py +0 -0
  56. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/__init__.py +0 -0
  57. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/crypto.py +0 -0
  58. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/encoding.py +0 -0
  59. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/errors.py +0 -0
  60. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/http.py +0 -0
  61. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/time.py +0 -0
  62. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/_utils/try_import.py +0 -0
  63. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_clients/__init__.py +0 -0
  64. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_clients/_base.py +0 -0
  65. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_clients/_impit.py +0 -0
  66. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_compressors/__init__.py +0 -0
  67. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_compressors/_base.py +0 -0
  68. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_compressors/_brotli.py +0 -0
  69. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_compressors/_gzip.py +0 -0
  70. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/http_compressors/_resolve.py +0 -0
  71. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/py.typed +0 -0
  72. {scrapely_client_python-1.0.11 → scrapely_client_python-1.0.13}/src/scrapely_client/types.py +0 -0
@@ -2,6 +2,18 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.0.13] - 2026-11-18
6
+
7
+ - Run logs printed by `ActorClient.call()`, `RunClient.get_streamed_log()` and `RunClient.get_status_message_watcher()` (sync and async) now carry the prefix `[scrapely.<actor> runId:<id>]` instead of `[apify.<actor> runId:<id>]`. The default redirect logger is named `scrapely.<actor> runId:<id>`; code that configured the `apify` logger hierarchy for these lines should use `scrapely` instead.
8
+ - The client and error classes are now named `ScrapelyClient`, `ScrapelyClientAsync`, `ScrapelyApiError` and `ScrapelyClientError`, so `help()`, `repr()` and tracebacks show those names. `ApifyClient`, `ApifyClientAsync`, `ApifyApiError` and `ApifyClientError` stay importable as aliases of the same classes: existing imports, `isinstance` checks and `except` handlers keep working.
9
+ - Charged dataset pushes: the default dataset's client asks the charging hooks on every push whether to charge, not only when the client was created, so pricing that loads later and a spending limit reached during the run apply to the next push (sync and async).
10
+
11
+ ## [1.0.12] - 2026-11-06
12
+
13
+ - Out of credit: the API's 402 for the account balance keeps its type and status and now carries the way out in `error.data` (`ApifyApiError.data`, model `InsufficientCreditErrorData`): a Free account gets `unlock` (Starter, its price and credit, and `checkoutUrl`), a paid account `topUpUrl`, plus the account's newest held run (`heldItems`, `heldUntil`, `runId`). `is_insufficient_credit_error(err)` and `credit_unlock_url(err)` read it.
14
+ - `Run.held` (`RunHeld`): results a run found after the free credit ran out, kept out of its dataset until unlocked. All `RunHeld` / `CreditUnlock` fields are optional, so a partial object never fails `Run.model_validate`. `RunClient.wait_for_finish()` (and so `ActorClient.call()` / `TaskClient.call()`, sync and async) logs one warning with the count and the unlock link when the run has held results.
15
+ - Models regenerated from the updated specification (`scrapely-v2-2026-11-06`), which also picks up the current run retention text of `UpdateLimitsRequest.data_retention_days`.
16
+
5
17
  ## [1.0.11] - 2026-11-04
6
18
 
7
19
  - The API now sends its own 502 and 504 answers as 503 with the original status in the `X-Scrapely-Status` header (so the error body reaches you through Cloudflare). A 503 with `X-Scrapely-Status: 504` is treated like a 504: a POST or PATCH without an `Idempotency-Key` is not resent after it, since it may already have been applied. A 503 with `X-Scrapely-Status: 502` is retried like a 502.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scrapely-client-python
3
- Version: 1.0.11
3
+ Version: 1.0.13
4
4
  Summary: Scrapely API client for Python
5
5
  Keywords: scrapely,api,client,automation,crawling,scraping
6
6
  Author: TeraShift GmbH (Scrape.ly)
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "scrapely-client-python"
7
- version = "1.0.11"
7
+ version = "1.0.13"
8
8
  description = "Scrapely API client for Python"
9
9
  license = "Apache-2.0"
10
10
  license-files = [
@@ -262,8 +262,8 @@ disable_timestamp = true
262
262
  keep_model_order = true
263
263
 
264
264
  [tool.scrapely.openapi-spec]
265
- version = "scrapely-v2-2026-10-20"
266
- sha256 = "0913387f7deb9064489d43ec9aa345439ce3cfa96b5f29748f46220a65c9fe5e"
265
+ version = "scrapely-v2-2026-11-06"
266
+ sha256 = "f0fe68f5c2313c531f652394366ab6e372646d697eba4b4960b2f9e463572c17"
267
267
 
268
268
  [tool.uv]
269
269
  exclude-newer = "24 hours"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "scrapely-client-python"
7
- version = "1.0.11"
7
+ version = "1.0.13"
8
8
  description = "Scrapely API client for Python"
9
9
  authors = [{ name = "TeraShift GmbH (Scrape.ly)" }]
10
10
  license = "Apache-2.0"
@@ -251,8 +251,8 @@ keep_model_order = true
251
251
  # `poe generate-models`. `poe generate-models` refuses to run when the file doesn't match this hash; after reviewing
252
252
  # a change to the specification, record it with `poe accept-openapi-spec` (written by `scripts/openapi_spec.py`).
253
253
  [tool.scrapely.openapi-spec]
254
- version = "scrapely-v2-2026-10-20"
255
- sha256 = "0913387f7deb9064489d43ec9aa345439ce3cfa96b5f29748f46220a65c9fe5e"
254
+ version = "scrapely-v2-2026-11-06"
255
+ sha256 = "f0fe68f5c2313c531f652394366ab6e372646d697eba4b4960b2f9e463572c17"
256
256
 
257
257
  [tool.uv]
258
258
  # Minimal defense against supply-chain atatcks.
@@ -10,6 +10,7 @@ from ._charging import (
10
10
  normalize_items,
11
11
  push_data_charging_context,
12
12
  )
13
+ from ._credit_unlock import credit_unlock_url, held_run_warning, is_insufficient_credit_error
13
14
  from ._scrapely_client import ApifyClient, ApifyClientAsync, ScrapelyClient, ScrapelyClientAsync
14
15
 
15
16
  try:
@@ -27,6 +28,9 @@ __all__ = [
27
28
  'ScrapelyClient',
28
29
  'ScrapelyClientAsync',
29
30
  '__version__',
31
+ 'credit_unlock_url',
32
+ 'held_run_warning',
33
+ 'is_insufficient_credit_error',
30
34
  'normalize_items',
31
35
  'push_data_charging_context',
32
36
  ]
@@ -122,7 +122,9 @@ def _merge_context_charge_result(context: PpeAwarePushDataContext, hooks: Chargi
122
122
  context.charge_result = hooks.merge_charge_results(context.charge_result, result)
123
123
 
124
124
 
125
- def wrap_dataset_client_with_charging(client: Any, hooks: ChargingHooks, *, is_async: bool) -> Any:
125
+ def wrap_dataset_client_with_charging(
126
+ client: Any, hooks: ChargingHooks, *, is_async: bool, dataset_id: str | None = None
127
+ ) -> Any:
126
128
  """Wrap a dataset client's ``push_items`` with charging interception (method swap by design).
127
129
 
128
130
  Normalize items →
@@ -132,9 +134,17 @@ def wrap_dataset_client_with_charging(client: Any, hooks: ChargingHooks, *, is_a
132
134
  """
133
135
  original_push_items = client.push_items
134
136
 
137
+ def _charges() -> bool:
138
+ # Asked on every push, not when the client was created: pricing loads and
139
+ # the spending limit is reached after a client may already exist.
140
+ return dataset_id is None or hooks.should_charge_dataset_pushes(dataset_id)
141
+
135
142
  if is_async:
136
143
 
137
144
  async def patched_push_items(items: Any, **kwargs: Any) -> None:
145
+ if not _charges():
146
+ await original_push_items(items, **kwargs)
147
+ return
138
148
  context = push_data_charging_context.get()
139
149
  normalized = normalize_items(items)
140
150
 
@@ -153,6 +163,9 @@ def wrap_dataset_client_with_charging(client: Any, hooks: ChargingHooks, *, is_a
153
163
  else:
154
164
 
155
165
  def patched_push_items(items: Any, **kwargs: Any) -> None:
166
+ if not _charges():
167
+ original_push_items(items, **kwargs)
168
+ return
156
169
  context = push_data_charging_context.get()
157
170
  normalized = normalize_items(items)
158
171
 
@@ -0,0 +1,64 @@
1
+ # Scrape.ly addition (TeraShift GmbH): "out of credit" data of the API.
2
+ """Read the unlock data of an "out of credit" answer and warn about held results.
3
+
4
+ When the account's free credit runs out, the API answers run starts (and other paid requests) with HTTP 402 and puts
5
+ the way out in `error.data` (`ScrapelyApiError.data`): `unlock` (the Starter offer and its `checkoutUrl`) for a Free
6
+ account, `topUpUrl` for a paid one, and the account's newest held run (`heldItems`, `heldUntil`, `runId`). A run
7
+ that went on finding results after the credit ran out has `held` (`RunHeld`): the results are kept out of its
8
+ dataset until the account unlocks them.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import TYPE_CHECKING, Any
14
+
15
+ from scrapely_client._logging import logger
16
+
17
+ if TYPE_CHECKING:
18
+ from scrapely_client._models import Run
19
+
20
+ CREDIT_REASONS = frozenset({'insufficient-credit', 'insufficient-funds'})
21
+ PAYMENT_REQUIRED_STATUS = 402
22
+
23
+
24
+ def is_insufficient_credit_error(err: BaseException | Any) -> bool:
25
+ """Whether `err` is the API's HTTP 402 for the account balance (its unlock data is in `err.data`)."""
26
+ data = getattr(err, 'data', None)
27
+ return (
28
+ getattr(err, 'status_code', None) == PAYMENT_REQUIRED_STATUS
29
+ and isinstance(data, dict)
30
+ and data.get('reason') in CREDIT_REASONS
31
+ )
32
+
33
+
34
+ def credit_unlock_url(err: BaseException | Any) -> str | None:
35
+ """Return the link to show the user for a 402 for the balance: the unlock checkout, else the top-up page."""
36
+ if not is_insufficient_credit_error(err):
37
+ return None
38
+ data = getattr(err, 'data', None) or {}
39
+ unlock = data.get('unlock')
40
+ url = unlock.get('checkoutUrl') if isinstance(unlock, dict) else None
41
+ url = url or data.get('topUpUrl')
42
+ return url if isinstance(url, str) and url else None
43
+
44
+
45
+ def held_run_warning(run: Run | None) -> str | None:
46
+ """Return one warning line for a run with held results that can still be unlocked, else None."""
47
+ if run is None:
48
+ return None
49
+ held = run.held
50
+ n = held.items if held is not None else None
51
+ if held is None or not n or n <= 0 or held.status not in ('holding', 'held'):
52
+ return None
53
+ until = f' until {held.held_until.isoformat().replace("+00:00", "Z")}' if held.held_until else ''
54
+ checkout_url = held.unlock.checkout_url if held.unlock is not None else None
55
+ link = f' Unlock them: {checkout_url}' if checkout_url else ''
56
+ noun = 'result is' if n == 1 else 'results are'
57
+ return f'Run {run.id}: your free credit ran out, so {n:,} more {noun} held{until}.{link}'
58
+
59
+
60
+ def warn_if_held(run: Run | None) -> None:
61
+ """Log `held_run_warning(run)` when there is one."""
62
+ warning = held_run_warning(run)
63
+ if warning:
64
+ logger.warning(warning)
@@ -120,6 +120,7 @@ ErrorType = (
120
120
  'cannot-unpublish-paid-actor',
121
121
  'cannot-unpublish-profile',
122
122
  'cannot-update-invoice-field',
123
+ 'charge-limit-exceeded',
123
124
  'concurrent-runs-limit-exceeded',
124
125
  'concurrent-update-detected',
125
126
  'conference-token-not-found',
@@ -177,6 +178,8 @@ ErrorType = (
177
178
  'input-json-not-object',
178
179
  'input-json-too-long',
179
180
  'input-update-collision',
181
+ 'insufficient-balance',
182
+ 'insufficient-funds',
180
183
  'insufficient-permissions',
181
184
  'insufficient-permissions-to-change-field',
182
185
  'insufficient-security-measures',
@@ -295,6 +298,7 @@ ErrorType = (
295
298
  'password-reset-token-expired',
296
299
  'pay-as-you-go-without-monthly-interval',
297
300
  'payment-attempt-status-message-required',
301
+ 'payment-required',
298
302
  'payout-already-paid',
299
303
  'payout-canceled',
300
304
  'payout-invalid-state',
@@ -489,6 +493,18 @@ SourceCodeFileFormat = (
489
493
  )
490
494
 
491
495
 
496
+ Status = (
497
+ Literal[
498
+ 'holding',
499
+ 'held',
500
+ 'released',
501
+ 'expired',
502
+ ]
503
+ | str
504
+ )
505
+ """`holding` (run running), `held`, `released` (now in the dataset) or `expired`."""
506
+
507
+
492
508
  StorageOwnership = (
493
509
  Literal[
494
510
  'ownedByMe',
@@ -19,6 +19,7 @@ from scrapely_client._literals import (
19
19
  HttpMethod,
20
20
  RunOrigin,
21
21
  SourceCodeFileFormat,
22
+ Status,
22
23
  VersionSourceType,
23
24
  WebhookDispatchStatus,
24
25
  WebhookEventType,
@@ -883,6 +884,43 @@ class CreateTaskRequest(BaseModel):
883
884
  seo_description: str | None = None
884
885
 
885
886
 
887
+ @docs_group('Models')
888
+ class CreditUnlock(BaseModel):
889
+ """The plan that unlocks held results, or lets an account whose free credit is used up keep running. Prices come from the platform's plan table."""
890
+
891
+ model_config = ConfigDict(
892
+ extra='allow',
893
+ populate_by_name=True,
894
+ alias_generator=to_camel,
895
+ )
896
+ plan: Annotated[str | None, Field(examples=['starter'])] = None
897
+ """
898
+ Plan id.
899
+ """
900
+ plan_name: Annotated[str | None, Field(examples=['Starter'])] = None
901
+ """
902
+ Plan name.
903
+ """
904
+ price_usd: Annotated[float | None, Field(examples=[19])] = None
905
+ """
906
+ Price of one plan period (4 weeks) in USD.
907
+ """
908
+ credit_usd: Annotated[float | None, Field(examples=[19])] = None
909
+ """
910
+ Credit the plan grants every period, in USD.
911
+ """
912
+ held_items_cost_usd: Annotated[float | None, Field(examples=[0.48])] = None
913
+ """
914
+ What the run's held results cost out of that credit (run `held.unlock` only).
915
+ """
916
+ checkout_url: Annotated[
917
+ str | None, Field(examples=['https://my.scrape.ly/runs/HG7ML7M8z78YcAPEB?unlock=starter'])
918
+ ] = None
919
+ """
920
+ Console link that opens the checkout. It carries no token; the console asks for the user's login.
921
+ """
922
+
923
+
886
924
  @docs_group('Models')
887
925
  class Current(BaseModel):
888
926
  model_config = ConfigDict(
@@ -1359,6 +1397,10 @@ class ErrorDetail(BaseModel):
1359
1397
  """
1360
1398
  Human-readable error message describing what went wrong.
1361
1399
  """
1400
+ data: dict[str, Any] | None = None
1401
+ """
1402
+ Additional data about the error; for an HTTP 402 for the balance see InsufficientCreditErrorData.
1403
+ """
1362
1404
 
1363
1405
 
1364
1406
  @docs_group('Models')
@@ -1493,6 +1535,46 @@ class HeadResponse(BaseModel):
1493
1535
  data: RequestQueueHead
1494
1536
 
1495
1537
 
1538
+ @docs_group('Models')
1539
+ class InsufficientCreditErrorData(BaseModel):
1540
+ """`error.data` of an HTTP 402 for the account balance."""
1541
+
1542
+ model_config = ConfigDict(
1543
+ extra='allow',
1544
+ populate_by_name=True,
1545
+ alias_generator=to_camel,
1546
+ )
1547
+ reason: Annotated[str | None, Field(examples=['insufficient-credit'])] = None
1548
+ """
1549
+ `insufficient-credit` (the run's own charge route keeps `insufficient-funds`).
1550
+ """
1551
+ plan: Annotated[str | None, Field(examples=['free'])] = None
1552
+ """
1553
+ The account's plan id.
1554
+ """
1555
+ unlock: CreditUnlock | None = None
1556
+ """
1557
+ The Starter offer for a Free account; null for a paid account.
1558
+ """
1559
+ top_up_url: str | None = None
1560
+ """
1561
+ A paid account's billing page, to add credit.
1562
+ """
1563
+ held_items: int | None = None
1564
+ """
1565
+ Held results of the account's newest held run.
1566
+ """
1567
+ held_until: AwareDatetime | None = None
1568
+ run_id: str | None = None
1569
+ """
1570
+ That held run.
1571
+ """
1572
+ kyc_url: str | None = None
1573
+ """
1574
+ Set when the account's free credit waits for identity verification.
1575
+ """
1576
+
1577
+
1496
1578
  @docs_group('Models')
1497
1579
  class InvalidItem(BaseModel):
1498
1580
  model_config = ConfigDict(
@@ -2987,6 +3069,47 @@ class Run(BaseModel):
2987
3069
  """
2988
3070
  Indicates which party covers platform usage costs for this run.
2989
3071
  """
3072
+ held: RunHeld | None = None
3073
+ """
3074
+ Results held because the account's free credit ran out (owner only; absent when nothing is held).
3075
+ """
3076
+
3077
+
3078
+ @docs_group('Models')
3079
+ class RunHeld(BaseModel):
3080
+ """Results the run found after the account's free credit ran out. They are kept out of the run's dataset until the account unlocks them or `heldUntil` passes. Only on the owner's run. Every field is optional: a partial object never fails the run."""
3081
+
3082
+ model_config = ConfigDict(
3083
+ extra='allow',
3084
+ populate_by_name=True,
3085
+ alias_generator=to_camel,
3086
+ )
3087
+ status: Status | None = None
3088
+ """
3089
+ `holding` (run running), `held`, `released` (now in the dataset) or `expired`.
3090
+ """
3091
+ items: Annotated[int | None, Field(examples=[1653])] = None
3092
+ """
3093
+ Number of held results.
3094
+ """
3095
+ events: dict[str, int] | None = None
3096
+ """
3097
+ Held charge events by event name.
3098
+ """
3099
+ saved_items: Annotated[int | None, Field(examples=[1347])] = None
3100
+ """
3101
+ Results saved to the dataset before the credit ran out.
3102
+ """
3103
+ held_until: AwareDatetime | None = None
3104
+ """
3105
+ When the held results are deleted unless unlocked.
3106
+ """
3107
+ released_at: AwareDatetime | None = None
3108
+ expired_at: AwareDatetime | None = None
3109
+ unlock: CreditUnlock | None = None
3110
+ """
3111
+ How to unlock them.
3112
+ """
2990
3113
 
2991
3114
 
2992
3115
  @docs_group('Models')
@@ -3763,7 +3886,7 @@ class UpdateLimitsRequest(BaseModel):
3763
3886
  """
3764
3887
  data_retention_days: Annotated[int | None, Field(examples=[90])] = None
3765
3888
  """
3766
- How many days unnamed storages (datasets, key-value stores and request queues without a name) are kept: Free 2 days (48 hours), Starter 31, Scale 60, Business 90. Runs and their logs are kept for the same time as their results; on the Free plan your latest 10 runs are kept with their results until you delete them. This value is set by your plan and cannot be changed through the API.
3889
+ How many days unnamed storages (datasets, key-value stores and request queues without a name) are kept: Free 2 days (48 hours), Starter 31, Scale 60, Business 90. Runs follow their own retention: on the Free plan the latest 10 runs per Actor are kept and older ones are deleted after 7 days; on paid plans runs are deleted after 31 days. This value is set by your plan and cannot be changed through the API.
3767
3890
 
3768
3891
  """
3769
3892
 
@@ -9,6 +9,7 @@ import time
9
9
  from datetime import timedelta
10
10
  from typing import TYPE_CHECKING, Any
11
11
 
12
+ from scrapely_client._credit_unlock import warn_if_held
12
13
  from scrapely_client._docs import docs_group
13
14
  from scrapely_client._logging import create_redirect_logger
14
15
  from scrapely_client._models import Run, RunResponse
@@ -158,7 +159,10 @@ class RunClient(ResourceClient):
158
159
  if response is None:
159
160
  return None
160
161
 
161
- return Run.model_validate(response)
162
+ run = Run.model_validate(response)
163
+ # Results held because the free credit ran out: one line with the count and the unlock link.
164
+ warn_if_held(run)
165
+ return run
162
166
 
163
167
  def metamorph(
164
168
  self,
@@ -365,7 +369,7 @@ class RunClient(ResourceClient):
365
369
 
366
370
  if not to_logger:
367
371
  name = ' '.join(part for part in (actor_name, run_id) if part)
368
- to_logger = create_redirect_logger(f'apify.{name}')
372
+ to_logger = create_redirect_logger(f'scrapely.{name}')
369
373
 
370
374
  return StreamedLog(log_client=self.log(), to_logger=to_logger, from_start=from_start)
371
375
 
@@ -452,7 +456,7 @@ class RunClient(ResourceClient):
452
456
 
453
457
  if not to_logger:
454
458
  name = ' '.join(part for part in (actor_name, run_id) if part)
455
- to_logger = create_redirect_logger(f'apify.{name}')
459
+ to_logger = create_redirect_logger(f'scrapely.{name}')
456
460
 
457
461
  return StatusMessageWatcher(run_client=self, to_logger=to_logger, check_period=check_period)
458
462
 
@@ -565,7 +569,10 @@ class RunClientAsync(ResourceClientAsync):
565
569
  wait_duration=wait_duration,
566
570
  timeout=timeout,
567
571
  )
568
- return Run.model_validate(response) if response is not None else None
572
+ run = Run.model_validate(response) if response is not None else None
573
+ # Results held because the free credit ran out: one line with the count and the unlock link.
574
+ warn_if_held(run)
575
+ return run
569
576
 
570
577
  async def delete(self, *, timeout: Timeout = 'short') -> None:
571
578
  """Delete the run.
@@ -784,7 +791,7 @@ class RunClientAsync(ResourceClientAsync):
784
791
 
785
792
  if not to_logger:
786
793
  name = ' '.join(part for part in (actor_name, run_id) if part)
787
- to_logger = create_redirect_logger(f'apify.{name}')
794
+ to_logger = create_redirect_logger(f'scrapely.{name}')
788
795
 
789
796
  return StreamedLogAsync(log_client=self.log(), to_logger=to_logger, from_start=from_start)
790
797
 
@@ -872,6 +879,6 @@ class RunClientAsync(ResourceClientAsync):
872
879
 
873
880
  if not to_logger:
874
881
  name = ' '.join(part for part in (actor_name, run_id) if part)
875
- to_logger = create_redirect_logger(f'apify.{name}')
882
+ to_logger = create_redirect_logger(f'scrapely.{name}')
876
883
 
877
884
  return StatusMessageWatcherAsync(run_client=self, to_logger=to_logger, check_period=check_period)
@@ -100,7 +100,7 @@ def _resolve_api_url(api_url: str | None) -> str:
100
100
 
101
101
 
102
102
  @docs_group('Scrapely API clients')
103
- class ApifyClient:
103
+ class ScrapelyClient:
104
104
  """Synchronous client for the Scrapely API.
105
105
 
106
106
  This is the main entry point for interacting with the Scrapely platform. It provides methods to access
@@ -246,7 +246,7 @@ class ApifyClient:
246
246
  api_url: str | None = None,
247
247
  api_public_url: str | None = DEFAULT_API_URL,
248
248
  http_client: HttpClient,
249
- ) -> ApifyClient:
249
+ ) -> ScrapelyClient:
250
250
  """Create an `ScrapelyClient` instance with a custom HTTP client.
251
251
 
252
252
  Use this alternative constructor when you want to provide your own HTTP client implementation
@@ -364,12 +364,10 @@ class ApifyClient:
364
364
  dataset_id: ID of the dataset to be manipulated.
365
365
  """
366
366
  dataset_client = DatasetClient(resource_id=dataset_id, **self._base_kwargs)
367
- if (
368
- self._charging_hooks is not None
369
- and dataset_id == self._default_dataset_id
370
- and self._charging_hooks.should_charge_dataset_pushes(dataset_id)
371
- ):
372
- return wrap_dataset_client_with_charging(dataset_client, self._charging_hooks, is_async=False)
367
+ if self._charging_hooks is not None and dataset_id == self._default_dataset_id:
368
+ return wrap_dataset_client_with_charging(
369
+ dataset_client, self._charging_hooks, is_async=False, dataset_id=dataset_id
370
+ )
373
371
  return dataset_client
374
372
 
375
373
  def datasets(self) -> DatasetCollectionClient:
@@ -483,7 +481,7 @@ class ApifyClient:
483
481
 
484
482
 
485
483
  @docs_group('Scrapely API clients')
486
- class ApifyClientAsync:
484
+ class ScrapelyClientAsync:
487
485
  """Asynchronous client for the Scrapely API.
488
486
 
489
487
  This is the main entry point for interacting with the Scrapely platform using async/await. It provides
@@ -636,7 +634,7 @@ class ApifyClientAsync:
636
634
  api_url: str | None = None,
637
635
  api_public_url: str | None = DEFAULT_API_URL,
638
636
  http_client: HttpClientAsync,
639
- ) -> ApifyClientAsync:
637
+ ) -> ScrapelyClientAsync:
640
638
  """Create an `ScrapelyClientAsync` instance with a custom HTTP client.
641
639
 
642
640
  Use this alternative constructor when you want to provide your own HTTP client implementation
@@ -753,12 +751,10 @@ class ApifyClientAsync:
753
751
  dataset_id: ID of the dataset to be manipulated.
754
752
  """
755
753
  dataset_client = DatasetClientAsync(resource_id=dataset_id, **self._base_kwargs)
756
- if (
757
- self._charging_hooks is not None
758
- and dataset_id == self._default_dataset_id
759
- and self._charging_hooks.should_charge_dataset_pushes(dataset_id)
760
- ):
761
- return wrap_dataset_client_with_charging(dataset_client, self._charging_hooks, is_async=True)
754
+ if self._charging_hooks is not None and dataset_id == self._default_dataset_id:
755
+ return wrap_dataset_client_with_charging(
756
+ dataset_client, self._charging_hooks, is_async=True, dataset_id=dataset_id
757
+ )
762
758
  return dataset_client
763
759
 
764
760
  def datasets(self) -> DatasetCollectionClientAsync:
@@ -871,8 +867,8 @@ class ApifyClientAsync:
871
867
  return StoreCollectionClientAsync(**self._base_kwargs)
872
868
 
873
869
 
874
- ScrapelyClient = ApifyClient
875
- """Primary name of the client; ``ApifyClient`` is kept as a drop-in compatibility alias."""
870
+ ApifyClient = ScrapelyClient
871
+ """Compatibility alias of `ScrapelyClient` (the same class), kept so existing imports keep working."""
876
872
 
877
- ScrapelyClientAsync = ApifyClientAsync
878
- """Primary name of the async client; ``ApifyClientAsync`` is kept as a drop-in compatibility alias."""
873
+ ApifyClientAsync = ScrapelyClientAsync
874
+ """Compatibility alias of `ScrapelyClientAsync` (the same class), kept so existing imports keep working."""
@@ -14,17 +14,17 @@ if TYPE_CHECKING:
14
14
 
15
15
 
16
16
  @docs_group('Errors')
17
- class ApifyClientError(Exception):
17
+ class ScrapelyClientError(Exception):
18
18
  """Base class for all Scrapely API client errors."""
19
19
 
20
20
 
21
21
  @docs_group('Errors')
22
- class ApifyApiError(ApifyClientError):
22
+ class ScrapelyApiError(ScrapelyClientError):
23
23
  """Error raised when the Scrapely API returns an error response.
24
24
 
25
- Instantiating `ApifyApiError` dispatches to the subclass matching the HTTP status code (e.g. 404 → `NotFoundError`,
26
- any 5xx → `ServerError`). Unmapped statuses stay on `ApifyApiError`. Existing `except ApifyApiError` handlers keep
27
- working because every subclass inherits from this class.
25
+ Instantiating `ScrapelyApiError` dispatches to the subclass matching the HTTP status code (e.g. 404 →
26
+ `NotFoundError`, any 5xx → `ServerError`). Unmapped statuses stay on `ScrapelyApiError`. Existing
27
+ `except ScrapelyApiError` handlers keep working because every subclass inherits from this class.
28
28
 
29
29
  The `type`, `message` and `data` fields from the response body are exposed for inspection but are treated as
30
30
  non-authoritative metadata — dispatch is driven by the status code only.
@@ -44,7 +44,7 @@ class ApifyApiError(ApifyClientError):
44
44
  def __new__(cls, response: HttpResponse, attempt: int, *, method: str = 'GET') -> Self: # noqa: ARG004
45
45
  """Dispatch to the subclass matching the response's HTTP status code, if any."""
46
46
  instance = super().__new__(cls)
47
- if cls is ApifyApiError:
47
+ if cls is ScrapelyApiError:
48
48
  status = response.status_code
49
49
  mapped = _STATUS_TO_CLASS.get(status)
50
50
  if mapped is None and status >= HTTPStatus.INTERNAL_SERVER_ERROR:
@@ -98,32 +98,32 @@ class ApifyApiError(ApifyClientError):
98
98
 
99
99
 
100
100
  @docs_group('Errors')
101
- class InvalidRequestError(ApifyApiError):
101
+ class InvalidRequestError(ScrapelyApiError):
102
102
  """Raised when the Scrapely API returns an HTTP 400 Bad Request response."""
103
103
 
104
104
 
105
105
  @docs_group('Errors')
106
- class UnauthorizedError(ApifyApiError):
106
+ class UnauthorizedError(ScrapelyApiError):
107
107
  """Raised when the Scrapely API returns an HTTP 401 Unauthorized response."""
108
108
 
109
109
 
110
110
  @docs_group('Errors')
111
- class ForbiddenError(ApifyApiError):
111
+ class ForbiddenError(ScrapelyApiError):
112
112
  """Raised when the Scrapely API returns an HTTP 403 Forbidden response."""
113
113
 
114
114
 
115
115
  @docs_group('Errors')
116
- class NotFoundError(ApifyApiError):
116
+ class NotFoundError(ScrapelyApiError):
117
117
  """Raised when the Scrapely API returns an HTTP 404 Not Found response."""
118
118
 
119
119
 
120
120
  @docs_group('Errors')
121
- class ConflictError(ApifyApiError):
121
+ class ConflictError(ScrapelyApiError):
122
122
  """Raised when the Scrapely API returns an HTTP 409 Conflict response."""
123
123
 
124
124
 
125
125
  @docs_group('Errors')
126
- class RateLimitError(ApifyApiError):
126
+ class RateLimitError(ScrapelyApiError):
127
127
  """Raised when the Scrapely API returns an HTTP 429 Too Many Requests response.
128
128
 
129
129
  Rate-limited requests are retried automatically; this error is only raised after all retry attempts have been
@@ -132,7 +132,7 @@ class RateLimitError(ApifyApiError):
132
132
 
133
133
 
134
134
  @docs_group('Errors')
135
- class ServerError(ApifyApiError):
135
+ class ServerError(ScrapelyApiError):
136
136
  """Raised when the Scrapely API returns an HTTP 5xx response.
137
137
 
138
138
  Server errors are retried automatically; this error is only raised after all retry attempts have been exhausted.
@@ -140,7 +140,7 @@ class ServerError(ApifyApiError):
140
140
 
141
141
 
142
142
  @docs_group('Errors')
143
- class InvalidResponseBodyError(ApifyClientError):
143
+ class InvalidResponseBodyError(ScrapelyClientError):
144
144
  """Error raised when a response body cannot be parsed.
145
145
 
146
146
  This occurs when the API returns a body that does not match its content type, for example a malformed JSON
@@ -160,13 +160,12 @@ class InvalidResponseBodyError(ApifyClientError):
160
160
  self.response = response
161
161
 
162
162
 
163
- # Scrapely-named aliases for the error classes. The original class names stay part of the
164
- # client's backward-compatibility contract (existing code keeps working); these aliases let
165
- # Scrapely-native code use the platform name.
166
- ScrapelyApiError = ApifyApiError
167
- ScrapelyClientError = ApifyClientError
163
+ # Compatibility aliases (the same classes). The earlier class names stay part of the client's
164
+ # backward-compatibility contract, so existing imports and `except ApifyApiError` handlers keep working.
165
+ ApifyApiError = ScrapelyApiError
166
+ ApifyClientError = ScrapelyClientError
168
167
 
169
- _STATUS_TO_CLASS: dict[int, type[ApifyApiError]] = {
168
+ _STATUS_TO_CLASS: dict[int, type[ScrapelyApiError]] = {
170
169
  400: InvalidRequestError,
171
170
  401: UnauthorizedError,
172
171
  403: ForbiddenError,