home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !ibrowse / files / pylibi-3 (.txt) < prev    next >
GNU Info File  |  1996-11-14  |  50KB  |  931 lines
  1. This is Info file pylibi, produced by Makeinfo-1.55 from the input file
  2. lib.texi.
  3. This file describes the built-in types, exceptions and functions and the
  4. standard modules that come with the Python system.  It assumes basic
  5. knowledge about the Python language.  For an informal introduction to
  6. the language, see the Python Tutorial.  The Python Reference Manual
  7. gives a more formal definition of the language.  (These manuals are not
  8. yet available in INFO or Texinfo format.)
  9. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The
  10. Netherlands.
  11. All Rights Reserved
  12. Permission to use, copy, modify, and distribute this software and its
  13. documentation for any purpose and without fee is hereby granted,
  14. provided that the above copyright notice appear in all copies and that
  15. both that copyright notice and this permission notice appear in
  16. supporting documentation, and that the names of Stichting Mathematisch
  17. Centrum or CWI or Corporation for National Research Initiatives or CNRI
  18. not be used in advertising or publicity pertaining to distribution of
  19. the software without specific, written prior permission.
  20. While CWI is the initial source for this software, a modified version
  21. is made available by the Corporation for National Research Initiatives
  22. (CNRI) at the Internet address ftp://ftp.python.org.
  23. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  24. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  25. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  26. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  27. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  28. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  29. ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  30. THIS SOFTWARE.
  31. File: pylibi,  Node: marshal,  Next: imp,  Prev: copy,  Up: Python Services
  32. Built-in Module `marshal'
  33. =========================
  34. This module contains functions that can read and write Python values in
  35. a binary format.  The format is specific to Python, but independent of
  36. machine architecture issues (e.g., you can write a Python value to a
  37. file on a PC, transport the file to a Sun, and read it back there).
  38. Details of the format are undocumented on purpose; it may change
  39. between Python versions (although it rarely does).(1)
  40. This is not a general "persistency" module.  For general persistency
  41. and transfer of Python objects through RPC calls, see the modules
  42. `pickle' and `shelve'.  The `marshal' module exists mainly to support
  43. reading and writing the "pseudo-compiled" code for Python modules of
  44. `.pyc' files.
  45. Not all Python object types are supported; in general, only objects
  46. whose value is independent from a particular invocation of Python can
  47. be written and read by this module.  The following types are supported:
  48. `None', integers, long integers, floating point numbers, strings,
  49. tuples, lists, dictionaries, and code objects, where it should be
  50. understood that tuples, lists and dictionaries are only supported as
  51. long as the values contained therein are themselves supported; and
  52. recursive lists and dictionaries should not be written (they will cause
  53. infinite loops).
  54. Caveat: On machines where C's `long int' type has more than 32 bits
  55. (such as the DEC Alpha), it is possible to create plain Python integers
  56. that are longer than 32 bits.  Since the current `marshal' module uses
  57. 32 bits to transfer plain Python integers, such values are silently
  58. truncated.  This particularly affects the use of very long integer
  59. literals in Python modules -- these will be accepted by the parser on
  60. such machines, but will be silently be truncated when the module is read
  61. from the `.pyc' instead.(2)
  62. There are functions that read/write files as well as functions
  63. operating on strings.
  64. The module defines these functions:
  65.  - function of module marshal: dump (VALUE, FILE)
  66.      Write the value on the open file.  The value must be a supported
  67.      type.  The file must be an open file object such as `sys.stdout'
  68.      or returned by `open()' or `posix.popen()'.
  69.      If the value has (or contains an object that has) an unsupported
  70.      type, a `ValueError' exception is raised - but garbage data will
  71.      also be written to the file.  The object will not be properly read
  72.      back by `load()'.
  73.  - function of module marshal: load (FILE)
  74.      Read one value from the open file and return it.  If no valid value
  75.      is read, raise `EOFError', `ValueError' or `TypeError'.  The file
  76.      must be an open file object.
  77.      Warning: If an object containing an unsupported type was marshalled
  78.      with `dump()', `load()' will substitute `None' for the
  79.      unmarshallable type.
  80.  - function of module marshal: dumps (VALUE)
  81.      Return the string that would be written to a file by `dump(value,
  82.      file)'.  The value must be a supported type.  Raise a `ValueError'
  83.      exception if value has (or contains an object that has) an
  84.      unsupported type.
  85.  - function of module marshal: loads (STRING)
  86.      Convert the string to a value.  If no valid value is found, raise
  87.      `EOFError', `ValueError' or `TypeError'.  Extra characters in the
  88.      string are ignored.
  89. ---------- Footnotes ----------
  90. (1)  The name of this module stems from a bit of terminology used by
  91. the designers of Modula-3 (amongst others), who use the term
  92. "marshalling" for shipping of data around in a self-contained form.
  93. Strictly speaking, "to marshal" means to convert some data from
  94. internal to external form (in an RPC buffer for instance) and
  95. "unmarshalling" for the reverse process.
  96. (2)  A solution would be to refuse such literals in the parser, since
  97. they are inherently non-portable.  Another solution would be to let the
  98. `marshal' module raise an exception when an integer value would be
  99. truncated.  At least one of these solutions will be implemented in a
  100. future version.
  101. File: pylibi,  Node: imp,  Next: __builtin__,  Prev: marshal,  Up: Python Services
  102. Built-in Module `imp'
  103. =====================
  104. This module provides an interface to the mechanisms used to implement
  105. the `import' statement.  It defines the following constants and
  106. functions:
  107.  - function of module imp: get_magic ()
  108.      Return the magic string value used to recognize byte-compiled code
  109.      files ("`.pyc' files").
  110.  - function of module imp: get_suffixes ()
  111.      Return a list of triples, each describing a particular type of
  112.      file.  Each triple has the form `(SUFFIX, MODE, TYPE)', where
  113.      SUFFIX is a string to be appended to the module name to form the
  114.      filename to search for, MODE is the mode string to pass to the
  115.      built-in `open' function to open the file (this can be `'r'' for
  116.      text files or `'rb'' for binary files), and TYPE is the file type,
  117.      which has one of the values `PY_SOURCE', `PY_COMPILED' or
  118.      `C_EXTENSION', defined below.  (System-dependent values may also
  119.      be returned.)
  120.  - function of module imp: find_module (NAME, [PATH])
  121.      Try to find the module NAME on the search path PATH.  The default
  122.      PATH is `sys.path'.  The return value is a triple `(FILE,
  123.      PATHNAME, DESCRIPTION)' where FILE is an open file object
  124.      positioned at the beginning, PATHNAME is the pathname of the file
  125.      found, and DESCRIPTION is a triple as contained in the list
  126.      returned by `get_suffixes' describing the kind of file found.
  127.  - function of module imp: init_builtin (NAME)
  128.      Initialize the built-in module called NAME and return its module
  129.      object.  If the module was already initialized, it will be
  130.      initialized *again*.  A few modules cannot be initialized twice --
  131.      attempting to initialize these again will raise an `ImportError'
  132.      exception.  If there is no built-in module called NAME, `None' is
  133.      returned.
  134.  - function of module imp: init_frozen (NAME)
  135.      Initialize the frozen module called NAME and return its module
  136.      object.  If the module was already initialized, it will be
  137.      initialized *again*.  If there is no frozen module called NAME,
  138.      `None' is returned.  (Frozen modules are modules written in Python
  139.      whose compiled byte-code object is incorporated into a
  140.      custom-built Python interpreter by Python's `freeze' utilit