<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta http-equiv="charset" content="iso-8859-1">
<title>aspell-python 1.0</title>
</head>
<body style="margin:2em; font-family: Georgia, Times, serif">
<h1 align=center>aspell-python 1.0</h1>
<ol>
<li><a href="what">WHAT IS IT?</a></li>
<li><a href="copyrights">COPYRIGHTS</a></li>
<li><a href="download">DOWNLOAD</a></li>
<li><a href="installation">INSTALLATION</a></li>
<li><a href="usage">USAGE</a></li>
<li><a href="encoding">ENCODING</a></li>
<li><a href="#author">AUTHOR</a></li>
</ol>
<a name="what"></a><h2>1. WHAT IS IT?</h2>
<p>
<b>aspell-python</b> is a <a href="http://www.python.org">Python</a> wrapper for <a href="http://aspell.net">GNU Aspell</a>.
</p>
<p>
Module has been tested with Python 2.1, Python 2.3.4 and Python 2.4.1. Probably it works fine with all Python versions not older then 2.0.
</p>
<p>
Aspell 0.50.5 is almost fully supported (see note for <a href="#getMainwordlist">getMainwordlist</a>). The latest aspell 0.60.2 isn't fully supported, but essential functions should work fine.
</p>
<table border="1" align="center" cellpadding="4"> <tr>
<td>method
<td>aspell 0.50.5
<td>aspell 0.60.2
<tr>
<td><a href="#ConfigKeys">ConfigKeys</a>
<td>ok
<td>ok
<tr>
<td><a href="#Speller">Speller</a>
<td>ok
<td>ok
<tr>
<td><a href="#check">check</a>
<td>ok
<td>ok
<tr>
<td><a href="#suggest">suggest</a>
<td>ok
<td>ok
<tr>
<td><a href="#addReplecement">addReplecement</a>
<td>ok
<td>ok
<tr>
<td><a href="#addtoPersonal">addtoPersonal</a>
<td>ok
<td>ok
<tr>
<td><a href="#saveAllwords">saveAllwords</a>
<td>ok
<td>ok
<tr>
<td><a href="#addtoSession">addtoSession</a>
<td>ok
<td>ok
<tr>
<td><a href="clearSession">clearSession</a>
<td>ok
<td><a href="AspellSpellerError"><font color="red">error</font></a>
<tr>
<td><a href="#getPersonalwordlist">getPersonalwordlist</a>
<td>ok
<td><font color="red">SIGKILL</font>
<tr>
<td><a href="#getSessionwordlist">getSessionwordlist</a>
<td>ok
<td><font color="red">SIGKILL</font>
<tr>
<td><a href="#getMainwordlist">getMainwordlist</a>
<td><font color="red">SIGKILL</font>
<td><font color="red">SIGKILL</font>
</table>
<p>
This version of module comes with a bit different set of methods then previous
one (distributed in <tt>aspell-python2.1.tar.gz</tt>), so programs which use
previous version won't work.
</p>
<p>
If the program uses only <tt>new()</tt> (without parameters or with a single pair key&value), <tt>check()</tt>, and <tt>suggest()</tt>, you will need to replace <tt>new()</tt> with <tt>Speller()</tt>. In other cases more work is required.
Sorry for problems!
</p>
<a name="download"></a><h2>2. DOWNLOAD</h2>
<ul>
<li><a href="aspell-python1.1.tar.gz">aspell-python1.1.tar.gz</a> — <b>latest version</b>, described in this document</li>
<li><a href="aspell-python1.0.tar.gz">aspell-python1.0.tar.gz</a>
<li><a href="aspell-python2.1.tar.gz">aspell-python2.1.tar.gz</a> — obsolete (2.1 is a Python's version, not module); If it is possible don't use it.</li>
</ul>
<a name="copyrights"></a><h2>3. COPYRIGHTS</h2>
<p>
Module is covered by <a href="http://www.gnu.org">GNU</a> <a href="http://www.gnu.org/licenses/licenses.html#GPL">General Public License</a>. <a href="#author">Author</a> tried to make
code usable and free of errors, but can't give any guarantees and is not responsible for any damages in your software, hardware or anything else.
</p>
<a name="installation"><h2>3. INSTALLATION</h2>
<p>
First extract the sources:
</p>
<pre>
$ tar -xzf aspell-python[some-number].tar.gz
$ cd aspell-python
</pre>
<p>
You need to have libaspell headers installed, <a href="http://packages.debian.org">Debian package</a> is called libaspell-dev, other
distributions should have similar package.
</p>
<p>
In order to install aspell-python for all users, you must be a root.
If you are, type following command:
</p>
<pre>
$ python setup.py install
</pre>
<p>
It builds package and installs aspell.so in <tt>/usr/lib/{python}/site-packages</tt>.
</p>
<p>
If you don't have root login, you can build package locally.
Type following command:
</p>
<pre>
$ python setup.py build
</pre>
<p>
It builds package and places aspell.so in <tt>build/lib.{something}</tt>.
Change to this directory and when you will run python it will be able to
import module (you may also copy aspell.so wherever you want, and
there run python).
</p>
<a name="usage"></a><h2>5. USAGE</h2>
<p>
Aspell-python module is seen in python under name <tt>aspell</tt>. So, aspell-python module is imported in following way.
</p>
<pre>
import aspell
</pre>
<p>
The module provides <a href="AspellSpeller">AspellSpeller object</a>, two <a href="methods">methods</a>, and three types of <a href="#Exceptions">exceptions</a> — all described below.
</p>
<a name="methods"></a>
<h3>5.1. Methods</h3>
<ul>
<li><a href="ConfigKeys">ConfigKeys</a></li>
<li><a href="Speller">Speller</a></li>
</ul>
<a name="ConfigKeys"></a>
<h4>ConfigKeys()</h4>
<p>
Method returns a list of available configuration keys.
Items on the list are 4-tuples:
</p>
<ol>
<li>key name</li>
<li>key type:
<ul>
<li>string</li>
<li>integer</li>
<li>boolean - string <tt>true</tt> or <tt>false</tt></li>
<li>list (string, where items are separated by colons)</li>
</ul></li>
<li>default value for the key</li>
<li>short description - <tt>internal</tt> means that aspell
doesn't provide any description of item and you shouldn't
set/change it, unless you know what you do</li>
</ol>
<p>
Aspell's documentation covers in details all of keys and their meaning.
Belows is a list of most useful and obvious options
(it is a filtered output of ConfigKeys).
</p>
<pre>
('data-dir', 'string', '<prefix:share/aspell>', 'location of language data files')
('dict-dir', 'string', '<prefix:lib/aspell>', 'location of the main word list')
('encoding', 'string', 'iso8859-1', 'encoding to expect data to be in')
('home-dir', 'string', '<$HOME|./>', 'location for personal files')
('ignore', 'integer', '1', 'ignore words <= n chars')
('ignore-accents', 'boolean', 'false', 'ignore accents when checking words')
('ignore-case', 'boolean', 'false', 'ignore case when checking words')
('ignore-repl', 'boolean', 'false', 'ignore commands to store replacement pairs')
('keyboard', 'string', 'standard', 'keyboard definition to use for typo analysis')
('lang', 'string', '<language-tag>', 'language code')
('master', 'string', '', 'base name of the main dictionary to use')
('repl', 'string', '.aspell.<actual-lang>.prepl', 'replacements list file name')
('save-repl', 'boolean', 'true', 'save replacement pairs on save all')
('sug-mode', 'string', 'normal', 'suggestion mode')
('reverse', 'boolean', 'false', 'reverse the order of the suggest list')
</pre>
<a name="Speller"></a>
<h4>Speller()</h4>
<p>
Method creates an <a href="#AspellSpeller">AspellSpeller object</a>
which is an interface to the GNU Aspell.
</p>
<p>
Speller called with no parameters creates speller using default
configuration. If you want to change or set some parameter you can
pass pair of strings: key and it's value. One can get available
keys using <a href="#ConfigKeys">ConfigKeys()</a>.
</p>
<pre>
>>> aspell.Speller("key", "value")
</pre>
<p>
If you want to set more than one pair of key&value, pass the list
of pairs to the Speller().
</p>
<pre>
>>> aspell.Speller( ("k1","v1"), ("k2","v2"), ("k3","v3") )
</pre>
<a name="Exceptions"></a>
<h3>5.2. Exceptions</h3>
<p>
Module defines following errors:
<a href="AspellConfigError">AspellConfigError</a>,
<a href="AspellModuleError">AspellModuleError</a> and
<a href="#AspellSpellerError">AspellSpellerError</a>.
Additionally TypeError is raised when you pass wrong parameters to method. </p>
<a name="AspellConfigError"></a>
<h4>AspellConfigError</h4>
<p>
Error is reported by methods <a href="Speller">Speller()</a> and <a href="ConfigKeys">ConfigKeys()</a>. The most common error is passing unknown key.
</p>
<pre>
>>> s = aspell.Speller('python', '2.3')
Traceback (most recent call last):
File "<stdin>", line 1, in ?
aspell.AspellConfigError:The key "python" is unknown.
>>>
</pre>
<a name="AspellModuleError"></a>
<h4>AspellModuleError</h4>
<p>
Error is reported when module can't allocate aspell structures.
</p>
<a name="AspellSpellerError"></a>
<h4>AspellSpellerError</h4>
<p>
Error is reported by libaspell.
</p>
<pre>
>>> <i># we set master dictionary file, the file doesn't exist</i>
>>> s = Speller('master', '/home/dictionary.rws')
Traceback (most recent call last):
File "<stdin>", line 1, in ?
aspell.AspellSpellerError:The file "/home/dictionary.rws" can not be opened for reading.
>>>
</pre>
<a name="AspellSpeller"></a>
<h3>5.3. AspellSpeller Object</h3>
<p>
The AspellSpeller object provides interface to the aspell. It has
several methods, described below.
</p>
<ul>
<li><a href="mConfigKeys">ConfigKeys</a></li>
<li><a href="check">check</a></li>
<li><a href="suggest">suggest</a></li>
<li><a href="addReplecement">addReplecement</a></li>
<li><a href="addtoPersonal">addtoPersonal</a></li>
<li><a href="saveAllwords">saveAllwords</a></li>
<li><a href="addtoSession">addtoSession</a></li>
<li><a href="clearSession">clearSession</a></li>
<li><a href="getPersonalwordlist">getPersonalwordlist</a></li>
<li><a href="getSessionwordlist">getSessionwordlist</a></li>
<li><a href="#getMainwordlist">getMainwordlist</a></li>
</ul>
<p>
In examples the assumption is that following code has been executed earlier.
</p>
<pre>
>>> import aspell
>>> s = aspell.Speller('lang', 'en')
>>> s
<AspellSpeller object at 0x40209050>
>>>
</pre>
<a name="mConfigKeys"></a>
<h4>ConfigKeys(word) => list of setting of speller</h4>
<p>
<b>New in version 1.1.</b><br>
Method returns a list of the <b>speller's</b> configuration keys.
Items on the list are 3-tuples:
</p>
<ol>
<li>key name</li>
<li>key type:
<ul>
<li>string</li>
<li>integer</li>
<li>boolean - string <tt>true</tt> or <tt>false</tt></li>
<li>list (string, where items are separated by colons)</li>
</ul></li>
<li>value for the key</li>
</ol>
<a name="check"></a>
<h4>check(word) => 0 or 1</h4>
<p>
Method checks spelling of given <tt>word</tt>. If <tt>word</tt> is present in
the main or personal (see <a href="addtoPersonal">addtoPersonal()</a>) or
session dictionary (see <a href="addtoSession">addtoSession()</a>) returns 1,
otherwise 0.
</p>
<pre>
>>> s.check('word') <i> correct word</i>
1
>>> s.check('wrod') <i> incorrect</i>
0
>>>
</pre>
<a name="suggest"></a>
<h4>suggest(word) => list of suggestions</h4>
<p>
Method returns a list of suggested spellings for given word.
Even if word is correct, i.e. method <a href="#check">check()</a> returned 1,
action is performed.
</p>
<pre>
>>> s.suggest('wrod') <i># we made mistake, what aspell suggests?</i>
['word', 'Rod', 'rod', 'Brod', 'prod', 'trod', 'Wood', 'wood', 'wried']
>>>
</pre>
<p>
<b>Warning!</b> <tt>suggest()</tt> in aspell 0.50 is very, very slow. I recommend caching it's results if program calls <tt>suggest</tt> several times with the same argument.</p>
<a name="#addReplecement"></a>
<h4>addReplecement(incorrect, correct) => None</h4>
<p>
Adds a replacement pair, it affects order of words
in <a href="#suggest">suggest()</a> result.
</p>
<pre>
>>> <i># we choose 7th word from previous result</i>
>>> s.addReplecement('wrod', 'trod')
>>> <i># and the selected word appears at the 1st position</i>
>>> s.suggest('word')
['trod', 'word', 'Rod', 'rod', 'Brod', 'prod', 'Wood', 'wood', 'wried']
</pre>
<p>
If config key <tt>save-repl</tt> is <tt>true</tt> method <a href="#saveAllwords">saveAllwords()</a> saves
the replacement pairs to file <tt>~/.aspell.{lang_code}.prepl</tt>.
</p>
<a name="addtoPersonal"></a>
<h4>addtoPersonal(word) => None</h4>
<p>
Adds word to the personal dictionary, which is stored in file <tt>~./.aspell.{lang_code}.pws</tt>. The added words are available for AspellSpeller object, but they remain unsaved until method <a href="#saveAllwords">saveAllwords()</a> is called.
</p>
<pre>
<i># personal dictionary is empty now</i>
$ cat ~/.aspell.en.pws
personal_ws-1.1 en 0
$ python
>>> import aspell
>>> s = aspell.Speller('lang', 'en')
<i># word 'aspell' doesn't exist</i>
>>> s.check('aspell')
0
<i># we add it to the personal dictionary</i> >>> s.addtoPersonal('aspell')
<i># and now aspell knows it</i>
>>> s.check('aspell')
1
<i># we save personal dictionary</i>
>>> s.saveAllwords()
<i># new word appeared in the file</i>
$ cat ~/.aspell.en.pws
personal_ws-1.1 en 1
aspell
<i># check it once again</i>
$ python
>>> import aspell
>>> s = aspell.Speller('lang', 'en')
<i># aspell still knows it's own name</i>
>>> s.check('aspell')
1
>>> s.check('aaa')
0
>>> s.check('bbb')
0
<i># add incorrect words, they shouldn't be saved</i>
>>> s.addtoPersonal('aaa')
>>> s.addtoPersonal('bbb')
>>> s.check('aaa')
1
>>> s.check('bbb')
1
<i># we've exit without saving, words 'aaa' and 'bbb' doesn't exists</i>
$ cat ~/.aspell.en.pws
personal_ws-1.1 en 1
aspell
$
</pre>
<a name="addtoSession"></a>
<h4>addtoSession(word) => None</h4>
<p>
Adds word to the session dictionary. The session dictionary is
volatile, it is not saved to any file. It is destroyed with
<a href="AspellSpeller ">AspellSpeller</a> object or when method <a href="clearSession">clearSession()</a> is called.
</p>
<a name="clearSession"></a>
<h4>clearSession() => None</h4>
<p>
Clears session dictionary.
</p>
<pre>
>>> import aspell
>>> s = aspell.Speller('lang', 'en')
>>> s.check('linux')
0
>>> s.addtoSession('linux')
>>> s.check('linux')
1
>>> s.clearSession()
>>> s.check('linux')
0
</pre>
<a name="getPersonalwordlist"></a>
<h4>getPersonalwordlist() => [list of strings]</h4>
<p>
Returns list of words from personal dictionary.
</p>
<a name="getSessionwordlist"></a>
<h4>getSessionwordlist() => [list of strings]</h4>
<p>
Returns list of words from session dictionary.
</p>
<pre>
>>> s.addtoSession('aaa')
>>> s.addtoSession('bbb')
>>> s.getSessionwordlist()
['aaa', 'bbb']
>>> s.clearSession()
>>> s.getSessionwordlist()
[]
>>>
</pre>
<a name="getMainwordlist"></a>
<h4>getMainwordlist() => [list of strings]</h4>
<p>
Returns list of words from the main dictionary.
</p>
<p>
<b>Warning!</b> On my machine Python is always killed, libc sends SIGKILL. If list is needed, program <tt>word-list-compress</tt> may be used.
</p>
<a name="encoding"></a><h2>6. ENCODING</h2>
<p>
Aspell uses 8-bit encoding. The encoding depend on dictionary setting and
is stored in key <tt>encoding</tt>. One can obtain this key using speller's
method <a href="#mConfigKeys">ConfigKeys</a>.
</p>
<p>
If your application uses other encoding then aspell, the translation is
needed. Here is an sample session (polish dictionary is used).
</p>
<pre>
>>> import aspell
>>> s=aspell.Speller('lang', 'pl')
>>>
>>> [i for i in s.ConfigKeys() if i[0]=='encoding']
[('encoding', 'string', 'iso8859-2')]
>>> enc = [i for i in s.ConfigKeys() if i[0]=='encoding'][0][2]
>>> enc <i> dictionary encoding</i>
'iso8859-2'
>>> word <i> encoding of word is utf8</i>
'g\xc5\xbceg\xc5\xbc\xc3\xb3\xc5\x82ka'
>>> s.check(word)
0
>>> s.check( unicode(word, 'utf-8').encode(enc) )
1
</pre>
<a name="author"></a><h2>7. AUTHOR</h2>
<p>
Wojciech Muła, <a href="mailto:wojciech_mula[at]poczta[dot]onet[dot]pl">wojciech_mula[at]poczta[dot]onet[dot]pl</a> (please replace <tt>[at]</tt> with <tt>@</tt> and <tt>[dot]</tt> with <tt>.</tt>)
</p>
<hr>
$Id: README.html,v 1.9 2005/02/16 15:38:13 wojtek Exp wojtek $
</body>
</html>
<!--
vim ts=8
-->