Skills › Scientific Agent Skills › pyzotero › pagination.md

pagination.md

79 lines · skills/pyzotero/references/pagination.md at 5f2bc03

Open on GitHub

1# Pagination: follow(), everything(), Generators

3Pyzotero returns 100 items by default. Use these methods to retrieve more.

Pagination: follow(), everything(), Generators

Pyzotero returns 100 items by default. Use these methods to retrieve more.

Raw lines 1 to 4

5## everything() — Retrieve All Results

7The simplest way to get all items:

9```python

10# All items in the library

11all_items = zot.everything(zot.items())

13# All top-level items

14all_top = zot.everything(zot.top())

16# All items in a collection

17all_col = zot.everything(zot.collection_items('COLKEY'))

19# All items matching a search

20all_results = zot.everything(zot.items(q='machine learning', itemType='journalArticle'))

21```

23Use `everything()` with list-returning endpoints (items, collections, tags, searches) and BibTeX databases. Do not pass dict responses (`format=versions`, `deleted`, `settings`) or bytes (`format=keys`): their iteration semantics differ.

everything() — Retrieve All Results

The simplest way to get all items:

# All items in the library
all_items = zot.everything(zot.items())

# All top-level items
all_top = zot.everything(zot.top())

# All items in a collection
all_col = zot.everything(zot.collection_items('COLKEY'))

# All items matching a search
all_results = zot.everything(zot.items(q='machine learning', itemType='journalArticle'))

Use everything() with list-returning endpoints (items, collections, tags, searches) and BibTeX databases. Do not pass dict responses (format=versions, deleted, settings) or bytes (format=keys): their iteration semantics differ.

Raw lines 5 to 24

25## follow() — Sequential Pagination

27```python

28# Retrieve items in batches, manually advancing the page

29first_batch = zot.top(limit=25)

30second_batch = zot.follow() # next 25 items

31third_batch = zot.follow() # next 25 items

32```

34`follow()` returns `None` when no next-page link exists. `iterfollow()` and `makeiter()` end by raising `StopIteration` through normal generator exhaustion. Do not interleave other reads on the same client while paging: they replace its pagination links.

follow() — Sequential Pagination

# Retrieve items in batches, manually advancing the page
first_batch = zot.top(limit=25)
second_batch = zot.follow()   # next 25 items
third_batch = zot.follow()    # next 25 items

follow() returns None when no next-page link exists. iterfollow() and makeiter() end by raising StopIteration through normal generator exhaustion. Do not interleave other reads on the same client while paging: they replace its pagination links.

Raw lines 25 to 35

36## iterfollow() — Generator

38```python

39# Create a generator over follow()

40first = zot.top(limit=10)

41lazy = zot.iterfollow()

43# Retrieve subsequent pages

44second = next(lazy)

45third = next(lazy)

46```

iterfollow() — Generator

# Create a generator over follow()
first = zot.top(limit=10)
lazy = zot.iterfollow()

# Retrieve subsequent pages
second = next(lazy)
third = next(lazy)

Raw lines 36 to 47

48## makeiter() — Generator over Any Method

50```python

51# Create a generator directly from a method call

52gen = zot.makeiter(zot.top(limit=25))

54page1 = next(gen) # first 25 items, fetched AGAIN by makeiter()

55page2 = next(gen) # next 25 items

56# Raises StopIteration when exhausted

57```

makeiter() — Generator over Any Method

# Create a generator directly from a method call
gen = zot.makeiter(zot.top(limit=25))

page1 = next(gen)  # first 25 items, fetched AGAIN by makeiter()
page2 = next(gen)  # next 25 items
# Raises StopIteration when exhausted

Raw lines 48 to 58

59## Manual start/limit Pagination

61```python

62page_size = 50

63offset = 0

65while True:

66 batch = zot.items(limit=page_size, start=offset)

67 if not batch:

68 break

69 # process batch

70 for item in batch:

71 process(item)

72 offset += page_size

73```

Manual start/limit Pagination

page_size = 50
offset = 0

while True:
    batch = zot.items(limit=page_size, start=offset)
    if not batch:
        break
    # process batch
    for item in batch:
        process(item)
    offset += page_size

Raw lines 59 to 74

75## Performance Notes

77- `everything()` makes multiple API calls sequentially; large libraries may take time.

78- For incremental synchronization, combine `since=version` with `deleted(since=version)` and account for changes during paging; see [read-api.md](read-api.md).

79- The raw local API has no default limit, but Pyzotero still injects 100 unless you pass `limit=None`. Local reads can use `zot.items(limit=None)`; remote JSON reads remain paginated.

Performance Notes

everything() makes multiple API calls sequentially; large libraries may take time.
For incremental synchronization, combine since=version with deleted(since=version) and account for changes during paging; see read-api.md.
The raw local API has no default limit, but Pyzotero still injects 100 unless you pass limit=None. Local reads can use zot.items(limit=None); remote JSON reads remain paginated.

Raw lines 75 to 79