pipe).
All streams are careful about the type of data you give to them. For example
-giving a :class:`str` object to the ``write()`` method of a binary stream
+giving a :class:`str` object to the :meth:`!write` method of a binary stream
will raise a :exc:`TypeError`. So will giving a :class:`bytes` object to the
-``write()`` method of a text stream.
+:meth:`!write` method of a text stream.
.. versionchanged:: 3.3
Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since
See :pep:`597` for more details.
To find where the default locale encoding is used, you can enable
-the ``-X warn_default_encoding`` command line option or set the
+the :option:`-X warn_default_encoding <-X>` command line option or set the
:envvar:`PYTHONWARNDEFAULTENCODING` environment variable, which will
emit an :exc:`EncodingWarning` when the default encoding is used.
.. audit-event:: open path,mode,flags io.open
This function raises an :ref:`auditing event <auditing>` ``open`` with
- arguments ``path``, ``mode`` and ``flags``. The ``mode`` and ``flags``
+ arguments *path*, *mode* and *flags*. The *mode* and *flags*
arguments may have been modified or inferred from the original call.
Opens the provided file with mode ``'rb'``. This function should be used
when the intent is to treat the contents as executable code.
- ``path`` should be a :class:`str` and an absolute path.
+ *path* should be a :class:`str` and an absolute path.
The behavior of this function may be overridden by an earlier call to the
- :c:func:`PyFile_SetOpenCodeHook`. However, assuming that ``path`` is a
+ :c:func:`PyFile_SetOpenCodeHook`. However, assuming that *path* is a
:class:`str` and an absolute path, ``open_code(path)`` should always behave
the same as ``open(path, 'rb')``. Overriding the behavior is intended for
additional validation or preprocessing of the file.
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes. For
example, :class:`BufferedIOBase` provides unoptimized implementations of
- :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
+ :meth:`!readinto` and :meth:`!readline`.
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
defines the basic interface to a stream. Note, however, that there is no
implementations represent a file that cannot be read, written or
seeked.
- Even though :class:`IOBase` does not declare :meth:`read`
- or :meth:`write` because their signatures will vary, implementations and
+ Even though :class:`IOBase` does not declare :meth:`!read`
+ or :meth:`!write` because their signatures will vary, implementations and
clients should consider those methods part of the interface. Also,
implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`)
when operations they do not support are called.
.. method:: readable()
- Return ``True`` if the stream can be read from. If ``False``, :meth:`read`
- will raise :exc:`OSError`.
+ Return ``True`` if the stream can be read from.
+ If ``False``, :meth:`!read` will raise :exc:`OSError`.
.. method:: readline(size=-1, /)
hint.
Note that it's already possible to iterate on file objects using ``for
- line in file: ...`` without calling ``file.readlines()``.
+ line in file: ...`` without calling :meth:`!file.readlines`.
.. method:: seek(offset, whence=SEEK_SET, /)
Change the stream position to the given byte *offset*. *offset* is
interpreted relative to the position indicated by *whence*. The default
- value for *whence* is :data:`SEEK_SET`. Values for *whence* are:
+ value for *whence* is :data:`!SEEK_SET`. Values for *whence* are:
- * :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
+ * :data:`!SEEK_SET` or ``0`` -- start of the stream (the default);
*offset* should be zero or positive
- * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
+ * :data:`!SEEK_CUR` or ``1`` -- current stream position; *offset* may
be negative
- * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
+ * :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually
negative
Return the new absolute position.
.. versionadded:: 3.1
- The ``SEEK_*`` constants.
+ The :data:`!SEEK_*` constants.
.. versionadded:: 3.3
Some operating systems could support additional values, like
.. method:: writable()
Return ``True`` if the stream supports writing. If ``False``,
- :meth:`write` and :meth:`truncate` will raise :exc:`OSError`.
+ :meth:`!write` and :meth:`truncate` will raise :exc:`OSError`.
.. method:: writelines(lines, /)
implies writing, so this mode behaves in a similar way to ``'w'``. Add a
``'+'`` to the mode to allow simultaneous reading and writing.
- The :meth:`read` (when called with a positive argument), :meth:`readinto`
- and :meth:`write` methods on this class will only make one system call.
+ The :meth:`~RawIOBase.read` (when called with a positive argument),
+ :meth:`~RawIOBase.readinto` and :meth:`~RawIOBase.write` methods on this
+ class will only make one system call.
A custom opener can be used by passing a callable as *opener*. The underlying
file descriptor for the file object is then obtained by calling *opener* with
object under various conditions, including:
* when the buffer gets too small for all pending data;
- * when :meth:`flush()` is called;
- * when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
+ * when :meth:`flush` is called;
+ * when a :meth:`~IOBase.seek` is requested (for :class:`BufferedRandom` objects);
* when the :class:`BufferedWriter` object is closed or destroyed.
The constructor creates a :class:`BufferedWriter` for the given writeable
:data:`DEFAULT_BUFFER_SIZE`.
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
- :class:`BufferedWriter` can do. In addition, :meth:`seek` and :meth:`tell`
- are guaranteed to be implemented.
+ :class:`BufferedWriter` can do. In addition, :meth:`~IOBase.seek` and
+ :meth:`~IOBase.tell` are guaranteed to be implemented.
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)
.. method:: readline(size=-1, /)
- Read until newline or EOF and return a single ``str``. If the stream is
+ Read until newline or EOF and return a single :class:`str`. If the stream is
already at EOF, an empty string is returned.
If *size* is specified, at most *size* characters will be read.
Change the stream position to the given *offset*. Behaviour depends on
the *whence* parameter. The default value for *whence* is
- :data:`SEEK_SET`.
+ :data:`!SEEK_SET`.
- * :data:`SEEK_SET` or ``0``: seek from the start of the stream
+ * :data:`!SEEK_SET` or ``0``: seek from the start of the stream
(the default); *offset* must either be a number returned by
:meth:`TextIOBase.tell`, or zero. Any other *offset* value
produces undefined behaviour.
- * :data:`SEEK_CUR` or ``1``: "seek" to the current position;
+ * :data:`!SEEK_CUR` or ``1``: "seek" to the current position;
*offset* must be zero, which is a no-operation (all other values
are unsupported).
- * :data:`SEEK_END` or ``2``: seek to the end of the stream;
+ * :data:`!SEEK_END` or ``2``: seek to the end of the stream;
*offset* must be zero (all other values are unsupported).
Return the new absolute position as an opaque number.
.. versionadded:: 3.1
- The ``SEEK_*`` constants.
+ The :data:`!SEEK_*` constants.
.. method:: tell()
takes place. If *newline* is any of the other legal values, any ``'\n'``
characters written are translated to the given string.
- If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
+ If *line_buffering* is ``True``, :meth:`~IOBase.flush` is implied when a call to
write contains a newline character or a carriage return.
- If *write_through* is ``True``, calls to :meth:`write` are guaranteed
+ If *write_through* is ``True``, calls to :meth:`~BufferedIOBase.write` are guaranteed
not to be buffered: any data written on the :class:`TextIOWrapper`
object is immediately handled to its underlying binary *buffer*.
.. method:: getvalue()
- Return a ``str`` containing the entire contents of the buffer.
+ Return a :class:`str` containing the entire contents of the buffer.
Newlines are decoded as if by :meth:`~TextIOBase.read`, although
the stream position is not changed.
binary I/O over the same storage, because it requires conversions between
unicode and binary data using a character codec. This can become noticeable
handling huge amounts of text data like large log files. Also,
-:meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both quite slow
+:meth:`~TextIOBase.tell` and :meth:`~TextIOBase.seek` are both quite slow
due to the reconstruction algorithm used.
:class:`StringIO`, however, is a native in-memory unicode container and will
^^^^^^^^^^^^^^^
:class:`FileIO` objects are thread-safe to the extent that the operating system
-calls (such as ``read(2)`` under Unix) they wrap are thread-safe too.
+calls (such as :manpage:`read(2)` under Unix) they wrap are thread-safe too.
Binary buffered objects (instances of :class:`BufferedReader`,
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)
projects / thirdparty / Python / cpython.git / commitdiff
