Skip to content

Lists

Service for managing lists.

Lists are spreadsheet-like collections of people, companies, or opportunities.

Source code in affinity/services/lists.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
class ListService:
    """
    Service for managing lists.

    Lists are spreadsheet-like collections of people, companies, or opportunities.
    """

    def __init__(self, client: HTTPClient):
        self._client = client
        self._resolve_cache: dict[tuple[str, ListType | None], AffinityList | None] = {}
        self._size_cache: dict[ListId, tuple[float, int]] = {}  # (timestamp, size)

    def entries(self, list_id: ListId) -> ListEntryService:
        """
        Get a ListEntryService for a specific list.

        This is the explicit path for retrieving "full row" data via list entries.
        """
        return ListEntryService(self._client, list_id)

    # =========================================================================
    # List Operations (V2 for read, V1 for write)
    # =========================================================================

    def list(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[AffinityList]:
        """
        Get all lists accessible to you.

        Args:
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).

        Returns:
            Paginated list of lists (without field metadata)
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            data = self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = self._client.get("/lists", params=params or None)

        return PaginatedResponse[AffinityList](
            data=[
                _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
            ],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    def get_first(self) -> AffinityList | None:
        """Get the first list, or None if no lists exist."""
        page = self.list(limit=1)
        return page.data[0] if page.data else None

    def pages(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> Iterator[PaginatedResponse[AffinityList]]:
        """
        Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

        This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
        """
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = self.list(limit=limit) if cursor is None else self.list(cursor=cursor)
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = self.list(cursor=next_cursor)

    def all(self) -> Iterator[AffinityList]:
        """Iterate through all accessible lists."""

        def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
            if next_url:
                data = self._client.get_url(next_url)
                return PaginatedResponse[AffinityList](
                    data=[
                        _safe_model_validate(AffinityList, list_item)
                        for list_item in data.get("data", [])
                    ],
                    pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
                )
            return self.list()

        return PageIterator(fetch_page)

    def iter(self) -> Iterator[AffinityList]:
        """
        Auto-paginate all lists.

        Alias for `all()` (FR-006 public contract).
        """
        return self.all()

    def get(self, list_id: ListId) -> AffinityList:
        """
        Get a single list by ID.

        Includes field metadata for the list.

        Note: Uses V1 API because V2's listSize field is undocumented and
        returns incorrect values (often 0 for non-empty lists).
        """
        data = self._client.get(f"/lists/{list_id}", v1=True)
        return _safe_model_validate(AffinityList, data)

    def get_size(self, list_id: ListId, *, force: bool = False) -> int:
        """
        Get accurate list size. Uses V1 API, cached for 5 minutes.

        Args:
            list_id: The list ID.
            force: If True, bypass cache and fetch fresh value from API.

        Note: The V2 API's listSize field is unreliable (often returns 0 for
        non-empty lists). This method uses the V1 API which returns accurate values.
        """
        if not force and list_id in self._size_cache:
            cached_at, size = self._size_cache[list_id]
            if time.monotonic() - cached_at < _SIZE_CACHE_TTL:
                return size

        lst = self.get(list_id)
        size = lst._list_size_hint
        self._size_cache[list_id] = (time.monotonic(), size)
        return size

    def resolve(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> AffinityList | None:
        """
        Find a single list by name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Results are cached in-memory on this service instance. If you call this frequently,
          reuse the client, or persist the resolved `ListId` in your own configuration.

        If multiple matches exist, returns the first match in server-provided order.
        """
        key = (name.lower(), list_type)
        if key in self._resolve_cache:
            return self._resolve_cache[key]

        for item in self.all():
            if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
                self._resolve_cache[key] = item
                return item

        self._resolve_cache[key] = None
        return None

    def resolve_all(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> builtins.list[AffinityList]:
        """
        Find all lists matching a name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Unlike `resolve()`, this does not cache results.
        """
        matches: builtins.list[AffinityList] = []
        name_lower = name.lower()
        for item in self.all():
            if item.name.lower() != name_lower:
                continue
            if list_type is not None and item.type != list_type:
                continue
            matches.append(item)
        return matches

    def create(self, data: ListCreate) -> AffinityList:
        """
        Create a new list.

        Uses V1 API.
        """
        payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
        if not data.additional_permissions:
            payload.pop("additional_permissions", None)

        result = self._client.post("/lists", json=payload, v1=True)

        # Invalidate cache
        if self._client.cache:
            self._client.cache.invalidate_prefix("list")
        self._resolve_cache.clear()

        return _safe_model_validate(AffinityList, result)

    # =========================================================================
    # Field Operations
    # =========================================================================

    def get_fields(
        self,
        list_id: ListId,
        *,
        field_types: Sequence[FieldType] | None = None,
    ) -> builtins.list[FieldMetadata]:
        """
        Get fields (columns) for a list.

        Includes list-specific, global, enriched, and relationship intelligence fields.
        Cached for performance.
        """
        params: dict[str, Any] = {}
        if field_types:
            params["fieldTypes"] = [field_type.value for field_type in field_types]

        data = self._client.get(
            f"/lists/{list_id}/fields",
            params=params or None,
            cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
            cache_ttl=300,
        )

        return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

    # =========================================================================
    # Saved View Operations
    # =========================================================================

    def get_saved_views(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[SavedView]:
        """
        Get saved views for a list.

        Args:
            list_id: List id for the initial request.
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            cursor_list_id = _saved_views_list_id_from_cursor(cursor)
            if cursor_list_id is not None and int(list_id) != cursor_list_id:
                raise ValueError(
                    f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                    f"requested list_id is {int(list_id)}"
                )
            data = self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

        return PaginatedResponse[SavedView](
            data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    def saved_views_pages(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> Iterator[PaginatedResponse[SavedView]]:
        """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = (
            self.get_saved_views(list_id, limit=limit)
            if cursor is None
            else self.get_saved_views(list_id, cursor=cursor)
        )
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = self.get_saved_views(list_id, cursor=next_cursor)

    def saved_views_all(self, list_id: ListId) -> Iterator[SavedView]:
        """Iterate all saved views for a list."""
        for page in self.saved_views_pages(list_id):
            yield from page.data

    def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
        """Get a single saved view."""
        data = self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
        return _safe_model_validate(SavedView, data)

all() -> Iterator[AffinityList]

Iterate through all accessible lists.

Source code in affinity/services/lists.py 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def all(self) -> Iterator[AffinityList]:
    """Iterate through all accessible lists."""

    def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
        if next_url:
            data = self._client.get_url(next_url)
            return PaginatedResponse[AffinityList](
                data=[
                    _safe_model_validate(AffinityList, list_item)
                    for list_item in data.get("data", [])
                ],
                pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
            )
        return self.list()

    return PageIterator(fetch_page)

create(data: ListCreate) -> AffinityList

Create a new list.

Uses V1 API.

Source code in affinity/services/lists.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
def create(self, data: ListCreate) -> AffinityList:
    """
    Create a new list.

    Uses V1 API.
    """
    payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
    if not data.additional_permissions:
        payload.pop("additional_permissions", None)

    result = self._client.post("/lists", json=payload, v1=True)

    # Invalidate cache
    if self._client.cache:
        self._client.cache.invalidate_prefix("list")
    self._resolve_cache.clear()

    return _safe_model_validate(AffinityList, result)

entries(list_id: ListId) -> ListEntryService

Get a ListEntryService for a specific list.

This is the explicit path for retrieving "full row" data via list entries.

Source code in affinity/services/lists.py 
121
122
123
124
125
126
127
def entries(self, list_id: ListId) -> ListEntryService:
    """
    Get a ListEntryService for a specific list.

    This is the explicit path for retrieving "full row" data via list entries.
    """
    return ListEntryService(self._client, list_id)

get(list_id: ListId) -> AffinityList

Get a single list by ID.

Includes field metadata for the list.

Note: Uses V1 API because V2's listSize field is undocumented and returns incorrect values (often 0 for non-empty lists).

Source code in affinity/services/lists.py 
230
231
232
233
234
235
236
237
238
239
240
def get(self, list_id: ListId) -> AffinityList:
    """
    Get a single list by ID.

    Includes field metadata for the list.

    Note: Uses V1 API because V2's listSize field is undocumented and
    returns incorrect values (often 0 for non-empty lists).
    """
    data = self._client.get(f"/lists/{list_id}", v1=True)
    return _safe_model_validate(AffinityList, data)

get_fields(list_id: ListId, *, field_types: Sequence[FieldType] | None = None) -> builtins.list[FieldMetadata]

Get fields (columns) for a list.

Includes list-specific, global, enriched, and relationship intelligence fields. Cached for performance.

Source code in affinity/services/lists.py 
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
def get_fields(
    self,
    list_id: ListId,
    *,
    field_types: Sequence[FieldType] | None = None,
) -> builtins.list[FieldMetadata]:
    """
    Get fields (columns) for a list.

    Includes list-specific, global, enriched, and relationship intelligence fields.
    Cached for performance.
    """
    params: dict[str, Any] = {}
    if field_types:
        params["fieldTypes"] = [field_type.value for field_type in field_types]

    data = self._client.get(
        f"/lists/{list_id}/fields",
        params=params or None,
        cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
        cache_ttl=300,
    )

    return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

get_first() -> AffinityList | None

Get the first list, or None if no lists exist.

Source code in affinity/services/lists.py 
172
173
174
175
def get_first(self) -> AffinityList | None:
    """Get the first list, or None if no lists exist."""
    page = self.list(limit=1)
    return page.data[0] if page.data else None

get_saved_view(list_id: ListId, view_id: SavedViewId) -> SavedView

Get a single saved view.

Source code in affinity/services/lists.py 
442
443
444
445
def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
    """Get a single saved view."""
    data = self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
    return _safe_model_validate(SavedView, data)

get_saved_views(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[SavedView]

Get saved views for a list.

Parameters:

Name Type Description Default
list_id ListId

List id for the initial request.

 required
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None
Source code in affinity/services/lists.py 
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
def get_saved_views(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[SavedView]:
    """
    Get saved views for a list.

    Args:
        list_id: List id for the initial request.
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        cursor_list_id = _saved_views_list_id_from_cursor(cursor)
        if cursor_list_id is not None and int(list_id) != cursor_list_id:
            raise ValueError(
                f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                f"requested list_id is {int(list_id)}"
            )
        data = self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

    return PaginatedResponse[SavedView](
        data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

get_size(list_id: ListId, *, force: bool = False) -> int

Get accurate list size. Uses V1 API, cached for 5 minutes.

Parameters:

Name Type Description Default
list_id ListId

The list ID.

 required
force bool

If True, bypass cache and fetch fresh value from API.

 False

Note: The V2 API's listSize field is unreliable (often returns 0 for non-empty lists). This method uses the V1 API which returns accurate values.

Source code in affinity/services/lists.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
def get_size(self, list_id: ListId, *, force: bool = False) -> int:
    """
    Get accurate list size. Uses V1 API, cached for 5 minutes.

    Args:
        list_id: The list ID.
        force: If True, bypass cache and fetch fresh value from API.

    Note: The V2 API's listSize field is unreliable (often returns 0 for
    non-empty lists). This method uses the V1 API which returns accurate values.
    """
    if not force and list_id in self._size_cache:
        cached_at, size = self._size_cache[list_id]
        if time.monotonic() - cached_at < _SIZE_CACHE_TTL:
            return size

    lst = self.get(list_id)
    size = lst._list_size_hint
    self._size_cache[list_id] = (time.monotonic(), size)
    return size

iter() -> Iterator[AffinityList]

Auto-paginate all lists.

Alias for all() (FR-006 public contract).

Source code in affinity/services/lists.py 
222
223
224
225
226
227
228
def iter(self) -> Iterator[AffinityList]:
    """
    Auto-paginate all lists.

    Alias for `all()` (FR-006 public contract).
    """
    return self.all()

list(*, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[AffinityList]

Get all lists accessible to you.

Parameters:

Name Type Description Default
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None

Returns:

Type Description
PaginatedResponse[AffinityList]

Paginated list of lists (without field metadata)
Source code in affinity/services/lists.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def list(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[AffinityList]:
    """
    Get all lists accessible to you.

    Args:
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).

    Returns:
        Paginated list of lists (without field metadata)
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        data = self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = self._client.get("/lists", params=params or None)

    return PaginatedResponse[AffinityList](
        data=[
            _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
        ],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

pages(*, limit: int | None = None, cursor: str | None = None) -> Iterator[PaginatedResponse[AffinityList]]

Iterate list pages (not items), yielding PaginatedResponse[AffinityList].

This is useful for ETL scripts that want checkpoint/resume via page.next_cursor.

Source code in affinity/services/lists.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
def pages(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> Iterator[PaginatedResponse[AffinityList]]:
    """
    Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

    This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
    """
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = self.list(limit=limit) if cursor is None else self.list(cursor=cursor)
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = self.list(cursor=next_cursor)

resolve(*, name: str, list_type: ListType | None = None) -> AffinityList | None

Find a single list by name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Results are cached in-memory on this service instance. If you call this frequently, reuse the client, or persist the resolved ListId in your own configuration.

If multiple matches exist, returns the first match in server-provided order.

Source code in affinity/services/lists.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
def resolve(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> AffinityList | None:
    """
    Find a single list by name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Results are cached in-memory on this service instance. If you call this frequently,
      reuse the client, or persist the resolved `ListId` in your own configuration.

    If multiple matches exist, returns the first match in server-provided order.
    """
    key = (name.lower(), list_type)
    if key in self._resolve_cache:
        return self._resolve_cache[key]

    for item in self.all():
        if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
            self._resolve_cache[key] = item
            return item

    self._resolve_cache[key] = None
    return None

resolve_all(*, name: str, list_type: ListType | None = None) -> builtins.list[AffinityList]

Find all lists matching a name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Unlike resolve(), this does not cache results.

Source code in affinity/services/lists.py 
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
def resolve_all(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> builtins.list[AffinityList]:
    """
    Find all lists matching a name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Unlike `resolve()`, this does not cache results.
    """
    matches: builtins.list[AffinityList] = []
    name_lower = name.lower()
    for item in self.all():
        if item.name.lower() != name_lower:
            continue
        if list_type is not None and item.type != list_type:
            continue
        matches.append(item)
    return matches

saved_views_all(list_id: ListId) -> Iterator[SavedView]

Iterate all saved views for a list.

Source code in affinity/services/lists.py 
437
438
439
440
def saved_views_all(self, list_id: ListId) -> Iterator[SavedView]:
    """Iterate all saved views for a list."""
    for page in self.saved_views_pages(list_id):
        yield from page.data

saved_views_pages(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> Iterator[PaginatedResponse[SavedView]]

Iterate saved view pages, yielding PaginatedResponse[SavedView].

Source code in affinity/services/lists.py 
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
def saved_views_pages(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> Iterator[PaginatedResponse[SavedView]]:
    """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = (
        self.get_saved_views(list_id, limit=limit)
        if cursor is None
        else self.get_saved_views(list_id, cursor=cursor)
    )
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = self.get_saved_views(list_id, cursor=next_cursor)

Async list operations (TR-009).

Source code in affinity/services/lists.py 
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
class AsyncListService:
    """Async list operations (TR-009)."""

    def __init__(self, client: AsyncHTTPClient):
        self._client = client
        self._resolve_cache: dict[tuple[str, ListType | None], AffinityList | None] = {}
        self._size_cache: dict[ListId, tuple[float, int]] = {}  # (timestamp, size)

    def entries(self, list_id: ListId) -> AsyncListEntryService:
        """
        Get an AsyncListEntryService for a specific list.

        This is the explicit path for retrieving "full row" data via list entries.
        """
        return AsyncListEntryService(self._client, list_id)

    async def list(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[AffinityList]:
        """
        Get all lists accessible to you.

        Args:
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).

        Returns:
            Paginated list of lists (without field metadata)
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            data = await self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = await self._client.get("/lists", params=params or None)
        return PaginatedResponse[AffinityList](
            data=[
                _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
            ],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    async def get_first(self) -> AffinityList | None:
        """Get the first list, or None if no lists exist."""
        page = await self.list(limit=1)
        return page.data[0] if page.data else None

    async def pages(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> AsyncIterator[PaginatedResponse[AffinityList]]:
        """
        Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

        This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
        """
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = await self.list(limit=limit) if cursor is None else await self.list(cursor=cursor)
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = await self.list(cursor=next_cursor)

    def all(self) -> AsyncIterator[AffinityList]:
        """Iterate through all accessible lists."""

        async def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
            if next_url:
                data = await self._client.get_url(next_url)
                return PaginatedResponse[AffinityList](
                    data=[
                        _safe_model_validate(AffinityList, list_item)
                        for list_item in data.get("data", [])
                    ],
                    pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
                )
            return await self.list()

        return AsyncPageIterator(fetch_page)

    def iter(self) -> AsyncIterator[AffinityList]:
        """
        Auto-paginate all lists.

        Alias for `all()` (FR-006 public contract).
        """
        return self.all()

    # =========================================================================
    # Saved View Operations
    # =========================================================================

    async def get_saved_views(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[SavedView]:
        """
        Get saved views for a list.

        Args:
            list_id: List id for the initial request.
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            cursor_list_id = _saved_views_list_id_from_cursor(cursor)
            if cursor_list_id is not None and int(list_id) != cursor_list_id:
                raise ValueError(
                    f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                    f"requested list_id is {int(list_id)}"
                )
            data = await self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = await self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

        return PaginatedResponse[SavedView](
            data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    async def saved_views_pages(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> AsyncIterator[PaginatedResponse[SavedView]]:
        """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = (
            await self.get_saved_views(list_id, limit=limit)
            if cursor is None
            else await self.get_saved_views(list_id, cursor=cursor)
        )
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = await self.get_saved_views(list_id, cursor=next_cursor)

    async def saved_views_all(self, list_id: ListId) -> AsyncIterator[SavedView]:
        """Iterate all saved views for a list."""
        async for page in self.saved_views_pages(list_id):
            for item in page.data:
                yield item

    async def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
        """Get a single saved view."""
        data = await self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
        return _safe_model_validate(SavedView, data)

    async def get(self, list_id: ListId) -> AffinityList:
        """
        Get a single list by ID.

        Includes field metadata for the list.

        Note: Uses V1 API because V2's listSize field is undocumented and
        returns incorrect values (often 0 for non-empty lists).
        """
        data = await self._client.get(f"/lists/{list_id}", v1=True)
        return _safe_model_validate(AffinityList, data)

    async def get_size(self, list_id: ListId, *, force: bool = False) -> int:
        """
        Get accurate list size. Uses V1 API, cached for 5 minutes.

        Args:
            list_id: The list ID.
            force: If True, bypass cache and fetch fresh value from API.

        Note: The V2 API's listSize field is unreliable (often returns 0 for
        non-empty lists). This method uses the V1 API which returns accurate values.
        """
        if not force and list_id in self._size_cache:
            cached_at, size = self._size_cache[list_id]
            if time.monotonic() - cached_at < _SIZE_CACHE_TTL:
                return size

        lst = await self.get(list_id)
        size = lst._list_size_hint
        self._size_cache[list_id] = (time.monotonic(), size)
        return size

    async def resolve(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> AffinityList | None:
        """
        Find a single list by name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Results are cached in-memory on this service instance. If you call this frequently,
          reuse the client, or persist the resolved `ListId` in your own configuration.

        If multiple matches exist, returns the first match in server-provided order.
        """
        key = (name.lower(), list_type)
        if key in self._resolve_cache:
            return self._resolve_cache[key]

        async for item in self.all():
            if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
                self._resolve_cache[key] = item
                return item

        self._resolve_cache[key] = None
        return None

    async def resolve_all(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> builtins.list[AffinityList]:
        """
        Find all lists matching a name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Unlike `resolve()`, this does not cache results.
        """
        matches: builtins.list[AffinityList] = []
        name_lower = name.lower()
        async for item in self.all():
            if item.name.lower() != name_lower:
                continue
            if list_type is not None and item.type != list_type:
                continue
            matches.append(item)
        return matches

    # =========================================================================
    # Write Operations (V1 API)
    # =========================================================================

    async def create(self, data: ListCreate) -> AffinityList:
        """
        Create a new list.

        Uses V1 API.
        """
        payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
        if not data.additional_permissions:
            payload.pop("additional_permissions", None)

        result = await self._client.post("/lists", json=payload, v1=True)

        if self._client.cache:
            self._client.cache.invalidate_prefix("list")
        self._resolve_cache.clear()

        return _safe_model_validate(AffinityList, result)

    # =========================================================================
    # Field Operations
    # =========================================================================

    async def get_fields(
        self,
        list_id: ListId,
        *,
        field_types: Sequence[FieldType] | None = None,
    ) -> builtins.list[FieldMetadata]:
        """
        Get fields (columns) for a list.

        Includes list-specific, global, enriched, and relationship intelligence fields.
        Cached for performance.
        """
        params: dict[str, Any] = {}
        if field_types:
            params["fieldTypes"] = [field_type.value for field_type in field_types]

        data = await self._client.get(
            f"/lists/{list_id}/fields",
            params=params or None,
            cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
            cache_ttl=300,
        )

        return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

all() -> AsyncIterator[AffinityList]

Iterate through all accessible lists.

Source code in affinity/services/lists.py 
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
def all(self) -> AsyncIterator[AffinityList]:
    """Iterate through all accessible lists."""

    async def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
        if next_url:
            data = await self._client.get_url(next_url)
            return PaginatedResponse[AffinityList](
                data=[
                    _safe_model_validate(AffinityList, list_item)
                    for list_item in data.get("data", [])
                ],
                pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
            )
        return await self.list()

    return AsyncPageIterator(fetch_page)

create(data: ListCreate) -> AffinityList async

Create a new list.

Uses V1 API.

Source code in affinity/services/lists.py 
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
async def create(self, data: ListCreate) -> AffinityList:
    """
    Create a new list.

    Uses V1 API.
    """
    payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
    if not data.additional_permissions:
        payload.pop("additional_permissions", None)

    result = await self._client.post("/lists", json=payload, v1=True)

    if self._client.cache:
        self._client.cache.invalidate_prefix("list")
    self._resolve_cache.clear()

    return _safe_model_validate(AffinityList, result)

entries(list_id: ListId) -> AsyncListEntryService

Get an AsyncListEntryService for a specific list.

This is the explicit path for retrieving "full row" data via list entries.

Source code in affinity/services/lists.py 
1209
1210
1211
1212
1213
1214
1215
def entries(self, list_id: ListId) -> AsyncListEntryService:
    """
    Get an AsyncListEntryService for a specific list.

    This is the explicit path for retrieving "full row" data via list entries.
    """
    return AsyncListEntryService(self._client, list_id)

get(list_id: ListId) -> AffinityList async

Get a single list by ID.

Includes field metadata for the list.

Note: Uses V1 API because V2's listSize field is undocumented and returns incorrect values (often 0 for non-empty lists).

Source code in affinity/services/lists.py 
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
async def get(self, list_id: ListId) -> AffinityList:
    """
    Get a single list by ID.

    Includes field metadata for the list.

    Note: Uses V1 API because V2's listSize field is undocumented and
    returns incorrect values (often 0 for non-empty lists).
    """
    data = await self._client.get(f"/lists/{list_id}", v1=True)
    return _safe_model_validate(AffinityList, data)

get_fields(list_id: ListId, *, field_types: Sequence[FieldType] | None = None) -> builtins.list[FieldMetadata] async

Get fields (columns) for a list.

Includes list-specific, global, enriched, and relationship intelligence fields. Cached for performance.

Source code in affinity/services/lists.py 
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
async def get_fields(
    self,
    list_id: ListId,
    *,
    field_types: Sequence[FieldType] | None = None,
) -> builtins.list[FieldMetadata]:
    """
    Get fields (columns) for a list.

    Includes list-specific, global, enriched, and relationship intelligence fields.
    Cached for performance.
    """
    params: dict[str, Any] = {}
    if field_types:
        params["fieldTypes"] = [field_type.value for field_type in field_types]

    data = await self._client.get(
        f"/lists/{list_id}/fields",
        params=params or None,
        cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
        cache_ttl=300,
    )

    return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

get_first() -> AffinityList | None async

Get the first list, or None if no lists exist.

Source code in affinity/services/lists.py 
1255
1256
1257
1258
async def get_first(self) -> AffinityList | None:
    """Get the first list, or None if no lists exist."""
    page = await self.list(limit=1)
    return page.data[0] if page.data else None

get_saved_view(list_id: ListId, view_id: SavedViewId) -> SavedView async

Get a single saved view.

Source code in affinity/services/lists.py 
1394
1395
1396
1397
async def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
    """Get a single saved view."""
    data = await self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
    return _safe_model_validate(SavedView, data)

get_saved_views(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[SavedView] async

Get saved views for a list.

Parameters:

Name Type Description Default
list_id ListId

List id for the initial request.

 required
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None
Source code in affinity/services/lists.py 
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
async def get_saved_views(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[SavedView]:
    """
    Get saved views for a list.

    Args:
        list_id: List id for the initial request.
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        cursor_list_id = _saved_views_list_id_from_cursor(cursor)
        if cursor_list_id is not None and int(list_id) != cursor_list_id:
            raise ValueError(
                f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                f"requested list_id is {int(list_id)}"
            )
        data = await self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = await self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

    return PaginatedResponse[SavedView](
        data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

get_size(list_id: ListId, *, force: bool = False) -> int async

Get accurate list size. Uses V1 API, cached for 5 minutes.

Parameters:

Name Type Description Default
list_id ListId

The list ID.

 required
force bool

If True, bypass cache and fetch fresh value from API.

 False

Note: The V2 API's listSize field is unreliable (often returns 0 for non-empty lists). This method uses the V1 API which returns accurate values.

Source code in affinity/services/lists.py 
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
async def get_size(self, list_id: ListId, *, force: bool = False) -> int:
    """
    Get accurate list size. Uses V1 API, cached for 5 minutes.

    Args:
        list_id: The list ID.
        force: If True, bypass cache and fetch fresh value from API.

    Note: The V2 API's listSize field is unreliable (often returns 0 for
    non-empty lists). This method uses the V1 API which returns accurate values.
    """
    if not force and list_id in self._size_cache:
        cached_at, size = self._size_cache[list_id]
        if time.monotonic() - cached_at < _SIZE_CACHE_TTL:
            return size

    lst = await self.get(list_id)
    size = lst._list_size_hint
    self._size_cache[list_id] = (time.monotonic(), size)
    return size

iter() -> AsyncIterator[AffinityList]

Auto-paginate all lists.

Alias for all() (FR-006 public contract).

Source code in affinity/services/lists.py 
1305
1306
1307
1308
1309
1310
1311
def iter(self) -> AsyncIterator[AffinityList]:
    """
    Auto-paginate all lists.

    Alias for `all()` (FR-006 public contract).
    """
    return self.all()

list(*, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[AffinityList] async

Get all lists accessible to you.

Parameters:

Name Type Description Default
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None

Returns:

Type Description
PaginatedResponse[AffinityList]

Paginated list of lists (without field metadata)
Source code in affinity/services/lists.py 
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
async def list(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[AffinityList]:
    """
    Get all lists accessible to you.

    Args:
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).

    Returns:
        Paginated list of lists (without field metadata)
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        data = await self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = await self._client.get("/lists", params=params or None)
    return PaginatedResponse[AffinityList](
        data=[
            _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
        ],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

pages(*, limit: int | None = None, cursor: str | None = None) -> AsyncIterator[PaginatedResponse[AffinityList]] async

Iterate list pages (not items), yielding PaginatedResponse[AffinityList].

This is useful for ETL scripts that want checkpoint/resume via page.next_cursor.

Source code in affinity/services/lists.py 
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
async def pages(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> AsyncIterator[PaginatedResponse[AffinityList]]:
    """
    Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

    This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
    """
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = await self.list(limit=limit) if cursor is None else await self.list(cursor=cursor)
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = await self.list(cursor=next_cursor)

resolve(*, name: str, list_type: ListType | None = None) -> AffinityList | None async

Find a single list by name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Results are cached in-memory on this service instance. If you call this frequently, reuse the client, or persist the resolved ListId in your own configuration.

If multiple matches exist, returns the first match in server-provided order.

Source code in affinity/services/lists.py 
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
async def resolve(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> AffinityList | None:
    """
    Find a single list by name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Results are cached in-memory on this service instance. If you call this frequently,
      reuse the client, or persist the resolved `ListId` in your own configuration.

    If multiple matches exist, returns the first match in server-provided order.
    """
    key = (name.lower(), list_type)
    if key in self._resolve_cache:
        return self._resolve_cache[key]

    async for item in self.all():
        if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
            self._resolve_cache[key] = item
            return item

    self._resolve_cache[key] = None
    return None

resolve_all(*, name: str, list_type: ListType | None = None) -> builtins.list[AffinityList] async

Find all lists matching a name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Unlike resolve(), this does not cache results.

Source code in affinity/services/lists.py 
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
async def resolve_all(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> builtins.list[AffinityList]:
    """
    Find all lists matching a name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Unlike `resolve()`, this does not cache results.
    """
    matches: builtins.list[AffinityList] = []
    name_lower = name.lower()
    async for item in self.all():
        if item.name.lower() != name_lower:
            continue
        if list_type is not None and item.type != list_type:
            continue
        matches.append(item)
    return matches

saved_views_all(list_id: ListId) -> AsyncIterator[SavedView] async

Iterate all saved views for a list.

Source code in affinity/services/lists.py 
1388
1389
1390
1391
1392
async def saved_views_all(self, list_id: ListId) -> AsyncIterator[SavedView]:
    """Iterate all saved views for a list."""
    async for page in self.saved_views_pages(list_id):
        for item in page.data:
            yield item

saved_views_pages(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> AsyncIterator[PaginatedResponse[SavedView]] async

Iterate saved view pages, yielding PaginatedResponse[SavedView].

Source code in affinity/services/lists.py 
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
async def saved_views_pages(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> AsyncIterator[PaginatedResponse[SavedView]]:
    """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = (
        await self.get_saved_views(list_id, limit=limit)
        if cursor is None
        else await self.get_saved_views(list_id, cursor=cursor)
    )
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = await self.get_saved_views(list_id, cursor=next_cursor)