feat: accept Pydantic models as alternatives to dicts in resource client methods

Update resource client methods to accept union types `dict | Model` for
input parameters, giving users IDE hints about expected fields without
requiring model imports. When a Pydantic model is passed, it is serialized
to dict for the API call. When a dict is passed, it is validated through
the model first.

Changes:
- task.py: `task_input: dict | TaskInput`, `webhooks: list[dict | WebhookCreate]`
- task_collection.py: `task_input: dict | TaskInput`
- request_queue.py: `request: dict | RequestDraft` (add), `dict | Request` (update),
  `requests: list[dict | RequestDraft]` (batch_add)
- actor.py: `webhooks: list[dict | WebhookCreate]`
- _utils.py: `encode_webhook_list_to_base64` accepts `WebhookCreate` models and
  `None` via @overload

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vdusek

src/apify_client/_resource_clients/actor.py

@@ -23,6 +23,7 @@
     RunOrigin,
     RunResponse,
     UpdateActorRequest,
+    WebhookCreate,
 )
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import (
@@ -224,7 +225,7 @@ def start(
         timeout: timedelta | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[dict] | None = None,
+        webhooks: list[dict | WebhookCreate] | None = None,
     ) -> Run:
         """Start the Actor and immediately return the Run object.
 
@@ -251,7 +252,7 @@ def start(
             webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
                 the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
                 If you already have a webhook set up for the Actor or task, you do not have to add it again here.
-                Each webhook is represented by a dictionary containing these items:
+                Each webhook is represented by a dictionary or `WebhookCreate` model containing these items:
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
@@ -270,7 +271,7 @@ def start(
             timeout=to_seconds(timeout, as_int=True),
             waitForFinish=wait_for_finish,
             forcePermissionLevel=force_permission_level.value if force_permission_level is not None else None,
-            webhooks=encode_webhook_list_to_base64(webhooks) if webhooks is not None else None,
+            webhooks=encode_webhook_list_to_base64(webhooks),
         )
 
         response = self._http_client.call(
@@ -295,7 +296,7 @@ def call(
         restart_on_error: bool | None = None,
         memory_mbytes: int | None = None,
         timeout: timedelta | None = None,
-        webhooks: list[dict] | None = None,
+        webhooks: list[dict | WebhookCreate] | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
         logger: Logger | None | Literal['default'] = 'default',
@@ -689,7 +690,7 @@ async def start(
         timeout: timedelta | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[dict] | None = None,
+        webhooks: list[dict | WebhookCreate] | None = None,
     ) -> Run:
         """Start the Actor and immediately return the Run object.
 
@@ -716,7 +717,7 @@ async def start(
             webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
                 the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
                 If you already have a webhook set up for the Actor or task, you do not have to add it again here.
-                Each webhook is represented by a dictionary containing these items:
+                Each webhook is represented by a dictionary or `WebhookCreate` model containing these items:
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
@@ -735,7 +736,7 @@ async def start(
             timeout=to_seconds(timeout, as_int=True),
             waitForFinish=wait_for_finish,
             forcePermissionLevel=force_permission_level.value if force_permission_level is not None else None,
-            webhooks=encode_webhook_list_to_base64(webhooks) if webhooks is not None else None,
+            webhooks=encode_webhook_list_to_base64(webhooks),
         )
 
         response = await self._http_client.call(
@@ -760,7 +761,7 @@ async def call(
         restart_on_error: bool | None = None,
         memory_mbytes: int | None = None,
         timeout: timedelta | None = None,
-        webhooks: list[dict] | None = None,
+        webhooks: list[dict | WebhookCreate] | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
         logger: Logger | None | Literal['default'] = 'default',

src/apify_client/_resource_clients/request_queue.py

@@ -166,24 +166,27 @@ def list_and_lock_head(self, *, lock_duration: timedelta, limit: int | None = No
         result = response_to_dict(response)
         return HeadAndLockResponse.model_validate(result).data
 
-    def add_request(self, request: dict, *, forefront: bool | None = None) -> RequestRegistration:
+    def add_request(self, request: dict | RequestDraft, *, forefront: bool | None = None) -> RequestRegistration:
         """Add a request to the queue.
 
         https://docs.apify.com/api/v2#/reference/request-queues/request-collection/add-request
 
         Args:
-            request: The request to add to the queue.
+            request: The request to add to the queue, as a dictionary or `RequestDraft` model.
             forefront: Whether to add the request to the head or the end of the queue.
 
         Returns:
             The added request.
         """
+        if isinstance(request, dict):
+            request = RequestDraft.model_validate(request)
+
         request_params = self._build_params(forefront=forefront, clientKey=self.client_key)
 
         response = self._http_client.call(
             url=self._build_url('requests'),
             method='POST',
-            json=request,
+            json=request.model_dump(by_alias=True, exclude_none=True),
             params=request_params,
             timeout=FAST_OPERATION_TIMEOUT,
         )
@@ -217,26 +220,29 @@ def get_request(self, request_id: str) -> Request | None:
 
         return None
 
-    def update_request(self, request: dict, *, forefront: bool | None = None) -> RequestRegistration:
+    def update_request(self, request: dict | Request, *, forefront: bool | None = None) -> RequestRegistration:
         """Update a request in the queue.
 
         https://docs.apify.com/api/v2#/reference/request-queues/request/update-request
 
         Args:
-            request: The updated request.
+            request: The updated request, as a dictionary or `Request` model.
             forefront: Whether to put the updated request in the beginning or the end of the queue.
 
         Returns:
             The updated request.
         """
-        request_id = request['id']
+        if isinstance(request, dict):
+            request = Request.model_validate(request)
+
+        request_id = request.id
 
         request_params = self._build_params(forefront=forefront, clientKey=self.client_key)
 
         response = self._http_client.call(
             url=self._build_url(f'requests/{request_id}'),
             method='PUT',
-            json=request,
+            json=request.model_dump(by_alias=True, exclude_none=True),
             params=request_params,
             timeout=STANDARD_OPERATION_TIMEOUT,
         )
@@ -315,7 +321,7 @@ def delete_request_lock(self, request_id: str, *, forefront: bool | None = None)
 
     def batch_add_requests(
         self,
-        requests: list[dict],
+        requests: list[dict | RequestDraft],
         *,
         forefront: bool = False,
         max_parallel: int = 1,
@@ -329,7 +335,7 @@ def batch_add_requests(
         https://docs.apify.com/api/v2#/reference/request-queues/batch-request-operations/add-requests
 
         Args:
-            requests: List of requests to be added to the queue.
+            requests: List of requests to be added to the queue, each as a dictionary or `RequestDraft` model.
             forefront: Whether to add requests to the front of the queue.
             max_parallel: Specifies the maximum number of parallel tasks for API calls. This is only applicable
                 to the async client. For the sync client, this value must be set to 1, as parallel execution
@@ -348,14 +354,19 @@ def batch_add_requests(
         if max_parallel != 1:
             raise NotImplementedError('max_parallel is only supported in async client')
 
+        requests_as_dicts: list[dict] = [
+            (RequestDraft.model_validate(r) if isinstance(r, dict) else r).model_dump(by_alias=True, exclude_none=True)
+            for r in requests
+        ]
+
         request_params = self._build_params(clientKey=self.client_key, forefront=forefront)
 
         # Compute the payload size limit to ensure it doesn't exceed the maximum allowed size.
         payload_size_limit_bytes = _MAX_PAYLOAD_SIZE_BYTES - math.ceil(_MAX_PAYLOAD_SIZE_BYTES * _SAFETY_BUFFER_PERCENT)
 
         # Split the requests into batches, constrained by the max payload size and max requests per batch.
         batches = constrained_batches(
-            requests,
+            requests_as_dicts,
             max_size=payload_size_limit_bytes,
             max_count=_RQ_MAX_REQUESTS_PER_BATCH,
         )
@@ -580,24 +591,27 @@ async def list_and_lock_head(self, *, lock_duration: timedelta, limit: int | Non
         result = response_to_dict(response)
         return HeadAndLockResponse.model_validate(result).data
 
-    async def add_request(self, request: dict, *, forefront: bool | None = None) -> RequestRegistration:
+    async def add_request(self, request: dict | RequestDraft, *, forefront: bool | None = None) -> RequestRegistration:
         """Add a request to the queue.
 
         https://docs.apify.com/api/v2#/reference/request-queues/request-collection/add-request
 
         Args:
-            request: The request to add to the queue.
+            request: The request to add to the queue, as a dictionary or `RequestDraft` model.
             forefront: Whether to add the request to the head or the end of the queue.
 
         Returns:
             The added request.
         """
+        if isinstance(request, dict):
+            request = RequestDraft.model_validate(request)
+
         request_params = self._build_params(forefront=forefront, clientKey=self.client_key)
 
         response = await self._http_client.call(
             url=self._build_url('requests'),
             method='POST',
-            json=request,
+            json=request.model_dump(by_alias=True, exclude_none=True),
             params=request_params,
             timeout=FAST_OPERATION_TIMEOUT,
         )
@@ -629,26 +643,29 @@ async def get_request(self, request_id: str) -> Request | None:
             catch_not_found_or_throw(exc)
             return None
 
-    async def update_request(self, request: dict, *, forefront: bool | None = None) -> RequestRegistration:
+    async def update_request(self, request: dict | Request, *, forefront: bool | None = None) -> RequestRegistration:
         """Update a request in the queue.
 
         https://docs.apify.com/api/v2#/reference/request-queues/request/update-request
 
         Args:
-            request: The updated request.
+            request: The updated request, as a dictionary or `Request` model.
             forefront: Whether to put the updated request in the beginning or the end of the queue.
 
         Returns:
             The updated request.
         """
-        request_id = request['id']
+        if isinstance(request, dict):
+            request = Request.model_validate(request)
+
+        request_id = request.id
 
         request_params = self._build_params(forefront=forefront, clientKey=self.client_key)
 
         response = await self._http_client.call(
             url=self._build_url(f'requests/{request_id}'),
             method='PUT',
-            json=request,
+            json=request.model_dump(by_alias=True, exclude_none=True),
             params=request_params,
             timeout=STANDARD_OPERATION_TIMEOUT,
         )
@@ -777,7 +794,7 @@ async def _batch_add_requests_worker(
 
     async def batch_add_requests(
         self,
-        requests: list[dict],
+        requests: list[dict | RequestDraft],
         *,
         forefront: bool = False,
         max_parallel: int = 5,
@@ -791,7 +808,7 @@ async def batch_add_requests(
         https://docs.apify.com/api/v2#/reference/request-queues/batch-request-operations/add-requests
 
         Args:
-            requests: List of requests to be added to the queue.
+            requests: List of requests to be added to the queue, each as a dictionary or `RequestDraft` model.
             forefront: Whether to add requests to the front of the queue.
             max_parallel: Specifies the maximum number of parallel tasks for API calls. This is only applicable
                 to the async client. For the sync client, this value must be set to 1, as parallel execution
@@ -807,6 +824,11 @@ async def batch_add_requests(
         if min_delay_between_unprocessed_requests_retries:
             logger.warning('`min_delay_between_unprocessed_requests_retries` is deprecated and not used anymore.')
 
+        requests_as_dicts: list[dict] = [
+            (RequestDraft.model_validate(r) if isinstance(r, dict) else r).model_dump(by_alias=True, exclude_none=True)
+            for r in requests
+        ]
+
         asyncio_queue: asyncio.Queue[Iterable[dict]] = asyncio.Queue()
         request_params = self._build_params(clientKey=self.client_key, forefront=forefront)
 
@@ -815,7 +837,7 @@ async def batch_add_requests(
 
         # Split the requests into batches, constrained by the max payload size and max requests per batch.
         batches = constrained_batches(
-            requests,
+            requests_as_dicts,
             max_size=payload_size_limit_bytes,
             max_count=_RQ_MAX_REQUESTS_PER_BATCH,
         )