[Python-checkins] r80897 - in python/branches/py3k: Doc/library/os.path.rst Doc/library/os.rst

benjamin.peterson python-checkins at python.org
Fri May 7 01:03:06 CEST 2010


Author: benjamin.peterson
Date: Fri May  7 01:03:05 2010
New Revision: 80897

Log:
Merged revisions 80894,80896 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r80894 | benjamin.peterson | 2010-05-06 17:33:46 -0500 (Thu, 06 May 2010) | 1 line
  
  Availability gets its own line
........
  r80896 | benjamin.peterson | 2010-05-06 17:49:28 -0500 (Thu, 06 May 2010) | 1 line
  
  ensure that availability information is on its own line at the end of the function docs
........


Modified:
   python/branches/py3k/   (props changed)
   python/branches/py3k/Doc/library/os.path.rst
   python/branches/py3k/Doc/library/os.rst

Modified: python/branches/py3k/Doc/library/os.path.rst
==============================================================================
--- python/branches/py3k/Doc/library/os.path.rst	(original)
+++ python/branches/py3k/Doc/library/os.path.rst	Fri May  7 01:03:05 2010
@@ -223,19 +223,24 @@
    Return a relative filepath to *path* either from the current directory or from
    an optional *start* point.
 
-   *start* defaults to :attr:`os.curdir`. Availability:  Windows, Unix.
+   *start* defaults to :attr:`os.curdir`.
+
+   Availability:  Windows, Unix.
 
 
 .. function:: samefile(path1, path2)
 
    Return ``True`` if both pathname arguments refer to the same file or directory
    (as indicated by device number and i-node number). Raise an exception if a
-   :func:`os.stat` call on either pathname fails. Availability: Unix.
+   :func:`os.stat` call on either pathname fails.
+
+   Availability: Unix.
 
 
 .. function:: sameopenfile(fp1, fp2)
 
    Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
+
    Availability: Unix.
 
 
@@ -244,7 +249,9 @@
    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`. Availability: Unix.
+   :func:`samefile` and :func:`sameopenfile`.
+
+   Availability: Unix.
 
 
 .. function:: split(path)
@@ -293,7 +300,9 @@
    Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC
    mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of
    the path (such as  ``r'\path\file.ext'``).  For paths containing drive letters,
-   *unc* will always be the empty string. Availability:  Windows.
+   *unc* will always be the empty string.
+
+   Availability:  Windows.
 
 
 .. data:: supports_unicode_filenames

Modified: python/branches/py3k/Doc/library/os.rst
==============================================================================
--- python/branches/py3k/Doc/library/os.rst	(original)
+++ python/branches/py3k/Doc/library/os.rst	Fri May  7 01:03:05 2010
@@ -41,6 +41,9 @@
 * If not separately noted, all functions that claim "Availability: Unix" are
   supported on Mac OS X, which builds on a Unix core.
 
+.. Availability notes get their own line and occur at the end of the function
+.. documentation.
+
 .. note::
 
    All functions in this module raise :exc:`OSError` in the case of invalid or
@@ -166,33 +169,40 @@
 .. function:: ctermid()
 
    Return the filename corresponding to the controlling terminal of the process.
+
    Availability: Unix.
 
 
 .. 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:
-   Unix.
+   "set id" bit on the file being executed in the current process.
+
+   Availability: Unix.
 
 
 .. function:: geteuid()
 
    .. index:: single: user; effective id
 
-   Return the current process's effective user id. Availability: Unix.
+   Return the current process's effective user id.
+
+   Availability: Unix.
 
 
 .. function:: getgid()
 
    .. index:: single: process; group
 
-   Return the real group id of the current process. Availability: Unix.
+   Return the real group id of the current process.
+
+   Availability: Unix.
 
 
 .. function:: getgroups()
 
    Return list of supplemental group ids associated with the current process.
+
    Availability: Unix.
 
 
@@ -200,7 +210,9 @@
 
    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
-   group id. Availability: Unix.
+   group id.
+
+   Availability: Unix.
 
    .. versionadded:: 3.2
 
@@ -211,40 +223,51 @@
    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)
 
    Return the process group id of the process with process id *pid*. If *pid* is 0,
-   the process group id of the current process is returned. Availability: Unix.
+   the process group id of the current process is returned.
 
+   Availability: Unix.
 
 .. function:: getpgrp()
 
    .. index:: single: process; group
 
-   Return the id of the current process group. Availability: Unix.
+   Return the id of the current process group.
+
+   Availability: Unix.
 
 
 .. function:: getpid()
 
    .. index:: single: process; id
 
-   Return the current process id. Availability: Unix, Windows.
+   Return the current process id.
+
+   Availability: Unix, Windows.
 
 
 .. function:: getppid()
 
    .. index:: single: process; id of parent
 
-   Return the parent's process id. Availability: Unix.
+   Return the parent's process id.
+
+   Availability: Unix.
 
 
 .. function:: getresuid()
 
    Return a tuple (ruid, euid, suid) denoting the current process's
-   real, effective, and saved user ids. Availability: Unix.
+   real, effective, and saved user ids.
+
+   Availability: Unix.
 
    .. versionadded:: 3.2
 
@@ -252,7 +275,9 @@
 .. function:: getresgid()
 
    Return a tuple (rgid, egid, sgid) denoting the current process's
-   real, effective, and saved user ids. Availability: Unix.
+   real, effective, and saved user ids.
+
+   Availability: Unix.
 
    .. versionadded:: 3.2
 
@@ -261,19 +286,22 @@
 
    .. index:: single: user; id
 
-   Return the current process's user id. Availability: Unix.
+   Return the current process's user id.
+
+   Availability: Unix.
 
 
 .. function:: getenv(key, default=None)
 
    Return the value of the environment variable *key* if it exists, or
    *default* if it doesn't. *key*, *default* and the result are str.
-   Availability: most flavors of Unix, Windows.
 
    On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
    and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
    would like to use a different encoding.
 
+   Availability: most flavors of Unix, Windows.
+
 
 .. function:: getenvb(key, default=None)
 
@@ -291,8 +319,9 @@
 
    Set the environment variable named *key* to the string *value*.  Such
    changes to the environment affect subprocesses started with :func:`os.system`,
-   :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
-   Unix, Windows.
+   :func:`popen` or :func:`fork` and :func:`execv`.
+
+   Availability: most flavors of Unix, Windows.
 
    .. note::
 
@@ -307,17 +336,23 @@
 
 .. function:: setegid(egid)
 
-   Set the current process's effective group id. Availability: Unix.
+   Set the current process's effective group id.
+
+   Availability: Unix.
 
 
 .. function:: seteuid(euid)
 
-   Set the current process's effective user id. Availability: Unix.
+   Set the current process's effective user id.
+
+   Availability: Unix.
 
 
 .. function:: setgid(gid)
 
-   Set the current process' group id. Availability: Unix.
+   Set the current process' group id.
+
+   Availability: Unix.
 
 
 .. function:: setgroups(groups)
@@ -325,6 +360,7 @@
    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 typically available only to the superuser.
+
    Availability: Unix.
 
 
@@ -332,6 +368,7 @@
 
    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.
 
 
@@ -339,17 +376,22 @@
 
    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.
+   for the semantics.
+
+   Availability: Unix.
 
 
 .. function:: setregid(rgid, egid)
 
-   Set the current process's real and effective group ids. Availability: Unix.
+   Set the current process's real and effective group ids.
+
+   Availability: Unix.
 
 
 .. function:: setresgid(rgid, egid, sgid)
 
    Set the current process's real, effective, and saved group ids.
+
    Availability: Unix.
 
    .. versionadded:: 3.2
@@ -358,6 +400,7 @@
 .. function:: setresuid(ruid, euid, suid)
 
    Set the current process's real, effective, and saved user ids.
+
    Availibility: Unix.
 
    .. versionadded:: 3.2
@@ -365,18 +408,22 @@
 
 .. function:: setreuid(ruid, euid)
 
-   Set the current process's real and effective user ids. Availability: Unix.
+   Set the current process's real and effective user ids.
+
+   Availability: Unix.
 
 
 .. function:: getsid(pid)
 
    Call the system call :cfunc:`getsid`.  See the Unix manual for the semantics.
+
    Availability: Unix.
 
 
 .. function:: setsid()
 
    Call the system call :cfunc:`setsid`.  See the Unix manual for the semantics.
+
    Availability: Unix.
 
 
@@ -384,7 +431,9 @@
 
    .. index:: single: user; id, setting
 
-   Set the current process's 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
@@ -392,13 +441,16 @@
 
    Return the error message corresponding to the error code in *code*.
    On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
-   error number, :exc:`ValueError` is raised.  Availability: Unix, Windows.
+   error number, :exc:`ValueError` is raised.
+
+   Availability: Unix, Windows.
 
 
 .. function:: umask(mask)
 
-   Set the current numeric umask and return the previous umask. Availability:
-   Unix, Windows.
+   Set the current numeric umask and return the previous umask.
+
+   Availability: Unix, Windows.
 
 
 .. function:: uname()
@@ -412,8 +464,9 @@
    machine)``.  Some systems truncate the nodename to 8 characters or to the
    leading component; a better way to get the hostname is
    :func:`socket.gethostname`  or even
-   ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
-   Unix.
+   ``socket.gethostbyaddr(socket.gethostname())``.
+
+   Availability: recent flavors of Unix.
 
 
 .. function:: unsetenv(key)
@@ -422,13 +475,15 @@
 
    Unset (delete) the environment variable named *key*. Such changes to the
    environment affect subprocesses started with :func:`os.system`, :func:`popen` or
-   :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
+   :func:`fork` and :func:`execv`.
 
    When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
    automatically translated into a corresponding call to :func:`unsetenv`; however,
    calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
    preferable to delete items of ``os.environ``.
 
+   Availability: most flavors of Unix, Windows.
+
 
 .. _os-newstreams:
 
@@ -444,7 +499,7 @@
 
    Return an open file object connected to the file descriptor *fd*.  The *mode*
    and *bufsize* arguments have the same meaning as the corresponding arguments to
-   the built-in :func:`open` function. Availability: Unix, Windows.
+   the built-in :func:`open` function.
 
    When specified, the *mode* argument must start with one of the letters
    ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
@@ -453,6 +508,8 @@
    set on the file descriptor (which the :cfunc:`fdopen` implementation already
    does on most platforms).
 
+   Availability: Unix, Windows.
+
 
 .. _os-fd-ops:
 
@@ -475,7 +532,9 @@
 
 .. function:: close(fd)
 
-   Close file descriptor *fd*. Availability: Unix, Windows.
+   Close file descriptor *fd*.
+
+   Availability: Unix, Windows.
 
    .. note::
 
@@ -488,7 +547,7 @@
 .. function:: closerange(fd_low, fd_high)
 
    Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
-   ignoring errors. Availability: Unix, Windows. Equivalent to::
+   ignoring errors. Equivalent to::
 
       for fd in range(fd_low, fd_high):
           try:
@@ -496,6 +555,8 @@
           except OSError:
               pass
 
+   Availability: Unix, Windows.
+
 
 .. function:: device_encoding(fd)
 
@@ -505,33 +566,40 @@
 
 .. function:: dup(fd)
 
-   Return a duplicate of file descriptor *fd*. Availability: Unix,
-   Windows.
+   Return a duplicate of file descriptor *fd*.
+
+   Availability: Unix, Windows.
 
 
 .. function:: dup2(fd, fd2)
 
    Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
+
    Availability: Unix, Windows.
 
 
 .. function:: fchmod(fd, mode)
 
    Change the mode of the file given by *fd* to the numeric *mode*.  See the docs
-   for :func:`chmod` for possible values of *mode*.  Availability: Unix.
+   for :func:`chmod` for possible values of *mode*.
+
+   Availability: Unix.
 
 
 .. function:: fchown(fd, uid, gid)
 
    Change the owner and group id of the file given by *fd* to the numeric *uid*
    and *gid*.  To leave one of the ids unchanged, set it to -1.
+
    Availability: Unix.
 
 
 .. function:: fdatasync(fd)
 
    Force write of file with filedescriptor *fd* to disk. Does not force update of
-   metadata. Availability: Unix.
+   metadata.
+
+   Availability: Unix.
 
    .. note::
       This function is not available on MacOS.
@@ -546,24 +614,28 @@
    additional names as well.  The names known to the host operating system are
    given in the ``pathconf_names`` dictionary.  For configuration variables not
    included in that mapping, passing an integer for *name* is also accepted.
-   Availability: Unix.
 
    If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
    specific value for *name* is not supported by the host system, even if it is
    included in ``pathconf_names``, an :exc:`OSError` is raised with
    :const:`errno.EINVAL` for the error number.
 
+   Availability: Unix.
+
 
 .. function:: fstat(fd)
 
-   Return status for file descriptor *fd*, like :func:`stat`. Availability:
-   Unix, Windows.
+   Return status for file descriptor *fd*, like :func:`stat`.
+
+   Availability: Unix, Windows.
 
 
 .. function:: fstatvfs(fd)
 
    Return information about the filesystem containing the file associated with file
-   descriptor *fd*, like :func:`statvfs`. Availability: Unix.
+   descriptor *fd*, like :func:`statvfs`.
+
+   Availability: Unix.
 
 
 .. function:: fsync(fd)
@@ -573,19 +645,25 @@
 
    If you're starting with a Python file object *f*, first do ``f.flush()``, and
    then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
-   with *f* are written to disk.  Availability: Unix, Windows.
+   with *f* are written to disk.
+
+   Availability: Unix, and Windows.
 
 
 .. function:: ftruncate(fd, length)
 
    Truncate the file corresponding to file descriptor *fd*, so that it is at most
-   *length* bytes in size. Availability: Unix.
+   *length* bytes in size.
+
+   Availability: Unix.
 
 
 .. function:: isatty(fd)
 
    Return ``True`` if the file descriptor *fd* is open and connected to a
-   tty(-like) device, else ``False``. Availability: Unix.
+   tty(-like) device, else ``False``.
+
+   Availability: Unix.
 
 
 .. function:: lseek(fd, pos, how)
@@ -594,7 +672,9 @@
    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: Unix, Windows.
+   the file.
+
+   Availability: Unix, Windows.
 
 
 .. function:: open(file, flags[, mode])
@@ -602,17 +682,19 @@
    Open the file *file* and set various flags according to *flags* and possibly
    its mode according to *mode*.  The default *mode* is ``0o777`` (octal), and
    the current umask value is first masked out.  Return the file descriptor for
-   the newly opened file.  Availability: Unix, Windows.
+   the newly opened file.
 
    For a description of the flag and mode values, see the C run-time documentation;
    flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
    this module too (see below).
 
+   Availability: Unix, Windows.
+
    .. note::
 
       This function is intended for low-level I/O.  For normal usage, use the
       built-in function :func:`open`, which returns a "file object" with
-      :meth:`~file.read` and :meth:`~file.write` methods (and many more).  To
+      :meth:`~file.read` and :meth:`~file.wprite` methods (and many more).  To
       wrap a file descriptor in a "file object", use :func:`fdopen`.
 
 
@@ -622,21 +704,26 @@
 
    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: some flavors of
-   Unix.
+   approach, use the :mod:`pty` module.
+
+   Availability: some flavors of Unix.
 
 
 .. function:: pipe()
 
    Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for reading
-   and writing, respectively. Availability: Unix, Windows.
+   and writing, respectively.
+
+   Availability: Unix, Windows.
 
 
 .. function:: read(fd, n)
 
    Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
    bytes read.  If the end of the file referred to by *fd* has been reached, an
-   empty bytes object is returned. Availability: Unix, Windows.
+   empty bytes object is returned.
+
+   Availability: Unix, Windows.
 
    .. note::
 
@@ -650,26 +737,34 @@
 .. function:: tcgetpgrp(fd)
 
    Return the process group associated with the terminal given by *fd* (an open
-   file descriptor as returned by :func:`os.open`). Availability: Unix.
+   file descriptor as returned by :func:`os.open`).
+
+   Availability: Unix.
 
 
 .. 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*. Availability: Unix.
+   descriptor as returned by :func:`os.open`) to *pg*.
+
+   Availability: Unix.
 
 
 .. 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
-   exception is raised. Availability: Unix.
+   exception is raised.
+
+   Availability: Unix.
 
 
 .. function:: write(fd, str)
 
    Write the bytestring in *str* to file descriptor *fd*. Return the number of
-   bytes actually written. Availability: Unix, Windows.
+   bytes actually written.
+
+   Availability: Unix, Windows.
 
    .. note::
 
@@ -752,7 +847,9 @@
    can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
    :const:`X_OK` to test permissions.  Return :const:`True` if access is allowed,
    :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
-   information. Availability: Unix, Windows.
+   information.
+
+   Availability: Unix, Windows.
 
    .. note::
 
@@ -796,25 +893,31 @@
 
    .. index:: single: directory; changing
 
-   Change the current working directory to *path*. Availability: Unix,
-   Windows.
+   Change the current working directory to *path*.
+
+   Availability: Unix, Windows.
 
 
 .. function:: fchdir(fd)
 
    Change the current working directory to the directory represented by the file
    descriptor *fd*.  The descriptor must refer to an opened directory, not an open
-   file. Availability: Unix.
+   file.
+
+   Availability: Unix.
 
 
 .. function:: getcwd()
 
    Return a string representing the current working directory.
+
    Availability: Unix, Windows.
 
+
 .. function:: getcwdb()
 
    Return a bytestring representing the current working directory.
+
    Availability: Unix, Windows.
 
 
@@ -882,32 +985,41 @@
 .. function:: chown(path, uid, gid)
 
    Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
-   one of the ids unchanged, set it to -1. Availability: Unix.
+   one of the ids unchanged, set it to -1.
+
+   Availability: Unix.
 
 
 .. function:: lchflags(path, flags)
 
    Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
-   follow symbolic links. Availability: Unix.
+   follow symbolic links.
+
+   Availability: Unix.
 
 
 .. function:: lchmod(path, mode)
 
    Change the mode of *path* to the numeric *mode*. If path is a symlink, this
    affects the symlink rather than the target. See the docs for :func:`chmod`
-   for possible values of *mode*.  Availability: Unix.
+   for possible values of *mode*.
+
+   Availability: Unix.
 
 
 .. function:: lchown(path, uid, gid)
 
    Change the owner and group id of *path* to the numeric *uid* and *gid*. This
-   function will not follow symbolic links. Availability: Unix.
+   function will not follow symbolic links.
+
+   Availability: Unix.
 
 
 .. function:: link(source, link_name)
 
-   Create a hard link pointing to *source* named *link_name*. Availability:
-   Unix.
+   Create a hard link pointing to *source* named *link_name*.
+
+   Availability: Unix.
 
 
 .. function:: listdir(path)
@@ -915,11 +1027,12 @@
    Return a list containing the names of the entries in the directory given by
    *path*.  The list is in arbitrary order.  It does not include the special
    entries ``'.'`` and ``'..'`` even if they are present in the directory.
-   Availability: Unix, Windows.
 
    This function can be called with a bytes or string argument, and returns
    filenames of the same datatype.
 
+   Availability: Unix, Windows.
+
 
 .. function:: lstat(path)
 
@@ -932,7 +1045,7 @@
 
    Create a FIFO (a named pipe) named *path* with numeric mode *mode*.  The
    default *mode* is ``0o666`` (octal).  The current umask value is first masked
-   out from the mode. Availability: Unix.
+   out from the mode.
 
    FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
    are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
@@ -940,6 +1053,8 @@
    FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
    doesn't open the FIFO --- it just creates the rendezvous point.
 
+   Availability: Unix.
+
 
 .. function:: mknod(filename[, mode=0o600[, device]])
 
@@ -973,11 +1088,13 @@
 
    Create a directory named *path* with numeric mode *mode*. The default *mode*
    is ``0o777`` (octal).  On some systems, *mode* is ignored.  Where it is used,
-   the current umask value is first masked out. Availability: Unix, Windows.
+   the current umask value is first masked out.
 
    It is also possible to create temporary directories; see the
    :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
 
+   Availability: Unix, Windows.
+
 
 .. function:: makedirs(path[, mode])
 
@@ -1008,13 +1125,14 @@
    additional names as well.  The names known to the host operating system are
    given in the ``pathconf_names`` dictionary.  For configuration variables not
    included in that mapping, passing an integer for *name* is also accepted.
-   Availability: Unix.
 
    If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
    specific value for *name* is not supported by the host system, even if it is
    included in ``pathconf_names``, an :exc:`OSError` is raised with
    :const:`errno.EINVAL` for the error number.
 
+   Availability: Unix.
+
 
 .. data:: pathconf_names
 
@@ -1045,8 +1163,9 @@
    the :func:`unlink` function documented below.  On Windows, attempting to
    remove a file that is in use causes an exception to be raised; on Unix, the
    directory entry is removed but the storage allocated to the file is not made
-   available until the original file is no longer in use. Availability: Unix,
-   Windows.
+   available until the original file is no longer in use.
+
+   Availability: Unix, Windows.
 
 
 .. function:: removedirs(path)
@@ -1072,7 +1191,9 @@
    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
    file; there may be no way to implement an atomic rename when *dst* names an
-   existing file. Availability: Unix, Windows.
+   existing file.
+
+   Availability: Unix, Windows.
 
 
 .. function:: renames(old, new)
@@ -1092,8 +1213,9 @@
 
    Remove (delete) the directory *path*.  Only works when the directory is
    empty, otherwise, :exc:`OSError` is raised.  In order to remove whole
-   directory trees, :func:`shutil.rmtree` can be used.  Availability: Unix,
-   Windows.
+   directory trees, :func:`shutil.rmtree` can be used.
+
+   Availability: Unix, Windows.
 
 
 .. function:: stat(path)
@@ -1184,20 +1306,25 @@
    correspond to the members of the :ctype:`statvfs` structure, namely:
    :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
    :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
-   :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.
+   :attr:`f_flag`, :attr:`f_namemax`.
+
+   Availability: Unix.
 
 
 .. function:: symlink(source, link_name)
 
-   Create a symbolic link pointing to *source* named *link_name*. Availability:
-   Unix.
+   Create a symbolic link pointing to *source* named *link_name*.
+
+   Availability: Unix.
 
 
 .. function:: unlink(path)
 
    Remove (delete) the file *path*.  This is the same function as
    :func:`remove`; the :func:`unlink` name is its traditional Unix
-   name. Availability: Unix, Windows.
+   name.
+
+   Availability: Unix, Windows.
 
 
 .. function:: utime(path, times)
@@ -1321,6 +1448,7 @@
    behavior is to produce a core dump; on Windows, the process immediately returns
    an exit code of ``3``.  Be aware that programs which use :func:`signal.signal`
    to register a handler for :const:`SIGABRT` will behave differently.
+
    Availability: Unix, Windows.
 
 
@@ -1376,7 +1504,9 @@
 .. function:: _exit(n)
 
    Exit to the system with status *n*, without calling cleanup handlers, flushing
-   stdio buffers, etc. Availability: Unix, Windows.
+   stdio buffers, etc.
+
+   Availability: Unix, Windows.
 
    .. note::
 
@@ -1396,69 +1526,88 @@
 
 .. data:: EX_OK
 
-   Exit code that means no error occurred. Availability: Unix.
+   Exit code that means no error occurred.
+
+   Availability: Unix.
 
 
 .. data:: EX_USAGE
 
    Exit code that means the command was used incorrectly, such as when the wrong
-   number of arguments are given. Availability: Unix.
+   number of arguments are given.
+
+   Availability: Unix.
 
 
 .. data:: EX_DATAERR
 
-   Exit code that means the input data was incorrect. Availability: Unix.
+   Exit code that means the input data was incorrect.
+
+   Availability: Unix.
 
 
 .. data:: EX_NOINPUT
 
    Exit code that means an input file did not exist or was not readable.
+
    Availability: Unix.
 
 
 .. data:: EX_NOUSER
 
-   Exit code that means a specified user did not exist. Availability: Unix.
+   Exit code that means a specified user did not exist.
+
+   Availability: Unix.
 
 
 .. data:: EX_NOHOST
 
-   Exit code that means a specified host did not exist. Availability: Unix.
+   Exit code that means a specified host did not exist.
+
+   Availability: Unix.
 
 
 .. data:: EX_UNAVAILABLE
 
-   Exit code that means that a required service is unavailable. Availability:
-   Unix.
+   Exit code that means that a required service is unavailable.
+
+   Availability: Unix.
 
 
 .. data:: EX_SOFTWARE
 
-   Exit code that means an internal software error was detected. Availability:
-   Unix.
+   Exit code that means an internal software error was detected.
+
+   Availability: Unix.
 
 
 .. data:: EX_OSERR
 
    Exit code that means an operating system error was detected, such as the
-   inability to fork or create a pipe. Availability: Unix.
+   inability to fork or create a pipe.
+
+   Availability: Unix.
 
 
 .. data:: EX_OSFILE
 
    Exit code that means some system file did not exist, could not be opened, or had
-   some other kind of error. Availability: Unix.
+   some other kind of error.
+
+   Availability: Unix.
 
 
 .. data:: EX_CANTCREAT
 
    Exit code that means a user specified output file could not be created.
+
    Availability: Unix.
 
 
 .. data:: EX_IOERR
 
    Exit code that means that an error occurred while doing I/O on some file.
+
    Availability: Unix.
 
 
@@ -1466,31 +1615,39 @@
 
    Exit code that means a temporary failure occurred.  This indicates something
    that may not really be an error, such as a network connection that couldn't be
-   made during a retryable operation. Availability: Unix.
+   made during a retryable operation.
+
+   Availability: Unix.
 
 
 .. data:: EX_PROTOCOL
 
    Exit code that means that a protocol exchange was illegal, invalid, or not
-   understood. Availability: Unix.
+   understood.
+
+   Availability: Unix.
 
 
 .. data:: EX_NOPERM
 
    Exit code that means that there were insufficient permissions to perform the
-   operation (but not intended for file system problems). Availability: Unix.
+   operation (but not intended for file system problems).
+
+   Availability: Unix.
 
 
 .. data:: EX_CONFIG
 
    Exit code that means that some kind of configuration error occurred.
+
    Availability: Unix.
 
 
 .. data:: EX_NOTFOUND
 
-   Exit code that means something like "an entry was not found". Availability:
-   Unix.
+   Exit code that means something like "an entry was not found".
+
+   Availability: Unix.
 
 
 .. function:: fork()
@@ -1511,6 +1668,7 @@
    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.  If an error occurs :exc:`OSError` is raised.
+
    Availability: some flavors of Unix.
 
 
@@ -1540,19 +1698,24 @@
       single: process; killing
       single: process; signalling
 
-   Send the signal *sig* to the process group *pgid*. Availability: Unix.
+   Send the signal *sig* to the process group *pgid*.
+
+   Availability: Unix.
 
 
 .. function:: nice(increment)
 
    Add *increment* to the process's "niceness".  Return the new niceness.
+
    Availability: Unix.
 
 
 .. function:: plock(op)
 
    Lock program segments into memory.  The value of *op* (defined in
-   ``<sys/lock.h>``) determines which segments are locked. Availability: Unix.
+   ``<sys/lock.h>``) determines which segments are locked.
+
+   Availability: Unix.
 
 
 .. function:: popen(...)
@@ -1631,7 +1794,9 @@
    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
-   the return value. Availability: Unix, Windows.
+   the return value.
+
+   Availability: Unix, Windows.
 
 
 .. data:: P_WAIT
@@ -1640,7 +1805,9 @@
    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
-   process. Availability: Unix, Windows.
+   process.
+
+   Availability: Unix, Windows.
 
 
 .. data:: P_DETACH
@@ -1651,6 +1818,7 @@
    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.
+
    Availability: Windows.
 
 
@@ -1674,7 +1842,9 @@
    directory.  If you want to use an absolute path, make sure the first character
    is not a slash (``'/'``); the underlying Win32 :cfunc:`ShellExecute` function
    doesn't work if it is.  Use the :func:`os.path.normpath` function to ensure that
-   the path is properly encoded for Win32. Availability: Windows.
+   the path is properly encoded for Win32.
+
+   Availability: Windows.
 
 
 .. function:: system(command)
@@ -1696,22 +1866,24 @@
    the command run; on systems using a non-native shell, consult your shell
    documentation.
 
-   Availability: Unix, Windows.
-
    The :mod:`subprocess` module provides more powerful facilities for spawning new
    processes and retrieving their results; using that module is preferable to using
    this function.  Use the :mod:`subprocess` module.  Check especially the
    :ref:`subprocess-replacements` section.
 
+   Availability: Unix, Windows.
+
 
 .. function:: times()
 
-   Return a 5-tuple of floating point numbers indicating accumulated (processor or
-   other) times, in seconds.  The items are: user time, system time, children's
-   user time, children's system time, and elapsed real time since a fixed point in
-   the past, in that order.  See the Unix manual page :manpage:`times(2)` or the
-   corresponding Windows Platform API documentation. Availability: Unix,
-   Windows.  On Windows, only the first two items are filled, the others are zero.
+   Return a 5-tuple of floating point numbers indicating accumulated (processor
+   or other) times, in seconds.  The items are: user time, system time,
+   children's user time, children's system time, and elapsed real time since a
+   fixed point in the past, in that order.  See the Unix manual page
+   :manpage:`times(2)` or the corresponding Windows Platform API documentation.
+   On Windows, only the first two items are filled, the others are zero.
+
+   Availability: Unix, Windows
 
 
 .. function:: wait()
@@ -1720,7 +1892,9 @@
    and exit status indication: a 16-bit number, whose low byte is the signal number
    that killed the process, and whose high byte is the exit status (if the signal
    number is zero); the high bit of the low byte is set if a core file was
-   produced. Availability: Unix.
+   produced.
+
+   Availability: Unix.
 
 
 .. function:: waitpid(pid, options)
@@ -1758,6 +1932,7 @@
    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`.
+
    Availability: Unix.
 
 
@@ -1767,28 +1942,33 @@
    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`. Availability: Unix.
+   :func:`waitpid`.
+
+   Availability: Unix.
 
 
 .. data:: WNOHANG
 
    The option for :func:`waitpid` to return immediately if no child process status
    is available immediately. The function returns ``(0, 0)`` in this case.
+
    Availability: Unix.
 
 
 .. data:: WCONTINUED
 
    This option causes child processes to be reported if they have been continued
-   from a job control stop since their status was last reported. Availability: Some
-   Unix systems.
+   from a job control stop since their status was last reported.
+
+   Availability: Some Unix systems.
 
 
 .. data:: WUNTRACED
 
    This option causes child processes to be reported if they have been stopped but
-   their current state has not been reported since they were stopped. Availability:
-   Unix.
+   their current state has not been reported since they were stopped.
+
+   Availability: Unix.
 
 
 The following functions take a process status code as returned by
@@ -1798,48 +1978,63 @@
 .. function:: WCOREDUMP(status)
 
    Return ``True`` if a core dump was generated for the process, otherwise
-   return ``False``. Availability: Unix.
+   return ``False``.
+
+   Availability: Unix.
 
 
 .. function:: WIFCONTINUED(status)
 
    Return ``True`` if the process has been continued from a job control stop,
-   otherwise return ``False``. Availability: Unix.
+   otherwise return ``False``.
+
+   Availability: Unix.
 
 
 .. function:: WIFSTOPPED(status)
 
    Return ``True`` if the process has been stopped, otherwise return
-   ``False``. Availability: Unix.
+   ``False``.
+
+   Availability: Unix.
 
 
 .. function:: WIFSIGNALED(status)
 
    Return ``True`` if the process exited due to a signal, otherwise return
-   ``False``. Availability: Unix.
+   ``False``.
+
+   Availability: Unix.
 
 
 .. function:: WIFEXITED(status)
 
    Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
-   otherwise return ``False``. Availability: Unix.
+   otherwise return ``False``.
+
+   Availability: Unix.
 
 
 .. function:: WEXITSTATUS(status)
 
    If ``WIFEXITED(status)`` is true, return the integer parameter to the
    :manpage:`exit(2)` system call.  Otherwise, the return value is meaningless.
+
    Availability: Unix.
 
 
 .. function:: WSTOPSIG(status)
 
-   Return the signal which caused the process to stop. Availability: Unix.
+   Return the signal which caused the process to stop.
+
+   Availability: Unix.
 
 
 .. function:: WTERMSIG(status)
 
-   Return the signal which caused the process to exit. Availability: Unix.
+   Return the signal which caused the process to exit.
+
+   Availability: Unix.
 
 
 .. _os-path:
@@ -1856,8 +2051,7 @@
    Unix 95, Unix 98, and others).  Some platforms define additional names as well.
    The names known to the host operating system are given as the keys of the
    ``confstr_names`` dictionary.  For configuration variables not included in that
-   mapping, passing an integer for *name* is also accepted. Availability:
-   Unix.
+   mapping, passing an integer for *name* is also accepted.
 
    If the configuration value specified by *name* isn't defined, ``None`` is
    returned.
@@ -1867,19 +2061,25 @@
    included in ``confstr_names``, an :exc:`OSError` is raised with
    :const:`errno.EINVAL` for the error number.
 
+   Availability: Unix
+
 
 .. data:: confstr_names
 
    Dictionary mapping names accepted by :func:`confstr` to the integer values
    defined for those names by the host operating system. This can be used to
-   determine the set of names known to the system. Availability: Unix.
+   determine the set of names known to the system.
+
+   Availability: Unix.
 
 
 .. function:: getloadavg()
 
    Return the number of processes in the system run queue averaged over the last
    1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
-   unobtainable.  Availability: Unix.
+   unobtainable.
+
+   Availability: Unix.
 
 
 .. function:: sysconf(name)
@@ -1888,6 +2088,7 @@
    specified by *name* isn't defined, ``-1`` is returned.  The comments regarding
    the *name* parameter for :func:`confstr` apply here as well; the dictionary that
    provides information on the known names is given by ``sysconf_names``.
+
    Availability: Unix.
 
 
@@ -1895,7 +2096,9 @@
 
    Dictionary mapping names accepted by :func:`sysconf` to the integer values
    defined for those names by the host operating system. This can be used to
-   determine the set of names known to the system. Availability: Unix.
+   determine the set of names known to the system.
+
+   Availability: Unix.
 
 The following data values are used to support path manipulation operations.  These
 are defined for all platforms.


More information about the Python-checkins mailing list