Package: ebbe
EbbeA collection of typical helper functions for python that cannot be found in the however great standard library.InstallationYou can installebbewith pip with the following command:pip install ebbeUsageIterator functionsas_chunksas_gramsfail_fastuniqdistinctwith_prevwith_prev_and_nextwith_nextwith_is_firstwith_is_lastwithout_firstwithout_lastUtilitiesgetgettergetpathpathgetterindexedgroupedpartitionedsorted_uniqpickomitFunctional ProgrammingnoopcomposercomposeFormattingand_joinformat_intformat_timeTODO:format_repr,format_filesizeDecoratorsdecorators.fail_fastdecorators.with_deferBenchmarkingTimeras_chunksIterate over chunks of the desired size by grouping items as we iterate over them.fromebbeimportas_chunkslist(as_chunks(3,[1,2,3,4,5]))>>>[[1,2,3],[4,5]]as_gramsIterate over grams (sometimes called n-grams or q-grams etc.) of the given iterable. It works with strings, lists and other sized sequences as well as with lazy iterables without consuming any superfluous memory while doing so.fromebbeimportas_gramslist(as_grams(3,'hello'))>>>['hel','ell','llo']list(as_grams(2,(i*2foriinrange(5))))>>>[(0,2),(2,4),(4,6),(6,8)]fail_fastTake an iterable (but this has been geared towards generators, mostly), and tries to access the first value to see if an Exception will be raised before returning an equivalent iterator.This is useful with some badly-conceived generators that checks arguments and raise if they are not valid, for instance, and if you don't want to wrap the whole iteration block within a try/except.This logic is also available as adecorator.fromebbeimportfail_fastdefhellraiser(n):ifn>10:raiseTypeErroryield fromrange(n)# You will need to do this to catch the error:gen=hellraiser(15)try:foriingen:print(i)exceptTypeError:print('Something went wrong when creating the generator')# With fail_fasttry:gen=fail_fast(hellraiser(15))exceptTypeError:print('Something went wrong when creating the generator')foriingen:print(i)uniqFilter repeated items, optionally by key, seen next to each other in the given iterator.fromebbeimportuniqlist(uniq([1,1,1,2,3,4,4,5,5,6]))>>>[1,2,3,4,5,6]# BEWARE: it does not try to remember items (like the `uniq` command)list(uniq([1,2,2,3,2]))>>>[1,2,3,2]# Using a keylist(uniq([(1,2),(1,3),(2,4)],key=lambdax:x[0]))>>>[(1,2),(2,4)]distinctFilter repeated items, optionally by key, in the given iterator.fromebbeimportdistinctlist(distinct([0,3,4,4,1,0,3]))>>>[0,3,4,1]list(distinct(range(6),key=lambdax:x%2))>>>[0,1]with_prevIterate over items along with the previous one.fromebbeimportwith_prevforprevious_item,iteminwith_prev(iterable):print(previous_item,'came before',item)list(with_prev([1,2,3]))>>>[(None,1),(1,2),(2,3)]with_prev_and_nextIterate over items along with the previous and the next one.fromebbeimportwith_prev_and_nextforprevious_item,item,next_iteminwith_prev_and_next(iterable):print(previous_item,'came before',item)print(next_item,'will come after',item)list(with_prev_and_next([1,2,3]))>>>[(None,1,2),(1,2,3),(2,3,None)]with_nextIterate over items along with the next one.fromebbeimportwith_nextforitem,next_iteminwith_next(iterable):print(next_item,'will come after',item)list(with_next([1,2,3]))>>>[(1,2),(2,3),(3,None)]with_is_firstIterate over items along with the information that the current item is the first one or not.fromebbeimportwith_is_firstforis_first,iteminwith_is_first(iterable):ifis_first:print(item,'is first')else:print(item,'is not first')list(with_is_first([1,2,3]))>>>[(True,1),(False,2),(False,3)]with_is_lastIterate over items along with the information that the current item is the last one or not.fromebbeimportwith_is_lastforis_last,iteminwith_is_last(iterable):ifis_last:print(item,'is last')else:print(item,'is not last')list(with_is_last([1,2,3]))>>>[(False,1),(False,2),(True,3)]without_firstIterate over the given iterator after skipping its first item. Can be useful if you want to skip headers of a CSV file for instance.fromebbeimportwithout_firstlist(without_first([1,2,3]))>>>[2,3]forrowinwithout_first(csv.reader(f)):print(row)without_lastIterate over the given iterator but skipping its last item.fromebbeimportwithout_lastlist(without_last([1,2,3]))>>>[1,2]getOperator function similar tooperator.getitembut able to take a default value.fromebbeimportgetget([1,2,3],1)>>>2get([1,2,3],4)>>>None# With default valueget([1,2,3],4,35)>>>35getterOperator factory similar tooperator.itemgetterbut able to take a default value.fromebbeimportgetterget_second_or_thirty=getter(1,30)get_second_or_thirty([1,2,3])>>>2get_second_or_thirty([1])>>>30# Overriding default on the spotget_second_or_thirty([1],76)>>>76getpathOperator function used to retrieve a value at given path in a nested structure or a default value if this value cannot be found.fromebbeimportgetpathdata={'a':{'b':[{'c':34},'test'],'d':'hello'}}getpath(data,['a','b',0,'c'])>>>34getpath(data,['t','e','s','t'])>>>None# Using a default return valuegetpath(data,['t','e','s','t'],45)>>>45# Using a string pathgetpath(data,'a.b.d',split_char='.')>>>'hello'Argumentstargetany: target object.pathiterable: path to get.default?any[None]: default value to return.items?bool[True]: whether to attempt to traverse keys and indices.attributes?bool[False]: whether to attempt to traverse attributes.split_char?str: if given, will split strings passed as path instead of raisingTypeError.parse_indices?bool[False]: whether to parse integer indices when splitting string paths.pathgetterFunction returning a getter function working asgetpathand partially applied to use the provided path or paths.fromebbeimportpathgetterdata={'a':{'b':[{'c':34},'test'],'d':'hello'}}getter=pathgetter(['a','b',0,'c'])getter(data)>>>34getter=pathgetter(['t','e','s','t'])getter(data)>>>None# Using a default return valuegetter=pathgetter(['t','e','s','t'])getter(data,45)>>>45# Using a string pathgetter=pathgetter('a.b.d',split_char='.')getter(data)>>>'hello'# Using multiple pathsgetter=pathgetter(['a','b',0,'c'],['t','e','s','t'],['a','b','d'])getter(data)>>>(34,None,'hello')Argumentspathslist: paths to get.items?bool[True]: whether to attempt to traverse keys and indices.attributes?bool[False]: whether to attempt to traverse attributes.split_char?str: if given, will split strings passed as path instead of raisingTypeError.parse_indices?bool[False]: whether to parse integer indices when splitting string paths.Getter argumentstargetany: target object.default?any[None]: default value to return.indexedFunction indexing the given iterable in a dict-like structure. This is basically just some functional sugar over adictconstructor.fromebbeimportindexedindexed(range(3),key=lambdax:x*10)>>>{0:0,10:1,20:2}groupedFunction grouping the given iterable by a key.fromebbeimportgroupedgrouped(range(4),key=lambdax:x%2)>>>{0:[0,2],1:[1,3]}# Using an optional valuegrouped(range(4),key=lambdax:x%2,value=lambdax:x*10)>>>{0:[0,20],1:[10,30]}# Using the items variantfromebbeimportgrouped_itemsgrouped_items((x%2,x*10)foriinrange(4))>>>{0:[0,20],1:[10,30]}partitionedFunction partitioning the given iterable by key.fromebbeimportpartitionedpartitioned(range(4),key=lambdax:x%2)>>>[[0,2],[1,3]]# Using an optional valuepartitioned(range(4),key=lambdax:x%2,value=lambdax:x*10)>>>[[0,20],[10,30]]# Using the items variantfromebbeimportpartitioned_itemspartitioned_items((x%2,x*10)foriinrange(4))>>>[[0,20],[10,30]]sorted_uniqFunction sorting the given iterable then dropping its duplicate through a single linear pass over the data.fromebbeimportsorted_uniqnumbers=[3,17,3,4,1,4,5,5,1,-1,5]sorted_uniq(numbers)>>>[-1,1,3,4,5,17]# It accepts all of `sorted` kwargs:sorted_uniq(numbers,reverse=True)>>>[17,5,4,3,1,-1]pickFunction returning the given dictionary with only the selected keys.fromebbeimportpick# Selected keys must be an iterable:pick({'a':1,'b':2,'c':3},['a','c'])>>>{'a':1,'c':3}# If you need the function to raise if one of the picked keys is not found:pick({'a':1,'b':2,'c':3},['a','d'],strict=True)>>>KeyError:'d'omitFunction returning the given dictionary without the selected keys.fromebbeimportomit# Selected keys must be a container:omit({'a':1,'b':2,'c':3},['a','c'])>>>{'b':2}# If need to select large numbers of keys, use a set:omit({'a':1,'b':2,'c':3},{'a','c'})>>>{'b':2}noopNoop function (a function that can be called with any arguments and does nothing). Useful as a default to avoid complicating code sometimes.fromebbeimportnoopnoop()# Does nothing...noop(4,5)# Still does nothing...noop(4,index=65)# Nothing yet again...composeFunction returning the composition function of its variadic arguments.deftimes_2(x):returnx*2defplus_5(x):returnx+5compose(times_2,plus_5)(10)>>>30# Reverse ordercompose(times_2,plus_5,reverse=True)(10)>>>25rcomposeFunction returning the reverse composition function of its variadic arguments.deftimes_2(x):returnx*2defplus_5(x):returnx+5rcompose(times_2,plus_5)(10)>>>25and_joinJoin function able to group the last items with a custom copula such as "and".fromebbeimportand_joinand_join(['1','2','3'])>>>'1, 2 and 3'and_join(['1','2','3'],separator=';',copula="y")>>>'1; 2 y 3'format_intFormat given number as an int with thousands separator.fromebbeimportformat_intformat_int(4500)>>>'4,500'format_int(10000,separator=' ')>>>'10 000'format_timeFormat time with custom precision and unit from years to nanoseconds.fromebbeimportformat_timeformat_time(57309)>>>"57 microseconds and 309 nanoseconds"format_time(57309,precision="microseconds")>>>"57 microsecondsformat_time(78,unit="seconds")>>>"1 minute and 18 seconds"format_time(4865268458795)>>>"1 hour, 21 minutes, 5 seconds, 268 milliseconds, 458 microseconds and 795 nanoseconds"assertformat_time(4865268458795,max_items=2)>>>"1 hour and 21 minutes"format_time(4865268458795,short=True)>>>"1h, 21m, 5s, 268ms, 458µs, 795ns"decorators.fail_fastDecorate a generator function by wrapping it into another generator function that will fail fast if some validation is run before executing the iteration logic so that exceptions can be caught early.This logic is also available as afunction.fromebbe.decoratorsimportfail_fastdefhellraiser(n):ifn>10:raiseTypeErroryield fromrange(n)# This will not raise until you consume `gen`gen=hellraiser(15)@fail_fast()defhellraiser(n):ifn>10:raiseTypeErroryield fromrange(n)# This will raise immediatelygen=hellraiser(15)decorators.with_deferDecorates a function calling it with adeferkwarg working a bit like Go'sdefer statementso that you can "defer" actions to be done by the end of the function or when an exception is raised to cleanup or tear down things.This relies on anExitStackand can of course be also accomplished by context managers but this way of declaring things to defer can be useful sometimes to avoid nesting in complex functions.fromebbe.decoratorsimportwith_defer@with_defer()defmain(content,*,defer):f=open('./output.txt','w')defer(f.close)f.write(content)TimerContext manager printing the time (to stderr by default) it took to execute wrapped code. Very useful to run benchmarks.fromebbeimportTimerwithTimer():some_costly_operation()# Will print "Timer: ...s etc." on exit# To display a custom message:withTimer('my operation'):...# To print to stdoutimportsyswithTimer(file=sys.stdout):...