doc/developer/python-gnumeric.txt

   1 IMPORTANT
   2
   3 This document describes an obsolete Python plugin which is no longer
   4 part of Gnumeric. The current Python plugin support is based on the
   5 plugin loader in plugins/python-loader. This will be documented
   6 later. For now, plugins/py-func and plugins/gnome-glossary serve as
   7 examples.
   8
   9 Jon Kåre Hellan <hellan@acm.org>                       Oct 11, 2002
  10 -------------------------------------------------------------------
  11
  12
  13
  14
  15
  16
  17
  18
  19 Python plugin for Gnumeric
  20 --------------------------
  21
  22 Jon Kåre Hellan <hellan@acm.org>                       Feb 26, 2000
  23
  24 NOTE 1: A more complete documentation of the Python plugin will follow
  25 in due course (whatever that means).
  26
  27 NOTE 2: The plugin is still experimental. Things can change if
  28 somebody convinces us of a better way of doing it. If you need an
  29 assurance of stability, please ask, and we'll reconsider the
  30 "experimental" status.
  31
  32 Introduction:
  33 -------------
  34
  35 The Python plugin lets you add spreadsheet functions to Gnumeric using
  36 Python.
  37
  38 The steps involved are:
  39
  40 1. Write a function in Python
  41
  42 2. Make the Python function known to Gnumeric by calling
  43    gnumeric.register_function. More about this later.
  44
  45 Enabling installation
  46 ---------------------
  47
  48 On Solaris, there are problems with linking the plugin dynamically to
  49 Gnumeric. Because it doesn't work everywhere, it is not installed by
  50 default. On Linux, it works. To enable installation, comment out the
  51 line starting with noinst_LTLIBRARIES in plugins/python/Makefile.am in
  52 the Gnumeric source tree, and uncomment the line starting with
  53 #plugin_LTLIBRARIES. Next, run automake from the root of the source
  54 tree.
  55
  56 Plugin startup
  57 --------------
  58
  59 When the plugin is initialized, the file gnumeric_startup.py is run.
  60 This file is in the directory "gnumeric/python" in the Gnome
  61 directory.  It imports necessary definitions from gnumeric_defs.py,
  62 and defines a couple of spreadsheet functions. These functions are not
  63 particularly useful, but are intended to illustrate how to write
  64 spreadsheet functions in Python.
  65
  66 Finally, the file ~/.gnumeric/rc.py is run. This is where users can
  67 define their own functions.
  68
  69 Registering a spreadsheet function
  70 ----------------------------------
  71
  72 A spreadsheet function is registered using the Python function
  73 gnumeric.register_function:
  74
  75 gnumeric.register_function (<function_name>,
  76                             <category_name>,
  77                             <parameter_declaration>,
  78                             <parameter_names>,
  79                             <help_string>,
  80                             <python_function>)
  81
  82 The meaning of the parameters is:
  83 function_name          The name of the spreadsheet function.
  84 category_name          The function category.
  85 parameter_declaration  See below
  86 parameter_names        A string which lists the names of the parameters.
  87 help_string            Help string. The format is documented in ...
  88 python_function        The Python function which implements the
  89                        spreadsheet function.
  90
  91 The python function must take a context as the first parameter. This
  92 is used when calling back into built-in functions. The other
  93 parameters correspond to the parameters you register for the
  94 spreadsheet function.
  95
  96 Example:
  97
  98 Here's a Python function to return the middle of a string:
  99
 100 def gnumeric_mid(context, text, start_num, num_chars):
 101     return text[start_num-1:start_num+num_chars-1];
 102
 103 Here's a help string for the function:
 104
 105 help_mid = \
 106     "@FUNCTION=PY_MID\n"                       \
 107     "@SYNTAX=PY_MID(text,start,num_chars)\n"               \
 108     "@DESCRIPTION="                         \
 109     "Returns a specific number of characters from a text string, "  \
 110     "starting at START and spawning NUM_CHARS.  Index is counted "  \
 111     "starting from one"
 112
 113 Here's how the function can be registered. We use the spreadsheet
 114 function name "py_mid", because there is a built-in "mid" function:
 115
 116 gnumeric.register_function("py_mid", "Plugin demo", "sff", "text,
 117                            start_num, num_chars", help_mid, gnumeric_mid);
 118
 119 Heres's how you can use it in a spreadsheet:
 120
 121 py_mid("Hello", 1, 2)
 122
 123 Parameter tokens used in Gnumeric
 124 ---------------------------------
 125
 126 parameter_declaration is a string where each character is a token
 127 defining the type of a parameter. A complete reference can be found in
 128 writing-functions.sgml.
 129
 130 Here are the parameter tokens used in Gnumeric:
 131
 132 f : A floating point value.
 133 s : A string.
 134 b : A boolean.
 135 r : A GnmRange, e. g. A1:A5 - See 'A'
 136 a : An Array e. g. {1,2,3;4,5,6} ( a 3x2 array ) - See 'A'
 137 A : Either an Array or a GnmRange.
 138 ? : Any type.
 139 | : This designates that the arguments in the token string
 140     following this character are optional.
 141
 142 For functions which accept an arbitrary number of parameters, give an
 143 empty parameter_declaration.
 144
 145 Python mapping of Gnumeric values.
 146 ----------------------------------
 147
 148 Function parameters and function results are passed across the C
 149 interface to Gnumeric using the data structure GnmValue, which is a
 150 discriminated union. This table shows the mappings between the various
 151 types of Gnumeric values and Python data types.
 152
 153 VALUE_FLOAT      <=>    Python float
 154 VALUE_STRING     <=>    Python string
 155 VALUE_CELLRANGE  <=>    Python CellRange class
 156 VALUE_EMPTY      <=>    Python None
 157 VALUE_BOOLEAN     =>    Python Boolean class
 158 VALUE_ERROR      <=>    Python Exception class (not yet done)
 159 VALUE_ARRAY      <=>    Python list of lists. array[y][x] denotes row
 160                         y, column x of the array.
 161
 162 The classes CellRange, CellRef and Boolean live in the module
 163 gnumeric_defs, which is imported on startup.
 164
 165 CellRange objects are a tuple of two CellRef objects. The CellRef
 166 class has the following attributes:
 167       column
 168       row
 169       col_relative
 170       row_relative
 171       sheet
 172 The first four are integers (the Python plugin C code enforces
 173 this). Sheet is not yet implemented.
 174
 175 Here is why we use a class for booleans: Many built-in spreadsheet
 176 functions treat the boolean values TRUE and FALSE differently from the
 177 integers 0 and 1. So they have to be able to tell whether a Python
 178 function returned a boolean or an integer. The objects
 179 gnumeric_defs.TRUE and gnumeric_defs.FALSE are instantiated on
 180 startup.
 181
 182 Invoking Gnumeric functions from Python
 183 --------------------------------------
 184
 185 Python functions may invoke spreadsheet functions by means of the Python
 186 function gnumeric.apply:
 187
 188 gnumeric.apply(<context>,<function_name>,
 189                <arguments>)
 190
 191 context:       Context to pass to built-in functions.
 192 function_name: The name of the spreadsheet function (string).
 193 arguments:     A sequence of the arguments. Any sequence type will do,
 194                but a tuple is the natural choice.
 195
 196 Example: Calling "abs" from Python
 197
 198 abs_val = gnumeric.apply("abs", (f,))
 199
 200 NOTE: (f,) is the way a tuple of length one is written.
 201
 202 Errors and Exceptions
 203 ---------------------
 204
 205 When a Python exception has propagated to a Python function called
 206 directly from C without being caught, it is handled as follows: A
 207 VALUE_ERROR is returned, where the message part is the string
 208 representation of the type and value of the exception. Currently, the
 209 full traceback is also written to standard error. A better solution
 210 for this will have to be found.
 211
 212 A Python function may also receive a VALUE_ERROR, either as an
 213 argument or as a return value. This value will be converted to an
 214 exception of the class GnumericError, with the
 215 exception value set to the message part. If the Python function should
 216 return this value to C code, it can convert the exception back to the
 217 original VALUE_ERROR.
 218
 219 Python environment
 220 ------------------
 221
 222 The directory "gnumeric/python" in the Gnome directory is appended to
 223 sys.path.