/usr/local/Hypy
view README.txt @ 139:d0a738aea316
Added tag 0.8.4.1 for changeset bbc3e3a3c4fb
| author | Cory Dodt <corymercurial@spam.goonmill.org> |
|---|---|
| date | Fri Oct 09 10:32:45 2009 -0700 (2009-10-09) |
| parents | 11f9e80e08e0 |
| children |
line source
1 ====
2 Hypy
3 ====
5 .. sidebar:: Download
7 Download the `latest source`_ or `browse the source`_ or get the `latest
8 official release`_.
10 .. _latest source: http://hypy-source.goonmill.org/archive/tip.tar.gz
11 .. _latest official release: http://pypi.python.org/pypi/Hypy/
12 .. _browse the source: http://hypy-source.goonmill.org/file/tip/
14 .. sidebar:: Docs
16 `Reference (API) documentation <http://goonmill.org/hypy/apidocs/>`_.
17 You probably want the `examples`_ though, knowing you.
19 .. sidebar:: Discuss
21 Hypy now has a Google Group called hypy-discuss_.
23 .. _examples: examples.tsw
24 .. _hypy-discuss: http://groups.google.com/group/hypy-discuss
26 .. image:: /static/hypylogo.png
28 Hypy is a fulltext search interface for Python applications. Use it to index
29 and search your documents from Python code.
31 Hypy is based on the estraiernative bindings by Yusuke Yoshida.
33 The estraiernative bindings are, in turn, based on Hyper Estraier by Mikio
34 Hirabayashi.
36 README
37 ------
39 Installation: Ubuntu using APT
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41 Hypy is hosted on Launchpad, and has a launchpad PPA. This is arguably the
42 easiest way to install the software if you are an Ubuntu user.
44 Add the following lines to the end of ``/etc/apt/sources.list``. You can
45 also paste these lines in to System > Administration > Software Sources >
46 Third-Party Software.
48 (jaunty)
49 ::
51 deb http://ppa.launchpad.net/corydodt/ubuntu jaunty main
52 deb-src http://ppa.launchpad.net/corydodt/ubuntu jaunty main
54 (or intrepid)
55 ::
57 deb http://ppa.launchpad.net/corydodt/ppa/ubuntu intrepid main
58 deb-src http://ppa.launchpad.net/corydodt/ppa/ubuntu intrepid main
60 Then::
62 sudo apt-get update
63 sudo apt-get install python-hypy
65 All dependencies including Hyper Estraier will be auto-fetched for you, and
66 you will get automatic updates when I publish them.
69 Installation: Non-Ubuntu
70 ~~~~~~~~~~~~~~~~~~~~~~~~
72 If you don't have Ubuntu or don't intend to use the PPA, you will need to
73 (a) install Hyper Estraier, then (b) install Hypy.
75 **Don't be intimidated by how long this section is; check your distribution
76 first for binary packages! Windows users, there's a link for you below.
77 Everyone who likes things to be complicated, read on.**
79 Installing Hyper Estraier on Windows
80 ====================================
82 If you are using Windows, a binary installer for `Windows Hyper Estraier`_ can
83 be had. **You must still install Hypy, perhaps with easy_install, so see
84 below.**
86 .. _Windows Hyper Estraier: http://hyperestraier.sourceforge.net/win/
88 Installing Hyper Estraier (dev packages) with a package manager
89 ===============================================================
91 Linux users can probably install binary packages using their favorite package
92 manager. You will need these:
94 * hyperestraier runtime
95 * libestraier headers and object code
96 * libqdbm headers and object code
97 * Python headers and object code, natch
99 If you are using Ubuntu (and for some reason you won't just use the PPA
100 above), you can get all the build dependencies with this command::
102 sudo apt-get install hyperestraier libestraier-dev libqdbm-dev python-dev
104 Installing Hyper Estraier from Source
105 =====================================
107 Instructions for building and `installing Hyper Estraier`_ can be found on
108 that site. It is a standard configure/make/make install process, but you must
109 make sure to download all the required files. See the Hyper Estraier
110 installation page for details.
112 .. _installing Hyper Estraier: http://hyperestraier.sourceforge.net/intro-en.html#installation
114 Then: Install Hypy with easy_install
115 ====================================
116 With setuptools (Ubuntu: sudo apt-get install python-setuptools), you can
117 install Hypy without even downloading it first, by using
118 ::
120 sudo easy_install hypy
123 ... or: Install Hypy from tarball
124 =================================
126 Get one of the tarballs `linked`_ at the top of the page.
128 ::
130 tar xvfz hypy.tar.gz; cd Hypy-*
131 python setup.py build; sudo python setup.py install
133 Optionally, run::
135 make tests
137 in the source directory to see the unit tests run.
139 .. _linked: Hypy_
142 Quick Start
143 ~~~~~~~~~~~
144 You can get an instant "oh I get it!" fix by looking inside the "examples"
145 directory distributed with this software.
147 Index documents into a collection (see `gather.py`_ for the complete program)::
149 ...
151 db = HDatabase()
152 db.open('casket', 'w')
153 # create a document object
154 doc = HDocument(uri=u'http://estraier.gov/example.txt')
155 ...
157 Search for documents in an existing collection (see `search.py`_ for the
158 complete program)::
160 ...
162 # create a search condition object
163 cond = HCondition(u'lull*')
164 # get the result of search
165 result = db.search(cond)
166 # iterate the result
167 for doc in result:
168 ...
170 .. _gather.py: http://hypy-source.goonmill.org/file/tip/examples/gather.py
171 .. _search.py: http://hypy-source.goonmill.org/file/tip/examples/search.py
174 Hey, I need Even More Examples
175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
177 OK.
179 Here are `even more examples`_. (Find this in the doc/ directory if you
180 unpacked the tarball and are reading this from there.)
182 .. _even more examples: examples.tsw
185 Read This! - Unicode
186 ~~~~~~~~~~~~~~~~~~~~
187 To make the transition to Python 3.0 easier, and because it is a good idea,
188 Hypy requires Unicode objects in all of its APIs.
190 *WRONG*
191 ::
193 >>> d = HDocument(uri='http://pinatas.com/store.html') # byte string!
194 Traceback (most recent call last):
195 File "<stdin>", line 1, in <module>
196 File "/usr/lib/python2.5/site-pacakges/hypy/lib.py", line 291, in __init__
197 raise TypeError("Must provide uri as unicode text")
198 TypeError: Must provide uri as unicode text
200 *RIGHT*
201 ::
203 >>> d = HDocument(uri=u'http://pinatas.com/store.html') # unicode :-)
204 >>> d.addText(u'Olé')
205 >>> d[u'@title'] = u'Piñata Store' # attributes are also unicode
207 Because of this change, and some other minor, Python-enhancing differences
208 between the APIs, I have deliberately renamed all the classes and methods
209 supported by Hypy, to prevent confusion. If you know Python and are already
210 familiar with Hyper Estraier, you should now visit the `API docs`_ to learn
211 the new names of functions. In general, though, "est_someclass_foo_bar" takes
212 a byte string in Hyper Estraier, but becomes "HSomeClass.fooBar" in Hypy and
213 takes Unicode text.
215 .. _API docs: api/
217 What's not Supported in Hypy vs. Hyper Estraier
218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219 Hyper Estraier implements a version of federated search which is supported by
220 its APIs such as merge, search_meta and eclipse. If I hear a compelling use case
221 or receive patches with unit tests, I may add support for these APIs. This is
222 not a hard thing to do, I just have no use for it myself, so I am reluctant to
223 promise to maintain it unless someone else really needs it.
226 Contributing and Reporting Bugs
227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228 Hypy has a `bug tracker <https://bugs.launchpad.net/hypy>`_ on Launchpad.
230 For more information on contributing, including the URL of the source
231 repository for Hypy, go to `DevelopmentCentral
232 <http://wiki.goonmill.org/DevelopmentCentral>`_ on the wiki_.
234 .. _wiki: http://wiki.goonmill.org/
236 It bears emphasizing that **bugs with reproducible steps, patches and unit
237 tests** (in that order) **get fixed sooner**.
240 License
241 ~~~~~~~
242 LGPL 2.1
244 Hypy (c) Cory Dodt, 2008.
246 estraiernative (c) Yusuke Yoshida.