refactor!: Introduce fully typed clients (#604)

### Summary

This is a major refactoring that introduces fully typed Pydantic models
throughout the client library. The models are generated from the OpenAPI
specifications. All API responses now return typed objects instead of
raw dictionaries.

This follows up on apify/apify-docs#2182.

### Issues

- Closes: #21
- Closes: #481

### Packages

- Add direct dependency on `Pydantic`.
- Removes the dependency on `apify-shared`.
- Add dev dependency
[datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator/)
for model generation.

### Key changes

- Uses
[datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator/)
tool configured via `pyproject.toml` to generate Pydantic models based
on the [OpenAPI specs](https://docs.apify.com/api/openapi.json).
- Refactors the whole codebase to adopt the new generated models.
- All resource clients now return typed Pydantic models (`Actor`,
`Task`, `Run`, etc.).
- Adds response wrappers for validating and extracting API response
data.
- Updates list methods to return typed pagination models.
- Documentation examples now use typed attribute access.
- Updates the SDK to use the new typed client.
- See the corresponding PR in `apify/apify-sdk-python` for details -
apify/apify-sdk-python#719.
  - It will be merged later.

### Architecture

- Get rid of 3/4/5 levels of inheritance.
- Get rid of inline imports because of circular dependencies.
- I had to utilize `ClientRegistry` to be able to achieve that (because
of resource clients-siblings imports).

### Breaking changes

- Client methods now return Pydantic models instead of dicts.
- Access patterns change from dict-style (`result['key']`) to
attribute-style (`result.key`).

### Test plan

- Updated test concurrency to 16 workers.
- A lot of new tests were implemented - coverage ~95%.
- Unit tests - do not call production API, only for testing utils or
other functionality using mocks.
  - Integration tests - call production API.
- Thanks to the new tests, I was able to do a lot of fixes in the
OpenAPI specs.

### Next steps

- Explore the generation of resource clients using
[openapi-python-client](https://github.com/openapi-generators/openapi-python-client).
- Fully automate model updates based on changes in
[apify-api/openapi](https://github.com/apify/apify-docs/tree/master/apify-api/openapi).
- This will be released as part of the Apify client v3.0.

Author: vdusek

.github/workflows/_tests.yaml

@@ -20,7 +20,7 @@ jobs:
       operating_systems: '["ubuntu-latest", "windows-latest"]'
       python_version_for_codecov: "3.14"
       operating_system_for_codecov: ubuntu-latest
-      tests_concurrency: "1"
+      tests_concurrency: "16"
 
   integration_tests:
     name: Integration tests
@@ -36,4 +36,4 @@ jobs:
       operating_systems: '["ubuntu-latest"]'
       python_version_for_codecov: "3.14"
       operating_system_for_codecov: ubuntu-latest
-      tests_concurrency: "1"
+      tests_concurrency: "16"

datamodel_codegen_aliases.json

@@ -0,0 +1,3 @@
+{
+    "gitHubGistUrl": "github_gist_url"
+}

docs/01_overview/code/01_usage_async.py

@@ -16,6 +16,6 @@ async def main() -> None:
         return
 
     # Fetch results from the Actor run's default dataset.
-    dataset_client = apify_client.dataset(call_result['defaultDatasetId'])
+    dataset_client = apify_client.dataset(call_result.default_dataset_id)
     list_items_result = await dataset_client.list_items()
     print(f'Dataset: {list_items_result}')

docs/01_overview/code/01_usage_sync.py

@@ -16,6 +16,6 @@ def main() -> None:
         return
 
     # Fetch results from the Actor run's default dataset.
-    dataset_client = apify_client.dataset(call_result['defaultDatasetId'])
+    dataset_client = apify_client.dataset(call_result.default_dataset_id)
     list_items_result = dataset_client.list_items()
     print(f'Dataset: {list_items_result}')

docs/02_concepts/code/01_async_support.py

@@ -11,7 +11,7 @@ async def main() -> None:
 
     # Start the Actor and get the run ID
     run_result = await actor_client.start()
-    run_client = apify_client.run(run_result['id'])
+    run_client = apify_client.run(run_result.id)
     log_client = run_client.log()
 
     # Stream the logs

docs/02_concepts/code/05_retries_async.py

@@ -1,3 +1,5 @@
+from datetime import timedelta
+
 from apify_client import ApifyClientAsync
 
 TOKEN = 'MY-APIFY-TOKEN'
@@ -7,6 +9,6 @@ async def main() -> None:
     apify_client = ApifyClientAsync(
         token=TOKEN,
         max_retries=8,
-        min_delay_between_retries_millis=500,  # 0.5s
-        timeout_secs=360,  # 6 mins
+        min_delay_between_retries=timedelta(milliseconds=500),
+        timeout=timedelta(seconds=360),
     )

docs/02_concepts/code/05_retries_sync.py

@@ -1,12 +1,14 @@
+from datetime import timedelta
+
 from apify_client import ApifyClient
 
 TOKEN = 'MY-APIFY-TOKEN'
 
 
-async def main() -> None:
+def main() -> None:
     apify_client = ApifyClient(
         token=TOKEN,
         max_retries=8,
-        min_delay_between_retries_millis=500,  # 0.5s
-        timeout_secs=360,  # 6 mins
+        min_delay_between_retries=timedelta(milliseconds=500),
+        timeout=timedelta(seconds=360),
     )

docs/03_examples/code/01_input_async.py

@@ -1,4 +1,5 @@
 import asyncio
+from datetime import timedelta
 
 from apify_client import ApifyClientAsync
 
@@ -16,7 +17,9 @@ async def main() -> None:
 
     # Run the Actor and wait for it to finish up to 60 seconds.
     # Input is not persisted for next runs.
-    run_result = await actor_client.call(run_input=input_data, timeout_secs=60)
+    run_result = await actor_client.call(
+        run_input=input_data, timeout=timedelta(seconds=60)
+    )
 
 
 if __name__ == '__main__':

docs/03_examples/code/01_input_sync.py

@@ -1,3 +1,5 @@
+from datetime import timedelta
+
 from apify_client import ApifyClient
 
 TOKEN = 'MY-APIFY-TOKEN'
@@ -14,7 +16,7 @@ def main() -> None:
 
     # Run the Actor and wait for it to finish up to 60 seconds.
     # Input is not persisted for next runs.
-    run_result = actor_client.call(run_input=input_data, timeout_secs=60)
+    run_result = actor_client.call(run_input=input_data, timeout=timedelta(seconds=60))
 
 
 if __name__ == '__main__':

docs/03_examples/code/02_tasks_async.py

@@ -1,22 +1,16 @@
 import asyncio
 
 from apify_client import ApifyClientAsync
-from apify_client.clients.resource_clients import TaskClientAsync
 
 TOKEN = 'MY-APIFY-TOKEN'
 HASHTAGS = ['zebra', 'lion', 'hippo']
 
 
-async def run_apify_task(client: TaskClientAsync) -> dict:
-    result = await client.call()
-    return result or {}
-
-
 async def main() -> None:
     apify_client = ApifyClientAsync(token=TOKEN)
 
     # Create Apify tasks
-    apify_tasks = list[dict]()
+    apify_tasks = []
     apify_tasks_client = apify_client.tasks()
 
     for hashtag in HASHTAGS:
@@ -31,20 +25,19 @@ async def main() -> None:
     print('Tasks created:', apify_tasks)
 
     # Create Apify task clients
-    apify_task_clients = list[TaskClientAsync]()
-
-    for apify_task in apify_tasks:
-        task_id = apify_task['id']
-        apify_task_client = apify_client.task(task_id)
-        apify_task_clients.append(apify_task_client)
+    apify_task_clients = [apify_client.task(task.id) for task in apify_tasks]
 
     print('Task clients created:', apify_task_clients)
 
     # Execute Apify tasks
-    run_apify_tasks = [run_apify_task(client) for client in apify_task_clients]
-    task_run_results = await asyncio.gather(*run_apify_tasks)
+    task_run_results = await asyncio.gather(
+        *[client.call() for client in apify_task_clients]
+    )
+
+    # Filter out None results (tasks that failed to return a run)
+    successful_runs = [run for run in task_run_results if run is not None]
 
-    print('Task results:', task_run_results)
+    print('Task results:', successful_runs)
 
 
 if __name__ == '__main__':