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.
yany
— Extended version of the builtin any, test if any values are trueyall
— Extended version of the builtin all, test if all values are truefirst
— Get the first value from an iteraterablelast
— Get the final value from an iteraterablehead
— Get the first values from an iteraterabletail
— Get the last values from an iteraterablefinish
— Complete an iterator and get number of valuesminmax
— Find the minimum and maximum values from an iterableminmedmax
— Find the minimum, median, and maximum values from an iterableisiter
— Test if an object is iterable, but not a string typecontain
— Copy an iterator into a list if it is not already a sequence
Iterators
There are several iterators that wrap an existing iterator and process it's output.
call
— Iterator that works with mixed callable typespercent
— Iterator that skips a percentage of valuesflat
— Iterator of values from a iterable of iteratorschunk
— Iterator of lists with a fixed size from iterablekey
— Iterator of pairs of key result and original valuesunique
— Iterate only the unique valuesduplicate
— Iterate only the duplicated values
Keys
Utility functions that are useful to use as a key argument
formatter
— Create a function that formats given values into stringsnumeric
— Split a string into string and integer sectionsgetter
— Shorthand for attrgetter, itemgetter, and methodcaller operators
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
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']