[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.4,1.5
anthonybaxter@users.sourceforge.net
anthonybaxter@users.sourceforge.net
Sun, 18 May 2003 20:12:29 -0700
Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv31619
Modified Files:
distref.tex
Log Message:
this morning's tramride worth of typing. distutils.util doc, more stuff
in the section on 'setup()' (including seepep entries for relevant PEPs).
Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** distref.tex 13 May 2003 11:36:39 -0000 1.4
--- distref.tex 19 May 2003 03:12:27 -0000 1.5
***************
*** 41,44 ****
--- 41,57 ----
You do not need to be a Python programmer to read this
manual.}
+
+ \seepep{241}{Metadata for Python Software Packages v1.0}{A proposal to
+ extract metadata from setup.py files. Contains descriptions
+ and examples for many of the descriptive metadata fields.}
+
+ \seepep{314}{Metadata for Python Software Packages v1.1}{An update to
+ the metadata PEP}
+
+ \seepep{301}{Package Index and Metadata for Distutils}{Describes the
+ \code{register} command for distutils, as well as the
+ trove metadata used in the \var{classifiers} argument to
+ \function{setup}.}
+
\end{seealso}
***************
*** 81,91 ****
instances of \class{distutils.core.Extension}}
\lineiii{classifiers}{A list of Trove categories for the package}{XXX link to better definition}
! \lineiii{distclass}{}{}
! \lineiii{script_name}{}{}
! \lineiii{script_args}{}{}
! \lineiii{options}{}{}
\lineiii{license}{The license for the package}{}
! \lineiii{keywords}{}{}
\lineiii{platforms}{}{}
\end{tableiii}
--- 94,106 ----
instances of \class{distutils.core.Extension}}
\lineiii{classifiers}{A list of Trove categories for the package}{XXX link to better definition}
! \lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}}
! % What on earth is the use case for script_name?
! \lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string}
! \lineiii{script_args}{Arguments to supply to the setup script}{a list of strings}
! \lineiii{options}{default options for the setup script}{a string}
\lineiii{license}{The license for the package}{}
! \lineiii{keywords}{Descriptive meta-data. See \pep{314}}{}
\lineiii{platforms}{}{}
+ \lineiii{cmdclass}{A mapping of command names to \class{Command} subclasses}{a dictionary}
\end{tableiii}
***************
*** 150,154 ****
\lineiii{define_macros}{list of macros to define; each macro is defined
using a 2-tuple, where 'value' is either the string to define it to or
! None to define it without a particular value (equivalent of "\#define
FOO" in source or -DFOO on Unix C compiler command line) }{ (string,string)
tuple or (name,\code{None}) }
--- 165,169 ----
\lineiii{define_macros}{list of macros to define; each macro is defined
using a 2-tuple, where 'value' is either the string to define it to or
! \code{None} to define it without a particular value (equivalent of "\#define
FOO" in source or -DFOO on Unix C compiler command line) }{ (string,string)
tuple or (name,\code{None}) }
***************
*** 866,869 ****
--- 881,1032 ----
any other utility module.
+ \begin{funcdesc}{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:
+ \begin{itemize}
+ \item \code{linux-i586}
+ \item \code{linux-alpha}
+ \item \code{solaris-2.6-sun4u}
+ \item \code{irix-5.3}
+ \item \code{irix64-6.2}
+ \end{itemize}
+
+ For non-\POSIX platforms, currently just returns \code{sys.platform}.
+ % XXX isn't this also provided by some other non-distutils module?
+ \end{funcdesc}
+
+ \begin{funcdesc}{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
+ \exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either
+ starts or ends with a slash.
+ \end{funcdesc}
+
+ \begin{funcdesc}{change_root}{new_root, pathname}
+ Return \var{pathname} with \var{new_root} prepended. If \var{pathname} is
+ relative, this is equivalent to \samp{os.path.join(new_root,pathname)}
+ Otherwise, it requires making \var{pathname} relative and then joining the
+ two, which is tricky on DOS/Windows and Mac OS.
+ \end{funcdesc}
+
+ \begin{funcdesc}{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:
+ \begin{itemize}
+ \item \code{HOME} - user's home directory (\UNIX only)
+ \item \code{PLAT} - description of the current platform, including hardware and OS (see \function{get_platform()})
+ \end{itemize}
+ \end{funcdesc}
+
+ \begin{funcdesc}{subst_vars}{s, local_vars}
+ Perform shell/Perl-style variable substitution on \var{s}. Every
+ occurrence of \code{$} followed by a name is considered a variable, and
+ variable is substituted by the value found in the \var{local_vars}
+ dictionary, or in \code{os.environ} if it's not in \var{local_vars}.
+ \var{os.environ} is first checked/augmented to guarantee that it contains
+ certain values: see \function{check_environ()}. Raise \exception{ValueError}
+ for any variables not found in either \var{local_vars} or \code{os.environ}.
+
+ Note that this is not a fully-fledged string interpolation function. A
+ valid \code{$variable} can consist only of upper and lower case letters,
+ numbers and an underscore. No \{ \} or \( \) style quoting is available.
+ \end{funcdesc}
+
+ \begin{funcdesc}{grok_environment_error}{exc\optional{, prefix=\samp{"error: "}}}
+ Generate a useful error message from an \exception{EnvironmentError}
+ (\exception{IOError} or \exception{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 \function{rename()} or
+ \function{link()}). Returns the error message as a string prefixed
+ with \var{prefix}.
+ \end{funcdesc}
+
+ \begin{funcdesc}{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.
+ % Should probably be moved into the standard library.
+ \end{funcdesc}
+
+ \begin{funcdesc}{execute}{func, args\optional{, msg=\code{None}, verbose=\code{0}, dry_run=\code{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 \var{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.
+ \end{funcdesc}
+
+ \begin{funcdesc}{strtobool}{val}
+ Convert a string representation of truth to true (1) or false (0).
+
+ True values are \code{y}, \code{yes}, \code{t}, \code{true}, \code{on}
+ and \code{1}; false values are \code{n}, \code{no}, \code{f}, \code{false},
+ \code{off} and \code{0}. Raises \exception{ValueError} if \var{val}
+ is anything else.
+ \end{funcdesc}
+
+ \begin{funcdesc}{byte_compile}{py_files\optional{,
+ optimize=\code{0}, force=\code{0},
+ prefix=\code{None}, base_dir=\code{None},
+ verbose=\code{1}, dry_run=\code{0},
+ direct=\code{None}}}
+ Byte-compile a collection of Python source files to either \file{.pyc}
+ or \file{.pyo} files in the same directory. \var{py_files} is a list of files
+ to compile; any files that don't end in \file{.py} are silently skipped.
+ \var{optimize} must be one of the following:
+ \begin{itemize}
+ \item \code{0} - don't optimize (generate \file{.pyc})
+ \item \code{1} - normal optimization (like \samp{python -O})
+ \item \code{2} - extra optimization (like \samp{python -OO})
+ \end{itemize}
+
+ If \var{force} is true, all files are recompiled regardless of
+ timestamps.
+
+ The source filename encoded in each bytecode file defaults to the
+ filenames listed in \var{py_files}; you can modify these with \var{prefix} and
+ \var{basedir}. \var{prefix} is a string that will be stripped off of each
+ source filename, and \var{base_dir} is a directory name that will be
+ prepended (after \var{prefix} is stripped). You can supply either or both
+ (or neither) of \var{prefix} and \var{base_dir}, as you wish.
+
+ If \var{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 \module{py_compile} module, or indirectly by writing a
+ temporary script and executing it. Normally, you should let
+ \function{byte_compile()} figure out to use direct compilation or not (see
+ the source for details). The \var{direct} flag is used by the script
+ generated in indirect mode; unless you know what you're doing, leave
+ it set to \code{None}.
+ \end{funcdesc}
+
+ \begin{funcdesc}{rfc822_escape}{header}
+ Return a version of \var{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.
+ % this _can_ be replaced
+ \end{funcdesc}
\subsection{Distutils objects}