File: mxTools.html

package info (click to toggle)
python-mxtools 0.8-1
links: PTS
area: main
in suites: slink
size: 204 kB
ctags: 209
sloc: ansic: 1,961; python: 140; makefile: 41; sh: 19
file content (692 lines) | stat: -rw-r--r-- 19,375 bytes
<HTML>
  <HEAD>
    <TITLE>mxTools - A collection of new builtins for Python</TITLE>
    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
    <META HTTP-EQUIV="Description" CONTENT="
BEGIN PYTHON-PACKAGE-INFO 1.0
Current-Version:	0.8
Title:          	mxTools - A collection of new builtins for Python
Home-page:      	http://starship.skyport.net/crew/lemburg/mxTools.html
Description:    	Collection of tools written in C
Keywords:       	Tools Toolbox functional programming
Author:         	Marc-Andre Lemburg, mailto:lemburg@uni-duesseldorf.de
Maintained-by:  	The author
Primary-site:   	http://startship.skyport.net/crew/lemburg/mxTools-0.8.zip
Alternate-site: 	None
Original-site:  	Same as primary site
Platform:       	Unix/Windows/Mac
Copying-policy: 	Free software, see homepage for details
Difficulty-rating:      Medium, compilation is necessary
System-requirements:    Compiler
Software-requirements:  Python 1.5

The package contains a collection of useful functions that aid in
common tasks like iterating over objects or applying functions to sets
of parameters. The functions contained in the package auto-install
themselves as builtins when the package is imported.

You should visit the home page every now and then for updates, since
the package will eventually evolve with time.

END PYTHON-PACKAGE-INFO
">
  </HEAD>

  <BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">

    <HR SIZE=2 NOSHADE WIDTH="100%">
    <H2>mxTools - A collection of new builtins for Python</H2>

    <HR SIZE=1 NOSHADE WIDTH="100%">
    <TABLE WIDTH="100%">
      <TR>
	<TD>
	  <SMALL>
	    <A HREF="#Functions">Functions</A> :
	    <A HREF="#Objects">Objects</A> :
	    <A HREF="#Examples">Examples</A> :
	    <A HREF="#Structure">Structure</A> :
	    <A HREF="#Installation">Installation</A> :
	    <A HREF="#Copyright">Copyright</A> :
	    <A HREF="#History">History</A>
	</SMALL>
	</TD>
	<TD ALIGN=RIGHT>
	  <SMALL>
	    <FONT COLOR="#FF0000">Version 0.8.1</FONT>
	  </SMALL>
	</TD>
    </TABLE>
    <HR SIZE=1 NOSHADE WIDTH="100%">

    <H3>Introduction</H3>

    <UL>

	<P>As time passes there have often been situations where I
	thought "Hey, why not have this as builtin". In most cases the
	functionality was easily coded in Python. But I started to use
	them quite heavily and since performance is always an issue
	(at least for me: hits/second pay my bills), I decided to code
	them in C. Well, that's how it started and here we are now
	with an ever growing number of goodies...

	<P>

    </UL>

    <A NAME="Functions">
    
    <H3>Functions</H3>

    <UL>

	<P><DL>

	  <DT><CODE><FONT COLOR="#000066">

		indices(object)

	      </FONT></CODE></DT>

	  <DD>
	    Returns the same as <CODE>tuple(range(len(object)))</CODE>
	    -- a tad faster and a lot easier to type.<P></DD>

	  <DT><CODE><FONT COLOR="#000066">

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

	      </FONT></CODE></DT>

	  <DD>
	    This works like the builtin function <CODE>range()</CODE>
	    but returns a tuple instead of a list. Since
	    <CODE>range()</CODE> 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 <CODE>range()</CODE> in for-loops to
	    <CODE>trange()</CODE> pays off in the long run.<P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		range_len(object)

	      </FONT></CODE></DT>

	  <DD>
	    Returns the same as
	    <CODE>range(len(object))</CODE>.<P></DD>

	  <DT><CODE><FONT COLOR="#000066">

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

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		lists(seq)

	      </FONT></CODE></DT>

	  <DD>
	    Inverse of <CODE>tuples()</CODE>, except that
	    <CODE>None</CODE> 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
	    <CODE>tuples()</CODE>, the first item in the sequence
	    decides how many lists will be created. All other items
	    must have at least as many entries.  <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		reverse(sequence)

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		dict(items)

	      </FONT></CODE></DT>

	  <DD>
	    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.
	    <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		invdict(dictionary)

	      </FONT></CODE></DT>

	  <DD>
	    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).  <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		irange(object[,indices])

	      </FONT></CODE></DT>

	  <DD>
	    Builds a tuple of tuples
	    <CODE>(index,object[index])</CODE>. If a sequence
	    <CODE>indices</CODE> is given, the indices are read from
	    it. If not, then the index sequence defaults to
	    <CODE>trange(len(object))</CODE>. Note that
	    <CODE>object</CODE> can be any object that can handle
	    <CODE>object[index]</CODE>, 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. <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		ifilter(condition,object[,indices])

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		get(object,index[,default])

	      </FONT></CODE></DT>

	  <DD>
	    Returns <CODE>object[index]</CODE>, or, if that fails,
	    <CODE>default</CODE>. <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		mget(object,indices[,defaults])

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		findattr(object_list,attrname)

	      </FONT></CODE></DT>

	  <DD>
	    Returns the first attribute with name
	    <CODE>attrname</CODE> found among the objects in the
	    list. Raises an <CODE>AttributeError</CODE> if the
	    attribute is not found.  <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

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

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

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

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

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

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		count(condition,sequence)

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		exists(condition,sequence)

	      </FONT></CODE></DT>

	  <DD>
	    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.  <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		forall(condition,sequence)

	      </FONT></CODE></DT>

	  <DD>
	    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.  <P></DD>

	  <DT><CODE><FONT COLOR="#000066">

		index(condition,sequence)

	      </FONT></CODE></DT>

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

	  <DT><CODE><FONT COLOR="#000066">

		sizeof(object)

	      </FONT></CODE></DT>

	  <DD>
	    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.  <P></DD>

	</DL>

	<P>A note on the naming scheme used:
	<UL>

	  <LI><CODE>i</CODE> stands for indexed, meaning that you have
	  access to indices

	  <LI><CODE>m</CODE> stands for multi, meaning that processing involves multiple
	    objects

	  <LI><CODE>n</CODE> stands for n-times, e.g. a function is executed a
	  certain number of times

	  <LI><CODE>t</CODE> stands for tuple

	  <LI><CODE>x</CODE> stands for lazy evaluation

	</UL>

	<P>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 <TT>:-)</TT>.

	<P>

    </UL>

    <A NAME="Objects">
    
    <H3>Objects</H3>

    <UL>

	<P>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 <CODE>map()</CODE>-constructs
	  called <CODE>xmap()</CODE>:

	<P><DL>

	  <DT><CODE><FONT COLOR="#000066">
		
		xmap(func, seq, [seq, seq, ...])

	      </FONT></CODE></DT>

	  <DD>Constructs a new xmap object emulating <CODE>map(func,
	  seq, [seq, seq, ...])</CODE>. 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). <P></DD>

	</DL>

	<P>These objects define one method:

	<P><DL>

	  <DT><CODE><FONT COLOR="#000066">

		tolist()

	      </FONT></CODE></DT>

	  <DD>Return the whole list giving the same result as the
	  emulated map()-construct. <P></DD>

	</DL>

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

	<P>

    </UL>

    <A NAME="Examples">
    
    <H3>Examples of Use</H3>

    <UL>

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

    </UL>

    <A NAME="Structure">
    
    <H3>Package Structure</H3>

    <UL>

	<PRE>
[NewBuiltins]
	mxTools
	</PRE>

	<P>Entries enclosed in brackets are packages (i.e. they are
	directories that include a <TT>__init__.py</TT> file) or
	submodules. Ones without brackets are just simple
	subdirectories that are not accessible via
	<CODE>import</CODE>. 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. <TT>/usr/local/lib/python-x.xx/site-packages</TT>).

	<P><U>Note</U>: Importing <CODE>NewBuiltins</CODE> 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.

	<P>

    </UL>

    <A NAME="Installation">
    
    <H3>Installation</H3>

    <UL>

	<P>First, download the <A HREF="mxTools-0.8.zip">archive</A>,
	unzip it to a directory on your path and then follow these
	steps (assuming you have already installed Python):

	<P>David Ascher has kindly provided pre-compiled Windows
	versions of the extensions (for mxTools version 0.6 and xmap
	version 0.2), so if you're running WinXX, you can skip the
	following and start using the package right away.

	<P><OL>

	  <LI>
	    run <TT>make -f Makefile.pre.in boot</TT> in the mxTools
	    directory</LI>

	  <LI>
	    run <TT>make</TT></LI>

	  <LI>
	    get Python 1.5 or above running, and execute <TT>test.py</TT>; it
	    should not report any errors.</LI>
<!--
	  <LI>
	    if you like it, run <TT>make install</TT>.
-->
	  <LI>
	    give me feedback <TT>:-)</TT></LI>
	</OL>

	<P>Though the module has been tested, there may still be some
	bugs left. Please post any bug reports, questions
	etc. directly to <A
	HREF="mailto:mal@lemburg.com?subject=mxTools-0.8">me</A>.

    </UL>

    <H3>What I'd like to hear from you...</H3>

    <UL>

	<P><UL>

	  <LI>
	    Can you get the module to compile/work on other Unix
	    platforms other than Linux ? </LI>
<!--
	  <LI>
	    Could someone contribute a compiled .pyd-file for Windows
	    95/NT ?
-->
	</UL>

    </UL>

    <A NAME="Copyright">
    
    <H3>Copyright &amp; Disclaimer</H3>

    <UL>

	<P>(c) 1997, 1998, Copyright by Marc-Andr&eacute; Lemburg; All
	Rights Reserved.  mailto: <A
	HREF="mailto:mal@lemburg.com?subject=mxTools-0.8">mal@lemburg.com</A>

	<P>Permission to use, copy, modify, and distribute this
	software and its documentation for any purpose and without fee
	or royalty is hereby granted, provided that the above
	copyright notice appear in all copies and that both the
	copyright notice and this permission notice appear in
	supporting documentation or portions thereof, including
	modifications, that you make.

	<P>THE AUTHOR MARC-ANDRE LEMBURG DISCLAIMS ALL WARRANTIES WITH
	REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
	MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE
	LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
	ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
	PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
	TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
	OR PERFORMANCE OF THIS SOFTWARE !

    </UL>

    <A NAME="History">
    
    <H3>History & Future</H3>

    <UL>

	<P>Changes from <A HREF="mxTools-0.7.zip">0.7</A> to 0.8:

	<UL>

	  <LI>Version 0.8.1: Fixed a bug that caused sizeof(),
	  reverse() and invdict() to dump core when called without
	  argument.

	  <LI>Fixed a bug in forall() that caused it to fail. Found by
	  Henk Jansen.

	  <LI>Added index(). Contributed by Henk Jansen (TU Delft).

	  <LI>Added tests for forall(), exists(), count() and index()
	  to the test script.

	</UL>

	<P>Changes from <A HREF="mxTools-0.6.zip">0.6</A> to 0.7:

	<UL>

	  <LI><B>Renamed mgetattr()</B> to findattr().
	  The old function name still works, but it will either be
	  removed in the near future or replaced with another
	  functionality.

	  <LI>Changed the way list creation works. This should speed
	  up all functions from the package which create and return
	  lists.

	  <LI>Fixed a serious memory leakage in dict().

	  <LI>Fixed a bug in get().
	    
	  <LI>Added lists().

	  <LI>Made many functions taking only one argument use a simpler
	    calling mechanism. Note that passing more than one argument
	    to these functions results in the "multiple" arguments being
	    seen as a tuple, e.g. sizeof(1,2) is the same as calling
	    sizeof((1,2)). Note that there are some other methods in core
	    Python that work in the same way, e.g. list.append(1,2) really
	    does a list.append((1,2)). I find this convenient at times.

	  <LI><B>Renamed trange_len()</B> to indices() (easier to
	    write and intuitive enough to use, e.g. in 'for i in
	    indices(obj):...').  The old function name still works, but
	    it will be removed in the near future.

	</UL>

	<P>Changes from <A HREF="mxTools-0.5.zip">0.5</A> to 0.6:

	<UL>

	  <LI>Added dict().

	  <LI>Added invdict().

	  <LI>Added tuples().

	  <LI>Added reverse().

	</UL>

	<P>Changes from <A HREF="mxTools-0.4.zip">0.4</A> to 0.5:

	<UL>

	  <LI>Added get() and mget().

	  <LI>Added sizeof().

	  <LI>Added mgetattr().

	</UL>

	<P>Changes from <A HREF="mxTools-0.3.zip">0.3</A> to 0.4:

	<UL>

	  <LI>Converted the module into a package called
	  'NewBuiltins'. Importing it installs all of the functions
	  defined in the C extension modules as builtins.

	  <LI>Fixed a few memory leaks.

	  <LI>Added method_mapply().

	  <LI>Added Christopher Tavares' xmap module.

	</UL>

	<P>

    </UL>

    <HR WIDTH="100%">
    <CENTER><FONT SIZE=-1>(c) 1997, 1998, Copyright by
    Marc-Andr&eacute; Lemburg; All Rights Reserved. mailto: <A
    HREF="mailto:mal@lemburg.com?subject=mxTools-0.8">mal@lemburg.com</A>
    </FONT></CENTER>

  </BODY>
</HTML>