Python API#
Query#
- class pyquerylist.Query(*args, **kwargs)#
Combinable query class.
Condition can be specified in two different ways:
specified by a python expression.
specified by a lambda or function.
>>> q1 = Query('field1 < 10') >>> q2 = Query('(0 < field1 < 10) & (field2 == "b")') >>> q3 = Query(lambda x: x.field1 < 10) >>> q4 = Query(q1, '|', q2) >>> qand = q1 & q2 >>> qor = q2 | q3 >>> qnand = ~q1 & ~q4
- classmethod add_allowed_ast_type(ast_type)#
Add additional allowed AST types to existing.
When a query is constructed using:
>>> q = Query('a < 10')
Checks are done to validate the expression to make sure it only contains certain types given by Q.allowed_ast_types. This metho allows the addition of any AST types to this set.
>>> Query.add_allowed_ast_type(ast.Call) >>> ast.Call in Query.allowed_ast_types True >>> q = Query('func() < 10') # Normally would cause exception.
- Parameters
ast_type – AST type or set of AST types.
- allowed_ast_types = {<class 'ast.BitAnd'>, <class 'ast.In'>, <class 'ast.BitXor'>, <class 'ast.Load'>, <class 'ast.IsNot'>, <class 'ast.BitOr'>, <class 'ast.Is'>, <class 'ast.RShift'>, <class 'ast.GtE'>, <class 'ast.NotIn'>, <class 'ast.LShift'>, <class 'ast.Tuple'>, <class 'ast.Set'>, <class 'ast.Gt'>, <class 'ast.Pow'>, <class 'ast.List'>, <class 'ast.Dict'>, <class 'ast.LtE'>, <class 'ast.Name'>, <class 'ast.Mod'>, <class 'ast.Lt'>, <class 'ast.Div'>, <class 'ast.NotEq'>, <class 'ast.Mult'>, <class 'ast.Eq'>, <class 'ast.Constant'>, <class 'ast.Sub'>, <class 'ast.BinOp'>, <class 'ast.Add'>, <class 'ast.Compare'>, <class 'ast.FloorDiv'>}#
- classmethod expr_validation(validate)#
Enable or disable expression validation
>>> Query.expr_validation(False) >>> q = Query('func() < 10') # Normally would cause exception.
- Parameters
validate – whether to validate or not
- match(item, item_type='obj')#
Determine if the given item is matched by this query.
>>> class Item: pass >>> item = Item() >>> item.field1 = 6 >>> item.field2 = 'a' >>> q1 = Query('(field1 > 0) & (field2 == "a")') >>> q2 = Query(lambda x: x.field1 < 10) >>> q1.match(item) True >>> q2.match(item) True
- Parameters
item – item to test
item_type – type of item
- Returns
True if item matches query
QueryList#
- class pyquerylist.QueryList(iterable=None, item_type='obj')#
Queryable list.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> len(ql) 3 >>> ql[:2] QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}]) >>> ql.where('a==1').select('a') [1]
- aggregate(method, fields)#
Aggregate a given field(s) based on method.
Exactly one of field or fields must be supplied.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.aggregate(sum, 'a') 12 >>> ql.aggregate(sum, fields=['a', 'b']) [12, 16]
- Parameters
method – method to use (e.g. statistics.mean)
fields – fields to aggregate over
- Returns
aggregated values
- all(query)#
Test if all items match query.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.all(Query('a>0')) True >>> ql.all(Query('a<4')) False
- Parameters
query – query to test
- Returns
True if all items match query
- any(query)#
Test if any items match query.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.any(Query('a<0')) False >>> ql.any(Query('a>4')) True
- Parameters
query – query to test
- Returns
True if all items match query
- count()#
Get number of items.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.count() 3 >>> ql.count() == len(ql) True
- Returns
number of items
- first()#
Get first item.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.first() {'a': 1, 'b': 2}
- Returns
first item
- groupby(field)#
Group on given field.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 1, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.groupby('a') {1: QueryList([{'a': 1, 'b': 2}, {'a': 1, 'b': 5}]), 7: QueryList([{'a': 7, 'b': 9}])}
- Parameters
field – field to group on
- Returns
QueryGroup of grouped data
- last()#
Get last item.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.last() {'a': 7, 'b': 9}
- Returns
first item
- orderby(fields=None, key=None, order='ascending')#
Order QueryList based on supplied arguments.
Exactly one of fields or key must be supplied.
>>> ql = QueryList([{'a': 5, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.orderby('a') QueryList([{'a': 4, 'b': 5}, {'a': 5, 'b': 2}, {'a': 7, 'b': 9}]) >>> ql.orderby(['a', 'b']) QueryList([{'a': 4, 'b': 5}, {'a': 5, 'b': 2}, {'a': 7, 'b': 9}]) >>> ql.orderby(key=lambda x: x['b'], order='descending') QueryList([{'a': 7, 'b': 9}, {'a': 4, 'b': 5}, {'a': 5, 'b': 2}])
- Parameters
field – field to order by
fields – fields to order by
key – key to order on (passed to sorted)
order – ascending or descending
- Returns
Ordered QueryList
- select(fields=None, func=None)#
Select given field(s).
Exactly one of the three arguments must be supplied.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.select('a') [1, 4, 7] >>> ql.select(fields=['a', 'b']) [(1, 2), (4, 5), (7, 9)] >>> ql.select(func=lambda x: x['a']**2) [1, 16, 49]
- Parameters
field – field to select
fields – multiple fields to select
func – function to apply to item – output is selected
- Returns
list of selected field(s) or function output
- tabulate(fields)#
Produce a formated table of a QueryList
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> print(ql.tabulate(['a', 'b'])) a b --- --- 1 2 4 5 7 9
- Parameters
fields – to use as headers/values
- Returns
output string of table
- where(query)#
Filter based on query.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 4, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.where('(b>3)&(a==b-2)') QueryList([{'a': 7, 'b': 9}])
- Parameters
query – query to apply
- Returns
filtered QueryList
QueryGroup#
- class pyquerylist.QueryGroup(group)#
Extension of dict to allow aggregate statistics to be calculated on QueryList.groupby.
- aggregate(method, fields)#
Aggregate over instances of each group using method and field(s).
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 1, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.groupby('a').aggregate(sum, 'b') {1: 7, 7: 9}
- Parameters
method – method to use (e.g. statistics.mean)
fields – field(s) to aggregate over
- Returns
aggregated values dict with key (group) and value (aggregated value)
- count()#
Count instances of each group.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 1, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.groupby('a').count() {1: 2, 7: 1}
- Returns
dict containing key (group) and values (counts)
- select(fields=None, func=None)#
Select given field(s) from instances of each group.
Exactly one of the three arguments must be supplied.
>>> ql = QueryList([{'a': 1, 'b': 2}, {'a': 1, 'b': 5}, {'a': 7, 'b': 9}], 'dict') >>> ql.groupby('a').select('b') {1: [2, 5], 7: [9]}
- Parameters
fields – field(s) to select
func – function to apply to item – output is selected
- Returns
aggregated values dict with key (group) and value (selected field(s))