/Doc/tutorial/inputoutput.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 407 lines · 316 code · 91 blank · 0 comment · 0 complexity · 6219bce46ddc790f0ae324364b8f6974 MD5 · raw file

  1. .. _tut-io:
  2. ****************
  3. Input and Output
  4. ****************
  5. There are several ways to present the output of a program; data can be printed
  6. in a human-readable form, or written to a file for future use. This chapter will
  7. discuss some of the possibilities.
  8. .. _tut-formatting:
  9. Fancier Output Formatting
  10. =========================
  11. So far we've encountered two ways of writing values: *expression statements* and
  12. the :keyword:`print` statement. (A third way is using the :meth:`write` method
  13. of file objects; the standard output file can be referenced as ``sys.stdout``.
  14. See the Library Reference for more information on this.)
  15. .. index:: module: string
  16. Often you'll want more control over the formatting of your output than simply
  17. printing space-separated values. There are two ways to format your output; the
  18. first way is to do all the string handling yourself; using string slicing and
  19. concatenation operations you can create any layout you can imagine. The
  20. standard module :mod:`string` contains some useful operations for padding
  21. strings to a given column width; these will be discussed shortly. The second
  22. way is to use the :meth:`str.format` method.
  23. One question remains, of course: how do you convert values to strings? Luckily,
  24. Python has ways to convert any value to a string: pass it to the :func:`repr`
  25. or :func:`str` functions.
  26. The :func:`str` function is meant to return representations of values which are
  27. fairly human-readable, while :func:`repr` is meant to generate representations
  28. which can be read by the interpreter (or will force a :exc:`SyntaxError` if
  29. there is not equivalent syntax). For objects which don't have a particular
  30. representation for human consumption, :func:`str` will return the same value as
  31. :func:`repr`. Many values, such as numbers or structures like lists and
  32. dictionaries, have the same representation using either function. Strings and
  33. floating point numbers, in particular, have two distinct representations.
  34. Some examples::
  35. >>> s = 'Hello, world.'
  36. >>> str(s)
  37. 'Hello, world.'
  38. >>> repr(s)
  39. "'Hello, world.'"
  40. >>> str(0.1)
  41. '0.1'
  42. >>> repr(0.1)
  43. '0.10000000000000001'
  44. >>> x = 10 * 3.25
  45. >>> y = 200 * 200
  46. >>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
  47. >>> print s
  48. The value of x is 32.5, and y is 40000...
  49. >>> # The repr() of a string adds string quotes and backslashes:
  50. ... hello = 'hello, world\n'
  51. >>> hellos = repr(hello)
  52. >>> print hellos
  53. 'hello, world\n'
  54. >>> # The argument to repr() may be any Python object:
  55. ... repr((x, y, ('spam', 'eggs')))
  56. "(32.5, 40000, ('spam', 'eggs'))"
  57. Here are two ways to write a table of squares and cubes::
  58. >>> for x in range(1, 11):
  59. ... print repr(x).rjust(2), repr(x*x).rjust(3),
  60. ... # Note trailing comma on previous line
  61. ... print repr(x*x*x).rjust(4)
  62. ...
  63. 1 1 1
  64. 2 4 8
  65. 3 9 27
  66. 4 16 64
  67. 5 25 125
  68. 6 36 216
  69. 7 49 343
  70. 8 64 512
  71. 9 81 729
  72. 10 100 1000
  73. >>> for x in range(1,11):
  74. ... print '{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x)
  75. ...
  76. 1 1 1
  77. 2 4 8
  78. 3 9 27
  79. 4 16 64
  80. 5 25 125
  81. 6 36 216
  82. 7 49 343
  83. 8 64 512
  84. 9 81 729
  85. 10 100 1000
  86. (Note that in the first example, one space between each column was added by the
  87. way :keyword:`print` works: it always adds spaces between its arguments.)
  88. This example demonstrates the :meth:`rjust` method of string objects, which
  89. right-justifies a string in a field of a given width by padding it with spaces
  90. on the left. There are similar methods :meth:`ljust` and :meth:`center`. These
  91. methods do not write anything, they just return a new string. If the input
  92. string is too long, they don't truncate it, but return it unchanged; this will
  93. mess up your column lay-out but that's usually better than the alternative,
  94. which would be lying about a value. (If you really want truncation you can
  95. always add a slice operation, as in ``x.ljust(n)[:n]``.)
  96. There is another method, :meth:`zfill`, which pads a numeric string on the left
  97. with zeros. It understands about plus and minus signs::
  98. >>> '12'.zfill(5)
  99. '00012'
  100. >>> '-3.14'.zfill(7)
  101. '-003.14'
  102. >>> '3.14159265359'.zfill(5)
  103. '3.14159265359'
  104. Basic usage of the :meth:`str.format` method looks like this::
  105. >>> print 'We are the {0} who say "{1}!"'.format('knights', 'Ni')
  106. We are the knights who say "Ni!"
  107. The brackets and characters within them (called format fields) are replaced with
  108. the objects passed into the format method. The number in the brackets refers to
  109. the position of the object passed into the format method. ::
  110. >>> print '{0} and {1}'.format('spam', 'eggs')
  111. spam and eggs
  112. >>> print '{1} and {0}'.format('spam', 'eggs')
  113. eggs and spam
  114. If keyword arguments are used in the format method, their values are referred to
  115. by using the name of the argument. ::
  116. >>> print 'This {food} is {adjective}.'.format(
  117. ... food='spam', adjective='absolutely horrible')
  118. This spam is absolutely horrible.
  119. Positional and keyword arguments can be arbitrarily combined::
  120. >>> print 'The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
  121. ... other='Georg')
  122. The story of Bill, Manfred, and Georg.
  123. An optional ``':'`` and format specifier can follow the field name. This also
  124. greater control over how the value is formatted. The following example
  125. truncates the Pi to three places after the decimal.
  126. >>> import math
  127. >>> print 'The value of PI is approximately {0:.3f}.'.format(math.pi)
  128. The value of PI is approximately 3.142.
  129. Passing an integer after the ``':'`` will cause that field to be a minimum
  130. number of characters wide. This is useful for making tables pretty.::
  131. >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
  132. >>> for name, phone in table.items():
  133. ... print '{0:10} ==> {1:10d}'.format(name, phone)
  134. ...
  135. Jack ==> 4098
  136. Dcab ==> 7678
  137. Sjoerd ==> 4127
  138. If you have a really long format string that you don't want to split up, it
  139. would be nice if you could reference the variables to be formatted by name
  140. instead of by position. This can be done by simply passing the dict and using
  141. square brackets ``'[]'`` to access the keys ::
  142. >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
  143. >>> print ('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
  144. ... 'Dcab: {0[Dcab]:d}'.format(table))
  145. Jack: 4098; Sjoerd: 4127; Dcab: 8637678
  146. This could also be done by passing the table as keyword arguments with the '**'
  147. notation.::
  148. >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
  149. >>> print 'Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table)
  150. Jack: 4098; Sjoerd: 4127; Dcab: 8637678
  151. This is particularly useful in combination with the new built-in :func:`vars`
  152. function, which returns a dictionary containing all local variables.
  153. For a complete overview of string formatting with :meth:`str.format`, see
  154. :ref:`formatstrings`.
  155. Old string formatting
  156. ---------------------
  157. The ``%`` operator can also be used for string formatting. It interprets the
  158. left argument much like a :cfunc:`sprintf`\ -style format string to be applied
  159. to the right argument, and returns the string resulting from this formatting
  160. operation. For example::
  161. >>> import math
  162. >>> print 'The value of PI is approximately %5.3f.' % math.pi
  163. The value of PI is approximately 3.142.
  164. Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%``
  165. operator. However, because this old style of formatting will eventually removed
  166. from the language :meth:`str.format` should generally be used.
  167. More information can be found in the :ref:`string-formatting` section.
  168. .. _tut-files:
  169. Reading and Writing Files
  170. =========================
  171. .. index::
  172. builtin: open
  173. object: file
  174. :func:`open` returns a file object, and is most commonly used with two
  175. arguments: ``open(filename, mode)``.
  176. ::
  177. >>> f = open('/tmp/workfile', 'w')
  178. >>> print f
  179. <open file '/tmp/workfile', mode 'w' at 80a0960>
  180. The first argument is a string containing the filename. The second argument is
  181. another string containing a few characters describing the way in which the file
  182. will be used. *mode* can be ``'r'`` when the file will only be read, ``'w'``
  183. for only writing (an existing file with the same name will be erased), and
  184. ``'a'`` opens the file for appending; any data written to the file is
  185. automatically added to the end. ``'r+'`` opens the file for both reading and
  186. writing. The *mode* argument is optional; ``'r'`` will be assumed if it's
  187. omitted.
  188. On Windows, ``'b'`` appended to the mode opens the file in binary mode, so there
  189. are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. Windows makes a
  190. distinction between text and binary files; the end-of-line characters in text
  191. files are automatically altered slightly when data is read or written. This
  192. behind-the-scenes modification to file data is fine for ASCII text files, but
  193. it'll corrupt binary data like that in :file:`JPEG` or :file:`EXE` files. Be
  194. very careful to use binary mode when reading and writing such files. On Unix,
  195. it doesn't hurt to append a ``'b'`` to the mode, so you can use it
  196. platform-independently for all binary files.
  197. .. _tut-filemethods:
  198. Methods of File Objects
  199. -----------------------
  200. The rest of the examples in this section will assume that a file object called
  201. ``f`` has already been created.
  202. To read a file's contents, call ``f.read(size)``, which reads some quantity of
  203. data and returns it as a string. *size* is an optional numeric argument. When
  204. *size* is omitted or negative, the entire contents of the file will be read and
  205. returned; it's your problem if the file is twice as large as your machine's
  206. memory. Otherwise, at most *size* bytes are read and returned. If the end of
  207. the file has been reached, ``f.read()`` will return an empty string (``""``).
  208. ::
  209. >>> f.read()
  210. 'This is the entire file.\n'
  211. >>> f.read()
  212. ''
  213. ``f.readline()`` reads a single line from the file; a newline character (``\n``)
  214. is left at the end of the string, and is only omitted on the last line of the
  215. file if the file doesn't end in a newline. This makes the return value
  216. unambiguous; if ``f.readline()`` returns an empty string, the end of the file
  217. has been reached, while a blank line is represented by ``'\n'``, a string
  218. containing only a single newline. ::
  219. >>> f.readline()
  220. 'This is the first line of the file.\n'
  221. >>> f.readline()
  222. 'Second line of the file\n'
  223. >>> f.readline()
  224. ''
  225. ``f.readlines()`` returns a list containing all the lines of data in the file.
  226. If given an optional parameter *sizehint*, it reads that many bytes from the
  227. file and enough more to complete a line, and returns the lines from that. This
  228. is often used to allow efficient reading of a large file by lines, but without
  229. having to load the entire file in memory. Only complete lines will be returned.
  230. ::
  231. >>> f.readlines()
  232. ['This is the first line of the file.\n', 'Second line of the file\n']
  233. An alternative approach to reading lines is to loop over the file object. This is
  234. memory efficient, fast, and leads to simpler code::
  235. >>> for line in f:
  236. print line,
  237. This is the first line of the file.
  238. Second line of the file
  239. The alternative approach is simpler but does not provide as fine-grained
  240. control. Since the two approaches manage line buffering differently, they
  241. should not be mixed.
  242. ``f.write(string)`` writes the contents of *string* to the file, returning
  243. ``None``. ::
  244. >>> f.write('This is a test\n')
  245. To write something other than a string, it needs to be converted to a string
  246. first::
  247. >>> value = ('the answer', 42)
  248. >>> s = str(value)
  249. >>> f.write(s)
  250. ``f.tell()`` returns an integer giving the file object's current position in the
  251. file, measured in bytes from the beginning of the file. To change the file
  252. object's position, use ``f.seek(offset, from_what)``. The position is computed
  253. from adding *offset* to a reference point; the reference point is selected by
  254. the *from_what* argument. A *from_what* value of 0 measures from the beginning
  255. of the file, 1 uses the current file position, and 2 uses the end of the file as
  256. the reference point. *from_what* can be omitted and defaults to 0, using the
  257. beginning of the file as the reference point. ::
  258. >>> f = open('/tmp/workfile', 'r+')
  259. >>> f.write('0123456789abcdef')
  260. >>> f.seek(5) # Go to the 6th byte in the file
  261. >>> f.read(1)
  262. '5'
  263. >>> f.seek(-3, 2) # Go to the 3rd byte before the end
  264. >>> f.read(1)
  265. 'd'
  266. When you're done with a file, call ``f.close()`` to close it and free up any
  267. system resources taken up by the open file. After calling ``f.close()``,
  268. attempts to use the file object will automatically fail. ::
  269. >>> f.close()
  270. >>> f.read()
  271. Traceback (most recent call last):
  272. File "<stdin>", line 1, in ?
  273. ValueError: I/O operation on closed file
  274. It is good practice to use the :keyword:`with` keyword when dealing with file
  275. objects. This has the advantage that the file is properly closed after its
  276. suite finishes, even if an exception is raised on the way. It is also much
  277. shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
  278. >>> with open('/tmp/workfile', 'r') as f:
  279. ... read_data = f.read()
  280. >>> f.closed
  281. True
  282. File objects have some additional methods, such as :meth:`isatty` and
  283. :meth:`truncate` which are less frequently used; consult the Library Reference
  284. for a complete guide to file objects.
  285. .. _tut-pickle:
  286. The :mod:`pickle` Module
  287. ------------------------
  288. .. index:: module: pickle
  289. Strings can easily be written to and read from a file. Numbers take a bit more
  290. effort, since the :meth:`read` method only returns strings, which will have to
  291. be passed to a function like :func:`int`, which takes a string like ``'123'``
  292. and returns its numeric value 123. However, when you want to save more complex
  293. data types like lists, dictionaries, or class instances, things get a lot more
  294. complicated.
  295. Rather than have users be constantly writing and debugging code to save
  296. complicated data types, Python provides a standard module called :mod:`pickle`.
  297. This is an amazing module that can take almost any Python object (even some
  298. forms of Python code!), and convert it to a string representation; this process
  299. is called :dfn:`pickling`. Reconstructing the object from the string
  300. representation is called :dfn:`unpickling`. Between pickling and unpickling,
  301. the string representing the object may have been stored in a file or data, or
  302. sent over a network connection to some distant machine.
  303. If you have an object ``x``, and a file object ``f`` that's been opened for
  304. writing, the simplest way to pickle the object takes only one line of code::
  305. pickle.dump(x, f)
  306. To unpickle the object again, if ``f`` is a file object which has been opened
  307. for reading::
  308. x = pickle.load(f)
  309. (There are other variants of this, used when pickling many objects or when you
  310. don't want to write the pickled data to a file; consult the complete
  311. documentation for :mod:`pickle` in the Python Library Reference.)
  312. :mod:`pickle` is the standard way to make Python objects which can be stored and
  313. reused by other programs or by a future invocation of the same program; the
  314. technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is
  315. so widely used, many authors who write Python extensions take care to ensure
  316. that new data types such as matrices can be properly pickled and unpickled.