home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / i / imp next >
Text File  |  1996-11-14  |  7KB  |  120 lines
  1. <TITLE>imp -- Python library reference</TITLE>
  2. Next: <A HREF="../_/__builtin__" TYPE="Next">__builtin__</A>  
  3. Prev: <A HREF="../m/marshal" TYPE="Prev">marshal</A>  
  4. Up: <A HREF="../p/python_services" TYPE="Up">Python Services</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H1>3.8. Built-in Module <CODE>imp</CODE></H1>
  7. This module provides an interface to the mechanisms used to implement
  8. the <CODE>import</CODE> statement.  It defines the following constants and
  9. functions:
  10. <P>
  11. <DL><DT><B>get_magic</B> () -- function of module imp<DD>
  12. Return the magic string value used to recognize byte-compiled code
  13. files (``<CODE>.pyc</CODE> files'').
  14. </DL>
  15. <DL><DT><B>get_suffixes</B> () -- function of module imp<DD>
  16. Return a list of triples, each describing a particular type of file.
  17. Each triple has the form <CODE>(<VAR>suffix</VAR>, <VAR>mode</VAR>,
  18. <VAR>type</VAR>)</CODE>, where <VAR>suffix</VAR> is a string to be appended to the
  19. module name to form the filename to search for, <VAR>mode</VAR> is the mode
  20. string to pass to the built-in <CODE>open</CODE> function to open the file
  21. (this can be <CODE>'r'</CODE> for text files or <CODE>'rb'</CODE> for binary
  22. files), and <VAR>type</VAR> is the file type, which has one of the values
  23. <CODE>PY_SOURCE</CODE>, <CODE>PY_COMPILED</CODE> or <CODE>C_EXTENSION</CODE>, defined
  24. below.  (System-dependent values may also be returned.)
  25. </DL>
  26. <DL><DT><B>find_module</B> (<VAR>name</VAR>, [<VAR>path</VAR>]) -- function of module imp<DD>
  27. Try to find the module <VAR>name</VAR> on the search path <VAR>path</VAR>.  The
  28. default <VAR>path</VAR> is <CODE>sys.path</CODE>.  The return value is a triple
  29. <CODE>(<VAR>file</VAR>, <VAR>pathname</VAR>, <VAR>description</VAR>)</CODE> where
  30. <VAR>file</VAR> is an open file object positioned at the beginning,
  31. <VAR>pathname</VAR> is the pathname of the
  32. file found, and <VAR>description</VAR> is a triple as contained in the list
  33. returned by <CODE>get_suffixes</CODE> describing the kind of file found.
  34. </DL>
  35. <DL><DT><B>init_builtin</B> (<VAR>name</VAR>) -- function of module imp<DD>
  36. Initialize the built-in module called <VAR>name</VAR> and return its module
  37. object.  If the module was already initialized, it will be initialized
  38. <I>again</I>.  A few modules cannot be initialized twice --- attempting
  39. to initialize these again will raise an <CODE>ImportError</CODE> exception.
  40. If there is no
  41. built-in module called <VAR>name</VAR>, <CODE>None</CODE> is returned.
  42. </DL>
  43. <DL><DT><B>init_frozen</B> (<VAR>name</VAR>) -- function of module imp<DD>
  44. Initialize the frozen module called <VAR>name</VAR> and return its module
  45. object.  If the module was already initialized, it will be initialized
  46. <I>again</I>.  If there is no frozen module called <VAR>name</VAR>,
  47. <CODE>None</CODE> is returned.  (Frozen modules are modules written in
  48. Python whose compiled byte-code object is incorporated into a
  49. custom-built Python interpreter by Python's <CODE>freeze</CODE> utility.
  50. See <CODE>Tools/freeze</CODE> for now.)
  51. </DL>
  52. <DL><DT><B>is_builtin</B> (<VAR>name</VAR>) -- function of module imp<DD>
  53. Return <CODE>1</CODE> if there is a built-in module called <VAR>name</VAR> which can be
  54. initialized again.  Return <CODE>-1</CODE> if there is a built-in module
  55. called <VAR>name</VAR> which cannot be initialized again (see
  56. <CODE>init_builtin</CODE>).  Return <CODE>0</CODE> if there is no built-in module
  57. called <VAR>name</VAR>.
  58. </DL>
  59. <DL><DT><B>is_frozen</B> (<VAR>name</VAR>) -- function of module imp<DD>
  60. Return <CODE>1</CODE> if there is a frozen module (see <CODE>init_frozen</CODE>)
  61. called <VAR>name</VAR>, <CODE>0</CODE> if there is no such module.
  62. </DL>
  63. <DL><DT><B>load_compiled</B> (<VAR>name</VAR>, <VAR>pathname</VAR>, <VAR>file</VAR>) -- function of module imp<DD>
  64. Load and initialize a module implemented as a byte-compiled code file
  65. and return its module object.  If the module was already initialized,
  66. it will be initialized <I>again</I>.  The <VAR>name</VAR> argument is used
  67. to create or access a module object.  The <VAR>pathname</VAR> argument
  68. points to the byte-compiled code file.  The <VAR>file</VAR>
  69. argument is the byte-compiled code file, open for reading in binary
  70. mode, from the beginning.
  71. It must currently be a real file object, not a
  72. user-defined class emulating a file.
  73. </DL>
  74. <DL><DT><B>load_dynamic</B> (<VAR>name</VAR>, <VAR>pathname</VAR>, [<VAR>file</VAR>]) -- function of module imp<DD>
  75. Load and initialize a module implemented as a dynamically loadable
  76. shared library and return its module object.  If the module was
  77. already initialized, it will be initialized <I>again</I>.  Some modules
  78. don't like that and may raise an exception.  The <VAR>pathname</VAR>
  79. argument must point to the shared library.  The <VAR>name</VAR> argument is
  80. used to construct the name of the initialization function: an external
  81. C function called <CODE>init<VAR>name</VAR>()</CODE> in the shared library is
  82. called.  The optional <VAR>file</VAR> argment is ignored.  (Note: using
  83. shared libraries is highly system dependent, and not all systems
  84. support it.)
  85. </DL>
  86. <DL><DT><B>load_source</B> (<VAR>name</VAR>, <VAR>pathname</VAR>, <VAR>file</VAR>) -- function of module imp<DD>
  87. Load and initialize a module implemented as a Python source file and
  88. return its module object.  If the module was already initialized, it
  89. will be initialized <I>again</I>.  The <VAR>name</VAR> argument is used to
  90. create or access a module object.  The <VAR>pathname</VAR> argument points
  91. to the source file.  The <VAR>file</VAR> argument is the source
  92. file, open for reading as text, from the beginning.
  93. It must currently be a real file
  94. object, not a user-defined class emulating a file.  Note that if a
  95. properly matching byte-compiled file (with suffix <CODE>.pyc</CODE>) exists,
  96. it will be used instead of parsing the given source file.
  97. </DL>
  98. <DL><DT><B>new_module</B> (<VAR>name</VAR>) -- function of module imp<DD>
  99. Return a new empty module object called <VAR>name</VAR>.  This object is
  100. <I>not</I> inserted in <CODE>sys.modules</CODE>.
  101. </DL>
  102. The following constants with integer values, defined in the module,
  103. are used to indicate the search result of <CODE>imp.find_module</CODE>.
  104. <P>
  105. <DL><DT><B>SEARCH_ERROR</B> -- data of module imp<DD>
  106. The module was not found.
  107. </DL>
  108. <DL><DT><B>PY_SOURCE</B> -- data of module imp<DD>
  109. The module was found as a source file.
  110. </DL>
  111. <DL><DT><B>PY_COMPILED</B> -- data of module imp<DD>
  112. The module was found as a compiled code object file.
  113. </DL>
  114. <DL><DT><B>C_EXTENSION</B> -- data of module imp<DD>
  115. The module was found as dynamically loadable shared library.
  116. </DL>
  117. <H2>Menu</H2><DL COMPACT>
  118. <DT><A HREF="../e/examples" TYPE=Menu>Examples</A>
  119. <DD></DL>
  120.