mirror of
https://github.com/python/cpython.git
synced 2025-08-03 08:34:29 +00:00
Issue #20175: Converted the _io module to Argument Clinic.
This commit is contained in:
Serhiy Storchaka
parent
7f90cba7f3
commit
f24131ff31
16 changed files with 4209 additions and 1372 deletions
|
|
@ -93,140 +93,145 @@ PyDoc_STRVAR(module_doc,
|
|||
/*
|
||||
* The main open() function
|
||||
*/
|
||||
PyDoc_STRVAR(open_doc,
|
||||
"open(file, mode='r', buffering=-1, encoding=None,\n"
|
||||
" errors=None, newline=None, closefd=True, opener=None) -> file object\n"
|
||||
"\n"
|
||||
"Open file and return a stream. Raise IOError upon failure.\n"
|
||||
"\n"
|
||||
"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"
|
||||
"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"
|
||||
"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.getpreferredencoding(False) is called to get the\n"
|
||||
"current locale encoding. (For reading and writing raw bytes use binary\n"
|
||||
"mode and leave encoding unspecified.) The available modes are:\n"
|
||||
"\n"
|
||||
"========= ===============================================================\n"
|
||||
"Character Meaning\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"
|
||||
"'b' binary mode\n"
|
||||
"'t' text mode (default)\n"
|
||||
"'+' open a disk file for updating (reading and writing)\n"
|
||||
"'U' universal newline mode (deprecated)\n"
|
||||
"========= ===============================================================\n"
|
||||
"\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"
|
||||
"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"
|
||||
"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"
|
||||
"'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"
|
||||
"'U' mode is deprecated and will raise an exception in future versions\n"
|
||||
"of Python. It has no effect in Python 3. Use newline to control\n"
|
||||
"universal newlines mode.\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"
|
||||
"\n"
|
||||
"* Binary files are buffered in fixed-size chunks; the size of the buffer\n"
|
||||
" is chosen using a heuristic trying to determine the underlying device's\n"
|
||||
" \"block size\" and falling back on `io.DEFAULT_BUFFER_SIZE`.\n"
|
||||
" On many systems, the buffer will typically be 4096 or 8192 bytes 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"
|
||||
"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"
|
||||
"'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"
|
||||
"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"
|
||||
"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"
|
||||
"\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"
|
||||
" 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"
|
||||
"and must be True in that case.\n"
|
||||
"\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"
|
||||
"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"
|
||||
"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"
|
||||
"opened in a text mode, and for bytes a BytesIO can be used like a file\n"
|
||||
"opened in a binary mode.\n"
|
||||
);
|
||||
/*[clinic input]
|
||||
module _io
|
||||
|
||||
_io.open
|
||||
file: object
|
||||
mode: str = "r"
|
||||
buffering: int = -1
|
||||
encoding: str(nullable=True) = NULL
|
||||
errors: str(nullable=True) = NULL
|
||||
newline: str(nullable=True) = NULL
|
||||
closefd: int(c_default="1") = True
|
||||
opener: object = None
|
||||
|
||||
Open file and return a stream. Raise IOError 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
|
||||
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 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.getpreferredencoding(False) 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
|
||||
'b' binary mode
|
||||
't' text mode (default)
|
||||
'+' open a disk file for updating (reading and writing)
|
||||
'U' universal newline mode (deprecated)
|
||||
========= ===============================================================
|
||||
|
||||
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
|
||||
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
|
||||
binary mode (appending 'b' to the mode argument) return contents as
|
||||
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.
|
||||
|
||||
'U' mode is deprecated and will raise an exception in future versions
|
||||
of Python. It has no effect in Python 3. Use newline to control
|
||||
universal newlines mode.
|
||||
|
||||
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:
|
||||
|
||||
* Binary files are buffered in fixed-size chunks; the size of the buffer
|
||||
is chosen using a heuristic trying to determine the underlying device's
|
||||
"block size" and falling back on `io.DEFAULT_BUFFER_SIZE`.
|
||||
On many systems, the buffer will typically be 4096 or 8192 bytes 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
|
||||
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
|
||||
'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.)
|
||||
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
|
||||
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 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
|
||||
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
|
||||
and must be True in that case.
|
||||
|
||||
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).
|
||||
|
||||
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
|
||||
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
|
||||
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]*/
|
||||
|
||||
static PyObject *
|
||||
io_open(PyObject *self, PyObject *args, PyObject *kwds)
|
||||
_io_open_impl(PyModuleDef *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=7615d0d746eb14d2 input=0541ce15691a82f2]*/
|
||||
{
|
||||
char *kwlist[] = {"file", "mode", "buffering",
|
||||
"encoding", "errors", "newline",
|
||||
"closefd", "opener", NULL};
|
||||
PyObject *file, *opener = Py_None;
|
||||
char *mode = "r";
|
||||
int buffering = -1, closefd = 1;
|
||||
char *encoding = NULL, *errors = NULL, *newline = NULL;
|
||||
unsigned i;
|
||||
|
||||
int creating = 0, reading = 0, writing = 0, appending = 0, updating = 0;
|
||||
|
|
@ -242,13 +247,6 @@ io_open(PyObject *self, PyObject *args, PyObject *kwds)
|
|||
_Py_IDENTIFIER(mode);
|
||||
_Py_IDENTIFIER(close);
|
||||
|
||||
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|sizzziO:open", kwlist,
|
||||
&file, &mode, &buffering,
|
||||
&encoding, &errors, &newline,
|
||||
&closefd, &opener)) {
|
||||
return NULL;
|
||||
}
|
||||
|
||||
if (!PyUnicode_Check(file) &&
|
||||
!PyBytes_Check(file) &&
|
||||
!PyNumber_Check(file)) {
|
||||
|
|
@ -611,8 +609,10 @@ iomodule_free(PyObject *mod) {
|
|||
* Module definition
|
||||
*/
|
||||
|
||||
#include "clinic/_iomodule.c.h"
|
||||
|
||||
static PyMethodDef module_methods[] = {
|
||||
{"open", (PyCFunction)io_open, METH_VARARGS|METH_KEYWORDS, open_doc},
|
||||
_IO_OPEN_METHODDEF
|
||||
{NULL, NULL}
|
||||
};
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue