From 089e2497a5f6b708686c04177aca03ed6874c023 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 10 Jul 2022 23:00:15 -0700 Subject: [PATCH] Add position-only markers for os functions --- Doc/library/os.rst | 134 ++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index baf89bf8b56aac..5c19d72bf92c3f 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -358,7 +358,7 @@ process and user. .. availability:: Unix. -.. function:: getgrouplist(user, group) +.. function:: getgrouplist(user, group, /) Return list of group ids that *user* belongs to. If *group* is not in the list, it is included; typically, *group* is specified as the group ID @@ -499,7 +499,7 @@ process and user. .. availability:: Unix. -.. function:: initgroups(username, gid) +.. function:: initgroups(username, gid, /) Call the system initgroups() to initialize the group access list with all of the groups of which the specified username is a member, plus the specified @@ -510,7 +510,7 @@ process and user. .. versionadded:: 3.2 -.. function:: putenv(key, value) +.. function:: putenv(key, value, /) .. index:: single: environment variables; setting @@ -535,28 +535,28 @@ process and user. The function is now always available. -.. function:: setegid(egid) +.. function:: setegid(egid, /) Set the current process's effective group id. .. availability:: Unix. -.. function:: seteuid(euid) +.. function:: seteuid(euid, /) Set the current process's effective user id. .. availability:: Unix. -.. function:: setgid(gid) +.. function:: setgid(gid, /) Set the current process' group id. .. availability:: Unix. -.. function:: setgroups(groups) +.. function:: setgroups(groups, /) Set the list of supplemental group ids associated with the current process to *groups*. *groups* must be a sequence, and each element must be an integer @@ -577,7 +577,7 @@ process and user. .. availability:: Unix. -.. function:: setpgid(pid, pgrp) +.. function:: setpgid(pid, pgrp, /) Call the system call :c:func:`setpgid` to set the process group id of the process with id *pid* to the process group with id *pgrp*. See the Unix manual @@ -605,14 +605,14 @@ process and user. .. versionadded:: 3.3 -.. function:: setregid(rgid, egid) +.. function:: setregid(rgid, egid, /) Set the current process's real and effective group ids. .. availability:: Unix. -.. function:: setresgid(rgid, egid, sgid) +.. function:: setresgid(rgid, egid, sgid, /) Set the current process's real, effective, and saved group ids. @@ -621,7 +621,7 @@ process and user. .. versionadded:: 3.2 -.. function:: setresuid(ruid, euid, suid) +.. function:: setresuid(ruid, euid, suid, /) Set the current process's real, effective, and saved user ids. @@ -630,14 +630,14 @@ process and user. .. versionadded:: 3.2 -.. function:: setreuid(ruid, euid) +.. function:: setreuid(ruid, euid, /) Set the current process's real and effective user ids. .. availability:: Unix. -.. function:: getsid(pid) +.. function:: getsid(pid, /) Call the system call :c:func:`getsid`. See the Unix manual for the semantics. @@ -651,7 +651,7 @@ process and user. .. availability:: Unix. -.. function:: setuid(uid) +.. function:: setuid(uid, /) .. index:: single: user; id, setting @@ -661,7 +661,7 @@ process and user. .. placed in this section since it relates to errno.... a little weak -.. function:: strerror(code) +.. function:: strerror(code, /) Return the error message corresponding to the error code in *code*. On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown @@ -676,7 +676,7 @@ process and user. .. versionadded:: 3.2 -.. function:: umask(mask) +.. function:: umask(mask, /) Set the current numeric umask and return the previous umask. @@ -713,7 +713,7 @@ process and user. with named attributes. -.. function:: unsetenv(key) +.. function:: unsetenv(key, /) .. index:: single: environment variables; deleting @@ -781,7 +781,7 @@ as internal buffering of data. :func:`fdopen`, use its :meth:`~io.IOBase.close` method. -.. function:: closerange(fd_low, fd_high) +.. function:: closerange(fd_low, fd_high, /) Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), ignoring errors. Equivalent to (but much faster than):: @@ -841,7 +841,7 @@ as internal buffering of data. On Unix, the function now implements the Python UTF-8 Mode. -.. function:: dup(fd) +.. function:: dup(fd, /) Return a duplicate of file descriptor *fd*. The new file descriptor is :ref:`non-inheritable `. @@ -902,7 +902,7 @@ as internal buffering of data. This function is not available on MacOS. -.. function:: fpathconf(fd, name) +.. function:: fpathconf(fd, name, /) Return system configuration information relevant to an open file. *name* specifies the configuration value to retrieve; it may be a string which is the @@ -934,7 +934,7 @@ as internal buffering of data. The :func:`.stat` function. -.. function:: fstatvfs(fd) +.. function:: fstatvfs(fd, /) Return information about the filesystem containing the file associated with file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is @@ -955,7 +955,7 @@ as internal buffering of data. .. availability:: Unix, Windows. -.. function:: ftruncate(fd, length) +.. function:: ftruncate(fd, length, /) Truncate the file corresponding to file descriptor *fd*, so that it is at most *length* bytes in size. As of Python 3.3, this is equivalent to @@ -969,7 +969,7 @@ as internal buffering of data. Added support for Windows -.. function:: get_blocking(fd) +.. function:: get_blocking(fd, /) Get the blocking mode of the file descriptor: ``False`` if the :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared. @@ -981,13 +981,13 @@ as internal buffering of data. .. versionadded:: 3.5 -.. function:: isatty(fd) +.. function:: isatty(fd, /) Return ``True`` if the file descriptor *fd* is open and connected to a tty(-like) device, else ``False``. -.. function:: lockf(fd, cmd, len) +.. function:: lockf(fd, cmd, len, /) Apply, test or remove a POSIX lock on an open file descriptor. *fd* is an open file descriptor. @@ -1014,7 +1014,7 @@ as internal buffering of data. .. versionadded:: 3.3 -.. function:: login_tty(fd) +.. function:: login_tty(fd, /) Prepare the tty of which fd is a file descriptor for a new login session. Make the calling process a session leader; make the tty the controlling tty, @@ -1025,7 +1025,7 @@ as internal buffering of data. .. versionadded:: 3.11 -.. function:: lseek(fd, pos, how) +.. function:: lseek(fd, pos, how, /) Set the current position of file descriptor *fd* to position *pos*, modified by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the @@ -1182,7 +1182,7 @@ or `the MSDN `_ on Windo The new file descriptors are now non-inheritable. -.. function:: pipe2(flags) +.. function:: pipe2(flags, /) Create a pipe with *flags* set atomically. *flags* can be constructed by ORing together one or more of these values: @@ -1195,7 +1195,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: posix_fallocate(fd, offset, len) +.. function:: posix_fallocate(fd, offset, len, /) Ensures that enough disk space is allocated for the file specified by *fd* starting from *offset* and continuing for *len* bytes. @@ -1205,7 +1205,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: posix_fadvise(fd, offset, len, advice) +.. function:: posix_fadvise(fd, offset, len, advice, /) Announces an intention to access data in a specific pattern thus allowing the kernel to make optimizations. @@ -1235,7 +1235,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: pread(fd, n, offset) +.. function:: pread(fd, n, offset, /) Read at most *n* bytes from file descriptor *fd* at a position of *offset*, leaving the file offset unchanged. @@ -1248,7 +1248,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: preadv(fd, buffers, offset, flags=0) +.. function:: preadv(fd, buffers, offset, flags=0, /) Read from a file descriptor *fd* at a position of *offset* into mutable :term:`bytes-like objects ` *buffers*, leaving the file @@ -1305,7 +1305,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.7 -.. function:: pwrite(fd, str, offset) +.. function:: pwrite(fd, str, offset, /) Write the bytestring in *str* to file descriptor *fd* at position of *offset*, leaving the file offset unchanged. @@ -1317,7 +1317,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: pwritev(fd, buffers, offset, flags=0) +.. function:: pwritev(fd, buffers, offset, flags=0, /) Write the *buffers* contents to file descriptor *fd* at a offset *offset*, leaving the file offset unchanged. *buffers* must be a sequence of @@ -1380,7 +1380,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.10 -.. function:: read(fd, n) +.. function:: read(fd, n, /) Read at most *n* bytes from file descriptor *fd*. @@ -1440,7 +1440,7 @@ or `the MSDN `_ on Windo Parameters *out* and *in* was renamed to *out_fd* and *in_fd*. -.. function:: set_blocking(fd, blocking) +.. function:: set_blocking(fd, blocking, /) Set the blocking mode of the specified file descriptor. Set the :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise. @@ -1506,7 +1506,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.10 -.. function:: readv(fd, buffers) +.. function:: readv(fd, buffers, /) Read from a file descriptor *fd* into a number of mutable :term:`bytes-like objects ` *buffers*. Transfer data into each buffer until @@ -1524,7 +1524,7 @@ or `the MSDN `_ on Windo .. versionadded:: 3.3 -.. function:: tcgetpgrp(fd) +.. function:: tcgetpgrp(fd, /) Return the process group associated with the terminal given by *fd* (an open file descriptor as returned by :func:`os.open`). @@ -1532,7 +1532,7 @@ or `the MSDN `_ on Windo .. availability:: Unix. -.. function:: tcsetpgrp(fd, pg) +.. function:: tcsetpgrp(fd, pg, /) Set the process group associated with the terminal given by *fd* (an open file descriptor as returned by :func:`os.open`) to *pg*. @@ -1540,7 +1540,7 @@ or `the MSDN `_ on Windo .. availability:: Unix. -.. function:: ttyname(fd) +.. function:: ttyname(fd, /) Return a string which specifies the terminal device associated with file descriptor *fd*. If *fd* is not associated with a terminal device, an @@ -1549,7 +1549,7 @@ or `the MSDN `_ on Windo .. availability:: Unix. -.. function:: write(fd, str) +.. function:: write(fd, str, /) Write the bytestring in *str* to file descriptor *fd*. @@ -1569,7 +1569,7 @@ or `the MSDN `_ on Windo :exc:`InterruptedError` exception (see :pep:`475` for the rationale). -.. function:: writev(fd, buffers) +.. function:: writev(fd, buffers, /) Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a sequence of :term:`bytes-like objects `. Buffers are @@ -1593,7 +1593,7 @@ Querying the size of a terminal .. versionadded:: 3.3 -.. function:: get_terminal_size(fd=STDOUT_FILENO) +.. function:: get_terminal_size(fd=STDOUT_FILENO, /) Return the size of the terminal window as ``(columns, lines)``, tuple of type :class:`terminal_size`. @@ -1645,21 +1645,21 @@ Using the :mod:`subprocess` module, all file descriptors except standard streams are closed, and inheritable handles are only inherited if the *close_fds* parameter is ``False``. -.. function:: get_inheritable(fd) +.. function:: get_inheritable(fd, /) Get the "inheritable" flag of the specified file descriptor (a boolean). -.. function:: set_inheritable(fd, inheritable) +.. function:: set_inheritable(fd, inheritable, /) Set the "inheritable" flag of the specified file descriptor. -.. function:: get_handle_inheritable(handle) +.. function:: get_handle_inheritable(handle, /) Get the "inheritable" flag of the specified handle (a boolean). .. availability:: Windows. -.. function:: set_handle_inheritable(handle, inheritable) +.. function:: set_handle_inheritable(handle, inheritable, /) Set the "inheritable" flag of the specified handle. @@ -2200,19 +2200,19 @@ features: Accepts a :term:`path-like object`. -.. function:: major(device) +.. function:: major(device, /) Extract the device major number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). -.. function:: minor(device) +.. function:: minor(device, /) Extract the device minor number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). -.. function:: makedev(major, minor) +.. function:: makedev(major, minor, /) Compose a raw device number from the major and minor device numbers. @@ -3864,7 +3864,7 @@ written in Python, such as a mail server's external command delivery program. .. availability:: some flavors of Unix. -.. function:: kill(pid, sig) +.. function:: kill(pid, sig, /) .. index:: single: process; killing @@ -3889,7 +3889,7 @@ written in Python, such as a mail server's external command delivery program. Windows support. -.. function:: killpg(pgid, sig) +.. function:: killpg(pgid, sig, /) .. index:: single: process; killing @@ -3902,7 +3902,7 @@ written in Python, such as a mail server's external command delivery program. .. availability:: Unix. -.. function:: nice(increment) +.. function:: nice(increment, /) Add *increment* to the process's "niceness". Return the new niceness. @@ -3931,7 +3931,7 @@ written in Python, such as a mail server's external command delivery program. .. versionadded:: 3.12 -.. function:: plock(op) +.. function:: plock(op, /) Lock program segments into memory. The value of *op* (defined in ````) determines which segments are locked. @@ -4347,7 +4347,7 @@ written in Python, such as a mail server's external command delivery program. :func:`waitpid` can be used to wait for the completion of a specific child process and has more options. -.. function:: waitid(idtype, id, options) +.. function:: waitid(idtype, id, options, /) Wait for the completion of one or more child processes. *idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or @@ -4415,7 +4415,7 @@ written in Python, such as a mail server's external command delivery program. Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values. -.. function:: waitpid(pid, options) +.. function:: waitpid(pid, options, /) The details of this function differ on Unix and Windows. @@ -4538,7 +4538,7 @@ The following functions take a process status code as returned by :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be used to determine the disposition of a process. -.. function:: WCOREDUMP(status) +.. function:: WCOREDUMP(status, /) Return ``True`` if a core dump was generated for the process, otherwise return ``False``. @@ -4683,33 +4683,33 @@ operating system. scheduling policy constants above. -.. function:: sched_setscheduler(pid, policy, param) +.. function:: sched_setscheduler(pid, policy, param, /) Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means the calling process. *policy* is one of the scheduling policy constants above. *param* is a :class:`sched_param` instance. -.. function:: sched_getscheduler(pid) +.. function:: sched_getscheduler(pid, /) Return the scheduling policy for the process with PID *pid*. A *pid* of 0 means the calling process. The result is one of the scheduling policy constants above. -.. function:: sched_setparam(pid, param) +.. function:: sched_setparam(pid, param, /) Set the scheduling parameters for the process with PID *pid*. A *pid* of 0 means the calling process. *param* is a :class:`sched_param` instance. -.. function:: sched_getparam(pid) +.. function:: sched_getparam(pid, /) Return the scheduling parameters as a :class:`sched_param` instance for the process with PID *pid*. A *pid* of 0 means the calling process. -.. function:: sched_rr_get_interval(pid) +.. function:: sched_rr_get_interval(pid, /) Return the round-robin quantum in seconds for the process with PID *pid*. A *pid* of 0 means the calling process. @@ -4720,14 +4720,14 @@ operating system. Voluntarily relinquish the CPU. -.. function:: sched_setaffinity(pid, mask) +.. function:: sched_setaffinity(pid, mask, /) Restrict the process with PID *pid* (or the current process if zero) to a set of CPUs. *mask* is an iterable of integers representing the set of CPUs to which the process should be restricted. -.. function:: sched_getaffinity(pid) +.. function:: sched_getaffinity(pid, /) Return the set of CPUs the process with PID *pid* (or the current process if zero) is restricted to. @@ -4739,7 +4739,7 @@ Miscellaneous System Information -------------------------------- -.. function:: confstr(name) +.. function:: confstr(name, /) Return string-valued system configuration values. *name* specifies the configuration value to retrieve; it may be a string which is the name of a @@ -4790,7 +4790,7 @@ Miscellaneous System Information .. availability:: Unix. -.. function:: sysconf(name) +.. function:: sysconf(name, /) Return integer-valued system configuration values. If the configuration value specified by *name* isn't defined, ``-1`` is returned. The comments regarding @@ -4933,7 +4933,7 @@ Random numbers .. versionadded:: 3.6 -.. function:: urandom(size) +.. function:: urandom(size, /) Return a bytestring of *size* random bytes suitable for cryptographic use.