Functions

indices(object)

Returns the same as tuple(range(len(object))) -- a tad faster and a lot easier to type.

trange([start=0,]stop[,step=1])

This works like the builtin function range() but returns a tuple instead of a list. Since range() is most often used in for-loops there really is no need for a mutable data type and construction of tuples is somewhat (20%) faster than that of lists. So changing the usage of range() in for-loops to trange() pays off in the long run.

range_len(object)

Returns the same as range(len(object)).

tuples(a,b,c,...)

Returns much the same as map(None,a,b,c,...) does, except that the resulting list will always have the length of the first sequence. The function returns a list of tuples (a[0], b[0], c[0],...), (a[1], b[1], c[1],...), ... with missing elements being filled in with None. The latter case should be avoided, though, since no optimizations are done (map(None,...) performs better in these situations, well, sometimes :).

lists(seq)

Inverse of tuples(), except that None entries are not interpreted as being placeholders for missing entries. seq must be a sequence of sequences, e.g. a list of tuples. These are then converted into a tuple of lists. As with tuples(), the first item in the sequence decides how many lists will be created. All other items must have at least as many entries.

reverse(sequence)

Returns a tuple or list with the elements from sequence in reverse order. A tuple is returned, if the sequence itself is a tuple. In all other cases a list is returned.

dict(items)

Constructs a dictionary from the given items sequence. The sequence must contain sequence entries with at least two values. The first one is interpreted as key, the second one as associated object. Remaining values are ignored.

invdict(dictionary)

Constructs a new dictionary from the given one with inverted mappings. Keys become values and vice versa. Note that no exception is raised if the values are not unique. The result is undefined in this case (there is a value:key entry, but it is not defined which key gets used).

irange(object[,indices])

Builds a tuple of tuples (index,object[index]). If a sequence indices is given, the indices are read from it. If not, then the index sequence defaults to trange(len(object)). Note that object can be any object that can handle object[index], e.g. lists, tuples, string, dictionaries, even your own objects, if they provide a __getitem__-method. This makes very nifty constructions possible and extracting items from another sequence becomes a piece of cake. Give it a try ! You'll soon love this little function.

ifilter(condition,object[,indices])

Builds a list of tuples (index,object[index]) such that condition(object[index]) is true and index is found in the sequence indices (defaulting to trange(len(object))). Order is preserved. condition must be a callable object. Same comment as above.

get(object,index[,default])

Returns object[index], or, if that fails, default.

mget(object,indices[,defaults])

Builds a list with entries object[index] for each index in the sequence indices. If a lookup fails and the sequence defaults is given, then defaults[nth_index] is used, where nth_index is the index of index in indices (confused ? it works as expected !). defaults should have the same length as indices. If you need the indices as well, try the irange function. The function raises an IndexError in case it can't find an entry in indices or defaults.

findattr(object_list,attrname)

Returns the first attribute with name attrname found among the objects in the list. Raises an AttributeError if the attribute is not found.

napply(number_of_calls,function[,args=(),kw={}])

Calls the given function number_of_calls times with the same arguments and returns a tuple with the return values. This is roughly equivalent to a for-loop that repeatedly calls apply(function,args,kw) and stores the return values in a tuple. Example: create 10 instances of a certain class... objects = napply(10,Class,()).

mapply(callable_objects[,args=(),kw={}])

Creates a tuple of values by applying the given arguments to each object in the sequence callable_objects. This function has a functionality dual to that of map(). While map applies many different arguments to one callable object, this function applies one set of arguments to many different callable objects.

method_mapply(objects,methodname[,args=(),kw={}])

Creates a tuple of values by applying the given arguments to each object's <methodname> method. The objects are processed as given in the sequence objects. A simple application is e.g. method_mapply([a,b,c],'method', (x,y)) resulting in a tuple (a.method(x,y), b.method(x,y), c.method(x,y)). Thanks to Aaron Waters for suggesting this function.

count(condition,sequence)

Counts the number of objects in sequence for which condition returns true and returns the result as integer. condition must be a callable object.

exists(condition,sequence)

Return 1 if and only if condition is true for at least one of the items in sequence and 0 otherwise. condition must be a callable object.

forall(condition,sequence)

Return 1 if and only if condition is true for all of the items in sequence and 0 otherwise. condition must be a callable object.

index(condition,sequence)

Return the index of the first item for which condition is true. A ValueError is raised in case no item is found. condition must be a callable object.

sizeof(object)

Returns the number of bytes allocated for the given Python object. Additional space allocated by the object and stored in pointers is not taken into account (though the pointer itself is). If the object defines tp_itemsize in its type object then it is assumed to be a variable size object and the size is adjusted accordingly.

A note on the naming scheme used:

• i stands for indexed, meaning that you have access to indices
• m stands for multi, meaning that processing involves multiple objects
• n stands for n-times, e.g. a function is executed a certain number of times
• t stands for tuple
• x stands for lazy evaluation

Since this is (and will always be) work-in-progress, more functions will eventually turn up in this module, so stopping by every now and then is not a bad idea :-).

Objects

As of version 0.4 the package also includes a contribution by Christopher Tavares (see xmapmodule.c for his email address): an extension type for lazy evaluation of map()-constructs called xmap():

xmap(func, seq, [seq, seq, ...])

Constructs a new xmap object emulating map(func, seq, [seq, seq, ...]). The object behaves like a list, but evaluation of the function is postponed until a specific element from the list is requested. Unlike map, xmap can handle sequences not having a __len__ method defined (due to the evaluation-on-demand feature).

These objects define one method:

tolist()

Return the whole list giving the same result as the emulated map()-construct.

I am providing this extension AS-IS in this release, since I haven't had time yet to adapt it to my coding style.

Examples of Use

Usage should be clear, so I'll skip the examples (see the test.py script which is included in the archive for some rudimentary examples).

Package Structure

[NewBuiltins]
	mxTools
	

Entries enclosed in brackets are packages (i.e. they are directories that include a __init__.py file) or submodules. Ones without brackets are just simple subdirectories that are not accessible via import. These are used for compiling the C extension modules which will get installed in the same place where all your other site specific extensions live (e.g. /usr/local/lib/python-x.xx/site-packages).

Note: Importing NewBuiltins will automatically install the functions and objects defined in this module as builtins. They are then available in all other modules without having to import then again every time. If you don't want this feature, then import mxTools directly.

Installation

Copyright & Disclaimer

History & Future