asq.predicates

Predicate function factories

Predicates are boolean functions which return True or False.

Predicate factories

The predicate factories partially apply the binary comparison operators by providing the right-hand-side argument. The result is a unary function the single argument to which is the left-hand-side of the comparison operator.

For example. the lt_(rhs) predicate factory returns:

lambda lhs: lhs < rhs

where rhs is provided when the predicate is created but lhs takes the value passed to the unary predicate.

contains_	Create a unary predicate which tests for membership if its argument.
eq_	Create a predicate which tests its argument for equality with a value.
is_	Create a predicate which performs an identity comparison of its argument with a value.
ge_	Create a predicate which performs a greater-than-or-equal comparison of its argument with a value.
gt_	Create a predicate which performs a greater-than comparison of its argument with a value.
le_	Create a predicate which performs a less-than-or-equal comparison of its argument with a value.
lt_	Create a predicate which performs a less-than comparison of its argument with a value.
ne_	Create a predicate which tests its argument for inequality with a value.

asq.predicates.contains_(lhs)

Create a unary predicate which tests for membership if its argument.

Parameters:lhs – (left-hand-side) The value to test for membership for in the predicate argument. Returns:A unary predicate function which determines whether its single arguments (lhs) contains lhs.

Example

Filter for specific words containing ‘ei’:

>>> words = ['banana', 'receive', 'believe', 'ticket', 'deceive']
>>> query(words).where(contains_('ei')).to_list()
['receive', 'deceive']

asq.predicates.eq_(rhs)

Create a predicate which tests its argument for equality with a value.

Parameters:rhs – (right-hand-side) The value with which the left-hand-side element will be compared for equality. Returns:A unary predicate function which compares its single argument (lhs) for equality with rhs.

Example

Filter for those numbers equal to five:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(eq_(5)).to_list()
[5, 5]

asq.predicates.is_(rhs)

Create a predicate which performs an identity comparison of its argument with a value.

Parameters:rhs – (right-hand-side) The value against which the identity test will be performed. Returns:A unary predicate function which determines whether its single arguments (lhs) has the same identity - that is, is the same object - as rhs.

Example

Filter for a specific object by identity:

>>> sentinel = object()
>>> sentinel
<object object at 0x0000000002ED8040>
>>> objects = ["Dinosaur", 5, sentinel, 89.3]
>>> query(objects).where(is_(sentinel)).to_list()
[<object object at 0x0000000002ED8040>]
>>>

asq.predicates.ge_(rhs)

Create a predicate which performs a greater-than-or-equal comparison of its argument with a value.

Parameters:rhs – (right-hand-side) The value against which the greater-than-or- equal test will be performed. Returns:A unary predicate function which determines whether its single argument (lhs) is greater-than rhs.

Example

Filter for those numbers greater-than-or-equal to 43:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(ge_(43)).to_list()
[89, 67, 43]

asq.predicates.gt_(rhs)

Create a predicate which performs a greater-than comparison of its argument with a value.

Parameters:rhs – (right-hand-side) The value against which the greater-than test will be performed. Returns:A unary predicate function which determines whether its single argument (lhs) is less-than-or-equal to rhs.

Example

Filter for those numbers greater-than 43:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(gt_(43)).to_list()
[89, 67]

asq.predicates.le_(rhs)

Create a predicate which performs a less-than-or-equal comparison of its argument with a value.

Parameters:rhs – (right-hand-side) The value against which the less-than-or-equal test will be performed. Returns:A unary predicate function which determines whether its single argument (lhs) is less-than-or-equal to rhs.

Example

Filter for those numbers less-than-or-equal to 43:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(le_(43)).to_list()
[5, 9, 12, 5, 34, 2, 43]

asq.predicates.lt_(rhs)

Create a predicate which performs a less-than comparison of its argument with a value.

Parameters:rhs – (right-hand-side) The value against which the less-than test will be performed. Returns:A unary predicate function which determines whether its single argument (lhs) is less-than rhs.

Example

Filter for those numbers less-than-or-equal to 43:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(lt_(43)).to_list()
[5, 9, 12, 5, 34, 2]

asq.predicates.ne_(rhs)

Create a predicate which tests its argument for inequality with a value.

Parameters:rhs – (right-hand-side) The value with which the left-hand-side element will be compared for inequality. Returns:A unary predicate function which compares its single argument (lhs) for inequality with rhs.

Example

Filter for those numbers not equal to 5:

>>> numbers = [5, 9, 12, 5, 89, 34, 2, 67, 43]
>>> query(numbers).where(ne_(5)).to_list()
[9, 12, 89, 34, 2, 67, 43]

Predicate combinators

Predicate combinators allow the predicate factories to be modified and combined in a concise way. For example, we can write:

or_(lt_(5), gt_(37))

which will produce a predicate equivalent to:

lambda lhs: lhs < 5 or lhs > 37

which can be applied to each element of a sequence to test whether the element is outside the range 5 to 37.

and_	A predicate combinator which produces the a new predicate which is the logical conjunction of two existing unary predicates.
not_	A predicate combinator which negates produces an inverted predicate.
or_	A predicate combinator which produces the a new predicate which is the logical disjunction of two existing unary predicates.
xor_	A predicate combinator which produces the a new predicate which is the logical exclusive disjunction of two existing unary predicates.

asq.predicates.and_(predicate1, predicate2)

A predicate combinator which produces the a new predicate which is the logical conjunction of two existing unary predicates.

The predicate returned by this combinator returns True when both of the two supplied predicates return True, otherwise it returns False.

Parameters:

• predicate1 – A unary predicate function.
• predicate2 – A unary predicate function.

Returns:

A unary predicate function which is the logical conjunction of predicate1 and predicate2.

..rubric:: Example

Filter a list for all the words which both start with ‘a’ and end ‘t’:

>>> words = ['alphabet', 'train', 'apple', 'aghast', 'tent', 'alarm']
>>> query(words).where(and_(m_('startswith', 'a'), m_('endswith', 't'))).to_list()
['alphabet', 'aghast']

asq.predicates.not_(predicate)

A predicate combinator which negates produces an inverted predicate.

The predicate returned by this combinator is the logical inverse of the supplied combinator.

Parameters:predicate – A unary predicate function to be inverted. Returns:A unary predicate function which is the logical inverse of pred.

Example

Filter a list for all the word which do not contain a specific sentinel object:

>>> sentinel = object()
>>> objects = ["Dinosaur", 5, sentinel, 89.3]
>>> query(objects).where(not_(is_(sentinel))).to_list()
['Dinosaur', 5, 89.3]

asq.predicates.or_(predicate1, predicate2)

A predicate combinator which produces the a new predicate which is the logical disjunction of two existing unary predicates.

The predicate returned by this combinator returns True when either or both of the two supplied predicates return True, otherwise it returns False.

Parameters:

• predicate1 – A unary predicate function.
• predicate2 – A unary predicate function.

Returns:

A unary predicate function which is the logical disjunction of predicate1 and predicate2.

Example

Filter a list for all words which either start with ‘a’ or end with ‘t’:

>>> words = ['alphabet', 'train', 'apple', 'aghast', 'tent', 'alarm']
>>> query(words).where(or_(m_('startswith', 'a'), m_('endswith', 't'))).to_list()
['alphabet', 'apple', 'aghast', 'tent', 'alarm']

asq.predicates.xor_(predicate1, predicate2)

A predicate combinator which produces the a new predicate which is the logical exclusive disjunction of two existing unary predicates.

The predicate returned by this combinator returns True when the two supplied predicates return the different values, otherwise it returns False.

Parameters:

• predicate1 – A unary predicate function.
• predicate2 – A unary predicate function.

Returns:

A unary predicate function which is the logical exclusive disjunction of predicate1 and predicate2.

Example

Filter a list for all words which either start with ‘a’ or end with ‘t’ but not both:

>>> words = ['alphabet', 'train', 'apple', 'aghast', 'tent', 'alarm']
>>> query(words).where(xor_(m_('startswith', 'a'), m_('endswith', 't'))).to_list()
['apple', 'tent', 'alarm']