def iterate(
*,
limit: int | None = None,
offset: int | None = None,
search: str | None = None,
sort_by: str | None = None,
timeout: float | None = None,
) -> Iterator[RoleResource]def iterate(
*,
limit: int | None = None,
offset: int | None = None,
search: str | None = None,
sort_by: str | None = None,
timeout: float | None = None,
) -> AsyncIterator[RoleResource]Yields roles individually, fetching the next page only once the current one is drained. Role sets are small, so this exists mainly for symmetry with the other collections and for the ability to stop as soon as you find the row you wanted.
It returns an iterator, so put the call straight into a for loop, or an async for loop on AsyncEnvless. No request is issued until the first iteration, and breaking out of the loop leaves any remaining pages unfetched.
Example
from envless import envless
for role in envless.roles.iterate():
if role['isSystem']:
continue
print(role['name'], len(role['permissions']))import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
async for role in envless.roles.iterate():
if role['isSystem']:
continue
print(role['name'], len(role['permissions']))
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | int | No | Page size fetched behind the scenes, clamped to 100. |
offset | int | No | Row to start streaming from. |
search | str | No | Case insensitive substring match against role name and description. |
sort_by | str | No | Order within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
An iterator that yields RoleResource values until the pages run out.
Reads the roles collection. list returns one page as a dict with items and pagination, list_all collects every page into a list, and iterate yields one item at a time, fetching the next page only when the loop reaches it. On AsyncEnvless, iterate is an async iterator for async for.
Worth knowing
- The offset advances by the number of rows actually received, so a role created mid walk can shift the window.
- System roles are yielded before custom roles, so a loop that breaks on the first row always sees a system role.
Required scopes
roles:read
Underlying endpoint
GET /roles
Request and response schema, every error code, and a live playground.
In TypeScript
envless.roles.iterate()
The same method in @goenvless/sdk, with the same request, retries and errors.