10.13 `distutils.util` -- Miscellaneous other utility functions

This module contains other assorted bits and pieces that don't fit into any other utility module.

get_platform( )

Return a string that identifies the current platform. This is used mainly to distinguish platform-specific build directories and platform-specific built distributions. Typically includes the OS name and version and the architecture (as supplied by 'os.uname()'), although the exact information included depends on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only runs on SGI hardware), but for Linux the kernel version isn't particularly important.

Examples of returned values:

linux-i586
linux-alpha
solaris-2.6-sun4u
irix-5.3
irix64-6.2

For non-POSIX platforms, currently just returns sys.platform.

convert_path( pathname): Return 'pathname' as a name that will work on the native filesystem, i.e. split it on '/' and put it back together again using the current directory separator. Needed because filenames in the setup script are always supplied in Unix style, and have to be converted to the local convention before we can actually use them in the filesystem. Raises ValueError on non-Unix-ish systems if pathname either starts or ends with a slash.

change_root( new_root, pathname): Return pathname with new_root prepended. If pathname is relative, this is equivalent to "os.path.join(new_root,pathname)"Otherwise, it requires making pathname relative and then joining the two, which is tricky on DOS/Windows.

check_environ( )

Ensure that 'os.environ' has all the environment variables we guarantee that users can use in config files, command-line options, etc. Currently this includes:

HOME - user's home directory (Unix only)
PLAT - description of the current platform, including hardware and OS (see get_platform())

subst_vars( s, local_vars): Perform shell/Perl-style variable substitution on s. Every occurrence of $ followed by a name is considered a variable, and variable is substituted by the value found in the local_vars dictionary, or in os.environ if it's not in local_vars. os.environ is first checked/augmented to guarantee that it contains certain values: see check_environ(). Raise ValueError for any variables not found in either local_vars or os.environ.
Note that this is not a fully-fledged string interpolation function. A valid $variable can consist only of upper and lower case letters, numbers and an underscore. No { } or style quoting is available.

grok_environment_error( exc[, prefix=tex2html_deferred"'error: '"]): Generate a useful error message from an EnvironmentError (IOError or OSError) exception object. Handles Python 1.5.1 and later styles, and does what it can to deal with exception objects that don't have a filename (which happens when the error is due to a two-file operation, such as rename() or link()). Returns the error message as a string prefixed with prefix.

split_quoted( s): Split a string up according to Unix shell-like rules for quotes and backslashes. In short: words are delimited by spaces, as long as those spaces are not escaped by a backslash, or inside a quoted string. Single and double quotes are equivalent, and the quote characters can be backslash-escaped. The backslash is stripped from any two-character escape sequence, leaving only the escaped character. The quote characters are stripped from any quoted string. Returns a list of words.

execute( func, args[, msg=None, verbose=0, dry_run=0]): Perform some action that affects the outside world (for instance, writing to the filesystem). Such actions are special because they are disabled by the dry_run flag. This method takes care of all that bureaucracy for you; all you have to do is supply the function to call and an argument tuple for it (to embody the ``external action'' being performed), and an optional message to print.

strtobool( val): Convert a string representation of truth to true (1) or false (0).
True values are y, yes, t, true, on and 1; false values are n, no, f, false, off and 0. Raises ValueError if val is anything else.

byte_compile( py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

Byte-compile a collection of Python source files to either .pyc or .pyo files in the same directory. py_files is a list of files to compile; any files that don't end in .py are silently skipped. optimize must be one of the following:

0 - don't optimize (generate .pyc)
1 - normal optimization (like "python -O")
2 - extra optimization (like "python -OO")

If force is true, all files are recompiled regardless of timestamps.

The source filename encoded in each bytecode file defaults to the filenames listed in py_files; you can modify these with prefix and basedir. prefix is a string that will be stripped off of each source filename, and base_dir is a directory name that will be prepended (after prefix is stripped). You can supply either or both (or neither) of prefix and base_dir, as you wish.

If dry_run is true, doesn't actually do anything that would affect the filesystem.

Byte-compilation is either done directly in this interpreter process with the standard py_compile module, or indirectly by writing a temporary script and executing it. Normally, you should let byte_compile() figure out to use direct compilation or not (see the source for details). The direct flag is used by the script generated in indirect mode; unless you know what you're doing, leave it set to None.

rfc822_escape( header): Return a version of header escaped for inclusion in an RFC 822 header, by ensuring there are 8 spaces space after each newline. Note that it does no other modification of the string.

See About this document... for information on suggesting changes.

10.13 distutils.util -- Miscellaneous other utility functions

10.13 `distutils.util` -- Miscellaneous other utility functions