Skip to content

Commit 2d123f3

Browse files
committed
Naming
1 parent 3f395a2 commit 2d123f3

30 files changed

Lines changed: 270 additions & 276 deletions
Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,14 @@ def __await__(self) -> Generator[Any, None, T]:
4646
return (yield from self._task.__await__())
4747

4848

49-
def build_iterable_list_page(
49+
def build_get_iterator(
5050
callback: Callable[..., HasItems[T]],
5151
first_page: HasItems[T],
5252
**kwargs: Any,
5353
) -> Callable[[], Iterator[T]]:
54-
"""Build an `IterableListPage` from a paginated sync callback.
54+
"""Build a factory for `Iterator` to yield items across paginated API calls.
5555
56-
The callback is invoked once immediately to fetch the first page, and again lazily during
57-
iteration to fetch further pages.
56+
The callback is invoked to lazy fetch items from API.
5857
5958
There are several optional kwargs that control the pagination, but not all are accepted on each paginated endpoint.
6059
Some endpoints do not return all paginated metadata, so the implementation should be resilient to missing fields,
@@ -96,16 +95,14 @@ def get_iterator() -> Iterator[T]:
9695
return get_iterator
9796

9897

99-
def build_iterable_list_page_async(
98+
def build_get_iterator_async(
10099
callback: Callable[..., Coroutine[Any, Any, HasItems[T]]],
101100
fetch_first_page: Awaitable[HasItems[T]],
102101
**kwargs: Any,
103102
) -> Callable[[], AsyncIterator[T]]:
104-
"""Build an `IterableListPageAsync` from a paginated async callback.
103+
"""Build a factory for `AsyncIterator` to yield items across paginated API calls.
105104
106-
Mirrors `build_iterable_list_page` but for async callbacks. The returned object is both
107-
awaitable (resolves to the first page wrapped in `IterableListPage`) and asynchronously
108-
iterable (yields items across pages).
105+
Mirrors `build_get_iterator` but for async callbacks.
109106
"""
110107
chunk_size = kwargs.pop('chunk_size', 0) or 0
111108
offset = kwargs.get('offset') or 0
@@ -131,7 +128,7 @@ async def get_async_iterator() -> AsyncIterator[T]:
131128
return get_async_iterator
132129

133130

134-
def build_cursor_iterable_list_page(
131+
def build_get_cursor_iterator(
135132
callback: Callable[..., HasItems[T]],
136133
first_page: HasItems[T],
137134
*,
@@ -140,7 +137,9 @@ def build_cursor_iterable_list_page(
140137
chunk_size: int | None = None,
141138
**kwargs: Any,
142139
) -> Callable[[], Iterator[T]]:
143-
"""Build the iterator factory for endpoints that paginate with a cursor instead of an offset.
140+
"""Build a factory for `Iterator` to yield items across paginated API calls.
141+
142+
Mirrors `build_get_iterator` but with cursor based pagination.
144143
145144
The caller is responsible for fetching the first page (typically by calling `callback` with
146145
the initial cursor). After each page, `getattr(page, f'next_{cursor_param}')` is consulted
@@ -168,7 +167,7 @@ def get_iterator() -> Iterator[T]:
168167
return get_iterator
169168

170169

171-
def build_cursor_iterable_list_page_async(
170+
def build_get_cursor_iterator_async(
172171
callback: Callable[..., Coroutine[Any, Any, HasItems[T]]],
173172
fetch_first_page: Awaitable[HasItems[T]],
174173
*,
@@ -177,10 +176,9 @@ def build_cursor_iterable_list_page_async(
177176
chunk_size: int | None = None,
178177
**kwargs: Any,
179178
) -> Callable[[], AsyncIterator[T]]:
180-
"""Build the async iterator factory for endpoints that paginate with a cursor instead of an offset.
179+
"""Build a factory for `Iterator` to yield items across paginated API calls.
181180
182-
Mirrors `build_cursor_iterable_list_page` but for async callbacks. The caller is responsible
183-
for awaiting the first page (typically through a `_LazyTask` wrapping the initial callback).
181+
Mirrors `build_get_cursor_iterator` but for async callbacks.
184182
"""
185183
effective_chunk = chunk_size or 0
186184
user_limit = limit or 0

‎src/apify_client/_pagination_classes.py‎

Lines changed: 41 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@
2828

2929

3030
@dataclass
31-
class IterablePage(Generic[T]):
31+
class IterableOf(Generic[T]):
3232
_get_iterator: Callable[[], Iterator[T]] = field(repr=False, compare=False)
3333

3434
def __iter__(self) -> Iterator[T]:
3535
return self._get_iterator()
3636

3737

3838
@dataclass
39-
class IterablePageAsync(Generic[T]):
39+
class AsyncIterableOf(Generic[T]):
4040
_get_async_iterator: Callable[[], AsyncIterator[T]] = field(repr=False, compare=False)
4141

4242
def __aiter__(self) -> AsyncIterator[T]:
@@ -74,17 +74,15 @@ class PageWithDesc(Generic[T]):
7474

7575

7676
@dataclass
77-
class PaginatedPage(PageWithItems[T], PageWithTotal, PageWithLimit, PageWithCount, PageWithOffset, PageWithDesc): ...
77+
class PageOfItems(PageWithItems[T], PageWithTotal, PageWithLimit, PageWithCount, PageWithOffset, PageWithDesc): ...
7878

7979

8080
@dataclass
81-
class PaginatedPageOnlyTotal(PageWithItems[T], PageWithTotal): ...
81+
class PageOfDatasetItems(PageOfItems[dict[str, Any]]): ...
8282

8383

8484
@dataclass
85-
class PageOfDatasetItems(
86-
PageWithItems[dict[str, Any]], PageWithLimit, PageWithCount, PageWithOffset, PageWithTotal, PageWithDesc
87-
): ...
85+
class PageOfItemsOnlyTotal(PageWithItems[T], PageWithTotal): ...
8886

8987

9088
@dataclass
@@ -103,17 +101,17 @@ class PageOfKeys(PageWithItems[KeyValueStoreKey], PageWithLimit, PageWithCount):
103101

104102
@dataclass
105103
class AwaitablePage(Generic[T]):
106-
_awaitable_first_page: Awaitable[PaginatedPage[T]] = field(repr=False, compare=False)
104+
_awaitable_first_page: Awaitable[PageOfItems[T]] = field(repr=False, compare=False)
107105

108-
def __await__(self) -> Generator[Any, Any, PaginatedPage[T]]:
106+
def __await__(self) -> Generator[Any, Any, PageOfItems[T]]:
109107
return self._awaitable_first_page.__await__()
110108

111109

112110
@dataclass
113111
class AwaitablePageOnlyTotal(Generic[T]):
114-
_awaitable_first_page: Awaitable[PaginatedPageOnlyTotal[T]] = field(repr=False, compare=False)
112+
_awaitable_first_page: Awaitable[PageOfItemsOnlyTotal[T]] = field(repr=False, compare=False)
115113

116-
def __await__(self) -> Generator[Any, Any, PaginatedPageOnlyTotal[T]]:
114+
def __await__(self) -> Generator[Any, Any, PageOfItemsOnlyTotal[T]]:
117115
return self._awaitable_first_page.__await__()
118116

119117

@@ -142,128 +140,128 @@ def __await__(self) -> Generator[Any, Any, PageOfKeys]:
142140

143141

144142
@dataclass
145-
class ListPageOfActors(PaginatedPage[ActorShort], IterablePage[ActorShort]): ...
143+
class ListPageOfActors(PageOfItems[ActorShort], IterableOf[ActorShort]): ...
146144

147145

148146
@dataclass
149-
class ListPageOfActorsAsync(IterablePageAsync[ActorShort], AwaitablePage[ActorShort]): ...
147+
class ListPageOfActorsAsync(AsyncIterableOf[ActorShort], AwaitablePage[ActorShort]): ...
150148

151149

152150
@dataclass
153-
class ListPageOfBuilds(PaginatedPage[BuildShort], IterablePage[BuildShort]): ...
151+
class ListPageOfBuilds(PageOfItems[BuildShort], IterableOf[BuildShort]): ...
154152

155153

156154
@dataclass
157-
class ListPageOfBuildsAsync(IterablePageAsync[BuildShort], AwaitablePage[BuildShort]): ...
155+
class ListPageOfBuildsAsync(AsyncIterableOf[BuildShort], AwaitablePage[BuildShort]): ...
158156

159157

160158
@dataclass
161-
class ListPageOfDatasets(PaginatedPage[DatasetListItem], IterablePage[DatasetListItem]): ...
159+
class ListPageOfDatasets(PageOfItems[DatasetListItem], IterableOf[DatasetListItem]): ...
162160

163161

164162
@dataclass
165-
class ListPageOfDatasetsAsync(IterablePageAsync[DatasetListItem], AwaitablePage[DatasetListItem]): ...
163+
class ListPageOfDatasetsAsync(AsyncIterableOf[DatasetListItem], AwaitablePage[DatasetListItem]): ...
166164

167165

168166
@dataclass
169-
class ListPageOfDatasetItems(PageOfDatasetItems, IterablePage[dict[str, Any]]): ...
167+
class ListPageOfDatasetItems(PageOfDatasetItems, IterableOf[dict[str, Any]]): ...
170168

171169

172170
@dataclass
173-
class ListPageOfDatasetItemsAsync(IterablePageAsync[dict[str, Any]], AwaitablePageOfDatasetItems): ...
171+
class ListPageOfDatasetItemsAsync(AsyncIterableOf[dict[str, Any]], AwaitablePageOfDatasetItems): ...
174172

175173

176174
@dataclass
177-
class ListPageOfKeyValueStores(PaginatedPage[KeyValueStore], IterablePage[KeyValueStore]): ...
175+
class ListPageOfKeyValueStores(PageOfItems[KeyValueStore], IterableOf[KeyValueStore]): ...
178176

179177

180178
@dataclass
181-
class ListPageOfKeyValueStoresAsync(IterablePageAsync[KeyValueStore], AwaitablePage[KeyValueStore]): ...
179+
class ListPageOfKeyValueStoresAsync(AsyncIterableOf[KeyValueStore], AwaitablePage[KeyValueStore]): ...
182180

183181

184182
@dataclass
185-
class ListPageOfRequestQueues(PaginatedPage[RequestQueueShort], IterablePage[RequestQueueShort]): ...
183+
class ListPageOfRequestQueues(PageOfItems[RequestQueueShort], IterableOf[RequestQueueShort]): ...
186184

187185

188186
@dataclass
189-
class ListPageOfRequestQueuesAsync(IterablePageAsync[RequestQueueShort], AwaitablePage[RequestQueueShort]): ...
187+
class ListPageOfRequestQueuesAsync(AsyncIterableOf[RequestQueueShort], AwaitablePage[RequestQueueShort]): ...
190188

191189

192190
@dataclass
193-
class ListPageOfRuns(PaginatedPage[RunShort], IterablePage[RunShort]): ...
191+
class ListPageOfRuns(PageOfItems[RunShort], IterableOf[RunShort]): ...
194192

195193

196194
@dataclass
197-
class ListPageOfRunsAsync(IterablePageAsync[RunShort], AwaitablePage[RunShort]): ...
195+
class ListPageOfRunsAsync(AsyncIterableOf[RunShort], AwaitablePage[RunShort]): ...
198196

199197

200198
@dataclass
201-
class ListPageOfSchedules(PaginatedPage[ScheduleShort], IterablePage[ScheduleShort]): ...
199+
class ListPageOfSchedules(PageOfItems[ScheduleShort], IterableOf[ScheduleShort]): ...
202200

203201

204202
@dataclass
205-
class ListPageOfSchedulesAsync(IterablePageAsync[ScheduleShort], AwaitablePage[ScheduleShort]): ...
203+
class ListPageOfSchedulesAsync(AsyncIterableOf[ScheduleShort], AwaitablePage[ScheduleShort]): ...
206204

207205

208206
@dataclass
209-
class ListPageOfStoreActors(PaginatedPage[StoreListActor], IterablePage[StoreListActor]): ...
207+
class ListPageOfStoreActors(PageOfItems[StoreListActor], IterableOf[StoreListActor]): ...
210208

211209

212210
@dataclass
213-
class ListPageOfStoreActorsAsync(IterablePageAsync[StoreListActor], AwaitablePage[StoreListActor]): ...
211+
class ListPageOfStoreActorsAsync(AsyncIterableOf[StoreListActor], AwaitablePage[StoreListActor]): ...
214212

215213

216214
@dataclass
217-
class ListPageOfTasks(PaginatedPage[TaskShort], IterablePage[TaskShort]): ...
215+
class ListPageOfTasks(PageOfItems[TaskShort], IterableOf[TaskShort]): ...
218216

219217

220218
@dataclass
221-
class ListPageOfTasksAsync(IterablePageAsync[TaskShort], AwaitablePage[TaskShort]): ...
219+
class ListPageOfTasksAsync(AsyncIterableOf[TaskShort], AwaitablePage[TaskShort]): ...
222220

223221

224222
@dataclass
225-
class ListPageOfWebhookDispatches(PaginatedPage[WebhookDispatch], IterablePage[WebhookDispatch]): ...
223+
class ListPageOfWebhookDispatches(PageOfItems[WebhookDispatch], IterableOf[WebhookDispatch]): ...
226224

227225

228226
@dataclass
229-
class ListPageOfWebhookDispatchesAsync(IterablePageAsync[WebhookDispatch], AwaitablePage[WebhookDispatch]): ...
227+
class ListPageOfWebhookDispatchesAsync(AsyncIterableOf[WebhookDispatch], AwaitablePage[WebhookDispatch]): ...
230228

231229

232230
@dataclass
233-
class ListPageOfWebhooks(PaginatedPage[WebhookShort], IterablePage[WebhookShort]): ...
231+
class ListPageOfWebhooks(PageOfItems[WebhookShort], IterableOf[WebhookShort]): ...
234232

235233

236234
@dataclass
237-
class ListPageOfWebhooksAsync(IterablePageAsync[WebhookShort], AwaitablePage[WebhookShort]): ...
235+
class ListPageOfWebhooksAsync(AsyncIterableOf[WebhookShort], AwaitablePage[WebhookShort]): ...
238236

239237

240238
@dataclass
241-
class ListPageOfEnvVars(IterablePage[EnvVar], PaginatedPageOnlyTotal): ...
239+
class ListPageOfEnvVars(IterableOf[EnvVar], PageOfItemsOnlyTotal): ...
242240

243241

244242
@dataclass
245-
class ListPageOfEnvVarsAsync(IterablePageAsync[EnvVar], AwaitablePageOnlyTotal[EnvVar]): ...
243+
class ListPageOfEnvVarsAsync(AsyncIterableOf[EnvVar], AwaitablePageOnlyTotal[EnvVar]): ...
246244

247245

248246
@dataclass
249-
class ListPageOfVersions(IterablePage[Version], PaginatedPageOnlyTotal): ...
247+
class ListPageOfVersions(IterableOf[Version], PageOfItemsOnlyTotal): ...
250248

251249

252250
@dataclass
253-
class ListPageOfVersionsAsync(IterablePageAsync[Version], AwaitablePageOnlyTotal[Version]): ...
251+
class ListPageOfVersionsAsync(AsyncIterableOf[Version], AwaitablePageOnlyTotal[Version]): ...
254252

255253

256254
@dataclass
257-
class ListPageOfRequests(PageOfRequests, IterablePage[Request]): ...
255+
class ListPageOfRequests(PageOfRequests, IterableOf[Request]): ...
258256

259257

260258
@dataclass
261-
class ListPageOfRequestsAsync(IterablePageAsync[Request], AwaitablePageOfRequests): ...
259+
class ListPageOfRequestsAsync(AsyncIterableOf[Request], AwaitablePageOfRequests): ...
262260

263261

264262
@dataclass
265-
class ListPageOfKeys(PageOfKeys, IterablePage[KeyValueStoreKey]): ...
263+
class ListPageOfKeys(PageOfKeys, IterableOf[KeyValueStoreKey]): ...
266264

267265

268266
@dataclass
269-
class ListPageOfKeysAsync(IterablePageAsync[KeyValueStoreKey], AwaitablePageOfKeys): ...
267+
class ListPageOfKeysAsync(AsyncIterableOf[KeyValueStoreKey], AwaitablePageOfKeys): ...

‎src/apify_client/_resource_clients/actor_collection.py‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,6 @@
33
from typing import TYPE_CHECKING, Any, Literal
44

55
from apify_client._docs import docs_group
6-
from apify_client._iterable_list_page import (
7-
_LazyTask,
8-
build_iterable_list_page,
9-
build_iterable_list_page_async,
10-
)
116
from apify_client._models_generated import (
127
Actor,
138
ActorResponse,
@@ -17,10 +12,15 @@
1712
ExampleRunInput,
1813
ListOfActorsResponse,
1914
)
15+
from apify_client._pagination import (
16+
_LazyTask,
17+
build_get_iterator,
18+
build_get_iterator_async,
19+
)
2020
from apify_client._pagination_classes import (
2121
ListPageOfActors,
2222
ListPageOfActorsAsync,
23-
PaginatedPage,
23+
PageOfItems,
2424
)
2525
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
2626
from apify_client._utils import to_seconds
@@ -86,10 +86,10 @@ def list(
8686
"""
8787
api_sort_by = _SORT_BY_TO_API[sort_by] if sort_by is not None else None
8888

89-
def _callback(**kwargs: Any) -> PaginatedPage[ActorShort]:
89+
def _callback(**kwargs: Any) -> PageOfItems[ActorShort]:
9090
result = self._list(timeout=timeout, my=my, sortBy=api_sort_by, **kwargs)
9191
data = ListOfActorsResponse.model_validate(result).data
92-
return PaginatedPage(
92+
return PageOfItems(
9393
items=data.items,
9494
count=data.count,
9595
limit=data.limit,
@@ -99,7 +99,7 @@ def _callback(**kwargs: Any) -> PaginatedPage[ActorShort]:
9999
)
100100

101101
first_page = _callback(limit=limit, offset=offset, desc=desc)
102-
get_iterator = build_iterable_list_page(_callback, first_page, limit=limit, offset=offset, desc=desc)
102+
get_iterator = build_get_iterator(_callback, first_page, limit=limit, offset=offset, desc=desc)
103103

104104
return ListPageOfActors(
105105
_get_iterator=get_iterator,
@@ -258,10 +258,10 @@ def list(
258258
"""
259259
api_sort_by = _SORT_BY_TO_API[sort_by] if sort_by is not None else None
260260

261-
async def _callback(**kwargs: Any) -> PaginatedPage[ActorShort]:
261+
async def _callback(**kwargs: Any) -> PageOfItems[ActorShort]:
262262
result = await self._list(timeout=timeout, my=my, sortBy=api_sort_by, **kwargs)
263263
data = ListOfActorsResponse.model_validate(result).data
264-
return PaginatedPage(
264+
return PageOfItems(
265265
items=data.items,
266266
count=data.count,
267267
limit=data.limit,
@@ -271,7 +271,7 @@ async def _callback(**kwargs: Any) -> PaginatedPage[ActorShort]:
271271
)
272272

273273
fetch_first_page = _LazyTask(_callback(limit=limit, offset=offset, desc=desc))
274-
get_async_iterator = build_iterable_list_page_async(
274+
get_async_iterator = build_get_iterator_async(
275275
_callback, fetch_first_page, limit=limit, offset=offset, desc=desc
276276
)
277277

0 commit comments

Comments
 (0)