2007-08-15 11:28:22 -03:00
|
|
|
.. _tut-io:
|
|
|
|
|
|
|
|
****************
|
|
|
|
Input and Output
|
|
|
|
****************
|
|
|
|
|
|
|
|
There are several ways to present the output of a program; data can be printed
|
|
|
|
in a human-readable form, or written to a file for future use. This chapter will
|
|
|
|
discuss some of the possibilities.
|
|
|
|
|
|
|
|
|
|
|
|
.. _tut-formatting:
|
|
|
|
|
|
|
|
Fancier Output Formatting
|
|
|
|
=========================
|
|
|
|
|
|
|
|
So far we've encountered two ways of writing values: *expression statements* and
|
2007-08-31 00:25:11 -03:00
|
|
|
the :func:`print` function. (A third way is using the :meth:`write` method
|
2007-08-15 11:28:22 -03:00
|
|
|
of file objects; the standard output file can be referenced as ``sys.stdout``.
|
|
|
|
See the Library Reference for more information on this.)
|
|
|
|
|
|
|
|
Often you'll want more control over the formatting of your output than simply
|
2018-07-07 18:36:23 -03:00
|
|
|
printing space-separated values. There are several ways to format output.
|
2008-05-25 22:03:56 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
* To use :ref:`formatted string literals <tut-f-strings>`, begin a string
|
|
|
|
with ``f`` or ``F`` before the opening quotation mark or triple quotation mark.
|
|
|
|
Inside this string, you can write a Python expression between ``{`` and ``}``
|
|
|
|
characters that can refer to variables or literal values.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
::
|
|
|
|
|
2018-09-19 07:28:28 -03:00
|
|
|
>>> year = 2016
|
|
|
|
>>> event = 'Referendum'
|
2018-07-07 18:36:23 -03:00
|
|
|
>>> f'Results of the {year} {event}'
|
|
|
|
'Results of the 2016 Referendum'
|
|
|
|
|
|
|
|
* The :meth:`str.format` method of strings requires more manual
|
|
|
|
effort. You'll still use ``{`` and ``}`` to mark where a variable
|
|
|
|
will be substituted and can provide detailed formatting directives,
|
|
|
|
but you'll also need to provide the information to be formatted.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-09-19 07:28:28 -03:00
|
|
|
>>> yes_votes = 42_572_654
|
|
|
|
>>> no_votes = 43_132_495
|
|
|
|
>>> percentage = yes_votes / (yes_votes + no_votes)
|
2018-07-20 13:06:44 -03:00
|
|
|
>>> '{:-9} YES votes {:2.2%}'.format(yes_votes, percentage)
|
2018-07-07 18:36:23 -03:00
|
|
|
' 42572654 YES votes 49.67%'
|
|
|
|
|
|
|
|
* Finally, you can do all the string handling yourself by using string slicing and
|
|
|
|
concatenation operations to create any layout you can imagine. The
|
|
|
|
string type has some methods that perform useful operations for padding
|
|
|
|
strings to a given column width.
|
|
|
|
|
|
|
|
When you don't need fancy output but just want a quick display of some
|
|
|
|
variables for debugging purposes, you can convert any value to a string with
|
|
|
|
the :func:`repr` or :func:`str` functions.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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
|
2012-08-14 14:51:43 -03:00
|
|
|
there is no equivalent syntax). For objects which don't have a particular
|
2007-08-15 11:28:22 -03:00
|
|
|
representation for human consumption, :func:`str` will return the same value as
|
|
|
|
:func:`repr`. Many values, such as numbers or structures like lists and
|
2011-03-12 20:27:26 -04:00
|
|
|
dictionaries, have the same representation using either function. Strings, in
|
|
|
|
particular, have two distinct representations.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
Some examples::
|
|
|
|
|
|
|
|
>>> s = 'Hello, world.'
|
|
|
|
>>> str(s)
|
|
|
|
'Hello, world.'
|
|
|
|
>>> repr(s)
|
|
|
|
"'Hello, world.'"
|
2011-03-12 20:27:26 -04:00
|
|
|
>>> str(1/7)
|
2009-06-28 17:59:42 -03:00
|
|
|
'0.14285714285714285'
|
2007-08-15 11:28:22 -03:00
|
|
|
>>> x = 10 * 3.25
|
|
|
|
>>> y = 200 * 200
|
|
|
|
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
|
2007-08-31 00:25:11 -03:00
|
|
|
>>> print(s)
|
2007-08-15 11:28:22 -03:00
|
|
|
The value of x is 32.5, and y is 40000...
|
|
|
|
>>> # The repr() of a string adds string quotes and backslashes:
|
|
|
|
... hello = 'hello, world\n'
|
|
|
|
>>> hellos = repr(hello)
|
2007-08-31 00:25:11 -03:00
|
|
|
>>> print(hellos)
|
2007-08-15 11:28:22 -03:00
|
|
|
'hello, world\n'
|
|
|
|
>>> # The argument to repr() may be any Python object:
|
|
|
|
... repr((x, y, ('spam', 'eggs')))
|
|
|
|
"(32.5, 40000, ('spam', 'eggs'))"
|
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
The :mod:`string` module contains a :class:`~string.Template` class that offers
|
|
|
|
yet another way to substitute values into strings, using placeholders like
|
|
|
|
``$x`` and replacing them with values from a dictionary, but offers much less
|
|
|
|
control of the formatting.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
.. _tut-f-strings:
|
|
|
|
|
|
|
|
Formatted String Literals
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
:ref:`Formatted string literals <f-strings>` (also called f-strings for
|
|
|
|
short) let you include the value of Python expressions inside a string by
|
|
|
|
prefixing the string with ``f`` or ``F`` and writing expressions as
|
|
|
|
``{expression}``.
|
|
|
|
|
|
|
|
An optional format specifier can follow the expression. This allows greater
|
|
|
|
control over how the value is formatted. The following example rounds pi to
|
|
|
|
three places after the decimal::
|
|
|
|
|
|
|
|
>>> import math
|
|
|
|
>>> print(f'The value of pi is approximately {math.pi:.3f}.')
|
2018-09-19 07:28:28 -03:00
|
|
|
The value of pi is approximately 3.142.
|
2018-07-07 18:36:23 -03:00
|
|
|
|
|
|
|
Passing an integer after the ``':'`` will cause that field to be a minimum
|
|
|
|
number of characters wide. This is useful for making columns line up. ::
|
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
|
|
|
|
>>> for name, phone in table.items():
|
|
|
|
... print(f'{name:10} ==> {phone:10d}')
|
2009-01-03 17:18:54 -04:00
|
|
|
...
|
2018-07-07 18:36:23 -03:00
|
|
|
Sjoerd ==> 4127
|
|
|
|
Jack ==> 4098
|
|
|
|
Dcab ==> 7678
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
Other modifiers can be used to convert the value before it is formatted.
|
|
|
|
``'!a'`` applies :func:`ascii`, ``'!s'`` applies :func:`str`, and ``'!r'``
|
|
|
|
applies :func:`repr`::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
>>> animals = 'eels'
|
|
|
|
>>> print(f'My hovercraft is full of {animals}.')
|
|
|
|
My hovercraft is full of eels.
|
2018-09-19 07:28:28 -03:00
|
|
|
>>> print(f'My hovercraft is full of {animals!r}.')
|
2018-07-07 18:36:23 -03:00
|
|
|
My hovercraft is full of 'eels'.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
For a reference on these format specifications, see
|
|
|
|
the reference guide for the :ref:`formatspec`.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
.. _tut-string-format:
|
|
|
|
|
|
|
|
The String format() Method
|
|
|
|
--------------------------
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2008-05-25 22:03:56 -03:00
|
|
|
Basic usage of the :meth:`str.format` method looks like this::
|
|
|
|
|
2009-09-01 04:42:40 -03:00
|
|
|
>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
|
2008-05-25 22:03:56 -03:00
|
|
|
We are the knights who say "Ni!"
|
|
|
|
|
|
|
|
The brackets and characters within them (called format fields) are replaced with
|
2011-03-12 20:19:57 -04:00
|
|
|
the objects passed into the :meth:`str.format` method. A number in the
|
2009-09-01 04:42:40 -03:00
|
|
|
brackets can be used to refer to the position of the object passed into the
|
2011-03-12 20:19:57 -04:00
|
|
|
:meth:`str.format` method. ::
|
2008-05-25 22:03:56 -03:00
|
|
|
|
2008-07-26 18:59:03 -03:00
|
|
|
>>> print('{0} and {1}'.format('spam', 'eggs'))
|
2008-05-25 22:03:56 -03:00
|
|
|
spam and eggs
|
2008-07-26 18:59:03 -03:00
|
|
|
>>> print('{1} and {0}'.format('spam', 'eggs'))
|
2008-05-25 22:03:56 -03:00
|
|
|
eggs and spam
|
|
|
|
|
2011-03-12 20:19:57 -04:00
|
|
|
If keyword arguments are used in the :meth:`str.format` method, their values
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-29 16:54:39 -03:00
|
|
|
are referred to by using the name of the argument. ::
|
2008-05-25 22:03:56 -03:00
|
|
|
|
2008-07-26 19:27:04 -03:00
|
|
|
>>> print('This {food} is {adjective}.'.format(
|
|
|
|
... food='spam', adjective='absolutely horrible'))
|
2008-05-25 22:03:56 -03:00
|
|
|
This spam is absolutely horrible.
|
|
|
|
|
|
|
|
Positional and keyword arguments can be arbitrarily combined::
|
|
|
|
|
2008-07-26 19:27:04 -03:00
|
|
|
>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
|
|
|
|
other='Georg'))
|
2008-05-25 22:03:56 -03:00
|
|
|
The story of Bill, Manfred, and Georg.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
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
|
2008-05-25 22:03:56 -03:00
|
|
|
instead of by position. This can be done by simply passing the dict and using
|
2020-05-27 22:34:01 -03:00
|
|
|
square brackets ``'[]'`` to access the keys. ::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
|
2008-07-26 19:27:04 -03:00
|
|
|
>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
|
2012-10-17 10:41:28 -03:00
|
|
|
... 'Dcab: {0[Dcab]:d}'.format(table))
|
2008-05-25 22:03:56 -03:00
|
|
|
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
|
|
|
|
|
|
|
|
This could also be done by passing the table as keyword arguments with the '**'
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-29 16:54:39 -03:00
|
|
|
notation. ::
|
2008-05-25 22:03:56 -03:00
|
|
|
|
|
|
|
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
|
|
|
|
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
|
2007-08-15 11:28:22 -03:00
|
|
|
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
|
|
|
|
|
2011-03-12 20:19:57 -04:00
|
|
|
This is particularly useful in combination with the built-in function
|
|
|
|
:func:`vars`, which returns a dictionary containing all local variables.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
As an example, the following lines produce a tidily-aligned
|
|
|
|
set of columns giving integers and their squares and cubes::
|
|
|
|
|
|
|
|
>>> for x in range(1, 11):
|
|
|
|
... print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
|
|
|
|
...
|
|
|
|
1 1 1
|
|
|
|
2 4 8
|
|
|
|
3 9 27
|
|
|
|
4 16 64
|
|
|
|
5 25 125
|
|
|
|
6 36 216
|
|
|
|
7 49 343
|
|
|
|
8 64 512
|
|
|
|
9 81 729
|
|
|
|
10 100 1000
|
|
|
|
|
2009-02-21 16:59:32 -04:00
|
|
|
For a complete overview of string formatting with :meth:`str.format`, see
|
2008-05-25 22:03:56 -03:00
|
|
|
:ref:`formatstrings`.
|
|
|
|
|
|
|
|
|
2018-07-07 18:36:23 -03:00
|
|
|
Manual String Formatting
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
Here's the same table of squares and cubes, formatted manually::
|
|
|
|
|
|
|
|
>>> for x in range(1, 11):
|
|
|
|
... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
|
|
|
|
... # Note use of 'end' on previous line
|
|
|
|
... print(repr(x*x*x).rjust(4))
|
|
|
|
...
|
|
|
|
1 1 1
|
|
|
|
2 4 8
|
|
|
|
3 9 27
|
|
|
|
4 16 64
|
|
|
|
5 25 125
|
|
|
|
6 36 216
|
|
|
|
7 49 343
|
|
|
|
8 64 512
|
|
|
|
9 81 729
|
|
|
|
10 100 1000
|
|
|
|
|
|
|
|
(Note that the one space between each column was added by the
|
|
|
|
way :func:`print` works: it always adds spaces between its arguments.)
|
|
|
|
|
|
|
|
The :meth:`str.rjust` method of string objects right-justifies a string in a
|
|
|
|
field of a given width by padding it with spaces on the left. There are
|
|
|
|
similar methods :meth:`str.ljust` and :meth:`str.center`. These methods do
|
|
|
|
not write anything, they just return a new string. If the input string is too
|
|
|
|
long, they don't truncate it, but return it unchanged; this will mess up your
|
|
|
|
column lay-out but that's usually better than the alternative, which would be
|
|
|
|
lying about a value. (If you really want truncation you can always add a
|
|
|
|
slice operation, as in ``x.ljust(n)[:n]``.)
|
|
|
|
|
|
|
|
There is another method, :meth:`str.zfill`, which pads a numeric string on the
|
|
|
|
left with zeros. It understands about plus and minus signs::
|
|
|
|
|
|
|
|
>>> '12'.zfill(5)
|
|
|
|
'00012'
|
|
|
|
>>> '-3.14'.zfill(7)
|
|
|
|
'-003.14'
|
|
|
|
>>> '3.14159265359'.zfill(5)
|
|
|
|
'3.14159265359'
|
|
|
|
|
|
|
|
|
2008-05-25 22:03:56 -03:00
|
|
|
Old string formatting
|
|
|
|
---------------------
|
|
|
|
|
2020-05-27 22:34:01 -03:00
|
|
|
The % operator (modulo) can also be used for string formatting. Given ``'string'
|
|
|
|
% values``, instances of ``%`` in ``string`` are replaced with zero or more
|
|
|
|
elements of ``values``. This operation is commonly known as string
|
|
|
|
interpolation. For example::
|
2008-05-25 22:03:56 -03:00
|
|
|
|
|
|
|
>>> import math
|
2018-07-07 18:36:23 -03:00
|
|
|
>>> print('The value of pi is approximately %5.3f.' % math.pi)
|
|
|
|
The value of pi is approximately 3.142.
|
2008-05-25 22:03:56 -03:00
|
|
|
|
|
|
|
More information can be found in the :ref:`old-string-formatting` section.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. _tut-files:
|
|
|
|
|
|
|
|
Reading and Writing Files
|
|
|
|
=========================
|
|
|
|
|
|
|
|
.. index::
|
|
|
|
builtin: open
|
|
|
|
object: file
|
|
|
|
|
2010-09-15 08:11:28 -03:00
|
|
|
:func:`open` returns a :term:`file object`, and is most commonly used with
|
|
|
|
two arguments: ``open(filename, mode)``.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2013-02-23 14:26:56 -04:00
|
|
|
>>> f = open('workfile', 'w')
|
2008-08-08 04:04:38 -03:00
|
|
|
|
|
|
|
.. XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
|
|
|
|
|
2007-08-31 00:25:11 -03:00
|
|
|
>>> print(f)
|
2013-02-23 14:26:56 -04:00
|
|
|
<open file 'workfile', mode 'w' at 80a0960>
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2008-08-08 04:04:38 -03:00
|
|
|
Normally, files are opened in :dfn:`text mode`, that means, you read and write
|
2015-07-28 16:00:10 -03:00
|
|
|
strings from and to the file, which are encoded in a specific encoding. If
|
2015-07-29 15:04:36 -03:00
|
|
|
encoding is not specified, the default is platform dependent (see
|
|
|
|
:func:`open`). ``'b'`` appended to the mode opens the file in
|
2008-08-08 04:04:38 -03:00
|
|
|
:dfn:`binary mode`: now the data is read and written in the form of bytes
|
|
|
|
objects. This mode should be used for all files that don't contain text.
|
2007-09-25 22:10:12 -03:00
|
|
|
|
2012-10-18 00:17:41 -03:00
|
|
|
In text mode, the default when reading is to convert platform-specific line
|
|
|
|
endings (``\n`` on Unix, ``\r\n`` on Windows) to just ``\n``. When writing in
|
|
|
|
text mode, the default is to convert occurrences of ``\n`` back to
|
|
|
|
platform-specific line endings. This behind-the-scenes modification
|
2008-08-08 04:04:38 -03:00
|
|
|
to file data is fine for text files, but will corrupt binary data like that in
|
|
|
|
:file:`JPEG` or :file:`EXE` files. Be very careful to use binary mode when
|
|
|
|
reading and writing such files.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2017-06-13 02:31:01 -03:00
|
|
|
It is good practice to use the :keyword:`with` keyword when dealing
|
|
|
|
with file objects. The advantage is that the file is properly closed
|
|
|
|
after its suite finishes, even if an exception is raised at some
|
2018-12-19 02:09:46 -04:00
|
|
|
point. Using :keyword:`!with` is also much shorter than writing
|
2017-06-13 02:31:01 -03:00
|
|
|
equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
|
|
|
|
|
|
|
|
>>> with open('workfile') as f:
|
|
|
|
... read_data = f.read()
|
2019-04-17 09:18:37 -03:00
|
|
|
|
|
|
|
>>> # We can check that the file has been automatically closed.
|
2017-06-13 02:31:01 -03:00
|
|
|
>>> f.closed
|
|
|
|
True
|
|
|
|
|
|
|
|
If you're not using the :keyword:`with` keyword, then you should call
|
|
|
|
``f.close()`` to close the file and immediately free up any system
|
2020-11-26 20:41:32 -04:00
|
|
|
resources used by it.
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
Calling ``f.write()`` without using the :keyword:`!with` keyword or calling
|
|
|
|
``f.close()`` **might** result in the arguments
|
|
|
|
of ``f.write()`` not being completely written to the disk, even if the
|
|
|
|
program exits successfully.
|
|
|
|
|
|
|
|
..
|
|
|
|
See also https://bugs.python.org/issue17852
|
2017-06-13 02:31:01 -03:00
|
|
|
|
|
|
|
After a file object is closed, either by a :keyword:`with` statement
|
|
|
|
or by 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 <module>
|
2018-07-10 21:11:34 -03:00
|
|
|
ValueError: I/O operation on closed file.
|
2017-06-13 02:31:01 -03:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. _tut-filemethods:
|
|
|
|
|
|
|
|
Methods of File Objects
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
The rest of the examples in this section will assume that a file object called
|
|
|
|
``f`` has already been created.
|
|
|
|
|
|
|
|
To read a file's contents, call ``f.read(size)``, which reads some quantity of
|
2016-01-12 05:27:30 -04:00
|
|
|
data and returns it as a string (in text mode) or bytes object (in binary mode).
|
|
|
|
*size* is an optional numeric argument. When *size* is omitted or negative, the
|
|
|
|
entire contents of the file will be read and returned; it's your problem if the
|
2019-09-10 11:50:26 -03:00
|
|
|
file is twice as large as your machine's memory. Otherwise, at most *size*
|
|
|
|
characters (in text mode) or *size* bytes (in binary mode) are read and returned.
|
2008-08-08 04:04:38 -03:00
|
|
|
If the end of the file has been reached, ``f.read()`` will return an empty
|
|
|
|
string (``''``). ::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> f.read()
|
|
|
|
'This is the entire file.\n'
|
|
|
|
>>> f.read()
|
|
|
|
''
|
|
|
|
|
|
|
|
``f.readline()`` reads a single line from the file; a newline character (``\n``)
|
|
|
|
is left at the end of the string, and is only omitted on the last line of the
|
|
|
|
file if the file doesn't end in a newline. This makes the return value
|
|
|
|
unambiguous; if ``f.readline()`` returns an empty string, the end of the file
|
|
|
|
has been reached, while a blank line is represented by ``'\n'``, a string
|
2008-08-08 04:04:38 -03:00
|
|
|
containing only a single newline. ::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> f.readline()
|
|
|
|
'This is the first line of the file.\n'
|
|
|
|
>>> f.readline()
|
|
|
|
'Second line of the file\n'
|
|
|
|
>>> f.readline()
|
|
|
|
''
|
|
|
|
|
2013-04-15 13:08:31 -03:00
|
|
|
For reading lines from a file, you can loop over the file object. This is memory
|
|
|
|
efficient, fast, and leads to simple code::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> for line in f:
|
2008-08-08 04:04:38 -03:00
|
|
|
... print(line, end='')
|
|
|
|
...
|
2007-08-15 11:28:22 -03:00
|
|
|
This is the first line of the file.
|
|
|
|
Second line of the file
|
|
|
|
|
2013-04-15 13:08:31 -03:00
|
|
|
If you want to read all the lines of a file in a list you can also use
|
|
|
|
``list(f)`` or ``f.readlines()``.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
``f.write(string)`` writes the contents of *string* to the file, returning
|
2008-08-08 04:04:38 -03:00
|
|
|
the number of characters written. ::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> f.write('This is a test\n')
|
2008-08-08 04:04:38 -03:00
|
|
|
15
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2016-01-12 05:27:30 -04:00
|
|
|
Other types of objects need to be converted -- either to a string (in text mode)
|
|
|
|
or a bytes object (in binary mode) -- before writing them::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
>>> value = ('the answer', 42)
|
2016-01-12 05:27:30 -04:00
|
|
|
>>> s = str(value) # convert the tuple to string
|
2007-08-15 11:28:22 -03:00
|
|
|
>>> f.write(s)
|
2008-08-08 04:04:38 -03:00
|
|
|
18
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-07-30 16:51:57 -03:00
|
|
|
``f.tell()`` returns an integer giving the file object's current position in the file
|
2014-10-30 18:26:26 -03:00
|
|
|
represented as number of bytes from the beginning of the file when in binary mode and
|
|
|
|
an opaque number when in text mode.
|
2013-07-30 16:51:57 -03:00
|
|
|
|
2019-09-14 17:29:23 -03:00
|
|
|
To change the file object's position, use ``f.seek(offset, whence)``. The position is computed
|
2007-08-15 11:28:22 -03:00
|
|
|
from adding *offset* to a reference point; the reference point is selected by
|
2019-09-14 17:29:23 -03:00
|
|
|
the *whence* argument. A *whence* value of 0 measures from the beginning
|
2007-08-15 11:28:22 -03:00
|
|
|
of the file, 1 uses the current file position, and 2 uses the end of the file as
|
2019-09-14 17:29:23 -03:00
|
|
|
the reference point. *whence* can be omitted and defaults to 0, using the
|
2007-08-15 11:28:22 -03:00
|
|
|
beginning of the file as the reference point. ::
|
|
|
|
|
2013-02-23 14:26:56 -04:00
|
|
|
>>> f = open('workfile', 'rb+')
|
2008-08-08 04:04:38 -03:00
|
|
|
>>> f.write(b'0123456789abcdef')
|
|
|
|
16
|
2016-05-10 06:01:23 -03:00
|
|
|
>>> f.seek(5) # Go to the 6th byte in the file
|
2008-08-08 04:04:38 -03:00
|
|
|
5
|
2009-01-03 17:18:54 -04:00
|
|
|
>>> f.read(1)
|
2008-08-08 04:04:38 -03:00
|
|
|
b'5'
|
2016-05-10 06:01:23 -03:00
|
|
|
>>> f.seek(-3, 2) # Go to the 3rd byte before the end
|
2008-08-08 04:04:38 -03:00
|
|
|
13
|
2007-08-15 11:28:22 -03:00
|
|
|
>>> f.read(1)
|
2008-08-08 04:04:38 -03:00
|
|
|
b'd'
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2008-08-08 04:04:38 -03:00
|
|
|
In text files (those opened without a ``b`` in the mode string), only seeks
|
|
|
|
relative to the beginning of the file are allowed (the exception being seeking
|
2013-07-30 16:51:57 -03:00
|
|
|
to the very file end with ``seek(0, 2)``) and the only valid *offset* values are
|
|
|
|
those returned from the ``f.tell()``, or zero. Any other *offset* value produces
|
|
|
|
undefined behaviour.
|
|
|
|
|
Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line
#6513: fix example code: warning categories are classes, not instances.
........
r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line
#6489: fix an ambiguity in getiterator() documentation.
........
r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line
remove docs for deprecated -p option
........
r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line
use bools
........
r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line
Fix arg types of et#.
........
r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line
Dont put "void" in signature for nullary functions.
........
r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line
#6571: add index entries for more operators.
........
r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
2009-07-29 16:54:39 -03:00
|
|
|
File objects have some additional methods, such as :meth:`~file.isatty` and
|
|
|
|
:meth:`~file.truncate` which are less frequently used; consult the Library
|
|
|
|
Reference for a complete guide to file objects.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
.. _tut-json:
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
Saving structured data with :mod:`json`
|
|
|
|
---------------------------------------
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
.. index:: module: json
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
Strings can easily be written to and read from a file. Numbers take a bit more
|
2007-08-15 11:28:22 -03:00
|
|
|
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'``
|
2013-12-05 18:46:32 -04:00
|
|
|
and returns its numeric value 123. When you want to save more complex data
|
|
|
|
types like nested lists and dictionaries, parsing and serializing by hand
|
|
|
|
becomes complicated.
|
|
|
|
|
|
|
|
Rather than having users constantly writing and debugging code to save
|
|
|
|
complicated data types to files, Python allows you to use the popular data
|
|
|
|
interchange format called `JSON (JavaScript Object Notation)
|
|
|
|
<http://json.org>`_. The standard module called :mod:`json` can take Python
|
|
|
|
data hierarchies, and convert them to string representations; this process is
|
|
|
|
called :dfn:`serializing`. Reconstructing the data from the string representation
|
|
|
|
is called :dfn:`deserializing`. Between serializing and deserializing, the
|
|
|
|
string representing the object may have been stored in a file or data, or
|
2007-08-15 11:28:22 -03:00
|
|
|
sent over a network connection to some distant machine.
|
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
.. note::
|
|
|
|
The JSON format is commonly used by modern applications to allow for data
|
|
|
|
exchange. Many programmers are already familiar with it, which makes
|
|
|
|
it a good choice for interoperability.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
If you have an object ``x``, you can view its JSON string representation with a
|
|
|
|
simple line of code::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2017-06-11 22:42:59 -03:00
|
|
|
>>> import json
|
2021-05-18 18:56:01 -03:00
|
|
|
>>> x = [1, 'simple', 'list']
|
|
|
|
>>> json.dumps(x)
|
2013-12-05 18:46:32 -04:00
|
|
|
'[1, "simple", "list"]'
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
Another variant of the :func:`~json.dumps` function, called :func:`~json.dump`,
|
|
|
|
simply serializes the object to a :term:`text file`. So if ``f`` is a
|
|
|
|
:term:`text file` object opened for writing, we can do this::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
json.dump(x, f)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
To decode the object again, if ``f`` is a :term:`text file` object which has
|
|
|
|
been opened for reading::
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2013-12-05 18:46:32 -04:00
|
|
|
x = json.load(f)
|
|
|
|
|
|
|
|
This simple serialization technique can handle lists and dictionaries, but
|
|
|
|
serializing arbitrary class instances in JSON requires a bit of extra effort.
|
|
|
|
The reference for the :mod:`json` module contains an explanation of this.
|
|
|
|
|
|
|
|
.. seealso::
|
|
|
|
|
|
|
|
:mod:`pickle` - the pickle module
|
|
|
|
|
|
|
|
Contrary to :ref:`JSON <tut-json>`, *pickle* is a protocol which allows
|
|
|
|
the serialization of arbitrarily complex Python objects. As such, it is
|
|
|
|
specific to Python and cannot be used to communicate with applications
|
|
|
|
written in other languages. It is also insecure by default:
|
|
|
|
deserializing pickle data coming from an untrusted source can execute
|
|
|
|
arbitrary code, if the data was crafted by a skilled attacker.
|