| .. index:: module: string |
| |
| Often you'll want more control over the formatting of your output than simply |
| printing space-separated values. There are two ways to format your output; the |
| first way is to do all the string handling yourself; using string slicing and |
| concatenation operations you can create any layout you can imagine. The |
| standard module :mod:`string` contains some useful operations for padding |
| strings to a given column width; these will be discussed shortly. The second |
n | way is to use the ``%`` operator with a string as the left argument. The ``%`` |
n | way is to use the :meth:`str.format` method. |
| operator interprets the left argument much like a :cfunc:`sprintf`\ -style |
| format string to be applied to the right argument, and returns the string |
| resulting from this formatting operation. |
| |
| One question remains, of course: how do you convert values to strings? Luckily, |
| Python has ways to convert any value to a string: pass it to the :func:`repr` |
n | or :func:`str` functions. Reverse quotes (``````) are equivalent to |
n | or :func:`str` functions. |
| :func:`repr`, but they are no longer used in modern Python code and will likely |
| not be in future versions of the language. |
| |
| The :func:`str` function is meant to return representations of values which are |
| fairly human-readable, while :func:`repr` is meant to generate representations |
| which can be read by the interpreter (or will force a :exc:`SyntaxError` if |
| there is not equivalent syntax). For objects which don't have a particular |
| representation for human consumption, :func:`str` will return the same value as |
| :func:`repr`. Many values, such as numbers or structures like lists and |
| dictionaries, have the same representation using either function. Strings and |
| |
| >>> '12'.zfill(5) |
| '00012' |
| >>> '-3.14'.zfill(7) |
| '-003.14' |
| >>> '3.14159265359'.zfill(5) |
| '3.14159265359' |
| |
n | Using the ``%`` operator looks like this:: |
n | Basic usage of the :meth:`str.format` method looks like this:: |
| |
| >>> print 'We are the {0} who say "{1}!"'.format('knights', 'Ni') |
| We are the knights who say "Ni!" |
| |
| The brackets and characters within them (called format fields) are replaced with |
| the objects passed into the format method. The number in the brackets refers to |
| the position of the object passed into the format method. :: |
| |
| >>> print '{0} and {1}'.format('spam', 'eggs') |
| spam and eggs |
| >>> print '{1} and {0}'.format('spam', 'eggs') |
| eggs and spam |
| |
| If keyword arguments are used in the format method, their values are referred to |
| by using the name of the argument. :: |
| |
| >>> print 'This {food} is {adjective}.'.format( |
| ... food='spam', adjective='absolutely horrible') |
| This spam is absolutely horrible. |
| |
| Positional and keyword arguments can be arbitrarily combined:: |
| |
| >>> print 'The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred', |
| ... other='Georg') |
| The story of Bill, Manfred, and Georg. |
| |
| An optional ``':'`` and format specifier can follow the field name. This also |
| greater control over how the value is formatted. The following example |
| truncates the Pi to three places after the decimal. |
| |
| >>> import math |
| >>> print 'The value of PI is approximately {0:.3f}.'.format(math.pi) |
| The value of PI is approximately 3.142. |
| |
| Passing an integer after the ``':'`` will cause that field to be a minimum |
| number of characters wide. This is useful for making tables pretty.:: |
| |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678} |
| >>> for name, phone in table.items(): |
| ... print '{0:10} ==> {1:10d}'.format(name, phone) |
| ... |
| Jack ==> 4098 |
| Dcab ==> 7678 |
| Sjoerd ==> 4127 |
| |
| If you have a really long format string that you don't want to split up, it |
| would be nice if you could reference the variables to be formatted by name |
| instead of by position. This can be done by simply passing the dict and using |
| square brackets ``'[]'`` to access the keys :: |
| |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| >>> print ('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; ' |
| ... 'Dcab: {0[Dcab]:d}'.format(table)) |
| Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
| |
| This could also be done by passing the table as keyword arguments with the '**' |
| notation.:: |
| |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| >>> print 'Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table) |
| Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
| |
| This is particularly useful in combination with the new built-in :func:`vars` |
| function, which returns a dictionary containing all local variables. |
| |
| For a complete overview of string formating with :meth:`str.format`, see |
| :ref:`formatstrings`. |
| |
| |
| Old string formatting |
| --------------------- |
| |
| The ``%`` operator can also be used for string formatting. It interprets the |
| left argument much like a :cfunc:`sprintf`\ -style format string to be applied |
| to the right argument, and returns the string resulting from this formatting |
| operation. For example:: |
| |
| >>> import math |
| >>> print 'The value of PI is approximately %5.3f.' % math.pi |
| The value of PI is approximately 3.142. |
| |
n | If there is more than one format in the string, you need to pass a tuple as |
n | Since :meth:`str.format` is quite new, a lot of Python code still uses the ``%`` |
| right operand, as in this example:: |
| operator. However, because this old style of formatting will eventually removed |
| from the language :meth:`str.format` should generally be used. |
| |
n | >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678} |
n | More information can be found in the :ref:`string-formatting` section. |
| >>> for name, phone in table.items(): |
| ... print '%-10s ==> %10d' % (name, phone) |
| ... |
| Jack ==> 4098 |
| Dcab ==> 7678 |
| Sjoerd ==> 4127 |
| |
| Most formats work exactly as in C and require that you pass the proper type; |
| however, if you don't you get an exception, not a core dump. The ``%s`` format |
| is more relaxed: if the corresponding argument is not a string object, it is |
| converted to string using the :func:`str` built-in function. Using ``*`` to |
| pass the width or precision in as a separate (integer) argument is supported. |
| The C formats ``%n`` and ``%p`` are not supported. |
| |
| If you have a really long format string that you don't want to split up, it |
| would be nice if you could reference the variables to be formatted by name |
| instead of by position. This can be done by using form ``%(name)format``, as |
| shown here:: |
| |
| >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} |
| >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table |
| Jack: 4098; Sjoerd: 4127; Dcab: 8637678 |
| |
| This is particularly useful in combination with the new built-in :func:`vars` |
| function, which returns a dictionary containing all local variables. |
| |
| |
| .. _tut-files: |
| |
| Reading and Writing Files |
| ========================= |
| |
| .. index:: |
| builtin: open |
| object: file |
| |
| :func:`open` returns a file object, and is most commonly used with two |
| arguments: ``open(filename, mode)``. |
| |
n | .. % Opening files |
| |
| :: |
| |
n | >>> f=open('/tmp/workfile', 'w') |
n | >>> f = open('/tmp/workfile', 'w') |
| >>> print f |
| <open file '/tmp/workfile', mode 'w' at 80a0960> |
| |
| The first argument is a string containing the filename. The second argument is |
| another string containing a few characters describing the way in which the file |
| will be used. *mode* can be ``'r'`` when the file will only be read, ``'w'`` |
| for only writing (an existing file with the same name will be erased), and |
| ``'a'`` opens the file for appending; any data written to the file is |
| automatically added to the end. ``'r+'`` opens the file for both reading and |
| writing. The *mode* argument is optional; ``'r'`` will be assumed if it's |
| omitted. |
| |
n | On Windows and the Macintosh, ``'b'`` appended to the mode opens the file in |
n | On Windows, ``'b'`` appended to the mode opens the file in binary mode, so there |
| binary mode, so there are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. |
| are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. Windows makes a |
| Windows makes a distinction between text and binary files; the end-of-line |
| distinction between text and binary files; the end-of-line characters in text |
| characters in text files are automatically altered slightly when data is read or |
| files are automatically altered slightly when data is read or written. This |
| written. This behind-the-scenes modification to file data is fine for ASCII |
| behind-the-scenes modification to file data is fine for ASCII text files, but |
| text files, but it'll corrupt binary data like that in :file:`JPEG` or |
| it'll corrupt binary data like that in :file:`JPEG` or :file:`EXE` files. Be |
| :file:`EXE` files. Be very careful to use binary mode when reading and writing |
| very careful to use binary mode when reading and writing such files. On Unix, |
| such files. |
| it doesn't hurt to append a ``'b'`` to the mode, so you can use it |
| platform-independently for all binary files. |
| |
| |
| .. _tut-filemethods: |
| |
| Methods of File Objects |
| ----------------------- |
| |
| The rest of the examples in this section will assume that a file object called |
| the *from_what* argument. A *from_what* value of 0 measures from the beginning |
| of the file, 1 uses the current file position, and 2 uses the end of the file as |
| the reference point. *from_what* can be omitted and defaults to 0, using the |
| beginning of the file as the reference point. :: |
| |
| >>> f = open('/tmp/workfile', 'r+') |
| >>> f.write('0123456789abcdef') |
| >>> f.seek(5) # Go to the 6th byte in the file |
n | >>> f.read(1) |
n | >>> f.read(1) |
| '5' |
| >>> f.seek(-3, 2) # Go to the 3rd byte before the end |
| >>> f.read(1) |
| 'd' |
| |
| When you're done with a file, call ``f.close()`` to close it and free up any |
| system resources taken up by the open file. After calling ``f.close()``, |
| attempts to use the file object will automatically fail. :: |
| |
| >>> f.close() |
| >>> f.read() |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: I/O operation on closed file |
n | |
| It is good practice to use the :keyword:`with` keyword when dealing with file |
| objects. This has the advantage that the file is properly closed after its |
| suite finishes, even if an exception is raised on the way. It is also much |
| shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks:: |
| |
| >>> with open('/tmp/workfile', 'r') as f: |
| ... read_data = f.read() |
| >>> f.closed |
| True |
| |
| File objects have some additional methods, such as :meth:`isatty` and |
| :meth:`truncate` which are less frequently used; consult the Library Reference |
| for a complete guide to file objects. |
| |
| |
| .. _tut-pickle: |
| |
| Strings can easily be written to and read from a file. Numbers take a bit more |
| effort, since the :meth:`read` method only returns strings, which will have to |
| be passed to a function like :func:`int`, which takes a string like ``'123'`` |
| and returns its numeric value 123. However, when you want to save more complex |
| data types like lists, dictionaries, or class instances, things get a lot more |
| complicated. |
| |
| Rather than have users be constantly writing and debugging code to save |
n | complicated data types, Python provides a standard module called :mod:`pickle` |
n | complicated data types, Python provides a standard module called :mod:`pickle`. |
| (XXX reference: ../lib/module-pickle.html). This is an amazing module that can |
| This is an amazing module that can take almost any Python object (even some |
| take almost any Python object (even some forms of Python code!), and convert it |
| forms of Python code!), and convert it to a string representation; this process |
| to a string representation; this process is called :dfn:`pickling`. |
| is called :dfn:`pickling`. Reconstructing the object from the string |
| Reconstructing the object from the string representation is called |
| representation is called :dfn:`unpickling`. Between pickling and unpickling, |
| :dfn:`unpickling`. Between pickling and unpickling, the string representing the |
| the string representing the object may have been stored in a file or data, or |
| object may have been stored in a file or data, or sent over a network connection |
| sent over a network connection to some distant machine. |
| to some distant machine. |
| |
| If you have an object ``x``, and a file object ``f`` that's been opened for |
| writing, the simplest way to pickle the object takes only one line of code:: |
| |
| pickle.dump(x, f) |
| |
| To unpickle the object again, if ``f`` is a file object which has been opened |
| for reading:: |
| |
| x = pickle.load(f) |
| |
| (There are other variants of this, used when pickling many objects or when you |
| don't want to write the pickled data to a file; consult the complete |
n | documentation for :mod:`pickle` (XXX reference: ../lib/module-pickle.html) in |
n | documentation for :mod:`pickle` in the Python Library Reference.) |
| the Python Library Reference (XXX reference: ../lib/).) |
| |
t | :mod:`pickle` (XXX reference: ../lib/module-pickle.html) is the standard way to |
t | :mod:`pickle` is the standard way to make Python objects which can be stored and |
| make Python objects which can be stored and reused by other programs or by a |
| reused by other programs or by a future invocation of the same program; the |
| future invocation of the same program; the technical term for this is a |
| technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is |
| :dfn:`persistent` object. Because :mod:`pickle` (XXX reference: ../lib/module- |
| pickle.html) is so widely used, many authors who write Python extensions take |
| so widely used, many authors who write Python extensions take care to ensure |
| care to ensure that new data types such as matrices can be properly pickled and |
| that new data types such as matrices can be properly pickled and unpickled. |
| unpickled. |
| |
| |