[Python-checkins] python/dist/src/Doc/dist dist.tex, 1.42.2.2, 1.42.2.3

jhylton@users.sourceforge.net jhylton at users.sourceforge.net
Sun Oct 16 07:24:30 CEST 2005


Update of /cvsroot/python/python/dist/src/Doc/dist
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27718/Doc/dist

Modified Files:
      Tag: ast-branch
	dist.tex 
Log Message:
Merge head to branch (for the last time)


Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.42.2.2
retrieving revision 1.42.2.3
diff -u -d -r1.42.2.2 -r1.42.2.3
--- dist.tex	7 Jan 2005 06:56:53 -0000	1.42.2.2
+++ dist.tex	16 Oct 2005 05:23:57 -0000	1.42.2.3
@@ -25,6 +25,9 @@
 \begin{document}
 
 \maketitle
+
+\input{copyright}
+
 \begin{abstract}
   \noindent
   This document describes the Python Distribution Utilities
@@ -298,7 +301,7 @@
 current platform before actually using the pathname.  This makes your
 setup script portable across operating systems, which of course is one
 of the major goals of the Distutils.  In this spirit, all pathnames in
-this document are slash-separated.  (Mac OS programmers should keep in
+this document are slash-separated.  (Mac OS 9 programmers should keep in
 mind that the \emph{absence} of a leading slash indicates a relative
 path, the opposite of the Mac OS convention with colons.)
 
@@ -403,7 +406,7 @@
 with, etc.).
 
 All of this is done through another keyword argument to
-\function{setup()}, the \option{extensions} option.  \option{extensions}
+\function{setup()}, the \option{ext_modules} option.  \option{ext_modules}
 is just a list of \class{Extension} instances, each of which describes a
 single extension module.  Suppose your distribution includes a single
 extension, called \module{foo} and implemented by \file{foo.c}.  If no
@@ -631,7 +634,83 @@
 will automatically add \code{initmodule}
 to the list of exported symbols.
 
+\section{Relationships between Distributions and Packages}
+
+A distribution may relate to packages in three specific ways:
+
+\begin{enumerate}
+  \item It can require packages or modules.
+
+  \item It can provide packages or modules.
+
+  \item It can obsolete packages or modules.
+\end{enumerate}
+
+These relationships can be specified using keyword arguments to the
+\function{distutils.core.setup()} function.
+
+Dependencies on other Python modules and packages can be specified by
+supplying the \var{requires} keyword argument to \function{setup()}.
+The value must be a list of strings.  Each string specifies a package
+that is required, and optionally what versions are sufficient.
+
+To specify that any version of a module or package is required, the
+string should consist entirely of the module or package name.
+Examples include \code{'mymodule'} and \code{'xml.parsers.expat'}.
+
+If specific versions are required, a sequence of qualifiers can be
+supplied in parentheses.  Each qualifier may consist of a comparison
+operator and a version number.  The accepted comparison operators are:
+
+\begin{verbatim}
+<    >    ==
+<=   >=   !=
+\end{verbatim}
+
+These can be combined by using multiple qualifiers separated by commas
+(and optional whitespace).  In this case, all of the qualifiers must
+be matched; a logical AND is used to combine the evaluations.
+
+Let's look at a bunch of examples:
+
+\begin{tableii}{l|l}{code}{Requires Expression}{Explanation}
+  \lineii{==1.0}               {Only version \code{1.0} is compatible}
+  \lineii{>1.0, !=1.5.1, <2.0} {Any version after \code{1.0} and before
+                                \code{2.0} is compatible, except
+                                \code{1.5.1}}
+\end{tableii}
+
+Now that we can specify dependencies, we also need to be able to
+specify what we provide that other distributions can require.  This is
+done using the \var{provides} keyword argument to \function{setup()}.
+The value for this keyword is a list of strings, each of which names a
+Python module or package, and optionally identifies the version.  If
+the version is not specified, it is assumed to match that of the
+distribution.
+
+Some examples:
+
+\begin{tableii}{l|l}{code}{Provides Expression}{Explanation}
+  \lineii{mypkg}      {Provide \code{mypkg}, using the distribution version}
+  \lineii{mypkg (1.1} {Provide \code{mypkg} version 1.1, regardless of the
+                       distribution version}
+\end{tableii}
+
+A package can declare that it obsoletes other packages using the
+\var{obsoletes} keyword argument.  The value for this is similar to
+that of the \var{requires} keyword: a list of strings giving module or
+package specifiers.  Each specifier consists of a module or package
+name optionally followed by one or more version qualifiers.  Version
+qualifiers are given in parentheses after the module or package name.
+
+The versions identified by the qualifiers are those that are obsoleted
+by the distribution being described.  If no qualifiers are given, all
+versions of the named module or package are understood to be
+obsoleted.
+
+
 \section{Installing Scripts}
+
 So far we have been dealing with pure and non-pure Python modules,
 which are usually not run by themselves but imported by scripts.
 
@@ -1021,7 +1100,6 @@
 script or config file), \command{sdist} creates the archive of the
 default format for the current platform.  The default format is a gzip'ed
 tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
-\XXX{no Mac OS support here}
 
 You can specify as many formats as you like using the
 \longprogramopt{formats} option, for example:
@@ -1579,7 +1657,7 @@
                                   iconpath\optional{, iconindex}}}}}
   This function creates a shortcut.
   \var{target} is the path to the program to be started by the shortcut.
-  \var{description} is the description of the sortcut.
+  \var{description} is the description of the shortcut.
   \var{filename} is the title of the shortcut that the user will see.
   \var{arguments} specifies the command line arguments, if any.
   \var{workdir} is the working directory for the program.
@@ -1640,7 +1718,43 @@
 versions, the Hidden property should be set to yes. This must be edited
 through the web interface.
 
+\section{The .pypirc file}
+\label{pypirc}
+
+The format of the \file{.pypirc} file is formated as follows:
+
+\begin{verbatim}
+[server-login]
+repository: <repository-url>
+username: <username>
+password: <password>
+\end{verbatim}
+
+\var{repository} can be ommitted and defaults to
+\code{http://www.python.org/pypi}.
+
+\chapter{Uploading Packages to the Package Index}
+\label{package-upload}
+
+The Python Package Index (PyPI) not only stores the package info, but also 
+the package data if the author of the package wishes to. The distutils
+command \command{upload} pushes the distribution files to PyPI.
+
+The command is invoked immediately after building one or more distribution
+files.  For example, the command
 
+\begin{verbatim}
+python setup.py sdist bdist_wininst upload
+\end{verbatim}
+
+will cause the source distribution and the Windows installer to be
+uploaded to PyPI.  Note that these will be uploaded even if they are
+built using an earlier invocation of \file{setup.py}, but that only
+distributions named on the command line for the invocation including
+the \command{upload} command are uploaded.
+
+The \command{upload} command uses the username and password stored in
+the file \file{\$HOME/.pypirc}, see section~\ref{pypirc}.
 
 \chapter{Examples}
 \label{examples}
@@ -1980,6 +2094,14 @@
 implemented by the class \class{distcmds.bdist_openpkg.bdist_openpkg}
 or \class{buildcmds.bdist_openpkg.bdist_openpkg}.
 
+\section{Adding new distribution types}
+
+Commands that create distributions (files in the \file{dist/}
+directory) need to add \code{(\var{command}, \var{filename})} pairs to
+\code{self.distribution.dist_files} so that \command{upload} can
+upload it to PyPI.  The \var{filename} in the pair contains no path
+information, only the name of the file itself.  In dry-run mode, pairs
+should still be added to represent what would have been created.
 
 \chapter{Command Reference}
 \label{reference}
@@ -2059,9 +2181,9 @@
 characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},
 \code{a-f0-9\_.}).  The definition of ``regular filename character'' is
 platform-specific: on \UNIX{} it is anything except slash; on Windows
-anything except backslash or colon; on Mac OS anything except colon.
+anything except backslash or colon; on Mac OS 9 anything except colon.
 
-\XXX{Windows and Mac OS support not there yet}
+\XXX{Windows support not there yet}
 
 
 %\section{Creating a built distribution: the
@@ -2135,9 +2257,9 @@
 the contents of the config files or command-line.
 
 \var{script_name} is a file that will be run with \function{execfile()}
-\var{sys.argv[0]} will be replaced with \var{script} for the duration of the
+\code{sys.argv[0]} will be replaced with \var{script} for the duration of the
 call.  \var{script_args} is a list of strings; if supplied,
-\var{sys.argv[1:]} will be replaced by \var{script_args} for the duration 
+\code{sys.argv[1:]} will be replaced by \var{script_args} for the duration 
 of the call.
 
 \var{stop_after} tells \function{setup()} when to stop processing; possible 
@@ -2172,7 +2294,7 @@
 \begin{classdesc*}{Extension}
 
 The Extension class describes a single C or \Cpp extension module in a
-setup script. It accepts the following keyword arguments in it's
+setup script. It accepts the following keyword arguments in its
 constructor
 
 \begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
@@ -2232,7 +2354,7 @@
 \end{classdesc*}
 
 \begin{classdesc*}{Command}
-A \class{Command} class (or rather, an instance of one of it's subclasses)
+A \class{Command} class (or rather, an instance of one of its subclasses)
 implement a single distutils command.
 \end{classdesc*}
 
@@ -2258,22 +2380,24 @@
 \end{funcdesc}
     
 \begin{funcdesc}{gen_preprocess_options}{macros, include_dirs}
-Generate C pre-processor options (-D, -U, -I) as used by at least
+Generate C pre-processor options (\programopt{-D}, \programopt{-U},
+\programopt{-I}) as used by at least
 two types of compilers: the typical \UNIX{} compiler and Visual \Cpp.
-\var{macros} is the usual thing, a list of 1- or 2-tuples, where \var{(name,)}
-means undefine (-U) macro \var{name}, and \var{(name,value)} means define (-D)
-macro \var{name} to \var{value}.  \var{include_dirs} is just a list of directory
-names to be added to the header file search path (-I).  Returns a list
-of command-line options suitable for either \UNIX{} compilers or Visual
-\Cpp.
+\var{macros} is the usual thing, a list of 1- or 2-tuples, where
+\code{(\var{name},)} means undefine (\programopt{-U}) macro \var{name},
+and \code{(\var{name}, \var{value})} means define (\programopt{-D})
+macro \var{name} to \var{value}.  \var{include_dirs} is just a list of
+directory names to be added to the header file search path (\programopt{-I}).
+Returns a list of command-line options suitable for either \UNIX{} compilers
+or Visual \Cpp.
 \end{funcdesc}
 
 \begin{funcdesc}{get_default_compiler}{osname, platform}
 Determine the default compiler to use for the given platform.
     
-\var{osname} should be one of the standard Python OS names (i.e. the
-ones returned by \var{os.name}) and \var{platform} the common value
-returned by \var{sys.platform} for the platform in question.
+\var{osname} should be one of the standard Python OS names (i.e.\ the
+ones returned by \code{os.name}) and \var{platform} the common value
+returned by \code{sys.platform} for the platform in question.
     
 The default values are \code{os.name} and \code{sys.platform} in case the
 parameters are not given.
@@ -2319,7 +2443,7 @@
 (don't actually execute the steps) and \var{force} (rebuild
 everything, regardless of dependencies). All of these flags default to
 \code{0} (off). Note that you probably don't want to instantiate
-\class{CCompiler} or one of it's subclasses directly - use the
+\class{CCompiler} or one of its subclasses directly - use the
 \function{distutils.CCompiler.new_compiler()} factory function
 instead.
 
@@ -2505,7 +2629,8 @@
 \file{build/foo/bar.o}.
 
 \var{macros}, if given, must be a list of macro definitions.  A macro
-definition is either a \var{(name, value)} 2-tuple or a \var{(name,)} 1-tuple.
+definition is either a \code{(\var{name}, \var{value})} 2-tuple or a
+\code{(\var{name},)} 1-tuple.
 The former defines a macro; if the value is \code{None}, the macro is
 defined without an explicit value.  The 1-tuple case undefines a
 macro.  Later definitions/redefinitions/undefinitions take
@@ -2518,7 +2643,7 @@
 \var{debug} is a boolean; if true, the compiler will be instructed to
 output debug symbols in (or alongside) the object file(s).
 
-\var{extra_preargs} and \var{extra_postargs} are implementation- dependent.
+\var{extra_preargs} and \var{extra_postargs} are implementation-dependent.
 On platforms that have the notion of a command-line (e.g. \UNIX,
 DOS/Windows), they are most likely lists of strings: extra
 command-line arguments to prepend/append to the compiler command
@@ -2759,7 +2884,8 @@
 \modulesynopsis{Metrowerks CodeWarrior support}
 
 Contains \class{MWerksCompiler}, an implementation of the abstract 
-\class{CCompiler} class for MetroWerks CodeWarrior on the Macintosh. Needs work to support CW on Windows.
+\class{CCompiler} class for MetroWerks CodeWarrior on the pre-Mac OS X Macintosh.
+Needs work to support CW on Windows or Mac OS X.
 
 
 %\subsection{Utility modules}
@@ -2791,8 +2917,8 @@
 \end{funcdesc}
 
 \begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress=\code{'gzip'}, verbose=\code{0}, dry_run=\code{0}}}'Create an (optional compressed) archive as a tar file from all files in and under \var{base_dir}. \var{compress} must be \code{'gzip'} (the default), 
-\code{'compress'}, \code{'bzip2'}, or \code{None}.  Both \code{'tar'}
-and the compression utility named by \var{'compress'} must be on the 
+\code{'compress'}, \code{'bzip2'}, or \code{None}.  Both \program{tar}
+and the compression utility named by \var{compress} must be on the 
 default program search path, so this is probably \UNIX-specific.  The 
 output tar file will be named \file{\var{base_dir}.tar}, possibly plus
 the appropriate compression extension (\file{.gz}, \file{.bz2} or
@@ -2881,7 +3007,7 @@
 Copy an entire directory tree \var{src} to a new location \var{dst}.  Both
 \var{src} and \var{dst} must be directory names.  If \var{src} is not a
 directory, raise \exception{DistutilsFileError}.  If \var{dst} does 
-not exist, it is created with \var{mkpath()}.  The end result of the 
+not exist, it is created with \function{mkpath()}.  The end result of the 
 copy is that every file in \var{src} is copied to \var{dst}, and 
 directories under \var{src} are recursively copied to \var{dst}.  
 Return the list of files that were copied or might have been copied,
@@ -2901,7 +3027,7 @@
 
 \begin{funcdesc}{remove_tree}{directory\optional{verbose=\code{0}, dry_run=\code{0}}}
 Recursively remove \var{directory} and all files and directories underneath
-it. Any errors are ignored (apart from being reported to \code{stdout} if 
+it. Any errors are ignored (apart from being reported to \code{sys.stdout} if
 \var{verbose} is true).
 \end{funcdesc}
 
@@ -2929,7 +3055,7 @@
 to \code{'hard'} or \code{'sym'}; if it is \code{None} (the default),
 files are copied. Don't set \var{link} on systems that don't support
 it: \function{copy_file()} doesn't check if hard or symbolic linking is
-available.  It uses \var{_copy_file_contents()} to copy file contents.
+available.  It uses \function{_copy_file_contents()} to copy file contents.
 
 Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual 
 name of the output file, and \var{copied} is true if the file was copied 
@@ -2999,7 +3125,7 @@
 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.
+two, which is tricky on DOS/Windows.
 \end{funcdesc}
 
 \begin{funcdesc}{check_environ}{}
@@ -3197,7 +3323,7 @@
 The option_table is a list of 3-tuples: \samp{(long_option,
 short_option, help_string)}
 
-If an option takes an argument, it's \var{long_option} should have \code{'='}
+If an option takes an argument, its \var{long_option} should have \code{'='}
 appended; \var{short_option} should just be a single character, no \code{':'}
 in any case. \var{short_option} should be \code{None} if a \var{long_option} 
 doesn't have a corresponding \var{short_option}. All option tuples must have
@@ -3294,11 +3420,11 @@
 something that provides \method{readline()} and \method{close()} 
 methods).  It is recommended that you supply at least \var{filename}, 
 so that \class{TextFile} can include it in warning messages.  If 
-\var{file} is not supplied, TextFile creates its own using the 
-\var{open()} builtin.
+\var{file} is not supplied, \class{TextFile} creates its own using the 
+\function{open()} built-in function.
 
 The options are all boolean, and affect the values returned by
-\var{readline()}
+\method{readline()}
 
 \begin{tableiii}{c|l|l}{option name}{option name}{description}{default}
 \lineiii{strip_comments}{



More information about the Python-checkins mailing list