les_iterables.selecting module

Summary

Functions:

element_at
offset_iterators	Produce two iterators which are offset from each other by a given number of items.
preceding	The item which comes in the series immediately before the specified item.
reject_falsy	Reject those items which evaluate to False in a boolean context.
reject_if	Retain those items for which predicate evaluates to True.
reject_if_none	Reject those items which are None.
reject_truthy	Reject those items which evaluate to True in a boolean context.
relative_to	Return the item relative to the nth occurrence of some existing item.
retain_falsy	Retain those items which evaluate to False in a boolean context.
retain_if	Retain those items for which predicate evaluates to True.
retain_if_not_none	Retain those items which are not None.
retain_truthy	Retain those items which evaluate to True in a boolean context.
single
skip_while	Skip leading items while the predicate matches.
succeeding	The item which comes in the series immediately after the specified item.
take_after_inclusive	Yield items starting with the first match.
take_after_last_match	Yield items in an iterable series after the last matching.
take_before_exclusive	Yield items up to but excluding including the first match.
take_before_inclusive	Yield items up to and including the first match.
take_between_inclusive	A list of items from the first matching to the last matching inclusive.
take_between_inclusive_values	A list of items from the first matching to the last matching inclusive.
take_until_exclusive	Yield items up to but excluding the first match.
take_until_inclusive	Yield items up and including the first match.
transform_if	Apply a transformation to items which match a predicate.

Reference

les_iterables.selecting.single(iterable)

les_iterables.selecting.element_at(iterable, index, *, start=0)

les_iterables.selecting.retain_if(predicate, iterable)

Retain those items for which predicate evaluates to True.

Example

>>> list(retain_if(lambda x: x%2 == 0, range(10)))
[0, 2, 4, 6, 8]

Parameters:

• predicate – A single-argument callable to which each item of iterable will be passed in turn to determine whether it should be retained, by returning True, or rejected, by returning False.

• iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which predicate returns True.

les_iterables.selecting.reject_if(predicate, iterable)

Retain those items for which predicate evaluates to True.

Example

>>> list(reject_if(lambda x: x%2 == 0, range(10)))
[1, 3, 5, 7, 9]

Parameters:

• predicate – A single-argument callable to which each item of iterable will be passed in turn to determine whether it should be rejected, by returning True, or retained, by returning False.

• iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which predicate returns False.

les_iterables.selecting.reject_if_none(iterable)

Reject those items which are None.

Example

>>> list(reject_if_none(, [1, 3, None, 7, None]))
[1, 3, 7]

Parameters:

iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items without None values.

les_iterables.selecting.retain_if_not_none(iterable)

Retain those items which are not None.

Example

>>> list(retain_if_not_none(, [1, 3, None, 7, None]))
[1, 3, 7]

Returns:

An iterable series of items without None values.

les_iterables.selecting.retain_truthy(iterable)

Retain those items which evaluate to True in a boolean context.

Parameters:

iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which bool(item) is True.

les_iterables.selecting.retain_falsy(iterable)

Retain those items which evaluate to False in a boolean context.

Parameters:

iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which bool(item) is True.

les_iterables.selecting.reject_truthy(iterable)

Reject those items which evaluate to True in a boolean context.

Parameters:

iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which bool(item) is False.

les_iterables.selecting.reject_falsy(iterable)

Reject those items which evaluate to False in a boolean context.

Parameters:

iterable – The iterable series of items to be filtered.

Returns:

An iterable series of items for which bool(item) is True.

les_iterables.selecting.take_after_last_match(iterable, predicate)

Yield items in an iterable series after the last matching.

Warning

This function potentially allocates sufficient space to store the entire series.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select items.

Returns:

A sequence containing the tail of the iterable series after the last match.

les_iterables.selecting.take_after_inclusive(iterable, predicate)

Yield items starting with the first match.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select the first item.

Yields:

Items starting with the first match.

les_iterables.selecting.take_before_inclusive(iterable, predicate)

Yield items up to and including the first match.

If no matching item is present, the result is empty.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select the last item.

Returns:

A sequence of items finishing with the first match.

les_iterables.selecting.take_before_exclusive(iterable, predicate)

Yield items up to but excluding including the first match.

If no matching item is present, the result is empty.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select the last item.

Returns:

A sequence of items finishing with the first match.

les_iterables.selecting.take_until_inclusive(iterable, predicate)

Yield items up and including the first match.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select item after the last item.

Returns:

A series of items finishing with but excluding the first match.

les_iterables.selecting.take_until_exclusive(iterable, predicate)

Yield items up to but excluding the first match.

Parameters:

• iterable – An iterable series of items.

• predicate – A function of one argument used to select item after the last item.

Returns:

A series of items finishing with but excluding the first match.

les_iterables.selecting.take_between_inclusive(iterable, first_predicate, last_predicate)

A list of items from the first matching to the last matching inclusive.

Parameters:

• iterable – An iterable series of items.

• first_predicate – A function of one argument used to select the first item in the result.

• last_predicate – A function of one argument used to select the last item in the result.

• Returns – Either a sequence of at least two elements, or an empty sequence if elements matching the first predicate and the last predicate were not both found.

les_iterables.selecting.take_between_inclusive_values(iterable, first, last)

A list of items from the first matching to the last matching inclusive.

Parameters:

• iterable – An iterable series of items.

• first – A value marking the start of the result sequence.

• last – A value marking the end of the result sequence.

• Returns – Either a sequence of at least two elements, or an empty sequence if elements matching the first predicate and the last predicate were not both found.

les_iterables.selecting.preceding(iterable, item)

The item which comes in the series immediately before the specified item.

Parameters:

• iterable – The iterable series in which to search for item.

• item – The item to search for in iterable.

Returns:

The previous item.

Raises:

ValueError – If item is not present in iterable beyond the first item.

les_iterables.selecting.succeeding(iterable, item)

The item which comes in the series immediately after the specified item.

Parameters:

• iterable – The iterable series in which to search for item.

• item – The item to search for in iterable.

Returns:

The next item.

Raises:

ValueError – If the item is not present before the penultimate item.

les_iterables.selecting.relative_to(iterable, item, *, offset, n=0, default=<object object>)

Return the item relative to the nth occurrence of some existing item.

Parameters:

• iterable – The iterable series from which to search for item.

• item – The value to relative to which the returned item should be.

• offset – The positive or negative offset relative to the found item.

• n – Where it is the nth occurrence of item which will be searched for.

• default – The default value to return if not found.

Returns:

The item at a given offset from a specific value, or the default value if given.

Raises:

ValueError – If there is not item matching the criteria an no default value has been specified.

les_iterables.selecting.offset_iterators(iterable, offset: int)

Produce two iterators which are offset from each other by a given number of items.

Once offset_iterators() has been called, and if the original itererable is an iterator (as opposed to a iterablecollection), the iterator should not be used anywhere else; otherwise, the iterator could get advanced without the offset_iterators objects being informed.

The produced iterators will start with the requested offset but are independent and can be advanced independently. To keep them synchronized, consider iterating over them in lockstep using zip().

Note that:

p, q = offset_iterators(iterable, 0)

is equivalent to:

p, q = itertools.tee(iterable)

Parameters:

• iterable – An iterable from which to return two iterators separated by offset.

• offset – An integer offset by which the two iterators should be separated. This offset can be positive or negative.

Returns:

Two iterators, the second of which will be offset from the first by the specified number (positive, negative or zero) places.

Raises:

ValueError – If the iterable is not long enough to accommodate two iterators separated by the specified offset.

les_iterables.selecting.skip_while(iterable, predicate)

Skip leading items while the predicate matches.

Parameters:

• iterable – An iterable of items.

• predicate – A predicate function with which to test items.

Yields:

Those items including and after the first which doesn’t match the predicate.

les_iterables.selecting.transform_if(iterable, predicate, transform)

Apply a transformation to items which match a predicate.

Non-matching items will not be transformed.

Parameters:

• iterable – An iterable of items.

• predicate – predicate: A predicate function with which to select items to be transformed.

• transform – A unary function which accepts an item to be transformed and returns the transformed item.

Yields:

An iterable series of items.