[Python-checkins] cpython (2.7): Issue #19207: Improved cross-references in the os, os.path, and posix modules
serhiy.storchaka
python-checkins at python.org
Sun Oct 13 19:26:21 CEST 2013
http://hg.python.org/cpython/rev/fd2c34e0104b
changeset: 86324:fd2c34e0104b
branch: 2.7
parent: 86317:d513149e0c19
user: Serhiy Storchaka <storchaka at gmail.com>
date: Sun Oct 13 20:25:30 2013 +0300
summary:
Issue #19207: Improved cross-references in the os, os.path, and posix modules
documentation.
files:
Doc/library/os.path.rst | 6 +-
Doc/library/os.rst | 44 +++++++++++++++-------------
Doc/library/posix.rst | 9 +++--
3 files changed, 31 insertions(+), 28 deletions(-)
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -267,9 +267,9 @@
.. 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.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -615,7 +615,7 @@
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)
@@ -743,7 +743,7 @@
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.
Availability: Unix, Windows.
@@ -1676,7 +1676,7 @@
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]``
@@ -1714,9 +1714,9 @@
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.
-
- The "l" and "v" variants of the :func:`exec\*` functions differ in how
+ :func:`exec\* <execl>` function.
+
+ 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\*`
@@ -1728,7 +1728,7 @@
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
@@ -2030,7 +2030,7 @@
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
@@ -2042,7 +2042,7 @@
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
@@ -2078,7 +2078,7 @@
.. 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.
@@ -2090,7 +2090,7 @@
.. 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
@@ -2104,7 +2104,7 @@
.. 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
@@ -2220,8 +2220,8 @@
(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)
@@ -2229,8 +2229,9 @@
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.
@@ -2241,9 +2242,9 @@
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.
@@ -2467,8 +2468,9 @@
.. 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
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -19,7 +19,7 @@
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 @@
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`.
.. note::
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list