docs: cover apify-client v3 changes in the v4 upgrading guide

Restructure the apify-client section of the v4 upgrading guide to mirror the
client's "Upgrading to v3" guide, and document the changes that reach SDK
users through it:

- Split into "Built on apify-client v3", "Typed responses", and "Literal
  string aliases instead of StrEnum classes"; fix the typed-responses method
  list (start / abort / call / call_task; metamorph returns None).
- Add "Actor pricing info models" - the pricing models are now thin
  apify-client subclasses; shape unchanged, fuller field set, event_price_usd
  optional.
- Add "Using the client from Actor.new_client" - 404 raising NotFoundError on
  ambiguous endpoints, keyword-only arguments, and async iterate_* returning
  AsyncIterator.

Author: vdusek

docs/04_upgrading/upgrading_to_v4.md

@@ -8,13 +8,20 @@ This page summarizes the breaking changes between Apify Python SDK v3.x and v4.0
 
 ## Python 3.11+ required
 
-Support for Python 3.10 has been dropped. Apify Python SDK v4.x requires Python 3.11 or later.
+Support for Python 3.10 has been dropped. Apify Python SDK v4.x now requires Python 3.11 or later — make sure your environment is on a compatible version before upgrading.
 
-## `apify-client` v3 required
+## Built on `apify-client` v3
 
-The SDK is now built on `apify-client` v3 and no longer depends on `apify-shared`. Three changes are user-visible:
+The SDK is now built on [`apify-client`](https://docs.apify.com/api/client/python) v3 and no longer depends on `apify-shared`. The sections below cover the user-visible consequences; see the client's [Upgrading to v3](https://docs.apify.com/api/client/python/docs/upgrading/upgrading-to-v3) guide for the full list of changes in the client itself.
+
+## Typed responses
+
+`Actor.start`, `Actor.abort`, `Actor.call`, and `Actor.call_task` now return `apify_client._models.Run` instead of the SDK-side `ActorRun`. Both are [Pydantic](https://docs.pydantic.dev/latest/) models with the same snake_case fields, so field access is unchanged — only the type and import path differ. The SDK no longer ships its own response models (`apify._models` has been removed); response shapes come from `apify-client`.
+
+## Literal string aliases instead of StrEnum classes
+
+Generated enum-like types are now [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal) string aliases instead of `StrEnum` classes. Pass plain strings instead of enum members.
 
-- `Actor.start`, `Actor.call`, `Actor.call_task`, and `Actor.metamorph` return `apify_client._models.Run` instead of the SDK-side `ActorRun`. The shape is equivalent — only the import path changes.
 - `apify.WebhookEventType` is now a `Literal[...]` instead of a `StrEnum`. Use plain string values (`'ACTOR.RUN.FAILED'`) instead of enum members.
 - `apify_shared.consts.ActorEventTypes` (a `StrEnum`) is replaced by `apify.ActorEventTypes`, now a `Literal['systemInfo', 'persistState', 'migrating', 'aborting']`. For runtime values, use `apify.Event` (re-exported from Crawlee) instead of enum members.
 
@@ -35,6 +42,10 @@ from apify import Actor, Event
 Actor.on(Event.SYSTEM_INFO, callback)
 ```
 
+## Actor pricing info models
+
+The Actor pricing-info models exposed through `Actor.configuration.actor_pricing_info` — `FreeActorPricingInfo`, `FlatPricePerMonthActorPricingInfo`, `PricePerDatasetItemActorPricingInfo`, `PayPerEventActorPricingInfo`, and the nested `ActorChargeEvent` / `PricingPerEvent` — are now thin subclasses of the corresponding `apify-client` models instead of standalone SDK copies. The discriminated-union shape is unchanged, so existing access (`pricing_model`, per-event titles and prices) keeps working; the models now expose the full `apify-client` field set, and a charge event's `event_price_usd` is optional (it is unset for tier-priced events). `ChargingManager.get_pricing_info()` is unchanged.
+
 ## `Webhook` API simplified
 
 The `Webhook` model has been slimmed down to only the fields a user sets when defining a webhook. Server-populated response fields (`id`, `created_at`, `modified_at`, `user_id`, `is_ad_hoc`, `condition`, `last_dispatch`, `stats`) and the unused `WebhookCondition` helper class have been removed. `Webhook` is now a plain `@dataclass` instead of a Pydantic `BaseModel` — construct it with snake_case kwargs; `.model_dump()` / `.model_validate()` are gone.
@@ -79,3 +90,56 @@ The `webhooks` argument on `Actor.start`, `Actor.call`, and `Actor.call_task` st
 ## `Actor.new_client` — `timeout` scales all tiers
 
 `apify-client` v3 split its single timeout into four tiers (short / medium / long / max). `Actor.new_client(timeout=...)` still takes a single `timedelta`; the SDK uses it as the medium-tier baseline and scales the other tiers proportionally (short = `timeout / 6`, long = `timeout * 12`, max = `timeout * 24`). The public signature is unchanged — no migration needed.
+
+## Using the client from `Actor.new_client`
+
+`Actor.new_client()` (and the `Actor.apify_client` property) now returns an `apify-client` v3 `ApifyClientAsync`. When you use that client directly, the client's v3 breaking changes apply — the most impactful ones are below. See the client's [Upgrading to v3](https://docs.apify.com/api/client/python/docs/upgrading/upgrading-to-v3) guide for the complete reference.
+
+### 404 raises `NotFoundError` on ambiguous endpoints
+
+Direct `.get(id)` and `.delete(id)` calls still swallow 404 into `None`. But where a 404 could mean either the parent or the sub-resource is missing, the client now raises `NotFoundError` instead of returning `None`.
+
+**Before (v3.x):**
+
+```python
+client = Actor.new_client()
+
+# Returned None on 404.
+dataset = await client.run('some-run-id').dataset().get()
+```
+
+**Now (v4.0):**
+
+```python
+from apify_client.errors import NotFoundError
+
+client = Actor.new_client()
+
+# Raises NotFoundError; handle it explicitly.
+try:
+    dataset = await client.run('some-run-id').dataset().get()
+except NotFoundError:
+    dataset = None
+```
+
+### Keyword-only arguments
+
+Secondary parameters on several client methods can no longer be passed positionally.
+
+**Before (v3.x):**
+
+```python
+await client.key_value_store('my-store').set_record('my-key', {'data': 1}, 'application/json')
+await client.run('my-run').charge('my-event', 5)
+```
+
+**Now (v4.0):**
+
+```python
+await client.key_value_store('my-store').set_record('my-key', {'data': 1}, content_type='application/json')
+await client.run('my-run').charge('my-event', count=5)
+```
+
+### Async `iterate_*` are no longer coroutine functions
+
+`DatasetClientAsync.iterate_items()` and `KeyValueStoreClientAsync.iterate_keys()` are now plain `def` functions returning `AsyncIterator[T]`. Consumer code (`async for ...`) is unchanged; if you annotate the call's return value, change `AsyncGenerator[T, None]` to `AsyncIterator[T]`.