Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-06-04 16:50:51 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-150285: Fix too long docstrings in the io module (GH-150287)

Browse source
This commit is contained in:
Serhiy Storchaka 2026-05-24 15:02:21 +03:00 • committed by GitHub
parent 4c0fe2d134
commit 160dc74122
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 295 additions and 269 deletions
Download patch file Download diff file Expand all files Collapse all files

128
Lib/_pyio.py
View file

@ -83,27 +83,28 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None,
wrapped. (If a file descriptor is given, it is closed when the
returned I/O object is closed, unless closefd is set to False.)
mode is an optional string that specifies the mode in which the file is
opened. It defaults to 'r' which means open for reading in text mode. Other
common values are 'w' for writing (truncating the file if it already
exists), 'x' for exclusive creation of a new file, and 'a' for appending
(which on some Unix systems, means that all writes append to the end of the
file regardless of the current seek position). In text mode, if encoding is
not specified the encoding used is platform dependent. (For reading and
writing raw bytes use binary mode and leave encoding unspecified.) The
available modes are:
mode is an optional string that specifies the mode in which the file
is opened. It defaults to 'r' which means open for reading in text
mode. Other common values are 'w' for writing (truncating the file if
it already exists), 'x' for exclusive creation of a new file, and
'a' for appending (which on some Unix systems, means that all writes
append to the end of the file regardless of the current seek position).
In text mode, if encoding is not specified the encoding used is platform
dependent. (For reading and writing raw bytes use binary mode and leave
encoding unspecified.) The available modes are:
========= ===============================================================
========= ==========================================================
Character Meaning
--------- ---------------------------------------------------------------
--------- ----------------------------------------------------------
'r' open for reading (default)
'w' open for writing, truncating the file first
'x' create a new file and open it for writing
'a' open for writing, appending to the end of the file if it exists
'a' open for writing, appending to the end of the file if it
exists
'b' binary mode
't' text mode (default)
'+' open a disk file for updating (reading and writing)
========= ===============================================================
========= ==========================================================
The default mode is 'rt' (open for reading text). For binary random
access, the mode 'w+b' opens and truncates the file to 0 bytes, while
@ -111,23 +112,23 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None,
raises an `FileExistsError` if the file already exists.
Python distinguishes between files opened in binary and text modes,
even when the underlying operating system doesn't. Files opened in
even when the underlying operating system doesn't. Files opened in
binary mode (appending 'b' to the mode argument) return contents as
bytes objects without any decoding. In text mode (the default, or when
bytes objects without any decoding. In text mode (the default, or when
't' is appended to the mode argument), the contents of the file are
returned as strings, the bytes having been first decoded using a
platform-dependent encoding or using the specified encoding if given.
buffering is an optional integer used to set the buffering policy.
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
line buffering (only usable in text mode), and an integer > 1 to indicate
the size of a fixed-size chunk buffer. When no buffering argument is
given, the default buffering policy works as follows:
Pass 0 to switch buffering off (only allowed in binary mode), 1 to
select line buffering (only usable in text mode), and an integer > 1 to
indicate the size of a fixed-size chunk buffer. When no buffering
argument is given, the default buffering policy works as follows:
* Binary files are buffered in fixed-size chunks; the size of the buffer
is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)
when the device block size is available.
On most systems, the buffer will typically be 128 kilobytes long.
* Binary files are buffered in fixed-size chunks; the size of the buffer
is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) when the device
block size is available.
On most systems, the buffer will typically be 128 kilobytes long.
* "Interactive" text files (files for which isatty() returns True)
use line buffering. Other text files use the policy described above
@ -147,8 +148,8 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None,
encoding error strings.
newline is a string controlling how universal newlines works (it only
applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It works
as follows:
applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It
works as follows:
* On input, if newline is None, universal newlines mode is
enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
@ -164,17 +165,17 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None,
other legal values, any '\n' characters written are translated to
the given string.
closedfd is a bool. If closefd is False, the underlying file descriptor will
be kept open when the file is closed. This does not work when a file name is
given and must be True in that case.
closedfd is a bool. If closefd is False, the underlying file descriptor
will be kept open when the file is closed. This does not work when
a file name is given and must be True in that case.
The newly created file is non-inheritable.
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 (*file*, *flags*). *opener* must return an open file
descriptor (passing os.open as *opener* results in functionality similar to
passing None).
underlying file descriptor for the file object is then obtained by
calling *opener* with (*file*, *flags*). *opener* must return an open
file descriptor (passing os.open as *opener* results in functionality
similar to passing None).
open() returns a file object whose type depends on the mode, and
through which the standard file operations such as reading and writing
@ -351,10 +352,12 @@ def seek(self, pos, whence=0):
interpreted relative to the position indicated by whence. Values
for whence are ints:
* 0 -- start of stream (the default); offset should be zero or positive
* 0 -- start of stream (the default); offset should be zero or
positive
* 1 -- current stream position; offset may be negative
* 2 -- end of stream; offset is usually negative
Some operating systems / file systems could provide additional values.
Some operating systems / file systems could provide additional
values.
Return an int indicating the new absolute position.
"""
@ -367,8 +370,8 @@ def tell(self):
def truncate(self, pos=None):
"""Truncate file to size bytes.
Size defaults to the current IO position as reported by tell(). Return
the new size.
Size defaults to the current IO position as reported by tell().
Return the new size.
"""
self._unsupported("truncate")
@ -492,7 +495,8 @@ def __exit__(self, *args):
def fileno(self):
"""Returns underlying file descriptor (an int) if one exists.
An OSError is raised if the IO object does not use a file descriptor.
An OSError is raised if the IO object does not use a file
descriptor.
"""
self._unsupported("fileno")
@ -1505,17 +1509,22 @@ class FileIO(RawIOBase):
_closefd = True
def __init__(self, file, mode='r', closefd=True, opener=None):
"""Open a file. The mode can be 'r' (default), 'w', 'x' or 'a' for reading,
writing, exclusive creation or appending. The file will be created if it
doesn't exist when opened for writing or appending; it will be truncated
when opened for writing. A FileExistsError will be raised if it already
exists when opened for creating. Opening a file for creating implies
writing so this mode behaves in a similar way to 'w'. Add a '+' to the mode
to allow simultaneous reading and writing. 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 (*name*, *flags*).
*opener* must return an open file descriptor (passing os.open as *opener*
results in functionality similar to passing None).
"""Open a file.
The mode can be 'r' (default), 'w', 'x' or 'a' for reading,
writing, exclusive creation or appending. The file will be created
if it doesn't exist when opened for writing or appending; it will be
truncated when opened for writing. A FileExistsError will be raised
if it already exists when opened for creating. Opening a file for
creating implies writing so this mode behaves in a similar way to
'w'. Add a '+' to the mode to allow simultaneous reading and
writing.
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 (*name*, *flags*). *opener* must return
an open file descriptor (passing os.open as *opener* results in
functionality similar to passing None).
"""
if self._fd >= 0:
# Have to close the existing file first.
@ -1754,8 +1763,8 @@ def write(self, b):
"""Write bytes b to file, return number written.
Only makes one system call, so not all of the data may be written.
The number of bytes actually written is returned. In non-blocking mode,
returns None if the write would block.
The number of bytes actually written is returned. In non-blocking
mode, returns None if the write would block.
"""
self._checkClosed()
self._checkWritable()
@ -1767,11 +1776,12 @@ def write(self, b):
def seek(self, pos, whence=SEEK_SET):
"""Move to new file position.
Argument offset is a byte count. Optional argument whence defaults to
SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
are SEEK_CUR or 1 (move relative to current position, positive or negative),
and SEEK_END or 2 (move relative to end of file, usually negative, although
many platforms allow seeking beyond the end of a file).
Argument offset is a byte count. Optional argument whence defaults
to SEEK_SET or 0 (offset from start of file, offset should be >= 0);
other values are SEEK_CUR or 1 (move relative to current position,
positive or negative), and SEEK_END or 2 (move relative to end of
file, usually negative, although many platforms allow seeking beyond
the end of a file).
Note that not all file objects are seekable.
"""
@ -1804,8 +1814,8 @@ def truncate(self, size=None):
def close(self):
"""Close the file.
A closed file cannot be used for further I/O operations. close() may be
called more than once without error.
A closed file cannot be used for further I/O operations.
close() may be called more than once without error.
"""
if not self.closed:
self._stat_atopen = None
@ -1903,8 +1913,8 @@ class TextIOBase(IOBase):
def read(self, size=-1):
"""Read at most size characters from stream, where size is an int.
Read from underlying buffer until we have size characters or we hit EOF.
If size is negative or omitted, read until EOF.
Read from underlying buffer until we have size characters or we hit
EOF. If size is negative or omitted, read until EOF.
Returns a string.
"""

89
Modules/_io/_iomodule.c
View file

@ -70,7 +70,6 @@ PyDoc_STRVAR(module_doc,
/*[clinic input]
module _io
@permit_long_docstring_body
_io.open
file: object
mode: str = "r"
@ -86,112 +85,113 @@ Open file and return a stream. Raise OSError upon failure.
file is either a text or byte string giving the name (and the path
if the file isn't in the current working directory) of the file to
be opened or an integer file descriptor of the file to be
wrapped. (If a file descriptor is given, it is closed when the
wrapped. (If a file descriptor is given, it is closed when the
returned I/O object is closed, unless closefd is set to False.)
mode is an optional string that specifies the mode in which the file
is opened. It defaults to 'r' which means open for reading in text
is opened. It defaults to 'r' which means open for reading in text
mode. Other common values are 'w' for writing (truncating the file if
it already exists), 'x' for creating and writing to a new file, and
'a' for appending (which on some Unix systems, means that all writes
append to the end of the file regardless of the current seek position).
In text mode, if encoding is not specified the encoding used is platform
dependent: locale.getencoding() is called to get the current locale encoding.
(For reading and writing raw bytes use binary mode and leave encoding
unspecified.) The available modes are:
dependent: locale.getencoding() is called to get the current locale
encoding. (For reading and writing raw bytes use binary mode and leave
encoding unspecified.) The available modes are:
========= ===============================================================
========= ==========================================================
Character Meaning
--------- ---------------------------------------------------------------
--------- ----------------------------------------------------------
'r' open for reading (default)
'w' open for writing, truncating the file first
'x' create a new file and open it for writing
'a' open for writing, appending to the end of the file if it exists
'a' open for writing, appending to the end of the file if it
exists
'b' binary mode
't' text mode (default)
'+' open a disk file for updating (reading and writing)
========= ===============================================================
========= ==========================================================
The default mode is 'rt' (open for reading text). For binary random
The default mode is 'rt' (open for reading text). For binary random
access, the mode 'w+b' opens and truncates the file to 0 bytes, while
'r+b' opens the file without truncation. The 'x' mode implies 'w' and
'r+b' opens the file without truncation. The 'x' mode implies 'w' and
raises an `FileExistsError` if the file already exists.
Python distinguishes between files opened in binary and text modes,
even when the underlying operating system doesn't. Files opened in
even when the underlying operating system doesn't. Files opened in
binary mode (appending 'b' to the mode argument) return contents as
bytes objects without any decoding. In text mode (the default, or when
bytes objects without any decoding. In text mode (the default, or when
't' is appended to the mode argument), the contents of the file are
returned as strings, the bytes having been first decoded using a
platform-dependent encoding or using the specified encoding if given.
buffering is an optional integer used to set the buffering policy.
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
line buffering (only usable in text mode), and an integer > 1 to indicate
the size of a fixed-size chunk buffer. When no buffering argument is
given, the default buffering policy works as follows:
Pass 0 to switch buffering off (only allowed in binary mode), 1 to
select line buffering (only usable in text mode), and an integer > 1 to
indicate the size of a fixed-size chunk buffer. When no buffering
argument is given, the default buffering policy works as follows:
* Binary files are buffered in fixed-size chunks; the size of the buffer
is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)
when the device block size is available.
On most systems, the buffer will typically be 128 kilobytes long.
is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) when the device
block size is available.
On most systems, the buffer will typically be 128 kilobytes long.
* "Interactive" text files (files for which isatty() returns True)
use line buffering. Other text files use the policy described above
for binary files.
encoding is the name of the encoding used to decode or encode the
file. This should only be used in text mode. The default encoding is
file. This should only be used in text mode. The default encoding is
platform dependent, but any encoding supported by Python can be
passed. See the codecs module for the list of supported encodings.
errors is an optional string that specifies how encoding errors are to
be handled---this argument should not be used in binary mode. Pass
be handled---this argument should not be used in binary mode. Pass
'strict' to raise a ValueError exception if there is an encoding error
(the default of None has the same effect), or pass 'ignore' to ignore
errors. (Note that ignoring encoding errors can lead to data loss.)
errors. (Note that ignoring encoding errors can lead to data loss.)
See the documentation for codecs.register or run 'help(codecs.Codec)'
for a list of the permitted encoding error strings.
newline controls how universal newlines works (it only applies to text
mode). It can be None, '', '\n', '\r', and '\r\n'. It works as
mode). It can be None, '', '\n', '\r', and '\r\n'. It works as
follows:
* On input, if newline is None, universal newlines mode is
enabled. Lines in the input can end in '\n', '\r', or '\r\n', and
these are translated into '\n' before being returned to the
caller. If it is '', universal newline mode is enabled, but line
endings are returned to the caller untranslated. If it has any of
the other legal values, input lines are only terminated by the given
string, and the line ending is returned to the caller untranslated.
* On input, if newline is None, universal newlines mode is enabled.
Lines in the input can end in '\n', '\r', or '\r\n', and these are
translated into '\n' before being returned to the caller. If it is
'', universal newline mode is enabled, but line endings are returned
to the caller untranslated. If it has any of the other legal values,
input lines are only terminated by the given string, and the line
ending is returned to the caller untranslated.
* On output, if newline is None, any '\n' characters written are
translated to the system default line separator, os.linesep. If
newline is '' or '\n', no translation takes place. If newline is any
translated to the system default line separator, os.linesep. If
newline is '' or '\n', no translation takes place. If newline is any
of the other legal values, any '\n' characters written are translated
to the given string.
If closefd is False, the underlying file descriptor will be kept open
when the file is closed. This does not work when a file name is given
when the file is closed. This does not work when a file name is given
and must be True in that case.
A custom opener can be used by passing a callable as *opener*. The
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 (*file*, *flags*). *opener* must return an open
calling *opener* with (*file*, *flags*). *opener* must return an open
file descriptor (passing os.open as *opener* results in functionality
similar to passing None).
open() returns a file object whose type depends on the mode, and
through which the standard file operations such as reading and writing
are performed. When open() is used to open a file in a text mode ('w',
'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
are performed. When open() is used to open a file in a text mode ('w',
'r', 'wt', 'rt', etc.), it returns a TextIOWrapper. When used to open
a file in a binary mode, the returned class varies: in read binary
mode, it returns a BufferedReader; in write binary and append binary
modes, it returns a BufferedWriter, and in read/write mode, it returns
a BufferedRandom.
It is also possible to use a string or bytearray as a file for both
reading and writing. For strings StringIO can be used like a file
reading and writing. For strings StringIO can be used like a file
opened in a text mode, and for bytes a BytesIO can be used like a file
opened in a binary mode.
[clinic start generated code]*/
@ -200,7 +200,7 @@ static PyObject *
_io_open_impl(PyObject *module, PyObject *file, const char *mode,
int buffering, const char *encoding, const char *errors,
const char *newline, int closefd, PyObject *opener)
/*[clinic end generated code: output=aefafc4ce2b46dc0 input=8629579a442a99e3]*/
/*[clinic end generated code: output=aefafc4ce2b46dc0 input=b3cefa70bef404b3]*/
{
size_t i;
@ -499,21 +499,20 @@ _io_text_encoding_impl(PyObject *module, PyObject *encoding, int stacklevel)
/*[clinic input]
@permit_long_docstring_body
_io.open_code
path : unicode
Opens the provided file with the intent to import the contents.
This may perform extra validation beyond open(), but is otherwise interchangeable
with calling open(path, 'rb').
This may perform extra validation beyond open(), but is otherwise
interchangeable with calling open(path, 'rb').
[clinic start generated code]*/
static PyObject *
_io_open_code_impl(PyObject *module, PyObject *path)
/*[clinic end generated code: output=2fe4ecbd6f3d6844 input=53d38a37d780d034]*/
/*[clinic end generated code: output=2fe4ecbd6f3d6844 input=2803c35aeb63c719]*/
{
return PyFile_OpenCodeObject(path);
}

12
Modules/_io/bytesio.c
View file

@ -488,13 +488,13 @@ _io.BytesIO.read1
Read at most size bytes, returned as a bytes object.
If the size argument is negative or omitted, read until EOF is reached.
Return an empty bytes object at EOF.
If the size argument is negative or omitted, read until EOF is
reached. Return an empty bytes object at EOF.
[clinic start generated code]*/
static PyObject *
_io_BytesIO_read1_impl(bytesio *self, Py_ssize_t size)
/*[clinic end generated code: output=d0f843285aa95f1c input=a08fc9e507ab380c]*/
/*[clinic end generated code: output=d0f843285aa95f1c input=796ff4e0efccc4d9]*/
{
return _io_BytesIO_read_impl(self, size);
}
@ -792,13 +792,13 @@ _io.BytesIO.writelines
Write lines to the file.
Note that newlines are not added. lines can be any iterable object
producing bytes-like objects. This is equivalent to calling write() for
each element.
producing bytes-like objects. This is equivalent to calling write()
for each element.
[clinic start generated code]*/
static PyObject *
_io_BytesIO_writelines_impl(bytesio *self, PyObject *lines)
/*[clinic end generated code: output=03a43a75773bc397 input=5d6a616ae39dc9ca]*/
/*[clinic end generated code: output=03a43a75773bc397 input=d265f76533b058e7]*/
{
PyObject *it, *item;

85
Modules/_io/clinic/_iomodule.c.h generated
View file

@ -18,112 +18,113 @@ PyDoc_STRVAR(_io_open__doc__,
"file is either a text or byte string giving the name (and the path\n"
"if the file isn\'t in the current working directory) of the file to\n"
"be opened or an integer file descriptor of the file to be\n"
"wrapped. (If a file descriptor is given, it is closed when the\n"
"wrapped. (If a file descriptor is given, it is closed when the\n"
"returned I/O object is closed, unless closefd is set to False.)\n"
"\n"
"mode is an optional string that specifies the mode in which the file\n"
"is opened. It defaults to \'r\' which means open for reading in text\n"
"is opened. It defaults to \'r\' which means open for reading in text\n"
"mode. Other common values are \'w\' for writing (truncating the file if\n"
"it already exists), \'x\' for creating and writing to a new file, and\n"
"\'a\' for appending (which on some Unix systems, means that all writes\n"
"append to the end of the file regardless of the current seek position).\n"
"In text mode, if encoding is not specified the encoding used is platform\n"
"dependent: locale.getencoding() is called to get the current locale encoding.\n"
"(For reading and writing raw bytes use binary mode and leave encoding\n"
"unspecified.) The available modes are:\n"
"dependent: locale.getencoding() is called to get the current locale\n"
"encoding. (For reading and writing raw bytes use binary mode and leave\n"
"encoding unspecified.) The available modes are:\n"
"\n"
"========= ===============================================================\n"
"========= ==========================================================\n"
"Character Meaning\n"
"--------- ---------------------------------------------------------------\n"
"--------- ----------------------------------------------------------\n"
"\'r\' open for reading (default)\n"
"\'w\' open for writing, truncating the file first\n"
"\'x\' create a new file and open it for writing\n"
"\'a\' open for writing, appending to the end of the file if it exists\n"
"\'a\' open for writing, appending to the end of the file if it\n"
" exists\n"
"\'b\' binary mode\n"
"\'t\' text mode (default)\n"
"\'+\' open a disk file for updating (reading and writing)\n"
"========= ===============================================================\n"
"========= ==========================================================\n"
"\n"
"The default mode is \'rt\' (open for reading text). For binary random\n"
"The default mode is \'rt\' (open for reading text). For binary random\n"
"access, the mode \'w+b\' opens and truncates the file to 0 bytes, while\n"
"\'r+b\' opens the file without truncation. The \'x\' mode implies \'w\' and\n"
"\'r+b\' opens the file without truncation. The \'x\' mode implies \'w\' and\n"
"raises an `FileExistsError` if the file already exists.\n"
"\n"
"Python distinguishes between files opened in binary and text modes,\n"
"even when the underlying operating system doesn\'t. Files opened in\n"
"even when the underlying operating system doesn\'t. Files opened in\n"
"binary mode (appending \'b\' to the mode argument) return contents as\n"
"bytes objects without any decoding. In text mode (the default, or when\n"
"bytes objects without any decoding. In text mode (the default, or when\n"
"\'t\' is appended to the mode argument), the contents of the file are\n"
"returned as strings, the bytes having been first decoded using a\n"
"platform-dependent encoding or using the specified encoding if given.\n"
"\n"
"buffering is an optional integer used to set the buffering policy.\n"
"Pass 0 to switch buffering off (only allowed in binary mode), 1 to select\n"
"line buffering (only usable in text mode), and an integer > 1 to indicate\n"
"the size of a fixed-size chunk buffer. When no buffering argument is\n"
"given, the default buffering policy works as follows:\n"
"Pass 0 to switch buffering off (only allowed in binary mode), 1 to\n"
"select line buffering (only usable in text mode), and an integer > 1 to\n"
"indicate the size of a fixed-size chunk buffer. When no buffering\n"
"argument is given, the default buffering policy works as follows:\n"
"\n"
"* Binary files are buffered in fixed-size chunks; the size of the buffer\n"
" is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)\n"
" when the device block size is available.\n"
" On most systems, the buffer will typically be 128 kilobytes long.\n"
" is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) when the device\n"
" block size is available.\n"
" On most systems, the buffer will typically be 128 kilobytes long.\n"
"\n"
"* \"Interactive\" text files (files for which isatty() returns True)\n"
" use line buffering. Other text files use the policy described above\n"
" for binary files.\n"
"\n"
"encoding is the name of the encoding used to decode or encode the\n"
"file. This should only be used in text mode. The default encoding is\n"
"file. This should only be used in text mode. The default encoding is\n"
"platform dependent, but any encoding supported by Python can be\n"
"passed. See the codecs module for the list of supported encodings.\n"
"\n"
"errors is an optional string that specifies how encoding errors are to\n"
"be handled---this argument should not be used in binary mode. Pass\n"
"be handled---this argument should not be used in binary mode. Pass\n"
"\'strict\' to raise a ValueError exception if there is an encoding error\n"
"(the default of None has the same effect), or pass \'ignore\' to ignore\n"
"errors. (Note that ignoring encoding errors can lead to data loss.)\n"
"errors. (Note that ignoring encoding errors can lead to data loss.)\n"
"See the documentation for codecs.register or run \'help(codecs.Codec)\'\n"
"for a list of the permitted encoding error strings.\n"
"\n"
"newline controls how universal newlines works (it only applies to text\n"
"mode). It can be None, \'\', \'\\n\', \'\\r\', and \'\\r\\n\'. It works as\n"
"mode). It can be None, \'\', \'\\n\', \'\\r\', and \'\\r\\n\'. It works as\n"
"follows:\n"
"\n"
"* On input, if newline is None, universal newlines mode is\n"
" enabled. Lines in the input can end in \'\\n\', \'\\r\', or \'\\r\\n\', and\n"
" these are translated into \'\\n\' before being returned to the\n"
" caller. If it is \'\', universal newline mode is enabled, but line\n"
" endings are returned to the caller untranslated. If it has any of\n"
" the other legal values, input lines are only terminated by the given\n"
" string, and the line ending is returned to the caller untranslated.\n"
"* On input, if newline is None, universal newlines mode is enabled.\n"
" Lines in the input can end in \'\\n\', \'\\r\', or \'\\r\\n\', and these are\n"
" translated into \'\\n\' before being returned to the caller. If it is\n"
" \'\', universal newline mode is enabled, but line endings are returned\n"
" to the caller untranslated. If it has any of the other legal values,\n"
" input lines are only terminated by the given string, and the line\n"
" ending is returned to the caller untranslated.\n"
"\n"
"* On output, if newline is None, any \'\\n\' characters written are\n"
" translated to the system default line separator, os.linesep. If\n"
" newline is \'\' or \'\\n\', no translation takes place. If newline is any\n"
" translated to the system default line separator, os.linesep. If\n"
" newline is \'\' or \'\\n\', no translation takes place. If newline is any\n"
" of the other legal values, any \'\\n\' characters written are translated\n"
" to the given string.\n"
"\n"
"If closefd is False, the underlying file descriptor will be kept open\n"
"when the file is closed. This does not work when a file name is given\n"
"when the file is closed. This does not work when a file name is given\n"
"and must be True in that case.\n"
"\n"
"A custom opener can be used by passing a callable as *opener*. The\n"
"A custom opener can be used by passing a callable as *opener*. The\n"
"underlying file descriptor for the file object is then obtained by\n"
"calling *opener* with (*file*, *flags*). *opener* must return an open\n"
"calling *opener* with (*file*, *flags*). *opener* must return an open\n"
"file descriptor (passing os.open as *opener* results in functionality\n"
"similar to passing None).\n"
"\n"
"open() returns a file object whose type depends on the mode, and\n"
"through which the standard file operations such as reading and writing\n"
"are performed. When open() is used to open a file in a text mode (\'w\',\n"
"\'r\', \'wt\', \'rt\', etc.), it returns a TextIOWrapper. When used to open\n"
"are performed. When open() is used to open a file in a text mode (\'w\',\n"
"\'r\', \'wt\', \'rt\', etc.), it returns a TextIOWrapper. When used to open\n"
"a file in a binary mode, the returned class varies: in read binary\n"
"mode, it returns a BufferedReader; in write binary and append binary\n"
"modes, it returns a BufferedWriter, and in read/write mode, it returns\n"
"a BufferedRandom.\n"
"\n"
"It is also possible to use a string or bytearray as a file for both\n"
"reading and writing. For strings StringIO can be used like a file\n"
"reading and writing. For strings StringIO can be used like a file\n"
"opened in a text mode, and for bytes a BytesIO can be used like a file\n"
"opened in a binary mode.");
@ -352,8 +353,8 @@ PyDoc_STRVAR(_io_open_code__doc__,
"\n"
"Opens the provided file with the intent to import the contents.\n"
"\n"
"This may perform extra validation beyond open(), but is otherwise interchangeable\n"
"with calling open(path, \'rb\').");
"This may perform extra validation beyond open(), but is otherwise\n"
"interchangeable with calling open(path, \'rb\').");
#define _IO_OPEN_CODE_METHODDEF \
{"open_code", _PyCFunction_CAST(_io_open_code), METH_FASTCALL|METH_KEYWORDS, _io_open_code__doc__},
@ -410,4 +411,4 @@ _io_open_code(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObjec
exit:
return return_value;
}
/*[clinic end generated code: output=7a8e032c0424bce2 input=a9049054013a1b77]*/
/*[clinic end generated code: output=5190d11f0803bfe8 input=a9049054013a1b77]*/

10
Modules/_io/clinic/bytesio.c.h generated
View file

@ -254,8 +254,8 @@ PyDoc_STRVAR(_io_BytesIO_read1__doc__,
"\n"
"Read at most size bytes, returned as a bytes object.\n"
"\n"
"If the size argument is negative or omitted, read until EOF is reached.\n"
"Return an empty bytes object at EOF.");
"If the size argument is negative or omitted, read until EOF is\n"
"reached. Return an empty bytes object at EOF.");
#define _IO_BYTESIO_READ1_METHODDEF \
{"read1", _PyCFunction_CAST(_io_BytesIO_read1), METH_FASTCALL, _io_BytesIO_read1__doc__},
@ -529,8 +529,8 @@ PyDoc_STRVAR(_io_BytesIO_writelines__doc__,
"Write lines to the file.\n"
"\n"
"Note that newlines are not added. lines can be any iterable object\n"
"producing bytes-like objects. This is equivalent to calling write() for\n"
"each element.");
"producing bytes-like objects. This is equivalent to calling write()\n"
"for each element.");
#define _IO_BYTESIO_WRITELINES_METHODDEF \
{"writelines", (PyCFunction)_io_BytesIO_writelines, METH_O, _io_BytesIO_writelines__doc__},
@ -637,4 +637,4 @@ skip_optional_pos:
exit:
return return_value;
}
/*[clinic end generated code: output=daa81dfdae5ccc57 input=a9049054013a1b77]*/
/*[clinic end generated code: output=eac3911e207aaf45 input=a9049054013a1b77]*/

66
Modules/_io/clinic/fileio.c.h generated
View file

@ -15,8 +15,8 @@ PyDoc_STRVAR(_io_FileIO_close__doc__,
"\n"
"Close the file.\n"
"\n"
"A closed file cannot be used for further I/O operations. close() may be\n"
"called more than once without error.");
"A closed file cannot be used for further I/O operations. close()\n"
"may be called more than once without error.");
#define _IO_FILEIO_CLOSE_METHODDEF \
{"close", _PyCFunction_CAST(_io_FileIO_close), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_close__doc__},
@ -41,16 +41,19 @@ PyDoc_STRVAR(_io_FileIO___init____doc__,
"Open a file.\n"
"\n"
"The mode can be \'r\' (default), \'w\', \'x\' or \'a\' for reading,\n"
"writing, exclusive creation or appending. The file will be created if it\n"
"doesn\'t exist when opened for writing or appending; it will be truncated\n"
"when opened for writing. A FileExistsError will be raised if it already\n"
"exists when opened for creating. Opening a file for creating implies\n"
"writing so this mode behaves in a similar way to \'w\'.Add a \'+\' to the mode\n"
"to allow simultaneous reading and writing. A custom opener can be used by\n"
"passing a callable as *opener*. The underlying file descriptor for the file\n"
"object is then obtained by calling opener with (*name*, *flags*).\n"
"*opener* must return an open file descriptor (passing os.open as *opener*\n"
"results in functionality similar to passing None).");
"writing, exclusive creation or appending. The file will be created\n"
"if it doesn\'t exist when opened for writing or appending; it will be\n"
"truncated when opened for writing. A FileExistsError will be raised\n"
"if it already exists when opened for creating. Opening a file for\n"
"creating implies writing so this mode behaves in a similar way to\n"
"\'w\'. Add a \'+\' to the mode to allow simultaneous reading and\n"
"writing.\n"
"\n"
"A custom opener can be used by passing a callable as *opener*.\n"
"The underlying file descriptor for the file object is then obtained\n"
"by calling opener with (*name*, *flags*). *opener* must return\n"
"an open file descriptor (passing os.open as *opener* results in\n"
"functionality similar to passing None).");
static int
_io_FileIO___init___impl(fileio *self, PyObject *nameobj, const char *mode,
@ -270,11 +273,13 @@ PyDoc_STRVAR(_io_FileIO_readall__doc__,
"\n"
"Read all data from the file, returned as bytes.\n"
"\n"
"Reads until either there is an error or read() returns size 0 (indicates EOF).\n"
"If the file is already at EOF, returns an empty bytes object.\n"
"Reads until either there is an error or read() returns size 0\n"
"(indicates EOF). If the file is already at EOF, returns an empty\n"
"bytes object.\n"
"\n"
"In non-blocking mode, returns as much data as could be read before EAGAIN. If no\n"
"data is available (EAGAIN is returned before bytes are read) returns None.");
"In non-blocking mode, returns as much data as could be read before\n"
"EAGAIN. If no data is available (EAGAIN is returned before bytes\n"
"are read) returns None.");
#define _IO_FILEIO_READALL_METHODDEF \
{"readall", _PyCFunction_CAST(_io_FileIO_readall), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_readall__doc__},
@ -298,14 +303,14 @@ PyDoc_STRVAR(_io_FileIO_read__doc__,
"\n"
"Read at most size bytes, returned as bytes.\n"
"\n"
"If size is less than 0, read all bytes in the file making multiple read calls.\n"
"See ``FileIO.readall``.\n"
"If size is less than 0, read all bytes in the file making multiple\n"
"read calls. See ``FileIO.readall``.\n"
"\n"
"Attempts to make only one system call, retrying only per PEP 475 (EINTR). This\n"
"means less data may be returned than requested.\n"
"Attempts to make only one system call, retrying only per PEP 475\n"
"(EINTR). This means less data may be returned than requested.\n"
"\n"
"In non-blocking mode, returns None if no data is available. Return an empty\n"
"bytes object at EOF.");
"In non-blocking mode, returns None if no data is available. Return\n"
"an empty bytes object at EOF.");
#define _IO_FILEIO_READ_METHODDEF \
{"read", _PyCFunction_CAST(_io_FileIO_read), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_read__doc__},
@ -358,8 +363,8 @@ PyDoc_STRVAR(_io_FileIO_write__doc__,
"Write buffer b to file, return number of bytes written.\n"
"\n"
"Only makes one system call, so not all of the data may be written.\n"
"The number of bytes actually written is returned. In non-blocking mode,\n"
"returns None if the write would block.");
"The number of bytes actually written is returned. In non-blocking\n"
"mode, returns None if the write would block.");
#define _IO_FILEIO_WRITE_METHODDEF \
{"write", _PyCFunction_CAST(_io_FileIO_write), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_write__doc__},
@ -412,11 +417,12 @@ PyDoc_STRVAR(_io_FileIO_seek__doc__,
"\n"
"Move to new file position and return the file position.\n"
"\n"
"Argument offset is a byte count. Optional argument whence defaults to\n"
"SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values\n"
"are SEEK_CUR or 1 (move relative to current position, positive or negative),\n"
"and SEEK_END or 2 (move relative to end of file, usually negative, although\n"
"many platforms allow seeking beyond the end of a file).\n"
"Argument offset is a byte count. Optional argument whence defaults\n"
"to SEEK_SET or 0 (offset from start of file, offset should be >= 0);\n"
"other values are SEEK_CUR or 1 (move relative to current position,\n"
"positive or negative), and SEEK_END or 2 (move relative to end of\n"
"file, usually negative, although many platforms allow seeking beyond\n"
"the end of a file).\n"
"\n"
"Note that not all file objects are seekable.");
@ -547,4 +553,4 @@ _io_FileIO_isatty(PyObject *self, PyObject *Py_UNUSED(ignored))
#ifndef _IO_FILEIO_TRUNCATE_METHODDEF
#define _IO_FILEIO_TRUNCATE_METHODDEF
#endif /* !defined(_IO_FILEIO_TRUNCATE_METHODDEF) */
/*[clinic end generated code: output=2e48f3df2f189170 input=a9049054013a1b77]*/
/*[clinic end generated code: output=453d584e2e72f986 input=a9049054013a1b77]*/

16
Modules/_io/clinic/iobase.c.h generated
View file

@ -19,11 +19,13 @@ PyDoc_STRVAR(_io__IOBase_seek__doc__,
" whence\n"
" The relative position to seek from.\n"
"\n"
"The offset is interpreted relative to the position indicated by whence.\n"
"Values for whence are:\n"
"The offset is interpreted relative to the position indicated by\n"
"whence. Values for whence are:\n"
"\n"
"* os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive\n"
"* os.SEEK_CUR or 1 -- current stream position; offset may be negative\n"
"* os.SEEK_SET or 0 -- start of stream (the default); offset should\n"
" be zero or positive\n"
"* os.SEEK_CUR or 1 -- current stream position; offset may be\n"
" negative\n"
"* os.SEEK_END or 2 -- end of stream; offset is usually negative\n"
"\n"
"Return the new absolute position.");
@ -103,8 +105,8 @@ PyDoc_STRVAR(_io__IOBase_truncate__doc__,
"\n"
"Truncate file to size bytes.\n"
"\n"
"File pointer is left unchanged. Size defaults to the current IO position\n"
"as reported by tell(). Return the new size.");
"File pointer is left unchanged. Size defaults to the current IO\n"
"position as reported by tell(). Return the new size.");
#define _IO__IOBASE_TRUNCATE_METHODDEF \
{"truncate", _PyCFunction_CAST(_io__IOBase_truncate), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io__IOBase_truncate__doc__},
@ -443,4 +445,4 @@ _io__RawIOBase_readall(PyObject *self, PyObject *Py_UNUSED(ignored))
{
return _io__RawIOBase_readall_impl(self);
}
/*[clinic end generated code: output=9359e74d95534bef input=a9049054013a1b77]*/
/*[clinic end generated code: output=28c06bb6db32c096 input=a9049054013a1b77]*/

5
Modules/_io/clinic/stringio.c.h generated
View file

@ -179,7 +179,8 @@ PyDoc_STRVAR(_io_StringIO_seek__doc__,
"\n"
"Change stream position.\n"
"\n"
"Seek to character offset pos relative to position indicated by whence:\n"
"Seek to character offset pos relative to position indicated by\n"
"whence:\n"
" 0 Start of stream (the default). pos should be >= 0;\n"
" 1 Current position - pos must be 0;\n"
" 2 End of stream - pos must be 0.\n"
@ -550,4 +551,4 @@ _io_StringIO_newlines_get(PyObject *self, void *Py_UNUSED(context))
return return_value;
}
/*[clinic end generated code: output=bccc25ef8e6ce9ef input=a9049054013a1b77]*/
/*[clinic end generated code: output=730c34b2a6c0500b input=a9049054013a1b77]*/

13
Modules/_io/clinic/textio.c.h generated
View file

@ -16,7 +16,8 @@ PyDoc_STRVAR(_io__TextIOBase_detach__doc__,
"\n"
"Separate the underlying buffer from the TextIOBase and return it.\n"
"\n"
"After the underlying buffer has been detached, the TextIO is in an unusable state.");
"After the underlying buffer has been detached, the TextIO is in\n"
"an unusable state.");
#define _IO__TEXTIOBASE_DETACH_METHODDEF \
{"detach", _PyCFunction_CAST(_io__TextIOBase_detach), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io__TextIOBase_detach__doc__},
@ -40,8 +41,8 @@ PyDoc_STRVAR(_io__TextIOBase_read__doc__,
"\n"
"Read at most size characters from stream.\n"
"\n"
"Read from underlying buffer until we have size characters or we hit EOF.\n"
"If size is negative or omitted, read until EOF.");
"Read from underlying buffer until we have size characters or we hit\n"
"EOF. If size is negative or omitted, read until EOF.");
#define _IO__TEXTIOBASE_READ_METHODDEF \
{"read", _PyCFunction_CAST(_io__TextIOBase_read), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io__TextIOBase_read__doc__},
@ -964,8 +965,8 @@ PyDoc_STRVAR(_io_TextIOWrapper_tell__doc__,
"\n"
"Return the stream position as an opaque number.\n"
"\n"
"The return value of tell() can be given as input to seek(), to restore a\n"
"previous stream position.");
"The return value of tell() can be given as input to seek(), to\n"
"restore a previous stream position.");
#define _IO_TEXTIOWRAPPER_TELL_METHODDEF \
{"tell", (PyCFunction)_io_TextIOWrapper_tell, METH_NOARGS, _io_TextIOWrapper_tell__doc__},
@ -1328,4 +1329,4 @@ _io_TextIOWrapper__CHUNK_SIZE_set(PyObject *self, PyObject *value, void *Py_UNUS
return return_value;
}
/*[clinic end generated code: output=c38e6cd5ff4b7eea input=a9049054013a1b77]*/
/*[clinic end generated code: output=f900b42090c9781c input=a9049054013a1b77]*/

8
Modules/_io/clinic/winconsoleio.c.h generated
View file

@ -46,9 +46,9 @@ PyDoc_STRVAR(_io__WindowsConsoleIO___init____doc__,
"\n"
"Open a console buffer by file descriptor.\n"
"\n"
"The mode can be \'rb\' (default), or \'wb\' for reading or writing bytes. All\n"
"other mode characters will be ignored. Mode \'b\' will be assumed if it is\n"
"omitted. The *opener* parameter is always ignored.");
"The mode can be \'rb\' (default), or \'wb\' for reading or writing\n"
"bytes. All other mode characters will be ignored. Mode \'b\' will be\n"
"assumed if it is omitted. The *opener* parameter is always ignored.");
static int
_io__WindowsConsoleIO___init___impl(winconsoleio *self, PyObject *nameobj,
@ -463,4 +463,4 @@ _io__WindowsConsoleIO_isatty(PyObject *self, PyObject *Py_UNUSED(ignored))
#ifndef _IO__WINDOWSCONSOLEIO_ISATTY_METHODDEF
#define _IO__WINDOWSCONSOLEIO_ISATTY_METHODDEF
#endif /* !defined(_IO__WINDOWSCONSOLEIO_ISATTY_METHODDEF) */
/*[clinic end generated code: output=ce50bcd905f1f213 input=a9049054013a1b77]*/
/*[clinic end generated code: output=dfe49dd71f4f4b1d input=a9049054013a1b77]*/

82
Modules/_io/fileio.c
View file

@ -153,13 +153,13 @@ _io.FileIO.close
Close the file.
A closed file cannot be used for further I/O operations. close() may be
called more than once without error.
A closed file cannot be used for further I/O operations. close()
may be called more than once without error.
[clinic start generated code]*/
static PyObject *
_io_FileIO_close_impl(fileio *self, PyTypeObject *cls)
/*[clinic end generated code: output=c30cbe9d1f23ca58 input=70da49e63db7c64d]*/
/*[clinic end generated code: output=c30cbe9d1f23ca58 input=b405751dc4163da3]*/
{
PyObject *res;
int rc;
@ -231,22 +231,25 @@ _io.FileIO.__init__
Open a file.
The mode can be 'r' (default), 'w', 'x' or 'a' for reading,
writing, exclusive creation or appending. The file will be created if it
doesn't exist when opened for writing or appending; it will be truncated
when opened for writing. A FileExistsError will be raised if it already
exists when opened for creating. Opening a file for creating implies
writing so this mode behaves in a similar way to 'w'.Add a '+' to the mode
to allow simultaneous reading and writing. 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 (*name*, *flags*).
*opener* must return an open file descriptor (passing os.open as *opener*
results in functionality similar to passing None).
writing, exclusive creation or appending. The file will be created
if it doesn't exist when opened for writing or appending; it will be
truncated when opened for writing. A FileExistsError will be raised
if it already exists when opened for creating. Opening a file for
creating implies writing so this mode behaves in a similar way to
'w'. Add a '+' to the mode to allow simultaneous reading and
writing.
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 (*name*, *flags*). *opener* must return
an open file descriptor (passing os.open as *opener* results in
functionality similar to passing None).
[clinic start generated code]*/
static int
_io_FileIO___init___impl(fileio *self, PyObject *nameobj, const char *mode,
int closefd, PyObject *opener)
/*[clinic end generated code: output=23413f68e6484bbd input=588aac967e0ba74b]*/
/*[clinic end generated code: output=23413f68e6484bbd input=bac4efcd8f930bf3]*/
{
#ifdef MS_WINDOWS
wchar_t *widename = NULL;
@ -725,7 +728,6 @@ new_buffersize(fileio *self, size_t currentsize)
}
/*[clinic input]
@permit_long_docstring_body
_io.FileIO.readall
cls: defining_class
@ -733,16 +735,18 @@ _io.FileIO.readall
Read all data from the file, returned as bytes.
Reads until either there is an error or read() returns size 0 (indicates EOF).
If the file is already at EOF, returns an empty bytes object.
Reads until either there is an error or read() returns size 0
(indicates EOF). If the file is already at EOF, returns an empty
bytes object.
In non-blocking mode, returns as much data as could be read before EAGAIN. If no
data is available (EAGAIN is returned before bytes are read) returns None.
In non-blocking mode, returns as much data as could be read before
EAGAIN. If no data is available (EAGAIN is returned before bytes
are read) returns None.
[clinic start generated code]*/
static PyObject *
_io_FileIO_readall_impl(fileio *self, PyTypeObject *cls)
/*[clinic end generated code: output=d546737ec895c462 input=cecda40bf9961299]*/
/*[clinic end generated code: output=d546737ec895c462 input=65d05bd0169f2df5]*/
{
Py_off_t pos, end;
PyBytesWriter *writer;
@ -850,7 +854,6 @@ _io_FileIO_readall_impl(fileio *self, PyTypeObject *cls)
}
/*[clinic input]
@permit_long_docstring_body
_io.FileIO.read
cls: defining_class
size: Py_ssize_t(accept={int, NoneType}) = -1
@ -858,19 +861,19 @@ _io.FileIO.read
Read at most size bytes, returned as bytes.
If size is less than 0, read all bytes in the file making multiple read calls.
See ``FileIO.readall``.
If size is less than 0, read all bytes in the file making multiple
read calls. See ``FileIO.readall``.
Attempts to make only one system call, retrying only per PEP 475 (EINTR). This
means less data may be returned than requested.
Attempts to make only one system call, retrying only per PEP 475
(EINTR). This means less data may be returned than requested.
In non-blocking mode, returns None if no data is available. Return an empty
bytes object at EOF.
In non-blocking mode, returns None if no data is available. Return
an empty bytes object at EOF.
[clinic start generated code]*/
static PyObject *
_io_FileIO_read_impl(fileio *self, PyTypeObject *cls, Py_ssize_t size)
/*[clinic end generated code: output=bbd749c7c224143e input=752d1ad3db8564a5]*/
/*[clinic end generated code: output=bbd749c7c224143e input=c7baa3b440af9337]*/
{
if (self->fd < 0)
return err_closed();
@ -916,13 +919,13 @@ _io.FileIO.write
Write buffer b to file, return number of bytes written.
Only makes one system call, so not all of the data may be written.
The number of bytes actually written is returned. In non-blocking mode,
returns None if the write would block.
The number of bytes actually written is returned. In non-blocking
mode, returns None if the write would block.
[clinic start generated code]*/
static PyObject *
_io_FileIO_write_impl(fileio *self, PyTypeObject *cls, Py_buffer *b)
/*[clinic end generated code: output=927e25be80f3b77b input=2776314f043088f5]*/
/*[clinic end generated code: output=927e25be80f3b77b input=233f1f70f9e8b09e]*/
{
Py_ssize_t n;
int err;
@ -1016,7 +1019,6 @@ portable_lseek(fileio *self, PyObject *posobj, int whence, bool suppress_pipe_er
}
/*[clinic input]
@permit_long_docstring_body
_io.FileIO.seek
pos: object
whence: int = 0
@ -1024,18 +1026,19 @@ _io.FileIO.seek
Move to new file position and return the file position.
Argument offset is a byte count. Optional argument whence defaults to
SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values
are SEEK_CUR or 1 (move relative to current position, positive or negative),
and SEEK_END or 2 (move relative to end of file, usually negative, although
many platforms allow seeking beyond the end of a file).
Argument offset is a byte count. Optional argument whence defaults
to SEEK_SET or 0 (offset from start of file, offset should be >= 0);
other values are SEEK_CUR or 1 (move relative to current position,
positive or negative), and SEEK_END or 2 (move relative to end of
file, usually negative, although many platforms allow seeking beyond
the end of a file).
Note that not all file objects are seekable.
[clinic start generated code]*/
static PyObject *
_io_FileIO_seek_impl(fileio *self, PyObject *pos, int whence)
/*[clinic end generated code: output=c976acdf054e6655 input=f077c492a84c9e62]*/
/*[clinic end generated code: output=c976acdf054e6655 input=f165a1b4f5d494ad]*/
{
if (self->fd < 0)
return err_closed();
@ -1063,6 +1066,7 @@ _io_FileIO_tell_impl(fileio *self)
#ifdef HAVE_FTRUNCATE
/*[clinic input]
@permit_long_summary
_io.FileIO.truncate
cls: defining_class
size as posobj: object = None
@ -1076,7 +1080,7 @@ The current file position is changed to the value of size.
static PyObject *
_io_FileIO_truncate_impl(fileio *self, PyTypeObject *cls, PyObject *posobj)
/*[clinic end generated code: output=d936732a49e8d5a2 input=c367fb45d6bb2c18]*/
/*[clinic end generated code: output=d936732a49e8d5a2 input=8f22152bcf900ed2]*/
{
Py_off_t pos;
int ret;

19
Modules/_io/iobase.c
View file

@ -93,7 +93,6 @@ iobase_unsupported(_PyIO_State *state, const char *message)
/* Positioning */
/*[clinic input]
@permit_long_docstring_body
_io._IOBase.seek
cls: defining_class
offset: int(unused=True)
@ -104,11 +103,13 @@ _io._IOBase.seek
Change the stream position to the given byte offset.
The offset is interpreted relative to the position indicated by whence.
Values for whence are:
The offset is interpreted relative to the position indicated by
whence. Values for whence are:
* os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive
* os.SEEK_CUR or 1 -- current stream position; offset may be negative
* os.SEEK_SET or 0 -- start of stream (the default); offset should
be zero or positive
* os.SEEK_CUR or 1 -- current stream position; offset may be
negative
* os.SEEK_END or 2 -- end of stream; offset is usually negative
Return the new absolute position.
@ -117,7 +118,7 @@ Return the new absolute position.
static PyObject *
_io__IOBase_seek_impl(PyObject *self, PyTypeObject *cls,
int Py_UNUSED(offset), int Py_UNUSED(whence))
/*[clinic end generated code: output=8bd74ea6538ded53 input=a21b5aad416ff6a9]*/
/*[clinic end generated code: output=8bd74ea6538ded53 input=22eaf07a7a0ee289]*/
{
_PyIO_State *state = get_io_state_by_cls(cls);
return iobase_unsupported(state, "seek");
@ -144,14 +145,14 @@ _io._IOBase.truncate
Truncate file to size bytes.
File pointer is left unchanged. Size defaults to the current IO position
as reported by tell(). Return the new size.
File pointer is left unchanged. Size defaults to the current IO
position as reported by tell(). Return the new size.
[clinic start generated code]*/
static PyObject *
_io__IOBase_truncate_impl(PyObject *self, PyTypeObject *cls,
PyObject *Py_UNUSED(size))
/*[clinic end generated code: output=2013179bff1fe8ef input=660ac20936612c27]*/
/*[clinic end generated code: output=2013179bff1fe8ef input=5b3b6ab3c7abd806]*/
{
_PyIO_State *state = get_io_state_by_cls(cls);
return iobase_unsupported(state, "truncate");

5
Modules/_io/stringio.c
View file

@ -497,7 +497,8 @@ _io.StringIO.seek
Change stream position.
Seek to character offset pos relative to position indicated by whence:
Seek to character offset pos relative to position indicated by
whence:
0 Start of stream (the default). pos should be >= 0;
1 Current position - pos must be 0;
2 End of stream - pos must be 0.
@ -506,7 +507,7 @@ Returns the new absolute position.
static PyObject *
_io_StringIO_seek_impl(stringio *self, Py_ssize_t pos, int whence)
/*[clinic end generated code: output=e9e0ac9a8ae71c25 input=c75ced09343a00d7]*/
/*[clinic end generated code: output=e9e0ac9a8ae71c25 input=ffef24668fd71a5d]*/
{
CHECK_INITIALIZED(self);
CHECK_CLOSED(self);

18
Modules/_io/textio.c
View file

@ -53,19 +53,19 @@ _unsupported(_PyIO_State *state, const char *message)
}
/*[clinic input]
@permit_long_docstring_body
_io._TextIOBase.detach
cls: defining_class
/
Separate the underlying buffer from the TextIOBase and return it.
After the underlying buffer has been detached, the TextIO is in an unusable state.
After the underlying buffer has been detached, the TextIO is in
an unusable state.
[clinic start generated code]*/
static PyObject *
_io__TextIOBase_detach_impl(PyObject *self, PyTypeObject *cls)
/*[clinic end generated code: output=50915f40c609eaa4 input=8cd0652c17d7f015]*/
/*[clinic end generated code: output=50915f40c609eaa4 input=8099c088abcb87d8]*/
{
_PyIO_State *state = get_io_state_by_cls(cls);
return _unsupported(state, "detach");
@ -79,14 +79,14 @@ _io._TextIOBase.read
Read at most size characters from stream.
Read from underlying buffer until we have size characters or we hit EOF.
If size is negative or omitted, read until EOF.
Read from underlying buffer until we have size characters or we hit
EOF. If size is negative or omitted, read until EOF.
[clinic start generated code]*/
static PyObject *
_io__TextIOBase_read_impl(PyObject *self, PyTypeObject *cls,
int Py_UNUSED(size))
/*[clinic end generated code: output=51a5178a309ce647 input=f5e37720f9fc563f]*/
/*[clinic end generated code: output=51a5178a309ce647 input=c9fd4cc1cf1b4614]*/
{
_PyIO_State *state = get_io_state_by_cls(cls);
return _unsupported(state, "read");
@ -2727,13 +2727,13 @@ _io.TextIOWrapper.tell
Return the stream position as an opaque number.
The return value of tell() can be given as input to seek(), to restore a
previous stream position.
The return value of tell() can be given as input to seek(), to
restore a previous stream position.
[clinic start generated code]*/
static PyObject *
_io_TextIOWrapper_tell_impl(textio *self)
/*[clinic end generated code: output=4f168c08bf34ad5f input=415d6b4e4f8e6e8c]*/
/*[clinic end generated code: output=4f168c08bf34ad5f input=aeece020f747fd92]*/
{
PyObject *res;
PyObject *posobj = NULL;

8
Modules/_io/winconsoleio.c
View file

@ -315,16 +315,16 @@ _io._WindowsConsoleIO.__init__
Open a console buffer by file descriptor.
The mode can be 'rb' (default), or 'wb' for reading or writing bytes. All
other mode characters will be ignored. Mode 'b' will be assumed if it is
omitted. The *opener* parameter is always ignored.
The mode can be 'rb' (default), or 'wb' for reading or writing
bytes. All other mode characters will be ignored. Mode 'b' will be
assumed if it is omitted. The *opener* parameter is always ignored.
[clinic start generated code]*/
static int
_io__WindowsConsoleIO___init___impl(winconsoleio *self, PyObject *nameobj,
const char *mode, int closefd,
PyObject *opener)
/*[clinic end generated code: output=3fd9cbcdd8d95429 input=7a3eed6bbe998fd9]*/
/*[clinic end generated code: output=3fd9cbcdd8d95429 input=f31100e2cd724617]*/
{
const char *s;
wchar_t *name = NULL;