# HG changeset patch # Parent 6177482ce6a195485b90ffaeba6336640e19ea95 # Parent 6177482ce6a195485b90ffaeba6336640e19ea95 Issue #23738: Use square brackets for positional-only arguments Removed mentioning -1 for BufferedIOBase.read1(), because the common concrete implementation BufferedReader does not support this value. Fixed the name of the first FileIO parameter, and tested it. diff -r 6177482ce6a1 Doc/library/fcntl.rst --- a/Doc/library/fcntl.rst Wed Sep 09 03:01:17 2015 +0000 +++ b/Doc/library/fcntl.rst Sun Dec 06 01:23:26 2015 +0000 @@ -28,14 +28,15 @@ The module defines the following functions: -.. function:: fcntl(fd, cmd, arg=0) +.. function:: fcntl(fd, cmd[, arg]) Perform the operation *cmd* on file descriptor *fd* (file objects providing a :meth:`~io.IOBase.fileno` method are accepted as well). The values used for *cmd* are operating system dependent, and are available as constants in the :mod:`fcntl` module, using the same names as used in the relevant C header files. The argument *arg* can either be an integer value, or a - :class:`bytes` object. With an integer value, the return value of this + :class:`bytes` object. By default, *arg* is the integer 0. + With an integer value, the return value of this function is the integer return value of the C :c:func:`fcntl` call. When the argument is bytes it represents a binary structure, e.g. created by :func:`struct.pack`. The binary data is copied to a buffer whose address is @@ -50,19 +51,20 @@ If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. -.. function:: ioctl(fd, request, arg=0, mutate_flag=True) +.. function:: ioctl(fd, request[, arg[, mutate_flag]]) This function is identical to the :func:`~fcntl.fcntl` function, except that the argument handling is even more complicated. - The *request* parameter is limited to values that can fit in 32-bits. + The *request* parameter is limited to values that can fit in 32 bits. Additional constants of interest for use as the *request* argument can be found in the :mod:`termios` module, under the same names as used in the relevant C header files. The parameter *arg* can be one of an integer, an object supporting the read-only buffer interface (like :class:`bytes`) or an object supporting - the read-write buffer interface (like :class:`bytearray`). + the read-write buffer interface (like :class:`bytearray`). The default is + the integer 0. In all but the last case, behaviour is as for the :func:`~fcntl.fcntl` function. @@ -105,7 +107,7 @@ using :c:func:`fcntl`.) -.. function:: lockf(fd, cmd, len=0, start=0, whence=0) +.. function:: lockf(fd, cmd[, len[, start[, whence]]]) This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. *fd* is the file descriptor of the file to lock or unlock, and *cmd* @@ -118,7 +120,7 @@ When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. If :const:`LOCK_NB` is used and the lock cannot be acquired, an - :exc:`OSError` will be raised and the exception will have an *errno* + :exc:`OSError` will be raised and the exception will have its :attr:`~OSError.errno` attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the operating system; for portability, check for both values). On at least some systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a diff -r 6177482ce6a1 Doc/library/functions.rst --- a/Doc/library/functions.rst Wed Sep 09 03:01:17 2015 +0000 +++ b/Doc/library/functions.rst Sun Dec 06 01:23:26 2015 +0000 @@ -380,11 +380,11 @@ n += 1 -.. function:: eval(expression, globals=None, locals=None) +.. function:: eval(expression[, globals[, locals]]) - The arguments are a string and optional globals and locals. If provided, - *globals* must be a dictionary. If provided, *locals* can be any mapping - object. + The arguments are a string and optional globals and locals. By default, + *globals* and *locals* are ``None``. If not ``None``, *globals* + must be a dictionary, and *locals* can be any mapping object. The *expression* argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the *globals* and *locals* diff -r 6177482ce6a1 Doc/library/io.rst --- a/Doc/library/io.rst Wed Sep 09 03:01:17 2015 +0000 +++ b/Doc/library/io.rst Sun Dec 06 01:23:26 2015 +0000 @@ -283,19 +283,20 @@ Return ``True`` if the stream can be read from. If ``False``, :meth:`read` will raise :exc:`OSError`. - .. method:: readline(size=-1) + .. method:: readline([size]) - Read and return one line from the stream. If *size* is specified, at - most *size* bytes will be read. + Read and return one line from the stream. By default, *size* is −1. + If *size* is some other value, at most *size* bytes will be read. The line terminator is always ``b'\n'`` for binary files; for text files, the *newline* argument to :func:`open` can be used to select the line terminator(s) recognized. - .. method:: readlines(hint=-1) + .. method:: readlines([hint]) - Read and return a list of lines from the stream. *hint* can be specified - to control the number of lines read: no more lines will be read if the + Read and return a list of lines from the stream. + By default, *hint* is −1. If *hint* is some other value, it + controls the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds *hint*. Note that it's already possible to iterate on file objects using ``for @@ -333,10 +334,10 @@ Return the current stream position. - .. method:: truncate(size=None) + .. method:: truncate([size]) Resize the stream to the given *size* in bytes (or the current position - if *size* is not specified). The current stream position isn't changed. + if *size* is ``None`` or not specified). The current stream position isn't changed. This resizing can extend or reduce the current file size. In case of extension, the contents of the new file area depend on the platform (on most systems, additional bytes are zero-filled). The new file size @@ -375,10 +376,10 @@ In addition to the attributes and methods from :class:`IOBase`, :class:`RawIOBase` provides the following methods: - .. method:: read(size=-1) + .. method:: read([size]) Read up to *size* bytes from the object and return them. As a convenience, - if *size* is unspecified or -1, :meth:`readall` is called. Otherwise, + if *size* is unspecified or −1, :meth:`readall` is called. Otherwise, only one system call is ever made. Fewer than *size* bytes may be returned if the operating system call returns fewer than *size* bytes. @@ -451,7 +452,7 @@ .. versionadded:: 3.1 - .. method:: read(size=-1) + .. method:: read([size]) Read and return up to *size* bytes. If the argument is omitted, ``None``, or negative, data is read and returned until EOF is reached. An empty @@ -466,7 +467,7 @@ A :exc:`BlockingIOError` is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment. - .. method:: read1(size=-1) + .. method:: read1([size]) Read and return up to *size* bytes, with at most one call to the underlying raw stream's :meth:`~RawIOBase.read` (or @@ -513,21 +514,21 @@ Raw File I/O ^^^^^^^^^^^^ -.. class:: FileIO(name, mode='r', closefd=True, opener=None) +.. class:: FileIO(file, mode='r', closefd=True, opener=None) :class:`FileIO` represents an OS-level file containing bytes data. It implements the :class:`RawIOBase` interface (and therefore the :class:`IOBase` interface, too). - The *name* can be one of two things: + The *file* argument can be one of two things: * a character string or :class:`bytes` object representing the path to the - file which will be opened. In this case closefd must be True (the default) + file which will be opened. In this case *closefd* must be true (the default), otherwise an error will be raised. * an integer representing the number of an existing OS-level file descriptor to which the resulting :class:`FileIO` object will give access. When the FileIO object is closed this fd will be closed as well, unless *closefd* - is set to ``False``. + is false. The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading (default), writing, exclusive creation or appending. The file will be @@ -537,8 +538,9 @@ 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 @@ -702,14 +704,14 @@ :class:`BufferedWriter` can do. -.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE) +.. class:: BufferedRWPair(reader, writer[, buffer_size]) A buffered I/O object combining two unidirectional :class:`RawIOBase` objects -- one readable, the other writeable -- into a single bidirectional endpoint. It inherits :class:`BufferedIOBase`. *reader* and *writer* are :class:`RawIOBase` objects that are readable and - writeable respectively. If the *buffer_size* is omitted it defaults to + writeable respectively. If *buffer_size* is omitted it defaults to :data:`DEFAULT_BUFFER_SIZE`. :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods @@ -776,12 +778,13 @@ Read and return at most *size* characters from the stream as a single :class:`str`. If *size* is negative or ``None``, reads until EOF. - .. method:: readline(size=-1) + .. method:: readline([size]) Read until newline or EOF and return a single ``str``. If the stream is already at EOF, an empty string is returned. - If *size* is specified, at most *size* characters will be read. + By default *size* is −1. If *size* is some other value, at most + *size* characters will be read. .. method:: seek(offset, whence=SEEK_SET) diff -r 6177482ce6a1 Doc/library/os.rst --- a/Doc/library/os.rst Wed Sep 09 03:01:17 2015 +0000 +++ b/Doc/library/os.rst Sun Dec 06 01:23:26 2015 +0000 @@ -1208,7 +1208,7 @@ .. versionadded:: 3.3 -.. function:: get_terminal_size(fd=STDOUT_FILENO) +.. function:: get_terminal_size([fd]) Return the size of the terminal window as ``(columns, lines)``, tuple of type :class:`terminal_size`. diff -r 6177482ce6a1 Lib/test/test_fileio.py --- a/Lib/test/test_fileio.py Wed Sep 09 03:01:17 2015 +0000 +++ b/Lib/test/test_fileio.py Sun Dec 06 01:23:26 2015 +0000 @@ -522,6 +522,11 @@ def testInvalidInit(self): self.assertRaises(TypeError, self.FileIO, "1", 0, 0) + def testKeywords(self): + with self.FileIO(file=TESTFN, mode="w", closefd=True, opener=None): + pass + os.unlink(TESTFN) + def testWarnings(self): with check_warnings(quiet=True) as w: self.assertEqual(w.warnings, [])