yter

Version 1.8.0 2016, June 1

Clever, quick iterator functions that make your smile whiter.

This will work with versions of Python 2.6+ and 3.2+. The tests also pass with recent Pypy and Jython releases.

Functions

There are many functions that process data from iterators in efficient ways.

Iterators

There are several iterators that wrap an existing iterator and process it's output.

Keys

Utility functions that are useful to use as a key argument

Reference

yany

yany(y, key=None, empty=False)

Extended version of the builtin any, test if any values are true.

Unlike the builtin any method, this will return the last value iterated before ending. This will short circuit or exit early when a correct answer is found.

A simple explanation is that this will be the first true value or the final false value of the interator. This is the same as calling the logical or operator on all the iterated values.

The key is an optional function that will be called on each value in iterator. The return of that function will be used to test if the value is true or false.

If the iterator is empty this will return the empty argument. This defaults to False, the same as the built in any.

yall

yall(y, key=None, empty=True)

Extended version of the builtin all, test if all values are true.

Unlike the builtin all method, this will return the last value iterated before ending. This will short circuit or exit early when a correct answer is found.

A simple explanation is that this will be the final true value or the first false value of the interator. This is the same as calling the logical and operator on all the iterated values.

The key is an optional function that will be called on each value in iterator. The return of that function will be used to test if the value is true or false.

If the iterable is empty this will return the empty argument. This defaults to True, the same as the built in all.

last

last(y, empty=None)

Get the final value from an iterator.

This will get the final value from an iterable object. If the iterable object can be reversed then that will be used to collect only the first value.

If the iterable contains no values then the empty argument is returned.

head(y, count)

Get the first values from an iterator.

This will be a list of values no larger than count. This will always advance the iterable object by the given count.

tail

tail(y, count)

Get the last values from an iterator.

This will be a list of values no larger than count. If the iterable object can be reversed then that will be used. Otherwise this will always finish the iterable object.

finish

finish(y)

Complete an iterator and get number of values.

Get all the values from an iterator and return the number of values it contained. An empty iterable will return 0.

minmax

minmax(y, key=None, empty=None)

Find the minimum and maximum values from an iterable.

This will always return a tuple of two values. If the iterable contains no values it the tuple will contain two values of the empty argument.

The minimum and maximum preserve order. So the first value that compares equal will be considered the minimum and the last equal value is considered the maximum. If you sorted the iterable, this is the same as the first and last values from that list.

The key is an optional function that will be called on each value in iterator. The return of that function will be used to sort the values from the iterator.

minmedmax

minmedmax(y, key=None, empty=None)

Find the minimum, median, and maximum values from an iterable.

This will always return a tuple of three values. If the iterable contains no values it the tuple will contain three values of the empty argument.

The minimum and maximum preserve order. So the first value that compares equal will be considered the minimum and the last equal value is considered the maximum. If you sorted the iterable, this is the same as the first and last values from that list.

Computing the median requires storing half of the iterated values in memory. This only keeps the minimum required data, but be aware of this overhead when dealing with large iterators.

The key is an optional function that will be called on each value in iterator. The return of that function will be used to sort the values from the iterator.

isiter

isiter(y, ignore=(<class 'str'>, <class 'bytes'>))

Test if an object is iterable, but not a string type.

Test if an object is an iterator or is iterable itself. By default this does not return True for string objects.

The ignore argument defaults to a list of string types that are not considered iterable. This can be used to also exclude things like dictionaries or named tuples.

contain

contain(y)

Copy an iterator into a list if it is not already a sequence.

If the value is already a container, like a list or tuple, then return the original value. Otherwise the value must be an iterator and it will be copied into a sequence.

repeat

repeat(y)

Return an object that can be iterated multiple times.

If the value is already a container that can be iterated, that that will be returned with no changes. Otherwise this will wrap the results in an iterator that copies its values for repeated use.

This allows efficient use of containers when no copy is needed to iterate the data multiple times.

call

call(y)

Iterator that works with mixed callable types.

Iterate over all the values from the input iterator. If one of the values is a callable object it will be called and its return will be the value instead.

The args and kwargs arguments will be passed to any callable values in the iterator.

percent

percent(y, percent)

Iterator that skips a percentage of values.

The percent is a floating point value between 0.0 and 1.0. If the value is larger than 1.0 it will be the same as 1.0. If the value is less than or equal to 0.0 no values will be iterated.

As long as the percent is greater than 0.0 the first value will always be iterated.

flat

flat(y)

Iterator of values from a iterable of iterators.

This removes a level of nesting. When given a list of lists this will iterate the values from those children lists.

This is the same as itertools.chain.from_iterable with a more memorable name.

This will invert the results of the chunk iterator.

chunk

chunk(y, size)

Iterator of lists with a fixed size from iterable.

Group the values from the iterable into lists up to a given size. The final list generated can be smaller than the given size.

key

key(y, key)

Iterator of pairs of key result and original values

Each value will be a tuple with the return result of the key function and the actual value itself. The key function will be called with each value of the input iterator.

This allows passing the generator to functions like min and sorted, but you are able to see the value and the result of the key argument.

formatter

formatter(fmt)

Create a function that formats given values into strings.

Additional keywoard arguments can be given that will also be passed to the format function.

The values passed to the formatter will be given as the first argument to format, which is referenecd as {0}.

numeric

numeric(value)

Split a string into string and integer sections.

A string will be a tuple containing sections that are strings and integers. The numeric parts of the string will be converted into integers.

This is a convenient way to sort string containing numbers that are not padded.

Negative numbers will also be converted if preceded by a single minus sign.

getter

Shorthand for the attrgetter, itemgetter, and methodcaller operators.

The same results can be achieved by using operator.attrgetter and operator.itemgetter, but this is more concise and can also be used to lookup nested data.

By using the special syntax, getter._(args) you can also create a callable. This is similar to the operator.methodcaller but it doesn't use a method name. The underscore attribute can be called to create a callable lookup, which can still be chained with item and attributes.

If an attribute or item is not found this will result in None instead of an exception, which is more useful for key functions.

You can lookup multiple items by passing multiple values to the index operator.

Looking up attributes can only be done with a single value.

>>> data = {"name": {"first": "Peter", "last": "Shinners"}, "id": 1234}
>>> key = yter.getter["name"]["first"]
>>> print(key(data))
"Peter"
>>> print(yter.getter.real(1.2))
1.2
>>> data = [bool, int, float, str]
>>> print [yter.getter._("12") for d in data]
[True, 12, 12.0, '12']