Mercurial > cpython-lru_cache-weakref

annotate Lib/io.py @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 72df255a7716
children 8c2635afbfe1
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
55049
74c0a78114ae Merged revisions 69846 via svnmerge from
Jesus Cea <jcea@jcea.es>
parents: 54722
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
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
37 __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
38 "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
39 "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
40 "Antoine Pitrou <solipsis@pitrou.net>, "
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
41 "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
42 "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
43
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
44 __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
45 "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
46 "BufferedReader", "BufferedWriter", "BufferedRWPair",
52684
3b34c9374955 add seek constants to __all__
Benjamin Peterson <benjamin@python.org>
parents: 52681
diff changeset
47 "BufferedRandom", "TextIOBase", "TextIOWrapper",
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
48 "UnsupportedOperation", "SEEK_SET", "SEEK_CUR", "SEEK_END"]
46805
4c5ee1b38045 Backport fast alternate io.BytesIO implementation.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46663
diff changeset
49
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
50
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
51 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
52 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
53
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
54 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
55 open, FileIO, BytesIO, StringIO, BufferedReader,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
56 BufferedWriter, BufferedRWPair, BufferedRandom,
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
57 IncrementalNewlineDecoder, TextIOWrapper)
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 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
60
52681
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
61 # for seek()
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
62 SEEK_SET = 0
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
63 SEEK_CUR = 1
9e579bab76f1 #4572: add SEEK_* values as constants in io.py.
Georg Brandl <georg@python.org>
parents: 51775
diff changeset
64 SEEK_END = 2
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
65
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
66 # 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
67 # 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
68 # version however.
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
69 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
70 __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
71
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
72 class RawIOBase(_io._RawIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
73 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
74
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
75 class BufferedIOBase(_io._BufferedIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
76 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
77
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
78 class TextIOBase(_io._TextIOBase, IOBase):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
79 pass
46805
4c5ee1b38045 Backport fast alternate io.BytesIO implementation.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46663
diff changeset
80
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
81 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
82
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
83 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
84 BufferedRWPair):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
85 BufferedIOBase.register(klass)
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
86
54717
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
87 for klass in (StringIO, TextIOWrapper):
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
88 TextIOBase.register(klass)
760a710eb6c1 Issue #6215: backport the 3.1 io lib
Antoine Pitrou <solipsis@pitrou.net>
parents: 52684
diff changeset
89 del klass