Filtering Collections

Collections returned by the LinodeClient can be filtered using a SQLAlchemy-like syntax. When calling any “get” method of the LinodeClient class of one of its groups, any number of filters may be passed in as boolean comparisons between attributes of the model returned by the collection.

For example, calling get_instances returns a list of Linode objects, so we can use properties of Linode to filter the results:

# returns all Linodes in the "prod" group
client.linode.get_instances(Linode.group == "prod")

You can use any boolean comparisons when filtering collections:

# returns all Linodes _not_ in us-east-1a
client.linode.get_instances(Linode.region != "us-east-1a")

You can combine filters to be even more specific - by default all filters are considered:

# returns all Linodes in the "prod" group that are in us-east-1a
client.linode.get_instances(Linode.group == "prod",
                            Linode.region == "us-east-1a")

If you need to combine the results of two filters, you can use or_ to define this relationship:

# returns all Linodes in either the "prod" or "staging" groups
client.linode.get_instances(or_(Linode.group == "prod",
                                Linode.group == "staging"))

and_ is also available in case you need to do deeply-nested comparisons:

# returns all Linodes in the group "staging" and any Linodes in the "prod"
# group that are located in "us-east-1a"
client.linode.get_instances(or_(Linode.group == "staging",
                                and_(Linode.group == "prod",
                                     Linode.region == "us-east-1a"))
class linode.objects.filtering.Filter(dct)[source]

A Filter represents a comparison to send to the API. These should not be constructed normally, but instead should be returned from comparisons between class attributes of filterable classes (see above). Filters can be combined with and_ and or_.

linode.objects.filtering.and_(a, b)[source]

Combines two Filters with an “and” operation, matching any results that match both of the given filters.

Parameters:
  • a (Filter) – The first filter to consider.
  • b (Filter) – The second filter to consider.
Returns:

A filter that matches both a and b
Return type:

Filter
linode.objects.filtering.limit(amount)[source]

Allows limiting of results in a collection. You may only ever apply a limit once per request. For example:

# returns my first 5 Linodes
client.linode.get_instances(limit(5))
Parameters:amount (int) – The number of results to return.
Returns:A filter that will limit the number of results returned.
Return type:Filter
linode.objects.filtering.or_(a, b)[source]

Combines two Filters with an “or” operation, matching any results that match any of the given filters.

Parameters:
  • a (Filter) – The first filter to consider.
  • b (Filter) – The second filter to consider.
Returns:

A filter that matches either a or b
Return type:

Filter
linode.objects.filtering.order_by(field, desc=False)[source]

Allows ordering of results. You may only ever order a collection’s results once in a given request. For example:

# sort results by Linode group
client.linode.get_instances(order_by(Linode.group))
Parameters:
  • field (FilterableAttribute) – The field to order results by. Must be a filterable attribute of the model.
  • desc (bool) – If True, return results in descending order. Defaults to False
Returns:

A filter that will order results as requested.
Return type:

Filter