Skip to main content

Pagination

Use async paginators to iterate through all results without manual offset management.

Basic Usage​

from spatialflow import paginate_geofences

async for geofence in paginate_geofences(
    lambda offset, limit: client.geofences.list(offset=offset, limit=limit)
):
    print(geofence.name)

Resource-Specific Paginators​

Each resource has a dedicated paginator:

from spatialflow import (
    paginate_geofences,
    paginate_workflows,
    paginate_webhooks,
    paginate_users,
    paginate_files,
)

# Geofences
async for geofence in paginate_geofences(
    lambda o, l: client.geofences.list(offset=o, limit=l)
):
    print(geofence.name)

# Workflows
async for workflow in paginate_workflows(
    lambda o, l: client.workflows.list(offset=o, limit=l)
):
    print(workflow.name)

# Webhooks
async for webhook in paginate_webhooks(
    lambda o, l: client.webhooks.list(offset=o, limit=l)
):
    print(webhook.name)

Generic Paginate Function​

For custom pagination needs:

from spatialflow import paginate

async for item in paginate(
    fetch_fn=lambda o, l: client.geofences.list(offset=o, limit=l),
    items_field="geofences",
    limit=50,  # Items per page
):
    print(item.name)

Parameters​

ParameterTypeDefaultDescription
fetch_fnCallablerequiredFunction that takes (offset, limit) and returns a response
items_fieldstrrequiredKey in response containing the items list
limitint100Number of items per page

AsyncPaginator Class​

For more control, use the AsyncPaginator class directly:

from spatialflow import AsyncPaginator

paginator = AsyncPaginator(
    fetch_fn=lambda o, l: client.geofences.list(offset=o, limit=l),
    items_field="geofences",
    limit=50,
)

async for geofence in paginator:
    print(geofence.name)
    if some_condition:
        break  # Early exit is supported

PaginatedResponse​

Wrap a paginated response for easier access:

from spatialflow import PaginatedResponse

response = await client.geofences.list(limit=100)
paginated = PaginatedResponse(
    items=response.geofences,
    count=response.count,
)

print(f"Got {len(paginated)} of {paginated.count} items")

for geofence in paginated:
    print(geofence.name)

Filtering While Paginating​

Combine pagination with filtering:

from spatialflow import paginate_geofences

# Filter by group
async for geofence in paginate_geofences(
    lambda o, l: client.geofences.list(offset=o, limit=l, group_id="group-123")
):
    print(geofence.name)

Collecting All Results​

To collect all results into a list:

from spatialflow import paginate_geofences

all_geofences = [
    geofence
    async for geofence in paginate_geofences(
        lambda o, l: client.geofences.list(offset=o, limit=l)
    )
]

print(f"Total geofences: {len(all_geofences)}")

Performance Tips​

  • Use a reasonable page size (50-100 items) to balance API calls vs memory
  • Break early if you find what you need
  • Consider filtering server-side when possible to reduce data transfer