Mercurial > cpython-lru_cache-weakref

annotate Lib/io.py @ 79691:05c8928362ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge __next__ method link fixes with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 12 Oct 2012 13:46:37 +0300
parents d533663caee8
children 15a391919deb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
46448
59753bdce089 Fix problems in the io docs noted by Alexandre Vassalotti
Benjamin Peterson <benjamin@python.org>
parents: 46418
diff changeset
1 """The io module provides the Python interfaces to stream handling. The
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
2 builtin open function is defined in this module.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
3
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
4 At the top of the I/O hierarchy is the abstract base class IOBase. It
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
5 defines the basic interface to a stream. Note, however, that there is no
51776
d06a3ebf306f Merged revisions 69846 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 51533
diff changeset
6 separation between reading and writing to streams; implementations are
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
7 allowed to throw an IOError if they do not support a given operation.
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
9 Extending IOBase is RawIOBase which deals simply with the reading and
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
10 writing of raw bytes to a stream. FileIO subclasses RawIOBase to provide
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
11 an interface to OS files.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
12
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
13 BufferedIOBase deals with buffering on a raw byte stream (RawIOBase). Its
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
14 subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
15 streams that are readable, writable, and both respectively.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
16 BufferedRandom provides a buffered interface to random access
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
17 streams. BytesIO is a simple stream of in-memory bytes.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
18
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
19 Another IOBase subclass, TextIOBase, deals with the encoding and decoding
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
20 of streams into text. TextIOWrapper, which extends it, is a buffered text
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
21 interface to a buffered raw stream (`BufferedIOBase`). Finally, StringIO
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
22 is a in-memory stream for text.
40969
6c0d0be82b47 Added some comments and docstrings. More is needed.
Guido van Rossum <guido@python.org>
parents: 40964
diff changeset
23
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
24 Argument names are not part of the specification, and only the arguments
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
25 of open() are intended to be used as keyword arguments.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
26
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
27 data:
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
28
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
29 DEFAULT_BUFFER_SIZE
41204
a312c276a5e7 Add some XXX comments and fix BufferedReader signature.
Guido van Rossum <guido@python.org>
parents: 41064
diff changeset
30
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
31 An int containing the default buffer size used by the module's buffered
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
32 I/O classes. open() uses the file's blksize (as obtained by os.stat) if
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
33 possible.
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 """
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
35 # New I/O library conforming to PEP 3116.
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
36
40973
46f771e267bc Mike Verdone's checkpoint, cleaned up.
Guido van Rossum <guido@python.org>
parents: 40969
diff changeset
37 __author__ = ("Guido van Rossum <guido@python.org>, "
41395
9120281241b8 Added a working Text I/O layer, by Mark Russell.
Guido van Rossum <guido@python.org>
parents: 41223
diff changeset
38 "Mike Verdone <mike.verdone@gmail.com>, "
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
39 "Mark Russell <mark.russell@zen.co.uk>, "
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
40 "Antoine Pitrou <solipsis@pitrou.net>, "
53650
89d5ef82c006 add myself
Benjamin Peterson <benjamin@python.org>
parents: 53617
diff changeset
41 "Amaury Forgeot d'Arc <amauryfa@gmail.com>, "
89d5ef82c006 add myself
Benjamin Peterson <benjamin@python.org>
parents: 53617
diff changeset
42 "Benjamin Peterson <benjamin@python.org>")
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
43
41415
f4391abe5b02 More cleanup. Renamed BlockingIO to BlockingIOError.
Guido van Rossum <guido@python.org>
parents: 41408
diff changeset
44 __all__ = ["BlockingIOError", "open", "IOBase", "RawIOBase", "FileIO",
42904
cd235027e64c Changes to io.py and socket.py by Christian Heimes.
Guido van Rossum <guido@python.org>
parents: 42697
diff changeset
45 "BytesIO", "StringIO", "BufferedIOBase",
41045
21233c2e5d09 New version from Mike Verdone (sat in my inbox since 2/27).
Guido van Rossum <guido@python.org>
parents: 40973
diff changeset
46 "BufferedReader", "BufferedWriter", "BufferedRWPair",
52685
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
47 "BufferedRandom", "TextIOBase", "TextIOWrapper",
53617
b39cb2921945 add UnsupportedOperation to __all__
Benjamin Peterson <benjamin@python.org>
parents: 52685
diff changeset
48 "UnsupportedOperation", "SEEK_SET", "SEEK_CUR", "SEEK_END"]
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
49
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
50
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
51 import _io
42697
0081dbacb7aa Make IOBase (and hence all other classes in io.py) use ABCMeta as its metaclass,
Guido van Rossum <guido@python.org>
parents: 42667
diff changeset
52 import abc
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
52047
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
54 from _io import (DEFAULT_BUFFER_SIZE, BlockingIOError, UnsupportedOperation,
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
55 open, FileIO, BytesIO, StringIO, BufferedReader,
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
56 BufferedWriter, BufferedRWPair, BufferedRandom,
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
57 IncrementalNewlineDecoder, TextIOWrapper)
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
58
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
59 OpenWrapper = _io.open # for compatibility with _pyio
40969
6c0d0be82b47 Added some comments and docstrings. More is needed.
Guido van Rossum <guido@python.org>
parents: 40964
diff changeset
60
76830
2cd9dadd5c6c explicitly set UnsupportedOperation's module rather than relying on incorrect globals on startup (closes #14745)
Benjamin Peterson <benjamin@python.org>
parents: 53650
diff changeset
61 # Pretend this exception was created here.
2cd9dadd5c6c explicitly set UnsupportedOperation's module rather than relying on incorrect globals on startup (closes #14745)
Benjamin Peterson <benjamin@python.org>
parents: 53650
diff changeset
62 UnsupportedOperation.__module__ = "io"
2cd9dadd5c6c explicitly set UnsupportedOperation's module rather than relying on incorrect globals on startup (closes #14745)
Benjamin Peterson <benjamin@python.org>
parents: 53650
diff changeset
63
52685
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
64 # for seek()
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
65 SEEK_SET = 0
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
66 SEEK_CUR = 1
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
67 SEEK_END = 2
9ed9d2041306 Merged revisions 70992,70995 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52047
diff changeset
68
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
69 # Declaring ABCs in C is tricky so we do it here.
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
70 # Method descriptions and default implementations are inherited from the C
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
71 # version however.
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
72 class IOBase(_io._IOBase, metaclass=abc.ABCMeta):
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
73 pass
46418
3307a5450c37 Fleshed out docstrings in the io module, improving the reST one as I went.
Benjamin Peterson <benjamin@python.org>
parents: 46375
diff changeset
74
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
75 class RawIOBase(_io._RawIOBase, IOBase):
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
76 pass
40963
c24e95d11752 Checkpoint for new I/O library.
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
78 class BufferedIOBase(_io._BufferedIOBase, IOBase):
42172
3db0083f6683 Add proper tests for closed files to various I/O operations,
Guido van Rossum <guido@python.org>
parents: 42168
diff changeset
79 pass
3db0083f6683 Add proper tests for closed files to various I/O operations,
Guido van Rossum <guido@python.org>
parents: 42168
diff changeset
80
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
81 class TextIOBase(_io._TextIOBase, IOBase):
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
82 pass
46694
cda816c3a1e4 Added fast alternate io.BytesIO implementation and its test suite.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46690
diff changeset
83
51991
3049ac17e256 merge the io-c branch: C implementation of the io module
Benjamin Peterson <benjamin@python.org>
parents: 51776
diff changeset
84 RawIOBase.register(FileIO)
47625
1bfea956d0d7 Issue 2918: Merge StringIO and cStringIO.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 47285
diff changeset
85
52047
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
86 for klass in (BytesIO, BufferedReader, BufferedWriter, BufferedRandom,
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
87 BufferedRWPair):
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
88 BufferedIOBase.register(klass)
47625
1bfea956d0d7 Issue 2918: Merge StringIO and cStringIO.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 47285
diff changeset
89
52047
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
90 for klass in (StringIO, TextIOWrapper):
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
91 TextIOBase.register(klass)
90a66915ca91 simplify and beautify code
Benjamin Peterson <benjamin@python.org>
parents: 52001
diff changeset
92 del klass