home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / f / file_objec next >
Text File  |  1996-11-14  |  5KB  |  90 lines
  1. <TITLE>File Objects -- Python library reference</TITLE>
  2. Next: <A HREF="../i/internal_objects" TYPE="Next">Internal Objects</A>  
  3. Prev: <A HREF="../t/the_null_object" TYPE="Prev">The Null Object</A>  
  4. Up: <A HREF="../o/other_built-in_types" TYPE="Up">Other Built-in Types</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H3>2.1.7.8. File Objects</H3>
  7. File objects are implemented using C's <CODE>stdio</CODE> package and can be
  8. created with the built-in function <CODE>open()</CODE> described under
  9. Built-in Functions below.  They are also returned by some other
  10. built-in functions and methods, e.g. <CODE>posix.popen()</CODE> and
  11. <CODE>posix.fdopen()</CODE> and the <CODE>makefile()</CODE> method of socket
  12. objects.
  13. When a file operation fails for an I/O-related reason, the exception
  14. <CODE>IOError</CODE> is raised.  This includes situations where the
  15. operation is not defined for some reason, like <CODE>seek()</CODE> on a tty
  16. device or writing a file opened for reading.
  17. <P>
  18. Files have the following methods:
  19. <P>
  20. <DL><DT><B>close</B> () -- Method on file<DD>
  21. Close the file.  A closed file cannot be read or written anymore.
  22. </DL>
  23. <DL><DT><B>flush</B> () -- Method on file<DD>
  24. Flush the internal buffer, like <CODE>stdio</CODE>'s <CODE>fflush()</CODE>.
  25. </DL>
  26. <DL><DT><B>isatty</B> () -- Method on file<DD>
  27. Return <CODE>1</CODE> if the file is connected to a tty(-like) device, else
  28. <CODE>0</CODE>.
  29. </DL>
  30. <DL><DT><B>read</B> ([<VAR>size</VAR>]) -- Method on file<DD>
  31. Read at most <VAR>size</VAR> bytes from the file (less if the read hits
  32. EOF or no more data is immediately available on a pipe, tty or
  33. similar device).  If the <VAR>size</VAR> argument is negative or omitted,
  34. read all data until EOF is reached.  The bytes are returned as a string
  35. object.  An empty string is returned when EOF is encountered
  36. immediately.  (For certain files, like ttys, it makes sense to
  37. continue reading after an EOF is hit.)
  38. </DL>
  39. <DL><DT><B>readline</B> ([<VAR>size</VAR>]) -- Method on file<DD>
  40. Read one entire line from the file.  A trailing newline character is
  41. kept in the string<A NAME="footnoteref1" HREF="#footnotetext1">(1)</A>
  42. (but may be absent when a file ends with an
  43. incomplete line).  If the <VAR>size</VAR> argument is present and
  44. non-negative, it is a maximum byte count (including the trailing
  45. newline) and an incomplete line may be returned.
  46. An empty string is returned when EOF is hit
  47. immediately.  Note: unlike <CODE>stdio</CODE>'s <CODE>fgets()</CODE>, the returned
  48. string contains null characters (<CODE>'\0'</CODE>) if they occurred in the
  49. input.
  50. </DL>
  51. <DL><DT><B>readlines</B> () -- Method on file<DD>
  52. Read until EOF using <CODE>readline()</CODE> and return a list containing
  53. the lines thus read.
  54. </DL>
  55. <DL><DT><B>seek</B> (<VAR>offset</VAR>, <VAR>whence</VAR>) -- Method on file<DD>
  56. Set the file's current position, like <CODE>stdio</CODE>'s <CODE>fseek()</CODE>.
  57. The <VAR>whence</VAR> argument is optional and defaults to <CODE>0</CODE>
  58. (absolute file positioning); other values are <CODE>1</CODE> (seek
  59. relative to the current position) and <CODE>2</CODE> (seek relative to the
  60. file's end).  There is no return value.
  61. </DL>
  62. <DL><DT><B>tell</B> () -- Method on file<DD>
  63. Return the file's current position, like <CODE>stdio</CODE>'s <CODE>ftell()</CODE>.
  64. </DL>
  65. <DL><DT><B>truncate</B> ([<VAR>size</VAR>]) -- Method on file<DD>
  66. Truncate the file's size.  If the optional size argument present, the
  67. file is truncated to (at most) that size.  The size defaults to the
  68. current position.  Availability of this function depends on the
  69. operating system version (e.g., not all UNIX versions support this
  70. operation).
  71. </DL>
  72. <DL><DT><B>write</B> (<VAR>str</VAR>) -- Method on file<DD>
  73. Write a string to the file.  There is no return value.  Note: due to
  74. buffering, the string may not actually show up in the file until
  75. the <CODE>flush()</CODE> or <CODE>close()</CODE> method is called.
  76. </DL>
  77. <DL><DT><B>writelines</B> (<VAR>list</VAR>) -- Method on file<DD>
  78. Write a list of strings to the file.  There is no return value.
  79. (The name is intended to match <CODE>readlines</CODE>; <CODE>writelines</CODE>
  80. does not add line separators.)
  81. </DL>
  82. <H2>---------- Footnotes ----------</H2>
  83. <A NAME="footnotetext1" HREF="#footnoteref1">(1)</A>
  84. The advantage of leaving the newline on is that an empty string 
  85. can be returned to mean EOF without being ambiguous.  Another 
  86. advantage is that (in cases where it might matter, e.g. if you 
  87. want to make an exact copy of a file while scanning its lines) 
  88. you can tell whether the last line of a file ended in a newline
  89. or not (yes this happens!).<P>
  90.