Skip to content

Commit 0616e1a

Browse files
authored
fix: rename build_tag to build in validate_input() (#1110)
`ActorClient.validate_input()` and its async twin now take the build as `build`, the same name `start()`, `call()` and the JS client's `validateInput()` use. `build_tag` still works as a deprecated alias. It emits a `DeprecationWarning` and will be removed in v4. Passing both `build` and `build_tag` raises a `ValueError`. The warning uses `stacklevel=3` because the logging wrapper adds a frame, so it points at the caller's code. Closes: #1091 *✍️ Drafted by Claude Code*
1 parent 1d1e9f6 commit 0616e1a

2 files changed

Lines changed: 114 additions & 6 deletions

File tree

‎src/apify_client/_resource_clients/actor.py‎

Lines changed: 33 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from __future__ import annotations
22

3+
import warnings
34
from typing import TYPE_CHECKING, Any, Literal
45

56
from pydantic import TypeAdapter
@@ -575,9 +576,10 @@ def validate_input(
575576
self,
576577
run_input: Any = None,
577578
*,
578-
build_tag: str | None = None,
579+
build: str | None = None,
579580
content_type: str | None = None,
580581
timeout: Timeout = 'short',
582+
build_tag: str | None = None,
581583
) -> bool:
582584
"""Validate an input for the Actor that defines an input schema.
583585
@@ -586,21 +588,33 @@ def validate_input(
586588
including an `io.IOBase` stream such as an open file, an iterable of byte chunks, or a streamed
587589
`HttpResponse`, which are uploaded in chunks without being held in memory. Streaming is experimental,
588590
and its behavior may change in future versions.
589-
build_tag: The Actor's build tag.
591+
build: The Actor build to validate the input against. It can be either a build tag or build number. By
592+
default, the build specified in the default run configuration for the Actor (typically latest) is used.
590593
content_type: The content type of the input.
591594
timeout: Timeout for the API HTTP request.
595+
build_tag: Deprecated alias of `build`. Will be removed in v4.
592596
593597
Returns:
594598
True if the input is valid, else raise an exception with validation error details.
595599
"""
600+
if build_tag is not None:
601+
warnings.warn(
602+
'The `build_tag` argument is deprecated and will be removed in v4. Use `build` instead.',
603+
DeprecationWarning,
604+
stacklevel=3,
605+
)
606+
if build is not None:
607+
raise ValueError('Pass only one of `build` and `build_tag`.')
608+
build = build_tag
609+
596610
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
597611

598612
self._http_client.call(
599613
url=self._build_url('validate-input'),
600614
method='POST',
601615
headers={'content-type': content_type},
602616
data=run_input,
603-
params=self._build_params(build=build_tag),
617+
params=self._build_params(build=build),
604618
timeout=timeout,
605619
)
606620

@@ -1118,9 +1132,10 @@ async def validate_input(
11181132
self,
11191133
run_input: Any = None,
11201134
*,
1121-
build_tag: str | None = None,
1135+
build: str | None = None,
11221136
content_type: str | None = None,
11231137
timeout: Timeout = 'short',
1138+
build_tag: str | None = None,
11241139
) -> bool:
11251140
"""Validate an input for the Actor that defines an input schema.
11261141
@@ -1129,21 +1144,33 @@ async def validate_input(
11291144
including an `io.IOBase` stream such as an open file, an iterable of byte chunks, or a streamed
11301145
`HttpResponse`, which are uploaded in chunks without being held in memory. Streaming is experimental,
11311146
and its behavior may change in future versions.
1132-
build_tag: The Actor's build tag.
1147+
build: The Actor build to validate the input against. It can be either a build tag or build number. By
1148+
default, the build specified in the default run configuration for the Actor (typically latest) is used.
11331149
content_type: The content type of the input.
11341150
timeout: Timeout for the API HTTP request.
1151+
build_tag: Deprecated alias of `build`. Will be removed in v4.
11351152
11361153
Returns:
11371154
True if the input is valid, else raise an exception with validation error details.
11381155
"""
1156+
if build_tag is not None:
1157+
warnings.warn(
1158+
'The `build_tag` argument is deprecated and will be removed in v4. Use `build` instead.',
1159+
DeprecationWarning,
1160+
stacklevel=3,
1161+
)
1162+
if build is not None:
1163+
raise ValueError('Pass only one of `build` and `build_tag`.')
1164+
build = build_tag
1165+
11391166
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
11401167

11411168
await self._http_client.call(
11421169
url=self._build_url('validate-input'),
11431170
method='POST',
11441171
headers={'content-type': content_type},
11451172
data=run_input,
1146-
params=self._build_params(build=build_tag),
1173+
params=self._build_params(build=build),
11471174
timeout=timeout,
11481175
)
11491176

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
from __future__ import annotations
2+
3+
from typing import TYPE_CHECKING
4+
5+
import pytest
6+
7+
from apify_client import ApifyClient, ApifyClientAsync
8+
9+
if TYPE_CHECKING:
10+
from pytest_httpserver import HTTPServer
11+
12+
pytestmark = pytest.mark.usefixtures('http_client_classes')
13+
14+
ACTOR_ID = 'test_actor_id'
15+
16+
17+
def expect_validate_input(httpserver: HTTPServer, build: str) -> str:
18+
httpserver.expect_request(
19+
f'/v2/actors/{ACTOR_ID}/validate-input',
20+
method='POST',
21+
query_string={'build': build},
22+
).respond_with_json({'valid': True})
23+
return httpserver.url_for('/').removesuffix('/')
24+
25+
26+
def test_validate_input_passes_build_sync(httpserver: HTTPServer) -> None:
27+
"""`build` is sent as the `build` query parameter."""
28+
client = ApifyClient(token='test_token', api_url=expect_validate_input(httpserver, '1.2.3'))
29+
30+
assert client.actor(ACTOR_ID).validate_input({}, build='1.2.3') is True
31+
httpserver.check_assertions()
32+
33+
34+
async def test_validate_input_passes_build_async(httpserver: HTTPServer) -> None:
35+
"""`build` is sent as the `build` query parameter."""
36+
client = ApifyClientAsync(token='test_token', api_url=expect_validate_input(httpserver, '1.2.3'))
37+
38+
assert await client.actor(ACTOR_ID).validate_input({}, build='1.2.3') is True
39+
httpserver.check_assertions()
40+
41+
42+
def test_validate_input_build_tag_is_deprecated_alias_sync(httpserver: HTTPServer) -> None:
43+
"""The deprecated `build_tag` emits a `DeprecationWarning` pointing at the caller and is sent as `build`."""
44+
client = ApifyClient(token='test_token', api_url=expect_validate_input(httpserver, 'beta'))
45+
46+
with pytest.warns(DeprecationWarning, match='`build_tag` argument is deprecated') as record:
47+
assert client.actor(ACTOR_ID).validate_input({}, build_tag='beta') is True
48+
assert record[0].filename == __file__
49+
httpserver.check_assertions()
50+
51+
52+
async def test_validate_input_build_tag_is_deprecated_alias_async(httpserver: HTTPServer) -> None:
53+
"""The deprecated `build_tag` emits a `DeprecationWarning` pointing at the caller and is sent as `build`."""
54+
client = ApifyClientAsync(token='test_token', api_url=expect_validate_input(httpserver, 'beta'))
55+
56+
with pytest.warns(DeprecationWarning, match='`build_tag` argument is deprecated') as record:
57+
assert await client.actor(ACTOR_ID).validate_input({}, build_tag='beta') is True
58+
assert record[0].filename == __file__
59+
httpserver.check_assertions()
60+
61+
62+
def test_validate_input_rejects_build_and_build_tag_sync() -> None:
63+
"""Passing both `build` and `build_tag` raises a `ValueError`."""
64+
client = ApifyClient(token='test_token')
65+
66+
with (
67+
pytest.warns(DeprecationWarning, match='`build_tag` argument is deprecated'),
68+
pytest.raises(ValueError, match='only one of'),
69+
):
70+
client.actor(ACTOR_ID).validate_input({}, build='latest', build_tag='beta')
71+
72+
73+
async def test_validate_input_rejects_build_and_build_tag_async() -> None:
74+
"""Passing both `build` and `build_tag` raises a `ValueError`."""
75+
client = ApifyClientAsync(token='test_token')
76+
77+
with (
78+
pytest.warns(DeprecationWarning, match='`build_tag` argument is deprecated'),
79+
pytest.raises(ValueError, match='only one of'),
80+
):
81+
await client.actor(ACTOR_ID).validate_input({}, build='latest', build_tag='beta')

0 commit comments

Comments
 (0)