home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !ibrowse / files / pylibi-3 < prev    next >
Encoding:
GNU Info File  |  1996-11-14  |  48.8 KB  |  1,252 lines
  1. This is Info file pylibi, produced by Makeinfo-1.55 from the input file
  2. lib.texi.
  3.  
  4. This file describes the built-in types, exceptions and functions and the
  5. standard modules that come with the Python system.  It assumes basic
  6. knowledge about the Python language.  For an informal introduction to
  7. the language, see the Python Tutorial.  The Python Reference Manual
  8. gives a more formal definition of the language.  (These manuals are not
  9. yet available in INFO or Texinfo format.)
  10.  
  11. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The
  12. Netherlands.
  13.  
  14. All Rights Reserved
  15.  
  16. Permission to use, copy, modify, and distribute this software and its
  17. documentation for any purpose and without fee is hereby granted,
  18. provided that the above copyright notice appear in all copies and that
  19. both that copyright notice and this permission notice appear in
  20. supporting documentation, and that the names of Stichting Mathematisch
  21. Centrum or CWI or Corporation for National Research Initiatives or CNRI
  22. not be used in advertising or publicity pertaining to distribution of
  23. the software without specific, written prior permission.
  24.  
  25. While CWI is the initial source for this software, a modified version
  26. is made available by the Corporation for National Research Initiatives
  27. (CNRI) at the Internet address ftp://ftp.python.org.
  28.  
  29. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  30. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  31. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  32. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  33. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  34. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  35. ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  36. THIS SOFTWARE.
  37.  
  38. 
  39. File: pylibi,  Node: marshal,  Next: imp,  Prev: copy,  Up: Python Services
  40.  
  41. Built-in Module `marshal'
  42. =========================
  43.  
  44. This module contains functions that can read and write Python values in
  45. a binary format.  The format is specific to Python, but independent of
  46. machine architecture issues (e.g., you can write a Python value to a
  47. file on a PC, transport the file to a Sun, and read it back there).
  48. Details of the format are undocumented on purpose; it may change
  49. between Python versions (although it rarely does).(1)
  50.  
  51. This is not a general "persistency" module.  For general persistency
  52. and transfer of Python objects through RPC calls, see the modules
  53. `pickle' and `shelve'.  The `marshal' module exists mainly to support
  54. reading and writing the "pseudo-compiled" code for Python modules of
  55. `.pyc' files.
  56.  
  57. Not all Python object types are supported; in general, only objects
  58. whose value is independent from a particular invocation of Python can
  59. be written and read by this module.  The following types are supported:
  60. `None', integers, long integers, floating point numbers, strings,
  61. tuples, lists, dictionaries, and code objects, where it should be
  62. understood that tuples, lists and dictionaries are only supported as
  63. long as the values contained therein are themselves supported; and
  64. recursive lists and dictionaries should not be written (they will cause
  65. infinite loops).
  66.  
  67. Caveat: On machines where C's `long int' type has more than 32 bits
  68. (such as the DEC Alpha), it is possible to create plain Python integers
  69. that are longer than 32 bits.  Since the current `marshal' module uses
  70. 32 bits to transfer plain Python integers, such values are silently
  71. truncated.  This particularly affects the use of very long integer
  72. literals in Python modules -- these will be accepted by the parser on
  73. such machines, but will be silently be truncated when the module is read
  74. from the `.pyc' instead.(2)
  75.  
  76. There are functions that read/write files as well as functions
  77. operating on strings.
  78.  
  79. The module defines these functions:
  80.  
  81.  - function of module marshal: dump (VALUE, FILE)
  82.      Write the value on the open file.  The value must be a supported
  83.      type.  The file must be an open file object such as `sys.stdout'
  84.      or returned by `open()' or `posix.popen()'.
  85.  
  86.      If the value has (or contains an object that has) an unsupported
  87.      type, a `ValueError' exception is raised - but garbage data will
  88.      also be written to the file.  The object will not be properly read
  89.      back by `load()'.
  90.  
  91.  - function of module marshal: load (FILE)
  92.      Read one value from the open file and return it.  If no valid value
  93.      is read, raise `EOFError', `ValueError' or `TypeError'.  The file
  94.      must be an open file object.
  95.  
  96.      Warning: If an object containing an unsupported type was marshalled
  97.      with `dump()', `load()' will substitute `None' for the
  98.      unmarshallable type.
  99.  
  100.  - function of module marshal: dumps (VALUE)
  101.      Return the string that would be written to a file by `dump(value,
  102.      file)'.  The value must be a supported type.  Raise a `ValueError'
  103.      exception if value has (or contains an object that has) an
  104.      unsupported type.
  105.  
  106.  - function of module marshal: loads (STRING)
  107.      Convert the string to a value.  If no valid value is found, raise
  108.      `EOFError', `ValueError' or `TypeError'.  Extra characters in the
  109.      string are ignored.
  110.  
  111. ---------- Footnotes ----------
  112.  
  113. (1)  The name of this module stems from a bit of terminology used by
  114. the designers of Modula-3 (amongst others), who use the term
  115. "marshalling" for shipping of data around in a self-contained form.
  116. Strictly speaking, "to marshal" means to convert some data from
  117. internal to external form (in an RPC buffer for instance) and
  118. "unmarshalling" for the reverse process.
  119.  
  120. (2)  A solution would be to refuse such literals in the parser, since
  121. they are inherently non-portable.  Another solution would be to let the
  122. `marshal' module raise an exception when an integer value would be
  123. truncated.  At least one of these solutions will be implemented in a
  124. future version.
  125.  
  126. 
  127. File: pylibi,  Node: imp,  Next: __builtin__,  Prev: marshal,  Up: Python Services
  128.  
  129. Built-in Module `imp'
  130. =====================
  131.  
  132. This module provides an interface to the mechanisms used to implement
  133. the `import' statement.  It defines the following constants and
  134. functions:
  135.  
  136.  - function of module imp: get_magic ()
  137.      Return the magic string value used to recognize byte-compiled code
  138.      files ("`.pyc' files").
  139.  
  140.  - function of module imp: get_suffixes ()
  141.      Return a list of triples, each describing a particular type of
  142.      file.  Each triple has the form `(SUFFIX, MODE, TYPE)', where
  143.      SUFFIX is a string to be appended to the module name to form the
  144.      filename to search for, MODE is the mode string to pass to the
  145.      built-in `open' function to open the file (this can be `'r'' for
  146.      text files or `'rb'' for binary files), and TYPE is the file type,
  147.      which has one of the values `PY_SOURCE', `PY_COMPILED' or
  148.      `C_EXTENSION', defined below.  (System-dependent values may also
  149.      be returned.)
  150.  
  151.  - function of module imp: find_module (NAME, [PATH])
  152.      Try to find the module NAME on the search path PATH.  The default
  153.      PATH is `sys.path'.  The return value is a triple `(FILE,
  154.      PATHNAME, DESCRIPTION)' where FILE is an open file object
  155.      positioned at the beginning, PATHNAME is the pathname of the file
  156.      found, and DESCRIPTION is a triple as contained in the list
  157.      returned by `get_suffixes' describing the kind of file found.
  158.  
  159.  - function of module imp: init_builtin (NAME)
  160.      Initialize the built-in module called NAME and return its module
  161.      object.  If the module was already initialized, it will be
  162.      initialized *again*.  A few modules cannot be initialized twice --
  163.      attempting to initialize these again will raise an `ImportError'
  164.      exception.  If there is no built-in module called NAME, `None' is
  165.      returned.
  166.  
  167.  - function of module imp: init_frozen (NAME)
  168.      Initialize the frozen module called NAME and return its module
  169.      object.  If the module was already initialized, it will be
  170.      initialized *again*.  If there is no frozen module called NAME,
  171.      `None' is returned.  (Frozen modules are modules written in Python
  172.      whose compiled byte-code object is incorporated into a
  173.      custom-built Python interpreter by Python's `freeze' utility.  See
  174.      `Tools/freeze' for now.)
  175.  
  176.  - function of module imp: is_builtin (NAME)
  177.      Return `1' if there is a built-in module called NAME which can be
  178.      initialized again.  Return `-1' if there is a built-in module
  179.      called NAME which cannot be initialized again (see
  180.      `init_builtin').  Return `0' if there is no built-in module called
  181.      NAME.
  182.  
  183.  - function of module imp: is_frozen (NAME)
  184.      Return `1' if there is a frozen module (see `init_frozen') called
  185.      NAME, `0' if there is no such module.
  186.  
  187.  - function of module imp: load_compiled (NAME, PATHNAME, FILE)
  188.      Load and initialize a module implemented as a byte-compiled code
  189.      file and return its module object.  If the module was already
  190.      initialized, it will be initialized *again*.  The NAME argument is
  191.      used to create or access a module object.  The PATHNAME argument
  192.      points to the byte-compiled code file.  The FILE argument is the
  193.      byte-compiled code file, open for reading in binary mode, from the
  194.      beginning.  It must currently be a real file object, not a
  195.      user-defined class emulating a file.
  196.  
  197.  - function of module imp: load_dynamic (NAME, PATHNAME, [FILE])
  198.      Load and initialize a module implemented as a dynamically loadable
  199.      shared library and return its module object.  If the module was
  200.      already initialized, it will be initialized *again*.  Some modules
  201.      don't like that and may raise an exception.  The PATHNAME argument
  202.      must point to the shared library.  The NAME argument is used to
  203.      construct the name of the initialization function: an external C
  204.      function called `initNAME()' in the shared library is called.  The
  205.      optional FILE argment is ignored.  (Note: using shared libraries
  206.      is highly system dependent, and not all systems support it.)
  207.  
  208.  - function of module imp: load_source (NAME, PATHNAME, FILE)
  209.      Load and initialize a module implemented as a Python source file
  210.      and return its module object.  If the module was already
  211.      initialized, it will be initialized *again*.  The NAME argument is
  212.      used to create or access a module object.  The PATHNAME argument
  213.      points to the source file.  The FILE argument is the source file,
  214.      open for reading as text, from the beginning.  It must currently
  215.      be a real file object, not a user-defined class emulating a file.
  216.      Note that if a properly matching byte-compiled file (with suffix
  217.      `.pyc') exists, it will be used instead of parsing the given
  218.      source file.
  219.  
  220.  - function of module imp: new_module (NAME)
  221.      Return a new empty module object called NAME.  This object is
  222.      *not* inserted in `sys.modules'.
  223.  
  224. The following constants with integer values, defined in the module, are
  225. used to indicate the search result of `imp.find_module'.
  226.  
  227.  - data of module imp: SEARCH_ERROR
  228.      The module was not found.
  229.  
  230.  - data of module imp: PY_SOURCE
  231.      The module was found as a source file.
  232.  
  233.  - data of module imp: PY_COMPILED
  234.      The module was found as a compiled code object file.
  235.  
  236.  - data of module imp: C_EXTENSION
  237.      The module was found as dynamically loadable shared library.
  238.  
  239. * Menu:
  240.  
  241. * Examples::
  242.  
  243. 
  244. File: pylibi,  Node: Examples,  Prev: imp,  Up: imp
  245.  
  246. Examples
  247. --------
  248.  
  249. The following function emulates the default import statement:
  250.  
  251.      import imp
  252.      import sys
  253.      
  254.      def __import__(name, globals=None, locals=None, fromlist=None):
  255.          # Fast path: see if the module has already been imported.
  256.          if sys.modules.has_key(name):
  257.              return sys.modules[name]
  258.      
  259.          # If any of the following calls raises an exception,
  260.          # there's a problem we can't handle -- let the caller handle it.
  261.      
  262.          # See if it's a built-in module.
  263.          m = imp.init_builtin(name)
  264.          if m:
  265.              return m
  266.      
  267.          # See if it's a frozen module.
  268.          m = imp.init_frozen(name)
  269.          if m:
  270.              return m
  271.      
  272.          # Search the default path (i.e. sys.path).
  273.          fp, pathname, (suffix, mode, type) = imp.find_module(name)
  274.      
  275.          # See what we got.
  276.          try:
  277.              if type == imp.C_EXTENSION:
  278.                  return imp.load_dynamic(name, pathname)
  279.              if type == imp.PY_SOURCE:
  280.                  return imp.load_source(name, pathname, fp)
  281.              if type == imp.PY_COMPILED:
  282.                  return imp.load_compiled(name, pathname, fp)
  283.      
  284.              # Shouldn't get here at all.
  285.              raise ImportError, '%s: unknown module type (%d)' % (name, type)
  286.          finally:
  287.              # Since we may exit via an exception, close fp explicitly.
  288.              fp.close()
  289.  
  290. 
  291. File: pylibi,  Node: __builtin__,  Next: __main__,  Prev: imp,  Up: Python Services
  292.  
  293. Built-in Module `__builtin__'
  294. =============================
  295.  
  296. This module provides direct access to all `built-in' identifiers of
  297. Python; e.g. `__builtin__.open' is the full name for the built-in
  298. function `open'.  See the section on Built-in Functions in the previous
  299. chapter.
  300.  
  301. 
  302. File: pylibi,  Node: __main__,  Prev: __builtin__,  Up: Python Services
  303.  
  304. Built-in Module `__main__'
  305. ==========================
  306.  
  307. This module represents the (otherwise anonymous) scope in which the
  308. interpreter's main program executes -- commands read either from
  309. standard input or from a script file.
  310.  
  311. 
  312. File: pylibi,  Node: String Services,  Next: Miscellaneous Services,  Prev: Python Services,  Up: Top
  313.  
  314. String Services
  315. ***************
  316.  
  317. The modules described in this chapter provide a wide range of string
  318. manipulation operations.  Here's an overview:
  319.  
  320. string
  321.      -- Common string operations.
  322.  
  323. regex
  324.      -- Regular expression search and match operations.
  325.  
  326. regsub
  327.      -- Substitution and splitting operations that use regular
  328.      expressions.
  329.  
  330. struct
  331.      -- Interpret strings as packed binary data.
  332.  
  333. * Menu:
  334.  
  335. * string::
  336. * regex::
  337. * regsub::
  338. * struct::
  339.  
  340. 
  341. File: pylibi,  Node: string,  Next: regex,  Prev: String Services,  Up: String Services
  342.  
  343. Standard Module `string'
  344. ========================
  345.  
  346. This module defines some constants useful for checking character
  347. classes and some useful string functions.  See the modules `regex' and
  348. `regsub' for string functions based on regular expressions.
  349.  
  350. The constants defined in this module are are:
  351.  
  352.  - data of module string: digits
  353.      The string `'0123456789''.
  354.  
  355.  - data of module string: hexdigits
  356.      The string `'0123456789abcdefABCDEF''.
  357.  
  358.  - data of module string: letters
  359.      The concatenation of the strings `lowercase' and `uppercase'
  360.      described below.
  361.  
  362.  - data of module string: lowercase
  363.      A string containing all the characters that are considered
  364.      lowercase letters.  On most systems this is the string
  365.      `'abcdefghijklmnopqrstuvwxyz''.  Do not change its definition --
  366.      the effect on the routines `upper' and `swapcase' is undefined.
  367.  
  368.  - data of module string: octdigits
  369.      The string `'01234567''.
  370.  
  371.  - data of module string: uppercase
  372.      A string containing all the characters that are considered
  373.      uppercase letters.  On most systems this is the string
  374.      `'ABCDEFGHIJKLMNOPQRSTUVWXYZ''.  Do not change its definition --
  375.      the effect on the routines `lower' and `swapcase' is undefined.
  376.  
  377.  - data of module string: whitespace
  378.      A string containing all characters that are considered whitespace.
  379.      On most systems this includes the characters space, tab, linefeed,
  380.      return, formfeed, and vertical tab.  Do not change its definition
  381.      -- the effect on the routines `strip' and `split' is undefined.
  382.  
  383. The functions defined in this module are:
  384.  
  385.  - function of module string: atof (S)
  386.      Convert a string to a floating point number.  The string must have
  387.      the standard syntax for a floating point literal in Python,
  388.      optionally preceded by a sign (`+' or `-').
  389.  
  390.  - function of module string: atoi (S[, BASE])
  391.      Convert string S to an integer in the given BASE.  The string must
  392.      consist of one or more digits, optionally preceded by a sign (`+'
  393.      or `-').  The BASE defaults to 10.  If it is 0, a default base is
  394.      chosen depending on the leading characters of the string (after
  395.      stripping the sign): `0x' or `0X' means 16, `0' means 8, anything
  396.      else means 10.  If BASE is 16, a leading `0x' or `0X' is always
  397.      accepted.  (Note: for a more flexible interpretation of numeric
  398.      literals, use the built-in function `eval()'.)
  399.  
  400.  - function of module string: atol (S[, BASE])
  401.      Convert string S to a long integer in the given BASE.  The string
  402.      must consist of one or more digits, optionally preceded by a sign
  403.      (`+' or `-').  The BASE argument has the same meaning as for
  404.      `atoi()'.  A trailing `l' or `L' is not allowed, except if the
  405.      base is 0.
  406.  
  407.  - function of module string: capitalize (WORD)
  408.      Capitalize the first character of the argument.
  409.  
  410.  - function of module string: capwords (S)
  411.      Split the argument into words using `split', capitalize each word
  412.      using `capitalize', and join the capitalized words using `join'.
  413.      Note that this replaces runs of whitespace characters by a single
  414.      space.  (See also `regsub.capwords()' for a version that doesn't
  415.      change the delimiters, and lets you specify a word separator.)
  416.  
  417.  - function of module string: expandtabs (S, TABSIZE)
  418.      Expand tabs in a string, i.e. replace them by one or more spaces,
  419.      depending on the current column and the given tab size.  The column
  420.      number is reset to zero after each newline occurring in the string.
  421.      This doesn't understand other non-printing characters or escape
  422.      sequences.
  423.  
  424.  - function of module string: find (S, SUB[, START])
  425.      Return the lowest index in S not smaller than START where the
  426.      substring SUB is found.  Return `-1' when SUB does not occur as a
  427.      substring of S with index at least START.  If START is omitted, it
  428.      defaults to `0'.  If START is negative, `len(S)' is added.
  429.  
  430.  - function of module string: rfind (S, SUB[, START])
  431.      Like `find' but find the highest index.
  432.  
  433.  - function of module string: index (S, SUB[, START])
  434.      Like `find' but raise `ValueError' when the substring is not found.
  435.  
  436.  - function of module string: rindex (S, SUB[, START])
  437.      Like `rfind' but raise `ValueError' when the substring is not
  438.      found.
  439.  
  440.  - function of module string: count (S, SUB[, START])
  441.      Return the number of (non-overlapping) occurrences of substring
  442.      SUB in string S with index at least START.  If START is omitted,
  443.      it defaults to `0'.  If START is negative, `len(S)' is added.
  444.  
  445.  - function of module string: lower (S)
  446.      Convert letters to lower case.
  447.  
  448.  - function of module string: maketrans (FROM, TO)
  449.      Return a translation table suitable for passing to
  450.      `string.translate' or `regex.compile', that will map each
  451.      character in FROM into the character at the same position in TO;
  452.      FROM and TO must have the same length.
  453.  
  454.  - function of module string: split (S[, SEP[, MAXSPLIT]])
  455.      Return a list of the words of the string S.  If the optional
  456.      second argument SEP is absent or `None', the words are separated
  457.      by arbitrary strings of whitespace characters (space, tab,
  458.      newline, return, formfeed).  If the second argument SEP is present
  459.      and not `None', it specifies a string to be used as the word
  460.      separator.  The returned list will then have one more items than
  461.      the number of non-overlapping occurrences of the separator in the
  462.      string.  The optional third argument MAXSPLIT defaults to 0.  If
  463.      it is nonzero, at most MAXSPLIT number of splits occur, and the
  464.      remainder of the string is returned as the final element of the
  465.      list (thus, the list will have at most `MAXSPLIT+1' elements).
  466.      (See also `regsub.split()' for a version that allows specifying a
  467.      regular expression as the separator.)
  468.  
  469.  - function of module string: splitfields (S[, SEP[, MAXSPLIT]])
  470.      This function behaves identical to `split'.  (In the past, `split'
  471.      was only used with one argument, while `splitfields' was only used
  472.      with two arguments.)
  473.  
  474.  - function of module string: join (WORDS[, SEP])
  475.      Concatenate a list or tuple of words with intervening occurrences
  476.      of SEP.  The default value for SEP is a single space character.
  477.      It is always true that `string.join(string.split(S, SEP), SEP)'
  478.      equals S.
  479.  
  480.  - function of module string: joinfields (WORDS[, SEP])
  481.      This function behaves identical to `join'.  (In the past, `join'
  482.      was only used with one argument, while `joinfields' was only used
  483.      with two arguments.)
  484.  
  485.  - function of module string: lstrip (S)
  486.      Remove leading whitespace from the string S.
  487.  
  488.  - function of module string: rstrip (S)
  489.      Remove trailing whitespace from the string S.
  490.  
  491.  - function of module string: strip (S)
  492.      Remove leading and trailing whitespace from the string S.
  493.  
  494.  - function of module string: swapcase (S)
  495.      Convert lower case letters to upper case and vice versa.
  496.  
  497.  - function of module string: translate (S, TABLE[, DELETECHARS])
  498.      Delete all characters from S that are in DELETECHARS (if present),
  499.      and then translate the characters using TABLE, which must be a
  500.      256-character string giving the translation for each character
  501.      value, indexed by its ordinal.
  502.  
  503.  - function of module string: upper (S)
  504.      Convert letters to upper case.
  505.  
  506.  - function of module string: ljust (S, WIDTH)
  507.  
  508.  - function of module string: rjust (S, WIDTH)
  509.  
  510.  - function of module string: center (S, WIDTH)
  511.      These functions respectively left-justify, right-justify and
  512.      center a string in a field of given width.  They return a string
  513.      that is at least WIDTH characters wide, created by padding the
  514.      string S with spaces until the given width on the right, left or
  515.      both sides.  The string is never truncated.
  516.  
  517.  - function of module string: zfill (S, WIDTH)
  518.      Pad a numeric string on the left with zero digits until the given
  519.      width is reached.  Strings starting with a sign are handled
  520.      correctly.
  521.  
  522. This module is implemented in Python.  Much of its functionality has
  523. been reimplemented in the built-in module `strop'.  However, you should
  524. *never* import the latter module directly.  When `string' discovers
  525. that `strop' exists, it transparently replaces parts of itself with the
  526. implementation from `strop'.  After initialization, there is *no*
  527. overhead in using `string' instead of `strop'.
  528.  
  529. 
  530. File: pylibi,  Node: regex,  Next: regsub,  Prev: string,  Up: String Services
  531.  
  532. Built-in Module `regex'
  533. =======================
  534.  
  535. This module provides regular expression matching operations similar to
  536. those found in Emacs.  It is always available.
  537.  
  538. By default the patterns are Emacs-style regular expressions (with one
  539. exception).  There is a way to change the syntax to match that of
  540. several well-known UNIX utilities.  The exception is that Emacs' `\s'
  541. pattern is not supported, since the original implementation references
  542. the Emacs syntax tables.
  543.  
  544. This module is 8-bit clean: both patterns and strings may contain null
  545. bytes and characters whose high bit is set.
  546.  
  547. *Please note:* There is a little-known fact about Python string
  548. literals which means that you don't usually have to worry about
  549. doubling backslashes, even though they are used to escape special
  550. characters in string literals as well as in regular expressions.  This
  551. is because Python doesn't remove backslashes from string literals if
  552. they are followed by an unrecognized escape character.  *However*, if
  553. you want to include a literal "backslash" in a regular expression
  554. represented as a string literal, you have to *quadruple* it.  E.g.  to
  555. extract LaTeX `\section{...}' headers from a document, you can use this
  556. pattern: `'\\\\section{\(.*\)}''.  *Another exception:* the escape
  557. sequece `\b' is significant in string literals (where it means the
  558. ASCII bell character) as well as in Emacs regular expressions (where it
  559. stands for a word boundary), so in order to search for a word boundary,
  560. you should use the pattern `'\\b''.  Similarly, a backslash followed by
  561. a digit 0-7 should be doubled to avoid interpretation as an octal
  562. escape.
  563.  
  564. * Menu:
  565.  
  566. * Regular Expressions::
  567. * Module Contents::
  568.  
  569. 
  570. File: pylibi,  Node: Regular Expressions,  Next: Module Contents,  Prev: regex,  Up: regex
  571.  
  572. Regular Expressions
  573. -------------------
  574.  
  575. A regular expression (or RE) specifies a set of strings that matches
  576. it; the functions in this module let you check if a particular string
  577. matches a given regular expression (or if a given regular expression
  578. matches a particular string, which comes down to the same thing).
  579.  
  580. Regular expressions can be concatenated to form new regular
  581. expressions; if *A* and *B* are both regular expressions, then *AB* is
  582. also an regular expression.  If a string *p* matches A and another
  583. string *q* matches B, the string *pq* will match AB.  Thus, complex
  584. expressions can easily be constructed from simpler ones like the
  585. primitives described here.  For details of the theory and
  586. implementation of regular expressions, consult almost any textbook
  587. about compiler construction.
  588.  
  589. A brief explanation of the format of regular expressions follows.
  590.  
  591. Regular expressions can contain both special and ordinary characters.
  592. Ordinary characters, like '`A'', '`a'', or '`0'', are the simplest
  593. regular expressions; they simply match themselves.  You can concatenate
  594. ordinary characters, so '`last'' matches the characters 'last'.  (In
  595. the rest of this section, we'll write RE's in `this special font',
  596. usually without quotes, and strings to be matched 'in single quotes'.)
  597.  
  598. Special characters either stand for classes of ordinary characters, or
  599. affect how the regular expressions around them are interpreted.
  600.  
  601. The special characters are:
  602.    * `.' (Dot.)  Matches any character except a newline.
  603.  
  604.    * `' (Caret.)  Matches the start of the string.
  605.  
  606.    * `' Matches the end of the string.  `foo' matches both 'foo' and
  607.      'foobar', while the regular expression '`foo$'' matches only 'foo'.
  608.  
  609.    * `*' Causes the resulting RE to match 0 or more repetitions of the
  610.      preceding RE.  `ab*' will match 'a', 'ab', or 'a' followed by any
  611.      number of 'b's.
  612.  
  613.    * `+' Causes the resulting RE to match 1 or more repetitions of the
  614.      preceding RE.  `ab+' will match 'a' followed by any non-zero
  615.      number of 'b's; it will not match just 'a'.
  616.  
  617.    * `?' Causes the resulting RE to match 0 or 1 repetitions of the
  618.      preceding RE.  `ab?' will match either 'a' or 'ab'.
  619.  
  620.    * `' Either escapes special characters (permitting you to match
  621.      characters like '*?+&$'), or signals a special sequence; special
  622.      sequences are discussed below.  Remember that Python also uses the
  623.      backslash as an escape sequence in string literals; if the escape
  624.      sequence isn't recognized by Python's parser, the backslash and
  625.      subsequent character are included in the resulting string.
  626.      However, if Python would recognize the resulting sequence, the
  627.      backslash should be repeated twice.
  628.  
  629.    * `[]' Used to indicate a set of characters.  Characters can be
  630.      listed individually, or a range is indicated by giving two
  631.      characters and separating them by a '-'.  Special characters are
  632.      not active inside sets.  For example, `[akm$]' will match any of
  633.      the characters 'a', 'k', 'm', or '$'; `[a-z]' will match any
  634.      lowercase letter.
  635.  
  636.      If you want to include a `]' inside a set, it must be the first
  637.      character of the set; to include a `-', place it as the first or
  638.      last character.
  639.  
  640.      Characters *not* within a range can be matched by including a `^'
  641.      as the first character of the set; `^' elsewhere will simply match
  642.      the '`^'' character.
  643.  
  644. The special sequences consist of '`\'' and a character from the list
  645. below.  If the ordinary character is not on the list, then the
  646. resulting RE will match the second character.  For example, `\$'
  647. matches the character '$'.  Ones where the backslash should be doubled
  648. are indicated.
  649.  
  650.    * ` |' `A\|B', where A and B can be arbitrary REs, creates a regular
  651.      expression that will match either A or B.  This can be used inside
  652.      groups (see below) as well.
  653.  
  654.    * ` (  )' Indicates the start and end of a group; the contents of a
  655.      group can be matched later in the string with the `\' special
  656.      sequence, described next.
  657.  
  658.    * ` 1, ...  7,  8,  9' Matches the contents of the group of the same
  659.      number.  For example, `\(.+\) \\1' matches 'the the' or '55 55',
  660.      but not 'the end' (note the space after the group).  This special
  661.      sequence can only be used to match one of the first 9 groups;
  662.      groups with higher numbers can be matched using the `\v' sequence.
  663.      (`\8' and `\9' don't need a double backslash because they are not
  664.      octal digits.)
  665.  
  666.    * ` b' Matches the empty string, but only at the beginning or end of
  667.      a word.  A word is defined as a sequence of alphanumeric
  668.      characters, so the end of a word is indicated by whitespace or a
  669.      non-alphanumeric character.
  670.  
  671.    * ` B' Matches the empty string, but when it is *not* at the
  672.      beginning or end of a word.
  673.  
  674.    * ` v' Must be followed by a two digit decimal number, and matches
  675.      the contents of the group of the same number.  The group number
  676.      must be between 1 and 99, inclusive.
  677.  
  678.    * ` w' Matches any alphanumeric character; this is equivalent to the
  679.      set `[a-zA-Z0-9]'.
  680.  
  681.    * ` W' Matches any non-alphanumeric character; this is equivalent to
  682.      the set `[^a-zA-Z0-9]'.
  683.  
  684.    * ` <' Matches the empty string, but only at the beginning of a
  685.      word.  A word is defined as a sequence of alphanumeric characters,
  686.      so the end of a word is indicated by whitespace or a
  687.      non-alphanumeric character.
  688.  
  689.    * ` >' Matches the empty string, but only at the end of a word.
  690.  
  691.    * `' Matches a literal backslash.
  692.  
  693.    * ` `' Like `^', this only matches at the start of the string.
  694.  
  695.    * ` '' Like `$', this only matches at the end of the string.
  696.  
  697. 
  698. File: pylibi,  Node: Module Contents,  Prev: Regular Expressions,  Up: regex
  699.  
  700. Module Contents
  701. ---------------
  702.  
  703. The module defines these functions, and an exception:
  704.  
  705.  - function of module regex: match (PATTERN, STRING)
  706.      Return how many characters at the beginning of STRING match the
  707.      regular expression PATTERN.  Return `-1' if the string does not
  708.      match the pattern (this is different from a zero-length match!).
  709.  
  710.  - function of module regex: search (PATTERN, STRING)
  711.      Return the first position in STRING that matches the regular
  712.      expression PATTERN.  Return `-1' if no position in the string
  713.      matches the pattern (this is different from a zero-length match
  714.      anywhere!).
  715.  
  716.  - function of module regex: compile (PATTERN[, TRANSLATE])
  717.      Compile a regular expression pattern into a regular expression
  718.      object, which can be used for matching using its `match' and
  719.      `search' methods, described below.  The optional argument
  720.      TRANSLATE, if present, must be a 256-character string indicating
  721.      how characters (both of the pattern and of the strings to be
  722.      matched) are translated before comparing them; the `i'-th element
  723.      of the string gives the translation for the character with ASCII
  724.      code `i'.  This can be used to implement case-insensitive
  725.      matching; see the `casefold' data item below.
  726.  
  727.      The sequence
  728.  
  729.           prog = regex.compile(pat)
  730.           result = prog.match(str)
  731.      is equivalent to
  732.  
  733.           result = regex.match(pat, str)
  734.      but the version using `compile()' is more efficient when multiple
  735.      regular expressions are used concurrently in a single program.
  736.      (The compiled version of the last pattern passed to
  737.      `regex.match()' or `regex.search()' is cached, so programs that
  738.      use only a single regular expression at a time needn't worry about
  739.      compiling regular expressions.)
  740.  
  741.  - function of module regex: set_syntax (FLAGS)
  742.      Set the syntax to be used by future calls to `compile', `match'
  743.      and `search'.  (Already compiled expression objects are not
  744.      affected.)  The argument is an integer which is the OR of several
  745.      flag bits.  The return value is the previous value of the syntax
  746.      flags.  Names for the flags are defined in the standard module
  747.      `regex_syntax'; read the file `regex_syntax.py' for more
  748.      information.
  749.  
  750.  - function of module regex: symcomp (PATTERN[, TRANSLATE])
  751.      This is like `compile', but supports symbolic group names: if a
  752.      parenthesis-enclosed group begins with a group name in angular
  753.      brackets, e.g. `'\(<id>[a-z][a-z0-9]*\)'', the group can be
  754.      referenced by its name in arguments to the `group' method of the
  755.      resulting compiled regular expression object, like this:
  756.      `p.group('id')'.  Group names may contain alphanumeric characters
  757.      and `'_'' only.
  758.  
  759.  - exception of module regex: error
  760.      Exception raised when a string passed to one of the functions here
  761.      is not a valid regular expression (e.g., unmatched parentheses) or
  762.      when some other error occurs during compilation or matching.  (It
  763.      is never an error if a string contains no match for a pattern.)
  764.  
  765.  - data of module regex: casefold
  766.      A string suitable to pass as TRANSLATE argument to `compile' to
  767.      map all upper case characters to their lowercase equivalents.
  768.  
  769. Compiled regular expression objects support these methods:
  770.  
  771.  - Method on regex: match (STRING[, POS])
  772.      Return how many characters at the beginning of STRING match the
  773.      compiled regular expression.  Return `-1' if the string does not
  774.      match the pattern (this is different from a zero-length match!).
  775.  
  776.      The optional second parameter POS gives an index in the string
  777.      where the search is to start; it defaults to `0'.  This is not
  778.      completely equivalent to slicing the string; the `'^'' pattern
  779.      character matches at the real begin of the string and at positions
  780.      just after a newline, not necessarily at the index where the search
  781.      is to start.
  782.  
  783.  - Method on regex: search (STRING[, POS])
  784.      Return the first position in STRING that matches the regular
  785.      expression `pattern'.  Return `-1' if no position in the string
  786.      matches the pattern (this is different from a zero-length match
  787.      anywhere!).
  788.  
  789.      The optional second parameter has the same meaning as for the
  790.      `match' method.
  791.  
  792.  - Method on regex: group (INDEX, INDEX, ...)
  793.      This method is only valid when the last call to the `match' or
  794.      `search' method found a match.  It returns one or more groups of
  795.      the match.  If there is a single INDEX argument, the result is a
  796.      single string; if there are multiple arguments, the result is a
  797.      tuple with one item per argument.  If the INDEX is zero, the
  798.      corresponding return value is the entire matching string; if it is
  799.      in the inclusive range [1..99], it is the string matching the the
  800.      corresponding parenthesized group (using the default syntax,
  801.      groups are parenthesized using `
  802.      (' and `
  803.      )').  If no such group exists, the corresponding result is `None'.
  804.  
  805.      If the regular expression was compiled by `symcomp' instead of
  806.      `compile', the INDEX arguments may also be strings identifying
  807.      groups by their group name.
  808.  
  809. Compiled regular expressions support these data attributes:
  810.  
  811.  - attribute of regex: regs
  812.      When the last call to the `match' or `search' method found a
  813.      match, this is a tuple of pairs of indices corresponding to the
  814.      beginning and end of all parenthesized groups in the pattern.
  815.      Indices are relative to the string argument passed to `match' or
  816.      `search'.  The 0-th tuple gives the beginning and end or the whole
  817.      pattern.  When the last match or search failed, this is `None'.
  818.  
  819.  - attribute of regex: last
  820.      When the last call to the `match' or `search' method found a
  821.      match, this is the string argument passed to that method.  When the
  822.      last match or search failed, this is `None'.
  823.  
  824.  - attribute of regex: translate
  825.      This is the value of the TRANSLATE argument to `regex.compile'
  826.      that created this regular expression object.  If the TRANSLATE
  827.      argument was omitted in the `regex.compile' call, this is `None'.
  828.  
  829.  - attribute of regex: givenpat
  830.      The regular expression pattern as passed to `compile' or `symcomp'.
  831.  
  832.  - attribute of regex: realpat
  833.      The regular expression after stripping the group names for regular
  834.      expressions compiled with `symcomp'.  Same as `givenpat' otherwise.
  835.  
  836.  - attribute of regex: groupindex
  837.      A dictionary giving the mapping from symbolic group names to
  838.      numerical group indices for regular expressions compiled with
  839.      `symcomp'.  `None' otherwise.
  840.  
  841. 
  842. File: pylibi,  Node: regsub,  Next: struct,  Prev: regex,  Up: String Services
  843.  
  844. Standard Module `regsub'
  845. ========================
  846.  
  847. This module defines a number of functions useful for working with
  848. regular expressions (see built-in module `regex').
  849.  
  850. Warning: these functions are not thread-safe.
  851.  
  852.  - function of module regsub: sub (PAT, REPL, STR)
  853.      Replace the first occurrence of pattern PAT in string STR by
  854.      replacement REPL.  If the pattern isn't found, the string is
  855.      returned unchanged.  The pattern may be a string or an already
  856.      compiled pattern.  The replacement may contain references `\DIGIT'
  857.      to subpatterns and escaped backslashes.
  858.  
  859.  - function of module regsub: gsub (PAT, REPL, STR)
  860.      Replace all (non-overlapping) occurrences of pattern PAT in string
  861.      STR by replacement REPL.  The same rules as for `sub()' apply.
  862.      Empty matches for the pattern are replaced only when not adjacent
  863.      to a previous match, so e.g.  `gsub('', '-', 'abc')' returns
  864.      `'-a-b-c-''.
  865.  
  866.  - function of module regsub: split (STR, PAT[, MAXSPLIT])
  867.      Split the string STR in fields separated by delimiters matching
  868.      the pattern PAT, and return a list containing the fields.  Only
  869.      non-empty matches for the pattern are considered, so e.g.
  870.      `split('a:b', ':*')' returns `['a', 'b']' and `split('abc', '')'
  871.      returns `['abc']'.  The MAXSPLIT defaults to 0. If it is nonzero,
  872.      only MAXSPLIT number of splits occur, and the remainder of the
  873.      string is returned as the final element of the list.
  874.  
  875.  - function of module regsub: splitx (STR, PAT[, MAXSPLIT])
  876.      Split the string STR in fields separated by delimiters matching
  877.      the pattern PAT, and return a list containing the fields as well
  878.      as the separators.  For example, `splitx('a:::b', ':*')' returns
  879.      `['a', ':::', 'b']'.  Otherwise, this function behaves the same as
  880.      `split'.
  881.  
  882.  - function of module regsub: capwords (S[, PAT])
  883.      Capitalize words separated by optional pattern PAT.  The default
  884.      pattern uses any characters except letters, digits and underscores
  885.      as word delimiters.  Capitalization is done by changing the first
  886.      character of each word to upper case.
  887.  
  888. 
  889. File: pylibi,  Node: struct,  Prev: regsub,  Up: String Services
  890.  
  891. Built-in Module `struct'
  892. ========================
  893.  
  894. This module performs conversions between Python values and C structs
  895. represented as Python strings.  It uses "format strings" (explained
  896. below) as compact descriptions of the lay-out of the C structs and the
  897. intended conversion to/from Python values.
  898.  
  899. See also built-in module `array'.
  900.  
  901. The module defines the following exception and functions:
  902.  
  903.  - exception of module struct: error
  904.      Exception raised on various occasions; argument is a string
  905.      describing what is wrong.
  906.  
  907.  - function of module struct: pack (FMT, V1, V2, ...)
  908.      Return a string containing the values `V1, V2, ...' packed
  909.      according to the given format.  The arguments must match the
  910.      values required by the format exactly.
  911.  
  912.  - function of module struct: unpack (FMT, STRING)
  913.      Unpack the string (presumably packed by `pack(FMT, ...)')
  914.      according to the given format.  The result is a tuple even if it
  915.      contains exactly one item.  The string must contain exactly the
  916.      amount of data required by the format (i.e.  `len(STRING)' must
  917.      equal `calcsize(FMT)').
  918.  
  919.  - function of module struct: calcsize (FMT)
  920.      Return the size of the struct (and hence of the string)
  921.      corresponding to the given format.
  922.  
  923. Format characters have the following meaning; the conversion between C
  924. and Python values should be obvious given their types:
  925.  
  926. *Format*
  927.      *C*  --  *Python*
  928.  
  929. `x'
  930.      pad byte  --  no value
  931.  
  932. `c'
  933.      char  --  string of length 1
  934.  
  935. `b'
  936.      signed char  --  integer
  937.  
  938. `h'
  939.      short  --  integer
  940.  
  941. `i'
  942.      int  --  integer
  943.  
  944. `l'
  945.      long  --  integer
  946.  
  947. `f'
  948.      float  --  float
  949.  
  950. `d'
  951.      double  --  float
  952.  
  953. A format character may be preceded by an integral repeat count; e.g.
  954. the format string `'4h'' means exactly the same as `'hhhh''.
  955.  
  956. C numbers are represented in the machine's native format and byte
  957. order, and properly aligned by skipping pad bytes if necessary
  958. (according to the rules used by the C compiler).
  959.  
  960. Examples (all on a big-endian machine):
  961.  
  962.      pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
  963.      unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)
  964.      calcsize('hhl') == 8
  965. Hint: to align the end of a structure to the alignment requirement of a
  966. particular type, end the format with the code for that type with a
  967. repeat count of zero, e.g. the format `'llh0l'' specifies two pad bytes
  968. at the end, assuming longs are aligned on 4-byte boundaries.
  969.  
  970. (More format characters are planned, e.g. `'s'' for character arrays,
  971. upper case for unsigned variants, and a way to specify the byte order,
  972. which is useful for [de]constructing network packets and
  973. reading/writing portable binary file formats like TIFF and AIFF.)
  974.  
  975. 
  976. File: pylibi,  Node: Miscellaneous Services,  Next: Generic Operating System Services,  Prev: String Services,  Up: Top
  977.  
  978. Miscellaneous Services
  979. **********************
  980.  
  981. The modules described in this chapter provide miscellaneous services
  982. that are available in all Python versions.  Here's an overview:
  983.  
  984. math
  985.      -- Mathematical functions (`sin()' etc.).
  986.  
  987. rand
  988.      -- Integer random number generator.
  989.  
  990. whrandom
  991.      -- Floating point random number generator.
  992.  
  993. array
  994.      -- Efficient arrays of uniformly typed numeric values.
  995.  
  996. * Menu:
  997.  
  998. * math::
  999. * rand::
  1000. * whrandom::
  1001. * array::
  1002.  
  1003. 
  1004. File: pylibi,  Node: math,  Next: rand,  Prev: Miscellaneous Services,  Up: Miscellaneous Services
  1005.  
  1006. Built-in Module `math'
  1007. ======================
  1008.  
  1009. This module is always available.  It provides access to the
  1010. mathematical functions defined by the C standard.  They are:
  1011.  
  1012.  - function of module math: acos (X)
  1013.  
  1014.  - function of module math: asin (X)
  1015.  
  1016.  - function of module math: atan (X)
  1017.  
  1018.  - function of module math: atan2 (X, Y)
  1019.  
  1020.  - function of module math: ceil (X)
  1021.  
  1022.  - function of module math: cos (X)
  1023.  
  1024.  - function of module math: cosh (X)
  1025.  
  1026.  - function of module math: exp (X)
  1027.  
  1028.  - function of module math: fabs (X)
  1029.  
  1030.  - function of module math: floor (X)
  1031.  
  1032.  - function of module math: fmod (X, Y)
  1033.  
  1034.  - function of module math: frexp (X)
  1035.  
  1036.  - function of module math: hypot (X, Y)
  1037.  
  1038.  - function of module math: ldexp (X, Y)
  1039.  
  1040.  - function of module math: log (X)
  1041.  
  1042.  - function of module math: log10 (X)
  1043.  
  1044.  - function of module math: modf (X)
  1045.  
  1046.  - function of module math: pow (X, Y)
  1047.  
  1048.  - function of module math: sin (X)
  1049.  
  1050.  - function of module math: sinh (X)
  1051.  
  1052.  - function of module math: sqrt (X)
  1053.  
  1054.  - function of module math: tan (X)
  1055.  
  1056.  - function of module math: tanh (X)
  1057.  
  1058. Note that `frexp' and `modf' have a different call/return pattern than
  1059. their C equivalents: they take a single argument and return a pair of
  1060. values, rather than returning their second return value through an
  1061. `output parameter' (there is no such thing in Python).
  1062.  
  1063. The module also defines two mathematical constants:
  1064.  
  1065.  - data of module math: pi
  1066.  
  1067.  - data of module math: e
  1068.  
  1069. 
  1070. File: pylibi,  Node: rand,  Next: whrandom,  Prev: math,  Up: Miscellaneous Services
  1071.  
  1072. Standard Module `rand'
  1073. ======================
  1074.  
  1075. This module implements a pseudo-random number generator with an
  1076. interface similar to `rand()' in C. the following functions:
  1077.  
  1078.  - function of module rand: rand ()
  1079.      Returns an integer random number in the range [0 ... 32768).
  1080.  
  1081.  - function of module rand: choice (S)
  1082.      Returns a random element from the sequence (string, tuple or list)
  1083.      S.
  1084.  
  1085.  - function of module rand: srand (SEED)
  1086.      Initializes the random number generator with the given integral
  1087.      seed.  When the module is first imported, the random number is
  1088.      initialized with the current time.
  1089.  
  1090. 
  1091. File: pylibi,  Node: whrandom,  Next: array,  Prev: rand,  Up: Miscellaneous Services
  1092.  
  1093. Standard Module `whrandom'
  1094. ==========================
  1095.  
  1096. This module implements a Wichmann-Hill pseudo-random number generator.
  1097. It defines the following functions:
  1098.  
  1099.  - function of module whrandom: random ()
  1100.      Returns the next random floating point number in the range [0.0
  1101.      ... 1.0).
  1102.  
  1103.  - function of module whrandom: seed (X, Y, Z)
  1104.      Initializes the random number generator from the integers X, Y and
  1105.      Z.  When the module is first imported, the random number is
  1106.      initialized using values derived from the current time.
  1107.  
  1108. 
  1109. File: pylibi,  Node: array,  Prev: whrandom,  Up: Miscellaneous Services
  1110.  
  1111. Built-in Module `array'
  1112. =======================
  1113.  
  1114. This module defines a new object type which can efficiently represent
  1115. an array of basic values: characters, integers, floating point numbers.
  1116. Arrays are sequence types and behave very much like lists, except that
  1117. the type of objects stored in them is constrained.  The type is
  1118. specified at object creation time by using a "type code", which is a
  1119. single character.  The following type codes are defined:
  1120.  
  1121. *Typecode*
  1122.      *Type*  --  *Minimal size in bytes*
  1123.  
  1124. `'c''
  1125.      character  --  1
  1126.  
  1127. `'b''
  1128.      signed integer  --  1
  1129.  
  1130. `'h''
  1131.      signed integer  --  2
  1132.  
  1133. `'i''
  1134.      signed integer  --  2
  1135.  
  1136. `'l''
  1137.      signed integer  --  4
  1138.  
  1139. `'f''
  1140.      floating point  --  4
  1141.  
  1142. `'d''
  1143.      floating point  --  8
  1144.  
  1145. The actual representation of values is determined by the machine
  1146. architecture (strictly speaking, by the C implementation).  The actual
  1147. size can be accessed through the ITEMSIZE attribute.
  1148.  
  1149. See also built-in module `struct'.
  1150.  
  1151. The module defines the following function:
  1152.  
  1153.  - function of module array: array (TYPECODE[, INITIALIZER])
  1154.      Return a new array whose items are restricted by TYPECODE, and
  1155.      initialized from the optional INITIALIZER value, which must be a
  1156.      list or a string.  The list or string is passed to the new array's
  1157.      `fromlist()' or `fromstring()' method (see below) to add initial
  1158.      items to the array.
  1159.  
  1160. Array objects support the following data items and methods:
  1161.  
  1162.  - data of module array: typecode
  1163.      The typecode character used to create the array.
  1164.  
  1165.  - data of module array: itemsize
  1166.      The length in bytes of one array item in the internal
  1167.      representation.
  1168.  
  1169.  - function of module array: append (X)
  1170.      Append a new item with value X to the end of the array.
  1171.  
  1172.  - function of module array: byteswap (X)
  1173.      "Byteswap" all items of the array.  This is only supported for
  1174.      integer values.  It is useful when reading data from a file written
  1175.      on a machine with a different byte order.
  1176.  
  1177.  - function of module array: fromfile (F, N)
  1178.      Read N items (as machine values) from the file object F and append
  1179.      them to the end of the array.  If less than N items are available,
  1180.      `EOFError' is raised, but the items that were available are still
  1181.      inserted into the array.  F must be a real built-in file object;
  1182.      something else with a `read()' method won't do.
  1183.  
  1184.  - function of module array: fromlist (LIST)
  1185.      Append items from the list.  This is equivalent to `for x in LIST:
  1186.      a.append(x)' except that if there is a type error, the array is
  1187.      unchanged.
  1188.  
  1189.  - function of module array: fromstring (S)
  1190.      Appends items from the string, interpreting the string as an array
  1191.      of machine values (i.e. as if it had been read from a file using
  1192.      the `fromfile()' method).
  1193.  
  1194.  - function of module array: insert (I, X)
  1195.      Insert a new item with value X in the array before position I.
  1196.  
  1197.  - function of module array: tofile (F)
  1198.      Write all items (as machine values) to the file object F.
  1199.  
  1200.  - function of module array: tolist ()
  1201.      Convert the array to an ordinary list with the same items.
  1202.  
  1203.  - function of module array: tostring ()
  1204.      Convert the array to an array of machine values and return the
  1205.      string representation (the same sequence of bytes that would be
  1206.      written to a file by the `tofile()' method.)
  1207.  
  1208. When an array object is printed or converted to a string, it is
  1209. represented as `array(TYPECODE, INITIALIZER)'.  The INITIALIZER is
  1210. omitted if the array is empty, otherwise it is a string if the TYPECODE
  1211. is `'c'', otherwise it is a list of numbers.  The string is guaranteed
  1212. to be able to be converted back to an array with the same type and
  1213. value using reverse quotes (```').  Examples:
  1214.  
  1215.      array('l')
  1216.      array('c', 'hello world')
  1217.      array('l', [1, 2, 3, 4, 5])
  1218.      array('d', [1.0, 2.0, 3.14])
  1219.  
  1220. 
  1221. File: pylibi,  Node: Generic Operating System Services,  Next: Optional Operating System Services,  Prev: Miscellaneous Services,  Up: Top
  1222.  
  1223. Generic Operating System Services
  1224. *********************************
  1225.  
  1226. The modules described in this chapter provide interfaces to operating
  1227. system features that are available on (almost) all operating systems,
  1228. such as files and a clock.  The interfaces are generally modelled after
  1229. the UNIX or C interfaces but they are available on most other systems
  1230. as well.  Here's an overview:
  1231.  
  1232. os
  1233.      -- Miscellaneous OS interfaces.
  1234.  
  1235. time
  1236.      -- Time access and conversions.
  1237.  
  1238. getopt
  1239.      -- Parser for command line options.
  1240.  
  1241. tempfile
  1242.      -- Generate temporary file names.
  1243.  
  1244. * Menu:
  1245.  
  1246. * os::
  1247. * time::
  1248. * getopt::
  1249. * tempfile::
  1250. * errno::
  1251.  
  1252.