API Documentation for asq

asq

A module for a LINQ-like facility in Python.

class asq.queryable.Grouping(ordered_dict, key)

A collection of objects which share a common key.

All standard query operators may be used on a Grouping.

Note

It is not intended that clients should directly create Grouping objects. Instances of this class are retrieved from Lookup objects.

key

The key common to all elements.

class asq.queryable.Lookup(key_value_pairs)

A multi-valued dictionary.

A Lookup represents a collection of keys, each one of which is mapped to one or more values. The keys in the Lookup are maintained in the order in which they were added. The values for each key are also maintained in order.

All standard query operators may be used on a Lookup. When iterated or used as a Queryable the elements are returned as a sequence of Grouping objects.

class asq.queryable.OrderedQueryable(iterable, order, func)

A Queryable representing an ordered iterable.

The sorting implemented by this class is an incremental partial sort so you don’t pay for sorting results which are never enumerated.

then_by(key_selector=<function identity at 0x9722b8c>)

Introduce subsequent ordering to the sequence with an optional key.

The returned sequence will be sorted in ascending order by the selected key.

Note

This method uses deferred execution.

Parameters:

key_selector – A unary function the only positional argument to which is the element value from which the key will be selected. The return value should be the key from that element.

Returns:

An OrderedQueryable over the sorted items.

Raises :

• ValueError - If the OrderedQueryable is closed().
• TypeError - If key_selector is not callable.

then_by_descending(key_selector=<function identity at 0x9722b8c>)

Introduce subsequent ordering to the sequence with an optional key.

The returned sequence will be sorted in descending order by the selected key.

Note

This method uses deferred execution.

Parameters:

key_selector – A unary function the only positional argument to which is the element value from which the key will be selected. The return value should be the key from that element.

Returns:

An OrderedQueryable over the sorted items.

Raises :

• ValueError - If the OrderedQueryable is closed().
• TypeError - If key_selector is not callable.

class asq.queryable.Queryable(iterable)

Queries over iterables executed serially.

Queryable objects are constructed from iterables.

aggregate(reducer, seed=<object object at 0x938d540>, result_selector=<function identity at 0x9722b8c>)

Apply a function over a sequence to produce a single result.

Apply a binary function cumulatively to the elements of the source sequence so as to reduce the iterable to a single value.

Note

This method uses immediate execution.

Parameters:

• reducer – A binary function the first positional argument of which is an accumulated value and the second is the update value from the source sequence. The return value should be the new accumulated value after the update value has been incorporated.
• seed – An optional value used to initialise the accumulator before iteration over the source sequence. If seed is omitted the and the source sequence contains only one item, then that item is returned.
• result_selector – An optional unary function applied to the final accumulator value to produce the result. If omitted, defaults to the identity function.

Raises :

• ValueError - If called on an empty sequence with no seed value.
• TypeError - If reducer is not callable
• TypeError - If result_selector is not callable

all(predicate=<type 'bool'>)

Determine if all elements in the source sequence satisfy a condition.

All of the source sequence will be consumed.

Note

This method uses immediate execution.

Parameters:

predicate – An optional single argument function used to test each elements. If omitted, the bool() function is used resulting in the elements being tested directly.

Returns:

True if all elements in the sequence meet the predicate condition, otherwise False.

Raises :

• ValueError - If the Queryable is closed()
• TypeError - If predicate is not callable.

any(predicate=None)

Determine if the source sequence contains any elements which satisfy the predicate.

Only enough of the sequence to satisfy the predicate once is consumed.

Note

This method uses immediate execution.

Parameters:predicate – An optional single argument function used to test each element. If omitted, or None, this method returns True if there is at least one element in the source. Returns:True if the sequence contains at least one element which satisfies the predicate, otherwise False. Raises :ValueError - If the Queryable is closed()

as_parallel(pool=None)

Return a ParallelQueryable for parallel execution of queries.

Warning

This feature should be considered experimental alpha quality.

Parameters:pool – An optional multiprocessing pool which will provide execution resources for parellel processing. If omitted, a pool will be created if necessary and managed internally. Returns:A ParallelQueryable on which all the standard query operators may be called.

average(selector=<function identity at 0x9722b8c>)

Return the arithmetic mean of the values in the sequence..

All of the source sequence will be consumed.

Note

This method uses immediate execution.

Parameters:

selector – An optional single argument function which will be used to project the elements of the sequence. If omitted, the identity function is used.

Returns:

The arithmetic mean value of the projected sequence.

Raises :

• ValueError - If the Queryable has been closed.
• ValueError - I the source sequence is empty.

close()

Closes the queryable.

The Queryable should not be used following a call to close. This method is idempotent. Other calls to a Queryable following close() will raise ValueError.

closed()

Determine whether the Queryable has been closed.

Returns:True if closed, otherwise False.

concat(second_iterable)

Concatenates two sequences.

Note

This method uses deferred execution.

Parameters:

second_iterable – The sequence to concatenate on to the sequence.

Returns:

A Queryable over the concatenated sequences.

Raises :

• ValueError - If the Queryable is closed().
• TypeError - If second_iterable is not in fact iterable.

contains(value, equality_comparer=<built-in function eq>)

Determines whether the sequence contains a particular value.

Execution is immediate. Depending on the type of the sequence, all or none of the sequence may be consumed by this operation.

Note

This method uses immediate execution.

Parameters:value – The value to test for membership of the sequence Returns:True if value is in the sequence, otherwise False. Raises :ValueError - If the Queryable has been closed.

count(predicate=None)

Return the number of elements (which match an optional predicate).

Note

This method uses immediate execution.

Parameters:

predicate – An optional unary predicate function used to identify elements which will be counted. The single positional argument of the function is the element value. The function should return True or False.

Returns:

The number of elements in the sequence if the predicate is None (the default), or if the predicate is supplied the number of elements for which the predicate evaluates to True.

Raises :

• ValueError - If the Queryable is closed().
• TypeError - If predicate is neither None nor a callable.

default_if_empty(default)

If the source sequence is empty return a single element sequence containing the supplied default value, otherwise return the source sequence unchanged.

Note

This method uses deferred execution.

Parameters:default – The element to be returned if the source sequence is empty. Returns:The source sequence, or if the source sequence is empty an sequence containing a single element with the supplied default value. Raises :ValueError - If the Queryable has been closed.

difference(second_iterable, selector=<function identity at 0x9722b8c>)

Returns those elements which are in the source sequence which are not in the second_iterable.

This method is equivalent to the Except() LINQ operator, renamed to a valid Python identifier.

Note

This method uses deferred execution, but as soon as execution commences the entirety of the second_iterable is consumed; therefore, although the source sequence may be infinite the second_iterable must be finite.

Parameters:

• second_iterable – Elements from this sequence are excluded from the returned sequence. This sequence will be consumed in its entirety, so must be finite.
• selector – A optional single argument function with selects from the elements the of both sequences the values which will be compared for equality. If omitted the identity function will be used.

Returns:

A sequence containing all elements in the source sequence except those which are also members of the second sequence.

Raises :

• ValueError - If the Queryable has been closed.
• TypeError - If the second_iterable is not in fact iterable.
• TypeError - If the selector is not callable.

distinct(selector=<function identity at 0x9722b8c>)

Eliminate duplicate elements from a sequence.

Note

This method uses deferred execution.

Parameters:

selector – An optional single argument function the result of which is the value compared for uniqueness against elements already consumed. If omitted, the element value itself is compared for uniqueness.

Returns:

Unique elements of the source sequence as determined by the selector function. Note that it is unprojected elements that are returned, even if a selector was provided.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the selector is not callable.

element_at(index)

Return the element at ordinal index.

Note

This method uses immediate execution.

Parameters:

index – The index of the element to be returned.

Returns:

The element at ordinal index in the source sequence.

Raises :

• ValueError - If the Queryable is closed().
• ValueError - If index is out of range.

first(predicate=None)

The first element in a sequence (optionally satisfying a predicate).

If the predicate is omitted or is None this query returns the first element in the sequence; otherwise, it returns the first element in the sequence for which the predicate evaluates to True. Exceptions are raised if there is no such element.

Note

This method uses immediate execution.

Parameters:

predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the first element of the source sequence will be returned.

Returns:

The first element of the sequence if predicate is None, otherwise the first element for which the predicate returns True.

Raises :

• ValueError - If the Queryable is closed.
• ValueError - If the source sequence is empty.
• ValueError - If there are no elements matching the predicate.
• TypeError - If the predicate is not callable.

first_or_default(default, predicate=None)

The first element (optionally satisfying a predicate) or a default.

If the predicate is omitted or is None this query returns the first element in the sequence; otherwise, it returns the first element in the sequence for which the predicate evaluates to True. If there is no such element the value of the default argument is returned.

Note

This method uses immediate execution.

Parameters:

• default – The value which will be returned if either the sequence is empty or there are no elements matching the predicate.
• predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the first element of the source sequence will be returned.

Returns:

The first element of the sequence if predicate is None, otherwise the first element for which the predicate returns True. If there is no such element, the default argument is returned.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the predicate is not callable.

group_by(key_selector=<function identity at 0x9722b8c>, element_selector=<function identity at 0x9722b8c>, result_selector=<function <lambda> at 0x97304fc>)

Groups the elements according to the value of a key extracted by a selector function.

Note

This method has different behaviour to itertools.groupby in the Python standard library because it aggregates all items with the same key, rather than returning groups of consecutive items of the same key.

Note

This method uses deferred execution, but consumption of a single result will lead to evaluation of the whole source sequence.

Parameters:

• key_selector – An optional unary function used to extract a key from each element in the source sequence. The default is the identity function.
• element_selector – A optional unary function to map elements in the source sequence to elements in a resulting Grouping. The default is the identity function.
• result_selector – An optional binary function to create a result from each group. The first positional argument is the key identifying the group. The second argument is a Grouping object containing the members of the group. The default is a function which simply returns the Grouping.

Returns:

A Queryable sequence of elements of the where each element represents a group. If the default result_selector is relied upon this is a Grouping object.

Raises :

• ValueError - If the Queryable is closed().
• TypeError - If key_selector is not callable.
• TypeError - If element_selector is not callable.
• TypeError - If result_selector is not callable.

group_join(inner_iterable, outer_key_selector=<function identity at 0x9722b8c>, inner_key_selector=<function identity at 0x9722b8c>, result_selector=<function <lambda> at 0x9730dbc>)

Match elements of two sequences using keys and group the results.

The group_join() query produces a hierarchical result, with all of the inner elements in the result grouped against the matching outer element.

The order of elements from outer is maintained. For each of these the order of elements from inner is also preserved.

Note

This method uses deferred execution.

Parameters:

• inner_iterable – The sequence to join with the outer sequence.
• outer_key_selector – An optional unary function to extract keys from elements of the outer (source) sequence. The first positional argument of the function should accept outer elements and the result value should be the key. If omitted, the identity function is used.
• inner_key_selector – An optional unary function to extract keys from elements of the inner_iterable. The first positional argument of the function should accept outer elements and the result value should be the key. If omitted, the identity function is used.
• result_selector – An optional binary function to create a result element from an outer element and the Grouping of matching inner elements. The first positional argument is the outer elements and the second in the Grouping of inner elements which match the outer element according to the key selectors used. If omitted, the result elements will be the Groupings directly.

Returns:

A Queryable over a sequence with one element for each group in the result as returned by the result_selector. If the default result selector is used, the result is a sequence of Grouping objects.

Raises :

• ValueError - If the Queryable has been closed.
• TypeError - If the inner_iterable is not in fact iterable.
• TypeError - If the outer_key_selector is not callable.
• TypeError - If the inner_key_selector is not callable.
• TypeError - If the result_selector is not callable.

intersect(second_iterable, selector=<function identity at 0x9722b8c>)

Returns those elements which are both in the source sequence and in the second_iterable.

Note

This method uses deferred execution.

Parameters:

• second_iterable – Elements are returned if they are also in the sequence.
• selector – An optional single argument function which is used to project the elements in the source and second_iterables prior to comparing them. If omitted the identity function will be used.

Returns:

A sequence containing all elements in the source sequence which are also members of the second sequence.

Raises :

• ValueError - If the Queryable has been closed.
• TypeError - If the second_iterable is not in fact iterable.
• TypeError - If the selector is not callable.

join(inner_iterable, outer_key_selector=<function identity at 0x9722b8c>, inner_key_selector=<function identity at 0x9722b8c>, result_selector=<function <lambda> at 0x9730d14>)

Perform an inner join with a second sequence using selected keys.

The order of elements from outer is maintained. For each of these the order of elements from inner is also preserved.

Note

This method uses deferred execution.

Parameters:

• inner_iterable – The sequence to join with the outer sequence.
• outer_key_selector – An optional unary function to extract keys from elements of the outer (source) sequence. The first positional argument of the function should accept outer elements and the result value should be the key. If omitted, the identity function is used.
• inner_key_selector – An optional unary function to extract keys from elements of the inner_iterable. The first positional argument of the function should accept outer elements and the result value should be the key. If omitted, the identity function is used.
• result_selector – An optional binary function to create a result element from two matching elements of the outer and inner. If omitted the result elements will be a 2-tuple pair of the matching outer and inner elements.

Returns:

A Queryable whose elements are the result of performing an inner- join on two sequences.

Raises :

• ValueError - If the Queryable has been closed.
• TypeError - If the inner_iterable is not in fact iterable.
• TypeError - If the outer_key_selector is not callable.
• TypeError - If the inner_key_selector is not callable.
• TypeError - If the result_selector is not callable.

last(predicate=None)

The last element in a sequence (optionally satisfying a predicate).

If the predicate is omitted or is None this query returns the last element in the sequence; otherwise, it returns the last element in the sequence for which the predicate evaluates to True. Exceptions are raised if there is no such element.

Note

This method uses immediate execution.

Parameters:

predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the last element of the source sequence will be returned.

Returns:

The last element of the sequence if predicate is None, otherwise the last element for which the predicate returns True.

Raises :

• ValueError - If the Queryable is closed.
• ValueError - If the source sequence is empty.
• ValueError - If there are no elements matching the predicate.
• TypeError - If the predicate is not callable.

last_or_default(default, predicate=None)

The last element (optionally satisfying a predicate) or a default.

If the predicate is omitted or is None this query returns the last element in the sequence; otherwise, it returns the last element in the sequence for which the predicate evaluates to True. If there is no such element the value of the default argument is returned.

Note

This method uses immediate execution.

Parameters:

• default – The value which will be returned if either the sequence is empty or there are no elements matching the predicate.
• predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the last element of the source sequence will be returned.

Returns:

The last element of the sequence if predicate is None, otherwise the last element for which the predicate returns True. If there is no such element, the default argument is returned.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the predicate is not callable.

max(selector=<function identity at 0x9722b8c>)

Return the maximum value in a sequence.

All of the source sequence will be consumed.

Note

This method uses immediate execution.

Parameters:

selector – An optional single argument function which will be used to project the elements of the sequence. If omitted, the identity function is used.

Returns:

The maximum value of the projected sequence.

Raises :

• ValueError - If the Queryable has been closed.
• ValueError - If the sequence is empty.

min(selector=<function identity at 0x9722b8c>)

Return the minimum value in a sequence.

All of the source sequence will be consumed.

Note

This method uses immediate execution.

Parameters:

selector – An optional single argument function which will be used to project the elements of the sequence. If omitted, the identity function is used.

Returns:

The minimum value of the projected sequence.

Raises :

• ValueError - If the Queryable has been closed.
• ValueError - If the sequence is empty.

of_type(classinfo)

Filters elements according to whether they are of a certain type.

Note

This method uses deferred execution.

Parameters:

classinfo – If classinfo is neither a class object nor a type object it may be a tuple of class or type objects, or may recursively contain other such tuples (other sequence types are not accepted).

Returns:

A Queryable over those elements of the source sequence for which the predicate is True.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If classinfo is not a class, type, or tuple of classes,

types, and such tuples.

order_by(key_selector=<function identity at 0x9722b8c>)

Sorts by a key in ascending order.

Introduces a primary sorting order to the sequence. Additional sort criteria should be specified by subsequent calls to then_by() and then_by_descending(). Calling order_by() or order_by_descending() on the results of a call to order_by() will introduce a new primary ordering which will override any already established ordering.

This method performs a stable sort. The order of two elements with the same key will be preserved.

Note

This method uses deferred execution.

Parameters:

key_selector – A unary function which extracts a key from each element using which the result will be ordered.

Returns:

An OrderedQueryable over the sorted elements.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the key_selector is not callable.

order_by_descending(key_selector=<function identity at 0x9722b8c>)

Sorts by a key in descending order.

Introduces a primary sorting order to the sequence. Additional sort criteria should be specified by subsequent calls to then_by() and then_by_descending(). Calling order_by() or order_by_descending() on the results of a call to order_by() will introduce a new primary ordering which will override any already established ordering.

This method performs a stable sort. The order of two elements with the same key will be preserved.

Note

This method uses deferred execution.

Parameters:

key_selector – A unary function which extracts a key from each element using which the result will be ordered.

Returns:

An OrderedQueryable over the sorted elements.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the key_selector is not callable.

reverse()

Returns the sequence reversed.

Note

This method uses deferred execution, but the whole source sequence is consumed once execution commences.

Returns:The source sequence in reverse order. Raises :ValueError - If the Queryable is closed().

select(selector)

Transforms each element of a sequence into a new form.

Each element is transformed through a selector function to produce a value for each value in the source sequence. The generated sequence is lazily evaluated.

If the selector is identity the method will return self.

Note

This method uses deferred execution.

Parameters:

selector – A unary function mapping a value in the source sequence to the corresponding value in the generated generated sequence. The single positional argument to the selector function is the element value. The return value of the selector function should be the corresponding element of the result sequence.

Returns:

A Queryable over generated sequence whose elements are the result of invoking the selector function on each element of the source sequence.

Raises :

• ValueError - If this Queryable has been closed.
• TypeError - If selector is not callable.

select_many(collection_selector=<function identity at 0x9722b8c>, result_selector=<function identity at 0x9722b8c>)

Projects each element of a sequence to an intermediate new sequence, flattens the resulting sequences into one sequence and optionally transforms the flattened sequence using a selector function.

Note

This method uses deferred execution.

Parameters:

• collection_selector – A unary function mapping each element of the source iterable into an intermediate sequence. The single argument of the collection_selector is the value of an element from the source sequence. The return value should be an iterable derived from that element value. The default collection_selector, which is the identity function, assumes that each element of the source sequence is itself iterable.
• result_selector – An optional unary function mapping the elements in the flattened intermediate sequence to corresponding elements of the result sequence. The single argument of the result_selector is the value of an element from the flattened intermediate sequence. The return value should be the corresponding value in the result sequence. The default result_selector is the identity function.

Returns:

A Queryable over a generated sequence whose elements are the result of applying the one-to-many collection_selector to each element of the source sequence, concatenating the results into an intermediate sequence, and then mapping each of those elements through the result_selector into the result sequence.

Raises :

• ValueError - If this Queryable has been closed.
• TypeError - If either collection_selector or result_selector are not

callable.

select_many_with_correspondence(collection_selector=<function identity at 0x9722b8c>, result_selector=<function <lambda> at 0x9730454>)

Projects each element of a sequence to an intermediate new sequence, and flattens the resulting sequence, into one sequence and uses a selector function to incorporate the corresponding source for each item in the result sequence.

Note

This method uses deferred execution.

Parameters:

• collection_selector – A unary function mapping each element of the source iterable into an intermediate sequence. The single argument of the collection_selector is the value of an element from the source sequence. The return value should be an iterable derived from that element value. The default collection_selector, which is the identity function, assumes that each element of the source sequence is itself iterable.
• result_selector – An optional binary function mapping the elements in the flattened intermediate sequence together with their corresponding source elements to elements of the result sequence. The two positional arguments of the result_selector are, first the source element corresponding to an element from the intermediate sequence, and second the actual element from the intermediate sequence. The return value should be the corresponding value in the result sequence. If no result_selector function is provided, the elements of the result sequence are 2-tuple pairs of the form (source_element, intermediate_element).

Returns:

A Queryable over a generated sequence whose elements are the result of applying the one-to-many collection_selector to each element of the source sequence, concatenating the results into an intermediate sequence, and then mapping each of those elements through the result_selector which incorporates the corresponding source element into the result sequence.

Raises :

• ValueError - If this Queryable has been closed.
• TypeError - If projector or selector are not callable.

select_many_with_index(collection_selector=<function <lambda> at 0x9730374>, result_selector=<function <lambda> at 0x97303ac>)

Projects each element of a sequence to an intermediate new sequence, incorporating the index of the element, flattens the resulting sequence into one sequence and optionally transforms the flattened sequence using a selector function.

Note

This method uses deferred execution.

Parameters:

• collection_selector – A binary function mapping each element of the source sequence into an intermediate sequence, by incorporating its index in the source sequence. The two positional arguments to the function are the zero-based index of the source element and the value of the element. The result of the function should be an iterable derived from the index and element value. If no collection_selector is provided, the elements of the intermediate sequence will consist of tuples of (index, element) from the source sequence.
• result_selector – An optional binary function mapping the elements in the flattened intermediate sequence together with their corresponding source elements to elements of the result sequence. The two positional arguments of the result_selector are, first the source element corresponding to an element from the intermediate sequence, and second the actual element from the intermediate sequence. The return value should be the corresponding value in the result sequence. If no result_selector function is provided, the elements of the flattened intermediate sequence are returned untransformed.

Returns:

A Queryable over a generated sequence whose elements are the result of applying the one-to-many collection_selector to each element of the source sequence which incorporates both the index and value of the source element, concatenating the results into an intermediate sequence, and then mapping each of those elements through the result_selector into the result sequence.

Raises :

• ValueError - If this Queryable has been closed.
• TypeError - If projector [and selector] are not callable.

select_with_index(selector=<function <lambda> at 0x97302cc>)

Transforms each element of a sequence into a new form, incorporating the index of the element.

Each element is transformed through a selector function which accepts the element value and its zero-based index in the source sequence. The generated sequence is lazily evaluated.

Note

This method uses deferred execution.

Parameters:

selector – A binary function mapping the index of a value in the source sequence and the element value itself to the corresponding value in the generated sequence. The two positional arguments of the selector function are the zero- based index of the current element and the value of the current element. The return value should be the corresponding value in the result sequence. The default selector produces a 2-tuple containing the index and the element giving this function similar behaviour to the built-in enumerate().

Returns:

A Queryable whose elements are the result of invoking the selector function on each element of the source sequence

Raises :

• ValueError - If this Queryable has been closed.
• TypeError - If selector is not callable.

sequence_equal(second_iterable, equality_comparer=<built-in function eq>)

Note

This method uses immediate execution.

single(predicate=None)

The only element (which satisfies a condition).

If the predicate is omitted or is None this query returns the only element in the sequence; otherwise, it returns the only element in the sequence for which the predicate evaluates to True. Exceptions are raised if there is either no such element or more than one such element.

Note

This method uses immediate execution.

Parameters:

predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the only element of the source sequence will be returned.

Returns:

The only element of the sequence if predicate is None, otherwise the only element for which the predicate returns True.

Raises :

• ValueError - If the Queryable is closed.
• ValueError - If, when predicate is None the source sequence contains

more than one element.

• ValueError - If there are no elements matching the predicate or more

then one element matching the predicate.

• TypeError - If the predicate is not callable.

single_or_default(default, predicate=None)

The only element (which satisfies a condition) or a default.

If the predicate is omitted or is None this query returns the only element in the sequence; otherwise, it returns the only element in the sequence for which the predicate evaluates to True. A default value is returned if there is no such element. An exception is raised if there is more than one such element.

Note

This method uses immediate execution.

Parameters:

• default – The value which will be returned if either the sequence is empty or there are no elements matching the predicate.
• predicate – An optional unary predicate function, the only argument to which is the element. The return value should be True for matching elements, otherwise False. If the predicate is omitted or None the only element of the source sequence will be returned.

Returns:

The only element of the sequence if predicate is None, otherwise the only element for which the predicate returns True. If there are no such elements the default value will returned.

Raises :

• ValueError - If the Queryable is closed.
• ValueError - If, when predicate is None the source sequence contains

more than one element.

• ValueError - If there is more then one element matching the

predicate.

• TypeError - If the predicate is not callable.

skip(count=1)

Skip the first count contiguous elements of the source sequence.

If the source sequence contains fewer than count elements returns an empty sequence and does not raise an exception.

Note

This method uses deferred execution.

Parameters:count – The number of elements to skip from the beginning of the sequence. If omitted defaults to one. If count is less than one the result sequence will be empty. Returns:A Queryable over the elements of source excluding the first count elements. Raises :ValueError - If the Queryable is closed().

skip_while(predicate)

Omit elements from the start for which a predicate is True.

Note

This method uses deferred execution.

Parameters:

predicate – A single argument predicate function.

Returns:

A Queryable over the sequence of elements beginning with the first element for which the predicate returns False.

Raises :

• ValueError - If the Queryable is closed().
• TypeError - If predicate is not callable.

sum(selector=<function identity at 0x9722b8c>)

Return the arithmetic sum of the values in the sequence..

All of the source sequence will be consumed.

Note

This method uses immediate execution.

Parameters:selector – An optional single argument function which will be used to project the elements of the sequence. If omitted, the identity function is used. Returns:The total value of the projected sequence, or zero for an empty sequence. Raises :ValueError - If the Queryable has been closed.

take(count=1)

Returns a specified number of elements from the start of a sequence.

If the source sequence contains fewer elements than requested only the available elements will be returned and no exception will be raised.

Note

This method uses deferred execution.

Parameters:count – An optional number of elements to take. The default is one. Returns:A Queryable over the first count elements of the source sequence, or the all elements of elements in the source, whichever is fewer. Raises :ValueError - If the Queryable is closed()

take_while(predicate)

Returns elements from the start while the predicate is True.

Note

This method uses deferred execution.

Parameters:

predicate – A function returning True or False with which elements will be tested.

Returns:

A Queryable over the elements from the beginning of the source sequence for which predicate is True.

Raises :

• ValueError - If the Queryable is closed()
• TypeError - If the predicate is not callable.

to_dictionary(key_selector=<function identity at 0x9722b8c>, value_selector=<function identity at 0x9722b8c>)

Build a dictionary from the source sequence.

Note

This method uses immediate execution.

Raises :ValueError - If duplicate keys are in the projected source sequence.

to_list()

Note

This method uses immediate execution.

to_lookup(key_selector=<function identity at 0x9722b8c>, value_selector=<function identity at 0x9722b8c>)

Returns a Lookup object, using the provided selector to generate a key for each item.

Note

This method uses immediate execution.

to_set()

Build a dictionary from the source sequence.

Note

This method uses immediate execution.

Raises :

• ValueError - If duplicate keys are in the projected source sequence.
• ValueError - If the Queryable is closed()

to_tuple()

Note

This method uses immediate execution.

union(second_iterable, selector=<function identity at 0x9722b8c>)

Returns those elements which are either in the source sequence or in the second_iterable.

Note

This method uses deferred execution.

Parameters:

• second_iterable – Elements from this sequence are returns if they are not also in the source sequence.
• selector – An optional single argument function which is used to project the elements in the source and second_iterables prior to comparing them. If omitted the identity function will be used.

Returns:

A sequence containing all elements in the source sequence and second sequence.

Raises :

• ValueError - If the Queryable has been closed.
• TypeError - If the second_iterable is not in fact iterable.
• TypeError - If the selector is not callable.

where(predicate)

Filters elements according to whether they match a predicate.

Note

This method uses deferred execution.

Parameters:

predicate – A unary function which is applied to each element in the source sequence. Source elements for which the predicate returns True will be present in the result.

Returns:

A Queryable over those elements of the source sequence for which the predicate is True.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If the predicate is not callable.

zip(second_iterable, result_selector=<function <lambda> at 0x97312cc>)

Elementwise combination of two sequences.

The source sequence and the second iterable are merged element-by- element using a function to combine them into the single corresponding element of the result sequence. The length of the result sequence is equal to the length of the shorter of the two input sequences.

Note

This method uses deferred execution.

Parameters:

• second_iterable – The second sequence to be combined with the source sequence.
• result_selector – An optional binary function for combining corresponding elements of the source sequences into an element of the result sequence. The first and second positional arguments are the elements from the source sequences. The result should be the result sequence element. If omitted, the result sequence will consist of 2-tuple pairs of corresponding elements from the source sequences.

Returns:

A Queryable over the merged elements.

Raises :

• ValueError - If the Queryable is closed.
• TypeError - If result_selector is not callable.

asq.queryable.asq(iterable)

Make an iterable queryable.

Use this function as an entry-point to the asq system of chainable query methods.

Note

Currently this factory only provides support for objects supporting

Parameters:iterable – Any object supporting the iterator protocol. Returns:An instance of Queryable. Raises :TypeError - If iterable is not actually iterable

asq.queryable.empty()

An empty Queryable.

Note

The same empty instance will be returned each time.

Returns:A Queryable over an empty sequence.

asq.queryable.identity(x)

The identity function.

Parameters:x – A value that will be returned. Returns:The argument x.

asq.queryable.integers(start, count)

Generates in sequence the integral numbers within a range.

Note

This method uses deferred execution.

Parameters:

• start – The first integer in the sequence.
• count – The number of sequential integers to generate.

Returns:

A Queryable over the specified range of integers.

Raises :

ValueError - If count is negative.

asq.queryable.is_iterable(obj)

Determine if an object is iterable.

Parameters:obj – The object to be tested for supporting iteration. Returns:True if the object is iterable, otherwise False.

asq.queryable.is_type(obj)

Determine if an object is a type.

Parameters:obj – The object to be tested for being a type, or a tuple of types. Returns:True if the object is a type or tuple of types, otherwise False.

asq.queryable.repeat(element, count)

Generate a sequence with one repeated value.

Note

This method uses deferred execution.

Parameters:

• element – The value to be repeated.
• count – The number of times to repeat the value.

Raises :

ValueError - If the count is negative.

Parallel asq

Parallel asq uses Python’s multiprocessing library to distribute the effort

class asq.parallel_queryable.OrderedParallelQueryable(iterable, func=None, pool=None, chunksize=1)

A ParallelQueryable representing an ordered iterable.

Warning

This parallel query functionality should be considered to be alpha quality.

select(selector)

Transforms each element of a sequence into a new form.

Each element is transformed through a selector function to produce a value for each value in the source sequence. The generated sequence is lazily evaluated.

Parameters:selector –

A unary function mapping a value in the source sequence to the corresponding value in the generated generated sequence. The argument of the selector function (which can have any name) is,

Args:

element: The value of the element

Returns:

The selected value derived from the element value

Returns:A generated sequence whose elements are the result of invoking the selector function on each element of the source sequence.

class asq.parallel_queryable.ParallelQueryable(iterable, pool=None, chunksize=1)

A parallel version of Queryable using the multiprocessing module.

Warning

This parallel query functionality should be considered to be alpha quality.

select(selector)

Transforms each element of a sequence into a new form.

Each element is transformed through a selector function to produce a value for each value in the source sequence. The generated sequence is lazily evaluated.

Parameters:selector –

A unary function mapping a value in the source sequence to the corresponding value in the generated generated sequence. The argument of the selector function (which can have any name) is,

Args:

element: The value of the element

Returns:

The selected value derived from the element value

Returns:A generated sequence whose elements are the result of invoking the selector function on each element of the source sequence.

select_many(projector, selector=<function identity at 0x9722b8c>)

Projects each element of a sequence to an intermediate new sequence, flattens the resulting sequence into one sequence and optionally transforms the flattened sequence using a selector function.

Parameters:

• projector –

  A unary function mapping each element of the source sequence into an intermediate sequence. If no projection function is provided, the intermediate sequence will consist of the single corresponding element from the source sequence. The projector function argument (which can have any name) and return values are,

  Args:

  element: The value of the element

  Returns:

  An iterable derived from the element value

• selector –

  An optional unary functon mapping the elements in the flattened intermediate sequence to corresponding elements of the result sequence. If no selector function is provided, the identity function is used. The selector function argument and return values are,

  Args:

  element: The value of the intermediate element from the concatenated sequences arising from the

  projector function.

  Returns:

  The selected value derived from the element value

Returns:

A generated sequence whose elements are the result of projecting each element of the source sequence using projector function and then mapping each element through an optional selector function.

select_with_index(selector)

Transforms each element of a sequence into a new form, incorporating the index of the element.

Each element is transformed through a selector function which accepts the element value and its zero-based index in the source sequence. The generated sequence is lazily evaluated.

Parameters:selector –

A two argument function mapping the index of a value in the source sequence and the element value itself to the corresponding value in the generated sequence. The two arguments of the selector function (which can have any names) and its return value are,

Args:

index: The zero-based index of the element element: The value of the element

Returns:

The selected value derived from the index and element

Returns:A generated sequence whose elements are the result of invoking the selector function on each element of the source sequence

asq.parallel_queryable.partition(iterable, floor=1, ceiling=32768)

Partition an iterable into chunks. Returns an iterator over partitions.

asq.parallel_queryable.realize_partitions(iterable, floor=1, ceiling=32768)

Partition the input sequence into a list of lists