[Python-checkins] python/dist/src/Doc/dist dist.tex,1.42,1.42.2.1

[jhylton@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/dist
In directory sc8-pr-cvs1:/tmp/cvs-serv27228/Doc/dist

Modified Files:
      Tag: ast-branch
	dist.tex 
Log Message:
Merge head to this branch.

Merge all sorts of changes from just before 2.3b1 into the ast
branch.  This should make the eventual merge back to the trunk easier.

The merge is almost entirely porting changes into the ast-branch.
There was no attempt to get changes to compile.c into newcompile.c.
That work should be done when newcompile.c is closer to completion.

The only significant conflicts appeared to be in pythonrun.c.


Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.42
retrieving revision 1.42.2.1
diff -C2 -d -r1.42 -r1.42.2.1
*** dist.tex	29 May 2002 17:33:48 -0000	1.42
--- dist.tex	28 Apr 2003 17:38:09 -0000	1.42.2.1
***************
*** 12,16 ****
  
  \author{Greg Ward}
! \authoraddress{Email: \email{gward@python.net}}
  
  \makeindex
--- 12,16 ----
  
  \author{Greg Ward}
! \authoraddress{Email: \email{distutils-sig@python.org}}
  
  \makeindex
***************
*** 283,287 ****
  a couple of dozen modules split into (so far) two packages; an explicit
  list of every module would be tedious to generate and difficult to
! maintain.
  
  Note that any pathnames (files or directories) supplied in the setup
--- 283,288 ----
  a couple of dozen modules split into (so far) two packages; an explicit
  list of every module would be tedious to generate and difficult to
! maintain.  For more information on the additional meta-data, see
! section~\ref{meta-data}.
  
  Note that any pathnames (files or directories) supplied in the setup
***************
*** 297,302 ****
  
  This, of course, only applies to pathnames given to Distutils
! functions.  If you, for example, use standard python functions such as
! \function{glob.glob} or \function{os.listdir} to specify files, you
  should be careful to write portable code instead of hardcoding path
  separators:
--- 298,303 ----
  
  This, of course, only applies to pathnames given to Distutils
! functions.  If you, for example, use standard Python functions such as
! \function{glob.glob()} or \function{os.listdir()} to specify files, you
  should be careful to write portable code instead of hardcoding path
  separators:
***************
*** 681,684 ****
--- 682,756 ----
  string should be given as the directory.
  
+ \subsection{Additional meta-data}
+ \label{meta-data}
+ 
+ The setup script may include additional meta-data beyond the name and
+ version. This information includes:
+ 
+ \begin{tableiii}{l|l|c}{code}%
+   {Meta-Data}{Description}{Notes}
+   \lineiii{name}{the name of the package}{(1)}
+   \lineiii{version}{the version of this release}{(1)}
+   \lineiii{author}{package author's name}{(2)}
+   \lineiii{author_email}{email address of the package author}{(2)}
+   \lineiii{maintainer}{package maintainer's name}{(2)}
+   \lineiii{maintainer_email}{email address of the package maintainer}{(2)}
+   \lineiii{url}{URL of the package's home page}{(1)}
+   \lineiii{license}{the terms the package is released under}{}
+   \lineiii{description}{a short, summary description of the package}{}
+   \lineiii{long_description}{a longer description of the package}{}
+   \lineiii{keywords}{some keywords appropriate to the package}{}
+   \lineiii{platforms}{a list of the target platforms}{}
+   \lineiii{classifiers}{a list of Trove classifiers}{(3),(4)}
+   \lineiii{download_url}{a single URL containing the download location 
+            for this version of the package}{(3)}
+ \end{tableiii}
+ 
+ \noindent Notes:
+ \begin{description}
+ \item[(1)] these fields are required
+ \item[(2)] either the author or the maintainer must be nominated
+ \item[(3)] should not be used if your package is to be compatible with
+   Python versions prior to 2.2.3 or 2.3.  
+ \item[(4)] The list of classifiers is available from the
+   PyPI website (\url{http://www.python.org/pypi}).
+   \option{classifiers} are specified as a list of strings:
+ 
+ \begin{verbatim}
+ setup(...
+       classifiers=[
+           'Development Status :: 4 - Beta',
+           'Environment :: Console',
+           'Environment :: Web Environment',
+           'Intended Audience :: End Users/Desktop',
+           'Intended Audience :: Developers',
+           'Intended Audience :: System Administrators',
+           'License :: OSI Approved :: Python Software Foundation License',
+           'Operating System :: MacOS :: MacOS X',
+           'Operating System :: Microsoft :: Windows',
+           'Operating System :: POSIX',
+           'Programming Language :: Python',
+           'Topic :: Communications :: Email',
+           'Topic :: Office/Business',
+           'Topic :: Software Development :: Bug Tracking',
+           ],
+       ...
+       )
+ \end{verbatim}
+ \end{description}
+ 
+ If you wish to include classifiers or a download URL in your
+ \file{setup.py} file and also wish to remain backwards-compatible with
+ Python releases prior to 2.2.3, then you can include the following
+ code fragment in your \file{setup.py} before the \code{setup()} call:
+ 
+ \begin{verbatim}
+ # patch distutils if it can't cope with the "classifiers" keyword
+ if sys.version < '2.2.3':
+     from distutils.dist import DistributionMetadata
+     DistributionMetadata.classifiers = None
+     DistributionMetadata.download_url = None
+ \end{verbatim}
+ 
  
  \section{Writing the Setup Configuration File}
***************
*** 1266,1277 ****
  \label{creating-wininst}
  
! Executable installers are the natural format for binary
! distributions on Windows.  They display a nice graphical user interface,
! display some information about the module distribution to be installed taken
  from the metadata in the setup script, let the user select a few
! (currently maybe too few) options, and start or cancel the installation.
  
! Since the metadata is taken from the setup script, creating
! Windows installers is usually as easy as running:
  
  \begin{verbatim}
--- 1338,1349 ----
  \label{creating-wininst}
  
! Executable installers are the natural format for binary distributions
! on Windows.  They display a nice graphical user interface, display
! some information about the module distribution to be installed taken
  from the metadata in the setup script, let the user select a few
! options, and start or cancel the installation.
  
! Since the metadata is taken from the setup script, creating Windows
! installers is usually as easy as running:
  
  \begin{verbatim}
***************
*** 1279,1283 ****
  \end{verbatim}
  
! or the \command{bdist} command with the \longprogramopt{format} option:
  
  \begin{verbatim}
--- 1351,1355 ----
  \end{verbatim}
  
! or the \command{bdist} command with the \longprogramopt{formats} option:
  
  \begin{verbatim}
***************
*** 1285,1309 ****
  \end{verbatim}
  
! If you have a pure module distribution (only containing pure
! Python modules and packages), the resulting installer will be
! version independent and have a name like \file{foo-1.0.win32.exe}.
! These installers can even be created on \UNIX{} or MacOS platforms.
  
  If you have a non-pure distribution, the extensions can only be
  created on a Windows platform, and will be Python version dependent.
  The installer filename will reflect this and now has the form
! \file{foo-1.0.win32-py2.0.exe}. You have to create a separate installer
  for every Python version you want to support.
  
  The installer will try to compile pure modules into bytecode after
! installation on the target system in normal and optimizing mode.
! If you don't want this to happen for some reason, you can run
! the bdist_wininst command with the \longprogramopt{no-target-compile} and/or
! the \longprogramopt{no-target-optimize} option.
  
! \section{Examples}
! \label{examples}
  
  
  \subsection{Pure Python distribution (by module)}
  \label{pure-mod}
--- 1357,1526 ----
  \end{verbatim}
  
! If you have a pure module distribution (only containing pure Python
! modules and packages), the resulting installer will be version
! independent and have a name like \file{foo-1.0.win32.exe}.  These
! installers can even be created on \UNIX{} or MacOS platforms.
  
  If you have a non-pure distribution, the extensions can only be
  created on a Windows platform, and will be Python version dependent.
  The installer filename will reflect this and now has the form
! \file{foo-1.0.win32-py2.0.exe}.  You have to create a separate installer
  for every Python version you want to support.
  
  The installer will try to compile pure modules into bytecode after
! installation on the target system in normal and optimizing mode.  If
! you don't want this to happen for some reason, you can run the
! \command{bdist_wininst} command with the
! \longprogramopt{no-target-compile} and/or the
! \longprogramopt{no-target-optimize} option.
  
! By default the installer will display the cool ``Python Powered'' logo
! when it is run, but you can also supply your own bitmap which must be
! a Windows \file{.bmp} file with the \longprogramopt{bitmap} option.
! 
! The installer will also display a large title on the desktop
! background window when it is run, which is constructed from the name
! of your distribution and the version number.  This can be changed to
! another text by using the \longprogramopt{title} option.
  
+ The installer file will be written to the ``distribution directory''
+ --- normally \file{dist/}, but customizable with the
+ \longprogramopt{dist-dir} option.
+ 
+ \subsubsection{The Postinstallation script}
+ \label{postinstallation-script}
  
+ Starting with Python 2.3, a postinstallation script can be specified
+ which the \longprogramopt{install-script} option.  The basename of the
+ script must be specified, and the script filename must also be listed
+ in the scripts argument to the setup function.
+ 
+ This script will be run at installation time on the target system
+ after all the files have been copied, with argv[1] set to '-install',
+ and again at uninstallation time before the files are removed with argv[1]
+ set to '-remove'.
+ 
+ The installation script runs embedded in the windows installer, every
+ output (sys.stdout, sys.stderr) is redirected into a buffer and will
+ be displayed in the GUI after the script has finished.
+ 
+ Some functions especially useful in this context are available in the
+ installation script.
+ 
+ \begin{verbatim}
+ dir_created(pathname)
+ file_created(pathname)
+ \end{verbatim}
+ 
+ These functions should be called when a directory or file is created
+ by the postinstall script at installation time.  It will register the
+ pathname with the uninstaller, so that it will be removed when the
+ distribution is uninstalled.  To be safe, directories are only removed
+ if they are empty.
+ 
+ \begin{verbatim}
+ get_special_folder_path(csidl_string)
+ \end{verbatim}
+ 
+ This function can be used to retrieve special folder locations on
+ Windows like the Start Menu or the Desktop.  It returns the full path
+ to the folder.  'csidl_string' must be on of the following strings:
+ 
+ \begin{verbatim}
+ "CSIDL_APPDATA"
+ 
+ "CSIDL_COMMON_STARTMENU"
+ "CSIDL_STARTMENU"
+ 
+ "CSIDL_COMMON_DESKTOPDIRECTORY"
+ "CSIDL_DESKTOPDIRECTORY"
+ 
+ "CSIDL_COMMON_STARTUP"
+ "CSIDL_STARTUP"
+ 
+ "CSIDL_COMMON_PROGRAMS"
+ "CSIDL_PROGRAMS"
+ 
+ "CSIDL_FONTS"
+ \end{verbatim}
+ 
+ If the folder cannot be retrieved, OSError is raised.
+ 
+ Which folders are available depends on the exact Windows version, and probably
+ also the configuration. For details refer to Microsoft's documentation of the
+ \code{SHGetSpecialFolderPath} function.
+ 
+ \begin{verbatim}
+ create_shortcut(target, description, filename[, arguments[,
+                 workdir[, iconpath[, iconindex]]]])
+ \end{verbatim}
+ 
+ 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{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.
+ \var{iconpath} is the file containing the icon for the shortcut,
+ and \var{iconindex} is the index of the icon in the file
+ \var{iconpath}.  Again, for details consult the Microsoft
+ documentation for the \code{IShellLink} interface.
+ 
+ \section{Registering with the Package Index}
+ \label{package-index}
+ 
+ The Python Package Index (PyPI) holds meta-data describing distributions
+ packaged with distutils. The distutils command \command{register} is
+ used to submit your distribution's meta-data to the index. It is invoked
+ as follows:
+ 
+ \begin{verbatim}
+ python setup.py register
+ \end{verbatim}
+ 
+ Distutils will respond with the following prompt:
+ 
+ \begin{verbatim}
+ running register
+ We need to know who you are, so please choose either:
+  1. use your existing login,
+  2. register as a new user,
+  3. have the server generate a new password for you (and email it to you), or
+  4. quit
+ Your selection [default 1]:
+ \end{verbatim}
+ 
+ \noindent Note: if your username and password are saved locally, you will
+ not see this menu.
+ 
+ If you have not registered with PyPI, then you will need to do so now. You
+ should choose option 2, and enter your details as required. Soon after
+ submitting your details, you will receive an email which will be used to
+ confirm your registration.
+ 
+ Once you are registered, you may choose option 1 from the menu. You will
+ be prompted for your PyPI username and password, and \command{register}
+ will then submit your meta-data to the index.
+ 
+ You may submit any number of versions of your distribution to the index. If
+ you alter the meta-data for a particular version, you may submit it again
+ and the index will be updated.
+ 
+ PyPI holds a record for each (name, version) combination submitted. The
+ first user to submit information for a given name is designated the Owner
+ of that name. They may submit changes through the \command{register}
+ command or through the web interface. They may also designate other users
+ as Owners or Maintainers. Maintainers may edit the package information, but
+ not designate other Owners or Maintainers.
+ 
+ By default PyPI will list all versions of a given package. To hide certain
+ versions, the Hidden property should be set to yes. This must be edited
+ through the web interface.
+ 
+ 
+ 
+ \section{Examples}
+ \label{examples}
+   
  \subsection{Pure Python distribution (by module)}
  \label{pure-mod}