add --shared
[pylucene.git] / doc / documentation / readme.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <head>
4 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <meta content="Apache Forrest" name="Generator">
6 <meta name="Forrest-version" content="0.8">
7 <meta name="Forrest-skin-name" content="pelt">
8 <title>PyLucene Features</title>
9 <link type="text/css" href="../skin/basic.css" rel="stylesheet">
10 <link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
11 <link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
12 <link type="text/css" href="../skin/profile.css" rel="stylesheet">
13 <script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
14 <link rel="shortcut icon" href="../">
15 </head>
16 <body onload="init()">
17 <script type="text/javascript">ndeSetTextSize();</script>
18 <div id="top">
19 <!--+
20     |breadtrail
21     +-->
22 <div class="breadtrail">
23 <a href="http://www.apache.org/">apache</a> &gt; <a href="http://lucene.apache.org/">lucene</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
24 </div>
25 <!--+
26     |header
27     +-->
28 <div class="header">
29 <!--+
30     |start group logo
31     +-->
32 <div class="grouplogo">
33 <a href="http://lucene.apache.org/"><img class="logoImage" alt="Lucene" src="../images/lucene_green_150.gif" title="Lucene Description"></a>
34 </div>
35 <!--+
36     |end group logo
37     +-->
38 <!--+
39     |start Project Logo
40     +-->
41 <div class="projectlogoA1">
42 <a href="http://lucene.apache.org/pylucene/"><img class="logoImage" alt="PyLucene" src="../images/project.png" title="PyLucene Description"></a>
43 </div>
44 <!--+
45     |end Project Logo
46     +-->
47 <!--+
48     |start Tabs
49     +-->
50 <ul id="tabs">
51 <li class="current">
52 <a class="selected" href="../index.html">PyLucene</a>
53 </li>
54 <li>
55 <a class="unselected" href="../jcc/index.html">JCC</a>
56 </li>
57 </ul>
58 <!--+
59     |end Tabs
60     +-->
61 </div>
62 </div>
63 <div id="main">
64 <div id="publishedStrip">
65 <!--+
66     |start Subtabs
67     +-->
68 <div id="level2tabs"></div>
69 <!--+
70     |end Endtabs
71     +-->
72 <script type="text/javascript"><!--
73 document.write("Last Published: " + document.lastModified);
74 //  --></script>
75 </div>
76 <!--+
77     |breadtrail
78     +-->
79 <div class="breadtrail">
80
81              &nbsp;
82            </div>
83 <!--+
84     |start Menu, mainarea
85     +-->
86 <!--+
87     |start Menu
88     +-->
89 <div id="menu">
90 <div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">About</div>
91 <div id="menu_1.1" class="menuitemgroup">
92 <div class="menuitem">
93 <a href="../index.html" title="Welcome to PyLucene">Index</a>
94 </div>
95 </div>
96 <div onclick="SwitchMenu('menu_selected_1.2', '../skin/')" id="menu_selected_1.2Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Documentation</div>
97 <div id="menu_selected_1.2" class="selectedmenuitemgroup" style="display: block;">
98 <div class="menuitem">
99 <a href="../documentation/install.html">Installation</a>
100 </div>
101 <div class="menupage">
102 <div class="menupagetitle">Features</div>
103 </div>
104 </div>
105 <div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Resources</div>
106 <div id="menu_1.3" class="menuitemgroup">
107 <div class="menuitem">
108 <a href="http://www.apache.org/dyn/closer.cgi/lucene/pylucene/">Releases</a>
109 </div>
110 <div class="menuitem">
111 <a href="../resources/version_control.html">Source Code</a>
112 </div>
113 <div class="menuitem">
114 <a href="../resources/mailing_lists.html">Mailing Lists</a>
115 </div>
116 <div class="menuitem">
117 <a href="http://issues.apache.org/jira/browse/PyLucene">Issue Tracking</a>
118 </div>
119 </div>
120 <div id="credit"></div>
121 <div id="roundbottom">
122 <img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
123 <!--+
124   |alternative credits
125   +-->
126 <div id="credit2"></div>
127 </div>
128 <!--+
129     |end Menu
130     +-->
131 <!--+
132     |start content
133     +-->
134 <div id="content">
135 <div title="Portable Document Format" class="pdflink">
136 <a class="dida" href="readme.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
137         PDF</a>
138 </div>
139 <h1>PyLucene Features</h1>
140 <div id="minitoc-area">
141 <ul class="minitoc">
142 <li>
143 <a href="#install">Installing PyLucene</a>
144 </li>
145 <li>
146 <a href="#api">API documentation</a>
147 <ul class="minitoc">
148 <li>
149 <a href="#samples">Samples</a>
150 </li>
151 <li>
152 <a href="#threading">Threading support with attachCurrentThread</a>
153 </li>
154 <li>
155 <a href="#exceptions">Exception handling with lucene.JavaError</a>
156 </li>
157 <li>
158 <a href="#arrays">Handling Java arrays</a>
159 </li>
160 <li>
161 <a href="#differences">Differences between the Java Lucene and PyLucene APIs</a>
162 </li>
163 <li>
164 <a href="#python">Pythonic extensions to the Java Lucene APIs</a>
165 </li>
166 <li>
167 <a href="#extensions">Extending Java Lucene classes from Python</a>
168 </li>
169 </ul>
170 </li>
171 </ul>
172 </div>
173     
174 <div class="warning">
175 <div class="label">Warning</div>
176 <div class="content">
177       Before calling any PyLucene API that requires the Java VM, start it by
178       calling <span class="codefrag">initVM(classpath, ...)</span>. More about this function
179       in <a href="../jcc/documentation/readme.html">here</a>.
180     </div>
181 </div>
182     
183 <a name="N10017"></a><a name="install"></a>
184 <h2 class="boxed">Installing PyLucene</h2>
185 <div class="section">
186 <p>
187         PyLucene is a Python extension built with 
188         <a href="../jcc/index.html">JCC</a>.
189       </p>
190 <p>
191         To build PyLucene, JCC needs to be built first. Sources for JCC are
192         included with the PyLucene sources. Instructions for building and
193         installing JCC are <a href="../jcc/documentation/install.html">here</a>. 
194       </p>
195 <p>
196         Instruction for building PyLucene
197         are <a href="../documentation/install.html">here</a>.
198       </p>
199 </div>
200     
201 <a name="N10033"></a><a name="api"></a>
202 <h2 class="boxed">API documentation</h2>
203 <div class="section">
204 <p>
205         PyLucene is closely tracking Java Lucene releases. It intends to
206         supports the entire Lucene API.
207       </p>
208 <p>
209         PyLucene also includes a number of Lucene contrib packages: the
210         Snowball analyzer and stemmers, the highlighter package, analyzers
211         for other languages than english, regular expression queries, 
212         specialized queries such as 'more like this' and more.
213       </p>
214 <p>
215         This document only covers the pythonic extensions to Lucene offered
216         by PyLucene as well as some differences between the Java and Python
217         APIs. For the documentation on Java Lucene APIs,
218         see <a href="http://lucene.apache.org/java/docs/api/index.html">here</a>.
219       </p>
220 <p>
221         To help with debugging and to support some Lucene APIs, PyLucene also
222         exposes some Java runtime APIs.
223       </p>
224 <a name="N10049"></a><a name="samples"></a>
225 <h3 class="boxed">Samples</h3>
226 <p>
227           The best way to learn PyLucene is to look at the many samples
228           included with the PyLucene source release or on the web at:
229         </p>
230 <ul>
231           
232 <li>
233             
234 <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples">http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples</a>
235           
236 </li>
237           
238 <li>
239             
240 <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction">http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction</a>
241           
242 </li>
243         
244 </ul>
245 <p>
246           A large number of samples are shipped with PyLucene. Most notably,
247           all the samples published in
248           the <a href="http://www.manning.com/hatcher2"><em>Lucene in
249           Action</em></a> book that did not depend on a third party Java
250           library for which there was no obvious Python equivalent were
251           ported to Python and PyLucene.
252         </p>
253 <p>
254           
255 <em>Lucene in Action</em> is a great companion to learning
256           Lucene. Having all the samples available in Python should make it
257           even easier for Python developers.
258         </p>
259 <p>
260           
261 <em>Lucene in Action</em> was written by Erik Hatcher and Otis
262           Gospodnetic, both part of the Java Lucene development team, and is
263           available from
264           <a href="http://www.manning.com/hatcher2">Manning Publications</a>.
265         </p>
266 <a name="N1007C"></a><a name="threading"></a>
267 <h3 class="boxed">Threading support with attachCurrentThread</h3>
268 <p>
269           Before PyLucene APIs can be used from a thread other than the main
270           thread that was not created by the Java Runtime, the
271           <span class="codefrag">attachCurrentThread()</span> method must be called on the
272           <span class="codefrag">JCCEnv</span> object returned by the <span class="codefrag">initVM()</span>
273           or <span class="codefrag">getVMEnv()</span> functions.
274         </p>
275 <a name="N10092"></a><a name="exceptions"></a>
276 <h3 class="boxed">Exception handling with lucene.JavaError</h3>
277 <p>
278           Java exceptions are caught at the language barrier and reported to
279           Python by raising a JavaError instance whose args tuple contains the
280           actual Java Exception instance.
281         </p>
282 <a name="N1009C"></a><a name="arrays"></a>
283 <h3 class="boxed">Handling Java arrays</h3>
284 <p>
285           Java arrays are returned to Python in a <span class="codefrag">JArray</span>
286           wrapper instance that implements the Python sequence protocol. It
287           is possible to change array elements but not to change the array
288           size.
289         </p>
290 <p>
291           A few Lucene APIs take array arguments and expect values to be
292           returned in them. To call such an API and be able to retrieve the
293           array values after the call, a Java array needs to instantiated
294           first.<br>
295           For example, accessing termDocs:
296         </p>
297 <pre class="code">
298           termDocs = reader.termDocs(Term("isbn", isbn))
299           docs = JArray('int')(1)   # allocate an int[1] array
300           freq = JArray('int')(1)   # allocate an int[1] array
301           if termDocs.read(docs, freq) == 1:
302               bits.set(docs[0])     # access the array's first element
303         </pre>
304 <p>
305           In addition to <span class="codefrag">'int'</span>, the <span class="codefrag">'JArray'</span>
306           function accepts <span class="codefrag">'object'</span>, <span class="codefrag">'string'</span>,
307           <span class="codefrag">'bool'</span>, <span class="codefrag">'byte'</span>, <span class="codefrag">'char'</span>,
308           <span class="codefrag">'double'</span>, <span class="codefrag">'float'</span>, <span class="codefrag">'long'</span>
309           and <span class="codefrag">'short'</span> to create an array of the corresponding
310           type. The <span class="codefrag">JArray('object')</span> constructor takes a second
311           argument denoting the class of the object elements. This argument
312           is optional and defaults to Object. 
313         </p>
314 <p>
315           To convert a char array to a Python string use a 
316           <span class="codefrag">''.join(array)</span> construct.
317         </p>
318 <p>
319           Instead of an integer denoting the size of the desired Java array,
320           a sequence of objects of the expected element type may be passed
321           in to the array constructor.<br>
322           For example:
323         </p>
324 <pre class="code">
325           # creating a Java array of double from the [1.5, 2.5] list
326           JArray('double')([1.5, 2.5])
327         </pre>
328 <p>
329           All methods that expect an array also accept a sequence of Python
330           objects of the expected element type. If no values are expected
331           from the array arguments after the call, it is hence not necessary
332           to instantiate a Java array to make such calls.
333         </p>
334 <p>
335           See <a href="../jcc/documentation/readme.html">JCC</a> for more
336           information about handling arrays. 
337         </p>
338 <a name="N100F2"></a><a name="differences"></a>
339 <h3 class="boxed">Differences between the Java Lucene and PyLucene APIs</h3>
340 <ul>
341           
342 <li>
343             The PyLucene API exposes all Java Lucene classes in a flat namespace
344             in the PyLucene module. For example, the Java import
345             statement <span class="codefrag">import
346             org.apache.lucene.index.IndexReader;</span> corresponds to the
347             Python import statement <span class="codefrag">from lucene import
348             IndexReader</span>
349           
350 </li>
351           
352 <li>
353             Downcasting is a common operation in Java but not a concept in
354             Python. Because the wrapper objects implementing exactly the
355             APIs of the declared type of the wrapped object, all classes
356             implement two class methods called instance_ and cast_ that
357             verify and cast an instance respectively.
358           </li>
359         
360 </ul>
361 <a name="N10108"></a><a name="python"></a>
362 <h3 class="boxed">Pythonic extensions to the Java Lucene APIs</h3>
363 <p>
364           Java is a very verbose language. Python, on the other hand, offers
365           many syntactically attractive constructs for iteration, property
366           access, etc... As the Java Lucene samples from the <em>Lucene in
367           Action</em> book were ported to Python, PyLucene received a number
368           of pythonic extensions listed here:
369         </p>
370 <ul>
371           
372 <li>
373             Iterating search hits is a very common operation. Hits instances
374             are iterable in Python. Two values are returned for each
375             iteration, the zero-based number of the document in the Hits
376             instance and the document instance itself.<br>
377             The Java loop:
378             <pre class="code">
379               for (int i = 0; i &lt; hits.length(); i++) {
380                   Document doc = hits.doc(i);
381                   System.out.println(hits.score(i) + " : " + doc.get("title"));
382               }
383             </pre>
384             can be written in Python:
385             <pre class="code">
386              for hit in hits:
387                  hit = Hit.cast_(hit)
388                  print hit.getScore(), ':', hit.getDocument['title']
389              </pre>
390             if hit.iterator()'s next() method were declared to return
391             <span class="codefrag">Hit</span> instead of <span class="codefrag">Object</span>, the above
392             cast_() call would not be unnecessary.<br>
393             The same java loop can also be written:
394             <pre class="code">
395               for i xrange(len(hits)):
396                   print hits.score(i), ':', hits[i]['title']
397             </pre>
398           
399 </li>
400           
401 <li>
402             Hits instances partially implement the Python 'sequence' 
403             protocol.<br>
404             The Java expressions:
405             <pre class="code">
406               hits.length()
407               doc = hits.get(i)
408             </pre>
409             are better written in Python:
410             <pre class="code">
411               len(hits)
412               doc = hits[i]
413             </pre>
414           
415 </li>
416           
417 <li>
418             Document instances have fields whose values can be accessed 
419             through the mapping protocol.<br>
420             The Java expression:
421             <pre class="code">
422               doc.get("title")
423             </pre>
424             is better written in Python:
425             <pre class="code">
426               doc['title']
427             </pre>
428           
429 </li>
430           
431 <li>
432             Document instances can be iterated over for their fields.<br>
433             The Java loop:
434             <pre class="code">
435               Enumeration fields = doc.getFields();
436               while (fields.hasMoreElements()) {
437                   Field field = (Field) fields.nextElement();
438                   ...
439               }
440             </pre>
441             is better written in Python:
442             <pre class="code">
443               for field in doc.getFields():
444                   field = Field.cast_(field)
445                   ...
446             </pre>
447             Once JCC heeds Java 1.5 type parameters and once Java Lucene
448             makes use of them, such casting should become unncessary.
449           </li>
450         
451 </ul>
452 <a name="N10158"></a><a name="extensions"></a>
453 <h3 class="boxed">Extending Java Lucene classes from Python</h3>
454 <p>
455           Many areas of the Lucene API expect the programmer to provide
456           their own implementation or specialization of a feature where
457           the default is inappropriate. For example, text analyzers and
458           tokenizers are an area where many parameters and environmental
459           or cultural factors are calling for customization.
460         </p>
461 <p>
462           PyLucene enables this by providing Java extension points listed
463           below that serve as proxies for Java to call back into the
464           Python implementations of these customizations.
465         </p>
466 <p>
467           These extension points are simple Java classes that JCC
468           generates the native C++ implementations for. It is easy to add
469           more such extensions classes into the 'java' directory of the
470           PyLucene source tree.
471         </p>
472 <p>
473           To learn more about this topic, please refer to the JCC
474           <a href="../jcc/documentation/readme.html">documentation</a>.
475         </p>
476 <p>
477           Please refer to the classes in the 'java' tree for currently
478           available extension points. Examples of uses of these extension
479           points are to be found in PyLucene's unit tests and <em>Lucene
480           in
481           Action</em> <a href="http://svn.apache.org/viewcvs.cgi/lucene/pylucene/trunk/samples/LuceneInAction">samples</a>.
482         </p>
483 </div>
484   
485 </div>
486 <!--+
487     |end content
488     +-->
489 <div class="clearboth">&nbsp;</div>
490 </div>
491 <div id="footer">
492 <!--+
493     |start bottomstrip
494     +-->
495 <div class="lastmodified">
496 <script type="text/javascript"><!--
497 document.write("Last Published: " + document.lastModified);
498 //  --></script>
499 </div>
500 <div class="copyright">
501         Copyright &copy;
502          2009-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
503 </div>
504 <!--+
505     |end bottomstrip
506     +-->
507 </div>
508 </body>
509 </html>