Doc/sharing.html

   1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
   2 <html><head>
   3          <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   4          <meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"><title>Sharing Declarations Between Cython Modules</title></head>
   5
   6 <body>
   7    <h1>  <hr width="100%">Sharing Declarations Between Cython Modules
   8 <hr width="100%"></h1>
   9   This section describes a new set of facilities introduced in Cython 0.8
  10 for making C declarations and extension types in one Cython module available
  11 for use in another Cython module. These facilities are closely modelled on
  12 the Python import mechanism, and can be thought of as a compile-time version
  13 of it.
  14 <h2> Contents</h2>
  15    <ul>
  16   <li> <a href="#DefAndImpFiles">Definition and Implementation files</a></li>
  17        <ul>
  18   <li> <a href="#WhatDefFileContains">What a Definition File contains</a></li>
  19    <li> <a href="#WhatImpFileContains">What an Implementation File contains</a></li>
  20       </ul>
  21    <li> <a href="#CImportStatement">The <tt>cimport</tt> statement</a></li>
  22        <ul>
  23   <li> <a href="#SearchPaths">Search paths for definition files</a></li>
  24    <li> <a href="#ResolvingNamingConflicts">Using <tt>cimport</tt> to resolve
  25 naming conflicts</a></li>
  26       </ul>
  27    <li> <a href="#SharingExtensionTypes">Sharing extension types</a></li>
  28   </ul>
  29    <h2> <a name="DefAndImpFiles"></a>Definition and Implementation files</h2>
  30   A Cython module can be split into two parts: a <i>definition file</i> with
  31  a <tt>.pxd</tt> suffix, containing C declarations that are to be available
  32  to other Cython modules, and an <i>implementation file</i> with a <tt>.pyx</tt>
  33 suffix, containing everything else. When a module wants to use something
  34 declared in another module's definition file, it imports it using the <a href="#CImportStatement"><b>cimport</b> statement</a>.
  35 <h3> <a name="WhatDefFileContains"></a>What a Definition File contains</h3>
  36   A definition file can contain:
  37 <ul>
  38   <li> Any kind of C type declaration.</li>
  39    <li> <b>extern</b> C function or variable declarations.</li>
  40    <li> The definition part of an extension type (<a href="#SharingExtensionTypes">see below</a>).</li>
  41   </ul>
  42   It cannot currently contain any non-extern C function or variable declarations
  43  (although this may be possible in a future version).
  44 <p>It cannot contain the implementations of any C or Python functions, or
  45 any Python class definitions, or any executable statements. </p>
  46  <blockquote>NOTE: You don't need to (and shouldn't) declare anything in a
  47 declaration file <b>public</b> in order to make it available to other Cython
  48 modules; its mere presence in a definition file does that. You only need a
  49 public declaration if you want to make something available to external C code.</blockquote>
  50    <h3> <a name="WhatImpFileContains"></a>What an Implementation File contains</h3>
  51   An implementation file can contain any kind of Cython statement, although
  52  there are some restrictions on the implementation part of an extension type
  53 if the corresponding definition file also defines that type (see below).
  54
  55 <h2> <a name="CImportStatement"></a>The <tt>cimport</tt> statement</h2>
  56   The <b>cimport</b> statement is used in a definition or implementation
  57 file to gain access to names declared in another definition file. Its syntax
  58 exactly parallels that of the normal Python import statement:
  59 <blockquote><tt>cimport </tt><i>module</i><tt> [, </tt><i>module</i><tt>...]</tt></blockquote>
  60    <blockquote><tt>from </tt><i>module</i><tt> cimport </tt><i>name</i><tt>
  61 [as   </tt><i>name</i><tt>] [, </tt><i>name</i><tt> [as </tt><i>name</i><tt>]
  62  ...]</tt></blockquote>
  63   Here is an example. The file on the left is a definition file which exports
  64  a C data type. The file on the right is an implementation file which imports
  65  and uses it. <br>
  66  &nbsp; <table cellpadding="5" cols="2" width="100%">
  67   <tbody>
  68      <tr>
  69   <td bgcolor="#ffcc00" width="40%"><b><tt>dishes.pxd</tt></b></td>
  70    <td bgcolor="#5dbaca"><b><tt>restaurant.pyx</tt></b></td>
  71   </tr>
  72    <tr align="left" valign="top">
  73   <td bgcolor="#ffcc18" width="40%"><tt>cdef enum otherstuff:</tt> <br>
  74        <tt>&nbsp;&nbsp;&nbsp; sausage, eggs, lettuce</tt>             <p><tt>cdef struct spamdish:</tt> <br>
  75        <tt>&nbsp;&nbsp;&nbsp; int oz_of_spam</tt> <br>
  76        <tt>&nbsp;&nbsp;&nbsp; otherstuff filler</tt></p>
  77        </td>
  78    <td bgcolor="#5dbaca"><tt>cimport dishes</tt> <br>
  79        <tt>from dishes cimport spamdish</tt>             <p><tt>cdef void prepare(spamdish *d):</tt> <br>
  80        <tt>&nbsp;&nbsp;&nbsp; d.oz_of_spam = 42</tt> <br>
  81        <tt>&nbsp;&nbsp;&nbsp; d.filler = dishes.sausage</tt> </p>
  82              <p><tt>def serve():</tt> <br>
  83        <tt>&nbsp;&nbsp;&nbsp; spamdish d</tt> <br>
  84        <tt>&nbsp;&nbsp;&nbsp; prepare(&amp;d)</tt> <br>
  85        <tt>&nbsp;&nbsp;&nbsp; print "%d oz spam, filler no. %d" % \</tt>
  86       <br>
  87        <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (d-&gt;oz_of_spam,
  88  d-&gt;otherstuff)</tt></p>
  89        </td>
  90   </tr>
  91       </tbody> </table>
  92    <p>It is important to understand that the <b>cimport</b> statement can <i>only</i>
  93 be used to import C data types, external C functions and variables, and extension
  94 types. It cannot be used to import any Python objects, and (with one exception)
  95 it doesn't imply any Python import at run time. If you want to refer to any
  96 Python names from a module that you have cimported, you will have to include
  97 a regular <b>import</b> statement for it as well. </p>
  98  <p>The exception is that when you use <b>cimport</b> to import an extension
  99  type, its type object is imported at run time and made available by the
 100 name under which you imported it. Using <b>cimport</b> to import extension
 101 types is covered in more detail <a href="#SharingExtensionTypes">below</a>.
 102 </p>
 103  <h3> <a name="SearchPaths"></a>Search paths for definition files</h3>
 104   When you <b>cimport</b> a module called <tt>modulename</tt>, the Cython
 105 compiler searches for a file called <tt>modulename.pxd</tt> along the search
 106 path for include files, as specified by <b>-I</b> command line options.
 107 <p>Also, whenever you compile a file <tt>modulename.pyx</tt>, the corresponding
 108  definition file <tt>modulename.pxd</tt> is first searched for along the
 109 same path, and if found, it is processed before processing the <tt>.pyx</tt>
 110 file.  </p>
 111  <h3> <a name="ResolvingNamingConflicts"></a>Using cimport to resolve naming
 112  conflicts</h3>
 113   The cimport mechanism provides a clean and simple way to solve the problem
 114  of wrapping external C functions with Python functions of the same name.
 115 All you need to do is put the extern C declarations into a .pxd file for
 116 an imaginary module, and cimport that module. You can then refer to the C
 117 functions by qualifying them with the name of the module. Here's an example:
 118 <br>
 119  &nbsp; <table cellpadding="5" cols="2" width="100%">
 120   <tbody>
 121      <tr>
 122   <td bgcolor="#ffcc00" width="50%"><b><tt>c_lunch.pxd</tt></b></td>
 123    <td bgcolor="#5dbaca"><b><tt>lunch.pyx</tt></b></td>
 124   </tr>
 125    <tr align="left" valign="top">
 126   <td bgcolor="#ffcc18" width="50%"><tt>cdef extern from "lunch.h":</tt>
 127       <br>
 128        <tt>&nbsp;&nbsp;&nbsp; void eject_tomato(float)</tt></td>
 129    <td bgcolor="#5dbaca"><tt>cimport c_lunch</tt>             <p><tt>def eject_tomato(float speed):</tt> <br>
 130        <tt>&nbsp;&nbsp;&nbsp; c_lunch.eject_tomato(speed)</tt></p>
 131        </td>
 132   </tr>
 133       </tbody> </table>
 134    <p>You don't need any <tt>c_lunch.pyx</tt> file, because the only things
 135 defined in <tt>c_lunch.pxd</tt> are extern C entities. There won't be any
 136 actual <tt>c_lunch</tt> module at run time, but that doesn't matter -- <tt>c_lunch</tt>
 137 has done its job of providing an additional namespace at compile time. </p>
 138  <h2> <a name="SharingExtensionTypes"></a>Sharing Extension Types</h2>
 139   An extension type declaration can also be split into two parts, one in
 140 a definition file and the other in the corresponding implementation file.
 141 <br>
 142  <br>
 143  The definition part of the extension type can only declare C attributes
 144 and C methods, not Python methods, and it must declare <i>all</i> of that
 145 type's C attributes and C methods.<br>
 146  <br>
 147  The implementation part must implement all of the C methods declared in
 148 the definition part, and may not add any further C attributes. It may also
 149 define Python methods.
 150 <p>Here is an example of a module which defines and exports an extension
 151 type, and another module which uses it. <br>
 152  &nbsp; <table cellpadding="5" cols="2" width="100%">
 153   <tbody>
 154      <tr>
 155   <td bgcolor="#ffcc18" width="30%"><b><tt>Shrubbing.pxd</tt></b></td>
 156    <td bgcolor="#5dbaca" width="50%"><b><tt>Shrubbing.pyx</tt></b></td>
 157   </tr>
 158    <tr align="left" valign="top">
 159   <td bgcolor="#ffcc18" width="30%"><tt>cdef class Shrubbery:</tt> <br>
 160        <tt>&nbsp;&nbsp;&nbsp; cdef int width</tt> <br>
 161        <tt>&nbsp;&nbsp;&nbsp; cdef int length</tt></td>
 162    <td bgcolor="#5dbaca" width="50%"><tt>cdef class Shrubbery:</tt> <br>
 163        <tt>&nbsp;&nbsp;&nbsp; def __new__(self, int w, int l):</tt> <br>
 164        <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.width = w</tt>
 165       <br>
 166        <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; self.length = l</tt>
 167             <p><tt>def standard_shrubbery():</tt> <br>
 168        <tt>&nbsp;&nbsp;&nbsp; return Shrubbery(3, 7)</tt></p>
 169        </td>
 170   </tr>
 171    <tr>
 172   <td colspan="2" bgcolor="#8cbc1c" width="30%"><b><tt>Landscaping.pyx</tt></b></td>
 173   </tr>
 174    <tr>
 175   <td colspan="2" bgcolor="#99cc00" width="30%"><tt>cimport Shrubbing</tt>
 176       <br>
 177        <tt>import Shrubbing</tt>             <p><tt>cdef Shrubbing.Shrubbery sh</tt> <br>
 178        <tt>sh = Shrubbing.standard_shrubbery()</tt> <br>
 179        <tt>print "Shrubbery size is %d x %d" % (sh.width, sh.height)</tt>
 180       <br>
 181  &nbsp;</p>
 182        </td>
 183   </tr>
 184       </tbody> </table>
 185    </p>
 186  <p>Some things to note about this example: </p>
 187  <ul>
 188   <li> There is a <tt>cdef class Shrubbery</tt> declaration in both Shrubbing.pxd
 189  and Shrubbing.pyx. When the Shrubbing module is compiled, these two declarations
 190  are combined into one.</li>
 191
 192  &nbsp; <li> In Landscaping.pyx, the <tt>cimport Shrubbing</tt> declaration
 193 allows us to refer to the Shrubbery type as <tt>Shrubbing.Shrubbery</tt>.
 194 But it doesn't bind the name <tt>Shrubbery</tt> in Landscaping's module namespace
 195  at run time, so to access <tt>Shrubbery.standard_shrubbery</tt> we also
 196 need to <tt>import Shrubbing</tt>.</li>
 197   </ul>
 198    <hr width="100%">Back to the <a href="overview.html">Language Overview</a>
 199 <br>
 200  <br>
 201 </body></html>