153 lines
6.1 KiB
TeX
153 lines
6.1 KiB
TeX
\section{\module{os} ---
|
|
Miscellaneous OS interfaces.}
|
|
\declaremodule{standard}{os}
|
|
|
|
\modulesynopsis{Miscellaneous OS interfaces.}
|
|
|
|
|
|
This module provides a more portable way of using operating system
|
|
(OS) dependent functionality than importing an OS dependent built-in
|
|
module like \module{posix}.
|
|
|
|
When the optional built-in module \module{posix} is available, this
|
|
module exports the same functions and data as \module{posix}; otherwise,
|
|
it searches for an OS dependent built-in module like \module{mac} and
|
|
exports the same functions and data as found there. The design of all
|
|
Python's built-in OS dependent modules is such that as long as the same
|
|
functionality is available, it uses the same interface; e.g., the
|
|
function \code{os.stat(\var{file})} returns stat info about \var{file}
|
|
in a format compatible with the \POSIX{} interface.
|
|
|
|
Extensions peculiar to a particular OS are also available through the
|
|
\module{os} module, but using them is of course a threat to
|
|
portability!
|
|
|
|
Note that after the first time \module{os} is imported, there is
|
|
\emph{no} performance penalty in using functions from \module{os}
|
|
instead of directly from the OS dependent built-in module, so there
|
|
should be \emph{no} reason not to use \module{os}!
|
|
|
|
In addition to whatever the correct OS dependent module exports, the
|
|
following variables and functions are always exported by \module{os}:
|
|
|
|
\begin{datadesc}{name}
|
|
The name of the OS dependent module imported. The following names
|
|
have currently been registered: \code{'posix'}, \code{'nt'},
|
|
\code{'dos'}, \code{'mac'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{path}
|
|
The corresponding OS dependent standard module for pathname
|
|
operations, e.g., \module{posixpath} or \module{macpath}. Thus, (given
|
|
the proper imports), \code{os.path.split(\var{file})} is equivalent to but
|
|
more portable than \code{posixpath.split(\var{file})}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{curdir}
|
|
The constant string used by the OS to refer to the current directory,
|
|
e.g.\ \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pardir}
|
|
The constant string used by the OS to refer to the parent directory,
|
|
e.g.\ \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{sep}
|
|
The character used by the OS to separate pathname components,
|
|
e.g.\ \character{/} for \POSIX{} or \character{:} for the Macintosh.
|
|
Note that knowing this is not sufficient to be able to parse or
|
|
concatenate pathnames --- use \function{os.path.split()} and
|
|
\function{os.path.join()} --- but it is occasionally useful.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{altsep}
|
|
An alternative character used by the OS to separate pathname components,
|
|
or \code{None} if only one separator character exists. This is set to
|
|
\character{/} on DOS/Windows systems where \code{sep} is a backslash.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pathsep}
|
|
The character conventionally used by the OS to separate search patch
|
|
components (as in \envvar{PATH}), e.g.\ \character{:} for \POSIX{} or
|
|
\character{;} for MS-DOS.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{linesep}
|
|
The string used to separate (or, rather, terminate) lines on the
|
|
current platform. This may be a single character, e.g. \code{'\e n'}
|
|
for \POSIX{} or \code{'\e r'} for MacOS, or multiple characters,
|
|
e.g. \code{'\e r\e n'} for MS-DOS.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{defpath}
|
|
The default search path used by \function{exec*p*()} if the environment
|
|
doesn't have a \code{'PATH'} key.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{makedirs}{path\optional{, mode}}
|
|
\versionadded{1.5.2}
|
|
Recursive directory creation function. Like \function{mkdir()},
|
|
but makes all intermediate-level directories needed to contain the
|
|
leaf directory. Throws an \exception{os.error} exception if the leaf
|
|
directory already exists or cannot be created. The default \var{mode}
|
|
is \code{0777} (octal).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{removedirs}{path}
|
|
\versionadded{1.5.2}
|
|
Recursive directory removal function. Works like
|
|
\function{rmdir()} except that, if the leaf directory is
|
|
successfully removed, directories corresponding to rightmost path
|
|
segments will be pruned way until either the whole path is consumed or
|
|
an error is raised (which is ignored, because it generally means that
|
|
a parent directory is not empty). Throws an \exception{os.error}
|
|
exception if the leaf directory could not be successfully removed.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{renames}{path}
|
|
\versionadded{1.5.2}
|
|
Recursive directory or file renaming function.
|
|
Works like \function{rename()}, except creation of any intermediate
|
|
directories needed to make the new pathname good is attempted first.
|
|
After the rename, directories corresponding to rightmost path segments
|
|
of the old name will be pruned away using \function{removedirs()}.
|
|
|
|
Note: this function can fail with the new directory structure made if
|
|
you lack permissions needed to remove the leaf directory or file.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execl}{path, arg0, arg1, ...}
|
|
This is equivalent to
|
|
\samp{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execle}{path, arg0, arg1, ..., env}
|
|
This is equivalent to
|
|
\samp{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execlp}{path, arg0, arg1, ...}
|
|
This is equivalent to
|
|
\samp{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execvp}{path, args}
|
|
This is like \samp{execv(\var{path}, \var{args})} but duplicates
|
|
the shell's actions in searching for an executable file in a list of
|
|
directories. The directory list is obtained from
|
|
\code{environ['PATH']}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execvpe}{path, args, env}
|
|
This is a cross between \function{execve()} and \function{execvp()}.
|
|
The directory list is obtained from \code{\var{env}['PATH']}.
|
|
\end{funcdesc}
|
|
|
|
(The functions \function{execv()} and \function{execve()} are not
|
|
documented here, since they are implemented by the OS dependent
|
|
module. If the OS dependent module doesn't define either of these,
|
|
the functions that rely on it will raise an exception. They are
|
|
documented in the section on module \module{posix}, together with all
|
|
other functions that \module{os} imports from the OS dependent module.)
|