Pagination

The Linode API V4 returns collections of resources one page at a time. While this is useful, this library abstracts away the details of pagination and makes collections of resources appear as a single, uniform list that can be accessed, iterated over, and indexed as any normal Python list would be:

regions = client.regions() # get a collection of Regions

for region in regions:
    print(region.id)

first_region = regions[0]
last_region = regions[-1]

Pagination is handled transparently, and as requested. For example, if you had three pages of Linode Instances, accessing your collection of Instances would behave like this:

instances = client.linode.instances() # loads the first page only

instances[0] # no additional data is loaded

instances[-1] # third page is loaded to retrieve the last Linode in the collection

for instance in instances:
    # the second page will be loaded as soon as the first Linode on that page
    # is required.  The first and third pages are already loaded, and will not
    # be loaded again.
    print(instance.label)

The first page of a collection is always loaded when the collection is returned, and subsequent pages are loaded as they are required. When slicing a paginated list, only the pages required for the slice are loaded.

PaginatedList class

class linode_api4.PaginatedList(client, page_endpoint, page=[], max_pages=1, total_items=None, parent_id=None, filters=None)

The PaginatedList encapsulates the API V4’s pagination in an easily consumable way. A PaginatedList may be treated like a normal list in all ways, and can be iterated over, indexed, and sliced.

PaginatedLists should never be constructed manually, and instead should be created by requesting a collection of resources from the LinodeClient. For example:

linodes = client.linode.instances() # returns a PaginatedList of Linodes

Once you have a PaginatedList of resources, it doesn’t matter how many resources the API will return - you can iterate over all of them without having to worry about pagination.:

# iterate over all linodes.  If there are two or more pages,
# they will be loaded as required.
for linode in linodes:
    print(linode.label)

You may access the number of items in a collection by calling len on the PaginatedList:

num_linodes = len(linodes)

This will _not_ emit another API request.

first()

A convenience method for getting only the first item in this list. Exactly equivalent to getting index 0.

Returns:

The first item in this list.

last()

A convenience method for getting only the last item in this list. Exactly equivalent to getting index -1.

Returns:

The first item in this list.

only()

Returns the first item in this list, and asserts that it is the only item. This is useful when querying a collection for a resource and expecting to get only one back. For instance:

# raises if it finds more than one Linode
production_box = client.linode.instances(Linode.group == "prod").only()

Returns:

The first and only item in this list.

Raises:

ValueError – If more than one item is in this list.