關于Gnumeric

Gnumeric是linux平臺下的一款功能強大且易于使用的電子表格軟件，與其他常用電子表格軟件如Excel等在風格上非常一致。Gnumeric當前的穩(wěn)定版是1.2.13，對中文的支持已經(jīng)比較成熟。據(jù)官方信息，Gnumeric除實現(xiàn)了MS Excel所有的函數(shù)外，還實現(xiàn)了60多個Excel中不存在的函數(shù)和基本的金融方面函數(shù)，并已經(jīng)具備了高級統(tǒng)計分析、可擴展的隨機數(shù)產(chǎn)生器、線性或非線性求解的計算能力。更令人驚喜的是，現(xiàn)在Gnumeric已經(jīng)集成了Python強大的腳本編程能力，Python用戶可以為Gnumeric實現(xiàn)更為復雜的計算功能。

何謂Python

Python是一種解釋性的，面向對象的，具有動態(tài)語義的程序設計語言。Python代碼具有優(yōu)秀的可讀性，具有模塊和包的概念，支持各種主流平臺，并具有很好的跨平臺能力。Python已廣泛用于文本處理、互聯(lián)網(wǎng)編程、數(shù)據(jù)庫編程、系統(tǒng)管理等領域 。同時Python又是一種成功的嵌入語言，包裝C/C++的代碼非常方便，越來越多的重量級應用程序開始支持Python腳本編程，OpenOffice, GIMP, Blender等。

插件初探

任何一個C函數(shù)調用或訪問一個Python對象都必須遵循這樣一個框架：

1. C函數(shù)把調用參數(shù)轉換成Python語言數(shù)據(jù)類型

2. 利用轉換后的參數(shù)調用Python函數(shù)

3. 返回值轉換成C語言類型，并返回給C函數(shù)

類似的，從Python函數(shù)調用C函數(shù)也遵循相似的步驟：

1. Python函數(shù)把參數(shù)轉換成C語言類型

2. 用轉換后的參數(shù)調用C函數(shù)

3. 返回值轉換成Python語言類型后返回給Python函數(shù)

因此Python函數(shù)和C函數(shù)相互調用的關鍵是數(shù)據(jù)的相互轉換問題，這些轉換需要相當好的C和Python解釋語言開發(fā)功底，好在Gnumeric的Python插件已經(jīng)自動為我們做了數(shù)據(jù)類型的轉換，我們只需關注算法的實現(xiàn)就可以了。

Gnumeric和Python的交互也遵循類似的過程，首先Gnumeric自動轉換參數(shù)類型，繼而調用Python函數(shù)，最后再把返回值轉換成合適的類型返回給Gnumeric。下面是Gnumeric和Python的常見數(shù)據(jù)類型對應表：

對于單元格（Cell），Gnumeric把單元格中的數(shù)據(jù)直接轉換相應的數(shù)據(jù)類型，傳遞被調用Python函數(shù)，如整數(shù)（Integer）、浮點數(shù)（Float）、字符串（String）；然而對于單元格區(qū)域（Range），Gnumeric采取迂回的策略，只是傳遞一個單元格區(qū)域的引用（RangeRef）給被調用Python函數(shù)，而Python這時就需要通過Gnumeric接口才能訪問和操作單元格區(qū)域中的數(shù)據(jù)。因此，Gnumeric為Python提供了Gnumeric模塊，，包括Gnumeric的全部函數(shù)和工作薄工作表對象，這里簡略地列出了Gnumeric模塊中的函數(shù)和對象（具體細節(jié)請讀者參考Gnumeric的py-gnumeric.c源文件位于plugins/python-loader目錄）。

范例分析

通過上面的介紹，我們初步了解了跨語言調用的框架，在此基礎上再來分析一下Gnumeric軟件包自帶的Python插件范例（通常位于/usr/lib/gnumeric/<VERSION>/plugins/py-func/）。該范例由plugin.xml、py_func.py兩個文件構成，plugin.xml是XML形式的配置文件，供Gnumeric來讀取python函數(shù)的相關信息；py_func.py包含Python函數(shù)的定義和函數(shù)原型字典。

首先分析的是py_func.py文件。該文件定義了三個函數(shù)：func_printf，func_capwords，func_bitand，功能分別是格式化輸出，單詞首字母大寫，按位求和。我們來比較一下這三個函數(shù)：

以func_bitand函數(shù)為例，函數(shù)接受兩個整數(shù)，返回值也為整數(shù)，C與Python的類型轉換是Gnumeric自動完成的，func_bitand只注重算法的實現(xiàn)，具體計算是通過調用Gnumeric的按位求和函數(shù)（bitand）完成的；值得一提的是''@''開頭的文檔字符串是提供給Gnumeric的文檔接口，分別提供函數(shù)的功能、接口、實例以及引用方面的信息，格式也是固定的，每個域（包括換行符）用單引號括起來并后接"\"。
代碼 1 func_bitand函數(shù)定義

from Gnumeric import *
def func_bitand(num1, num2):
    '@FUNCTION=PY_BITAND\n'\
    '@SYNTAX=PY_BITAND (num)\n'\
    '@DESCRIPTION=The BITAND function returns bitwise'\
    'and-ing of its arguments.'\
    '\n'\
    '@EXAMPLES=\n'\
    'PY_BITAND(6, 2) equals 2)'\
    '\n'\
    '@SEEALSO=BITAND'
    
    
    gnm_bitand=functions['bitand'] # Gnumeric的按位求和函數(shù)
    return gnm_bitand(num1, num2)

py_func.py文件尾處還有一個起特殊作用的字典，向Gnumeric提供Python函數(shù)原型信息，姑且稱之為函數(shù)原型字典。函數(shù)原型字典的命名是非常嚴格的，必須以"_functions"為后綴，"_"前面前面的名字必須與plugin.xml文件保持一致，這樣Gnumeric才能發(fā)現(xiàn)插件中的各種函數(shù)信息，否則Gnumeric就會出現(xiàn)許多函數(shù)信息方面的錯誤，導致插件函數(shù)無法使用。函數(shù)原型用字典中"key:value"對來表示（代碼2）， 如func_bitand，key就是在Gnumeric被映射的函數(shù)名py_bitand，value是由參數(shù)類型、參數(shù)名稱、函數(shù)名稱組成的元組。
代碼 2 test_functions函數(shù)原型字典

test_functions = {
    'py_printf': func_printf,
    'py_capwords': ('s', 'sentence', func_capwords),
    
    
    'py_bitand':  ('ff', 'num1, num2', func_bitand)
}

在函數(shù)原型字典中，參數(shù)類型是用特殊的字符來表示的，例如func_bitand的兩個浮點數(shù)參數(shù)表示為"ff"。常見參數(shù)類型的字符串表示總結如下：

另外一個結構簡單的XML文件plugins.xml (1) ，是開發(fā)者向Gnumeric提供的配置信息。information標簽中的name和description標簽提供了該插件的名字和描述信息，而且這些信息的國際化也很簡單，只需要在有語言標記的相應標簽中填寫國際化信息即可。loader標簽中attribute標簽的value屬性、service標簽中id屬性、function標簽中的name屬性是最重要的，分別對應于Python腳本文件名、腳本中的函數(shù)原型字典名（不包括后綴）、函數(shù)原型函數(shù)的key。對于本例，屬性值為py_func，test，py_printf，py_capwords，py_bitand，則對應于插件分別為py_func.py和test_functions，py_printf，py_capwords，py_bitand。這些對應關系一定要一致，否則Gnumeric就會向你抱怨了。
代碼 3 py-func.py的plugin.xml配置文件

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="Gnumeric_PyFunc">
    <information>
        <name>Python functions</name>
        <description>Sample Python plugin providing
               some (useless) functions.
        </description>
        <require_explicit_enabling/>
    </information>
    <loader type="Gnumeric_PythonLoader:python">
        <attribute value="py_func" name="module_name"/>
    </loader>
    <services>
        <service type="function_group" id="test">
            <category>Python</category>
            <category xml:lang="zh_CN">
                Python
            </category>
            <functions>
                <function name="py_printf"/>
                <function name="py_capwords"/>
                <function name="py_bitand"/>
            </functions>
        </service>
    </services>
</plugin>

牛刀小試

根據(jù)上面的分析，我們看到用Python編寫Gnumeric函數(shù)，需要三個步驟：

1. 創(chuàng)建Python函數(shù)源文件，如py_func.py。

2. 根據(jù)創(chuàng)建的函數(shù)構建函數(shù)原型字典，如test_functions。

3. 創(chuàng)建plugin.xml配置文件，配置文件名、函數(shù)分類、名字、原型字典等相關信息。

為了演示具體的Gnumeric中Python函數(shù)創(chuàng)建的過程，筆者編寫了一個根據(jù)自動標記成績等級的小函數(shù)，由plugin.xml和exam.py兩個文件構成。

首先創(chuàng)建腳本文件exam.py，整個文件只有mark和cstr兩個函數(shù)：mark函數(shù)的參數(shù)和返回值都是字符串，功能是根據(jù)其大小返回成績的等級；cstr用來把字符串轉換成utf-8編碼，使Gnumeric能顯示中文 (2) 。mark函數(shù)中的注釋是提供給Gnumeric的函數(shù)信息，讀者開發(fā)時只需要按著模板簡單的修改就可以了。
代碼 4 exam.py文件

# -*- coding: GB2312 -*-
def mark(score):
  '@FUNCTION=MARK_SCORE\n'\
  '@SYNTAX=mark_score(score)\n'\
  '@DESCRIPTION= determine the level for a score\n'\
  '@EXAMPLES= To determine a score in A1: \n'\
  '  mark_score(a1)\n'\
  '@SEEALSO='
  level='N/A'
  if score < 0:
    level = cstr('非法分數(shù)')
  elif score < 60:
    level = cstr('未及格')
  elif score < 80:
    level = cstr('及格')
  elif score < 90:
    level = cstr('良')
  elif score <= 100:
    level = cstr('優(yōu)秀')
  else:
    level = cstr('非法分數(shù)')
  return level
def cstr(str):
  """ translate a chinese string into utf-8 string for GTK+ 
  """
  return unicode(str,'gbk').encode('utf8')
exam_functions = {
  'mark_score' : ('f','score',mark)
}

下一步就是就是注冊函數(shù)，exam.py文件尾處的exam_functions函數(shù)原型字典向Gnumeric揭示了mark函數(shù)的原型信息，字典的鍵'mark_score'是mark在Gnumeric的名字映射，f表示參數(shù)類型為整數(shù)，score為參數(shù)名。plugin.xml (3) 是根據(jù)模板簡單的改寫的，主要注意的就是上面提到的幾個屬性，必須和插件對應，否則插件是無效的；另外一些屬性，如category也加入了中文信息，以方便使用。
代碼 5 exam.py的plugin.xml配置文件

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="Gnumeric_PyFunc">
 <information>
  <name>Exam functions</name>
  <description> Determine rank for exam score </description>
  <require_explicit_enabling/>
 </information>
 <loader type="Gnumeric_PythonLoader:python">
  <attribute value="exam" name="module_name"/>
 </loader>
 <services>
  <service type="function_group" id=
    
    "exam">
   <category>
    
    Exam</category>
   <category xml:lang="zh_CN">Exam</category>
   <functions>
    <function name=
    
    "mark_score"/>
   </functions>
  </service>
 </services>
</plugin>

OK!現(xiàn)在啟動Gnumeric (4) ，按圖示在A列輸入一列成績，然后在B1單元格內輸入公式：'=mark_score(A1)', 然后利用鼠標拖動復制公式的功能，把公式復制到對應的B列，就會發(fā)現(xiàn)所有標志在B列中已經(jīng)自動生成了。
插圖1 成績分類

更進一步

如果只是對單元格數(shù)據(jù)簡單計算的話，那么Python在Gnumeric中充其量是好玩的玩具罷了，但Python插件的功能遠不只這些，Python可以控制讀寫單元格區(qū)域（Range）的數(shù)據(jù)，訪問Gnumeric的全部函數(shù)，控制工作表的創(chuàng)建等，把這些功能有機地組合起來就能完成復雜的任務了。本節(jié)對全班成績做進一步的處理，利用RPy (5) 的summary函數(shù)對所有的分數(shù)進行簡單的統(tǒng)計，計算最值、均值、中位數(shù)和兩個四分位數(shù)，并把所得計算結果打印到新的工作表中。

要想統(tǒng)計全班成績，首要的任務就是從Gnumeric獲取數(shù)據(jù)。對于大批量的數(shù)據(jù)，Gnumeric是用單元格區(qū)域（Range）來表示的，然而在調用過程中傳遞給Python的是單元格區(qū)域引用（RangeRef），所以需要對單元格區(qū)域引用（RangeRef）做相應的轉換以便提取批量數(shù)據(jù)。不幸的是，Gnumeric的API正處于發(fā)展階段，沒有直接的轉換方法。為此，筆者利用了Gnumeric自身的函數(shù)構建了一個PyGnmRange類。PyGnmRange對象以單元格區(qū)域引用（RangeRef）為初始化參數(shù)，為該單元格區(qū)域中的構建所有單元格的索引，即"_table"屬性，同時提供幾個方法來方便地訪問，這樣我們就可以配合Gnumeric模塊中的Sheet對象操縱單元格數(shù)據(jù)了。
代碼 6 類PyGnmRange的定義

    class PyGnmRange:
  def __init__(self, gnm_range_ref):
    get_cols = Gnumeric.functions['column']
    get_rows = Gnumeric.functions['row']
    get_col_num = Gnumeric.functions['columns']
    get_row_num = Gnumeric.functions['rows']
    cols = get_cols(gnm_range_ref)
    rows = get_rows(gnm_range_ref)
    # column first table
    self._table = []
    self._col_num = get_col_num(gnm_range_ref)
    self._row_num = get_row_num(gnm_range_ref)
    for i in range(self._col_num):
      for j in range(self._row_num):
        self._table.append((cols[i][j]-1, rows[i][j]-1))
  def col_num(self):
    return self._col_num
  def row_num(self):
    return self._row_num
  def get_col(self,col):
    start = (col-1) * self._row_num
    end = col * self._row_num
    return self._table[start:end]
  def get_row(self,row):
    indexes = [(i*self._row_num)+(row-1) for i in range(self._col_num)]
    return [self._table[i] for i in indexes]
  def __iter__(self):
    return iter(self._table)

另外PyGnmRange類定義需要注意兩點：

1. 單元格下標采取了列優(yōu)先的表示方法，從零開始計數(shù)，例如B3表示為（1，2），這樣同時也是為了與Gnumeric規(guī)范保持一致，便于操縱單元格數(shù)據(jù)。

2. 類初始化函數(shù)使用了四個Gnumeric的函數(shù)，分別為column、columns、row、rows，其功能如下：

有了前面的準備，我們就可以具體實現(xiàn)summary函數(shù)了。summary函數(shù)通過gnm_scores參數(shù)獲得當前的單元格區(qū)域引用，并利用該參數(shù)創(chuàng)建PyGnmRange對象，計算所有單元格的下標；又通過Gnumeric模塊的workbooks和sheets函數(shù)，取得工作表1的對象；從而結合工作表對象和單元格下標來操作單元格數(shù)據(jù)。而真正的計算R語言完成的，RPy模塊則是聯(lián)接Python和R語言的橋梁 (6) 。最后，summary函數(shù)取得R語言計算的結果并通過Gnumeric模塊將其打印到一個新建的工作表里。
代碼 7 exam.py 中summary函數(shù)定義

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="Gnumeric_PyFunc">
 <information>
  <name>Exam functions</name>
  <description>Sample Python plugin providing some (useless) functions.</description>
  <require_explicit_enabling/>
 </information>
 <loader type="Gnumeric_PythonLoader:python">
  <attribute value="exam" name="module_name"/>
 </loader>
 <services>
  <service type="function_group" id="exam">
   <category>Exam</category>
   <category xml:lang="zh_CN">Exam</category>
   <functions>
 <function name="mark_score"/>
 <function name="summerize_scores"/>
   </functions>
  </service>
 </services>
</plugin>

函數(shù)編寫完之后就是函數(shù)注冊了，函數(shù)原型字典只有一行，唯一需要注意的是，單元格區(qū)域引用數(shù)據(jù)類型需要用"r"來表示。plugin.xml文件也只需要加入下面一行：
代碼 8 summay函數(shù)的plugin.xml配置文件

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="Gnumeric_PyFunc">
 <information>
  <name>Exam functions</name>
  <description>Sample Python plugin providing some (useless) functions.</description>
  <require_explicit_enabling/>
 </information>
 <loader type="Gnumeric_PythonLoader:python">
  <attribute value="exam" name="module_name"/>
 </loader>
 <services>
  <service type="function_group" id="exam">
   <category>Exam</category>
   <category xml:lang="zh_CN">Exam</category>
   <functions>
 <function name="mark_score"/>
 <function name="summerize_scores"/>
   </functions>
  </service>
 </services>
</plugin>

下面的兩張是插件函數(shù)的運行效果圖，輸入數(shù)據(jù)是隨機生成的80個100以內的浮點數(shù)，函數(shù)插在B1單元格內，由于該函數(shù)的目的是生成簡單的報表而不是返回值，所以運行結束后B1單元格內依然空白，而所有的數(shù)據(jù)全部打印在新建的工作表4內（圖2和圖3）。
插圖2 全班成績和函數(shù)的輸入

插圖3 全班成績統(tǒng)計報告

插件部署

Gnumeric插件部署及其簡單，用戶只需要在自己主目錄下新建.gnumeric目錄，放入插件函數(shù)即可，例如exam.py和plugin.xml就是位于 <HOME>/.gnumeric/<version> (7) /plugins/exam/，重新啟動Gnumeric插件就生效了 (8) 。

結束語

Gnumeric的Python開發(fā)過程需要注意一下幾個問題：

1. Gumeric的Python插件還處于積極地開發(fā)過程中，一些代碼很可能在將來的版本中會發(fā)生很大的變化；插件提供的Gnumeric模塊接口還不是完整，比如缺乏獲得活動工作表的函數(shù)，編寫Python函數(shù)時需要仔細地處理。

2. Python函數(shù)配置雖然及其簡單，但是調試起來不是很方便，經(jīng)常會出現(xiàn)Gnumeric不能正確獲取Python信息的情況，這時候的原因是多方面的，例如plugin.xml文件的名字與腳本文件不一致，函數(shù)原型字典命名不規(guī)范，函數(shù)文檔字符串格式錯誤，腳本文件語法錯誤等。

盡管這樣，對于熟悉Python的編程人員來說，這些并不影響編寫Gnumeric函數(shù)的趣味，只需小心仔細地處理，這些都不是很難的事。希望本文能起到拋磚引玉的作用，有興趣的讀者可以在此基礎上參考Gnumeric源代碼中的開發(fā)者文檔和Python插件的源代碼，會發(fā)現(xiàn)許多有價值的信息，編寫更有價值的應用了。