blob: fbce6efc010c07c78bcf7b4458d5f7f22cd6f0ba [file] [log] [blame]
Benjamin Peterson9efcc4b2008-04-14 21:30:21 +00001"""The io module provides the Python interfaces to stream handling. The
Benjamin Peterson2c5f8282008-04-13 00:27:46 +00002builtin open function is defined in this module.
3
4At the top of the I/O hierarchy is the abstract base class IOBase. It
5defines the basic interface to a stream. Note, however, that there is no
Mark Dickinson934896d2009-02-21 20:59:32 +00006separation between reading and writing to streams; implementations are
Andrew Svetlovf7a17b42012-12-25 16:47:37 +02007allowed to raise an OSError if they do not support a given operation.
Benjamin Peterson2c5f8282008-04-13 00:27:46 +00008
9Extending IOBase is RawIOBase which deals simply with the reading and
10writing of raw bytes to a stream. FileIO subclasses RawIOBase to provide
11an interface to OS files.
12
13BufferedIOBase deals with buffering on a raw byte stream (RawIOBase). Its
14subclasses, BufferedWriter, BufferedReader, and BufferedRWPair buffer
15streams that are readable, writable, and both respectively.
16BufferedRandom provides a buffered interface to random access
17streams. BytesIO is a simple stream of in-memory bytes.
18
19Another IOBase subclass, TextIOBase, deals with the encoding and decoding
20of streams into text. TextIOWrapper, which extends it, is a buffered text
21interface to a buffered raw stream (`BufferedIOBase`). Finally, StringIO
Martin Panter7462b6492015-11-02 03:37:02 +000022is an in-memory stream for text.
Benjamin Peterson2c5f8282008-04-13 00:27:46 +000023
24Argument names are not part of the specification, and only the arguments
25of open() are intended to be used as keyword arguments.
26
27data:
28
29DEFAULT_BUFFER_SIZE
30
31 An int containing the default buffer size used by the module's buffered
32 I/O classes. open() uses the file's blksize (as obtained by os.stat) if
33 possible.
34"""
35# New I/O library conforming to PEP 3116.
36
Guido van Rossum68bbcd22007-02-27 17:19:33 +000037__author__ = ("Guido van Rossum <guido@python.org>, "
Guido van Rossum78892e42007-04-06 17:31:18 +000038 "Mike Verdone <mike.verdone@gmail.com>, "
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000039 "Mark Russell <mark.russell@zen.co.uk>, "
40 "Antoine Pitrou <solipsis@pitrou.net>, "
Benjamin Petersonef9f2bd2009-05-01 20:45:43 +000041 "Amaury Forgeot d'Arc <amauryfa@gmail.com>, "
42 "Benjamin Peterson <benjamin@python.org>")
Guido van Rossum28524c72007-02-27 05:47:44 +000043
Steve Dowerb82e17e2019-05-23 08:45:22 -070044__all__ = ["BlockingIOError", "open", "open_code", "IOBase", "RawIOBase",
45 "FileIO", "BytesIO", "StringIO", "BufferedIOBase",
Guido van Rossum01a27522007-03-07 01:00:12 +000046 "BufferedReader", "BufferedWriter", "BufferedRWPair",
Benjamin Peterson0e4caf42009-04-01 21:22:20 +000047 "BufferedRandom", "TextIOBase", "TextIOWrapper",
Benjamin Petersone12ef042009-04-29 21:53:47 +000048 "UnsupportedOperation", "SEEK_SET", "SEEK_CUR", "SEEK_END"]
Guido van Rossum28524c72007-02-27 05:47:44 +000049
Christian Heimesdeb75f52008-08-15 18:43:03 +000050
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000051import _io
52import abc
Guido van Rossum28524c72007-02-27 05:47:44 +000053
Benjamin Peterson113f6072009-03-06 23:59:29 +000054from _io import (DEFAULT_BUFFER_SIZE, BlockingIOError, UnsupportedOperation,
Steve Dowerb82e17e2019-05-23 08:45:22 -070055 open, open_code, FileIO, BytesIO, StringIO, BufferedReader,
Benjamin Peterson113f6072009-03-06 23:59:29 +000056 BufferedWriter, BufferedRWPair, BufferedRandom,
57 IncrementalNewlineDecoder, TextIOWrapper)
58
59OpenWrapper = _io.open # for compatibility with _pyio
Guido van Rossum01a27522007-03-07 01:00:12 +000060
Benjamin Petersonbbf83932012-05-07 22:19:42 -040061# Pretend this exception was created here.
62UnsupportedOperation.__module__ = "io"
63
Benjamin Peterson0e4caf42009-04-01 21:22:20 +000064# for seek()
65SEEK_SET = 0
66SEEK_CUR = 1
67SEEK_END = 2
68
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000069# Declaring ABCs in C is tricky so we do it here.
70# Method descriptions and default implementations are inherited from the C
71# version however.
72class IOBase(_io._IOBase, metaclass=abc.ABCMeta):
Andrew Kuchling86fe53e2014-04-25 09:29:30 -040073 __doc__ = _io._IOBase.__doc__
Guido van Rossum4b5386f2007-07-10 09:12:49 +000074
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000075class RawIOBase(_io._RawIOBase, IOBase):
Andrew Kuchling86fe53e2014-04-25 09:29:30 -040076 __doc__ = _io._RawIOBase.__doc__
Guido van Rossum4b5386f2007-07-10 09:12:49 +000077
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000078class BufferedIOBase(_io._BufferedIOBase, IOBase):
Andrew Kuchling86fe53e2014-04-25 09:29:30 -040079 __doc__ = _io._BufferedIOBase.__doc__
Guido van Rossum28524c72007-02-27 05:47:44 +000080
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000081class TextIOBase(_io._TextIOBase, IOBase):
Andrew Kuchling86fe53e2014-04-25 09:29:30 -040082 __doc__ = _io._TextIOBase.__doc__
Guido van Rossum17e43e52007-02-27 15:45:13 +000083
Benjamin Peterson4fa88fa2009-03-04 00:14:51 +000084RawIOBase.register(FileIO)
Guido van Rossum53807da2007-04-10 19:01:47 +000085
Benjamin Peterson113f6072009-03-06 23:59:29 +000086for klass in (BytesIO, BufferedReader, BufferedWriter, BufferedRandom,
87 BufferedRWPair):
88 BufferedIOBase.register(klass)
Benjamin Peterson2c5f8282008-04-13 00:27:46 +000089
Benjamin Peterson113f6072009-03-06 23:59:29 +000090for klass in (StringIO, TextIOWrapper):
91 TextIOBase.register(klass)
92del klass
Steve Dower39294992016-08-30 21:22:36 -070093
94try:
95 from _io import _WindowsConsoleIO
96except ImportError:
97 pass
98else:
99 RawIOBase.register(_WindowsConsoleIO)