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)[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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.
-