Mercurial > cpython-lru_cache-weakref

annotate Lib/io.py @ 58765:2ba7677bfa95 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
testCopysign was defined twice in test_math; combine the definitions
author Mark Dickinson <dickinsm@gmail.com>
date Sat, 06 Feb 2010 23:11:25 +0000
parents 760a710eb6c1
children b36cb4602e21
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
1 """The io module provides the Python interfaces to stream handling. The
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
2 builtin open function is defined in this module.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
3
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
4 At the top of the I/O hierarchy is the abstract base class IOBase. It
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
5 defines the basic interface to a stream. Note, however, that there is no
51775
af9b6c43804e Issue #5341: Fix a variety of spelling errors.
Mark Dickinson <dickinsm@gmail.com>
parents: 50305
diff changeset
6 separation between reading and writing to streams; implementations are
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
7 allowed to throw an IOError if they do not support a given operation.
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
8
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
9 Extending IOBase is RawIOBase which deals simply with the reading and
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
10 writing of raw bytes to a stream. FileIO subclasses RawIOBase to provide
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
11 an interface to OS files.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
12
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
13 BufferedIOBase deals with buffering on a raw byte stream (RawIOBase). Its
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
14 subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
15 streams that are readable, writable, and both respectively.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
16 BufferedRandom provides a buffered interface to random access
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
17 streams. BytesIO is a simple stream of in-memory bytes.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
18
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
19 Another IOBase subclass, TextIOBase, deals with the encoding and decoding
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
20 of streams into text. TextIOWrapper, which extends it, is a buffered text
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
21 interface to a buffered raw stream (`BufferedIOBase`). Finally, StringIO
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
22 is a in-memory stream for text.
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
23
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
24 Argument names are not part of the specification, and only the arguments
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
25 of open() are intended to be used as keyword arguments.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
26
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
27 data:
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
28
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
29 DEFAULT_BUFFER_SIZE
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
30
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
31 An int containing the default buffer size used by the module's buffered
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
32 I/O classes. open() uses the file's blksize (as obtained by os.stat) if
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
33 possible.
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
34 """
46420
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
35 # New I/O library conforming to PEP 3116.
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
36
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
37 # XXX edge cases when switching between reading/writing
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
38 # XXX need to support 1 meaning line-buffered
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
39 # XXX whenever an argument is None, use the default value
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
40 # XXX read/write ops should check readable/writable
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
41 # XXX buffered readinto should work with arbitrary buffer objects
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
42 # XXX use incremental encoder for text output, at least for UTF-16 and UTF-8-SIG
b544bb61bca9 Backported io module docs
Benjamin Peterson <benjamin@python.org>
parents: 46124
diff changeset
43 # XXX check writable, readable and seekable in appropriate places
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
44
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
45
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
46 __author__ = ("Guido van Rossum <guido@python.org>, "
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
47 "Mike Verdone <mike.verdone@gmail.com>, "
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
48 "Mark Russell <mark.russell@zen.co.uk>, "
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
49 "Antoine Pitrou <solipsis@pitrou.net>, "
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
50 "Amaury Forgeot d'Arc <amauryfa@gmail.com>, "
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
51 "Benjamin Peterson <benjamin@python.org>")
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
52
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
53 __all__ = ["BlockingIOError", "open", "IOBase", "RawIOBase", "FileIO",
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
54 "BytesIO", "StringIO", "BufferedIOBase",
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
55 "BufferedReader", "BufferedWriter", "BufferedRWPair",
52684
3b34c9374955 add seek constants to __all__
Benjamin Peterson <benjamin@python.org>
parents: 52681
diff changeset
56 "BufferedRandom", "TextIOBase", "TextIOWrapper",
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
57 "UnsupportedOperation", "SEEK_SET", "SEEK_CUR", "SEEK_END"]
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
58
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
59
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
60 import _io
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
61 import abc
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
62
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
63 from _io import (DEFAULT_BUFFER_SIZE, BlockingIOError, UnsupportedOperation,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
64 open, FileIO, BytesIO, StringIO, BufferedReader,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
65 BufferedWriter, BufferedRWPair, BufferedRandom,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
66 IncrementalNewlineDecoder, TextIOWrapper)
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
67
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
68 OpenWrapper = _io.open # for compatibility with _pyio
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
69
52681
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
70 # for seek()
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
71 SEEK_SET = 0
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
72 SEEK_CUR = 1
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
73 SEEK_END = 2
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
74
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
75 # Declaring ABCs in C is tricky so we do it here.
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
76 # Method descriptions and default implementations are inherited from the C
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
77 # version however.
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
78 class IOBase(_io._IOBase):
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
79 __metaclass__ = abc.ABCMeta
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
80
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
81 class RawIOBase(_io._RawIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
82 pass
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
83
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
84 class BufferedIOBase(_io._BufferedIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
85 pass
46805
4c5ee1b38045 Backport fast alternate io.BytesIO implementation.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46663
diff changeset
86
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
87 class TextIOBase(_io._TextIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
88 pass
48238
67938575afc6 Issue #3476: make BufferedReader and BufferedWriter thread-safe
Antoine Pitrou <solipsis@pitrou.net>
parents: 48093
diff changeset
89
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
90 RawIOBase.register(FileIO)
46107
5341b30b1812 Merged revisions 61750,61752,61754,61756,61760,61763,61768,61772,61775,61805,61809,61812,61819,61917,61920,61930,61933-61934 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents:
diff changeset
91
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
92 for klass in (BytesIO, BufferedReader, BufferedWriter, BufferedRandom,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
93 BufferedRWPair):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
94 BufferedIOBase.register(klass)
46805
4c5ee1b38045 Backport fast alternate io.BytesIO implementation.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46663
diff changeset
95
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
96 for klass in (StringIO, TextIOWrapper):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
97 TextIOBase.register(klass)
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
98 del klass