From f725b9587ce8fb1f63244e69e59763cef0750658 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 5 Jan 2008 19:44:22 +0000 Subject: [PATCH] Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. --- Doc/c-api/newtypes.rst | 2 +- Doc/library/fcntl.rst | 2 +- Doc/library/functions.rst | 2 +- Doc/library/msvcrt.rst | 2 +- Doc/library/os.rst | 153 +++++++++++++++++----------------- Doc/library/stdtypes.rst | 9 +- Doc/library/winsound.rst | 2 +- Doc/reference/expressions.rst | 20 ++--- Lib/test/test_doctest.py | 2 +- Modules/fcntlmodule.c | 2 +- 10 files changed, 101 insertions(+), 95 deletions(-) diff --git a/Doc/c-api/newtypes.rst b/Doc/c-api/newtypes.rst index bcb0d20cc61..fdc7bf1dd92 100644 --- a/Doc/c-api/newtypes.rst +++ b/Doc/c-api/newtypes.rst @@ -746,7 +746,7 @@ type objects) *must* have the :attr:`ob_size` field. indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL* values. - The following bit masks are currently defined; these can be or-ed together using + The following bit masks are currently defined; these can be ORed together using the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and checks whether ``tp->tp_flags & f`` is non-zero. diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 2d7bb9cbb2c..5050a7f4878 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -109,7 +109,7 @@ The module defines the following functions: * :const:`LOCK_EX` -- acquire an exclusive lock When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be - bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. + 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:`IOError` will be raised and the exception will have an *errno* attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 0133e5cf6fd..e153bc8c902 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -216,7 +216,7 @@ available. They are listed here in alphabetical order. the *flags* argument is it -- the future statements in effect around the call to compile are ignored. - Future statements are specified by bits which can be bitwise or-ed together to + Future statements are specified by bits which can be bitwise ORed together to specify multiple statements. The bitfield required to specify a given feature can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature` instance in the :mod:`__future__` module. diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index a3057882940..47d63b52d7e 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -67,7 +67,7 @@ File Operations .. function:: open_osfhandle(handle, flags) Create a C runtime file descriptor from the file handle *handle*. The *flags* - parameter should be a bit-wise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, + parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter to :func:`os.fdopen` to create a file object. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 8f6e46ef375..06a82ec44e5 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -7,7 +7,7 @@ This module provides a more portable way of using operating system dependent -functionality than importing a operating system dependent built-in module like +functionality than importing an operating system dependent built-in module like :mod:`posix` or :mod:`nt`. If you just want to read or write a file see :func:`open`, if you want to manipulate paths, see the :mod:`os.path` module, and if you want to read all the lines in all the files on the @@ -17,7 +17,7 @@ file and directory handling see the :mod:`shutil` module. This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found -there. The design of all Python's built-in operating system dependent modules +there. The design of all built-in operating system dependent modules of Python is such that as long as the same functionality is available, it uses the same interface; for example, the function ``os.stat(path)`` returns stat information about *path* in the same format (which happens to have originated with the POSIX @@ -137,7 +137,7 @@ process and user. .. function:: getegid() Return the effective group id of the current process. This corresponds to the - 'set id' bit on the file being executed in the current process. Availability: + "set id" bit on the file being executed in the current process. Availability: Unix. @@ -145,7 +145,7 @@ process and user. .. index:: single: user; effective id - Return the current process' effective user id. Availability: Unix. + Return the current process's effective user id. Availability: Unix. .. function:: getgid() @@ -167,7 +167,7 @@ process and user. process. For most purposes, it is more useful to use the environment variable :envvar:`LOGNAME` to find out who the user is, or ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently - effective user ID. Availability: Unix. + effective user id. Availability: Unix. .. function:: getpgid(pid) @@ -203,7 +203,7 @@ process and user. .. index:: single: user; id - Return the current process' user id. Availability: Unix. + Return the current process's user id. Availability: Unix. .. function:: getenv(varname[, value]) @@ -252,7 +252,7 @@ process and user. 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 - identifying a group. This operation is typical available only to the superuser. + identifying a group. This operation is typically available only to the superuser. Availability: Unix. .. versionadded:: 2.2 @@ -260,14 +260,14 @@ process and user. .. function:: setpgrp() - Calls the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on + Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on which version is implemented (if any). See the Unix manual for the semantics. Availability: Unix. .. function:: setpgid(pid, pgrp) - Calls the system call :cfunc:`setpgid` to set the process group id of the + Call the system call :cfunc:`setpgid` to set the process group id of the process with id *pid* to the process group with id *pgrp*. See the Unix manual for the semantics. Availability: Unix. @@ -284,7 +284,7 @@ process and user. .. function:: getsid(pid) - Calls the system call :cfunc:`getsid`. See the Unix manual for the semantics. + Call the system call :cfunc:`getsid`. See the Unix manual for the semantics. Availability: Unix. .. versionadded:: 2.4 @@ -292,7 +292,7 @@ process and user. .. function:: setsid() - Calls the system call :cfunc:`setsid`. See the Unix manual for the semantics. + Call the system call :cfunc:`setsid`. See the Unix manual for the semantics. Availability: Unix. @@ -300,7 +300,7 @@ process and user. .. index:: single: user; id, setting - Set the current process' user id. Availability: Unix. + Set the current process's user id. Availability: Unix. .. placed in this section since it relates to errno.... a little weak @@ -312,7 +312,7 @@ process and user. .. function:: umask(mask) - Set the current numeric umask and returns the previous umask. Availability: + Set the current numeric umask and return the previous umask. Availability: Unix, Windows. @@ -428,7 +428,7 @@ functions, see :ref:`popen2-flow-control`. .. function:: popen2(cmd[, mode[, bufsize]]) - Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin, + Execute *cmd* as a sub-process and return the file objects ``(child_stdin, child_stdout)``. .. deprecated:: 2.6 @@ -442,7 +442,7 @@ functions, see :ref:`popen2-flow-control`. .. function:: popen3(cmd[, mode[, bufsize]]) - Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin, + Execute *cmd* as a sub-process and return the file objects ``(child_stdin, child_stdout, child_stderr)``. .. deprecated:: 2.6 @@ -456,7 +456,7 @@ functions, see :ref:`popen2-flow-control`. .. function:: popen4(cmd[, mode[, bufsize]]) - Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin, + Execute *cmd* as a sub-process and return the file objects ``(child_stdin, child_stdout_and_stderr)``. .. deprecated:: 2.6 @@ -592,9 +592,10 @@ by file descriptors. .. function:: lseek(fd, pos, how) - Set the current position of file descriptor *fd* to position *pos*, modified by - *how*: ``0`` to set the position relative to the beginning of the file; ``1`` to - set it relative to the current position; ``2`` to set it relative to the end of + 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 + beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the + current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of the file. Availability: Macintosh, Unix, Windows. @@ -623,7 +624,7 @@ by file descriptors. Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master, slave)`` for the pty and the tty, respectively. For a (slightly) more portable - approach, use the :mod:`pty` module. Availability: Macintosh, Some flavors of + approach, use the :mod:`pty` module. Availability: Macintosh, some flavors of Unix. @@ -644,7 +645,7 @@ by file descriptors. This function is intended for low-level I/O and must be applied to a file descriptor as returned by :func:`open` or :func:`pipe`. To read a "file object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, or ``sys.stdin``, use its :meth:`read` or :meth:`readline` + :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline` methods. @@ -677,7 +678,7 @@ by file descriptors. This function is intended for low-level I/O and must be applied to a file descriptor as returned by :func:`open` or :func:`pipe`. To write a "file object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, or ``sys.stdout`` or ``sys.stderr``, use its :meth:`write` + :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write` method. The following data items are available for use in constructing the *flags* @@ -695,7 +696,7 @@ platforms. For descriptions of their availability and use, consult O_TRUNC Options for the *flag* argument to the :func:`open` function. These can be - bit-wise OR'd together. Availability: Macintosh, Unix, Windows. + combined using the bitwise OR operator ``|``. Availability: Macintosh, Unix, Windows. .. data:: O_DSYNC @@ -720,7 +721,7 @@ platforms. For descriptions of their availability and use, consult O_TEXT Options for the *flag* argument to the :func:`open` function. These can be - bit-wise OR'd together. Availability: Windows. + combined using the bitwise OR operator ``|``. Availability: Windows. .. data:: O_DIRECT @@ -860,7 +861,7 @@ Files and Directories .. function:: chmod(path, mode) Change the mode of *path* to the numeric *mode*. *mode* may take one of the - following values (as defined in the :mod:`stat` module) or bitwise or-ed + following values (as defined in the :mod:`stat` module) or bitwise ORed combinations of them: @@ -919,7 +920,7 @@ Files and Directories .. function:: lchown(path, uid, gid) - Change the owner and group id of *path* to the numeric *uid* and gid. This + Change the owner and group id of *path* to the numeric *uid* and *gid*. This function will not follow symbolic links. Availability: Macintosh, Unix. .. versionadded:: 2.3 @@ -978,7 +979,7 @@ Files and Directories .. function:: major(device) - Extracts the device major number from a raw device number (usually the + Extract the device major number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). .. versionadded:: 2.3 @@ -986,7 +987,7 @@ Files and Directories .. function:: minor(device) - Extracts the device minor number from a raw device number (usually the + Extract the device minor number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). .. versionadded:: 2.3 @@ -994,7 +995,7 @@ Files and Directories .. function:: makedev(major, minor) - Composes a raw device number from the major and minor device numbers. + Compose a raw device number from the major and minor device numbers. .. versionadded:: 2.3 @@ -1024,7 +1025,7 @@ Files and Directories .. note:: :func:`makedirs` will become confused if the path elements to create include - *os.pardir*. + :data:`os.pardir`. .. versionadded:: 1.5.2 @@ -1085,7 +1086,7 @@ Files and Directories .. index:: single: directory; deleting - Removes directories recursively. Works like :func:`rmdir` except that, if the + Remove directories recursively. Works like :func:`rmdir` except that, if the leaf directory is successfully removed, :func:`removedirs` tries to successively remove every parent directory mentioned in *path* until an error is raised (which is ignored, because it generally means that a parent directory @@ -1101,7 +1102,7 @@ Files and Directories Rename the file or directory *src* to *dst*. If *dst* is a directory, :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will - be removed silently if the user has permission. The operation may fail on some + be replaced silently if the user has permission. The operation may fail on some Unix flavors if *src* and *dst* are on different filesystems. If successful, the renaming will be an atomic operation (this is a POSIX requirement). On Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a @@ -1135,7 +1136,7 @@ Files and Directories object whose attributes correspond to the members of the :ctype:`stat` structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links), - :attr:`st_uid` (user ID of owner), :attr:`st_gid` (group ID of owner), + :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner), :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent access), :attr:`st_mtime` (time of most recent content modification), :attr:`st_ctime` (platform dependent; time of most recent metadata change on @@ -1150,7 +1151,7 @@ Files and Directories >>> .. versionchanged:: 2.3 - If :func:`stat_float_times` returns true, the time values are floats, measuring + If :func:`stat_float_times` returns ``True``, the time values are floats, measuring seconds. Fractions of a second may be reported if the system supports that. On Mac OS, the times are always floats. See :func:`stat_float_times` for further discussion. @@ -1196,7 +1197,7 @@ Files and Directories Added access to values as attributes of the returned object. .. versionchanged:: 2.5 - Added st_gen, st_birthtime. + Added :attr:`st_gen` and :attr:`st_birthtime`. .. function:: stat_float_times([newvalue]) @@ -1261,7 +1262,7 @@ Files and Directories to the filename. Applications are responsible for properly creating and managing files created using paths returned by :func:`tempnam`; no automatic cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR` - overrides *dir*, while on Windows the :envvar:`TMP` is used. The specific + overrides *dir*, while on Windows :envvar:`TMP` is used. The specific behavior of this function depends on the C library implementation; some aspects are underspecified in system documentation. @@ -1330,8 +1331,8 @@ Files and Directories single: directory; walking single: directory; traversal - :func:`walk` generates the file names in a directory tree, by walking the tree - either top down or bottom up. For each directory in the tree rooted at directory + Generate the file names in a directory tree by walking the tree + either top-down or bottom-up. For each directory in the tree rooted at directory *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, filenames)``. @@ -1342,29 +1343,29 @@ Files and Directories (which begins with *top*) to a file or directory in *dirpath*, do ``os.path.join(dirpath, name)``. - If optional argument *topdown* is true or not specified, the triple for a + If optional argument *topdown* is ``True`` or not specified, the triple for a directory is generated before the triples for any of its subdirectories - (directories are generated top down). If *topdown* is false, the triple for a + (directories are generated top-down). If *topdown* is ``False``, the triple for a directory is generated after the triples for all of its subdirectories - (directories are generated bottom up). + (directories are generated bottom-up). - When *topdown* is true, the caller can modify the *dirnames* list in-place + When *topdown* is ``True``, the caller can modify the *dirnames* list in-place (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only recurse into the subdirectories whose names remain in *dirnames*; this can be used to prune the search, impose a specific order of visiting, or even to inform :func:`walk` about directories the caller creates or renames before it resumes - :func:`walk` again. Modifying *dirnames* when *topdown* is false is + :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is ineffective, because in bottom-up mode the directories in *dirnames* are generated before *dirpath* itself is generated. - By default errors from the ``os.listdir()`` call are ignored. If optional + By default errors from the :func:`listdir` call are ignored. If optional argument *onerror* is specified, it should be a function; it will be called with one argument, an :exc:`OSError` instance. It can report the error to continue with the walk, or raise the exception to abort the walk. Note that the filename is available as the ``filename`` attribute of the exception object. By default, :func:`walk` will not walk down into symbolic links that resolve to - directories. Set *followlinks* to True to visit directories pointed to by + directories. Set *followlinks* to ``True`` to visit directories pointed to by symlinks, on systems that support them. .. versionadded:: 2.6 @@ -1372,7 +1373,7 @@ Files and Directories .. note:: - Be aware that setting *followlinks* to true can lead to infinite recursion if a + Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a link points to a parent directory of itself. :func:`walk` does not keep track of the directories it visited already. @@ -1395,10 +1396,10 @@ Files and Directories if 'CVS' in dirs: dirs.remove('CVS') # don't visit CVS directories - In the next example, walking the tree bottom up is essential: :func:`rmdir` + In the next example, walking the tree bottom-up is essential: :func:`rmdir` doesn't allow deleting a directory before the directory is empty:: - # Delete everything reachable from the directory named in 'top', + # Delete everything reachable from the directory named in "top", # assuming there are no symbolic links. # CAUTION: This is dangerous! For example, if top == '/', it # could delete all your disk files. @@ -1448,19 +1449,19 @@ to be ignored. These functions all execute a new program, replacing the current process; they do not return. On Unix, the new executable is loaded into the current process, - and will have the same process ID as the caller. Errors will be reported as + and will have the same process id as the caller. Errors will be reported as :exc:`OSError` exceptions. - The ``'l'`` and ``'v'`` variants of the :func:`exec\*` functions differ in how - command-line arguments are passed. The ``'l'`` variants are perhaps the easiest + The "l" and "v" variants of the :func:`exec\*` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest to work with if the number of parameters is fixed when the code is written; the individual parameters simply become additional parameters to the :func:`execl\*` - functions. The ``'v'`` variants are good when the number of parameters is + functions. The "v" variants are good when the number of parameters is variable, with the arguments being passed in a list or tuple as the *args* parameter. In either case, the arguments to the child process should start with the name of the command being run, but this is not enforced. - The variants which include a ``'p'`` near the end (:func:`execlp`, + The variants which include a "p" near the end (:func:`execlp`, :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the environment is being replaced (using one of the :func:`exec\*e` variants, @@ -1471,7 +1472,7 @@ to be ignored. path. For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note - that these all end in ``'e'``), the *env* parameter must be a mapping which is + that these all end in "e"), the *env* parameter must be a mapping which is used to define the environment variables for the new process; the :func:`execl`, :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to inherit the environment of the current process. Availability: Macintosh, Unix, @@ -1488,7 +1489,7 @@ to be ignored. The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only be used in the child process after a :func:`fork`. -The following exit codes are a defined, and can be used with :func:`_exit`, +The following exit codes are defined and can be used with :func:`_exit`, although they are not required. These are typically used for system programs written in Python, such as a mail server's external command delivery program. @@ -1638,7 +1639,7 @@ written in Python, such as a mail server's external command delivery program. .. function:: fork() - Fork a child process. Return ``0`` in the child, the child's process id in the + Fork a child process. Return ``0`` in the child and the child's process id in the parent. Availability: Macintosh, Unix. @@ -1648,7 +1649,7 @@ written in Python, such as a mail server's external command delivery program. terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the new child's process id in the parent, and *fd* is the file descriptor of the master end of the pseudo-terminal. For a more portable approach, use the - :mod:`pty` module. Availability: Macintosh, Some flavors of Unix. + :mod:`pty` module. Availability: Macintosh, some flavors of Unix. .. function:: kill(pid, sig) @@ -1712,22 +1713,22 @@ written in Python, such as a mail server's external command delivery program. spawning new processes and retrieving their results; using that module is preferable to using these functions.) - If *mode* is :const:`P_NOWAIT`, this function returns the process ID of the new + If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it exits normally, or ``-signal``, where *signal* is the signal that killed the - process. On Windows, the process ID will actually be the process handle, so can + process. On Windows, the process id will actually be the process handle, so can be used with the :func:`waitpid` function. - The ``'l'`` and ``'v'`` variants of the :func:`spawn\*` functions differ in how - command-line arguments are passed. The ``'l'`` variants are perhaps the easiest + The "l" and "v" variants of the :func:`spawn\*` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest to work with if the number of parameters is fixed when the code is written; the individual parameters simply become additional parameters to the - :func:`spawnl\*` functions. The ``'v'`` variants are good when the number of + :func:`spawnl\*` functions. The "v" variants are good when the number of parameters is variable, with the arguments being passed in a list or tuple as the *args* parameter. In either case, the arguments to the child process must start with the name of the command being run. - The variants which include a second ``'p'`` near the end (:func:`spawnlp`, + The variants which include a second "p" near the end (:func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the environment is being replaced (using one of the :func:`spawn\*e` variants, @@ -1738,7 +1739,7 @@ written in Python, such as a mail server's external command delivery program. appropriate absolute or relative path. For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` - (note that these all end in ``'e'``), the *env* parameter must be a mapping + (note that these all end in "e"), the *env* parameter must be a mapping which is used to define the environment variables for the new process; the :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause the new process to inherit the environment of the current process. @@ -1763,7 +1764,7 @@ written in Python, such as a mail server's external command delivery program. Possible values for the *mode* parameter to the :func:`spawn\*` family of functions. If either of these values is given, the :func:`spawn\*` functions - will return as soon as the new process has been created, with the process ID as + will return as soon as the new process has been created, with the process id as the return value. Availability: Macintosh, Unix, Windows. .. versionadded:: 1.6 @@ -1825,8 +1826,8 @@ written in Python, such as a mail server's external command delivery program. Execute the command (a string) in a subshell. This is implemented by calling the Standard C function :cfunc:`system`, and has the same limitations. Changes - to ``posix.environ``, ``sys.stdin``, etc. are not reflected in the environment - of the executed command. + to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the + environment of the executed command. On Unix, the return value is the exit status of the process encoded in the format specified for :func:`wait`. Note that POSIX does not specify the meaning @@ -1945,36 +1946,36 @@ used to determine the disposition of a process. .. function:: WCOREDUMP(status) - Returns ``True`` if a core dump was generated for the process, otherwise it - returns ``False``. Availability: Macintosh, Unix. + Return ``True`` if a core dump was generated for the process, otherwise + return ``False``. Availability: Macintosh, Unix. .. versionadded:: 2.3 .. function:: WIFCONTINUED(status) - Returns ``True`` if the process has been continued from a job control stop, - otherwise it returns ``False``. Availability: Unix. + Return ``True`` if the process has been continued from a job control stop, + otherwise return ``False``. Availability: Unix. .. versionadded:: 2.3 .. function:: WIFSTOPPED(status) - Returns ``True`` if the process has been stopped, otherwise it returns + Return ``True`` if the process has been stopped, otherwise return ``False``. Availability: Unix. .. function:: WIFSIGNALED(status) - Returns ``True`` if the process exited due to a signal, otherwise it returns + Return ``True`` if the process exited due to a signal, otherwise return ``False``. Availability: Macintosh, Unix. .. function:: WIFEXITED(status) - Returns ``True`` if the process exited using the :manpage:`exit(2)` system call, - otherwise it returns ``False``. Availability: Macintosh, Unix. + Return ``True`` if the process exited using the :manpage:`exit(2)` system call, + otherwise return ``False``. Availability: Macintosh, Unix. .. function:: WEXITSTATUS(status) @@ -2053,7 +2054,7 @@ Miscellaneous System Information defined for those names by the host operating system. This can be used to determine the set of names known to the system. Availability: Macintosh, Unix. -The follow data values are used to support path manipulation operations. These +The following data values are used to support path manipulation operations. These are defined for all platforms. Higher-level operations on pathnames are defined in the :mod:`os.path` module. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 7a0e24dcc91..40e11da544f 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -398,7 +398,7 @@ for bit-strings. Negative numbers are treated as their 2's complement value (for long integers, this assumes a sufficiently large number of bits that no overflow occurs during the operation). -The priorities of the binary bit-wise operations are all lower than the numeric +The priorities of the binary bitwise operations are all lower than the numeric operations and higher than the comparisons; the unary operation ``~`` has the same priority as the other unary numeric operations (``+`` and ``-``). @@ -2029,7 +2029,12 @@ Files have the following methods: argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's - end). There is no return value. Note that if the file is opened for appending + end). There is no return value. + + For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and + ``f.seek(-3, os.SEEK_END)`` sets the position to the third to last. + + Note that if the file is opened for appending (mode ``'a'`` or ``'a+'``), any :meth:`seek` operations will be undone at the next write. If the file is only opened for writing in append mode (mode ``'a'``), this method is essentially a no-op, but it remains useful for files diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst index c4c04bd058e..f9ca89b9d87 100644 --- a/Doc/library/winsound.rst +++ b/Doc/library/winsound.rst @@ -36,7 +36,7 @@ provided by Windows platforms. It includes functions and several constants. Call the underlying :cfunc:`PlaySound` function from the Platform API. The *sound* parameter may be a filename, audio data as a string, or ``None``. Its - interpretation depends on the value of *flags*, which can be a bit-wise ORed + interpretation depends on the value of *flags*, which can be a bitwise ORed combination of the constants described below. If the system indicates an error, :exc:`RuntimeError` is raised. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index ea2bb1a057d..21bd750a3c9 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -811,9 +811,9 @@ Unary arithmetic operations .. index:: triple: unary; arithmetic; operation - triple: unary; bit-wise; operation + triple: unary; bitwise; operation -All unary arithmetic (and bit-wise) operations have the same priority: +All unary arithmetic (and bitwise) operations have the same priority: .. productionlist:: u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` @@ -830,8 +830,8 @@ The unary ``+`` (plus) operator yields its numeric argument unchanged. .. index:: single: inversion -The unary ``~`` (invert) operator yields the bit-wise inversion of its plain or -long integer argument. The bit-wise inversion of ``x`` is defined as +The unary ``~`` (invert) operator yields the bitwise inversion of its plain or +long integer argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only applies to integral numbers. .. index:: exception: TypeError @@ -944,10 +944,10 @@ Negative shift counts raise a :exc:`ValueError` exception. .. _bitwise: -Binary bit-wise operations -========================== +Binary bitwise operations +========================= -.. index:: triple: binary; bit-wise; operation +.. index:: triple: binary; bitwise; operation Each of the three bitwise operations has a different priority level: @@ -956,20 +956,20 @@ Each of the three bitwise operations has a different priority level: xor_expr: `and_expr` | `xor_expr` "^" `and_expr` or_expr: `xor_expr` | `or_expr` "|" `xor_expr` -.. index:: pair: bit-wise; and +.. index:: pair: bitwise; and The ``&`` operator yields the bitwise AND of its arguments, which must be plain or long integers. The arguments are converted to a common type. .. index:: - pair: bit-wise; xor + pair: bitwise; xor pair: exclusive; or The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which must be plain or long integers. The arguments are converted to a common type. .. index:: - pair: bit-wise; or + pair: bitwise; or pair: inclusive; or The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py index 4e0c1f8012c..60e3c8133de 100644 --- a/Lib/test/test_doctest.py +++ b/Lib/test/test_doctest.py @@ -909,7 +909,7 @@ Tests of `DocTestRunner`'s option flag handling. Several option flags can be used to customize the behavior of the test runner. These are defined as module constants in doctest, and passed -to the DocTestRunner constructor (multiple constants should be or-ed +to the DocTestRunner constructor (multiple constants should be ORed together). The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False diff --git a/Modules/fcntlmodule.c b/Modules/fcntlmodule.c index 4e49a7d1201..1e4a254fd17 100644 --- a/Modules/fcntlmodule.c +++ b/Modules/fcntlmodule.c @@ -378,7 +378,7 @@ following values:\n\ LOCK_SH - acquire a shared lock\n\ LOCK_EX - acquire an exclusive lock\n\ \n\ -When operation is LOCK_SH or LOCK_EX, it can also be bit-wise OR'd with\n\ +When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with\n\ LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and the\n\ lock cannot be acquired, an IOError will be raised and the exception will\n\ have an errno attribute set to EACCES or EAGAIN (depending on the operating\n\