Issue #19207: Improved cross-references in the os, os.path, and posix modules

serhiy-storchaka · serhiy-storchaka · commit 690a6a95bda2 · 2013-10-13T20:13:37.000+03:00
documentation.
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
@@ -271,9 +271,9 @@ the :mod:`glob` module.)
 .. function:: samestat(stat1, stat2)
 
    Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
-   These structures may have been returned by :func:`fstat`, :func:`lstat`, or
-   :func:`stat`.  This function implements the underlying comparison used by
-   :func:`samefile` and :func:`sameopenfile`.
+   These structures may have been returned by :func:`os.fstat`,
+   :func:`os.lstat`, or :func:`os.stat`.  This function implements the
+   underlying comparison used by :func:`samefile` and :func:`sameopenfile`.
 
    Availability: Unix, Windows.
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
@@ -643,7 +643,7 @@ process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
 by file descriptors.
 
-The :meth:`~file.fileno` method can be used to obtain the file descriptor
+The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor
 associated with a :term:`file object` when required.  Note that using the file
 descriptor directly will bypass the file object methods, ignoring aspects such
 as internal buffering of data.
@@ -660,7 +660,7 @@ as internal buffering of data.
       This function is intended for low-level I/O and must be applied to a file
       descriptor as returned by :func:`os.open` or :func:`pipe`.  To close a "file
       object" returned by the built-in function :func:`open` or by :func:`popen` or
-      :func:`fdopen`, use its :meth:`~file.close` method.
+      :func:`fdopen`, use its :meth:`~io.IOBase.close` method.
 
 
 .. function:: closerange(fd_low, fd_high)
@@ -834,7 +834,7 @@ as internal buffering of data.
    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
+   current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
    the file. Return the new cursor position in bytes, starting from the beginning.
 
    Availability: Unix, Windows.
@@ -1217,7 +1217,7 @@ execution of a new program, other file descriptors are inherited.
 
 On Windows, non-inheritable handles and file descriptors are closed in child
 processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout
-and stderr), which are always inherited.  Using :func:`os.spawn*` functions,
+and stderr), which are always inherited.  Using :func:`spawn\* <spawnl>` functions,
 all inheritable handles and all inheritable file descriptors are inherited.
 Using the :mod:`subprocess` module, all file descriptors except standard
 streams are closed, and inheritable handles are only inherited if the
@@ -1993,7 +1993,7 @@ features:
 
 .. data:: supports_dir_fd
 
-   A :class:`~collections.Set` object indicating which functions in the
+   A :class:`~collections.abc.Set` object indicating which functions in the
    :mod:`os` module permit use of their *dir_fd* parameter.  Different platforms
    provide different functionality, and an option that might work on one might
    be unsupported on another.  For consistency's sakes, functions that support
@@ -2015,7 +2015,7 @@ features:
 
 .. data:: supports_effective_ids
 
-   A :class:`~collections.Set` object indicating which functions in the
+   A :class:`~collections.abc.Set` object indicating which functions in the
    :mod:`os` module permit use of the *effective_ids* parameter for
    :func:`os.access`.  If the local platform supports it, the collection will
    contain :func:`os.access`, otherwise it will be empty.
@@ -2033,7 +2033,7 @@ features:
 
 .. data:: supports_fd
 
-   A :class:`~collections.Set` object indicating which functions in the
+   A :class:`~collections.abc.Set` object indicating which functions in the
    :mod:`os` module permit specifying their *path* parameter as an open file
    descriptor.  Different platforms provide different functionality, and an
    option that might work on one might be unsupported on another.  For
@@ -2054,7 +2054,7 @@ features:
 
 .. data:: supports_follow_symlinks
 
-   A :class:`~collections.Set` object indicating which functions in the
+   A :class:`~collections.abc.Set` object indicating which functions in the
    :mod:`os` module permit use of their *follow_symlinks* parameter.  Different
    platforms provide different functionality, and an option that might work on
    one might be unsupported on another.  For consistency's sakes, functions that
@@ -2403,7 +2403,7 @@ Process Management
 
 These functions may be used to create and manage processes.
 
-The various :func:`exec\*` functions take a list of arguments for the new
+The various :func:`exec\* <execl>` functions take a list of arguments for the new
 program loaded into the process.  In each case, the first of these arguments is
 passed to the new program as its own name rather than as an argument a user may
 have typed on a command line.  For the C programmer, this is the ``argv[0]``
@@ -2441,9 +2441,9 @@ to be ignored.
    descriptors are not flushed, so if there may be data buffered
    on these open files, you should flush them using
    :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
-   :func:`exec\*` function.
+   :func:`exec\* <execl>` function.
 
-   The "l" and "v" variants of the :func:`exec\*` functions differ in how
+   The "l" and "v" variants of the :func:`exec\* <execl>` 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\*`
@@ -2455,7 +2455,7 @@ to be ignored.
    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,
+   environment is being replaced (using one of the :func:`exec\*e <execl>` variants,
    discussed in the next paragraph), the new environment is used as the source of
    the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
    :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
@@ -2701,7 +2701,6 @@ written in Python, such as a mail server's external command delivery program.
 
 
 .. function:: popen(...)
-   :noindex:
 
    Run child processes, returning opened pipes for communications.  These functions
    are described in section :ref:`os-newstreams`.
@@ -2729,7 +2728,7 @@ written in Python, such as a mail server's external command delivery program.
    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
+   The "l" and "v" variants of the :func:`spawn\* <spawnl>` 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
@@ -2741,7 +2740,7 @@ written in Python, such as a mail server's external command delivery program.
    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,
+   environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants,
    discussed in the next paragraph), the new environment is used as the source of
    the :envvar:`PATH` variable.  The other variants, :func:`spawnl`,
    :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
@@ -2775,7 +2774,7 @@ written in Python, such as a mail server's external command delivery program.
 .. data:: P_NOWAIT
           P_NOWAITO
 
-   Possible values for the *mode* parameter to the :func:`spawn\*` family of
+   Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` 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
    the return value.
@@ -2785,7 +2784,7 @@ written in Python, such as a mail server's external command delivery program.
 
 .. data:: P_WAIT
 
-   Possible value for the *mode* parameter to the :func:`spawn\*` family of
+   Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
    functions.  If this is given as *mode*, the :func:`spawn\*` functions will not
    return until the new process has run to completion and will return the exit code
    of the process the run is successful, or ``-signal`` if a signal kills the
@@ -2797,11 +2796,11 @@ written in Python, such as a mail server's external command delivery program.
 .. data:: P_DETACH
           P_OVERLAY
 
-   Possible values for the *mode* parameter to the :func:`spawn\*` family of
+   Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
    functions.  These are less portable than those listed above. :const:`P_DETACH`
    is similar to :const:`P_NOWAIT`, but the new process is detached from the
    console of the calling process. If :const:`P_OVERLAY` is used, the current
-   process will be replaced; the :func:`spawn\*` function will not return.
+   process will be replaced; the :func:`spawn\* <spawnl>` function will not return.
 
    Availability: Windows.
 
@@ -2973,17 +2972,18 @@ written in Python, such as a mail server's external command delivery program.
    (shifting makes cross-platform use of the function easier). A *pid* less than or
    equal to ``0`` has no special meaning on Windows, and raises an exception. The
    value of integer *options* has no effect. *pid* can refer to any process whose
-   id is known, not necessarily a child process. The :func:`spawn` functions called
-   with :const:`P_NOWAIT` return suitable process handles.
+   id is known, not necessarily a child process. The :func:`spawn\* <spawnl>`
+   functions called with :const:`P_NOWAIT` return suitable process handles.
 
 
 .. function:: wait3(options)
 
    Similar to :func:`waitpid`, except no process id argument is given and a
    3-element tuple containing the child's process id, exit status indication, and
    resource usage information is returned.  Refer to :mod:`resource`.\
-   :func:`getrusage` for details on resource usage information.  The option
-   argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
+   :func:`~resource.getrusage` for details on resource usage information.  The
+   option argument is the same as that provided to :func:`waitpid` and
+   :func:`wait4`.
 
    Availability: Unix.
 
@@ -2992,9 +2992,9 @@ written in Python, such as a mail server's external command delivery program.
 
    Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
    process id, exit status indication, and resource usage information is returned.
-   Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
-   information.  The arguments to :func:`wait4` are the same as those provided to
-   :func:`waitpid`.
+   Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on
+   resource usage information.  The arguments to :func:`wait4` are the same
+   as those provided to :func:`waitpid`.
 
    Availability: Unix.
 
@@ -3330,8 +3330,9 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module.
 
 .. data:: defpath
 
-   The default search path used by :func:`exec\*p\*` and :func:`spawn\*p\*` if the
-   environment doesn't have a ``'PATH'`` key. Also available via :mod:`os.path`.
+   The default search path used by :func:`exec\*p\* <execl>` and
+   :func:`spawn\*p\* <spawnl>` if the environment doesn't have a ``'PATH'``
+   key. Also available via :mod:`os.path`.
 
 
 .. data:: linesep
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
@@ -19,7 +19,7 @@ systems the :mod:`posix` module is not available, but a subset is always
 available through the :mod:`os` interface.  Once :mod:`os` is imported, there is
 *no* performance penalty in using it instead of :mod:`posix`.  In addition,
 :mod:`os` provides some additional functionality, such as automatically calling
-:func:`putenv` when an entry in ``os.environ`` is changed.
+:func:`~os.putenv` when an entry in ``os.environ`` is changed.
 
 Errors are reported as exceptions; the usual exceptions are given for type
 errors, while errors reported by the system calls raise :exc:`OSError`.
@@ -74,9 +74,10 @@ In addition to many functions described in the :mod:`os` module documentation,
    pathname of your home directory, equivalent to ``getenv("HOME")`` in C.
 
    Modifying this dictionary does not affect the string environment passed on by
-   :func:`execv`, :func:`popen` or :func:`system`; if you need to change the
-   environment, pass ``environ`` to :func:`execve` or add variable assignments and
-   export statements to the command string for :func:`system` or :func:`popen`.
+   :func:`~os.execv`, :func:`~os.popen` or :func:`~os.system`; if you need to
+   change the environment, pass ``environ`` to :func:`~os.execve` or add
+   variable assignments and export statements to the command string for
+   :func:`~os.system` or :func:`~os.popen`.
 
    .. versionchanged:: 3.2
       On Unix, keys and values are bytes.
