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>