Only in main/contrib/python-2.0/dist/src/Doc: .cvsignore diff -ru main/contrib/python-2.0/dist/src/Doc/ACKS main/Apps/ActivePython-2.0/src/Core/Doc/ACKS --- main/contrib/python-2.0/dist/src/Doc/ACKS Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/ACKS Mon Mar 12 16:10:18 2001 @@ -22,30 +22,25 @@ Daniel Barclay Chris Barker Don Bashford -Anthony Baxter Bennett Benson Jonathan Black Robin Boerdijk Michal Bozon Aaron Brancotti Keith Briggs -Lee Busby Lorenzo M. Catucci Mauro Cicognini -Gilles Civario Steve Clift Andrew Dalke Ben Darnell Robert Donohue Fred L. Drake, Jr. -Jeff Epler Michael Ernst Blame Andy Eskilsson Martijn Faassen Carl Feynman Hernan Martinez Foffani Stefan Franke -Jim Fulton Peter Funk Lele Gaifax Matthew Gallagher @@ -57,14 +52,10 @@ Mark Hammond Manus Hand Travis B. Hartwell -Janko Hauser Bernhard Herzog Magnus L. Hetland -Konrad Hinsen Stefan Hoffmeister Albert Hofkamp -Gregor Hoffleit -Steve Holden Gerrit Holl Rob Hooft Brian Hooper @@ -89,7 +80,7 @@ Detlef Lannert Piers Lauder Glyph Lefkowitz -Marc-André Lemburg +Marc-Andre Lemburg Ulf A. Lindgren Everett Lipman Mirko Liss @@ -101,38 +92,33 @@ Vladimir Marangozov Vincent Marchetti Aahz Maruch -Laura Matson -Daniel May Doug Mennella Paolo Milani Skip Montanaro Ross Moore Sjoerd Mullender Dale Nagata -Ng Pheng Siong Koray Oner Denis S. Otkidach William Park Tim Peters Christopher Petrilli Justin D. Pettit -Chris Phoenix François Pinard Paul Prescod Eric S. Raymond Edward K. Ream Sean Reifschneider Bernhard Reiter +Bernhard Reiter Wes Rishel Jim Roskind Guido van Rossum Donald Wallace Rouse II Nick Russo -Chris Ryland Constantina S. Hugh Sasse Bob Savage -Scott Schram Neil Schemenauer Barry Scott Joakim Sernbrant @@ -148,15 +134,12 @@ Greg Stein Peter Stoehr Mark Summerfield -Reuben Sumner -Jim Tittsler Martijn Vries Charles G. Waldman Greg Ward Barry Warsaw Corran Webster Glyn Webster -Bob Weiner Eddy Welbourne Gerry Wiener Timothy Wild diff -ru main/contrib/python-2.0/dist/src/Doc/Makefile main/Apps/ActivePython-2.0/src/Core/Doc/Makefile --- main/contrib/python-2.0/dist/src/Doc/Makefile Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/Makefile Mon Mar 12 16:10:18 2001 @@ -67,7 +67,7 @@ # This is the *documentation* release, and is used to construct the file # names of the downloadable tarballs. -RELEASE=2.1b1 +RELEASE=2.0 PYTHON= python DVIPS= dvips -N0 -t $(PAPER) diff -ru main/contrib/python-2.0/dist/src/Doc/Makefile.deps main/Apps/ActivePython-2.0/src/Core/Doc/Makefile.deps --- main/contrib/python-2.0/dist/src/Doc/Makefile.deps Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/Makefile.deps Mon Mar 12 16:10:18 2001 @@ -51,19 +51,14 @@ lib/libfuncs.tex \ lib/libpython.tex \ lib/libsys.tex \ - lib/libfpectl.tex \ lib/libgc.tex \ - lib/libweakref.tex \ lib/libinspect.tex \ - lib/libdifflib.tex \ - lib/libdoctest.tex \ lib/libtypes.tex \ lib/libtraceback.tex \ lib/libpickle.tex \ lib/libshelve.tex \ lib/libcopy.tex \ lib/libmarshal.tex \ - lib/libwarnings.tex \ lib/libimp.tex \ lib/libparser.tex \ lib/libbltin.tex \ @@ -194,7 +189,6 @@ lib/libuu.tex \ lib/libsunaudio.tex \ lib/libfileinput.tex \ - lib/libxreadlines.tex \ lib/libimaplib.tex \ lib/libpoplib.tex \ lib/libcalendar.tex \ diff -ru main/contrib/python-2.0/dist/src/Doc/README main/Apps/ActivePython-2.0/src/Core/Doc/README --- main/contrib/python-2.0/dist/src/Doc/README Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/README Mon Mar 12 16:10:18 2001 @@ -44,23 +44,17 @@ What if I find a bug? --------------------- -First, check that the bug is present in the development version of the -documentation at ; we may -have already fixed it. +First, check that the bug is present in the online version of the +documentation at ; we may have already +fixed it. If we haven't, tell us about it. We'd like the documentation to be complete and accurate, but have limited time. If you discover any inconsistencies between the documentation and implementation, or just have suggestions as to how to improve the documentation, let is know! -Specific bugs and patches should be reported using our bug & patch -databases at: +Send comments and patches to the Python Documentation Team: - http://sourceforge.net/projects/python - -Other suggestions or questions should be sent to the Python -Documentation Team: - - python-docs@python.org + python-docs@python.org Thanks! @@ -126,13 +120,6 @@ - Perl. Find the software at . - - HTML::Element. If you don't have this installed, you can get - this from CPAN. Use the command: - - perl -e 'use CPAN; CPAN::install("HTML::Element");' - - You may need to be root to do this. - To create HTML files: - Perl 5.004_04 or newer. Find the software at @@ -142,7 +129,8 @@ version changes enough that supporting multiple versions is not likely to work. Many older versions don't work with Perl 5.6 as well. This also screws up code fragments. ;-( - Releases are available at: . + Releases are available at: + . What if Times fonts are not available? @@ -162,9 +150,8 @@ ------------------------------- Instead of building the PostScript by giving the command "make", give -the command "make PAPER=a4 ps"; the output will be produced in the -paper-a4/ subdirectory. (You can use "make PAPER=a4 pdf" if you'd -rather have PDF output.) +the command "make PAPER=a4"; the output will be produced in the +paper-a4/ subdirectory. Making HTML files @@ -180,12 +167,13 @@ There is a new LaTeX document class called "howto". This is used for the new series of Python HOWTO documents which is being coordinated by -Andrew Kuchling . The file -templates/howto.tex is a commented example which may be used as a -template. A Python script to "do the right thing" to format a howto -document is included as tools/mkhowto. These documents can be -formatted as HTML, PDF, PostScript, or ASCII files. Use "mkhowto ---help" for information on using the formatting tool. +Andrew Kuchling . The file templates/howto.tex is a +commented example which may be used a template. A script to "do the +right thing" to format a howto document is included as +tools/mkhowto. These documents can be formatted as HTML, PDF, +PostScript, or ASCII files. Support for this document class is +still new, but is expected to evolve rapidly. Use "mkhowto --help" +for information on using the formatting tool. For authors of module documentation, there is a file templates/module.tex which may be used as a template for a module @@ -202,18 +190,16 @@ as long as you don't change or remove the copyright notice: ---------------------------------------------------------------------- -Copyright (c) 2000, 2001 Guido van Rossum. -All rights reserved. - -Copyright (c) 2000 BeOpen.com. -All rights reserved. +Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, +The Netherlands. -Copyright (c) 1995-2000 Corporation for National Research Initiatives. -All rights reserved. + All Rights Reserved -Copyright (c) 1991-1995 Stichting Mathematisch Centrum. +Copyright (c) 2000, BeOpen.com. +Copyright (c) 1995-2000, Corporation for National Research Initiatives. +Copyright (c) 1990-1995, Stichting Mathematisch Centrum. All rights reserved. -See the file "LICENSE" for information on usage and +See the file "Misc/COPYRIGHT" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. ---------------------------------------------------------------------- diff -ru main/contrib/python-2.0/dist/src/Doc/api/api.tex main/Apps/ActivePython-2.0/src/Core/Doc/api/api.tex --- main/contrib/python-2.0/dist/src/Doc/api/api.tex Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/api/api.tex Mon Mar 12 16:10:18 2001 @@ -456,7 +456,7 @@ item = dict[key] except KeyError: item = 0 - dict[key] = item + 1 + return item + 1 \end{verbatim} \ttindex{incr_item()} @@ -472,25 +472,21 @@ item = PyObject_GetItem(dict, key); if (item == NULL) { /* Handle KeyError only: */ - if (!PyErr_ExceptionMatches(PyExc_KeyError)) - goto error; + if (!PyErr_ExceptionMatches(PyExc_KeyError)) goto error; /* Clear the error and use zero: */ PyErr_Clear(); item = PyInt_FromLong(0L); - if (item == NULL) - goto error; + if (item == NULL) goto error; } + const_one = PyInt_FromLong(1L); - if (const_one == NULL) - goto error; + if (const_one == NULL) goto error; incremented_item = PyNumber_Add(item, const_one); - if (incremented_item == NULL) - goto error; + if (incremented_item == NULL) goto error; - if (PyObject_SetItem(dict, key, incremented_item) < 0) - goto error; + if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error; rv = 0; /* Success */ /* Continue with cleanup code */ @@ -888,7 +884,7 @@ const char *format, \moreargs} This function sets the error indicator. \var{exception} should be a Python exception (string or class, not an instance). -\var{format} should be a string, containing format codes, similar to +\var{fmt} should be a string, containing format codes, similar to \cfunction{printf}. The \code{width.precision} before a format code is parsed, but the width part is ignored. @@ -945,50 +941,6 @@ argument. It is mostly for internal use. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} -Issue a warning message. The \var{category} argument is a warning -category (see below) or \NULL; the \var{message} argument is a message -string. - -This function normally prints a warning message to \var{sys.stderr}; -however, it is also possible that the user has specified that warnings -are to be turned into errors, and in that case this will raise an -exception. It is also possible that the function raises an exception -because of a problem with the warning machinery (the implementation -imports the \module{warnings} module to do the heavy lifting). The -return value is \code{0} if no exception is raised, or \code{-1} if -an exception is raised. (It is not possible to determine whether a -warning message is actually printed, nor what the reason is for the -exception; this is intentional.) If an exception is raised, the -caller should do its normal exception handling -(e.g. \cfunction{Py_DECREF()} owned references and return an error -value). - -Warning categories must be subclasses of \cdata{Warning}; the default -warning category is \cdata{RuntimeWarning}. The standard Python -warning categories are available as global variables whose names are -\samp{PyExc_} followed by the Python exception name. These have the -type \ctype{PyObject*}; they are all class objects. Their names are -\cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, -\cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and -\cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of -\cdata{PyExc_Exception}; the other warning categories are subclasses -of \cdata{PyExc_Warning}. - -For information about warning control, see the documentation for the -\module{warnings} module and the \programopt{-W} option in the command -line documentation. There is no C API for warning control. -\end{cfuncdesc} - -\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, -char *filename, int lineno, char *module, PyObject *registry} -Issue a warning message with explicit control over all warning -attributes. This is a straightforward wrapper around the Python -function \function{warnings.warn_explicit()}, see there for more -information. The \var{module} and \var{registry} arguments may be -set to \code{NULL} to get the default effect described there. -\end{cfuncdesc} - \begin{cfuncdesc}{int}{PyErr_CheckSignals}{} This function interacts with Python's signal handling. It checks whether a signal has been sent to the processes and if so, invokes the @@ -1114,7 +1066,7 @@ \var{filename} is deemed interactive. This is the case for files for which \samp{isatty(fileno(\var{fp}))} is true. If the global flag \cdata{Py_InteractiveFlag} is true, this function also returns true if -the \var{filename} pointer is \NULL{} or if the name is equal to one of +the \var{name} pointer is \NULL{} or if the name is equal to one of the strings \code{''} or \code{'???'}. \end{cfuncdesc} @@ -1486,14 +1438,6 @@ \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o} -Compute a Unicode string representation of object \var{o}. Returns the -Unicode string representation on success, \NULL{} on failure. This is -the equivalent of the Python expression \samp{unistr(\var{o})}. -Called by the \function{unistr()}\bifuncindex{unistr} built-in function. -\end{cfuncdesc} - - \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} Determine if the object \var{o} is callable. Return \code{1} if the object is callable and \code{0} otherwise. @@ -1507,24 +1451,22 @@ arguments given by the tuple \var{args}. If no arguments are needed, then \var{args} may be \NULL{}. Returns the result of the call on success, or \NULL{} on failure. This is the equivalent -of the Python expression \samp{apply(\var{callable_object}, \var{args})}. +of the Python expression \samp{apply(\var{o}, \var{args})}. \bifuncindex{apply} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, - char *format, ...} +\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...} Call a callable Python object \var{callable_object}, with a variable number of C arguments. The C arguments are described using a \cfunction{Py_BuildValue()} style format string. The format may be \NULL{}, indicating that no arguments are provided. Returns the result of the call on success, or \NULL{} on failure. This is -the equivalent of the Python expression \samp{apply(\var{callable_object}, +the equivalent of the Python expression \samp{apply(\var{o}, \var{args})}.\bifuncindex{apply} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, - char *method, char *format, ...} +\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...} Call the method named \var{m} of object \var{o} with a variable number of C arguments. The C arguments are described by a \cfunction{Py_BuildValue()} format string. The format may be \NULL{}, @@ -1699,7 +1641,7 @@ \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and \NULL{} on failure. This is the equivalent of the Python expression -\samp{\var{o1} \&\ \var{o2}}. +\samp{\var{o1} \& \var{o2}}. \end{cfuncdesc} @@ -1757,7 +1699,7 @@ \NULL{} on failure. The operation is done \emph{in-place} when \var{o1} supports it. This is the equivalent of the Python expression \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an in-place variant of -\samp{pow(\var{o1}, \var{o2}, \var{o3})} otherwise. If \var{o3} is to be +\samp{pow(\var{o1}, \var{o2}, var{o3})} otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its place (passing \NULL{} for \var{o3} would cause an illegal memory access). \end{cfuncdesc} @@ -1779,10 +1721,10 @@ \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2} -Returns the ``bitwise and'' of \var{o1} and \var{o2} on success -and \NULL{} on failure. The operation is done \emph{in-place} when -\var{o1} supports it. This is the equivalent of the Python expression -\samp{\var{o1} \&= \var{o2}}. +Returns the ``bitwise and'' of \var{o2} and \var{o2} on success +and \NULL{} on failure. The operation is done \emph{in-place} when \var{o1} +supports it. This is the equivalent of the Python expression \samp{\var{o1} +\&= \var{o2}}. \end{cfuncdesc} @@ -1895,7 +1837,7 @@ \end{cfuncdesc} \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} -Delete the \var{i}th element of object \var{o}. Returns +Delete the \var{i}th element of object \var{v}. Returns \code{-1} on failure. This is the equivalent of the Python statement \samp{del \var{o}[\var{i}]}. \end{cfuncdesc} @@ -2055,17 +1997,10 @@ types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; -for example, to check that an object is a dictionary, use +for example. to check that an object is a dictionary, use \cfunction{PyDict_Check()}. The chapter is structured like the ``family tree'' of Python object types. -\strong{Warning:} -While the functions described in this chapter carefully check the type -of the objects which are passed in, many of them do not check for -\NULL{} being passed instead of a valid object. Allowing \NULL{} to -be passed in can cause memory access violations and immediate -termination of the interpreter. - \section{Fundamental Objects \label{fundamental}} @@ -2092,7 +2027,9 @@ \begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} Returns true if the type object \var{o} sets the feature -\var{feature}. Type features are denoted by single bit flags. +\var{feature}. Type features are denoted by single bit flags. The +only defined feature flag is \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER}, +described in section \ref{buffer-structs}. \end{cfuncdesc} @@ -2120,9 +2057,6 @@ \subsection{String Objects \label{stringObjects}} -These functions raise \exception{TypeError} when expecting a string -parameter and are called with a non-string parameter. - \obindex{string} \begin{ctypedesc}{PyStringObject} This subtype of \ctype{PyObject} represents a Python string object. @@ -2162,10 +2096,8 @@ \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} Returns a null-terminated representation of the contents of \var{string}. The pointer refers to the internal buffer of -\var{string}, not a copy. The data must not be modified in any way, -unless the string was just created using -\code{PyString_FromStringAndSize(NULL, \var{size})}. -It must not be deallocated. +\var{string}, not a copy. The data must not be modified in any way. +It must not be de-allocated. \end{cfuncdesc} \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} @@ -2186,9 +2118,8 @@ TypeError is raised. The buffer refers to an internal string buffer of \var{obj}, not a -copy. The data must not be modified in any way, unless the string was -just created using \code{PyString_FromStringAndSize(NULL, -\var{size})}. It must not be deallocated. +copy. The data must not be modified in any way. It must not be +de-allocated. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, @@ -3097,23 +3028,24 @@ Return a new tuple object of size \var{len}, or \NULL{} on failure. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} +\begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p} Takes a pointer to a tuple object, and returns the size of that tuple. \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos} +\begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyTupleObject *p, int pos} Returns the object at position \var{pos} in the tuple pointed to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and sets an \exception{IndexError} exception. \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos} +\begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos} Does the same, but does no checking of its arguments. \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, - int low, int high} +\begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p, + int low, + int high} Takes a slice of the tuple pointed to by \var{p} from \var{low} to \var{high} and returns it as a new tuple. \end{cfuncdesc} @@ -3132,7 +3064,7 @@ \strong{Note:} This function ``steals'' a reference to \var{o}. \end{cfuncdesc} -\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, +\begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p, int newsize, int last_is_sticky} Can be used to resize a tuple. \var{newsize} will be the new length of the tuple. Because tuples are \emph{supposed} to be immutable, @@ -3700,36 +3632,6 @@ \end{cfuncdesc} -\subsection{Instance Objects \label{instanceObjects}} - -\obindex{instance} -There are very few functions specific to instance objects. - -\begin{cvardesc}{PyTypeObject}{PyInstance_Type} - Type object for class instances. -\end{cvardesc} - -\begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} - Returns true if \var{obj} is an instance. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, - PyObject *arg, - PyObject *kw} - Create a new instance of a specific class. The parameters \var{arg} - and \var{kw} are used as the positional and keyword parameters to - the object's constructor. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, - PyObject *dict} - Create a new instance of a specific class without calling it's - constructor. \var{class} is the class of new object. The - \var{dict} parameter will be used as the object's \member{__dict__}; - if \NULL, a new dictionary will be created for the instance. -\end{cfuncdesc} - - \subsection{Module Objects \label{moduleObjects}} \obindex{module} @@ -4735,43 +4637,15 @@ \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name, - PyMethodDef *methods} - Create a new module object based on a name and table of functions, - returning the new module object. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name, - PyMethodDef *methods, - char *doc} - Create a new module object based on a name and table of functions, - returning the new module object. If \var{doc} is non-\NULL, it will - be used to define the docstring for the module. -\end{cfuncdesc} - -\begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name, - PyMethodDef *methods, - char *doc, PyObject *self, - int apiver} - Create a new module object based on a name and table of functions, - returning the new module object. If \var{doc} is non-\NULL, it will - be used to define the docstring for the module. If \var{self} is - non-\NULL, it will passed to the functions of the module as their - (otherwise \NULL) first parameter. (This was added as an - experimental feature, and there are no known uses in the current - version of Python.) For \var{apiver}, the only value which should - be passed is defined by the constant \constant{PYTHON_API_VERSION}. - - \strong{Note:} Most uses of this function should probably be using - the \cfunction{Py_InitModule3()} instead; only use this if you are - sure you need it. -\end{cfuncdesc} +Py_InitModule (!!!) PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse Py_BuildValue DL_IMPORT + +Py*_Check _Py_NoneStruct diff -ru main/contrib/python-2.0/dist/src/Doc/api/refcounts.dat main/Apps/ActivePython-2.0/src/Core/Doc/api/refcounts.dat --- main/contrib/python-2.0/dist/src/Doc/api/refcounts.dat Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/api/refcounts.dat Mon Mar 12 16:10:18 2001 @@ -21,13 +21,6 @@ # always return NULL. This is used by some of the PyErr_*() functions, in # particular. -# XXX NOTE: the 0/+1/-1 refcount information for arguments is -# confusing! Much more useful would be to indicate whether the -# function "steals" a reference to the argument or not. Take for -# example PyList_SetItem(list, i, item). This lists as a 0 change for -# both the list and the item arguments. However, in fact it steals a -# reference to the item argument! - # The parameter names are as they appear in the API manual, not the source # code. @@ -93,29 +86,29 @@ PyDict_Check:PyObject*:p:0: PyDict_Clear:void::: -PyDict_Clear:PyObject*:p:0: +PyDict_Clear:PyDictObject*:p:0: PyDict_DelItem:int::: -PyDict_DelItem:PyObject*:p:0: +PyDict_DelItem:PyDictObject*:p:0: PyDict_DelItem:PyObject*:key:0: PyDict_DelItemString:int::: -PyDict_DelItemString:PyObject*:p:0: +PyDict_DelItemString:PyDictObject*:p:0: PyDict_DelItemString:char*:key:: PyDict_GetItem:PyObject*::0:0 -PyDict_GetItem:PyObject*:p:0: +PyDict_GetItem:PyDictObject*:p:0: PyDict_GetItem:PyObject*:key:0: PyDict_GetItemString:PyObject*::0: -PyDict_GetItemString:PyObject*:p:0: +PyDict_GetItemString:PyDictObject*:p:0: PyDict_GetItemString:char*:key:: PyDict_Items:PyObject*::+1: -PyDict_Items:PyObject*:p:0: +PyDict_Items:PyDictObject*:p:0: PyDict_Keys:PyObject*::+1: -PyDict_Keys:PyObject*:p:0: +PyDict_Keys:PyDictObject*:p:0: PyDict_New:PyObject*::+1: @@ -123,26 +116,26 @@ PyDict_Copy:PyObject*:p:0: PyDict_Next:int::: -PyDict_Next:PyObject*:p:0: +PyDict_Next:PyDictObject*:p:0: PyDict_Next:int:ppos:: PyDict_Next:PyObject**:pkey:0: PyDict_Next:PyObject**:pvalue:0: PyDict_SetItem:int::: -PyDict_SetItem:PyObject*:p:0: +PyDict_SetItem:PyDictObject*:p:0: PyDict_SetItem:PyObject*:key:+1: PyDict_SetItem:PyObject*:val:+1: PyDict_SetItemString:int::: -PyDict_SetItemString:PyObject*:p:0: +PyDict_SetItemString:PyDictObject*:p:0: PyDict_SetItemString:char*:key:: PyDict_SetItemString:PyObject*:val:+1: PyDict_Size:int::: -PyDict_Size:PyObject*:p:: +PyDict_Size:PyDictObject*:p:: PyDict_Values:PyObject*::+1: -PyDict_Values:PyObject*:p:0: +PyDict_Values:PyDictObject*:p:0: PyErr_BadArgument:int::: @@ -206,10 +199,6 @@ PyErr_Format:char*:format:: PyErr_Format::...:: -PyErr_Warn:int::: -PyErr_Warn:PyObject*:category:0: -PyErr_Warn:char*:message:: - PyEval_AcquireLock:void::: PyEval_AcquireThread:void::: @@ -285,22 +274,6 @@ PyFloat_FromDouble:PyObject*::+1: PyFloat_FromDouble:double:v:: -Py_InitModule:PyObject*::0: -Py_InitModule:name:char*:: -Py_InitModule:methods:PyMethodDef[]:: - -Py_InitModule3:PyObject*::0: -Py_InitModule3:name:char*:: -Py_InitModule3:methods:PyMethodDef[]:: -Py_InitModule3:doc:char*:: - -Py_InitModule4:PyObject*::0: -Py_InitModule4:name:char*:: -Py_InitModule4:methods:PyMethodDef[]:: -Py_InitModule4:doc:char*:: -Py_InitModule4:self:PyObject*:: -Py_InitModule4:apiver:int::usually provided by Py_InitModule or Py_InitModule3 - PyImport_AddModule:PyObject*::0:reference borrowed from sys.modules PyImport_AddModule:char*:name:: @@ -331,15 +304,6 @@ PyImport_ReloadModule:PyObject*::+1: PyImport_ReloadModule:PyObject*:m:0: - -PyInstance_New:PyObject*::+1: -PyInstance_New:PyObject*:klass:+1: -PyInstance_New:PyObject*:arg:0: -PyInstance_New:PyObject*:kw:0: - -PyInstance_NewRaw:PyObject*::+1: -PyInstance_NewRaw:PyObject*:klass:+1: -PyInstance_NewRaw:PyObject*:dict:+1: PyInt_AS_LONG:long::: PyInt_AS_LONG:PyIntObject*:io:0: diff -ru main/contrib/python-2.0/dist/src/Doc/dist/dist.tex main/Apps/ActivePython-2.0/src/Core/Doc/dist/dist.tex --- main/contrib/python-2.0/dist/src/Doc/dist/dist.tex Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/dist/dist.tex Mon Mar 12 16:10:18 2001 @@ -1,7 +1,9 @@ \documentclass{howto} +\usepackage{ltxmarkup} +\usepackage{times} \usepackage{distutils} -% $Id: dist.tex,v 1.33 2001/03/01 18:35:43 fdrake Exp $ +% $Id: dist.tex,v 1.26 2000/09/12 23:08:53 gward Exp $ \title{Distributing Python Modules} @@ -22,13 +24,7 @@ build/release/install mechanics. \end{abstract} -% The ugly "%begin{latexonly}" pseudo-environment supresses the table -% of contents for HTML generation. -% -%begin{latexonly} \tableofcontents -%end{latexonly} - \section{Introduction} \label{intro} @@ -59,7 +55,7 @@ Using the Distutils is quite simple, both for module developers and for users/administrators installing third-party modules. As a developer, -your responsibilities (apart from writing solid, well-documented and +your responsibilites (apart from writing solid, well-documented and well-tested code, of course!) are: \begin{itemize} \item write a setup script (\file{setup.py} by convention) @@ -94,12 +90,11 @@ all you want to do is distribute a module called \module{foo}, contained in a file \file{foo.py}, then your setup script can be as little as this: - \begin{verbatim} from distutils.core import setup -setup(name="foo", - version="1.0", - py_modules=["foo"]) +setup (name = "foo", + version = "1.0", + py_modules = ["foo"]) \end{verbatim} Some observations: @@ -118,12 +113,10 @@ To create a source distribution for this module, you would create a setup script, \file{setup.py}, containing the above code, and run: - \begin{verbatim} python setup.py sdist \end{verbatim} - -which will create an archive file (e.g., tarball on \UNIX, ZIP file on +which will create an archive file (e.g., tarball on Unix, zip file on Windows) containing your setup script, \file{setup.py}, and your module, \file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or \file{.zip}), and will unpack into a directory \file{Foo-1.0}. @@ -131,11 +124,9 @@ If an end-user wishes to install your \module{foo} module, all she has to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it, and---from the \file{Foo-1.0} directory---run - \begin{verbatim} python setup.py install \end{verbatim} - which will ultimately copy \file{foo.py} to the appropriate directory for third-party modules in their Python installation. @@ -153,29 +144,36 @@ Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the \command{bdist\_wininst} command. For example: - \begin{verbatim} python setup.py bdist_wininst \end{verbatim} - will create an executable installer, \file{Foo-1.0.win32.exe}, in the current directory. -Currently (Distutils 0.9.2), the only other useful built +\XXX{not implemented yet} +(Another way to create executable installers for Windows is with the +\command{bdist\_wise} command, which uses Wise---the commercial +installer-generator used to create Python's own installer---to create +the installer. Wise-based installers are more appropriate for large, +industrial-strength applications that need the full capabilities of a +``real'' installer. \command{bdist\_wininst} creates a self-extracting +zip file with a minimal user interface, which is enough for small- to +medium-sized module collections. You'll need to have version XXX of +Wise installed on your system for the \command{bdist\_wise} command to +work; it's available from \url{http://foo/bar/baz}.) + +Currently (Distutils 0.9.2), the are only other useful built distribution format is RPM, implemented by the \command{bdist\_rpm} command. For example, the following command will create an RPM file called \file{Foo-1.0.noarch.rpm}: - \begin{verbatim} python setup.py bdist_rpm \end{verbatim} - (This uses the \command{rpm} command, so has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.) You can find out what distribution formats are available at any time by running - \begin{verbatim} python setup.py bdist --help-formats \end{verbatim} @@ -196,12 +194,12 @@ single \file{.py} file (and possibly associated \file{.pyc} and/or \file{.pyo} files). Sometimes referred to as a ``pure module.'' \item[extension module] a module written in the low-level language of - the Python implementation: C/C++ for Python, Java for JPython. + the Python implemention: C/C++ for CPython, Java for JPython. Typically contained in a single dynamically loadable pre-compiled - file, e.g. a shared object (\file{.so}) file for Python extensions on - \UNIX, a DLL (given the \file{.pyd} extension) for Python extensions + file, e.g. a shared object (\file{.so}) file for CPython extensions on + Unix, a DLL (given the \file{.pyd} extension) for CPython extensions on Windows, or a Java class file for JPython extensions. (Note that - currently, the Distutils only handles C/C++ extensions for Python.) + currently, the Distutils only handles C/C++ extensions for CPython.) \item[package] a module that contains other modules; typically contained in a directory in the filesystem and distinguished from other directories by the presence of a file \file{\_\_init\_\_.py}. @@ -265,16 +263,16 @@ from distutils.core import setup -setup(name="Distutils", - version="1.0", - description="Python Distribution Utilities", - author="Greg Ward", - author_email="gward@python.net", - url="http://www.python.org/sigs/distutils-sig/", - packages=['distutils', 'distutils.command'], - ) -\end{verbatim} +setup (name = "Distutils", + version = "1.0", + description = "Python Distribution Utilities", + author = "Greg Ward", + author_email = "gward@python.net", + url = "http://www.python.org/sigs/distutils-sig/", + packages = ['distutils', 'distutils.command'], + ) +\end{verbatim} There are only two differences between this and the trivial one-file distribution presented in section~\ref{simple-example}: more meta-data, and the specification of pure Python modules by package, @@ -284,25 +282,16 @@ maintain. Note that any pathnames (files or directories) supplied in the setup -script should be written using the \UNIX{} convention, i.e. +script should be written using the Unix convention, i.e. slash-separated. The Distutils will take care of converting this platform-neutral representation into whatever is appropriate on your 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 (MacOS programmers should keep in +this document are slash-separated (Mac OS programmers should keep in mind that the \emph{absence} of a leading slash indicates a relative -path, the opposite of the MacOS convention with colons). +path, the opposite of the Mac OS convention with colons). -This, of course, only applies to pathnames given to Distutils functions. -If you, for example, use standard python functions such as glob.glob -or os.listdir to specify files, you should be careful to write portable -code instead of hardcoding path separators: - -\begin{verbatim} - glob.glob(os.path.join('mydir', 'subdir', '*.html')) - os.listdir(os.path.join('mydir', 'subdir')) -\end{verbatim} \subsection{Listing whole packages} \label{listing-packages} @@ -328,11 +317,9 @@ ``root package'' (i.e., not in any package at all) are right in \file{lib}, modules in the \module{foo} package are in \file{lib/foo}, and so forth. Then you would put - \begin{verbatim} package_dir = {'': 'lib'} \end{verbatim} - in your setup script. (The keys to this dictionary are package names, and an empty package name stands for the root package. The values are directory names relative to your distribution root.) In this case, when @@ -342,11 +329,9 @@ Another possible convention is to put the \module{foo} package right in \file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This would be written in the setup script as - \begin{verbatim} package_dir = {'foo': 'lib'} \end{verbatim} - A \code{\var{package}: \var{dir}} entry in the \option{package\_dir} dictionary implicitly applies to all packages below \var{package}, so the \module{foo.bar} case is automatically handled here. In this @@ -367,11 +352,9 @@ that goes in the ``root package'' (i.e., no package at all). This simplest case was shown in section~\ref{simple-example}; here is a slightly more involved example: - \begin{verbatim} py_modules = ['mod1', 'pkg.mod2'] \end{verbatim} - This describes two modules, one of them in the ``root'' package, the other in the \module{pkg} package. Again, the default package/directory layout implies that these two modules can be found in \file{mod1.py} and @@ -398,24 +381,21 @@ extension, called \module{foo} and implemented by \file{foo.c}. If no additional instructions to the compiler/linker are needed, describing this extension is quite simple: - \begin{verbatim} Extension("foo", ["foo.c"]) \end{verbatim} - The \class{Extension} class can be imported from \module{distutils.core}, along with \function{setup()}. Thus, the setup script for a module distribution that contains only this one extension and nothing else might be: - \begin{verbatim} from distutils.core import setup, Extension -setup(name="foo", version="1.0", - ext_modules=[Extension("foo", ["foo.c"])]) +setup(name = "foo", version = "1.0", + ext_modules = [Extension("foo", ["foo.c"])]) \end{verbatim} The \class{Extension} class (actually, the underlying extension-building -machinery implemented by the \command{build\_ext} command) supports a +machinery implemented by the \command{built\_ext} command) supports a great deal of flexibility in describing Python extensions, which is explained in the following sections. @@ -424,17 +404,13 @@ The first argument to the \class{Extension} constructor is always the name of the extension, including any package names. For example, - \begin{verbatim} Extension("foo", ["src/foo1.c", "src/foo2.c"]) \end{verbatim} - describes an extension that lives in the root package, while - \begin{verbatim} Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"]) \end{verbatim} - describes the same extension in the \module{pkg} package. The source files and resulting object code are identical in both cases; the only difference is where in the filesystem (and therefore where in Python's @@ -443,15 +419,13 @@ If you have a number of extensions all in the same package (or all under the same base package), use the \option{ext\_package} keyword argument to \function{setup()}. For example, - \begin{verbatim} setup(... - ext_package="pkg", - ext_modules=[Extension("foo", ["foo.c"]), - Extension("subpkg.bar", ["bar.c"])] + ext_package = "pkg", + ext_modules = [Extension("foo", ["foo.c"]), + Extension("subpkg.bar", ["bar.c"])] ) \end{verbatim} - will compile \file{foo.c} to the extension \module{pkg.foo}, and \file{bar.c} to \module{pkg.subpkg.bar}. @@ -462,7 +436,7 @@ source files. Since the Distutils currently only support C/C++ extensions, these are normally C/C++ source files. (Be sure to use appropriate extensions to distinguish C++ source files: \file{.cc} and -\file{.cpp} seem to be recognized by both \UNIX{} and Windows compilers.) +\file{.cpp} seem to be recognized by both Unix and Windows compilers.) However, you can also include SWIG interface (\file{.i}) files in the list; the \command{build\_ext} command knows how to deal with SWIG @@ -475,9 +449,8 @@ On some platforms, you can include non-source files that are processed by the compiler and included in your extension. Currently, this just -means Windows message text (\file{.mc}) files and resource definition -(\file{.rc}) files for Visual C++. These will be compiled to binary resource -(\file{.res}) files and linked into the executable. +means Windows resource files for Visual C++. \XXX{get more detail on + this feature from Thomas Heller!} \subsubsection{Preprocessor options} @@ -490,19 +463,16 @@ For example, if your extension requires header files in the \file{include} directory under your distribution root, use the \code{include\_dirs} option: - \begin{verbatim} Extension("foo", ["foo.c"], include_dirs=["include"]) \end{verbatim} You can specify absolute directories there; if you know that your -extension will only be built on \UNIX{} systems with X11R6 installed to +extension will only be built on Unix systems with X11R6 installed to \file{/usr}, you can get away with - \begin{verbatim} Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"]) \end{verbatim} - You should avoid this sort of non-portable usage if you plan to distribute your code: it's probably better to write your code to include (e.g.) \code{}. @@ -510,7 +480,7 @@ If you need to include header files from some other Python extension, you can take advantage of the fact that the Distutils install extension header files in a consistent way. For example, the Numerical Python -header files are installed (on a standard \UNIX{} installation) to +header files are installed (on a standard Unix installation) to \file{/usr/local/include/python1.5/Numerical}. (The exact location will differ according to your platform and Python installation.) Since the Python include directory---\file{/usr/local/include/python1.5} in this @@ -520,14 +490,12 @@ \file{Numerical} include directory right into your header search path, though, you can find that directory using the Distutils \module{sysconfig} module: - \begin{verbatim} from distutils.sysconfig import get_python_inc incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical") setup(..., Extension(..., include_dirs=[incdir])) \end{verbatim} - Even though this is quite portable---it will work on any Python installation, regardless of platform---it's probably easier to just write your C code in the sensible way. @@ -543,16 +511,13 @@ a list of macros to undefine. For example: - \begin{verbatim} Extension(..., define_macros=[('NDEBUG', '1')], ('HAVE_STRFTIME', None), undef_macros=['HAVE_FOO', 'HAVE_BAR']) \end{verbatim} - is the equivalent of having this at the top of every C source file: - \begin{verbatim} #define NDEBUG 1 #define HAVE_STRFTIME @@ -572,7 +537,6 @@ For example, if you need to link against libraries known to be in the standard library search path on target systems - \begin{verbatim} Extension(..., libraries=["gdbm", "readline"]) @@ -580,75 +544,17 @@ If you need to link with libraries in a non-standard location, you'll have to include the location in \code{library\_dirs}: - \begin{verbatim} Extension(..., library_dirs=["/usr/X11R6/lib"], libraries=["X11", "Xt"]) \end{verbatim} - (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -\XXX{Should mention clib libraries here or somewhere else!} - -\subsubsection{Other options} - -There are still some other options which can be used to handle special -cases. - -The \option{extra\_objects} option is a list of object files to be passed -to the linker. These files must not have extensions, as the default -extension for the compiler is used. - -\option{extra\_compile\_args} and \option{extra\_link\_args} can be used -to specify additional command line options for the compiler resp. -the linker command line. - -\option{export\_symbols} is only useful on windows, it can contain a list -of symbols (functions or variables) to be exported. This option -is not needed when building compiled extensions: the \code{initmodule} -function will automatically be added to the exported symbols list -by Distutils. - -\subsection{Listing 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. - -Scripts are files containing Python source code, indended to be started -from the command line. -Distutils doesn't provide much functionality for the scripts: the only -support Distutils gives is to adjust the first line of the script -if it starts with \code{\#!} and contains the word ``python'' to refer -to the current interpreter location. - -The \option{scripts} option simply is a list of files to be handled -in this way. - - -\subsection{Listing additional files} - -The \option{data\_files} option can be used to specify additional -files needed by the module distribution: configuration files, -data files, anything which does not fit in the previous categories. - -\option{data\_files} specify a sequence of \code{(directory, files)} -pairs in the following way: - -\begin{verbatim} -setup(... - data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), - ('config', ['cfg/data.cfg'])]) -\end{verbatim} - -Note that you can specify the directory names where the data files -will be installed, but you cannot rename the data files themselves. - -You can specify the \option{data\_files} options as a simple sequence -of files without specifying a target directory, but this is not recommended, -and the \command{install} command will print a warning in this case. -To install data files directly in the target directory, an empty -string should be given as the directory. +\XXX{still undocumented: extra\_objects, extra\_compile\_args, + extra\_link\_args, export\_symbols---none of which are frequently + needed, some of which might be completely unnecessary!} \section{Writing the Setup Configuration File} @@ -670,6 +576,9 @@ started to appear in Distutils 0.9 but, as of this writing, isn't mature or stable enough yet for real-world use.) +\XXX{should reference description of distutils config files in + ``Installing'' manual here} + The setup configuration file is a useful middle-ground between the setup script---which, ideally, would be opaque to installers\footnote{This ideal probably won't be achieved until auto-configuration is fully @@ -689,24 +598,21 @@ \end{itemize} The basic syntax of the configuration file is simple: - \begin{verbatim} [command] option=value ... \end{verbatim} - where \var{command} is one of the Distutils commands (e.g. \command{build\_py}, \command{install}), and \var{option} is one of the options that command supports. Any number of options can be supplied for each command, and any number of command sections can be included in -the file. Blank lines are ignored, as are comments (from a -\character{\#} character to end-of-line). Long option values can be -split across multiple lines simply by indenting the continuation lines. +the file. Blank lines are ignored, as are comments (from a \verb+#+ +character to end-of-line). Long option values can be split across +multiple lines simply by indenting the continuation lines. You can find out the list of options supported by a particular command with the universal \longprogramopt{help} option, e.g. - \begin{verbatim} > python setup.py --help build_ext [...] @@ -720,7 +626,6 @@ --undef (-U) C preprocessor macros to undefine [...] \end{verbatim} - Or consult section \ref{reference} of this document (the command reference). @@ -729,25 +634,21 @@ For example, say you want your extensions to be built ``in-place''---that is, you have an extension \module{pkg.ext}, and you -want the compiled extension file (\file{ext.so} on \UNIX, say) to be put +want the compiled extension file (\file{ext.so} on Unix, say) to be put in the same source directory as your pure Python modules \module{pkg.mod1} and \module{pkg.mod2}. You can always use the \longprogramopt{inplace} option on the command-line to ensure this: - \begin{verbatim} python setup.py build_ext --inplace \end{verbatim} - But this requires that you always specify the \command{build\_ext} command explicitly, and remember to provide \longprogramopt{inplace}. An easier way is to ``set and forget'' this option, by encoding it in \file{setup.cfg}, the configuration file for this distribution: - \begin{verbatim} [build_ext] inplace=1 \end{verbatim} - This will affect all builds of this module distribution, whether or not you explcitly specify \command{build\_ext}. If you include \file{setup.cfg} in your source distribution, it will also affect @@ -767,7 +668,6 @@ \command{bdist\_rpm}, which would be very tedious to do on the command-line for every run. Hence, here is a snippet from the Distutils' own \file{setup.cfg}: - \begin{verbatim} [bdist_rpm] release = 1 @@ -778,42 +678,30 @@ doc/ examples/ \end{verbatim} - Note that the \option{doc\_files} option is simply a whitespace-separated string split across multiple lines for readability. -\begin{seealso} - \seetitle[../inst/config-syntax.html]{Installing Python - Modules}{More information on the configuration files is - available in the manual for system administrators.} -\end{seealso} - - \section{Creating a Source Distribution} \label{source-dist} As shown in section~\ref{simple-example}, you use the \command{sdist} command to create a source distribution. In the simplest case, - \begin{verbatim} python setup.py sdist \end{verbatim} - (assuming you haven't specified any \command{sdist} options in the setup script or config file), \command{sdist} creates the archive of the default format for the current platform. The default format is gzip'ed -tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows. -\XXX{no MacOS support here} +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: - \begin{verbatim} python setup.py sdist --formats=gztar,zip \end{verbatim} - to create a gzipped tarball and a zip file. The available formats are: \begin{tableiii}{l|l|c}{code}% {Format}{Description}{Notes} @@ -827,7 +715,7 @@ \noindent Notes: \begin{description} \item[(1)] default on Windows -\item[(2)] default on \UNIX +\item[(2)] default on Unix \item[(3)] requires either external \program{zip} utility or \module{zipfile} module (not part of the standard Python library) \item[(4)] requires external utilities: \program{tar} and possibly one @@ -873,13 +761,11 @@ specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template: - \begin{verbatim} include *.txt recursive-include examples *.txt *.py prune examples/sample?/build \end{verbatim} - The meanings should be fairly clear: include all files in the distribution root matching \code{*.txt}, all files anywhere under the \file{examples} directory matching \code{*.txt} or \code{*.py}, and @@ -970,18 +856,15 @@ example, if you have added or removed files or directories that match an existing pattern in the manifest template, you should regenerate the manifest: - \begin{verbatim} python setup.py sdist --force-manifest \end{verbatim} Or, you might just want to (re)generate the manifest, but not create a source distribution: - \begin{verbatim} python setup.py sdist --manifest-only \end{verbatim} - \longprogramopt{manifest-only} implies \longprogramopt{force-manifest}. \programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and \programopt{-f} for \longprogramopt{force-manifest}. @@ -1021,20 +904,18 @@ As a simple example, if I run the following command in the Distutils source tree: - \begin{verbatim} python setup.py bdist \end{verbatim} - then the Distutils builds my module distribution (the Distutils itself in this case), does a ``fake'' installation (also in the \file{build} directory), and creates the default type of built distribution for my platform. The default format for built distributions is a ``dumb'' tar -file on \UNIX, and an simple executable installer on Windows. (That tar +file on Unix, and an simple executable installer on Windows. (That tar file is considered ``dumb'' because it has to be unpacked in a specific location to work.) -Thus, the above command on a \UNIX{} system creates +Thus, the above command on a Unix system creates \file{Distutils-0.9.1.\filevar{plat}.tar.gz}; unpacking this tarball from the right place installs the Distutils just as though you had downloaded the source distribution and run \code{python setup.py @@ -1053,12 +934,10 @@ The \command{bdist} command has a \longprogramopt{formats} option, similar to the \command{sdist} command, which you can use to select the types of built distribution to generate: for example, - \begin{verbatim} python setup.py bdist --format=zip \end{verbatim} - -would, when run on a \UNIX{} system, create +would, when run on a Unix system, create \file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be unpacked from the root directory to install the Distutils. @@ -1071,12 +950,13 @@ \lineiii{zip}{zip file (\file{.zip})}{(4)} \lineiii{rpm}{RPM}{(5)} \lineiii{srpm}{source RPM}{(5) \XXX{to do!}} - \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)} + \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(6)} + %\lineiii{wise}{Wise installer for Windows}{(3)} \end{tableiii} \noindent Notes: \begin{description} -\item[(1)] default on \UNIX +\item[(1)] default on Unix \item[(2)] default on Windows \XXX{to-do!} \item[(3)] requires external utilities: \program{tar} and possibly one of \program{gzip}, \program{bzip2}, or \program{compress} @@ -1084,6 +964,8 @@ \module{zipfile} module (not part of the standard Python library) \item[(5)] requires external \program{rpm} utility, version 3.0.4 or better (use \code{rpm --version} to find out which version you have) +\item[(6)] \XXX{requirements for \command{bdist\_wininst}?} +%\item[(3)] not implemented yet \end{description} You don't have to use the \command{bdist} command with the @@ -1100,6 +982,7 @@ \lineii{bdist\_dumb}{tar, ztar, gztar, zip} \lineii{bdist\_rpm}{rpm, srpm} \lineii{bdist\_wininst}{wininst} + %\lineii{bdist\_wise}{wise} \end{tableii} The following sections give details on the individual \command{bdist\_*} @@ -1126,22 +1009,17 @@ The usual way to create an RPM of your module distribution is to run the \command{bdist\_rpm} command: - \begin{verbatim} python setup.py bdist_rpm \end{verbatim} - or the \command{bdist} command with the \longprogramopt{format} option: - \begin{verbatim} python setup.py bdist --formats=rpm \end{verbatim} - The former allows you to specify RPM-specific options; the latter allows you to easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple \command{bdist\_*} commands and their options: - \begin{verbatim} python setup.py bdist_rpm --packager="John Doe " \ bdist_wininst --target_version="2.0" @@ -1152,7 +1030,7 @@ the \command{bdist\_rpm} command normally creates a \file{.spec} file based on the information you supply in the setup script, on the command line, and in any Distutils configuration files. Various options and -sections in the \file{.spec} file are derived from options in the setup +section in the \file{.spec} file are derived from options in the setup script as follows: \begin{tableii}{l|l}{textrm}% {RPM \file{.spec} file option or section}{Distutils setup script option} @@ -1176,11 +1054,11 @@ \lineiii{Release}{\option{release}}{``1''} \lineiii{Group}{\option{group}}{``Development/Libraries''} \lineiii{Vendor}{\option{vendor}}{(see above)} - \lineiii{Packager}{\option{packager}}{(none)} - \lineiii{Provides}{\option{provides}}{(none)} - \lineiii{Requires}{\option{requires}}{(none)} - \lineiii{Conflicts}{\option{conflicts}}{(none)} - \lineiii{Obsoletes}{\option{obsoletes}}{(none)} + \lineiii{Packager}{packager}{(none)} + \lineiii{Provides}{provides}{(none)} + \lineiii{Requires}{requires}{(none)} + \lineiii{Conflicts}{conflicts}{(none)} + \lineiii{Obsoletes}{obsoletes}{(none)} \lineiii{Distribution}{\option{distribution\_name}}{(none)} \lineiii{BuildRequires}{\option{build\_requires}}{(none)} \lineiii{Icon}{\option{icon}}{(none)} @@ -1217,16 +1095,14 @@ \XXX{this isn't implemented yet---is it needed?!} You can also specify a custom \file{.spec} file with the -\longprogramopt{spec-file} option; used in conjunction with +\longprogramopt{spec-file} option; used in conjunctin with \longprogramopt{spec-only}, this gives you an opportunity to customize the \file{.spec} file manually: - \begin{verbatim} > python setup.py bdist_rpm --spec-only # ...edit dist/FooBar-1.0.spec > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec \end{verbatim} - (Although a better way to do this is probably to override the standard \command{bdist\_rpm} command with one that writes whatever else you want to the \file{.spec} file; see section~\ref{extending} for information on @@ -1236,78 +1112,42 @@ \subsection{Creating Windows installers} \label{creating-wininst} -Executable Windows installers are the natural format for binary -distributions on Windows. They display a nice GUI interface, display -some information of the module distribution to be installed, taken -from the meta-dada in the setup script, let the user select a few -(currently maybe too few) options, and start or cancel the installation. - -Since the meta-data is taken from the setup script, creating -Windows installers is usually as easy as running: - -\begin{verbatim} -python setup.py bdist_wininst -\end{verbatim} - -or the \command{bdist} command with the \longprogramopt{format} option: - -\begin{verbatim} -python setup.py bdist --formats=wininst -\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 dependend. -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} +\section{Examples} +\label{examples} -%\subsection{Pure Python distribution (by module)} -%\label{pure-mod} +\subsection{Pure Python distribution (by module)} +\label{pure-mod} -%\subsection{Pure Python distribution (by package)} -%\label{pure-pkg} +\subsection{Pure Python distribution (by package)} +\label{pure-pkg} -%\subsection{Single extension module} -%\label{single-ext} +\subsection{Single extension module} +\label{single-ext} -%\subsection{Multiple extension modules} -%\label{multiple-ext} +\subsection{Multiple extension modules} +\label{multiple-ext} -%\subsection{Putting it all together} +\subsection{Putting it all together} -%\section{Extending the Distutils} -%\label{extending} +\section{Extending the Distutils} +\label{extending} -%\subsection{Extending existing commands} -%\label{extend-existing} +\subsection{Extending existing commands} +\label{extend-existing} -%\subsection{Writing new commands} -%\label{new-commands} - -%\XXX{Would an uninstall command be a good example here?} +\subsection{Writing new commands} +\label{new-commands} @@ -1315,20 +1155,20 @@ \label{reference} -%\subsection{Building modules: the \protect\command{build} command family} -%\label{build-cmds} +\subsection{Building modules: the \protect\command{build} command family} +\label{build-cmds} -%\subsubsection{\protect\command{build}} -%\label{build-cmd} +\subsubsection{\protect\command{build}} +\label{build-cmd} -%\subsubsection{\protect\command{build\_py}} -%\label{build-py-cmd} +\subsubsection{\protect\command{build\_py}} +\label{build-py-cmd} -%\subsubsection{\protect\command{build\_ext}} -%\label{build-ext-cmd} +\subsubsection{\protect\command{build\_ext}} +\label{build-ext-cmd} -%\subsubsection{\protect\command{build\_clib}} -%\label{build-clib-cmd} +\subsubsection{\protect\command{build\_clib}} +\label{build-clib-cmd} \subsection{Installing modules: the \protect\command{install} command family} @@ -1339,8 +1179,8 @@ \command{install\_data} and \command{install\_scripts}. -%\subsubsection{\protect\command{install\_lib}} -%\label{install-lib-cmd} +\subsubsection{\protect\command{install\_lib}} +\label{install-lib-cmd} \subsubsection{\protect\command{install\_data}} \label{install-data-cmd} @@ -1351,12 +1191,11 @@ This command installs all (Python) scripts in the distribution. -%\subsection{Cleaning up: the \protect\command{clean} command} -%\label{clean-cmd} +\subsection{Cleaning up: the \protect\command{clean} command} +\label{clean-cmd} -\subsection{Creating a source distribution: the - \protect\command{sdist} command} +\subsection{Creating a source distribution: the \protect\command{sdist} command} \label{sdist-cmd} @@ -1381,29 +1220,35 @@ \lineii{prune \var{dir}}{exclude all files under \var{dir}} \lineii{graft \var{dir}}{include all files under \var{dir}} \end{tableii} -The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any +The patterns here are Unix-style ``glob'' patterns: \code{*} matches any sequence of regular filename characters, \code{?} matches any single regular filename character, and \code{[\var{range}]} matches any of the 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 MacOS anything except colon. +platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon; on Mac OS anything except colon. + +\XXX{Windows and Mac OS support not there yet} + + +\subsection{Creating a ``built'' distribution: the + \protect\command{bdist} command family} +\label{bdist-cmds} + + +\subsubsection{\protect\command{blib}} + +\subsubsection{\protect\command{blib\_dumb}} -\XXX{Windows and MacOS support not there yet} +\subsubsection{\protect\command{blib\_rpm}} +\subsubsection{\protect\command{blib\_wise}} -%\subsection{Creating a built distribution: the -% \protect\command{bdist} command family} -%\label{bdist-cmds} -%\subsubsection{\protect\command{blib}} -%\subsubsection{\protect\command{blib\_dumb}} -%\subsubsection{\protect\command{blib\_rpm}} -%\subsubsection{\protect\command{blib\_wise}} \end{document} diff -ru main/contrib/python-2.0/dist/src/Doc/doc/doc.tex main/Apps/ActivePython-2.0/src/Core/Doc/doc/doc.tex --- main/contrib/python-2.0/dist/src/Doc/doc/doc.tex Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/doc/doc.tex Mon Mar 12 16:10:18 2001 @@ -10,8 +10,8 @@ \author{Fred L. Drake, Jr.} \authoraddress{ - PythonLabs \\ - E-mail: \email{fdrake@acm.org} + BeOpen PythonLabs \\ + E-mail: \email{fdrake@beopen.com} } @@ -191,194 +191,10 @@ because it would cause output. The document body follows the preamble. This contains all the - printed components of the document marked up structurally. Generic - \LaTeX{} structures include hierarchical sections + printed components of the document marked up structurally. - \subsection{Syntax} - - There are only a things that an author of Python documentation - needs to know about \LaTeX{} syntax. - - A \dfn{comment} is started by the ``percent'' character - (\character{\%}) and continues through the end of the line and all - leading whitespace on the following line. This is a little - different from any programming language I know of, so an example - is in order: - -\begin{verbatim} -This is text.% comment - This is more text. % another comment -Still more text. -\end{verbatim} - - The first non-comment character following the first comment is the - letter \character{T} on the second line; the leading whitespace on - that line is consumed as part of the first comment. This means - that there is no space between the first and second sentences, so - the period and letter \character{T} will be directly adjacent in - the typeset document. - - Note also that though the first non-comment character after the - second comment is the letter \character{S}, there is whitespace - preceding the comment, so the two sentences are separated as - expected. - - A \dfn{group} is an enclosure for a collection of text and - commands which encloses the formatting context and constrains the - scope of any changes to that context made by commands within the - group. Groups can be nested hierarchically. The formatting - context includes the font and the definition of additional macros - (or overrides of macros defined in outer groups). Syntactically, - groups are enclosed in braces: - -\begin{verbatim} -{text in a group} -\end{verbatim} - - An alternate syntax for a group using brackets (\code{\{...\}}) is - used by macros and environment constructors which take optional - parameters; brackets do not normally hold syntactic significance. - A degenerate group, containing only one atomic bit of content, - does not need to have an explicit group, unless it is required to - avoid ambiguity. Since Python tends toward the explicit, groups - are also made explicit in the documentation markup. - - Groups are used only sparingly in the Python documentation, except - for their use in marking parameters to macros and environments. - - A \dfn{macro} is usually simple construct which is identified by - name and can take some number of parameters. In normal \LaTeX{} - usage, one of these can be optional. The markup is introduced - using the backslash character (\character{\e}), and the name is - given by alphabetic characters (no digits, hyphens, or - underscores). Required parameters should be marked as a group, - and optional parameters should be marked using the alternate - syntax for a group. - - For example, a macro named ``foo'' which takes a single parameter - would appear like this: - -\begin{verbatim} -\name{parameter} -\end{verbatim} - - A macro which takes an optional parameter would be typed like this - when the optional paramter is given: - -\begin{verbatim} -\name[optional] -\end{verbatim} - - If both optional and required parameters are to be required, it - looks like this: - -\begin{verbatim} -\name[optional]{required} -\end{verbatim} - - A macro name may be followed by a space or newline; a space - between the macro name and any parameters will be consumed, but - this usage is not practiced in the Python documentation. Such a - space is still consumed if there are no parameters to the marco, - in which case inserting an empty group (\code{\{\}}) or explicit - word space (\samp{\e\ }) immediately after the macro name helps to - avoid running the expansion of the macro into the following text. - Macros which take no parameters but which should not be followed - by a word space do not need special treatment if the following - character in the document source if not a name character (such as - puctuation). - - Each line of this example shows an appropriate way to write text - which includes a macro which takes no parameters: - -\begin{verbatim} -This \UNIX{} is followed by a space. -This \UNIX\ is also followed by a space. -\UNIX, followed by a comma, needs no additional markup. -\end{verbatim} - - An \dfn{environment} is a larger construct than a macro, and can - be used for things with more content that would conveniently fit - in a macro parameter. They are primarily used when formatting - parameters need to be changed before and after a large chunk of - content, but the content itself needs to be highly flexible. Code - samples are presented using an environment, and descriptions of - functions, methods, and classes are also marked using envionments. - - Since the content of an environment is free-form and can consist - of several paragraphs, they are actually marked using a pair of - macros: \macro{begin} and \macro{end}. These macros both take the - name of the environment as a parameter. An example is the - environment used to mark the abstract of a document: - -\begin{verbatim} -\begin{abstract} - This is the text of the abstract. It concisely explains what - information is found in the document. - - It can consist of multiple paragraphs. -\end{abstract} -\end{verbatim} - - An environment can also have required and optional parameters of - its own. These follow the parameter of the \macro{begin} macro. - This example shows an environment which takes a single required - parameter: - -\begin{verbatim} -\begin{datadesc}{datadesc}{controlnames} - A 33-element string array that contains the \ASCII{} mnemonics for - the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f - (US), in order, plus the mnemonic \samp{SP} for the space character. -\end{datadesc} -\end{verbatim} - - There are a number of less-used marks in \LaTeX{} are used to - enter non-\ASCII{} characters, especially those used in European - names. Given that these are often used adjacent to other - characters, the markup required to produce the proper character - may need to be followed by a space or an empty group, or the the - markup can be enclosed in a group. Some which are found in Python - documentation are: - -\begin{tableii}{c|l}{textrm}{Character}{Markup} - \lineii{\c c}{\code{\e c c}} - \lineii{\"o}{\code{\e"o}} - \lineii{\o}{\code{\e o}} -\end{tableii} - - - \subsection{Hierarchical Structure} - - \LaTeX{} expects documents to be arranged in a conventional, - hierarchical way, with chapters, sections, sub-sections, - appendixes, and the like. These are marked using macros rather - than environments, probably because the end of a section can be - safely inferred when a section of equal or higher level starts. - - There are six ``levels'' of sectioning in the document classes - used for Python documentation, and the lowest two levels are not - used. The levels are: - - \begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes} - \lineiii{1}{\macro{chapter}}{(1)} - \lineiii{2}{\macro{section}}{} - \lineiii{3}{\macro{subsection}}{} - \lineiii{4}{\macro{subsubsection}}{} - \lineiii{5}{\macro{paragraph}}{(2)} - \lineiii{6}{\macro{subparagraph}}{} - \end{tableiii} - - \noindent - Notes: - - \begin{description} - \item[(1)] - Only used for the \code{manual} documents, as described in - section \ref{classes}, ``Document Classes.'' - \item[(2)] - Not the same as a paragraph of text; nobody seems to use this. - \end{description} + XXX This section will discuss what the markup looks like, and + explain the difference between an environment and a macro. \section{Document Classes \label{classes}} @@ -574,22 +390,13 @@ Representing an interactive session requires including the prompts and output along with the Python code. No special markup is - required for interactive sessions. After the last line of input - or output presented, there should not be an ``unused'' primary - prompt; this is an example of what \emph{not} to do: - -\begin{verbatim} ->>> 1 + 1 -2 ->>> -\end{verbatim} + required for interactive sessions. Within the \env{verbatim} environment, characters special to \LaTeX{} do not need to be specially marked in any way. The entire example will be presented in a monospaced font; no attempt at ``pretty-printing'' is made, as the environment must work for - non-Python code and non-code displays. There should be no blank - lines at the top or bottom of any \env{verbatim} display. + non-Python code and non-code displays. The Python Documentation Special Interest Group has discussed a number of approaches to creating pretty-printed code displays and @@ -849,7 +656,7 @@ The version of Python in which the named feature was changed in some way (new parameters, changed side effects, etc.). \var{explanation} should be a \emph{brief} explanation of the - change consisting of a capitalized sentence fragment; a + change consisting of a non-capitalized sentence fragment; a period will be appended by the formatting process. This is typically added to the end of the first paragraph of the description before any availability notes and after diff -ru main/contrib/python-2.0/dist/src/Doc/ext/ext.tex main/Apps/ActivePython-2.0/src/Core/Doc/ext/ext.tex --- main/contrib/python-2.0/dist/src/Doc/ext/ext.tex Mon Mar 12 16:11:27 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/ext/ext.tex Mon Mar 12 16:10:18 2001 @@ -19,6 +19,16 @@ \input{copyright} +%begin{latexonly} +\vspace{1in} +%end{latexonly} +\strong{\large Acknowledgements} + +% XXX This needs to be checked and updated manually before each +% release. + +The following people have contributed sections to this document: Jim +Fulton, Konrad Hinsen, Chris Phoenix, and Neil Schemenauer. \begin{abstract} @@ -277,19 +287,14 @@ Note that the Python name for the exception object is \exception{spam.error}. The \cfunction{PyErr_NewException()} function -may create a class with the base class being \exception{Exception} -(unless another class is passed in instead of \NULL), described in the +may create either a string or class, depending on whether the +\programopt{-X} flag was passed to the interpreter. If +\programopt{-X} was used, \cdata{SpamError} will be a string object, +otherwise it will be a class object with the base class being +\exception{Exception}, described in the \citetitle[../lib/lib.html]{Python Library Reference} under ``Built-in Exceptions.'' -Note also that the \cdata{SpamError} variable retains a reference to -the newly created exception class; this is intentional! Since the -exception could be removed from the module by external code, an owned -reference to the class is needed to ensure that it will not be -discarded, causing \cdata{SpamError} to become a dangling pointer. -Should it become a dangling pointer, C code which raises the exception -could cause a core dump or other unintended side effects. - \section{Back to the Example \label{backToExample}} @@ -636,7 +641,7 @@ memory, and this should be checked. -\section{Extracting Parameters in Extension Functions +\section{Format Strings for \cfunction{PyArg_ParseTuple()} \label{parseTuple}} The \cfunction{PyArg_ParseTuple()} function is declared as follows: @@ -723,9 +728,10 @@ encoded data without embedded \NULL{} bytes. The variant reads one C variable and stores into two C variables, the -first one a pointer to an encoding name string (\var{encoding}), and the +first one a pointer to an encoding name string (\var{encoding}), the second a pointer to a pointer to a character buffer (\var{**buffer}, -the buffer used for storing the encoded data). +the buffer used for storing the encoded data) and the third one a +pointer to an integer (\var{*buffer_length}, the buffer length). The encoding name must map to a registered codec. If set to \NULL{}, the default encoding is used. @@ -740,7 +746,7 @@ object) {[const char *encoding, char **buffer, int *buffer_length]}] This variant on \samp{s\#} is used for encoding Unicode and objects convertible to Unicode into a character buffer. It reads one C -variable and stores into three C variables, the first one a pointer to +variable and stores into two C variables, the first one a pointer to an encoding name string (\var{encoding}), the second a pointer to a pointer to a character buffer (\var{**buffer}, the buffer used for storing the encoded data) and the third one a pointer to an integer @@ -891,8 +897,8 @@ the exception that \cfunction{PyArg_ParseTuple()} raises). \item[\samp{;}] -The list of format units ends here; the string after the semicolon is -used as the error message \emph{instead} of the default error message. +The list of format units ends here; the string after the colon is used +as the error message \emph{instead} of the default error message. Clearly, \samp{:} and \samp{;} mutually exclude each other. \end{description} @@ -961,7 +967,7 @@ \end{verbatim} -\section{Keyword Parameters for Extension Functions +\section{Keyword Parsing with \cfunction{PyArg_ParseTupleAndKeywords()} \label{parseTupleAndKeywords}} The \cfunction{PyArg_ParseTupleAndKeywords()} function is declared as @@ -1035,7 +1041,7 @@ \end{verbatim} -\section{Building Arbitrary Values +\section{The \cfunction{Py_BuildValue()} Function \label{buildValue}} This function is the counterpart to \cfunction{PyArg_ParseTuple()}. It is @@ -1106,6 +1112,15 @@ Unicode object. If the Unicode buffer pointer is \NULL, the length is ignored and \code{None} is returned. +\item[\samp{u} (Unicode string) {[Py_UNICODE *]}] +Convert a null-terminated buffer of Unicode (UCS-2) data to a Python Unicode +object. If the Unicode buffer pointer is \NULL{}, \code{None} is returned. + +\item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}] +Convert a Unicode (UCS-2) data buffer and its length to a Python Unicode +object. If the Unicode buffer pointer is \NULL{}, the length is ignored and +\code{None} is returned. + \item[\samp{i} (integer) {[int]}] Convert a plain C \ctype{int} to a Python integer object. @@ -1619,10 +1634,9 @@ void initspam() { - PyObject *m; + PyObject *m, *d; static void *PySpam_API[PySpam_API_pointers]; PyObject *c_api_object; - m = Py_InitModule("spam", SpamMethods); /* Initialize the C API pointer array */ @@ -1631,13 +1645,9 @@ /* Create a CObject containing the API pointer array's address */ c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL); - if (c_api_object != NULL) { - /* Create a name for this object in the module's namespace */ - PyObject *d = PyModule_GetDict(m); - - PyDict_SetItemString(d, "_C_API", c_api_object); - Py_DECREF(c_api_object); - } + /* Create a name for this object in the module's namespace */ + d = PyModule_GetDict(m); + PyDict_SetItemString(d, "_C_API", c_api_object); } \end{verbatim} @@ -1729,429 +1739,8 @@ \file{Objects/cobject.c} in the Python source code distribution). -\chapter{Defining New Types - \label{defining-new-types}} -\sectionauthor{Michael Hudson}{mwh21@cam.ac.uk} - -As mentioned in the last chapter, Python allows the writer of an -extension module to define new types that can be manipulated from -Python code, much like strings and lists in core Python. - -This is not hard; the code for all extension types follows a pattern, -but there are some details that you need to understand before you can -get started. - -\section{The Basics - \label{dnt-basics}} - -The Python runtime sees all Python objects as variables of type -\ctype{PyObject*}. A \ctype{PyObject} is not a very magnificent -object - it just contains the refcount and a pointer to the object's -``type object''. This is where the action is; the type object -determines which (C) functions get called when, for instance, an -attribute gets looked up on an object or it is multiplied by another -object. I call these C functions ``type methods'' to distinguish them -from things like \code{[].append} (which I will call ``object -methods'' when I get around to them). - -So, if you want to define a new object type, you need to create a new -type object. - -This sort of thing can only be explained by example, so here's a -minimal, but complete, module that defines a new type: - -\begin{verbatim} -#include - -staticforward PyTypeObject noddy_NoddyType; - -typedef struct { - PyObject_HEAD -} noddy_NoddyObject; - -static PyObject* -noddy_new_noddy(PyObject* self, PyObject* args) -{ - noddy_NoddyObject* noddy; - - if (!PyArg_ParseTuple(args,":new_noddy")) - return NULL; - - noddy = PyObject_New(noddy_NoddyObject, &noddy_NoddyType); - - return (PyObject*)noddy; -} - -static void -noddy_noddy_dealloc(PyObject* self) -{ - PyObject_Del(self); -} - -static PyTypeObject noddy_NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, - "Noddy", - sizeof(noddy_NoddyObject), - 0, - noddy_noddy_dealloc, /*tp_dealloc*/ - 0, /*tp_print*/ - 0, /*tp_getattr*/ - 0, /*tp_setattr*/ - 0, /*tp_compare*/ - 0, /*tp_repr*/ - 0, /*tp_as_number*/ - 0, /*tp_as_sequence*/ - 0, /*tp_as_mapping*/ - 0, /*tp_hash */ -}; - -static PyMethodDef noddy_methods[] = { - { "new_noddy", noddy_new_noddy, METH_VARARGS }, - {NULL, NULL} -}; - -DL_EXPORT(void) -initnoddy(void) -{ - noddy_NoddyType.ob_type = &PyType_Type; - - Py_InitModule("noddy", noddy_methods); -} -\end{verbatim} - -Now that's quite a bit to take in at once, but hopefully bits will -seem familiar from the last chapter. - -The first bit that will be new is: - -\begin{verbatim} -staticforward PyTypeObject noddy_NoddyType; -\end{verbatim} - -This names the type object that will be defining further down in the -file. It can't be defined here because its definition has to refer to -functions that have no yet been defined, but we need to be able to -refer to it, hence the declaration. - -The \code{staticforward} is required to placate various brain dead -compilers. - -\begin{verbatim} -typedef struct { - PyObject_HEAD -} noddy_NoddyObject; -\end{verbatim} - -This is what a Noddy object will contain. In this case nothing more -than every Python object contains - a refcount and a pointer to a type -object. These are the fields the \code{PyObject_HEAD} macro brings -in. The reason for the macro is to standardize the layout and to -enable special debugging fields to be brought in debug builds. - -For contrast - -\begin{verbatim} -typedef struct { - PyObject_HEAD - long ob_ival; -} PyIntObject; -\end{verbatim} - -is the corresponding definition for standard Python integers. - -Next up is: - -\begin{verbatim} -static PyObject* -noddy_new_noddy(PyObject* self, PyObject* args) -{ - noddy_NoddyObject* noddy; - - if (!PyArg_ParseTuple(args,":new_noddy")) - return NULL; - - noddy = PyObject_New(noddy_NoddyObject, &noddy_NoddyType); - - return (PyObject*)noddy; -} -\end{verbatim} - -This is in fact just a regular module function, as described in the -last chapter. The reason it gets special mention is that this is -where we create our Noddy object. Defining PyTypeObject structures is -all very well, but if there's no way to actually \textit{create} one -of the wretched things it is not going to do anyone much good. - -Almost always, you create objects with a call of the form: - -\begin{verbatim} -PyObject_New(, &); -\end{verbatim} - -This allocates the memory and then initializes the object (i.e.\ sets -the reference count to one, makes the \cdata{ob_type} pointer point at -the right place and maybe some other stuff, depending on build options). -You \emph{can} do these steps separately if you have some reason to ---- but at this level we don't bother. - -We cast the return value to a \ctype{PyObject*} because that's what -the Python runtime expects. This is safe because of guarantees about -the layout of structures in the C standard, and is a fairly common C -programming trick. One could declare \cfunction{noddy_new_noddy} to -return a \ctype{noddy_NoddyObject*} and then put a cast in the -definition of \cdata{noddy_methods} further down the file --- it -doesn't make much difference. - -Now a Noddy object doesn't do very much and so doesn't need to -implement many type methods. One you can't avoid is handling -deallocation, so we find - -\begin{verbatim} -static void -noddy_noddy_dealloc(PyObject* self) -{ - PyObject_Del(self); -} -\end{verbatim} - -This is so short as to be self explanatory. This function will be -called when the reference count on a Noddy object reaches \code{0} (or -it is found as part of an unreachable cycle by the cyclic garbage -collector). \cfunction{PyObject_Del()} is what you call when you want -an object to go away. If a Noddy object held references to other -Python objects, one would decref them here. - -Moving on, we come to the crunch --- the type object. - -\begin{verbatim} -static PyTypeObject noddy_NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, - "Noddy", - sizeof(noddy_NoddyObject), - 0, - noddy_noddy_dealloc, /*tp_dealloc*/ - 0, /*tp_print*/ - 0, /*tp_getattr*/ - 0, /*tp_setattr*/ - 0, /*tp_compare*/ - 0, /*tp_repr*/ - 0, /*tp_as_number*/ - 0, /*tp_as_sequence*/ - 0, /*tp_as_mapping*/ - 0, /*tp_hash */ -}; -\end{verbatim} - -Now if you go and look up the definition of \ctype{PyTypeObject} in -\file{object.h} you'll see that it has many, many more fields that the -definition above. The remaining fields will be filled with zeros by -the C compiler, and it's common practice to not specify them -explicitly unless you need them. - -This is so important that I'm going to pick the top of it apart still -further: - -\begin{verbatim} - PyObject_HEAD_INIT(NULL) -\end{verbatim} - -This line is a bit of a wart; what we'd like to write is: - -\begin{verbatim} - PyObject_HEAD_INIT(&PyType_Type) -\end{verbatim} - -as the type of a type object is ``type'', but this isn't strictly -conforming C and some compilers complain. So instead we fill in the -\cdata{ob_type} field of \cdata{noddy_NoddyType} at the earliest -oppourtunity --- in \cfunction{initnoddy()}. - -\begin{verbatim} - 0, -\end{verbatim} - -XXX why does the type info struct start PyObject_*VAR*_HEAD?? - -\begin{verbatim} - "Noddy", -\end{verbatim} - -The name of our type. This will appear in the default textual -representation of our objects and in some error messages, for example: - -\begin{verbatim} ->>> "" + noddy.new_noddy() -Traceback (most recent call last): - File "", line 1, in ? -TypeError: cannot add type "Noddy" to string -\end{verbatim} - -\begin{verbatim} - sizeof(noddy_NoddyObject), -\end{verbatim} - -This is so that Python knows how much memory to allocate when you call -\cfunction{PyObject_New}. - -\begin{verbatim} - 0, -\end{verbatim} - -This has to do with variable length objects like lists and strings. -Ignore for now... - -Now we get into the type methods, the things that make your objects -different from the others. Of course, the Noddy object doesn't -implement many of these, but as mentioned above you have to implement -the deallocation function. - -\begin{verbatim} - noddy_noddy_dealloc, /*tp_dealloc*/ -\end{verbatim} - -From here, all the type methods are nil so I won't go over them yet - -that's for the next section! - -Everything else in the file should be familiar, except for this line -in \cfunction{initnoddy}: - -\begin{verbatim} - noddy_NoddyType.ob_type = &PyType_Type; -\end{verbatim} - -This was alluded to above --- the \cdata{noddy_NoddyType} object should -have type ``type'', but \code{\&PyType_Type} is not constant and so -can't be used in its initializer. To work around this, we patch it up -in the module initialization. - -That's it! All that remains is to build it; put the above code in a -file called \file{noddymodule.c} and - -\begin{verbatim} -from distutils.core import setup, Extension -setup(name = "noddy", version = "1.0", - ext_modules = [Extension("noddy", ["noddymodule.c"])]) -\end{verbatim} - -in a file called \file{setup.py}; then typing - -\begin{verbatim} -$ python setup.py build%$ -\end{verbatim} - -at a shell should produce a file \file{noddy.so} in a subdirectory; -move to that directory and fire up Python --- you should be able to -\code{import noddy} and play around with Noddy objects. - -That wasn't so hard, was it? - -\section{Type Methods - \label{dnt-type-methods}} - -This section aims to give a quick fly-by on the various type methods -you can implement and what they do. - -Here is the definition of \ctype{PyTypeObject}, with some fields only -used in debug builds omitted: - -\begin{verbatim} -typedef struct _typeobject { - PyObject_VAR_HEAD - char *tp_name; /* For printing */ - int tp_basicsize, tp_itemsize; /* For allocation */ - - /* Methods to implement standard operations */ - - destructor tp_dealloc; - printfunc tp_print; - getattrfunc tp_getattr; - setattrfunc tp_setattr; - cmpfunc tp_compare; - reprfunc tp_repr; - - /* Method suites for standard classes */ - - PyNumberMethods *tp_as_number; - PySequenceMethods *tp_as_sequence; - PyMappingMethods *tp_as_mapping; - - /* More standard operations (here for binary compatibility) */ - - hashfunc tp_hash; - ternaryfunc tp_call; - reprfunc tp_str; - getattrofunc tp_getattro; - setattrofunc tp_setattro; - - /* Functions to access object as input/output buffer */ - PyBufferProcs *tp_as_buffer; - - /* Flags to define presence of optional/expanded features */ - long tp_flags; - - char *tp_doc; /* Documentation string */ - - /* call function for all accessible objects */ - traverseproc tp_traverse; - - /* delete references to contained objects */ - inquiry tp_clear; - - /* rich comparisons */ - richcmpfunc tp_richcompare; - - /* weak reference enabler */ - long tp_weaklistoffset; - -} PyTypeObject; -\end{verbatim} - -Now that's a \emph{lot} of methods. Don't worry too much though - if -you have a type you want to define, the chances are very good that you -will only implement a handful of these. - -As you probably expect by now, I'm going to go over this line-by-line, -saying a word about each field as we get to it. - -\begin{verbatim} - char *tp_name; /* For printing */ -\end{verbatim} - -The name of the type - as mentioned in the last section, this will -appear in various places, almost entirely for diagnostic purposes. -Try to choose something that will be helpful in such a situation! - -\begin{verbatim} - int tp_basicsize, tp_itemsize; /* For allocation */ -\end{verbatim} - -These fields tell the runtime how much memory to allocate when new -objects of this typed are created. Python has some builtin support -for variable length structures (think: strings, lists) which is where -the \cdata{tp_itemsize} field comes in. This will be dealt with -later. - -Now we come to the basic type methods - the ones most extension types -will implement. - -\begin{verbatim} - destructor tp_dealloc; - printfunc tp_print; - getattrfunc tp_getattr; - setattrfunc tp_setattr; - cmpfunc tp_compare; - reprfunc tp_repr; -\end{verbatim} - - -%\section{Attributes \& Methods -% \label{dnt-attrs-and-meths}} - - \chapter{Building C and \Cpp{} Extensions on \UNIX{} - \label{building-on-unix}} + \label{building-on-unix}} \sectionauthor{Jim Fulton}{jim@Digicool.com} @@ -2175,7 +1764,7 @@ The make file make file, \file{Makefile.pre.in} uses metadata provided in a file named \file{Setup}. The format of the \file{Setup} -file is the same as the \file{Setup} (or \file{Setup.dist}) file +file is the same as the \file{Setup} (or \file{Setup.in}) file provided in the \file{Modules/} directory of the Python source distribution. The \file{Setup} file contains variable definitions: @@ -2262,17 +1851,17 @@ make static \end{verbatim} -Any modules defined in the \file{Setup} file before the -\samp{*shared*} line will be statically linked into the interpreter. -Typically, a \samp{*shared*} line is omitted from the -\file{Setup} file when a custom interpreter is desired. +Any modules defined in the Setup file before the \samp{*shared*} line +will be statically linked into the interpreter. Typically, a +\samp{*shared*} line is omitted from the Setup file when a custom +interpreter is desired. \section{Module Definition Options \label{module-defn-options}} Several compiler options are supported: -\begin{tableii}{l|l}{programopt}{Option}{Meaning} +\begin{tableii}{l|l}{}{Option}{Meaning} \lineii{-C}{Tell the C pre-processor not to discard comments} \lineii{-D\var{name}=\var{value}}{Define a macro} \lineii{-I\var{dir}}{Specify an include directory, \var{dir}} @@ -2294,7 +1883,7 @@ \section{Example \label{module-defn-example}} -Here is a more complicated example from \file{Modules/Setup.dist}: +Here is a more complicated example from \file{Modules/Setup.in}: \begin{verbatim} GMP=/ufs/guido/src/gmp @@ -2309,25 +1898,12 @@ \section{Distributing your extension modules - \label{distributing}} - -There are two ways to distribute extension modules for others to use. -The way that allows the easiest cross-platform support is to use the -\module{distutils}\refstmodindex{distutils} package. The manual -\citetitle[../dist/dist.html]{Distributing Python Modules} contains -information on this approach. It is recommended that all new -extensions be distributed using this approach to allow easy building -and installation across platforms. Older extensions should migrate to -this approach as well. - -What follows describes the older approach; there are still many -extensions which use this. + \label{distributing}} When distributing your extension modules in source form, make sure to include a \file{Setup} file. The \file{Setup} file should be named \file{Setup.in} in the distribution. The make file make file, -\file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup} if -the person installing the extension doesn't do so manually. +\file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup}. Distributing a \file{Setup.in} file makes it easy for people to customize the \file{Setup} file while keeping the original in \file{Setup.in}. @@ -2340,9 +1916,16 @@ \file{README} file included in the package should provide simple instructions to perform the build. +Work is being done to make building and installing Python extensions +easier for all platforms; this work in likely to supplant the current +approach at some point in the future. For more information or to +participate in the effort, refer to +\url{http://www.python.org/sigs/distutils-sig/} on the Python Web +site. + \chapter{Building C and \Cpp{} Extensions on Windows - \label{building-on-windows}} + \label{building-on-windows}} This chapter briefly explains how to create a Windows extension module @@ -2395,13 +1978,13 @@ MyObject_Type.ob_type = &PyType_Type; \end{verbatim} -Refer to section 3 of the -\citetitle[http://www.python.org/doc/FAQ.html]{Python FAQ} for details -on why you must do this. +Refer to section 3 of the Python FAQ +(\url{http://www.python.org/doc/FAQ.html}) for details on why you must +do this. \section{Differences Between \UNIX{} and Windows - \label{dynamic-linking}} + \label{dynamic-linking}} \sectionauthor{Chris Phoenix}{cphoenix@best.com} @@ -2495,7 +2078,7 @@ \chapter{Embedding Python in Another Application - \label{embedding}} + \label{embedding}} Embedding Python is similar to extending it, but not quite. The difference is that when you extend Python, the main program of the @@ -2525,7 +2108,7 @@ \section{Embedding Python in \Cpp{} - \label{embeddingInCplusplus}} + \label{embeddingInCplusplus}} It is also possible to embed Python in a \Cpp{} program; precisely how this is done will depend on the details of the \Cpp{} system used; in general you @@ -2559,7 +2142,7 @@ \begin{verbatim} >>> import distutils.sysconfig ->>> distutils.sysconfig.get_config_var('LINKFORSHARED') +>>> distutils.sysconfig.LINKFORSHARED '-Xlinker -export-dynamic' \end{verbatim} \refstmodindex{distutils.sysconfig} Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: Makefile diff -ru main/contrib/python-2.0/dist/src/Doc/html/about.html main/Apps/ActivePython-2.0/src/Core/Doc/html/about.html --- main/contrib/python-2.0/dist/src/Doc/html/about.html Mon Mar 12 16:11:28 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/html/about.html Mon Mar 12 16:10:18 2001 @@ -11,26 +11,26 @@
- - - - -
up About the Python Documentation
Up: - + Python Documentation Index
@@ -48,6 +48,12 @@

A list of contributors is available.

Comments and Questions

+ +

Comments on the ActivePython distribution should be directed to + ActivePython@ActiveState.com. + For the latest news on ActivePython, visit the ActivePython homepage at + www.ActiveState.com/Products/ActivePython. +

General comments and questions regarding this document should be sent by email to Python @RELEASE@ Documentation - @DATE@ - - - +

- - - - - - -
+ Python DocumentationModule Index
Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.aux Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.dvi Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.how Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.l2h Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.log Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: inst.toc Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.aux Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.dvi Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.how Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.l2h Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.log Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib.toc Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib2.syn Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: lib3.syn Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.aux Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.dvi Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.how Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.l2h Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.log Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.pla Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac.toc Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac2.syn Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac3.syn Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: mac4.syn Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modapi.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: moddist.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: moddoc.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modext.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modinst.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modlib.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modlib.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modmac.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modmac.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modref.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: modtut.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.aux Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.dvi Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.how Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.idx Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.l2h Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.log Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: ref.toc diff -ru main/contrib/python-2.0/dist/src/Doc/html/stdabout.dat main/Apps/ActivePython-2.0/src/Core/Doc/html/stdabout.dat --- main/contrib/python-2.0/dist/src/Doc/html/stdabout.dat Mon Mar 12 16:11:28 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/html/stdabout.dat Mon Mar 12 16:10:18 2001 @@ -27,6 +27,12 @@

Comments and Questions

+

Comments on the ActivePython distribution should be directed to + ActivePython@ActiveState.com. + For the latest news on ActivePython, visit the ActivePython homepage at + www.ActiveState.com/Products/ActivePython. +

+

General comments and questions regarding this document should be sent by email to python-docs@python.org. If you find specific errors in diff -ru main/contrib/python-2.0/dist/src/Doc/html/style.css main/Apps/ActivePython-2.0/src/Core/Doc/html/style.css --- main/contrib/python-2.0/dist/src/Doc/html/style.css Mon Mar 12 16:11:28 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/html/style.css Mon Mar 12 16:10:18 2001 @@ -3,12 +3,9 @@ * with the "empty" declarations removed. */ -/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ -.math { font-family: "Century Schoolbook", serif; } -.math i { font-family: "Century Schoolbook", serif; - font-weight: bold } -.boldmath { font-family: "Century Schoolbook", serif; - font-weight: bold } +.math { font-family: serif; } +.math i { font-family: serif; font-weight: bold } +.boldmath { font-family: serif; font-weight: bold } /* Implement both fixed-size and relative sizes: */ small.xtiny { font-size : xx-small } @@ -28,56 +25,33 @@ * Netscape on Solaris otherwise doesn't get it right; they all end up * the normal text size. */ +a:link { color:#B82619; } +a:visited { color:#C2B266; } +a:active { color: #000000; } +body { font-family: verdana, arial, helvetica, sans-serif; font-size: small; } +h1, h2, h3, h4, h5, h6 { font-family: verdana, arial, helvetica, sans-serif; font-weight: bold; } +h1 { font-size: 180% } +h2 { font-size: 150% } +h3, h4 { font-size: 120% } +code, tt { font-family: monospace } +var { font-family: serif; font-style: italic; font-weight: normal } -body { color: #000000; - background-color: #ffffff; } +.navigation { font-family: verdana, arial, helvetica, sans-serif; font-size: 110% } -a:active { color: #ff0000; } -a:visited { color: #551a8b; } -a:link { color: #0000bb; } - -h1, h2, h3, h4, h5, h6 { font-family: avantgarde, sans-serif; - font-weight: bold } -h1 { font-size: 180% } -h2 { font-size: 150% } -h3, h4 { font-size: 120% } -code, tt { font-family: monospace } -var { font-family: serif; - font-style: italic; - font-weight: normal } - -.navigation td { background-color: #99ccff; - font-weight: bold; - font-family: avantgarde, sans-serif; - font-size: 110% } - -.release-info { font-style: italic; } - -.titlegraphic { vertical-align: top; } +.title { font-family: verdana, arial, helvetica, sans-serif; font-size: 110% } .verbatim { color: #00008b } -.email { font-family: avantgarde, sans-serif } -.mimetype { font-family: avantgarde, sans-serif } -.newsgroup { font-family: avantgarde, sans-serif } -.url { font-family: avantgarde, sans-serif } -.file { font-family: avantgarde, sans-serif } - -.tableheader { background-color: #99ccff; - font-family: avantgarde, sans-serif; } +.email { font-family: verdana, arial, helvetica, sans-serif } +.mimetype { font-family: verdana, arial, helvetica, sans-serif } +.newsgroup { font-family: verdana, arial, helvetica, sans-serif } +.url { font-family: verdana, arial, helvetica, sans-serif } +.file { font-family: verdana, arial, helvetica, sans-serif } .refcount-info { font-style: italic } -.refcount-info .value { font-weight: bold; - color: #006600 } +.refcount-info .value { font-weight: bold; color: #006600 } -/* - * Some decoration for the "See also:" blocks, in part inspired by some of - * the styling on Lars Marius Garshol's XSA pages. - * (The blue in the navigation bars is #99CCFF.) - */ -.seealso { background-color: #fffaf0; - border: thin solid black; - padding: 4pt } +.seealso { background-color: #EAE2BB; border: thin solid black; padding: 4pt } .seealso .heading { font-size: 110% } Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.aux Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.dvi Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.how Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.ind Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.l2h Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.log Only in main/Apps/ActivePython-2.0/src/Core/Doc/html: tut.toc Only in main/contrib/python-2.0/dist/src/Doc: icons diff -ru main/contrib/python-2.0/dist/src/Doc/info/Makefile main/Apps/ActivePython-2.0/src/Core/Doc/info/Makefile --- main/contrib/python-2.0/dist/src/Doc/info/Makefile Mon Mar 12 16:11:28 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/info/Makefile Mon Mar 12 16:10:18 2001 @@ -1,7 +1,9 @@ # Generate the Python "info" documentation. +PAPER=letter TOPDIR=.. TOOLSDIR=$(TOPDIR)/tools +PAPERDIR=$(TOPDIR)/paper-$(PAPER) HTMLDIR=$(TOPDIR)/html MKINFO=$(TOOLSDIR)/mkinfo @@ -9,8 +11,7 @@ $(TOOLSDIR)/fixinfo.el all: python-api.info python-ext.info python-lib.info \ - python-ref.info python-tut.info \ - python-dist.info python-inst.info + python-ref.info python-tut.info python-api.info: $(HTMLDIR)/api/api.html $(SCRIPTS) @@ -32,11 +33,6 @@ python-tut.info: $(HTMLDIR)/tut/tut.html $(SCRIPTS) $(MKINFO) $< -python-dist.info: $(HTMLDIR)/dist/dist.html $(SCRIPTS) - $(MKINFO) $< - -python-inst.info: $(HTMLDIR)/inst/inst.html $(SCRIPTS) - $(MKINFO) $< clean: rm -f *.texi~ *.texi @@ -45,29 +41,42 @@ rm -f *.texi python-*.info python-*.info-[0-9]* -# This makes sure we can build info files from a "clean" tree, -# in case we haven't already built the HTML: +# The HTML files are dependent on the .aux files, which are dependent on the +# LaTeX source documents. This makes sure we can build info files from a +# "clean" tree: + +$(HTMLDIR)/api/api.html: $(PAPERDIR)/api.aux $(BUILDINDEX) + (cd $(TOPDIR); $(MAKE) htmlapi) + +$(HTMLDIR)/ext/ext.html: $(PAPERDIR)/ext.aux + (cd $(TOPDIR); $(MAKE) htmlext) + +$(HTMLDIR)/lib/lib.html: $(PAPERDIR)/lib.aux $(BUILDINDEX) + (cd $(TOPDIR); $(MAKE) htmllib) + +$(HTMLDIR)/mac/mac.html: $(MACFILES) $(BUILDINDEX) + (cd $(TOPDIR); $(MAKE) htmlmac) + +$(HTMLDIR)/ref/ref.html: $(PAPERDIR)/ref.aux $(BUILDINDEX) + (cd $(TOPDIR); $(MAKE) htmlref) -$(HTMLDIR)/api/api.html: - (cd $(HTMLDIR); $(MAKE) api) +$(HTMLDIR)/tut/tut.html: $(PAPERDIR)/tut.aux + (cd $(TOPDIR); $(MAKE) htmltut) -$(HTMLDIR)/ext/ext.html: - (cd $(HTMLDIR); $(MAKE) ext) -$(HTMLDIR)/lib/lib.html: - (cd $(HTMLDIR); $(MAKE) lib) +include ../Makefile.deps -$(HTMLDIR)/mac/mac.html: - (cd $(HTMLDIR); $(MAKE) mac) +$(PAPERDIR)/api.aux: $(APIFILES) + (cd $(PAPERDIR); $(MAKE) PAPER=$(PAPER) api.dvi) -$(HTMLDIR)/ref/ref.html: - (cd $(HTMLDIR); $(MAKE) ref) +$(PAPERDIR)/ext.aux: $(EXTFILES) + (cd $(PAPERDIR); $(MAKE) PAPER=$(PAPER) ext.dvi) -$(HTMLDIR)/tut/tut.html: - (cd $(HTMLDIR); $(MAKE) tut) +$(PAPERDIR)/lib.aux: $(LIBFILES) + (cd $(PAPERDIR); $(MAKE) PAPER=$(PAPER) lib.dvi) -$(HTMLDIR)/dist/dist.html: - (cd $(HTMLDIR); $(MAKE) dist) +$(PAPERDIR)/ref.aux: $(REFFILES) + (cd $(PAPERDIR); $(MAKE) PAPER=$(PAPER) ref.dvi) -$(HTMLDIR)/inst/inst.html: - (cd $(HTMLDIR); $(MAKE) inst) +$(PAPERDIR)/tut.aux: $(TUTFILES) + (cd $(PAPERDIR); $(MAKE) PAPER=$(PAPER) tut.dvi) diff -ru main/contrib/python-2.0/dist/src/Doc/inst/inst.tex main/Apps/ActivePython-2.0/src/Core/Doc/inst/inst.tex --- main/contrib/python-2.0/dist/src/Doc/inst/inst.tex Mon Mar 12 16:11:28 2001 +++ main/Apps/ActivePython-2.0/src/Core/Doc/inst/inst.tex Mon Mar 12 16:10:18 2001 @@ -1,4 +1,6 @@ \documentclass{howto} +\usepackage{ltxmarkup} +\usepackage{times} \usepackage{distutils} \title{Installing Python Modules} @@ -41,14 +43,7 @@ %Abstract this! %\end{abstract} - -% The ugly "%begin{latexonly}" pseudo-environment supresses the table -% of contents for HTML generation. -% -%begin{latexonly} \tableofcontents -%end{latexonly} - \section{Introduction} \label{intro} @@ -120,7 +115,6 @@ setup script \file{setup.py}, and a \file{README.txt} (or possibly \file{README}), which should explain that building and installing the module distribution is a simple matter of running - \begin{verbatim} python setup.py install \end{verbatim} @@ -146,20 +140,20 @@ are already familiar with how the Python library is laid out on their platform, and know where to copy various files in order for Python to find them. This document makes no such assumptions, and explains how -the Python library is laid out on three major platforms (\UNIX, Windows, -and MacOS), so that you can understand what happens when the Distutils +the Python library is laid out on three major platforms (Unix, Windows, +and Mac~OS), so that you can understand what happens when the Distutils do their job \emph{and} know how to install modules manually when the module author fails to provide a setup script. Additionally, while there has not previously been a standard installation mechanism, Python has had some standard machinery for -building extensions on \UNIX{} since Python 1.4. This -machinery (the \file{Makefile.pre.in} file) is superseded by the -Distutils, but it will no doubt live on in older module distributions -for a while. This \file{Makefile.pre.in} mechanism is documented in -the \citetitle[../ext/ext.html]{Extending \& Embedding Python} manual, -but that manual is aimed at module developers---hence, we include -documentation for builders/installers here. +building extensions on Unix since Python \XXX{version?}. This machinery +(the \file{Makefile.pre.in} file) is superseded by the Distutils, but it +will no doubt live on in older module distributions for a while. This +\file{Makefile.pre.in} mechanism is documented in the ``Extending \& +Embedding Python'' manual, but that manual is aimed at module +developers---hence, we include documentation for builders/installers +here. All of the pre-Distutils material is tucked away in section~\ref{pre-distutils}. @@ -170,14 +164,12 @@ As described in section~\ref{new-standard}, building and installing a module distribution using the Distutils is usually one simple command: - \begin{verbatim} python setup.py install \end{verbatim} - -On \UNIX, you'd run this command from a shell prompt; on Windows, you +On Unix, you'd run this command from a shell prompt; on Windows, you have to open a command prompt window (``DOS box'') and do it there; on -MacOS, things are a tad more complicated (see below). +Mac~OS, things are a tad more complicated (see below). \subsection{Platform variations} @@ -186,9 +178,8 @@ You should always run the setup command from the distribution root directory, i.e. the top-level subdirectory that the module source distribution unpacks into. For example, if you've just downloaded a -module source distribution \file{foo-1.0.tar.gz} onto a -\UNIX{} system, the normal thing to do is: - +module source distribution \file{foo-1.0.tar.gz} onto a Unix system, the +normal thing to do is: \begin{verbatim} gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 cd foo-1.0 @@ -202,13 +193,12 @@ command-line tool (such as \program{unzip} or \program{pkunzip}) to unpack the archive. Then, open a command prompt window (``DOS box''), and run: - \begin{verbatim} cd c:\Temp\foo-1.0 python setup.py install \end{verbatim} -On MacOS, you have to go through a bit more effort to supply +On Mac~OS, you have to go through a bit more effort to supply command-line arguments to the setup script: \begin{itemize} \item hit option-double-click on the script's icon (or option-drop it @@ -219,9 +209,8 @@ voluminous and often useful) \item when the command-line dialog pops up, enter ``install'' (you can, of course, enter any Distutils command-line as described in this - document or in \citetitle[../dist/dist.html]{Distributing Python - Modules}: just leave off the initial \code{python setup.py} and - you'll be fine) + document or in the ``Distributing Python Modules'' document: just + leave of the initial \code{python setup.py} and you'll be fine) \end{itemize} \XXX{this should change: every Distutils setup script will need command-line arguments for every run (and should probably keep stdout @@ -242,12 +231,10 @@ For example, you can build everything in one step, and then install everything in a second step, by invoking the setup script twice: - \begin{verbatim} python setup.py build python setup.py install \end{verbatim} - (If you do this, you will notice that running the \command{install} command first runs the \command{build} command, which---in this case---quickly notices that it has nothing to do, since everything in @@ -269,33 +256,29 @@ concerned with speed, or want to keep the source tree pristine, you can change the build directory with the \longprogramopt{build-base} option. For example: - \begin{verbatim} python setup.py build --build-base=/tmp/pybuild/foo-1.0 \end{verbatim} - (Or you could do this permanently with a directive in your system or personal Distutils configuration file; see section~\ref{config-files}.) Normally, this isn't necessary. The default layout for the build tree is as follows: - \begin{verbatim} --- build/ --- lib/ or --- build/ --- lib./ temp./ \end{verbatim} - where \code{} expands to a brief description of the current -OS/hardware platform and Python version. The first form, with just a -\file{lib} directory, is used for ``pure module distributions''---that -is, module distributions that include only pure Python modules. If a -module distribution contains any extensions (modules written in C/\Cpp), -then the second form, with two \code{} directories, is used. In -that case, the \file{temp.\filevar{plat}} directory holds temporary -files generated by the compile/link process that don't actually get -installed. In either case, the \file{lib} (or +OS/hardware platform. The first form, with just a \file{lib} directory, +is used for ``pure module distributions''---that is, module +distributions that include only pure Python modules. If a module +distribution contains any extensions (modules written in C/C++, or Java +for JPython), then the second form, with two \code{} directories, +is used. In that case, the \file{temp.\filevar{plat}} directory holds +temporary files generated by the compile/link process that don't +actually get installed. In either case, the \file{lib} (or \file{lib.\filevar{plat}}) directory contains all Python modules (pure Python and extensions) that will be installed. @@ -317,15 +300,15 @@ \code{setup.py install}---then the \command{install} command installs to the standard location for third-party Python modules. This location varies by platform and by how you built/installed Python itself. On -\UNIX{} and MacOS, it also depends on whether the module distribution +Unix and Mac OS, it also depends on whether the module distribution being installed is pure Python or contains extensions (``non-pure''): \begin{tableiv}{l|l|l|c}{textrm}% {Platform}{Standard installation location}{Default value}{Notes} - \lineiv{\UNIX{} (pure)} + \lineiv{Unix (pure)} {\filenq{\filevar{prefix}/lib/python2.0/site-packages}} {\filenq{/usr/local/lib/python2.0/site-packages}} {(1)} - \lineiv{\UNIX{} (non-pure)} + \lineiv{Unix (non-pure)} {\filenq{\filevar{exec-prefix}/lib/python2.0/site-packages}} {\filenq{/usr/local/lib/python2.0/site-packages}} {(1)} @@ -333,13 +316,13 @@ {\filenq{\filevar{prefix}}} {\filenq{C:\textbackslash{}Python}} {(2)} - \lineiv{MacOS (pure)} - {\filenq{\filevar{prefix}:Lib:site-packages}} - {\filenq{Python:Lib:site-packages}} + \lineiv{Mac~OS (pure)} + {\filenq{\filevar{prefix}:Lib}} + {\filenq{Python:Lib} \XXX{???}} {} - \lineiv{MacOS (non-pure)} - {\filenq{\filevar{prefix}:Lib:site-packages}} - {\filenq{Python:Lib:site-packages}} + \lineiv{Mac~OS (non-pure)} + {\filevar{prefix}:Mac:PlugIns} + {\filenq{Python:Mac:PlugIns}\XXX{???}} {} \end{tableiv} @@ -348,7 +331,7 @@ \item[(1)] Most Linux distributions include Python as a standard part of the system, so \filevar{prefix} and \filevar{exec-prefix} are usually both \file{/usr} on Linux. If you build Python yourself on Linux (or - any \UNIX-like system), the default \filevar{prefix} and + any Unix-like system), the default \filevar{prefix} and \filevar{exec-prefix} are \file{/usr/local}. \item[(2)] The default installation directory on Windows was \file{C:\textbackslash{}Program Files\textbackslash{}Python} under @@ -357,12 +340,12 @@ \filevar{prefix} and \filevar{exec-prefix} stand for the directories that Python is installed to, and where it finds its libraries at -run-time. They are always the same under Windows and MacOS, and very -