Documentation -- Everything you never wanted to know about Gnumeric and Python

Everything you never wanted to know about Gnumeric and Python

1.Python and Gnumeric Basics

If you're using a 1.0.x release of Gnumeric, this page is for you. Python support in Gnumeric has changed substantially in the 1.1 cycle, and Charles Twardy has written a HOWTO about these bindings, which can be found here. If you're using a new build of Gnumeric, you'll want to go there.

Getting started

To kick things off, make sure that your build of Gnumeric has support for Python by starting up Gnumeric and looking under Tools->Plugins. In the active plugins list, you should see a listing that says "Python Plugin" along with "Python plugin loader". If you see both of those listings, you should be ok to write your own custom Python functions.

Where to put your custom script

The second thing that seekers of Gnumeric Python wisdom need to understand is the secret location of user-written Python functions. All userland Python functions belong in a file called rc.py. This file(AKA, the Python's secret lair) must be placed in a .gnumeric directory inside of your home directory. You have to create this directory yourself.

Code listing 1

    # Create the secret directory
    mkdir ~/.gnumeric
    # Give life to the secret lair
    touch ~/.gnumeric/rc.py

Writing a simple script

Once you've gotten these preliminaries out of the way, it's time to get it on. The first order of business should be getting comfortable with registering your custom written Gnumeric functions. Try to get the code example below working with your copy of Gnumeric, and you should get a feel for things. Just ignore the context argument for now and accept it as a semantic necessity.

Code listing 2

    # Add two numbers together
    def func_add(context, a, b):
        return a + b

    # Translate the func_add python function to a gnumeric function and register it
    gnumeric.register_function("py_add", "Python", "ff", "a,b", "", func_add);

The gnumeric register function

The six argument register function looks complicated at first glance, but it's actually pretty simple. The arguments break down as follows.

Code listing 3

    gnumeric.register_function(<function_name>,
                               <category_name>,
                               <parameter_declaration>,
                               <paramter_names>,
                               <help_string>,
                               <python_function>);

Further explanation

The first argument is the name of the function as it will show up inside of Gnumeric. This means that once your function is registered, you can type =PY_ADD(1,2) into a cell in Gnumeric, and the value 3 will appear. For now, keep things simple and always set the category to Python. The parameter declaration field can be one of three values: i,f, and s, which stand for integer, float, and string respectively. Make sure that you put a parameter declaration for each argument passed to the Gnumeric function The parameter names map to the variable names passed to the actual Python function. The help string can simply be omited for now, as I can't find where it shows up inside of Gnumeric anyway, and the final argument is the name of the Python function that the Gnumeric function relates to.

2.Getting Into The Guts

Calling native gnumeric functions

At this point, you're probably thinking that this is all well and good but wondering, "How the hell do I access the Gnumeric API?" Well, the answer is simple but incredibly hard to figure out with doing a serious amount of digging around. That's why I'm here! To save you the pain in the ass. If you want to make Python call a builtin Gnumeric function such as SQRT, CEIL, FLOOR, etc, you use the apply function.

Code listing 4

    # Map func_sqrt to the Gnumeric SQRT function
    def func_sqrt(context, x):    
        return gnumeric.apply(context, "sqrt", (x,))

Further explanation

The apply function takes three arguments: the context, the native Gnumeric function, and the argument list. The argument list has to be passed in as a tuple of arguments that will be fed into the Gnumeric function. By using the apply function, you gain access to Gnumeric's huge library of available functions.

Final notes

There you are! You have access to all of Python's native functions, object-oriented capabilities, and third-party classes. The allows for easy automation and data-manipulation and opens the door to possibilites such as data-acquisition and graphing in real time. Hopefully, the availablity of an open spreadsheet program such as Gnumeric that's not tied to a single proprietary programming language will encourage people to migrate away from closed data formats such as Excel, and we can all have a wider range of interoperability.

Credits

This HTML document was produced from an XML/XSL source using a modified version of Gentoo's guide-main.xsl stylesheet. You can obtain the XML source for this document here.

Updated 17 June 2003

Travis Whitton

Summary: After messing around with Gnumeric for several hours, I became curious as to how to make use of the Python plugin feature. I quickly became acutely aware of the fact that documentation on how to write your own Python functions using the Gnumeric API is about as easy to find as a white elephant. This tutorial is the result of a couple hours of groking through directory after directory in an attempt to figure this mess out; Hopefully, it will save you some of the heartache that I had to suffer through.