diff options
Diffstat (limited to 'Doc')
92 files changed, 4930 insertions, 1422 deletions
@@ -190,6 +190,7 @@ Eddy Welbourne Mats Wichmann Gerry Wiener Timothy Wild +Collin Winter Blake Winton Dan Wolfe Steven Work diff --git a/Doc/Makefile b/Doc/Makefile index 0d391af..a435f11 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -691,7 +691,7 @@ distlatex: bziplatex ziplatex # The small amount of additional work is a small price to pay for not # having to remember which order to do it in. ;) paperdist: distpdf distps pkglist -edist: disthtml distinfo zipisilo pkglist +edist: disthtml pkglist # The pkglist.html file is used as part of the download.html page on # python.org; it is not used as intermediate input here or as part of diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index 2fc3250..f828e1b 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -270,6 +270,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ lib/xmlsaxhandler.tex \ lib/xmlsaxutils.tex \ lib/xmlsaxreader.tex \ + lib/libetree.tex \ lib/libqueue.tex \ lib/liblocale.tex \ lib/libgettext.tex \ diff --git a/Doc/api/api.tex b/Doc/api/api.tex index 6fa8c41..cf28f5b 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -48,11 +48,6 @@ code releases.} \input{newtypes} -% \chapter{Debugging \label{debugging}} -% -% XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG. - - \appendix \chapter{Reporting Bugs} \input{reportingbugs} diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 10247ab..4c7487c 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -31,7 +31,7 @@ This section describes Python type objects and the singleton object \begin{cvardesc}{PyObject*}{PyType_Type} This is the type object for type objects; it is the same object as - \code{types.TypeType} in the Python layer. + \code{type} and \code{types.TypeType} in the Python layer. \withsubitem{(in module types)}{\ttindex{TypeType}} \end{cvardesc} @@ -117,7 +117,8 @@ There is no \cfunction{PyNone_Check()} function for the same reason. \begin{cvardesc}{PyTypeObject}{PyInt_Type} This instance of \ctype{PyTypeObject} represents the Python plain - integer type. This is the same object as \code{types.IntType}. + integer type. This is the same object as \code{int} and + \code{types.IntType}. \withsubitem{(in modules types)}{\ttindex{IntType}} \end{cvardesc} @@ -260,7 +261,8 @@ booleans. The following macros are available, however. \begin{cvardesc}{PyTypeObject}{PyLong_Type} This instance of \ctype{PyTypeObject} represents the Python long - integer type. This is the same object as \code{types.LongType}. + integer type. This is the same object as \code{long} and + \code{types.LongType}. \withsubitem{(in modules types)}{\ttindex{LongType}} \end{cvardesc} @@ -376,7 +378,7 @@ booleans. The following macros are available, however. \versionadded{2.3} \end{cfuncdesc} -\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongLongMask}{PyObject *io} +\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io} Return a C \ctype{unsigned long long} from a Python long integer, without checking for overflow. \versionadded{2.3} @@ -411,7 +413,8 @@ booleans. The following macros are available, however. \begin{cvardesc}{PyTypeObject}{PyFloat_Type} This instance of \ctype{PyTypeObject} represents the Python floating - point type. This is the same object as \code{types.FloatType}. + point type. This is the same object as \code{float} and + \code{types.FloatType}. \withsubitem{(in modules types)}{\ttindex{FloatType}} \end{cvardesc} @@ -520,7 +523,8 @@ typedef struct { \begin{cvardesc}{PyTypeObject}{PyComplex_Type} This instance of \ctype{PyTypeObject} represents the Python complex - number type. + number type. It is the same object as \code{complex} and + \code{types.ComplexType}. \end{cvardesc} \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} @@ -580,8 +584,8 @@ parameter and are called with a non-string parameter. \begin{cvardesc}{PyTypeObject}{PyString_Type} This instance of \ctype{PyTypeObject} represents the Python string - type; it is the same object as \code{types.TypeType} in the Python - layer. + type; it is the same object as \code{str} and \code{types.StringType} + in the Python layer. \withsubitem{(in module types)}{\ttindex{StringType}}. \end{cvardesc} @@ -850,7 +854,8 @@ Please keep this in mind when writing extensions or interfaces. \begin{cvardesc}{PyTypeObject}{PyUnicode_Type} This instance of \ctype{PyTypeObject} represents the Python Unicode - type. + type. It is exposed to Python code as \code{unicode} and + \code{types.UnicodeType}. \end{cvardesc} The following APIs are really C macros and can be used to do fast @@ -1001,21 +1006,14 @@ use these APIs: const char *errors} Coerce an encoded object \var{obj} to an Unicode object and return a reference with incremented refcount. + + String and other char buffer compatible objects are decoded + according to the given encoding and using the error handling + defined by errors. Both can be \NULL{} to have the interface + use the default values (see the next section for details). - Coercion is done in the following way: - -\begin{enumerate} -\item Unicode objects are passed back as-is with incremented - refcount. \note{These cannot be decoded; passing a non-\NULL{} - value for encoding will result in a \exception{TypeError}.} - -\item String and other char buffer compatible objects are decoded - according to the given encoding and using the error handling - defined by errors. Both can be \NULL{} to have the interface - use the default values (see the next section for details). - -\item All other objects cause an exception. -\end{enumerate} + All other objects, including Unicode objects, cause a + \exception{TypeError} to be set. The API returns \NULL{} if there was an error. The caller is responsible for decref'ing the returned objects. @@ -1431,6 +1429,18 @@ machine running the codec. raised by the codec. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s, + int size, + const char *errors, + int *consumed} + If \var{consumed} is \NULL{}, behave like + \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{}, + \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead + byte and the number of bytes that have been decoded will be stored in + \var{consumed}. + \versionadded{2.5} +\end{cfuncdesc} + \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, Py_ssize_t size, const char *errors} @@ -1618,8 +1628,9 @@ format. \begin{cvardesc}{PyTypeObject}{PyBuffer_Type} The instance of \ctype{PyTypeObject} which represents the Python - buffer type; it is the same object as \code{types.BufferType} in the - Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}. + buffer type; it is the same object as \code{buffer} and + \code{types.BufferType} in the Python layer. + \withsubitem{(in module types)}{\ttindex{BufferType}}. \end{cvardesc} \begin{cvardesc}{int}{Py_END_OF_BUFFER} @@ -1693,8 +1704,8 @@ format. \begin{cvardesc}{PyTypeObject}{PyTuple_Type} This instance of \ctype{PyTypeObject} represents the Python tuple - type; it is the same object as \code{types.TupleType} in the Python - layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. + type; it is the same object as \code{tuple} and \code{types.TupleType} + in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. \end{cvardesc} \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} @@ -1790,8 +1801,8 @@ format. \begin{cvardesc}{PyTypeObject}{PyList_Type} This instance of \ctype{PyTypeObject} represents the Python list - type. This is the same object as \code{types.ListType}. - \withsubitem{(in module types)}{\ttindex{ListType}} + type. This is the same object as \code{list} and \code{types.ListType} + in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}} \end{cvardesc} \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p} @@ -1919,7 +1930,7 @@ format. \begin{cvardesc}{PyTypeObject}{PyDict_Type} This instance of \ctype{PyTypeObject} represents the Python dictionary type. This is exposed to Python programs as - \code{types.DictType} and \code{types.DictionaryType}. + \code{dict} and \code{types.DictType}. \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} \end{cvardesc} @@ -2134,7 +2145,8 @@ implementation detail and may change in future releases of Python. \begin{cvardesc}{PyTypeObject}{PyFile_Type} This instance of \ctype{PyTypeObject} represents the Python file - type. This is exposed to Python programs as \code{types.FileType}. + type. This is exposed to Python programs as \code{file} and + \code{types.FileType}. \withsubitem{(in module types)}{\ttindex{FileType}} \end{cvardesc} @@ -2583,7 +2595,7 @@ They are found in the dictionary of type objects. \begin{cvardesc}{PyTypeObject}{PySlice_Type} The type object for slice objects. This is the same as - \code{types.SliceType}. + \code{slice} and \code{types.SliceType}. \withsubitem{(in module types)}{\ttindex{SliceType}} \end{cvardesc} diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex index 6dbe818..2a9db54 100644 --- a/Doc/api/exceptions.tex +++ b/Doc/api/exceptions.tex @@ -256,10 +256,14 @@ error indicator for each thread. argument. It is mostly for internal use. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} +\begin{cfuncdesc}{int}{PyErr_WarnEx}{PyObject *category, char *message, int stacklevel} Issue a warning message. The \var{category} argument is a warning category (see below) or \NULL; the \var{message} argument is a - message string. + message string. \var{stacklevel} is a positive number giving a + number of stack frames; the warning will be issued from the + currently executing line of code in that stack frame. A \var{stacklevel} + of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is + the function above that, and so forth. This function normally prints a warning message to \var{sys.stderr}; however, it is also possible that the user has specified that @@ -291,6 +295,16 @@ error indicator for each thread. command line documentation. There is no C API for warning control. \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. The warning will appear to be issued from the function + calling \cfunction{PyErr_Warn()}, equivalent to calling + \cfunction{PyErr_WarnEx()} with a \var{stacklevel} of 1. + + Deprecated; use \cfunction{PyErr_WarnEx()} instead. +\end{cfuncdesc} + \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry} diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex index 96f18ec..c2c3fec 100644 --- a/Doc/api/intro.tex +++ b/Doc/api/intro.tex @@ -577,3 +577,59 @@ information about these functions is given in a later chapter. Notice that \cfunction{Py_Finalize} does \emph{not} free all memory allocated by the Python interpreter, e.g. memory allocated by extension modules currently cannot be released. + + +\section{Debugging Builds \label{debugging}} + +Python can be built with several macros to enable extra checks of the +interpreter and extension modules. These checks tend to add a large +amount of overhead to the runtime so they are not enabled by default. + +A full list of the various types of debugging builds is in the file +\file{Misc/SpecialBuilds.txt} in the Python source distribution. +Builds are available that support tracing of reference counts, +debugging the memory allocator, or low-level profiling of the main +interpreter loop. Only the most frequently-used builds will be +described in the remainder of this section. + +Compiling the interpreter with the \csimplemacro{Py_DEBUG} macro +defined produces what is generally meant by "a debug build" of Python. +\csimplemacro{Py_DEBUG} is enabled in the \UNIX{} build by adding +\longprogramopt{with-pydebug} to the \file{configure} command. It is also +implied by the presence of the not-Python-specific +\csimplemacro{_DEBUG} macro. When \csimplemacro{Py_DEBUG} is enabled +in the \UNIX{} build, compiler optimization is disabled. + +In addition to the reference count debugging described below, the +following extra checks are performed: + +\begin{itemize} + \item Extra checks are added to the object allocator. + \item Extra checks are added to the parser and compiler. + \item Downcasts from wide types to narrow types are checked for + loss of information. + \item A number of assertions are added to the dictionary and set + implementations. In addition, the set object acquires a + \method{test_c_api} method. + \item Sanity checks of the input arguments are added to frame + creation. + \item The storage for long ints is initialized with a known + invalid pattern to catch reference to uninitialized + digits. + \item Low-level tracing and extra exception checking are added + to the runtime virtual machine. + \item Extra checks are added to the memory arena implementation. + \item Extra debugging is added to the thread module. +\end{itemize} + +There may be additional checks not mentioned here. + +Defining \csimplemacro{Py_TRACE_REFS} enables reference tracing. When +defined, a circular doubly linked list of active objects is maintained +by adding two extra fields to every \ctype{PyObject}. Total +allocations are tracked as well. Upon exit, all existing references +are printed. (In interactive mode this happens after every statement +run by the interpreter.) Implied by \csimplemacro{Py_DEBUG}. + +Please refer to \file{Misc/SpecialBuilds.txt} in the Python source +distribution for more detailed information. diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat index ab6d865..b8aaad5 100644 --- a/Doc/api/refcounts.dat +++ b/Doc/api/refcounts.dat @@ -303,6 +303,11 @@ PyErr_Warn:int::: PyErr_Warn:PyObject*:category:0: PyErr_Warn:char*:message:: +PyErr_WarnEx:int::: +PyErr_WarnEx:PyObject*:category:0: +PyErr_WarnEx:const char*:message:: +PyErr_WarnEx:Py_ssize_t:stack_level:: + PyEval_AcquireLock:void::: PyEval_AcquireThread:void::: diff --git a/Doc/commontex/boilerplate.tex b/Doc/commontex/boilerplate.tex index b4c9f48..9749432 100644 --- a/Doc/commontex/boilerplate.tex +++ b/Doc/commontex/boilerplate.tex @@ -5,5 +5,5 @@ Email: \email{docs@python.org} } -\date{\today} % XXX update before final release! +\date{3rd August, 2006} % XXX update before final release! \input{patchlevel} % include Python version information diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index e95c0d3..c1b72ad 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -530,7 +530,7 @@ If you need to include header files from some other Python extension, you can take advantage of the fact that header files are installed in a consistent way by the Distutils \command{install\_header} command. For example, the Numerical Python header files are installed (on a standard -Unix installation) to \file{/usr/local/include/python1.5/Numerical}. +\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 case---is always @@ -2317,7 +2317,7 @@ constructor \lineiii{name}{the full name of the extension, including any packages --- ie. \emph{not} a filename or pathname, but Python dotted name}{string} \lineiii{sources}{list of source filenames, relative to the distribution -root (where the setup script lives), in Unix form (slash-separated) for +root (where the setup script lives), in \UNIX{} form (slash-separated) for portability. Source files may be C, \Cpp, SWIG (.i), platform-specific resource files, or whatever else is recognized by the \command{build_ext} command as source for a Python extension.}{string} @@ -2873,9 +2873,20 @@ C compiler: \modulesynopsis{Microsoft Compiler} This module provides \class{MSVCCompiler}, an implementation of the abstract -\class{CCompiler} class for Microsoft Visual Studio. It should also work using -the freely available compiler provided as part of the .Net SDK download. XXX -download link. +\class{CCompiler} class for Microsoft Visual Studio. Typically, extension +modules need to be compiled with the same compiler that was used to compile +Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For +Python 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 +and Itanium binaries are created using the Platform SDK. + +\class{MSVCCompiler} will normally choose the right compiler, linker etc. +on its own. To override this choice, the environment variables +\var{DISTUTILS\_USE\_SDK} and \var{MSSdk} must be both set. \var{MSSdk} +indicates that the current environment has been setup by the SDK's +\code{SetEnv.Cmd} script, or that the environment variables had been +registered when the SDK was installed; \var{DISTUTILS\_USE\_SDK} indicates +that the distutils user has made an explicit choice to override the +compiler selection by \class{MSVCCompiler}. \section{\module{distutils.bcppcompiler} --- Borland Compiler} \declaremodule{standard}{distutils.bcppcompiler} @@ -3088,7 +3099,7 @@ name of the output file, and \var{copied} is true if the file was copied Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will be moved into it with the same name; otherwise, \var{src} is just renamed to \var{dst}. Returns the new full name of the file. -\warning{Handles cross-device moves on Unix using \function{copy_file()}. +\warning{Handles cross-device moves on \UNIX{} using \function{copy_file()}. What about other systems???} \end{funcdesc} @@ -3131,7 +3142,7 @@ For non-\POSIX{} platforms, currently just returns \code{sys.platform}. Return 'pathname' as a name that will work on the native filesystem, i.e. split it on '/' and put it back together again using the current directory separator. Needed because filenames in the setup script are -always supplied in Unix style, and have to be converted to the local +always supplied in \UNIX{} style, and have to be converted to the local convention before we can actually use them in the filesystem. Raises \exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either starts or ends with a slash. @@ -3180,7 +3191,7 @@ with \var{prefix}. \end{funcdesc} \begin{funcdesc}{split_quoted}{s} -Split a string up according to Unix shell-like rules for quotes and +Split a string up according to \UNIX{} shell-like rules for quotes and backslashes. In short: words are delimited by spaces, as long as those spaces are not escaped by a backslash, or inside a quoted string. Single and double quotes are equivalent, and the quote characters can diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex index e4b91ac..1d0f279 100644 --- a/Doc/doc/doc.tex +++ b/Doc/doc/doc.tex @@ -187,6 +187,20 @@ text contributions are more than welcome as well. Topics which are not covered in the Apple's style guide will be discussed in this document if necessary. + Footnotes are generally discouraged due to the pain of using + footnotes in the HTML conversion of documents. Footnotes may be + used when they are the best way to present specific information. + When a footnote reference is added at the end of the sentence, it + should follow the sentence-ending punctuation. The \LaTeX{} markup + should appear something like this: + +\begin{verbatim} +This sentence has a footnote reference.% + \footnote{This is the footnote text.} +\end{verbatim} + + Footnotes may appear in the middle of sentences where appropriate. + Many special names are used in the Python documentation, including the names of operating systems, programming languages, standards bodies, and the like. Many of these were assigned \LaTeX{} macros @@ -281,10 +295,10 @@ text contributions are more than welcome as well. 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: + (\character{\%}) and continues through the end of the line + \emph{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 diff --git a/Doc/ext/newtypes.tex b/Doc/ext/newtypes.tex index cd2c045..a485a15 100644 --- a/Doc/ext/newtypes.tex +++ b/Doc/ext/newtypes.tex @@ -16,8 +16,9 @@ get started. The way new types are defined changed dramatically (and for the better) in Python 2.2. This document documents how to define new types for Python 2.2 and later. If you need to support older -versions of Python, you will need to refer to older versions of this -documentation. +versions of Python, you will need to refer to +\ulink{older versions of this documentation} + {http://www.python.org/doc/versions/}. \end{notice} \section{The Basics @@ -479,7 +480,7 @@ this? 1 \item when we know that deallocation of the object\footnote{This is true when we know that the object is a basic type, like a string or - a float} will not cause any + a float.} will not cause any calls back into our type's code \item when decrementing a reference count in a \member{tp_dealloc} handler when garbage-collections is not supported\footnote{We relied @@ -791,9 +792,9 @@ eventually figure out that the list is garbage and free it. In the second version of the \class{Noddy} example, we allowed any kind of object to be stored in the \member{first} or \member{last} -attributes\footnote{Even in the third version, we aren't guaranteed to +attributes.\footnote{Even in the third version, we aren't guaranteed to avoid cycles. Instances of string subclasses are allowed and string -subclasses could allow cycles even if normal strings don't.}. This +subclasses could allow cycles even if normal strings don't.} This means that \class{Noddy} objects can participate in cycles: \begin{verbatim} @@ -1563,6 +1564,85 @@ without setting an exception or it may set \exception{StopIteration}; avoiding the exception can yield slightly better performance. If an actual error occurs, it should set an exception and return \NULL. + +\subsection{Weak Reference Support\label{weakref-support}} + +One of the goals of Python's weak-reference implementation is to allow +any type to participate in the weak reference mechanism without +incurring the overhead on those objects which do not benefit by weak +referencing (such as numbers). + +For an object to be weakly referencable, the extension must include a +\ctype{PyObject*} field in the instance structure for the use of the +weak reference mechanism; it must be initialized to \NULL{} by the +object's constructor. It must also set the \member{tp_weaklistoffset} +field of the corresponding type object to the offset of the field. +For example, the instance type is defined with the following +structure: + +\begin{verbatim} +typedef struct { + PyObject_HEAD + PyClassObject *in_class; /* The class object */ + PyObject *in_dict; /* A dictionary */ + PyObject *in_weakreflist; /* List of weak references */ +} PyInstanceObject; +\end{verbatim} + +The statically-declared type object for instances is defined this way: + +\begin{verbatim} +PyTypeObject PyInstance_Type = { + PyObject_HEAD_INIT(&PyType_Type) + 0, + "module.instance", + + /* Lots of stuff omitted for brevity... */ + + Py_TPFLAGS_DEFAULT, /* tp_flags */ + 0, /* tp_doc */ + 0, /* tp_traverse */ + 0, /* tp_clear */ + 0, /* tp_richcompare */ + offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */ +}; +\end{verbatim} + +The type constructor is responsible for initializing the weak reference +list to \NULL: + +\begin{verbatim} +static PyObject * +instance_new() { + /* Other initialization stuff omitted for brevity */ + + self->in_weakreflist = NULL; + + return (PyObject *) self; +} +\end{verbatim} + +The only further addition is that the destructor needs to call the +weak reference manager to clear any weak references. This should be +done before any other parts of the destruction have occurred, but is +only required if the weak reference list is non-\NULL: + +\begin{verbatim} +static void +instance_dealloc(PyInstanceObject *inst) +{ + /* Allocate temporaries if needed, but do not begin + destruction just yet. + */ + + if (inst->in_weakreflist != NULL) + PyObject_ClearWeakRefs((PyObject *) inst); + + /* Proceed with object destruction normally. */ +} +\end{verbatim} + + \subsection{More Suggestions} Remember that you can omit most of these functions, in which case you diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex index ca18a1e..f9de548 100644 --- a/Doc/ext/windows.tex +++ b/Doc/ext/windows.tex @@ -28,13 +28,15 @@ Python; typically Microsoft Visual \Cpp. \section{A Cookbook Approach \label{win-cookbook}} There are two approaches to building extension modules on Windows, -just as there are on \UNIX: use the \refmodule{distutils} package to +just as there are on \UNIX: use the +\ulink{\module{distutils}}{../lib/module-distutils.html} package to control the build process, or do things manually. The distutils approach works well for most extensions; documentation on using -\refmodule{distutils} to build and package extension modules is -available in \citetitle[../dist/dist.html]{Distributing Python -Modules}. This section describes the manual approach to building -Python extensions written in C or \Cpp. +\ulink{\module{distutils}}{../lib/module-distutils.html} to build and +package extension modules is available in +\citetitle[../dist/dist.html]{Distributing Python Modules}. This +section describes the manual approach to building Python extensions +written in C or \Cpp. To build extensions using these instructions, you need to have a copy of the Python sources of the same version as your installed Python. diff --git a/Doc/howto/Makefile b/Doc/howto/Makefile index 19701c6..18110a2 100644 --- a/Doc/howto/Makefile +++ b/Doc/howto/Makefile @@ -1,88 +1,84 @@ +# Makefile for the HOWTO directory +# LaTeX HOWTOs can be turned into HTML, PDF, PS, DVI or plain text output. +# reST HOWTOs can only be turned into HTML. -MKHOWTO=../tools/mkhowto -WEBDIR=. +# Variables to change + +# Paper size for non-HTML formats (letter or a4) +PAPER=letter + +# Arguments to rst2html.py, and location of the script RSTARGS = --input-encoding=utf-8 -VPATH=.:dvi:pdf:ps:txt +RST2HTML = rst2html.py -# List of HOWTOs that aren't to be processed +# List of HOWTOs that aren't to be processed. This should contain the +# base name of the HOWTO without any extension (e.g. 'advocacy', +# 'unicode'). +REMOVE_HOWTOS = -REMOVE_HOWTO = +MKHOWTO=../tools/mkhowto +WEBDIR=. +PAPERDIR=../paper-$(PAPER) +HTMLDIR=../html # Determine list of files to be built +TEX_SOURCES = $(wildcard *.tex) +RST_SOURCES = $(wildcard *.rst) +TEX_NAMES = $(filter-out $(REMOVE_HOWTOS),$(patsubst %.tex,%,$(TEX_SOURCES))) + +PAPER_PATHS=$(addprefix $(PAPERDIR)/,$(TEX_NAMES)) +DVI =$(addsuffix .dvi,$(PAPER_PATHS)) +PDF =$(addsuffix .pdf,$(PAPER_PATHS)) +PS =$(addsuffix .ps,$(PAPER_PATHS)) -HOWTO=$(filter-out $(REMOVE_HOWTO),$(wildcard *.tex)) -RST_SOURCES = $(shell echo *.rst) -DVI =$(patsubst %.tex,%.dvi,$(HOWTO)) -PDF =$(patsubst %.tex,%.pdf,$(HOWTO)) -PS =$(patsubst %.tex,%.ps,$(HOWTO)) -TXT =$(patsubst %.tex,%.txt,$(HOWTO)) -HTML =$(patsubst %.tex,%,$(HOWTO)) +ALL_HOWTO_NAMES = $(TEX_NAMES) $(patsubst %.rst,%,$(RST_SOURCES)) +HOWTO_NAMES = $(filter-out $(REMOVE_HOWTOS),$(ALL_HOWTO_NAMES)) +HTML = $(addprefix $(HTMLDIR)/,$(HOWTO_NAMES)) # Rules for building various formats -%.dvi : %.tex + +# reST to HTML +$(HTMLDIR)/%: %.rst + if [ ! -d $@ ] ; then mkdir $@ ; fi + $(RST2HTML) $(RSTARGS) $< >$@/index.html + +# LaTeX to various output formats +$(PAPERDIR)/%.dvi : %.tex $(MKHOWTO) --dvi $< - mv $@ dvi + mv $*.dvi $@ -%.pdf : %.tex +$(PAPERDIR)/%.pdf : %.tex $(MKHOWTO) --pdf $< - mv $@ pdf + mv $*.pdf $@ -%.ps : %.tex +$(PAPERDIR)/%.ps : %.tex $(MKHOWTO) --ps $< - mv $@ ps + mv $*.ps $@ + +$(HTMLDIR)/% : %.tex + $(MKHOWTO) --html --iconserver="." --dir $@ $< -%.txt : %.tex +# Rule that isn't actually used -- we no longer support the 'txt' target. +$(PAPERDIR)/%.txt : %.tex $(MKHOWTO) --text $< mv $@ txt -% : %.tex - $(MKHOWTO) --html --iconserver="." $< - tar -zcvf html/$*.tgz $* - #zip -r html/$*.zip $* - default: @echo "'all' -- build all files" - @echo "'dvi', 'pdf', 'ps', 'txt', 'html' -- build one format" - -all: $(HTML) - -.PHONY : dvi pdf ps txt html rst -dvi: $(DVI) - -pdf: $(PDF) -ps: $(PS) -txt: $(TXT) -html:$(HTML) - -# Rule to build collected tar files -dist: #all - for i in dvi pdf ps txt ; do \ - cd $$i ; \ - tar -zcf All.tgz *.$$i ;\ - cd .. ;\ - done + @echo "'dvi', 'pdf', 'ps', 'html' -- build one format" -# Rule to copy files to the Web tree on AMK's machine -web: dist - cp dvi/* $(WEBDIR)/dvi - cp ps/* $(WEBDIR)/ps - cp pdf/* $(WEBDIR)/pdf - cp txt/* $(WEBDIR)/txt - for dir in $(HTML) ; do cp -rp $$dir $(WEBDIR) ; done - for ltx in $(HOWTO) ; do cp -p $$ltx $(WEBDIR)/latex ; done +all: dvi pdf ps html -rst: unicode.html - -%.html: %.rst - rst2html $(RSTARGS) $< >$@ +.PHONY : dvi pdf ps html +dvi: $(DVI) +pdf: $(PDF) +ps: $(PS) +html: $(HTML) clean: - rm -f *~ *.log *.ind *.l2h *.aux *.toc *.how - rm -f *.dvi *.ps *.pdf *.bkm - rm -f unicode.html + rm -f *~ *.log *.ind *.l2h *.aux *.toc *.how *.bkm + rm -f *.dvi *.pdf *.ps clobber: - rm dvi/* ps/* pdf/* txt/* html/* - - - + rm -rf $(HTML) + rm -rf $(DVI) $(PDF) $(PS) diff --git a/Doc/howto/doanddont.tex b/Doc/howto/doanddont.tex index adbde66..a105ca1 100644 --- a/Doc/howto/doanddont.tex +++ b/Doc/howto/doanddont.tex @@ -288,8 +288,9 @@ More useful functions in \module{os.path}: \function{basename}, There are also many useful builtin functions people seem not to be aware of for some reason: \function{min()} and \function{max()} can find the minimum/maximum of any sequence with comparable semantics, -for example, yet many people write they own max/min. Another highly -useful function is \function{reduce()}. Classical use of \function{reduce()} +for example, yet many people write their own +\function{max()}/\function{min()}. Another highly useful function is +\function{reduce()}. A classical use of \function{reduce()} is something like \begin{verbatim} diff --git a/Doc/howto/sockets.tex b/Doc/howto/sockets.tex index 4da92a8..0cecbb9 100644 --- a/Doc/howto/sockets.tex +++ b/Doc/howto/sockets.tex @@ -213,34 +213,39 @@ Assuming you don't want to end the connection, the simplest solution is a fixed length message: \begin{verbatim} - class mysocket: - '''demonstration class only - - coded for clarity, not efficiency''' - def __init__(self, sock=None): - if sock is None: - self.sock = socket.socket( - socket.AF_INET, socket.SOCK_STREAM) - else: - self.sock = sock - def connect(host, port): - self.sock.connect((host, port)) - def mysend(msg): - totalsent = 0 - while totalsent < MSGLEN: - sent = self.sock.send(msg[totalsent:]) - if sent == 0: - raise RuntimeError, \\ - "socket connection broken" - totalsent = totalsent + sent - def myreceive(): - msg = '' - while len(msg) < MSGLEN: - chunk = self.sock.recv(MSGLEN-len(msg)) - if chunk == '': - raise RuntimeError, \\ - "socket connection broken" - msg = msg + chunk - return msg +class mysocket: + '''demonstration class only + - coded for clarity, not efficiency + ''' + + def __init__(self, sock=None): + if sock is None: + self.sock = socket.socket( + socket.AF_INET, socket.SOCK_STREAM) + else: + self.sock = sock + + def connect(self, host, port): + self.sock.connect((host, port)) + + def mysend(self, msg): + totalsent = 0 + while totalsent < MSGLEN: + sent = self.sock.send(msg[totalsent:]) + if sent == 0: + raise RuntimeError, \\ + "socket connection broken" + totalsent = totalsent + sent + + def myreceive(self): + msg = '' + while len(msg) < MSGLEN: + chunk = self.sock.recv(MSGLEN-len(msg)) + if chunk == '': + raise RuntimeError, \\ + "socket connection broken" + msg = msg + chunk + return msg \end{verbatim} The sending code here is usable for almost any messaging scheme - in diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex index 676f8ae..df7c656 100644 --- a/Doc/inst/inst.tex +++ b/Doc/inst/inst.tex @@ -262,7 +262,7 @@ If you don't choose an installation directory---i.e., if you just run \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 Mac OS X, which is also Unix-based), +\UNIX{} (and Mac OS X, which is also \UNIX-based), 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}% diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex index 6853325..ea12705 100644 --- a/Doc/lib/email.tex +++ b/Doc/lib/email.tex @@ -105,7 +105,7 @@ of the package. \lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5} \end{tableiii} -Here are the major differences between \module{email} verson 4 and version 3: +Here are the major differences between \module{email} version 4 and version 3: \begin{itemize} \item All modules have been renamed according to \pep{8} standards. For @@ -126,6 +126,15 @@ Here are the major differences between \module{email} verson 4 and version 3: \item Methods that were deprecated in version 3 have been removed. These include \method{Generator.__call__()}, \method{Message.get_type()}, \method{Message.get_main_type()}, \method{Message.get_subtype()}. + +\item Fixes have been added for \rfc{2231} support which can change some of + the return types for \function{Message.get_param()} and friends. Under + some circumstances, values which used to return a 3-tuple now return + simple strings (specifically, if all extended parameter segments were + unencoded, there is no language and charset designation expected, so the + return type is now a simple string). Also, \%-decoding used to be done + for both encoded and unencoded segments; this decoding is now done only + for encoded segments. \end{itemize} Here are the major differences between \module{email} version 3 and version 2: diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex index 3415442..b236673 100644 --- a/Doc/lib/emailgenerator.tex +++ b/Doc/lib/emailgenerator.tex @@ -31,11 +31,11 @@ Optional \var{mangle_from_} is a flag that, when \code{True}, puts a \samp{>} character in front of any line in the body that starts exactly as \samp{From }, i.e. \code{From} followed by a space at the beginning of the line. This is the only guaranteed portable way to avoid having such -lines be mistaken for a Unix mailbox format envelope header separator (see +lines be mistaken for a \UNIX{} mailbox format envelope header separator (see \ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD} {http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html} for details). \var{mangle_from_} defaults to \code{True}, but you -might want to set this to \code{False} if you are not writing Unix +might want to set this to \code{False} if you are not writing \UNIX{} mailbox format files. Optional \var{maxheaderlen} specifies the longest length for a diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 0691179..837c759 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -71,12 +71,12 @@ and how to embed it in other applications. % BUILT-INs % ============= -\input{libobjs} % Built-in Types, Exceptions and Functions +\input{libobjs} % Built-in Exceptions and Functions \input{libfuncs} -\input{libstdtypes} \input{libexcs} \input{libconsts} +\input{libstdtypes} % Built-in types % ============= @@ -154,8 +154,8 @@ and how to embed it in other applications. % encoding stuff \input{libbase64} -\input{libbinascii} \input{libbinhex} +\input{libbinascii} \input{libquopri} \input{libuu} @@ -171,6 +171,7 @@ and how to embed it in other applications. \input{xmlsaxhandler} \input{xmlsaxutils} \input{xmlsaxreader} +\input{libetree} % \input{libxmllib} \input{fileformats} % Miscellaneous file formats @@ -245,7 +246,6 @@ and how to embed it in other applications. \input{libplatform} \input{liberrno} \input{libctypes} -\input{libctypesref} \input{libsomeos} % Optional Operating System Services \input{libselect} @@ -292,6 +292,7 @@ and how to embed it in other applications. \input{libwebbrowser} \input{libcgi} \input{libcgitb} +\input{libwsgiref} \input{liburllib} \input{liburllib2} \input{libhttplib} @@ -303,6 +304,7 @@ and how to embed it in other applications. \input{libsmtplib} \input{libsmtpd} \input{libtelnetlib} +\input{libuuid} \input{liburlparse} \input{libsocksvr} \input{libbasehttp} diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex index 17228dd..badc6ec 100644 --- a/Doc/lib/libanydbm.tex +++ b/Doc/lib/libanydbm.tex @@ -46,6 +46,32 @@ be stored, retrieved, and deleted, and the \method{has_key()} and \method{keys()} methods are available. Keys and values must always be strings. +The following example records some hostnames and a corresponding title, +and then prints out the contents of the database: + +\begin{verbatim} +import anydbm + +# Open database, creating it if necessary. +db = anydbm.open('cache', 'c') + +# Record some values +db['www.python.org'] = 'Python Website' +db['www.cnn.com'] = 'Cable News Network' + +# Loop through contents. Other dictionary methods +# such as .keys(), .values() also work. +for k, v in db.iteritems(): + print k, '\t', v + +# Storing a non-string key or value will raise an exception (most +# likely a TypeError). +db['www.yahoo.com'] = 4 + +# Close when done. +db.close() +\end{verbatim} + \begin{seealso} \seemodule{dbhash}{BSD \code{db} database interface.} diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex index 747d837..0039c84 100644 --- a/Doc/lib/libbase64.tex +++ b/Doc/lib/libbase64.tex @@ -146,6 +146,18 @@ string containing one or more lines of base64-encoded data always including an extra trailing newline (\code{'\e n'}). \end{funcdesc} +An example usage of the module: + +\begin{verbatim} +>>> import base64 +>>> encoded = base64.b64encode('data to be encoded') +>>> encoded +'ZGF0YSB0byBiZSBlbmNvZGVk' +>>> data = base64.b64decode(encoded) +>>> data +'data to be encoded' +\end{verbatim} + \begin{seealso} \seemodule{binascii}{Support module containing \ASCII-to-binary and binary-to-\ASCII{} conversions.} diff --git a/Doc/lib/libbinascii.tex b/Doc/lib/libbinascii.tex index b244b10..84d29c6 100644 --- a/Doc/lib/libbinascii.tex +++ b/Doc/lib/libbinascii.tex @@ -9,10 +9,11 @@ The \module{binascii} module contains a number of methods to convert between binary and various \ASCII-encoded binary representations. Normally, you will not use these functions directly -but use wrapper modules like \refmodule{uu}\refstmodindex{uu} or -\refmodule{binhex}\refstmodindex{binhex} instead, this module solely -exists because bit-manipulation of large amounts of data is slow in -Python. +but use wrapper modules like \refmodule{uu}\refstmodindex{uu}, +\refmodule{base64}\refstmodindex{base64}, or +\refmodule{binhex}\refstmodindex{binhex} instead. The \module{binascii} module +contains low-level functions written in C for greater speed +that are used by the higher-level modules. The \module{binascii} module defines the following functions: diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex index a5cda6d..44b9168 100644 --- a/Doc/lib/libbsddb.tex +++ b/Doc/lib/libbsddb.tex @@ -13,23 +13,29 @@ using the appropriate open call. Bsddb objects behave generally like dictionaries. Keys and values must be strings, however, so to use other objects as keys or to store other kinds of objects the user must serialize them somehow, typically using \function{marshal.dumps()} or -\function{pickle.dumps}. +\function{pickle.dumps()}. The \module{bsddb} module requires a Berkeley DB library version from 3.3 thru 4.4. \begin{seealso} - \seeurl{http://pybsddb.sourceforge.net/}{Website with documentation - for the new python Berkeley DB interface that closely mirrors the - sleepycat object oriented interface provided in Berkeley DB 3 and 4.} + \seeurl{http://pybsddb.sourceforge.net/}{The website with documentation + for the \module{bsddb.db} python Berkeley DB interface that closely mirrors + the Sleepycat object oriented interface provided in Berkeley DB 3 and 4.} \seeurl{http://www.sleepycat.com/}{Sleepycat Software produces the - modern Berkeley DB library.} + Berkeley DB library.} \end{seealso} +A more modern DB, DBEnv and DBSequence object interface is available in the +\module{bsddb.db} module which closely matches the Sleepycat Berkeley DB C API +documented at the above URLs. Additional features provided by the +\module{bsddb.db} API include fine tuning, transactions, logging, and +multiprocess concurrent database access. + The following is a description of the legacy \module{bsddb} interface -compatible with the old python bsddb module. For details about the more -modern Db and DbEnv object oriented interface see the above mentioned -pybsddb URL. +compatible with the old python bsddb module. Starting in Python 2.5 this +interface should be safe for multithreaded access. The \module{bsddb.db} +API is recommended for threading users as it provides better control. The \module{bsddb} module defines the following functions that create objects that access the appropriate type of Berkeley DB file. The @@ -88,7 +94,7 @@ interpretation. \begin{notice} -Beginning in 2.3 some Unix versions of Python may have a \module{bsddb185} +Beginning in 2.3 some \UNIX{} versions of Python may have a \module{bsddb185} module. This is present \emph{only} to allow backwards compatibility with systems which ship with the old Berkeley DB 1.85 database library. The \module{bsddb185} module should never be used directly in new code. diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex index d39a548..3e9667d 100644 --- a/Doc/lib/libcompileall.tex +++ b/Doc/lib/libcompileall.tex @@ -44,6 +44,19 @@ compile Python sources in directories named on the command line or in \function{compile_dir()} function. \end{funcdesc} +To force a recompile of all the \file{.py} files in the \file{Lib/} +subdirectory and all its subdirectories: + +\begin{verbatim} +import compileall + +compileall.compile_dir('Lib/', force=True) + +# Perform same compilation, excluding files in .svn directories. +import re +compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True) +\end{verbatim} + \begin{seealso} \seemodule[pycompile]{py_compile}{Byte-compile a single source file.} diff --git a/Doc/lib/libcookielib.tex b/Doc/lib/libcookielib.tex index ef2d833..01f2539 100644 --- a/Doc/lib/libcookielib.tex +++ b/Doc/lib/libcookielib.tex @@ -24,7 +24,7 @@ Internet are Netscape cookies. \module{cookielib} attempts to follow the de-facto Netscape cookie protocol (which differs substantially from that set out in the original Netscape specification), including taking note of the \code{max-age} and \code{port} cookie-attributes -introduced with RFC 2109. \note{The various named parameters found in +introduced with RFC 2965. \note{The various named parameters found in \mailheader{Set-Cookie} and \mailheader{Set-Cookie2} headers (eg. \code{domain} and \code{expires}) are conventionally referred to as \dfn{attributes}. To distinguish them from Python attributes, the diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex index 65053c7..8e10ccf 100644 --- a/Doc/lib/libcsv.tex +++ b/Doc/lib/libcsv.tex @@ -55,7 +55,7 @@ The \module{csv} module defines the following functions: Return a reader object which will iterate over lines in the given {}\var{csvfile}. \var{csvfile} can be any object which supports the iterator protocol and returns a string each time its \method{next} -method is called - file objects and list objects are both suitable. +method is called --- file objects and list objects are both suitable. If \var{csvfile} is a file object, it must be opened with the 'b' flag on platforms where that makes a difference. An optional {}\var{dialect} parameter can be given @@ -70,6 +70,18 @@ Parameters'' for details of these parameters. All data read are returned as strings. No automatic data type conversion is performed. + +\versionchanged[ +The parser is now stricter with respect to multi-line quoted +fields. Previously, if a line ended within a quoted field without a +terminating newline character, a newline would be inserted into the +returned field. This behavior caused problems when reading files +which contained carriage return characters within fields. The +behavior was changed to return the field without inserting newlines. As +a consequence, if newlines embedded within fields are important, the +input should be split into lines in a manner which preserves the newline +characters]{2.5} + \end{funcdesc} \begin{funcdesc}{writer}{csvfile\optional{, @@ -404,7 +416,7 @@ csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE) reader = csv.reader(open("passwd", "rb"), 'unixpwd') \end{verbatim} -A slightly more advanced use of the reader - catching and reporting errors: +A slightly more advanced use of the reader --- catching and reporting errors: \begin{verbatim} import csv, sys diff --git a/Doc/lib/libctypes.tex b/Doc/lib/libctypes.tex index dc37749..6206b8c 100755 --- a/Doc/lib/libctypes.tex +++ b/Doc/lib/libctypes.tex @@ -1,4 +1,4 @@ -\newlength{\locallinewidth} +\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi \setlength{\locallinewidth}{\linewidth} \section{\module{ctypes} --- A foreign function library for Python.} \declaremodule{standard}{ctypes} @@ -6,13 +6,13 @@ \modulesynopsis{A foreign function library for Python.} \versionadded{2.5} -\code{ctypes} is a foreign function library for Python. +\code{ctypes} is a foreign function library for Python. It provides C +compatible data types, and allows to call functions in dlls/shared +libraries. It can be used to wrap these libraries in pure Python. \subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}} -This tutorial describes version 0.9.9 of \code{ctypes}. - Note: The code samples in this tutorial uses \code{doctest} to make sure that they actually work. Since some code samples behave differently under Linux, Windows, or Mac OS X, they contain doctest directives in @@ -66,8 +66,7 @@ calling the constructor: <CDLL 'libc.so.6', handle ... at ...> >>> \end{verbatim} - -XXX Add section for Mac OS X. +% XXX Add section for Mac OS X. \subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}} @@ -119,7 +118,7 @@ identifiers, like \code{"??2@YAPAXI@Z"}. In this case you have to use On Windows, some dlls export functions not by name but by ordinal. These functions can be accessed by indexing the dll object with the -odinal number: +ordinal number: \begin{verbatim} >>> cdll.kernel32[1] # doctest: +WINDOWS <_FuncPtr object at 0x...> @@ -143,16 +142,18 @@ which returns a win32 module handle. This example calls both functions with a NULL pointer (\code{None} should be used as the NULL pointer): \begin{verbatim} ->>> print libc.time(None) -114... +>>> print libc.time(None) # doctest: +SKIP +1150640792 >>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS 0x1d000000 >>> \end{verbatim} \code{ctypes} tries to protect you from calling functions with the wrong -number of arguments. Unfortunately this only works on Windows. It -does this by examining the stack after the function returns: +number of arguments or the wrong calling convention. Unfortunately +this only works on Windows. It does this by examining the stack after +the function returns, so although an error is raised the function +\emph{has} been called: \begin{verbatim} >>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS Traceback (most recent call last): @@ -165,6 +166,25 @@ ValueError: Procedure probably called with too many arguments (4 bytes in excess >>> \end{verbatim} +The same exception is raised when you call an \code{stdcall} function +with the \code{cdecl} calling convention, or vice versa: +\begin{verbatim} +>>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS +Traceback (most recent call last): + File "<stdin>", line 1, in ? +ValueError: Procedure probably called with not enough arguments (4 bytes missing) +>>> + +>>> windll.msvcrt.printf("spam") # doctest: +WINDOWS +Traceback (most recent call last): + File "<stdin>", line 1, in ? +ValueError: Procedure probably called with too many arguments (4 bytes in excess) +>>> +\end{verbatim} + +To find out the correct calling convention you have to look into the C +header file or the documentation for the function you want to call. + On Windows, \code{ctypes} uses win32 structured exception handling to prevent crashes from general protection faults when functions are called with invalid argument values: @@ -186,158 +206,172 @@ Before we move on calling functions with other parameter types, we have to learn more about \code{ctypes} data types. -\subsubsection{Simple data types\label{ctypes-simple-data-types}} +\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}} \code{ctypes} defines a number of primitive C compatible data types : \begin{quote} - -\begin{longtable}[c]{|p{0.19\locallinewidth}|p{0.28\locallinewidth}|p{0.14\locallinewidth}|} -\hline -\textbf{ +\begin{tableiii}{l|l|l}{textrm} +{ ctypes type -} & \textbf{ +} +{ C type -} & \textbf{ +} +{ Python type -} \\ -\hline -\endhead - +} +\lineiii{ \class{c{\_}char} - & +} +{ \code{char} - & +} +{ character - \\ -\hline - +} +\lineiii{ \class{c{\_}byte} - & +} +{ \code{char} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}ubyte} - & +} +{ \code{unsigned char} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}short} - & +} +{ \code{short} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}ushort} - & +} +{ \code{unsigned short} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}int} - & +} +{ \code{int} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}uint} - & +} +{ \code{unsigned int} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}long} - & +} +{ \code{long} - & +} +{ integer - \\ -\hline - +} +\lineiii{ \class{c{\_}ulong} - & +} +{ \code{unsigned long} - & +} +{ long - \\ -\hline - +} +\lineiii{ \class{c{\_}longlong} - & +} +{ \code{{\_}{\_}int64} or \code{long long} - & +} +{ long - \\ -\hline - +} +\lineiii{ \class{c{\_}ulonglong} - & +} +{ \code{unsigned {\_}{\_}int64} or \code{unsigned long long} - & +} +{ long - \\ -\hline - +} +\lineiii{ \class{c{\_}float} - & +} +{ \code{float} - & +} +{ float - \\ -\hline - +} +\lineiii{ \class{c{\_}double} - & +} +{ \code{double} - & +} +{ float - \\ -\hline - +} +\lineiii{ \class{c{\_}char{\_}p} - & +} +{ \code{char *} (NUL terminated) - & +} +{ string or \code{None} - \\ -\hline - +} +\lineiii{ \class{c{\_}wchar{\_}p} - & +} +{ \code{wchar{\_}t *} (NUL terminated) - & +} +{ unicode or \code{None} - \\ -\hline - +} +\lineiii{ \class{c{\_}void{\_}p} - & +} +{ \code{void *} - & +} +{ integer or \code{None} - \\ -\hline -\end{longtable} +} +\end{tableiii} \end{quote} All these types can be created by calling them with an optional @@ -380,6 +414,7 @@ c_char_p('Hello, World') c_char_p('Hi, there') >>> print s # first string is unchanged Hello, World +>>> \end{verbatim} You should be careful, however, not to pass them to functions @@ -557,13 +592,12 @@ None >>> \end{verbatim} -XXX Mention the \member{errcheck} protocol... - You can also use a callable Python object (a function or a class for -example) as the \member{restype} attribute. It will be called with the -\code{integer} the C function returns, and the result of this call will -be used as the result of your function call. This is useful to check -for error return values and automatically raise an exception: +example) as the \member{restype} attribute, if the foreign function returns +an integer. The callable will be called with the \code{integer} the C +function returns, and the result of this call will be used as the +result of your function call. This is useful to check for error return +values and automatically raise an exception: \begin{verbatim} >>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS >>> def ValidHandle(value): @@ -575,7 +609,7 @@ for error return values and automatically raise an exception: >>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS >>> GetModuleHandle(None) # doctest: +WINDOWS 486539264 ->>> GetModuleHandle("something silly") # doctest: +WINDOWS +IGNORE_EXCEPTION_DETAIL +>>> GetModuleHandle("something silly") # doctest: +WINDOWS Traceback (most recent call last): File "<stdin>", line 1, in ? File "<stdin>", line 3, in ValidHandle @@ -588,6 +622,10 @@ api to get the string representation of an error code, and \emph{returns} an exception. \code{WinError} takes an optional error code parameter, if no one is used, it calls \function{GetLastError()} to retrieve it. +Please note that a much more powerful error checking mechanism is +available through the \member{errcheck} attribute; see the reference manual +for details. + \subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}} @@ -744,6 +782,7 @@ containing 4 POINTs among other stuff: >>> >>> print len(MyStruct().point_array) 4 +>>> \end{verbatim} Instances are created in the usual way, by calling the class: @@ -781,21 +820,31 @@ Pointer instances are created by calling the \code{pointer} function on a >>> \end{verbatim} -XXX XXX Not correct: use indexing, not the contents atribute - Pointer instances have a \code{contents} attribute which returns the -ctypes' type pointed to, the \code{c{\_}int(42)} in the above case: +object to which the pointer points, the \code{i} object above: \begin{verbatim} >>> pi.contents c_long(42) >>> \end{verbatim} +Note that \code{ctypes} does not have OOR (original object return), it +constructs a new, equivalent object each time you retrieve an +attribute: +\begin{verbatim} +>>> pi.contents is i +False +>>> pi.contents is pi.contents +False +>>> +\end{verbatim} + Assigning another \class{c{\_}int} instance to the pointer's contents attribute would cause the pointer to point to the memory location where this is stored: \begin{verbatim} ->>> pi.contents = c_int(99) +>>> i = c_int(99) +>>> pi.contents = i >>> pi.contents c_long(99) >>> @@ -808,26 +857,21 @@ Pointer instances can also be indexed with integers: >>> \end{verbatim} -XXX What is this??? Assigning to an integer index changes the pointed to value: \begin{verbatim} ->>> i2 = pi[0] ->>> i2 -99 +>>> print i +c_long(99) >>> pi[0] = 22 ->>> i2 -99 +>>> print i +c_long(22) >>> \end{verbatim} It is also possible to use indexes different from 0, but you must know -what you're doing when you use this: You access or change arbitrary -memory locations when you do this. Generally you only use this feature -if you receive a pointer from a C function, and you \emph{know} that the -pointer actually points to an array instead of a single item. - - -\subsubsection{Pointer classes/types\label{ctypes-pointer-classestypes}} +what you're doing, just as in C: You can access or change arbitrary +memory locations. Generally you only use this feature if you receive a +pointer from a C function, and you \emph{know} that the pointer actually +points to an array instead of a single item. Behind the scenes, the \code{pointer} function does more than simply create pointer instances, it has to create pointer \emph{types} first. @@ -837,7 +881,7 @@ This is done with the \code{POINTER} function, which accepts any >>> PI = POINTER(c_int) >>> PI <class 'ctypes.LP_c_long'> ->>> PI(42) # doctest: +IGNORE_EXCEPTION_DETAIL +>>> PI(42) Traceback (most recent call last): File "<stdin>", line 1, in ? TypeError: expected c_long instead of int @@ -846,6 +890,103 @@ TypeError: expected c_long instead of int >>> \end{verbatim} +Calling the pointer type without an argument creates a \code{NULL} +pointer. \code{NULL} pointers have a \code{False} boolean value: +\begin{verbatim} +>>> null_ptr = POINTER(c_int)() +>>> print bool(null_ptr) +False +>>> +\end{verbatim} + +\code{ctypes} checks for \code{NULL} when dereferencing pointers (but +dereferencing non-\code{NULL} pointers would crash Python): +\begin{verbatim} +>>> null_ptr[0] +Traceback (most recent call last): + .... +ValueError: NULL pointer access +>>> + +>>> null_ptr[0] = 1234 +Traceback (most recent call last): + .... +ValueError: NULL pointer access +>>> +\end{verbatim} + + +\subsubsection{Type conversions\label{ctypes-type-conversions}} + +Usually, ctypes does strict type checking. This means, if you have +\code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or as the +type of a member field in a structure definition, only instances of +exactly the same type are accepted. There are some exceptions to this +rule, where ctypes accepts other objects. For example, you can pass +compatible array instances instead of pointer types. So, for +\code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int: +\begin{verbatim} +>>> class Bar(Structure): +... _fields_ = [("count", c_int), ("values", POINTER(c_int))] +... +>>> bar = Bar() +>>> bar.values = (c_int * 3)(1, 2, 3) +>>> bar.count = 3 +>>> for i in range(bar.count): +... print bar.values[i] +... +1 +2 +3 +>>> +\end{verbatim} + +To set a POINTER type field to \code{NULL}, you can assign \code{None}: +\begin{verbatim} +>>> bar.values = None +>>> +\end{verbatim} + +XXX list other conversions... + +Sometimes you have instances of incompatible types. In \code{C}, you can +cast one type into another type. \code{ctypes} provides a \code{cast} +function which can be used in the same way. The \code{Bar} structure +defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays +for its \code{values} field, but not instances of other types: +\begin{verbatim} +>>> bar.values = (c_byte * 4)() +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance +>>> +\end{verbatim} + +For these cases, the \code{cast} function is handy. + +The \code{cast} function can be used to cast a ctypes instance into a +pointer to a different ctypes data type. \code{cast} takes two +parameters, a ctypes object that is or can be converted to a pointer +of some kind, and a ctypes pointer type. It returns an instance of +the second argument, which references the same memory block as the +first argument: +\begin{verbatim} +>>> a = (c_byte * 4)() +>>> cast(a, POINTER(c_int)) +<ctypes.LP_c_long object at ...> +>>> +\end{verbatim} + +So, \code{cast} can be used to assign to the \code{values} field of \code{Bar} +the structure: +\begin{verbatim} +>>> bar = Bar() +>>> bar.values = cast((c_byte * 4)(), POINTER(c_int)) +>>> print bar.values[0] +0 +>>> +\end{verbatim} + \subsubsection{Incomplete Types\label{ctypes-incomplete-types}} @@ -1059,7 +1200,10 @@ py_cmp_func 5 7 >>> \end{verbatim} -So, our array sorted now: +It is quite interesting to see that the Windows \function{qsort} function +needs more comparisons than the linux version! + +As we can easily check, our array sorted now: \begin{verbatim} >>> for i in ia: print i, ... @@ -1070,14 +1214,14 @@ So, our array sorted now: \textbf{Important note for callback functions:} Make sure you keep references to CFUNCTYPE objects as long as they are -used from C code. ctypes doesn't, and if you don't, they may be +used from C code. \code{ctypes} doesn't, and if you don't, they may be garbage collected, crashing your program when a callback is made. \subsubsection{Accessing values exported from dlls\label{ctypes-accessing-values-exported-from-dlls}} Sometimes, a dll not only exports functions, it also exports -values. An example in the Python library itself is the +variables. An example in the Python library itself is the \code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the \programopt{-O} or \programopt{-OO} flag given on startup. @@ -1148,9 +1292,6 @@ The fact that standard Python has a frozen module and a frozen package (indicated by the negative size member) is not wellknown, it is only used for testing. Try it out with \code{import {\_}{\_}hello{\_}{\_}} for example. -XXX Describe how to access the \var{code} member fields, which contain -the byte code for the modules. - \subsubsection{Surprises\label{ctypes-surprises}} @@ -1175,6 +1316,7 @@ Consider the following example: >>> rc.a, rc.b = rc.b, rc.a >>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y 3 4 3 4 +>>> \end{verbatim} Hm. We certainly expected the last statement to print \code{3 4 1 2}. @@ -1184,6 +1326,7 @@ line above: >>> temp0, temp1 = rc.b, rc.a >>> rc.a = temp0 >>> rc.b = temp1 +>>> \end{verbatim} Note that \code{temp0} and \code{temp1} are objects still using the internal @@ -1214,6 +1357,51 @@ the object itself, instead the \code{contents} of the object is stored. Accessing the contents again constructs a new Python each time! +\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}} + +\code{ctypes} provides some support for variable-sized arrays and +structures (this was added in version 0.9.9.7). + +The \code{resize} function can be used to resize the memory buffer of an +existing ctypes object. The function takes the object as first +argument, and the requested size in bytes as the second argument. The +memory block cannot be made smaller than the natural memory block +specified by the objects type, a \code{ValueError} is raised if this is +tried: +\begin{verbatim} +>>> short_array = (c_short * 4)() +>>> print sizeof(short_array) +8 +>>> resize(short_array, 4) +Traceback (most recent call last): + ... +ValueError: minimum size is 8 +>>> resize(short_array, 32) +>>> sizeof(short_array) +32 +>>> sizeof(type(short_array)) +8 +>>> +\end{verbatim} + +This is nice and fine, but how would one access the additional +elements contained in this array? Since the type still only knows +about 4 elements, we get errors accessing other elements: +\begin{verbatim} +>>> short_array[:] +[0, 0, 0, 0] +>>> short_array[7] +Traceback (most recent call last): + ... +IndexError: invalid index +>>> +\end{verbatim} + +Another way to use variable-sized data types with \code{ctypes} is to use +the dynamic nature of Python, and (re-)define the data type after the +required size is already known, on a case by case basis. + + \subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}} Enumeration types are not implemented. You can do it easily yourself, @@ -1224,3 +1412,1014 @@ using \class{c{\_}int} as the base class. % compile-command: "make.bat" % End: + +\subsection{ctypes reference\label{ctypes-ctypes-reference}} + + +\subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}} + +When programming in a compiled language, shared libraries are accessed +when compiling/linking a program, and when the program is run. + +The purpose of the \code{find{\_}library} function is to locate a library in +a way similar to what the compiler does (on platforms with several +versions of a shared library the most recent should be loaded), while +the ctypes library loaders act like when a program is run, and call +the runtime loader directly. + +The \code{ctypes.util} module provides a function which can help to +determine the library to load. + +\begin{datadescni}{find_library(name)} +Try to find a library and return a pathname. \var{name} is the +library name without any prefix like \var{lib}, suffix like \code{.so}, +\code{.dylib} or version number (this is the form used for the posix +linker option \programopt{-l}). If no library can be found, returns +\code{None}. +\end{datadescni} + +The exact functionality is system dependend. + +On Linux, \code{find{\_}library} tries to run external programs +(/sbin/ldconfig, gcc, and objdump) to find the library file. It +returns the filename of the library file. Here are sone examples: +\begin{verbatim} +>>> from ctypes.util import find_library +>>> find_library("m") +'libm.so.6' +>>> find_library("c") +'libc.so.6' +>>> find_library("bz2") +'libbz2.so.1.0' +>>> +\end{verbatim} + +On OS X, \code{find{\_}library} tries several predefined naming schemes and +paths to locate the library, and returns a full pathname if successfull: +\begin{verbatim} +>>> from ctypes.util import find_library +>>> find_library("c") +'/usr/lib/libc.dylib' +>>> find_library("m") +'/usr/lib/libm.dylib' +>>> find_library("bz2") +'/usr/lib/libbz2.dylib' +>>> find_library("AGL") +'/System/Library/Frameworks/AGL.framework/AGL' +>>> +\end{verbatim} + +On Windows, \code{find{\_}library} searches along the system search path, +and returns the full pathname, but since there is no predefined naming +scheme a call like \code{find{\_}library("c")} will fail and return +\code{None}. + +If wrapping a shared library with \code{ctypes}, it \emph{may} be better to +determine the shared library name at development type, and hardcode +that into the wrapper module instead of using \code{find{\_}library} to +locate the library at runtime. + + +\subsubsection{Loading shared libraries\label{ctypes-loading-shared-libraries}} + +There are several ways to loaded shared libraries into the Python +process. One way is to instantiate one of the following classes: + +\begin{classdesc}{CDLL}{name, mode=DEFAULT_MODE, handle=None} +Instances of this class represent loaded shared libraries. +Functions in these libraries use the standard C calling +convention, and are assumed to return \code{int}. +\end{classdesc} + +\begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None} +Windows only: Instances of this class represent loaded shared +libraries, functions in these libraries use the \code{stdcall} +calling convention, and are assumed to return the windows specific +\class{HRESULT} code. \class{HRESULT} values contain information +specifying whether the function call failed or succeeded, together +with additional error code. If the return value signals a +failure, an \class{WindowsError} is automatically raised. +\end{classdesc} + +\begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None} +Windows only: Instances of this class represent loaded shared +libraries, functions in these libraries use the \code{stdcall} +calling convention, and are assumed to return \code{int} by default. + +On Windows CE only the standard calling convention is used, for +convenience the \class{WinDLL} and \class{OleDLL} use the standard calling +convention on this platform. +\end{classdesc} + +The Python GIL is released before calling any function exported by +these libraries, and reaquired afterwards. + +\begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None} +Instances of this class behave like \class{CDLL} instances, except +that the Python GIL is \emph{not} released during the function call, +and after the function execution the Python error flag is checked. +If the error flag is set, a Python exception is raised. + +Thus, this is only useful to call Python C api functions directly. +\end{classdesc} + +All these classes can be instantiated by calling them with at least +one argument, the pathname of the shared library. If you have an +existing handle to an already loaded shard library, it can be passed +as the \code{handle} named parameter, otherwise the underlying platforms +\code{dlopen} or \method{LoadLibrary} function is used to load the library +into the process, and to get a handle to it. + +The \var{mode} parameter can be used to specify how the library is +loaded. For details, consult the \code{dlopen(3)} manpage, on Windows, +\var{mode} is ignored. + +\begin{datadescni}{RTLD_GLOBAL} +Flag to use as \var{mode} parameter. On platforms where this flag +is not available, it is defined as the integer zero. +\end{datadescni} + +\begin{datadescni}{RTLD_LOCAL} +Flag to use as \var{mode} parameter. On platforms where this is not +available, it is the same as \var{RTLD{\_}GLOBAL}. +\end{datadescni} + +\begin{datadescni}{DEFAULT_MODE} +The default mode which is used to load shared libraries. On OSX +10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as +\var{RTLD{\_}LOCAL}. +\end{datadescni} + +Instances of these classes have no public methods, however +\method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions +exported by the shared library can be accessed as attributes of by +index. Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} +cache their result, so calling them repeatedly returns the same object +each time. + +The following public attributes are available, their name starts with +an underscore to not clash with exported function names: + +\begin{memberdesc}{_handle} +The system handle used to access the library. +\end{memberdesc} + +\begin{memberdesc}{_name} +The name of the library passed in the contructor. +\end{memberdesc} + +Shared libraries can also be loaded by using one of the prefabricated +objects, which are instances of the \class{LibraryLoader} class, either by +calling the \method{LoadLibrary} method, or by retrieving the library as +attribute of the loader instance. + +\begin{classdesc}{LibraryLoader}{dlltype} +Class which loads shared libraries. \code{dlltype} should be one +of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types. + +\method{{\_}{\_}getattr{\_}{\_}} has special behaviour: It allows to load a shared +library by accessing it as attribute of a library loader +instance. The result is cached, so repeated attribute accesses +return the same library each time. +\end{classdesc} + +\begin{methoddesc}{LoadLibrary}{name} +Load a shared library into the process and return it. This method +always returns a new instance of the library. +\end{methoddesc} + +These prefabricated library loaders are available: + +\begin{datadescni}{cdll} +Creates \class{CDLL} instances. +\end{datadescni} + +\begin{datadescni}{windll} +Windows only: Creates \class{WinDLL} instances. +\end{datadescni} + +\begin{datadescni}{oledll} +Windows only: Creates \class{OleDLL} instances. +\end{datadescni} + +\begin{datadescni}{pydll} +Creates \class{PyDLL} instances. +\end{datadescni} + +For accessing the C Python api directly, a ready-to-use Python shared +library object is available: + +\begin{datadescni}{pythonapi} +An instance of \class{PyDLL} that exposes Python C api functions as +attributes. Note that all these functions are assumed to return +integers, which is of course not always the truth, so you have to +assign the correct \member{restype} attribute to use these functions. +\end{datadescni} + + +\subsubsection{Foreign functions\label{ctypes-foreign-functions}} + +As explained in the previous section, foreign functions can be +accessed as attributes of loaded shared libraries. The function +objects created in this way by default accept any number of arguments, +accept any ctypes data instances as arguments, and return the default +result type specified by the library loader. They are instances of a +private class: + +\begin{classdesc*}{_FuncPtr} +Base class for C callable foreign functions. +\end{classdesc*} + +Instances of foreign functions are also C compatible data types; they +represent C function pointers. + +This behaviour can be customized by assigning to special attributes of +the foreign function object. + +\begin{memberdesc}{restype} +Assign a ctypes type to specify the result type of the foreign +function. Use \code{None} for \code{void} a function not returning +anything. + +It is possible to assign a callable Python object that is not a +ctypes type, in this case the function is assumed to return an +integer, and the callable will be called with this integer, +allowing to do further processing or error checking. Using this +is deprecated, for more flexible postprocessing or error checking +use a ctypes data type as \member{restype} and assign a callable to the +\member{errcheck} attribute. +\end{memberdesc} + +\begin{memberdesc}{argtypes} +Assign a tuple of ctypes types to specify the argument types that +the function accepts. Functions using the \code{stdcall} calling +convention can only be called with the same number of arguments as +the length of this tuple; functions using the C calling convention +accept additional, unspecified arguments as well. + +When a foreign function is called, each actual argument is passed +to the \method{from{\_}param} class method of the items in the +\member{argtypes} tuple, this method allows to adapt the actual +argument to an object that the foreign function accepts. For +example, a \class{c{\_}char{\_}p} item in the \member{argtypes} tuple will +convert a unicode string passed as argument into an byte string +using ctypes conversion rules. + +New: It is now possible to put items in argtypes which are not +ctypes types, but each item must have a \method{from{\_}param} method +which returns a value usable as argument (integer, string, ctypes +instance). This allows to define adapters that can adapt custom +objects as function parameters. +\end{memberdesc} + +\begin{memberdesc}{errcheck} +Assign a Python function or another callable to this attribute. +The callable will be called with three or more arguments: +\end{memberdesc} + +\begin{funcdescni}{callable}{result, func, arguments} +\code{result} is what the foreign function returns, as specified by the +\member{restype} attribute. + +\code{func} is the foreign function object itself, this allows to +reuse the same callable object to check or postprocess the results +of several functions. + +\code{arguments} is a tuple containing the parameters originally +passed to the function call, this allows to specialize the +behaviour on the arguments used. + +The object that this function returns will be returned from the +foreign function call, but it can also check the result value and +raise an exception if the foreign function call failed. +\end{funcdescni} + +\begin{excdesc}{ArgumentError()} +This exception is raised when a foreign function call cannot +convert one of the passed arguments. +\end{excdesc} + + +\subsubsection{Function prototypes\label{ctypes-function-prototypes}} + +Foreign functions can also be created by instantiating function +prototypes. Function prototypes are similar to function prototypes in +C; they describe a function (return type, argument types, calling +convention) without defining an implementation. The factory +functions must be called with the desired result type and the argument +types of the function. + +\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes} +The returned function prototype creates functions that use the +standard C calling convention. The function will release the GIL +during the call. +\end{funcdesc} + +\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes} +Windows only: The returned function prototype creates functions +that use the \code{stdcall} calling convention, except on Windows CE +where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}. The function +will release the GIL during the call. +\end{funcdesc} + +\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes} +The returned function prototype creates functions that use the +Python calling convention. The function will \emph{not} release the +GIL during the call. +\end{funcdesc} + +Function prototypes created by the factory functions can be +instantiated in different ways, depending on the type and number of +the parameters in the call. + +\begin{funcdescni}{prototype}{address} +Returns a foreign function at the specified address. +\end{funcdescni} + +\begin{funcdescni}{prototype}{callable} +Create a C callable function (a callback function) from a Python +\code{callable}. +\end{funcdescni} + +\begin{funcdescni}{prototype}{func_spec\optional{, paramflags}} +Returns a foreign function exported by a shared library. +\code{func{\_}spec} must be a 2-tuple \code{(name{\_}or{\_}ordinal, library)}. +The first item is the name of the exported function as string, or +the ordinal of the exported function as small integer. The second +item is the shared library instance. +\end{funcdescni} + +\begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}} +Returns a foreign function that will call a COM method. +\code{vtbl{\_}index} is the index into the virtual function table, a +small nonnegative integer. \var{name} is name of the COM method. +\var{iid} is an optional pointer to the interface identifier which +is used in extended error reporting. + +COM methods use a special calling convention: They require a +pointer to the COM interface as first argument, in addition to +those parameters that are specified in the \member{argtypes} tuple. +\end{funcdescni} + +The optional \var{paramflags} parameter creates foreign function +wrappers with much more functionality than the features described +above. + +\var{paramflags} must be a tuple of the same length as \member{argtypes}. + +Each item in this tuple contains further information about a +parameter, it must be a tuple containing 1, 2, or 3 items. + +The first item is an integer containing flags for the parameter: + +\begin{datadescni}{1} +Specifies an input parameter to the function. +\end{datadescni} + +\begin{datadescni}{2} +Output parameter. The foreign function fills in a value. +\end{datadescni} + +\begin{datadescni}{4} +Input parameter which defaults to the integer zero. +\end{datadescni} + +The optional second item is the parameter name as string. If this is +specified, the foreign function can be called with named parameters. + +The optional third item is the default value for this parameter. + +This example demonstrates how to wrap the Windows \code{MessageBoxA} +function so that it supports default parameters and named arguments. +The C declaration from the windows header file is this: +\begin{verbatim} +WINUSERAPI int WINAPI +MessageBoxA( + HWND hWnd , + LPCSTR lpText, + LPCSTR lpCaption, + UINT uType); +\end{verbatim} + +Here is the wrapping with \code{ctypes}: +\begin{quote} +\begin{verbatim}>>> from ctypes import c_int, WINFUNCTYPE, windll +>>> from ctypes.wintypes import HWND, LPCSTR, UINT +>>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, c_uint) +>>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) +>>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) +>>>\end{verbatim} +\end{quote} + +The MessageBox foreign function can now be called in these ways: +\begin{verbatim} +>>> MessageBox() +>>> MessageBox(text="Spam, spam, spam") +>>> MessageBox(flags=2, text="foo bar") +>>> +\end{verbatim} + +A second example demonstrates output parameters. The win32 +\code{GetWindowRect} function retrieves the dimensions of a specified +window by copying them into \code{RECT} structure that the caller has to +supply. Here is the C declaration: +\begin{verbatim} +WINUSERAPI BOOL WINAPI +GetWindowRect( + HWND hWnd, + LPRECT lpRect); +\end{verbatim} + +Here is the wrapping with \code{ctypes}: +\begin{quote} +\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll +>>> from ctypes.wintypes import BOOL, HWND, RECT +>>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) +>>> paramflags = (1, "hwnd"), (2, "lprect") +>>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags) +>>>\end{verbatim} +\end{quote} + +Functions with output parameters will automatically return the output +parameter value if there is a single one, or a tuple containing the +output parameter values when there are more than one, so the +GetWindowRect function now returns a RECT instance, when called. + +Output parameters can be combined with the \member{errcheck} protocol to do +further output processing and error checking. The win32 +\code{GetWindowRect} api function returns a \code{BOOL} to signal success or +failure, so this function could do the error checking, and raises an +exception when the api call failed: +\begin{verbatim} +>>> def errcheck(result, func, args): +... if not result: +... raise WinError() +... return args +>>> GetWindowRect.errcheck = errcheck +>>> +\end{verbatim} + +If the \member{errcheck} function returns the argument tuple it receives +unchanged, \code{ctypes} continues the normal processing it does on the +output parameters. If you want to return a tuple of window +coordinates instead of a \code{RECT} instance, you can retrieve the +fields in the function and return them instead, the normal processing +will no longer take place: +\begin{verbatim} +>>> def errcheck(result, func, args): +... if not result: +... raise WinError() +... rc = args[1] +... return rc.left, rc.top, rc.bottom, rc.right +>>> +>>> GetWindowRect.errcheck = errcheck +>>> +\end{verbatim} + + +\subsubsection{Utility functions\label{ctypes-utility-functions}} + +\begin{funcdesc}{addressof}{obj} +Returns the address of the memory buffer as integer. \code{obj} must +be an instance of a ctypes type. +\end{funcdesc} + +\begin{funcdesc}{alignment}{obj_or_type} +Returns the alignment requirements of a ctypes type. +\code{obj{\_}or{\_}type} must be a ctypes type or instance. +\end{funcdesc} + +\begin{funcdesc}{byref}{obj} +Returns a light-weight pointer to \code{obj}, which must be an +instance of a ctypes type. The returned object can only be used as +a foreign function call parameter. It behaves similar to +\code{pointer(obj)}, but the construction is a lot faster. +\end{funcdesc} + +\begin{funcdesc}{cast}{obj, type} +This function is similar to the cast operator in C. It returns a +new instance of \code{type} which points to the same memory block as +\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an +object that can be interpreted as a pointer. +\end{funcdesc} + +\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}} +This function creates a mutable character buffer. The returned +object is a ctypes array of \class{c{\_}char}. + +\code{init{\_}or{\_}size} must be an integer which specifies the size of +the array, or a string which will be used to initialize the array +items. + +If a string is specified as first argument, the buffer is made one +item larger than the length of the string so that the last element +in the array is a NUL termination character. An integer can be +passed as second argument which allows to specify the size of the +array if the length of the string should not be used. + +If the first parameter is a unicode string, it is converted into +an 8-bit string according to ctypes conversion rules. +\end{funcdesc} + +\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}} +This function creates a mutable unicode character buffer. The +returned object is a ctypes array of \class{c{\_}wchar}. + +\code{init{\_}or{\_}size} must be an integer which specifies the size of +the array, or a unicode string which will be used to initialize +the array items. + +If a unicode string is specified as first argument, the buffer is +made one item larger than the length of the string so that the +last element in the array is a NUL termination character. An +integer can be passed as second argument which allows to specify +the size of the array if the length of the string should not be +used. + +If the first parameter is a 8-bit string, it is converted into an +unicode string according to ctypes conversion rules. +\end{funcdesc} + +\begin{funcdesc}{DllCanUnloadNow}{} +Windows only: This function is a hook which allows to implement +inprocess COM servers with ctypes. It is called from the +DllCanUnloadNow function that the {\_}ctypes extension dll exports. +\end{funcdesc} + +\begin{funcdesc}{DllGetClassObject}{} +Windows only: This function is a hook which allows to implement +inprocess COM servers with ctypes. It is called from the +DllGetClassObject function that the \code{{\_}ctypes} extension dll exports. +\end{funcdesc} + +\begin{funcdesc}{FormatError}{\optional{code}} +Windows only: Returns a textual description of the error code. If +no error code is specified, the last error code is used by calling +the Windows api function GetLastError. +\end{funcdesc} + +\begin{funcdesc}{GetLastError}{} +Windows only: Returns the last error code set by Windows in the +calling thread. +\end{funcdesc} + +\begin{funcdesc}{memmove}{dst, src, count} +Same as the standard C memmove library function: copies \var{count} +bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be +integers or ctypes instances that can be converted to pointers. +\end{funcdesc} + +\begin{funcdesc}{memset}{dst, c, count} +Same as the standard C memset library function: fills the memory +block at address \var{dst} with \var{count} bytes of value +\var{c}. \var{dst} must be an integer specifying an address, or a +ctypes instance. +\end{funcdesc} + +\begin{funcdesc}{POINTER}{type} +This factory function creates and returns a new ctypes pointer +type. Pointer types are cached an reused internally, so calling +this function repeatedly is cheap. type must be a ctypes type. +\end{funcdesc} + +\begin{funcdesc}{pointer}{obj} +This function creates a new pointer instance, pointing to +\code{obj}. The returned object is of the type POINTER(type(obj)). + +Note: If you just want to pass a pointer to an object to a foreign +function call, you should use \code{byref(obj)} which is much faster. +\end{funcdesc} + +\begin{funcdesc}{resize}{obj, size} +This function resizes the internal memory buffer of obj, which +must be an instance of a ctypes type. It is not possible to make +the buffer smaller than the native size of the objects type, as +given by sizeof(type(obj)), but it is possible to enlarge the +buffer. +\end{funcdesc} + +\begin{funcdesc}{set_conversion_mode}{encoding, errors} +This function sets the rules that ctypes objects use when +converting between 8-bit strings and unicode strings. encoding +must be a string specifying an encoding, like \code{'utf-8'} or +\code{'mbcs'}, errors must be a string specifying the error handling +on encoding/decoding errors. Examples of possible values are +\code{"strict"}, \code{"replace"}, or \code{"ignore"}. + +\code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous +conversion rules. On windows, the initial conversion rules are +\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}. +\end{funcdesc} + +\begin{funcdesc}{sizeof}{obj_or_type} +Returns the size in bytes of a ctypes type or instance memory +buffer. Does the same as the C \code{sizeof()} function. +\end{funcdesc} + +\begin{funcdesc}{string_at}{address\optional{, size}} +This function returns the string starting at memory address +address. If size is specified, it is used as size, otherwise the +string is assumed to be zero-terminated. +\end{funcdesc} + +\begin{funcdesc}{WinError}{code=None, descr=None} +Windows only: this function is probably the worst-named thing in +ctypes. It creates an instance of WindowsError. If \var{code} is not +specified, \code{GetLastError} is called to determine the error +code. If \code{descr} is not spcified, \function{FormatError} is called to +get a textual description of the error. +\end{funcdesc} + +\begin{funcdesc}{wstring_at}{address} +This function returns the wide character string starting at memory +address \code{address} as unicode string. If \code{size} is specified, +it is used as the number of characters of the string, otherwise +the string is assumed to be zero-terminated. +\end{funcdesc} + + +\subsubsection{Data types\label{ctypes-data-types}} + +\begin{classdesc*}{_CData} +This non-public class is the common base class of all ctypes data +types. Among other things, all ctypes type instances contain a +memory block that hold C compatible data; the address of the +memory block is returned by the \code{addressof()} helper function. +Another instance variable is exposed as \member{{\_}objects}; this +contains other Python objects that need to be kept alive in case +the memory block contains pointers. +\end{classdesc*} + +Common methods of ctypes data types, these are all class methods (to +be exact, they are methods of the metaclass): + +\begin{methoddesc}{from_address}{address} +This method returns a ctypes type instance using the memory +specified by address which must be an integer. +\end{methoddesc} + +\begin{methoddesc}{from_param}{obj} +This method adapts obj to a ctypes type. It is called with the +actual object used in a foreign function call, when the type is +present in the foreign functions \member{argtypes} tuple; it must +return an object that can be used as function call parameter. + +All ctypes data types have a default implementation of this +classmethod, normally it returns \code{obj} if that is an instance of +the type. Some types accept other objects as well. +\end{methoddesc} + +\begin{methoddesc}{in_dll}{name, library} +This method returns a ctypes type instance exported by a shared +library. \var{name} is the name of the symbol that exports the data, +\code{library} is the loaded shared library. +\end{methoddesc} + +Common instance variables of ctypes data types: + +\begin{memberdesc}{_b_base_} +Sometimes ctypes data instances do not own the memory block they +contain, instead they share part of the memory block of a base +object. The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes +object that owns the memory block. +\end{memberdesc} + +\begin{memberdesc}{_b_needsfree_} +This readonly variable is true when the ctypes data instance has +allocated the memory block itself, false otherwise. +\end{memberdesc} + +\begin{memberdesc}{_objects} +This member is either \code{None} or a dictionary containing Python +objects that need to be kept alive so that the memory block +contents is kept valid. This object is only exposed for +debugging; never modify the contents of this dictionary. +\end{memberdesc} + + +\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}} + +\begin{classdesc*}{_SimpleCData} +This non-public class is the base class of all fundamental ctypes +data types. It is mentioned here because it contains the common +attributes of the fundamental ctypes data types. \code{{\_}SimpleCData} +is a subclass of \code{{\_}CData}, so it inherits their methods and +attributes. +\end{classdesc*} + +Instances have a single attribute: + +\begin{memberdesc}{value} +This attribute contains the actual value of the instance. For +integer and pointer types, it is an integer, for character types, +it is a single character string, for character pointer types it +is a Python string or unicode string. + +When the \code{value} attribute is retrieved from a ctypes instance, +usually a new object is returned each time. \code{ctypes} does \emph{not} +implement original object return, always a new object is +constructed. The same is true for all other ctypes object +instances. +\end{memberdesc} + +Fundamental data types, when returned as foreign function call +results, or, for example, by retrieving structure field members or +array items, are transparently converted to native Python types. In +other words, if a foreign function has a \member{restype} of \class{c{\_}char{\_}p}, +you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p} +instance. + +Subclasses of fundamental data types do \emph{not} inherit this behaviour. +So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p}, +you will receive an instance of this subclass from the function call. +Of course, you can get the value of the pointer by accessing the +\code{value} attribute. + +These are the fundamental ctypes data types: + +\begin{classdesc*}{c_byte} +Represents the C signed char datatype, and interprets the value as +small integer. The constructor accepts an optional integer +initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_char} +Represents the C char datatype, and interprets the value as a single +character. The constructor accepts an optional string initializer, +the length of the string must be exactly one character. +\end{classdesc*} + +\begin{classdesc*}{c_char_p} +Represents the C char * datatype, which must be a pointer to a +zero-terminated string. The constructor accepts an integer +address, or a string. +\end{classdesc*} + +\begin{classdesc*}{c_double} +Represents the C double datatype. The constructor accepts an +optional float initializer. +\end{classdesc*} + +\begin{classdesc*}{c_float} +Represents the C double datatype. The constructor accepts an +optional float initializer. +\end{classdesc*} + +\begin{classdesc*}{c_int} +Represents the C signed int datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. On +platforms where \code{sizeof(int) == sizeof(long)} it is an alias to +\class{c{\_}long}. +\end{classdesc*} + +\begin{classdesc*}{c_int8} +Represents the C 8-bit \code{signed int} datatype. Usually an alias for +\class{c{\_}byte}. +\end{classdesc*} + +\begin{classdesc*}{c_int16} +Represents the C 16-bit signed int datatype. Usually an alias for +\class{c{\_}short}. +\end{classdesc*} + +\begin{classdesc*}{c_int32} +Represents the C 32-bit signed int datatype. Usually an alias for +\class{c{\_}int}. +\end{classdesc*} + +\begin{classdesc*}{c_int64} +Represents the C 64-bit \code{signed int} datatype. Usually an alias +for \class{c{\_}longlong}. +\end{classdesc*} + +\begin{classdesc*}{c_long} +Represents the C \code{signed long} datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_longlong} +Represents the C \code{signed long long} datatype. The constructor accepts +an optional integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_short} +Represents the C \code{signed short} datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_size_t} +Represents the C \code{size{\_}t} datatype. +\end{classdesc*} + +\begin{classdesc*}{c_ubyte} +Represents the C \code{unsigned char} datatype, it interprets the +value as small integer. The constructor accepts an optional +integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_uint} +Represents the C \code{unsigned int} datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. On +platforms where \code{sizeof(int) == sizeof(long)} it is an alias for +\class{c{\_}ulong}. +\end{classdesc*} + +\begin{classdesc*}{c_uint8} +Represents the C 8-bit unsigned int datatype. Usually an alias for +\class{c{\_}ubyte}. +\end{classdesc*} + +\begin{classdesc*}{c_uint16} +Represents the C 16-bit unsigned int datatype. Usually an alias for +\class{c{\_}ushort}. +\end{classdesc*} + +\begin{classdesc*}{c_uint32} +Represents the C 32-bit unsigned int datatype. Usually an alias for +\class{c{\_}uint}. +\end{classdesc*} + +\begin{classdesc*}{c_uint64} +Represents the C 64-bit unsigned int datatype. Usually an alias for +\class{c{\_}ulonglong}. +\end{classdesc*} + +\begin{classdesc*}{c_ulong} +Represents the C \code{unsigned long} datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_ulonglong} +Represents the C \code{unsigned long long} datatype. The constructor +accepts an optional integer initializer; no overflow checking is +done. +\end{classdesc*} + +\begin{classdesc*}{c_ushort} +Represents the C \code{unsigned short} datatype. The constructor accepts an +optional integer initializer; no overflow checking is done. +\end{classdesc*} + +\begin{classdesc*}{c_void_p} +Represents the C \code{void *} type. The value is represented as +integer. The constructor accepts an optional integer initializer. +\end{classdesc*} + +\begin{classdesc*}{c_wchar} +Represents the C \code{wchar{\_}t} datatype, and interprets the value as a +single character unicode string. The constructor accepts an +optional string initializer, the length of the string must be +exactly one character. +\end{classdesc*} + +\begin{classdesc*}{c_wchar_p} +Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to +a zero-terminated wide character string. The constructor accepts +an integer address, or a string. +\end{classdesc*} + +\begin{classdesc*}{HRESULT} +Windows only: Represents a \class{HRESULT} value, which contains success +or error information for a function or method call. +\end{classdesc*} + +\begin{classdesc*}{py_object} +Represents the C \code{PyObject *} datatype. +\end{classdesc*} + +The \code{ctypes.wintypes} module provides quite some other Windows +specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}. +Some useful structures like \code{MSG} or \code{RECT} are also defined. + + +\subsubsection{Structured data types\label{ctypes-structured-data-types}} + +\begin{classdesc}{Union}{*args, **kw} +Abstract base class for unions in native byte order. +\end{classdesc} + +\begin{classdesc}{BigEndianStructure}{*args, **kw} +Abstract base class for structures in \emph{big endian} byte order. +\end{classdesc} + +\begin{classdesc}{LittleEndianStructure}{*args, **kw} +Abstract base class for structures in \emph{little endian} byte order. +\end{classdesc} + +Structures with non-native byte order cannot contain pointer type +fields, or any other data types containing pointer type fields. + +\begin{classdesc}{Structure}{*args, **kw} +Abstract base class for structures in \emph{native} byte order. +\end{classdesc} + +Concrete structure and union types must be created by subclassing one +of these types, and at least define a \member{{\_}fields{\_}} class variable. +\code{ctypes} will create descriptors which allow reading and writing the +fields by direct attribute accesses. These are the + +\begin{memberdesc}{_fields_} +A sequence defining the structure fields. The items must be +2-tuples or 3-tuples. The first item is the name of the field, +the second item specifies the type of the field; it can be any +ctypes data type. + +For integer type fields, a third optional item can be given. It +must be a small positive integer defining the bit width of the +field. + +Field names must be unique within one structure or union. This is +not checked, only one field can be accessed when names are +repeated. + +It is possible to define the \member{{\_}fields{\_}} class variable \emph{after} +the class statement that defines the Structure subclass, this +allows to create data types that directly or indirectly reference +themselves: +\begin{verbatim} +class List(Structure): + pass +List._fields_ = [("pnext", POINTER(List)), + ... + ] +\end{verbatim} + +The \member{{\_}fields{\_}} class variable must, however, be defined before +the type is first used (an instance is created, \code{sizeof()} is +called on it, and so on). Later assignments to the \member{{\_}fields{\_}} +class variable will raise an AttributeError. + +Structure and union subclass constructors accept both positional +and named arguments. Positional arguments are used to initialize +the fields in the same order as they appear in the \member{{\_}fields{\_}} +definition, named arguments are used to initialize the fields with +the corresponding name. + +It is possible to defined sub-subclasses of structure types, they +inherit the fields of the base class plus the \member{{\_}fields{\_}} defined +in the sub-subclass, if any. +\end{memberdesc} + +\begin{memberdesc}{_pack_} +An optional small integer that allows to override the alignment of +structure fields in the instance. \member{{\_}pack{\_}} must already be +defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no +effect. +\end{memberdesc} + +\begin{memberdesc}{_anonymous_} +An optional sequence that lists the names of unnamed (anonymous) +fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}} +is assigned, otherwise it will have no effect. + +The fields listed in this variable must be structure or union type +fields. \code{ctypes} will create descriptors in the structure type +that allows to access the nested fields directly, without the need +to create the structure or union field. + +Here is an example type (Windows): +\begin{verbatim} +class _U(Union): + _fields_ = [("lptdesc", POINTER(TYPEDESC)), + ("lpadesc", POINTER(ARRAYDESC)), + ("hreftype", HREFTYPE)] + +class TYPEDESC(Structure): + _fields_ = [("u", _U), + ("vt", VARTYPE)] + + _anonymous_ = ("u",) +\end{verbatim} + +The \code{TYPEDESC} structure describes a COM data type, the \code{vt} +field specifies which one of the union fields is valid. Since the +\code{u} field is defined as anonymous field, it is now possible to +access the members directly off the TYPEDESC instance. +\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former +is faster since it does not need to create a temporary union +instance: +\begin{verbatim} +td = TYPEDESC() +td.vt = VT_PTR +td.lptdesc = POINTER(some_type) +td.u.lptdesc = POINTER(some_type) +\end{verbatim} +\end{memberdesc} + +It is possible to defined sub-subclasses of structures, they inherit +the fields of the base class. If the subclass definition has a +separate \member{{\_}fields{\_}} variable, the fields specified in this are +appended to the fields of the base class. + +Structure and union constructors accept both positional and +keyword arguments. Positional arguments are used to initialize member +fields in the same order as they are appear in \member{{\_}fields{\_}}. Keyword +arguments in the constructor are interpreted as attribute assignments, +so they will initialize \member{{\_}fields{\_}} with the same name, or create new +attributes for names not present in \member{{\_}fields{\_}}. + + +\subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}} + +XXX + diff --git a/Doc/lib/libctypesref.tex b/Doc/lib/libctypesref.tex deleted file mode 100644 index 6d950f4..0000000 --- a/Doc/lib/libctypesref.tex +++ /dev/null @@ -1,457 +0,0 @@ -\subsection{ctypes reference\label{ctypes-reference}} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% functions -\subsubsection{ctypes functions} - -\begin{funcdesc}{addressof}{obj} -Returns the address of the memory buffer as integer. \var{obj} must -be an instance of a ctypes type. -\end{funcdesc} - -\begin{funcdesc}{alignment}{obj_or_type} -Returns the alignment requirements of a ctypes type. -\var{obj_or_type} must be a ctypes type or an instance. -\end{funcdesc} - -\begin{excclassdesc}{ArgumentError}{} -This exception is raised when a foreign function call cannot convert -one of the passed arguments. -\end{excclassdesc} - -\begin{funcdesc}{byref}{obj} -Returns a light-weight pointer to \var{obj}, which must be an instance -of a ctypes type. The returned object can only be used as a foreign -function call parameter. It behaves similar to \code{pointer(obj)}, -but the construction is a lot faster. -\end{funcdesc} - -\begin{funcdesc}{cast}{obj, type} -This function is similar to the cast operator in C. It returns a new -instance of \var{type} which points to the same memory block as -\code{obj}. \code{type} must be a pointer type, and \code{obj} - must be an object that can be interpreted as a pointer. -\end{funcdesc} - -% XXX separate section for CFUNCTYPE, WINFUNCTYPE, PYFUNCTYPE? - -\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes} -This is a factory function that returns a function prototype. The -function prototype describes a function that has a result type of -\code{restype}, and accepts arguments as specified by \code{argtypes}. -The function prototype can be used to construct several kinds of -functions, depending on how the prototype is called. - -The prototypes returned by \code{CFUNCTYPE} or \code{PYFUNCTYPE} -create functions that use the standard C calling convention, -prototypes returned from \code{WINFUNCTYPE} (on Windows) use the -\code{__stdcall} calling convention. - -Functions created by calling the \code{CFUNCTYPE} and -\code{WINFUNCTYPE} prototypes release the Python GIL -before entering the foreign function, and acquire it back after -leaving the function code. - -% XXX differences between CFUNCTYPE / WINFUNCTYPE / PYFUNCTYPE - -\end{funcdesc} - -\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}} -This function creates a mutable character buffer. The returned object -is a ctypes array of \code{c_char}. - -\var{init_or_size} must be an integer which specifies the size of the -array, or a string which will be used to initialize the array items. - -If a string is specified as first argument, the buffer is made one -item larger than the length of the string so that the last element in -the array is a NUL termination character. An integer can be passed as -second argument which allows to specify the size of the array if the -length of the string should not be used. - -If the first parameter is a unicode string, it is converted into an -8-bit string according to ctypes conversion rules. -\end{funcdesc} - -\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}} -This function creates a mutable unicode character buffer. The -returned object is a ctypes array of \code{c_wchar}. - -\var{init_or_size} must be an integer which specifies the size of the -array, or a unicode string which will be used to initialize the array -items. - -If a unicode string is specified as first argument, the buffer is made -one item larger than the length of the string so that the last element -in the array is a NUL termination character. An integer can be passed -as second argument which allows to specify the size of the array if -the length of the string should not be used. - -If the first parameter is a 8-bit string, it is converted into an -unicode string according to ctypes conversion rules. -\end{funcdesc} - -\begin{funcdesc}{DllCanUnloadNow}{} -Windows only: This function is a hook which allows to implement -inprocess COM servers with ctypes. It is called from the -\code{DllCanUnloadNow} function that the \code{_ctypes} -extension dll exports. -\end{funcdesc} - -\begin{funcdesc}{DllGetClassObject}{} -Windows only: This function is a hook which allows to implement -inprocess COM servers with ctypes. It is called from the -\code{DllGetClassObject} function that the \code{_ctypes} -extension dll exports. -\end{funcdesc} - -\begin{funcdesc}{FormatError}{\optional{code}} -Windows only: Returns a textual description of the error code. If no -error code is specified, the last error code is used by calling the -Windows api function \code{GetLastError}. -\end{funcdesc} - -\begin{funcdesc}{GetLastError}{} -Windows only: Returns the last error code set by Windows in the -calling thread. -\end{funcdesc} - -\begin{funcdesc}{memmove}{dst, src, count} -Same as the standard C \code{memmove} library function: copies -\var{count} bytes from \code{src} to \code{dst}. \code{dst} and -\code{src} must be integers or ctypes instances that can be converted to pointers. -\end{funcdesc} - -\begin{funcdesc}{memset}{dst, c, count} -Same as the standard C \code{memset} library function: fills the -memory clock at address \code{dst} with \var{count} bytes of value -\var{c}. \var{dst} must be an integer specifying an address, or a ctypes instance. -\end{funcdesc} - -\begin{funcdesc}{POINTER}{type} -This factory function creates and returns a new ctypes pointer type. -Pointer types are cached an reused internally, so calling this -function repeatedly is cheap. \var{type} must be a ctypes type. -\end{funcdesc} - -\begin{funcdesc}{pointer}{obj} -This function creates a new pointer instance, pointing to \var{obj}. -The returned object is of the type \code{POINTER(type(obj))}. - -Note: If you just want to pass a pointer to an object to a foreign -function call, you should use \code{byref(obj)} which is much faster. -\end{funcdesc} - -\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes} -\end{funcdesc} - -\begin{funcdesc}{pythonapi}{} -\end{funcdesc} - -\begin{funcdesc}{resize}{obj, size} -This function resizes the internal memory buffer of \var{obj}, which -must be an instance of a ctypes type. It is not possible to make the -buffer smaller than the native size of the objects type, as given by -\code{sizeof(type(obj))}, but it is possible to enlarge the buffer. -\end{funcdesc} - -\begin{funcdesc}{set_conversion_mode}{encoding, errors} -This function sets the rules that ctypes objects use when converting -between 8-bit strings and unicode strings. \var{encoding} must be a -string specifying an encoding, like 'utf-8' or 'mbcs', \var{errors} -must be a string specifying the error handling on encoding/decoding -errors. Examples of possible values are ``strict'', ``replace'', or -``ignore''. - -\code{set_conversion_mode} returns a 2-tuple containing the previous -conversion rules. On windows, the initial conversion rules are -\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}. -\end{funcdesc} - -\begin{funcdesc}{sizeof}{obj_or_type} -Returns the size in bytes of a ctypes type or instance memory buffer. -Does the same as the C sizeof() function. -\end{funcdesc} - -\begin{funcdesc}{string_at}{address\optional{size}} -This function returns the string starting at memory address -\var{address}. If \var{size} is specified, it is used as size, -otherwise the string is assumed to be zero-terminated. -\end{funcdesc} - -\begin{funcdesc}{WinError}{code=None, descr=None} -Windows only: this function is probably the worst-named thing in -ctypes. It creates an instance of \code{WindowsError}. If \var{code} -is not specified, \code{GetLastError} is called to determine the error -code. If \var{descr} is not spcified, \var{FormatError} is called to -get a textual description of the error. -\end{funcdesc} - -\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes} -\end{funcdesc} - -\begin{funcdesc}{wstring_at}{address} -This function returns the wide character string starting at memory -address \var{address} as unicode string. If \var{size} is specified, -it is used as size, otherwise the string is assumed to be -zero-terminated. -\end{funcdesc} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% data types -\subsubsection{data types} - -ctypes defines a lot of C compatible datatypes, and also allows to -define your own types. Among other things, a ctypes type instance -holds a memory block that contains C compatible data. - -\begin{classdesc}{_ctypes._CData}{} -This non-public class is the base class of all ctypes data types. It -is mentioned here because it contains the common methods of the ctypes -data types. -\end{classdesc} - -Common methods of ctypes data types, these are all class methods (to -be exact, they are methods of the metaclass): - -\begin{methoddesc}{from_address}{address} -This method returns a ctypes type instance using the memory specified -by \code{address}. -\end{methoddesc} - -\begin{methoddesc}{from_param}{obj} -This method adapts \code{obj} to a ctypes type. -\end{methoddesc} - -\begin{methoddesc}{in_dll}{name, library} -This method returns a ctypes type instance exported by a shared -library. \var{name} is the name of the symbol that exports the data, -\var{library} is the loaded shared library. -\end{methoddesc} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% simple data types -\subsubsection{simple data types} - -\begin{classdesc}{_ctypes._SimpleCData}{} -This non-public class is the base class of all ctypes data types. It -is mentioned here because it contains the common attributes of the -ctypes data types. -\end{classdesc} - -\begin{memberdesc}{value} -This attribute contains the actual value of the instance. For integer -types, it is an integer. -\end{memberdesc} - -Here are the simple ctypes data types: - -\begin{classdesc}{c_byte}{\optional{value}} -Represents a C \code{signed char} datatype, and interprets the value -as small integer. The constructor accepts an optional integer -initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_char}{\optional{value}} -Represents a C \code{char} datatype, and interprets the value as a -single character. The constructor accepts an optional string -initializer, the length of the string must be exactly one character. -\end{classdesc} - -\begin{classdesc}{c_char_p}{\optional{value}} -Represents a C \code{char *} datatype, which must be a pointer to a -zero-terminated string. The constructor accepts an integer address, -or a string. -% XXX Explain the difference to POINTER(c_char) -\end{classdesc} - -\begin{classdesc}{c_double}{\optional{value}} -Represents a C \code{double} datatype. The constructor accepts an -optional float initializer. -\end{classdesc} - -\begin{classdesc}{c_float}{\optional{value}} -Represents a C \code{double} datatype. The constructor accepts an -optional float initializer. -\end{classdesc} - -\begin{classdesc}{c_int}{\optional{value}} -Represents a C \code{signed int} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. On -platforms where \code{sizeof(int) == sizeof(long)} \var{c_int} is an -alias to \var{c_long}. -\end{classdesc} - -\begin{classdesc}{c_int16}{\optional{value}} -Represents a C 16-bit \code{signed int} datatype. Usually an alias -for \var{c_short}. -\end{classdesc} - -\begin{classdesc}{c_int32}{\optional{value}} -Represents a C 32-bit \code{signed int} datatype. Usually an alias -for \code{c_int}. -\end{classdesc} - -\begin{classdesc}{c_int64}{\optional{value}} -Represents a C 64-bit \code{signed int} datatype. Usually an alias -for \code{c_longlong}. -\end{classdesc} - -\begin{classdesc}{c_int8}{\optional{value}} -Represents a C 8-bit \code{signed int} datatype. Usually an alias for \code{c_byte}. -\end{classdesc} - -\begin{classdesc}{c_long}{\optional{value}} -Represents a C \code{signed long} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_longlong}{\optional{value}} -Represents a C \code{signed long long} datatype. The constructor -accepts an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_short}{\optional{value}} -Represents a C \code{signed short} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_size_t}{\optional{value}} -Represents a C \code{size_t} datatype. -\end{classdesc} - -\begin{classdesc}{c_ubyte}{\optional{value}} -Represents a C \code{unsigned char} datatype, and interprets the value -as small integer. The constructor accepts an optional integer -initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_uint}{\optional{value}} -Represents a C \code{unsigned int} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. On -platforms where \code{sizeof(int) == sizeof(long)} \var{c_int} is an -alias to \var{c_long}. -\end{classdesc} - -\begin{classdesc}{c_uint16}{\optional{value}} -Represents a C 16-bit \code{unsigned int} datatype. Usually an alias -for \code{c_ushort}. -\end{classdesc} - -\begin{classdesc}{c_uint32}{\optional{value}} -Represents a C 32-bit \code{unsigned int} datatype. Usually an alias -for \code{c_uint}. -\end{classdesc} - -\begin{classdesc}{c_uint64}{\optional{value}} -Represents a C 64-bit \code{unsigned int} datatype. Usually an alias -for \code{c_ulonglong}. -\end{classdesc} - -\begin{classdesc}{c_uint8}{\optional{value}} -Represents a C 8-bit \code{unsigned int} datatype. Usually an alias -for \code{c_ubyte}. -\end{classdesc} - -\begin{classdesc}{c_ulong}{\optional{value}} -Represents a C \code{unsigned long} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_ulonglong}{\optional{value}} -Represents a C \code{unsigned long long} datatype. The constructor -accepts an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_ushort}{\optional{value}} -Represents a C \code{unsigned short} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. -\end{classdesc} - -\begin{classdesc}{c_void_p}{\optional{value}} -Represents a C \code{void *} type. The value is represented as -integer. The constructor accepts an optional integer initializer. -\end{classdesc} - -\begin{classdesc}{c_wchar}{\optional{value}} -Represents a C \code{wchar_t} datatype, and interprets the value as a -single character unicode string. The constructor accepts an optional -string initializer, the length of the string must be exactly one -character. -\end{classdesc} - -\begin{classdesc}{c_wchar_p}{\optional{value}} -Represents a C \code{wchar_t *} datatype, which must be a pointer to a -zero-terminated wide character string. The constructor accepts an -integer address, or a string. -% XXX Explain the difference to POINTER(c_wchar) -\end{classdesc} - -\begin{classdesc}{HRESULT}{} -Windows only: Represents a \code{HRESULT} value, which contains -success or error information for a function or method call. -\end{classdesc} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% structured data types -\subsubsection{structured data types} - -\begin{classdesc}{BigEndianStructure}{} -\end{classdesc} - -\begin{classdesc}{LittleEndianStructure}{} -\end{classdesc} - -\begin{classdesc}{Structure}{} -Base class for Structure data types. - -\end{classdesc} - -\begin{classdesc}{Union}{} -\end{classdesc} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% libraries -\subsubsection{libraries} - -\begin{classdesc}{CDLL}{name, mode=RTLD_LOCAL, handle=None} -\end{classdesc} - -\begin{datadesc}{cdll} -\end{datadesc} - -\begin{classdesc}{LibraryLoader}{dlltype} - -\begin{memberdesc}{LoadLibrary}{name, mode=RTLD_LOCAL, handle=None} -\end{memberdesc} - -\end{classdesc} - -\begin{classdesc}{OleDLL}{name, mode=RTLD_LOCAL, handle=None} -\end{classdesc} - -\begin{datadesc}{oledll} -\end{datadesc} - -\begin{classdesc}{py_object}{} -\end{classdesc} - -\begin{classdesc}{PyDLL}{name, mode=RTLD_LOCAL, handle=None} -\end{classdesc} - -\begin{datadesc}{pydll}{} -\end{datadesc} - -\begin{datadesc}{RTLD_GLOBAL} -\end{datadesc} - -\begin{datadesc}{RTLD_LOCAL} -\end{datadesc} - -\begin{classdesc}{WinDLL}{name, mode=RTLD_LOCAL, handle=None} -\end{classdesc} - -\begin{datadesc}{windll} -\end{datadesc} - diff --git a/Doc/lib/libdifflib.tex b/Doc/lib/libdifflib.tex index 765accc..acb5ed1 100644 --- a/Doc/lib/libdifflib.tex +++ b/Doc/lib/libdifflib.tex @@ -419,6 +419,16 @@ of the other sequences. len(\var{b}), 0)}. It is the only triple with \code{\var{n} == 0}. % Explain why a dummy is used! + If + \code{(\var{i}, \var{j}, \var{n})} and + \code{(\var{i'}, \var{j'}, \var{n'})} are adjacent triples in the list, + and the second is not the last triple in the list, then + \code{\var{i}+\var{n} != \var{i'}} or + \code{\var{j}+\var{n} != \var{j'}}; in other words, adjacent triples + always describe non-adjacent equal blocks. + \versionchanged[The guarantee that adjacent triples always describe + non-adjacent blocks was implemented]{2.5} + \begin{verbatim} >>> s = SequenceMatcher(None, "abxcd", "abcd") >>> s.get_matching_blocks() diff --git a/Doc/lib/libetree.tex b/Doc/lib/libetree.tex new file mode 100644 index 0000000..1f29887 --- /dev/null +++ b/Doc/lib/libetree.tex @@ -0,0 +1,367 @@ +\section{\module{elementtree} --- The xml.etree.ElementTree Module} +\declaremodule{standard}{elementtree} +\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} +\modulesynopsis{This module provides implementations +of the Element and ElementTree types, plus support classes. + +A C version of this API is available as xml.etree.cElementTree.} +\versionadded{2.5} + + +\subsection{Overview\label{elementtree-overview}} + +The Element type is a flexible container object, designed to store +hierarchical data structures in memory. The type can be described as a +cross between a list and a dictionary. + +Each element has a number of properties associated with it: +\begin{itemize} +\item {} +a tag which is a string identifying what kind of data +this element represents (the element type, in other words). + +\item {} +a number of attributes, stored in a Python dictionary. + +\item {} +a text string. + +\item {} +an optional tail string. + +\item {} +a number of child elements, stored in a Python sequence + +\end{itemize} + +To create an element instance, use the Element or SubElement factory +functions. + +The ElementTree class can be used to wrap an element +structure, and convert it from and to XML. + + +\subsection{Functions\label{elementtree-functions}} + +\begin{funcdesc}{Comment}{\optional{text}} +Comment element factory. This factory function creates a special +element that will be serialized as an XML comment. +The comment string can be either an 8-bit ASCII string or a Unicode +string. +\var{text} is a string containing the comment string. + +\begin{datadescni}{Returns:} +An element instance, representing a comment. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{dump}{elem} +Writes an element tree or element structure to sys.stdout. This +function should be used for debugging only. + +The exact output format is implementation dependent. In this +version, it's written as an ordinary XML file. + +\var{elem} is an element tree or an individual element. +\end{funcdesc} + +\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}} +Element factory. This function returns an object implementing the +standard Element interface. The exact class or type of that object +is implementation dependent, but it will always be compatible with +the {\_}ElementInterface class in this module. + +The element name, attribute names, and attribute values can be +either 8-bit ASCII strings or Unicode strings. +\var{tag} is the element name. +\var{attrib} is an optional dictionary, containing element attributes. +\var{extra} contains additional attributes, given as keyword arguments. + +\begin{datadescni}{Returns:} +An element instance. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{fromstring}{text} +Parses an XML section from a string constant. Same as XML. +\var{text} is a string containing XML data. + +\begin{datadescni}{Returns:} +An Element instance. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{iselement}{element} +Checks if an object appears to be a valid element object. +\var{element} is an element instance. + +\begin{datadescni}{Returns:} +A true value if this is an element object. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{iterparse}{source\optional{, events}} +Parses an XML section into an element tree incrementally, and reports +what's going on to the user. +\var{source} is a filename or file object containing XML data. +\var{events} is a list of events to report back. If omitted, only ``end'' +events are reported. + +\begin{datadescni}{Returns:} +A (event, elem) iterator. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{parse}{source\optional{, parser}} +Parses an XML section into an element tree. +\var{source} is a filename or file object containing XML data. +\var{parser} is an optional parser instance. If not given, the +standard XMLTreeBuilder parser is used. + +\begin{datadescni}{Returns:} +An ElementTree instance +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}} +PI element factory. This factory function creates a special element +that will be serialized as an XML processing instruction. +\var{target} is a string containing the PI target. +\var{text} is a string containing the PI contents, if given. + +\begin{datadescni}{Returns:} +An element instance, representing a PI. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{SubElement}{parent, tag\optional{, attrib} \optional{, **extra}} +Subelement factory. This function creates an element instance, and +appends it to an existing element. + +The element name, attribute names, and attribute values can be +either 8-bit ASCII strings or Unicode strings. +\var{parent} is the parent element. +\var{tag} is the subelement name. +\var{attrib} is an optional dictionary, containing element attributes. +\var{extra} contains additional attributes, given as keyword arguments. + +\begin{datadescni}{Returns:} +An element instance. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{tostring}{element\optional{, encoding}} +Generates a string representation of an XML element, including all +subelements. +\var{element} is an Element instance. +\var{encoding} is the output encoding (default is US-ASCII). + +\begin{datadescni}{Returns:} +An encoded string containing the XML data. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{XML}{text} +Parses an XML section from a string constant. This function can +be used to embed ``XML literals'' in Python code. +\var{text} is a string containing XML data. + +\begin{datadescni}{Returns:} +An Element instance. +\end{datadescni} +\end{funcdesc} + +\begin{funcdesc}{XMLID}{text} +Parses an XML section from a string constant, and also returns +a dictionary which maps from element id:s to elements. +\var{text} is a string containing XML data. + +\begin{datadescni}{Returns:} +A tuple containing an Element instance and a dictionary. +\end{datadescni} +\end{funcdesc} + + +\subsection{ElementTree Objects\label{elementtree-elementtree-objects}} + +\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}} +ElementTree wrapper class. This class represents an entire element +hierarchy, and adds some extra support for serialization to and from +standard XML. + +\var{element} is the root element. +The tree is initialized with the contents of the XML \var{file} if given. +\end{classdesc} + +\begin{methoddesc}{_setroot}{element} +Replaces the root element for this tree. This discards the +current contents of the tree, and replaces it with the given +element. Use with care. +\var{element} is an element instance. +\end{methoddesc} + +\begin{methoddesc}{find}{path} +Finds the first toplevel element with given tag. +Same as getroot().find(path). +\var{path} is the element to look for. + +\begin{datadescni}{Returns:} +The first matching element, or None if no element was found. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{findall}{path} +Finds all toplevel elements with the given tag. +Same as getroot().findall(path). +\var{path} is the element to look for. + +\begin{datadescni}{Returns:} +A list or iterator containing all matching elements, +in section order. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{findtext}{path\optional{, default}} +Finds the element text for the first toplevel element with given +tag. Same as getroot().findtext(path). +\var{path} is the toplevel element to look for. +\var{default} is the value to return if the element was not found. + +\begin{datadescni}{Returns:} +The text content of the first matching element, or the +default value no element was found. Note that if the element +has is found, but has no text content, this method returns an +empty string. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{getiterator}{\optional{tag}} +Creates a tree iterator for the root element. The iterator loops +over all elements in this tree, in section order. +\var{tag} is the tag to look for (default is to return all elements) + +\begin{datadescni}{Returns:} +An iterator. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{getroot}{} +Gets the root element for this tree. + +\begin{datadescni}{Returns:} +An element instance. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{parse}{source\optional{, parser}} +Loads an external XML section into this element tree. +\var{source} is a file name or file object. +\var{parser} is an optional parser instance. If not given, the +standard XMLTreeBuilder parser is used. + +\begin{datadescni}{Returns:} +The section root element. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{write}{file\optional{, encoding}} +Writes the element tree to a file, as XML. +\var{file} is a file name, or a file object opened for writing. +\var{encoding} is the output encoding (default is US-ASCII). +\end{methoddesc} + + +\subsection{QName Objects\label{elementtree-qname-objects}} + +\begin{classdesc}{QName}{text_or_uri\optional{, tag}} +QName wrapper. This can be used to wrap a QName attribute value, in +order to get proper namespace handling on output. +\var{text_or_uri} is a string containing the QName value, +in the form {\{}uri{\}}local, or, if the tag argument is given, +the URI part of a QName. +If \var{tag} is given, the first argument is interpreted as +an URI, and this argument is interpreted as a local name. + +\begin{datadescni}{Returns:} +An opaque object, representing the QName. +\end{datadescni} +\end{classdesc} + + +\subsection{TreeBuilder Objects\label{elementtree-treebuilder-objects}} + +\begin{classdesc}{TreeBuilder}{\optional{element_factory}} +Generic element structure builder. This builder converts a sequence +of start, data, and end method calls to a well-formed element structure. +You can use this class to build an element structure using a custom XML +parser, or a parser for some other XML-like format. +The \var{element_factory} is called to create new Element instances when +given. +\end{classdesc} + +\begin{methoddesc}{close}{} +Flushes the parser buffers, and returns the toplevel documen +element. + +\begin{datadescni}{Returns:} +An Element instance. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{data}{data} +Adds text to the current element. +\var{data} is a string. This should be either an 8-bit string +containing ASCII text, or a Unicode string. +\end{methoddesc} + +\begin{methoddesc}{end}{tag} +Closes the current element. +\var{tag} is the element name. + +\begin{datadescni}{Returns:} +The closed element. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{start}{tag, attrs} +Opens a new element. +\var{tag} is the element name. +\var{attrs} is a dictionary containing element attributes. + +\begin{datadescni}{Returns:} +The opened element. +\end{datadescni} +\end{methoddesc} + + +\subsection{XMLTreeBuilder Objects\label{elementtree-xmltreebuilder-objects}} + +\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}} +Element structure builder for XML source data, based on the +expat parser. +\var{html} are predefined HTML entities. This flag is not supported +by the current implementation. +\var{target} is the target object. If omitted, the builder uses an +instance of the standard TreeBuilder class. +\end{classdesc} + +\begin{methoddesc}{close}{} +Finishes feeding data to the parser. + +\begin{datadescni}{Returns:} +An element structure. +\end{datadescni} +\end{methoddesc} + +\begin{methoddesc}{doctype}{name, pubid, system} +Handles a doctype declaration. +\var{name} is the doctype name. +\var{pubid} is the public identifier. +\var{system} is the system identifier. +\end{methoddesc} + +\begin{methoddesc}{feed}{data} +Feeds data to the parser. + +\var{data} is encoded data. +\end{methoddesc} diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 8904d5f..65b0bf5 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -401,77 +401,27 @@ class C: \end{funcdesc} \begin{funcdesc}{file}{filename\optional{, mode\optional{, bufsize}}} - Return a new file object (described in - section~\ref{bltin-file-objects}, ``\ulink{File - Objects}{bltin-file-objects.html}''). - The first two arguments are the same as for \code{stdio}'s - \cfunction{fopen()}: \var{filename} is the file name to be opened, - \var{mode} indicates how the file is to be opened: \code{'r'} for - reading, \code{'w'} for writing (truncating an existing file), and - \code{'a'} opens it for appending (which on \emph{some} \UNIX{} - systems means that \emph{all} writes append to the end of the file, - regardless of the current seek position). - - Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for - updating (note that \code{'w+'} truncates the file). Append - \code{'b'} to the mode to open the file in binary mode, on systems - that differentiate between binary and text files (else it is - ignored). If the file cannot be opened, \exception{IOError} is - raised. - - In addition to the standard \cfunction{fopen()} values \var{mode} - may be \code{'U'} or \code{'rU'}. If Python is built with universal - newline support (the default) the file is opened as a text file, but - lines may be terminated by any of \code{'\e n'}, the Unix end-of-line - convention, - \code{'\e r'}, the Macintosh convention or \code{'\e r\e n'}, the Windows - convention. All of these external representations are seen as - \code{'\e n'} - by the Python program. If Python is built without universal newline support - \var{mode} \code{'U'} is the same as normal text mode. Note that - file objects so opened also have an attribute called - \member{newlines} which has a value of \code{None} (if no newlines - have yet been seen), \code{'\e n'}, \code{'\e r'}, \code{'\e r\e n'}, - or a tuple containing all the newline types seen. - - Python enforces that the mode, after stripping \code{'U'}, begins with - \code{'r'}, \code{'w'} or \code{'a'}. - - If \var{mode} is omitted, it defaults to \code{'r'}. When opening a - binary file, you should append \code{'b'} to the \var{mode} value - for improved portability. (It's useful even on systems which don't - treat binary and text files differently, where it serves as - documentation.) - \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O} - \index{I/O control!buffering} - The optional \var{bufsize} argument specifies the - file's desired buffer size: 0 means unbuffered, 1 means line - buffered, any other positive value means use a buffer of - (approximately) that size. A negative \var{bufsize} means to use - the system default, which is usually line buffered for tty - devices and fully buffered for other files. If omitted, the system - default is used.\footnote{ - Specifying a buffer size currently has no effect on systems that - don't have \cfunction{setvbuf()}. The interface to specify the - buffer size is not done using a method that calls - \cfunction{setvbuf()}, because that may dump core when called - after any I/O has been performed, and there's no reliable way to - determine whether this is the case.} + Constructor function for the \class{file} type, described further + in section~\ref{bltin-file-objects}, ``\ulink{File + Objects}{bltin-file-objects.html}''. The constructor's arguments + are the same as those of the \function{open()} built-in function + described below. + + When opening a file, it's preferable to use \function{open()} instead of + invoking this constructor directly. \class{file} is more suited to + type testing (for example, writing \samp{isinstance(f, file)}). \versionadded{2.2} - - \versionchanged[Restriction on first letter of mode string - introduced]{2.5} \end{funcdesc} \begin{funcdesc}{filter}{function, list} Construct a list from those elements of \var{list} for which \var{function} returns true. \var{list} may be either a sequence, a container which supports iteration, or an iterator, If \var{list} - is a string or a tuple, the result also has that type; otherwise it - is always a list. If \var{function} is \code{None}, the identity - function is assumed, that is, all elements of \var{list} that are false - (zero or empty) are removed. + is a string or a tuple, the result + also has that type; otherwise it is always a list. If \var{function} is + \code{None}, the identity function is assumed, that is, all elements of + \var{list} that are false are removed. Note that \code{filter(function, \var{list})} is equivalent to \code{[item for item in \var{list} if function(item)]} if function is @@ -709,10 +659,71 @@ class C: \end{funcdesc} \begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}} - A wrapper for the \function{file()} function above. The intent is - for \function{open()} to be preferred for use as a factory function - returning a new \class{file} object. \class{file} is more suited to - type testing (for example, writing \samp{isinstance(f, file)}). + Open a file, returning an object of the \class{file} type described + in section~\ref{bltin-file-objects}, ``\ulink{File + Objects}{bltin-file-objects.html}''. If the file cannot be opened, + \exception{IOError} is raised. When opening a file, it's + preferable to use \function{open()} instead of invoking the + \class{file} constructor directly. + + The first two arguments are the same as for \code{stdio}'s + \cfunction{fopen()}: \var{filename} is the file name to be opened, + and \var{mode} is a string indicating how the file is to be opened. + + The most commonly-used values of \var{mode} are \code{'r'} for + reading, \code{'w'} for writing (truncating the file if it already + exists), and \code{'a'} for appending (which on \emph{some} \UNIX{} + systems means that \emph{all} writes append to the end of the file + regardless of the current seek position). If \var{mode} is omitted, + it defaults to \code{'r'}. When opening a binary file, you should + append \code{'b'} to the \var{mode} value to open the file in binary + mode, which will improve portability. (Appending \code{'b'} is + useful even on systems that don't treat binary and text files + differently, where it serves as documentation.) See below for more + possible values of \var{mode}. + + \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O} + \index{I/O control!buffering} + The optional \var{bufsize} argument specifies the + file's desired buffer size: 0 means unbuffered, 1 means line + buffered, any other positive value means use a buffer of + (approximately) that size. A negative \var{bufsize} means to use + the system default, which is usually line buffered for tty + devices and fully buffered for other files. If omitted, the system + default is used.\footnote{ + Specifying a buffer size currently has no effect on systems that + don't have \cfunction{setvbuf()}. The interface to specify the + buffer size is not done using a method that calls + \cfunction{setvbuf()}, because that may dump core when called + after any I/O has been performed, and there's no reliable way to + determine whether this is the case.} + + Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for + updating (note that \code{'w+'} truncates the file). Append + \code{'b'} to the mode to open the file in binary mode, on systems + that differentiate between binary and text files; on systems + that don't have this distinction, adding the \code{'b'} has no effect. + + In addition to the standard \cfunction{fopen()} values \var{mode} + may be \code{'U'} or \code{'rU'}. Python is usually built with universal + newline support; supplying \code{'U'} opens the file as a text file, but + lines may be terminated by any of the following: the \UNIX{} end-of-line + convention \code{'\e n'}, + the Macintosh convention \code{'\e r'}, or the Windows + convention \code{'\e r\e n'}. All of these external representations are seen as + \code{'\e n'} + by the Python program. If Python is built without universal newline support + a \var{mode} with \code{'U'} is the same as normal text mode. Note that + file objects so opened also have an attribute called + \member{newlines} which has a value of \code{None} (if no newlines + have yet been seen), \code{'\e n'}, \code{'\e r'}, \code{'\e r\e n'}, + or a tuple containing all the newline types seen. + + Python enforces that the mode, after stripping \code{'U'}, begins with + \code{'r'}, \code{'w'} or \code{'a'}. + + \versionchanged[Restriction on first letter of mode string + introduced]{2.5} \end{funcdesc} \begin{funcdesc}{ord}{c} @@ -764,15 +775,30 @@ class C: \begin{verbatim} class C(object): def __init__(self): self.__x = None - def getx(self): return self.__x - def setx(self, value): self.__x = value - def delx(self): del self.__x + def getx(self): return self._x + def setx(self, value): self._x = value + def delx(self): del self._x x = property(getx, setx, delx, "I'm the 'x' property.") \end{verbatim} If given, \var{doc} will be the docstring of the property attribute. Otherwise, the property will copy \var{fget}'s docstring (if it - exists). + exists). This makes it possible to create read-only properties + easily using \function{property()} as a decorator: + +\begin{verbatim} +class Parrot(object): + def __init__(self): + self._voltage = 100000 + + @property + def voltage(self): + """Get the current voltage.""" + return self._voltage +\end{verbatim} + + turns the \method{voltage()} method into a ``getter'' for a read-only + attribute with the same name. \versionadded{2.2} \versionchanged[Use \var{fget}'s docstring if no \var{doc} given]{2.5} @@ -958,8 +984,30 @@ except NameError: \begin{funcdesc}{sorted}{iterable\optional{, cmp\optional{, key\optional{, reverse}}}} Return a new sorted list from the items in \var{iterable}. - The optional arguments \var{cmp}, \var{key}, and \var{reverse} - have the same meaning as those for the \method{list.sort()} method. + + The optional arguments \var{cmp}, \var{key}, and \var{reverse} have + the same meaning as those for the \method{list.sort()} method + (described in section~\ref{typesseq-mutable}). + + \var{cmp} specifies a custom comparison function of two arguments + (iterable elements) which should return a negative, zero or positive + number depending on whether the first argument is considered smaller + than, equal to, or larger than the second argument: + \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}: + \function{cmp}(x.lower(), y.lower())} + + \var{key} specifies a function of one argument that is used to + extract a comparison key from each list element: + \samp{\var{key}=\function{str.lower}} + + \var{reverse} is a boolean value. If set to \code{True}, then the + list elements are sorted as if each comparison were reversed. + + In general, the \var{key} and \var{reverse} conversion processes are + much faster than specifying an equivalent \var{cmp} function. This is + because \var{cmp} is called multiple times for each list element while + \var{key} and \var{reverse} touch each element only once. + \versionadded{2.4} \end{funcdesc} diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex index e41f8bf..5c7c6b9 100644 --- a/Doc/lib/libgettext.tex +++ b/Doc/lib/libgettext.tex @@ -549,7 +549,7 @@ The \program{pygettext}\footnote{Fran\c cois Pinard has written a program called \program{xpot} which does a similar job. It is available as part of his \program{po-utils} package at -\url{http://www.iro.umontreal.ca/contrib/po-utils/HTML/}.} program +\url{http://po-utils.progiciels-bpi.ca/}.} program scans all your Python source code looking for the strings you previously marked as translatable. It is similar to the GNU \program{gettext} program except that it understands all the @@ -585,8 +585,8 @@ files are what the \module{gettext} module uses for the actual translation processing during run-time. How you use the \module{gettext} module in your code depends on -whether you are internationalizing your entire application or a single -module. +whether you are internationalizing a single module or your entire application. +The next two sections will discuss each case. \subsubsection{Localizing your module} diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex index e0a775c..598d351 100644 --- a/Doc/lib/libimp.tex +++ b/Doc/lib/libimp.tex @@ -232,6 +232,24 @@ properly matching byte-compiled file (with suffix \file{.pyc} or source file. \end{funcdesc} +\begin{classdesc}{NullImporter}{path_string} +The \class{NullImporter} type is a \pep{302} import hook that handles +non-directory path strings by failing to find any modules. Calling this +type with an existing directory or empty string raises +\exception{ImportError}. Otherwise, a \class{NullImporter} instance is +returned. + +Python adds instances of this type to \code{sys.path_importer_cache} for +any path entries that are not directories and are not handled by any other +path hooks on \code{sys.path_hooks}. Instances have only one method: + +\begin{methoddesc}{find_module}{fullname \optional{, path}} +This method always returns \code{None}, indicating that the requested +module could not be found. +\end{methoddesc} + +\versionadded{2.5} +\end{classdesc} \subsection{Examples} \label{examples-imp} @@ -257,7 +275,7 @@ def __import__(name, globals=None, locals=None, fromlist=None): # there's a problem we can't handle -- let the caller handle it. fp, pathname, description = imp.find_module(name) - + try: return imp.load_module(name, fp, pathname, description) finally: diff --git a/Doc/lib/libinspect.tex b/Doc/lib/libinspect.tex index 5cabb80..85651f0 100644 --- a/Doc/lib/libinspect.tex +++ b/Doc/lib/libinspect.tex @@ -180,13 +180,32 @@ Note: Return true if the object is a data descriptor. Data descriptors have both a __get__ and a __set__ attribute. Examples are - properties (defined in Python) and getsets and members (defined in C). - Typically, data descriptors will also have __name__ and __doc__ attributes - (properties, getsets, and members have both of these attributes), but this - is not guaranteed. + properties (defined in Python), getsets, and members. The latter two are + defined in C and there are more specific tests available for those types, + which is robust across Python implementations. Typically, data descriptors + will also have __name__ and __doc__ attributes (properties, getsets, and + members have both of these attributes), but this is not guaranteed. \versionadded{2.3} \end{funcdesc} +\begin{funcdesc}{isgetsetdescriptor}{object} + Return true if the object is a getset descriptor. + + getsets are attributes defined in extension modules via \code{PyGetSetDef} + structures. For Python implementations without such types, this method will + always return \code{False}. +\versionadded{2.5} +\end{funcdesc} + +\begin{funcdesc}{ismemberdescriptor}{object} + Return true if the object is a member descriptor. + + Member descriptors are attributes defined in extension modules via + \code{PyMemberDef} structures. For Python implementations without such + types, this method will always return \code{False}. +\versionadded{2.5} +\end{funcdesc} + \subsection{Retrieving source code \label{inspect-source}} @@ -272,18 +291,18 @@ Note: \end{funcdesc} \begin{funcdesc}{formatargspec}{args\optional{, varargs, varkw, defaults, - argformat, varargsformat, varkwformat, defaultformat}} + formatarg, formatvarargs, formatvarkw, formatvalue, join}} Format a pretty argument spec from the four values returned by - \function{getargspec()}. The other four arguments are the + \function{getargspec()}. The format* arguments are the corresponding optional formatting functions that are called to turn names and values into strings. \end{funcdesc} \begin{funcdesc}{formatargvalues}{args\optional{, varargs, varkw, locals, - argformat, varargsformat, varkwformat, valueformat}} + formatarg, formatvarargs, formatvarkw, formatvalue, join}} Format a pretty argument spec from the four values returned by - \function{getargvalues()}. The other four arguments are the + \function{getargvalues()}. The format* arguments are the corresponding optional formatting functions that are called to turn names and values into strings. \end{funcdesc} diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex index 1477d3c..72c7743 100644 --- a/Doc/lib/liblinecache.tex +++ b/Doc/lib/liblinecache.tex @@ -38,7 +38,7 @@ files previously read using \function{getline()}. \begin{funcdesc}{checkcache}{\optional{filename}} Check the cache for validity. Use this function if files in the cache may have changed on disk, and you require the updated version. If -\var{filename} is omitted, it will check the whole cache entries. +\var{filename} is omitted, it will check all the entries in the cache. \end{funcdesc} Example: diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex index 576e2e7..cc44294 100644 --- a/Doc/lib/liblogging.tex +++ b/Doc/lib/liblogging.tex @@ -1068,13 +1068,11 @@ list of possible values is, note that they are not case sensitive: \end{tableii} If \var{backupCount} is non-zero, the system will save old log files by -appending the extensions ".1", ".2" etc., to the filename. For example, -with a \var{backupCount} of 5 and a base file name of \file{app.log}, -you would get \file{app.log}, \file{app.log.1}, \file{app.log.2}, up to -\file{app.log.5}. The file being written to is always \file{app.log}. -When this file is filled, it is closed and renamed to \file{app.log.1}, -and if files \file{app.log.1}, \file{app.log.2}, etc. exist, then they -are renamed to \file{app.log.2}, \file{app.log.3} etc. respectively. +appending extensions to the filename. The extensions are date-and-time +based, using the strftime format \code{\%Y-\%m-\%d_\%H-\%M-\%S} or a leading +portion thereof, depending on the rollover interval. At most \var{backupCount} +files will be kept, and if more would be created when rollover occurs, the +oldest one is deleted. \end{classdesc} \begin{methoddesc}{doRollover}{} @@ -1539,7 +1537,7 @@ to start the server, and which you can \method{join()} when appropriate. To stop the server, call \function{stopListening()}. To send a configuration to the socket, read in the configuration file and send it to the socket as a string of bytes preceded by a four-byte length packed in binary using -struct.\code{pack(">L", n)}. +struct.\code{pack('>L', n)}. \end{funcdesc} \begin{funcdesc}{stopListening}{} diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex index 0a1f792..75ea7e1 100644 --- a/Doc/lib/libmailbox.tex +++ b/Doc/lib/libmailbox.tex @@ -1367,9 +1367,8 @@ for message in mailbox.mbox('~/mbox'): print subject \end{verbatim} -A (surprisingly) simple example of copying all mail from a Babyl mailbox to an -MH mailbox, converting all of the format-specific information that can be -converted: +To copy all mail from a Babyl mailbox to an MH mailbox, converting all +of the format-specific information that can be converted: \begin{verbatim} import mailbox diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex index 8e07768..6c46d6f 100644 --- a/Doc/lib/libmimetypes.tex +++ b/Doc/lib/libmimetypes.tex @@ -158,6 +158,20 @@ want more than one MIME-type database: \versionadded{2.2} \end{classdesc} +An example usage of the module: + +\begin{verbatim} +>>> import mimetypes +>>> mimetypes.init() +>>> mimetypes.knownfiles +['/etc/mime.types', '/etc/httpd/mime.types', ... ] +>>> mimetypes.suffix_map['.tgz'] +'.tar.gz' +>>> mimetypes.encodings_map['.gz'] +'gzip' +>>> mimetypes.types_map['.tgz'] +'application/x-tar-gz' +\end{verbatim} \subsection{MimeTypes Objects \label{mimetypes-objects}} diff --git a/Doc/lib/libnew.tex b/Doc/lib/libnew.tex index e3f2a49..18162dc 100644 --- a/Doc/lib/libnew.tex +++ b/Doc/lib/libnew.tex @@ -22,13 +22,16 @@ unbound if \var{instance} is \code{None}. \var{function} must be callable. \end{funcdesc} -\begin{funcdesc}{function}{code, globals\optional{, name\optional{, argdefs}}} +\begin{funcdesc}{function}{code, globals\optional{, name\optional{, + argdefs\optional{, closure}}}} Returns a (Python) function with the given code and globals. If \var{name} is given, it must be a string or \code{None}. If it is a string, the function will have the given name, otherwise the function name will be taken from \code{\var{code}.co_name}. If \var{argdefs} is given, it must be a tuple and will be used to -determine the default values of parameters. +determine the default values of parameters. If \var{closure} is given, +it must be \code{None} or a tuple of cell objects containing objects +to bind to the names in \code{\var{code}.co_freevars}. \end{funcdesc} \begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring, diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex index ec43e3d..df96dd4 100644 --- a/Doc/lib/liboptparse.tex +++ b/Doc/lib/liboptparse.tex @@ -1,3 +1,5 @@ +% THIS FILE IS AUTO-GENERATED! DO NOT EDIT! +% (Your changes will be lost the next time it is generated.) \section{\module{optparse} --- More powerful command line option parser} \declaremodule{standard}{optparse} \moduleauthor{Greg Ward}{gward@python.net} @@ -306,7 +308,7 @@ Of these, \member{action} is the most fundamental. Actions tell \module{optparse} what to do when it encounters an option on the command line. There is a fixed set of actions hard-coded into \module{optparse}; -adding new actions is an advanced topic covered in section~\ref{optparse-extending}, Extending \module{optparse}. +adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}. Most actions tell \module{optparse} to store a value in some variable{---}for example, take a string from the command line and store it in an attribute of \code{options}. @@ -371,7 +373,7 @@ are no long option strings, \module{optparse} looks at the first short option string: the default destination for \code{"-f"} is \code{f}. \module{optparse} also includes built-in \code{long} and \code{complex} types. Adding -types is covered in section~\ref{optparse-extending}, Extending \module{optparse}. +types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}. \subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}} @@ -566,7 +568,7 @@ argument to OptionParser: parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") \end{verbatim} -Note that \code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart +\code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart from that, \code{version} can contain anything you like. When you supply it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser. If it encounters this option on the command line, it expands your @@ -659,7 +661,7 @@ def main(): if __name__ == "__main__": main() \end{verbatim} -% $Id: tutorial.txt 505 2005-07-22 01:52:40Z gward $ +% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $ \subsection{Reference Guide\label{optparse-reference-guide}} @@ -1146,7 +1148,7 @@ See section~\ref{optparse-tutorial}, the tutorial for an example. \module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long}, \code{choice}, \code{float} and \code{complex}. If you need to add new option -types, see section~\ref{optparse-extending}, Extending \module{optparse}. +types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}. Arguments to string options are not checked or converted in any way: the text on the command line is stored in the destination (or passed to the @@ -1195,16 +1197,16 @@ its \method{parse{\_}args()} method: where the input parameters are \begin{description} \item[\code{args}] -the list of arguments to process (\code{sys.argv{[}1:]} by default) +the list of arguments to process (default: \code{sys.argv{[}1:]}) \item[\code{options}] -object to store option arguments in (a new instance of -optparse.Values by default) +object to store option arguments in (default: a new instance of +optparse.Values) \end{description} and the return values are \begin{description} \item[\code{options}] -the same object as was passed in as \code{options}, or the new +the same object that was passed in as \code{options}, or the optparse.Values instance created by \module{optparse} \item[\code{args}] the leftover positional arguments after all options have been @@ -1212,9 +1214,9 @@ processed \end{description} The most common usage is to supply neither keyword argument. If you -supply a \code{values} object, it will be repeatedly modified with a -\code{setattr()} call for every option argument written to an option -destination, and finally returned by \method{parse{\_}args()}. +supply \code{options}, it will be modified with repeated \code{setattr()} +calls (roughly one for every option argument stored to an option +destination) and returned by \method{parse{\_}args()}. If \method{parse{\_}args()} encounters any errors in the argument list, it calls the OptionParser's \method{error()} method with an appropriate end-user error @@ -1388,7 +1390,7 @@ parser.add_option("--novice", action="store_const", \end{verbatim} \end{itemize} -% $Id: reference.txt 505 2005-07-22 01:52:40Z gward $ +% $Id: reference.txt 519 2006-06-11 14:39:11Z gward $ \subsection{Option Callbacks\label{optparse-option-callbacks}} @@ -1681,3 +1683,206 @@ further options (probably causing an error), rather than as arguments to \code{"-c"}. Fixing this is left as an exercise for the reader. % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $ + +\subsection{Extending \module{optparse}\label{optparse-extending-optparse}} + +Since the two major controlling factors in how \module{optparse} interprets +command-line options are the action and type of each option, the most +likely direction of extension is to add new actions and new types. + + +\subsubsection{Adding new types\label{optparse-adding-new-types}} + +To add new types, you need to define your own subclass of \module{optparse}'s Option +class. This class has a couple of attributes that define \module{optparse}'s types: +\member{TYPES} and \member{TYPE{\_}CHECKER}. + +\member{TYPES} is a tuple of type names; in your subclass, simply define a new +tuple \member{TYPES} that builds on the standard one. + +\member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking +functions. A type-checking function has the following signature: +\begin{verbatim} +def check_mytype(option, opt, value) +\end{verbatim} + +where \code{option} is an \class{Option} instance, \code{opt} is an option string +(e.g., \code{"-f"}), and \code{value} is the string from the command line that +must be checked and converted to your desired type. \code{check{\_}mytype()} +should return an object of the hypothetical type \code{mytype}. The value +returned by a type-checking function will wind up in the OptionValues +instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a +callback as the \code{value} parameter. + +Your type-checking function should raise OptionValueError if it +encounters any problems. OptionValueError takes a single string +argument, which is passed as-is to OptionParser's \method{error()} method, +which in turn prepends the program name and the string \code{"error:"} and +prints everything to stderr before terminating the process. + +Here's a silly example that demonstrates adding a \code{complex} option +type to parse Python-style complex numbers on the command line. (This +is even sillier than it used to be, because \module{optparse} 1.3 added built-in +support for complex numbers, but never mind.) + +First, the necessary imports: +\begin{verbatim} +from copy import copy +from optparse import Option, OptionValueError +\end{verbatim} + +You need to define your type-checker first, since it's referred to later +(in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass): +\begin{verbatim} +def check_complex(option, opt, value): + try: + return complex(value) + except ValueError: + raise OptionValueError( + "option %s: invalid complex value: %r" % (opt, value)) +\end{verbatim} + +Finally, the Option subclass: +\begin{verbatim} +class MyOption (Option): + TYPES = Option.TYPES + ("complex",) + TYPE_CHECKER = copy(Option.TYPE_CHECKER) + TYPE_CHECKER["complex"] = check_complex +\end{verbatim} + +(If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end +up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class. +This being Python, nothing stops you from doing that except good manners +and common sense.) + +That's it! Now you can write a script that uses the new option type +just like any other \module{optparse}-based script, except you have to instruct your +OptionParser to use MyOption instead of Option: +\begin{verbatim} +parser = OptionParser(option_class=MyOption) +parser.add_option("-c", type="complex") +\end{verbatim} + +Alternately, you can build your own option list and pass it to +OptionParser; if you don't use \method{add{\_}option()} in the above way, you +don't need to tell OptionParser which option class to use: +\begin{verbatim} +option_list = [MyOption("-c", action="store", type="complex", dest="c")] +parser = OptionParser(option_list=option_list) +\end{verbatim} + + +\subsubsection{Adding new actions\label{optparse-adding-new-actions}} + +Adding new actions is a bit trickier, because you have to understand +that \module{optparse} has a couple of classifications for actions: +\begin{description} +\item[``store'' actions] +actions that result in \module{optparse} storing a value to an attribute of the +current OptionValues instance; these options require a \member{dest} +attribute to be supplied to the Option constructor +\item[``typed'' actions] +actions that take a value from the command line and expect it to be +of a certain type; or rather, a string that can be converted to a +certain type. These options require a \member{type} attribute to the +Option constructor. +\end{description} + +These are overlapping sets: some default ``store'' actions are \code{store}, +\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed'' +actions are \code{store}, \code{append}, and \code{callback}. + +When you add an action, you need to categorize it by listing it in at +least one of the following class attributes of Option (all are lists of +strings): +\begin{description} +\item[\member{ACTIONS}] +all actions must be listed in ACTIONS +\item[\member{STORE{\_}ACTIONS}] +``store'' actions are additionally listed here +\item[\member{TYPED{\_}ACTIONS}] +``typed'' actions are additionally listed here +\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}] +actions that always take a type (i.e. whose options always take a +value) are additionally listed here. The only effect of this is +that \module{optparse} assigns the default type, \code{string}, to options with no +explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}. +\end{description} + +In order to actually implement your new action, you must override +Option's \method{take{\_}action()} method and add a case that recognizes your +action. + +For example, let's add an \code{extend} action. This is similar to the +standard \code{append} action, but instead of taking a single value from +the command-line and appending it to an existing list, \code{extend} will +take multiple values in a single comma-delimited string, and extend an +existing list with them. That is, if \code{"-{}-names"} is an \code{extend} +option of type \code{string}, the command line +\begin{verbatim} +--names=foo,bar --names blah --names ding,dong +\end{verbatim} + +would result in a list +\begin{verbatim} +["foo", "bar", "blah", "ding", "dong"] +\end{verbatim} + +Again we define a subclass of Option: +\begin{verbatim} +class MyOption (Option): + + ACTIONS = Option.ACTIONS + ("extend",) + STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) + TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",) + ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",) + + def take_action(self, action, dest, opt, value, values, parser): + if action == "extend": + lvalue = value.split(",") + values.ensure_value(dest, []).extend(lvalue) + else: + Option.take_action( + self, action, dest, opt, value, values, parser) +\end{verbatim} + +Features of note: +\begin{itemize} +\item {} +\code{extend} both expects a value on the command-line and stores that +value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and +\member{TYPED{\_}ACTIONS} + +\item {} +to ensure that \module{optparse} assigns the default type of \code{string} to +\code{extend} actions, we put the \code{extend} action in +\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well + +\item {} +\method{MyOption.take{\_}action()} implements just this one new action, and +passes control back to \method{Option.take{\_}action()} for the standard +\module{optparse} actions + +\item {} +\code{values} is an instance of the optparse{\_}parser.Values class, +which provides the very useful \method{ensure{\_}value()} method. +\method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve; +it is called as +\begin{verbatim} +values.ensure_value(attr, value) +\end{verbatim} + +If the \code{attr} attribute of \code{values} doesn't exist or is None, then +ensure{\_}value() first sets it to \code{value}, and then returns 'value. +This is very handy for actions like \code{extend}, \code{append}, and +\code{count}, all of which accumulate data in a variable and expect that +variable to be of a certain type (a list for the first two, an integer +for the latter). Using \method{ensure{\_}value()} means that scripts using +your action don't have to worry about setting a default value for the +option destinations in question; they can just leave the default as +None and \method{ensure{\_}value()} will take care of getting it right when +it's needed. + +\end{itemize} +% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ + diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex index 223cf28..4c19aaf 100644 --- a/Doc/lib/libossaudiodev.tex +++ b/Doc/lib/libossaudiodev.tex @@ -68,7 +68,7 @@ raises \exception{IOError}. Errors detected directly by Open an audio device and return an OSS audio device object. This object supports many file-like methods, such as \method{read()}, \method{write()}, and \method{fileno()} (although there are subtle -differences between conventional Unix read/write semantics and those of +differences between conventional \UNIX{} read/write semantics and those of OSS audio devices). It also supports a number of audio-specific methods; see below for the complete list of methods. diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex index 45e80b8..a8ab39e 100644 --- a/Doc/lib/libpickle.tex +++ b/Doc/lib/libpickle.tex @@ -725,7 +725,50 @@ source of the strings your application unpickles. \subsection{Example \label{pickle-example}} -Here's a simple example of how to modify pickling behavior for a +For the simplest code, use the \function{dump()} and \function{load()} +functions. Note that a self-referencing list is pickled and restored +correctly. + +\begin{verbatim} +import pickle + +data1 = {'a': [1, 2.0, 3, 4+6j], + 'b': ('string', u'Unicode string'), + 'c': None} + +selfref_list = [1, 2, 3] +selfref_list.append(selfref_list) + +output = open('data.pkl', 'wb') + +# Pickle dictionary using protocol 0. +pickle.dump(data1, output) + +# Pickle the list using the highest protocol available. +pickle.dump(selfref_list, output, -1) + +output.close() +\end{verbatim} + +The following example reads the resulting pickled data. When reading +a pickle-containing file, you should open the file in binary mode +because you can't be sure if the ASCII or binary format was used. + +\begin{verbatim} +import pprint, pickle + +pkl_file = open('data.pkl', 'rb') + +data1 = pickle.load(pkl_file) +pprint.pprint(data1) + +data2 = pickle.load(pkl_file) +pprint.pprint(data2) + +pkl_file.close() +\end{verbatim} + +Here's a larger example that shows how to modify pickling behavior for a class. The \class{TextReader} class opens a text file, and returns the line number and line contents each time its \method{readline()} method is called. If a \class{TextReader} instance is pickled, all diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex index 15d866b..a286f00 100644 --- a/Doc/lib/libpkgutil.tex +++ b/Doc/lib/libpkgutil.tex @@ -30,7 +30,7 @@ __path__ = extend_path(__path__, __name__) with \code{import}. A \file{*.pkg} file is trusted at face value: apart from checking for duplicates, all entries found in a \file{*.pkg} file are added to the path, regardless of whether they - exist the filesystem. (This is a feature.) + exist on the filesystem. (This is a feature.) If the input path is not a list (as is the case for frozen packages) it is returned unchanged. The input path is not diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex index 9f0de1f..0b2da66 100644 --- a/Doc/lib/libposixpath.tex +++ b/Doc/lib/libposixpath.tex @@ -42,8 +42,11 @@ half of the pair returned by \code{split(\var{path})}. \end{funcdesc} \begin{funcdesc}{exists}{path} -Return \code{True} if \var{path} refers to an existing path. -Returns \code{False} for broken symbolic links. +Return \code{True} if \var{path} refers to an existing path. Returns +\code{False} for broken symbolic links. On some platforms, this +function may return \code{False} if permission is not granted to +execute \function{os.stat()} on the requested file, even if the +\var{path} physically exists. \end{funcdesc} \begin{funcdesc}{lexists}{path} @@ -190,9 +193,8 @@ Availability: Macintosh, \UNIX. \end{funcdesc} \begin{funcdesc}{sameopenfile}{fp1, fp2} -Return \code{True} if the file objects \var{fp1} and \var{fp2} refer to the -same file. The two file objects may represent different file -descriptors. +Return \code{True} if the file descriptors \var{fp1} and \var{fp2} refer +to the same file. Availability: Macintosh, \UNIX. \end{funcdesc} diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex index 6c2f710..c6b8846 100644 --- a/Doc/lib/librandom.tex +++ b/Doc/lib/librandom.tex @@ -236,7 +236,7 @@ these equations can be found in any statistics text. \var{beta} is the shape parameter. \end{funcdesc} -Alternative Generators +Alternative Generators: \begin{classdesc}{WichmannHill}{\optional{seed}} Class that implements the Wichmann-Hill algorithm as the core generator. @@ -267,6 +267,30 @@ called. \versionadded{2.4} \end{classdesc} +Examples of basic usage: + +\begin{verbatim} +>>> random.random() # Random float x, 0.0 <= x < 1.0 +0.37444887175646646 +>>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0 +1.1800146073117523 +>>> random.randint(1, 10) # Integer from 1 to 10, endpoints included +7 +>>> random.randrange(0, 101, 2) # Even integer from 0 to 100 +26 +>>> random.choice('abcdefghij') # Choose a random element +'c' + +>>> items = [1, 2, 3, 4, 5, 6, 7] +>>> random.shuffle(items) +>>> items +[7, 3, 2, 5, 6, 4, 1] + +>>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements +[4, 1, 5] + +\end{verbatim} + \begin{seealso} \seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom diff --git a/Doc/lib/libre.tex b/Doc/lib/libre.tex index 1404e09..84e382d 100644 --- a/Doc/lib/libre.tex +++ b/Doc/lib/libre.tex @@ -897,7 +897,7 @@ offers some more-or-less equivalent mappings between \lineii{\code{\%d}} {\regexp{[-+]?\e d+}} \lineii{\code{\%e}, \code{\%E}, \code{\%f}, \code{\%g}} - {\regexp{[-+]?(\e d+(\e.\e d*)?|\e d*\e.\e d+)([eE][-+]?\e d+)?}} + {\regexp{[-+]?(\e d+(\e.\e d*)?|\e.\e d+)([eE][-+]?\e d+)?}} \lineii{\code{\%i}} {\regexp{[-+]?(0[xX][\e dA-Fa-f]+|0[0-7]*|\e d+)}} \lineii{\code{\%o}} diff --git a/Doc/lib/libreadline.tex b/Doc/lib/libreadline.tex index ac8e23f..dec37b6 100644 --- a/Doc/lib/libreadline.tex +++ b/Doc/lib/libreadline.tex @@ -7,10 +7,13 @@ \modulesynopsis{GNU readline support for Python.} -The \module{readline} module defines a number of functions used either -directly or from the \refmodule{rlcompleter} module to facilitate -completion and history file read and write from the Python -interpreter. +The \module{readline} module defines a number of functions to +facilitate completion and reading/writing of history files from the +Python interpreter. This module can be used directly or via the +\refmodule{rlcompleter} module. Settings made using +this module affect the behaviour of both the interpreter's interactive prompt +and the prompts offered by the \function{raw_input()} and \function{input()} +built-in functions. The \module{readline} module defines the following functions: diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex index 3ec1018..1fe0d63 100644 --- a/Doc/lib/libsgmllib.tex +++ b/Doc/lib/libsgmllib.tex @@ -132,27 +132,59 @@ nothing. \begin{methoddesc}{handle_charref}{ref} This method is called to process a character reference of the form -\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must -be a decimal number in the -range 0-255. It translates the character to \ASCII{} and calls the -method \method{handle_data()} with the character as argument. If -\var{ref} is invalid or out of range, the method -\code{unknown_charref(\var{ref})} is called to handle the error. A -subclass must override this method to provide support for named -character entities. +\samp{\&\#\var{ref};}. The base implementation uses +\method{convert_charref()} to convert the reference to a string. If +that method returns a string, it is passed to \method{handle_data()}, +otherwise \method{unknown_charref(\var{ref})} is called to handle the +error. +\versionchanged[Use \method{convert_charref()} instead of hard-coding +the conversion]{2.5} +\end{methoddesc} + +\begin{methoddesc}{convert_charref}{ref} +Convert a character reference to a string, or \code{None}. \var{ref} +is the reference passed in as a string. In the base implementation, +\var{ref} must be a decimal number in the range 0-255. It converts +the code point found using the \method{convert_codepoint()} method. +If \var{ref} is invalid or out of range, this method returns +\code{None}. This method is called by the default +\method{handle_charref()} implementation and by the attribute value +parser. +\versionadded{2.5} +\end{methoddesc} + +\begin{methoddesc}{convert_codepoint}{codepoint} +Convert a codepoint to a \class{str} value. Encodings can be handled +here if appropriate, though the rest of \module{sgmllib} is oblivious +on this matter. +\versionadded{2.5} \end{methoddesc} \begin{methoddesc}{handle_entityref}{ref} This method is called to process a general entity reference of the form \samp{\&\var{ref};} where \var{ref} is an general entity -reference. It looks for \var{ref} in the instance (or class) -variable \member{entitydefs} which should be a mapping from entity -names to corresponding translations. If a translation is found, it +reference. It converts \var{ref} by passing it to +\method{convert_entityref()}. If a translation is returned, it calls the method \method{handle_data()} with the translation; otherwise, it calls the method \code{unknown_entityref(\var{ref})}. The default \member{entitydefs} defines translations for \code{\&}, \code{\&apos}, \code{\>}, \code{\<}, and \code{\"}. +\versionchanged[Use \method{convert_entityref()} instead of hard-coding +the conversion]{2.5} +\end{methoddesc} + +\begin{methoddesc}{convert_entityref}{ref} +Convert a named entity reference to a \class{str} value, or +\code{None}. The resulting value will not be parsed. \var{ref} will +be only the name of the entity. The default implementation looks for +\var{ref} in the instance (or class) variable \member{entitydefs} +which should be a mapping from entity names to corresponding +translations. If no translation is available for \var{ref}, this +method returns \code{None}. This method is called by the default +\method{handle_entityref()} implementation and by the attribute value +parser. +\versionadded{2.5} \end{methoddesc} \begin{methoddesc}{handle_comment}{comment} diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex index 8bd204e..6ca3576 100644 --- a/Doc/lib/libshelve.tex +++ b/Doc/lib/libshelve.tex @@ -143,15 +143,17 @@ data = d[key] # retrieve a COPY of data at key (raise KeyError if no del d[key] # delete data stored at key (raises KeyError # if no such key) flag = d.has_key(key) # true if the key exists -list = d.keys() # a list of all existing keys (slow!) +klist = d.keys() # a list of all existing keys (slow!) # as d was opened WITHOUT writeback=True, beware: d['xx'] = range(4) # this works as expected, but... d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!! + # having opened d without writeback=True, you need to code carefully: temp = d['xx'] # extracts the copy temp.append(5) # mutates the copy d['xx'] = temp # stores the copy right back, to persist it + # or, d=shelve.open(filename,writeback=True) would let you just code # d['xx'].append(5) and have it work as expected, BUT it would also # consume more memory and make the d.close() operation slower. diff --git a/Doc/lib/libsite.tex b/Doc/lib/libsite.tex index 43b8db2..c079790 100644 --- a/Doc/lib/libsite.tex +++ b/Doc/lib/libsite.tex @@ -16,12 +16,13 @@ search path. It starts by constructing up to four directories from a head and a tail part. For the head part, it uses \code{sys.prefix} and \code{sys.exec_prefix}; empty heads are skipped. For -the tail part, it uses the empty string (on Windows) or -\file{lib/python\shortversion/site-packages} (on \UNIX{} and Macintosh) -and then \file{lib/site-python}. For each of the distinct -head-tail combinations, it sees if it refers to an existing directory, -and if so, adds it to \code{sys.path} and also inspects the newly added -path for configuration files. +the tail part, it uses the empty string and then +\file{lib/site-packages} (on Windows) or +\file{lib/python\shortversion/site-packages} and then +\file{lib/site-python} (on \UNIX{} and Macintosh). For each of the +distinct head-tail combinations, it sees if it refers to an existing +directory, and if so, adds it to \code{sys.path} and also inspects +the newly added path for configuration files. \indexii{site-python}{directory} \indexii{site-packages}{directory} diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index 8066528..aa75ec9 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -711,6 +711,17 @@ If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise read until EOF. The return value is a string of the bytes read. \end{methoddesc} +\begin{methoddesc}{server}{} +Returns a string containing the ASN.1 distinguished name identifying the +server's certificate. (See below for an example +showing what distinguished names look like.) +\end{methoddesc} + +\begin{methoddesc}{issuer}{} +Returns a string containing the ASN.1 distinguished name identifying the +issuer of the server's certificate. +\end{methoddesc} + \subsection{Example \label{socket-example}} Here are four minimal example programs using the TCP/IP protocol:\ a @@ -833,3 +844,44 @@ data = s.recv(1024) s.close() print 'Received', repr(data) \end{verbatim} + +This example connects to an SSL server, prints the +server and issuer's distinguished names, sends some bytes, +and reads part of the response: + +\begin{verbatim} +import socket + +s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) +s.connect(('www.verisign.com', 443)) + +ssl_sock = socket.ssl(s) + +print repr(ssl_sock.server()) +print repr(ssl_sock.issuer()) + +# Set a simple HTTP request -- use httplib in actual code. +ssl_sock.write("""GET / HTTP/1.0\r +Host: www.verisign.com\r\n\r\n""") + +# Read a chunk of data. Will not necessarily +# read all the data returned by the server. +data = ssl_sock.read() + +# Note that you need to close the underlying socket, not the SSL object. +del ssl_sock +s.close() +\end{verbatim} + +At this writing, this SSL example prints the following output (line +breaks inserted for readability): + +\begin{verbatim} +'/C=US/ST=California/L=Mountain View/ + O=VeriSign, Inc./OU=Production Services/ + OU=Terms of use at www.verisign.com/rpa (c)00/ + CN=www.verisign.com' +'/O=VeriSign Trust Network/OU=VeriSign, Inc./ + OU=VeriSign International Server CA - Class 3/ + OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign' +\end{verbatim} diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex index b21e804..c7b28ea 100644 --- a/Doc/lib/libsocksvr.tex +++ b/Doc/lib/libsocksvr.tex @@ -74,9 +74,9 @@ synchronous servers of four types: \end{verbatim} Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not -from \class{UnixStreamServer} -- the only difference between an IP and a -Unix stream server is the address family, which is simply repeated in both -unix server classes. +from \class{UnixStreamServer} --- the only difference between an IP and a +\UNIX{} stream server is the address family, which is simply repeated in both +\UNIX{} server classes. Forking and threading versions of each type of server can be created using the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex index db15c00..d87e064 100644 --- a/Doc/lib/libsqlite3.tex +++ b/Doc/lib/libsqlite3.tex @@ -195,6 +195,14 @@ This can be used to build a shell for SQLite, like in the following example: \verbatiminput{sqlite3/complete_statement.py} \end{funcdesc} +\begin{funcdesc}{}enable_callback_tracebacks{flag} +By default you will not get any tracebacks in user-defined functions, +aggregates, converters, authorizer callbacks etc. If you want to debug them, +you can call this function with \var{flag} as True. Afterwards, you will get +tracebacks from callbacks on \code{sys.stderr}. Use \constant{False} to disable +the feature again. +\end{funcdesc} + \subsection{Connection Objects \label{sqlite3-Connection-Objects}} A \class{Connection} instance has the following attributes and methods: @@ -237,8 +245,7 @@ of parameters the function accepts, and \var{func} is a Python callable that is called as SQL function. The function can return any of the types supported by SQLite: unicode, str, -int, long, float, buffer and None. Exceptions in the function are ignored and -they are handled as if the function returned None. +int, long, float, buffer and None. Example: @@ -254,7 +261,7 @@ number of parameters \var{num_params}, and a \code{finalize} method which will return the final result of the aggregate. The \code{finalize} method can return any of the types supported by SQLite: -unicode, str, int, long, float, buffer and None. Any exceptions are ignored. +unicode, str, int, long, float, buffer and None. Example: @@ -283,6 +290,34 @@ To remove a collation, call \code{create_collation} with None as callable: \end{verbatim} \end{methoddesc} +\begin{methoddesc}{interrupt}{} + +You can call this method from a different thread to abort any queries that +might be executing on the connection. The query will then abort and the caller +will get an exception. +\end{methoddesc} + +\begin{methoddesc}{set_authorizer}{authorizer_callback} + +This routine registers a callback. The callback is invoked for each attempt to +access a column of a table in the database. The callback should return +\constant{SQLITE_OK} if access is allowed, \constant{SQLITE_DENY} if the entire +SQL statement should be aborted with an error and \constant{SQLITE_IGNORE} if +the column should be treated as a NULL value. These constants are available in +the \module{sqlite3} module. + +The first argument to the callback signifies what kind of operation is to be +authorized. The second and third argument will be arguments or \constant{None} +depending on the first argument. The 4th argument is the name of the database +("main", "temp", etc.) if applicable. The 5th argument is the name of the +inner-most trigger or view that is responsible for the access attempt or +\constant{None} if this access attempt is directly from input SQL code. + +Please consult the SQLite documentation about the possible values for the first +argument and the meaning of the second and third argument depending on the +first one. All necessary constants are available in the \module{sqlite3} +module. +\end{methoddesc} \begin{memberdesc}{row_factory} You can change this attribute to a callable that accepts the cursor and @@ -477,10 +512,10 @@ The type/class to adapt must be a new-style class, i. e. it must have \class{object} as one of its bases. \end{notice} -The \module{sqlite3} module has two default adapters for Python's builtin -\class{datetime.date} and \class{datetime.datetime} types. Now let's suppose we -want to store \class{datetime.datetime} objects not in ISO representation, but -as Unix timestamp. +The \module{sqlite3} module has two default adapters for Python's built-in +\class{datetime.date} and \class{datetime.datetime} types. Now let's suppose +we want to store \class{datetime.datetime} objects not in ISO representation, +but as a \UNIX{} timestamp. \verbatiminput{sqlite3/adapter_datetime.py} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index f44360b..95b06f8 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -1,4 +1,4 @@ -\section{Built-in Types \label{types}} +\chapter{Built-in Types \label{types}} The following sections describe the standard types that are built into the interpreter. @@ -7,14 +7,14 @@ differed from user-defined types because it was not possible to use the built-in types as the basis for object-oriented inheritance. This limitation does not exist any longer.} -The principal built-in types are numerics, sequences, mappings, files +The principal built-in types are numerics, sequences, mappings, files, classes, instances and exceptions. \indexii{built-in}{types} Some operations are supported by several object types; in particular, practically all objects can be compared, tested for truth value, -and converted to a string (with the \code{`\textrm{\ldots}`} notation, -the equivalent \function{repr()} function, or the slightly different +and converted to a string (with +the \function{repr()} function or the slightly different \function{str()} function). The latter function is implicitly used when an object is written by the \keyword{print}\stindex{print} statement. @@ -24,7 +24,7 @@ and other language statements can be found in the \citetitle[../tut/tut.html]{Python Tutorial}.) -\subsection{Truth Value Testing\label{truth}} +\section{Truth Value Testing\label{truth}} Any object can be tested for truth value, for use in an \keyword{if} or \keyword{while} condition or as operand of the Boolean operations below. @@ -71,7 +71,7 @@ return one of their operands.) \index{False} \index{True} -\subsection{Boolean Operations --- +\section{Boolean Operations --- \keyword{and}, \keyword{or}, \keyword{not} \label{boolean}} @@ -107,7 +107,7 @@ These only evaluate their second argument if needed for their outcome. \end{description} -\subsection{Comparisons \label{comparisons}} +\section{Comparisons \label{comparisons}} Comparison operations are supported by all objects. They all have the same priority (which is higher than that of the Boolean operations). @@ -174,7 +174,7 @@ Two more operations with the same syntactic priority, only by sequence types (below). -\subsection{Numeric Types --- +\section{Numeric Types --- \class{int}, \class{float}, \class{long}, \class{complex} \label{typesnumeric}} @@ -307,7 +307,7 @@ though the result's type is not necessarily int. \end{description} % XXXJH exceptions: overflow (when? what operations?) zerodivision -\subsubsection{Bit-string Operations on Integer Types \label{bitstring-ops}} +\subsection{Bit-string Operations on Integer Types \label{bitstring-ops}} \nodename{Bit-string Operations} Plain and long integer types support additional operations that make @@ -350,7 +350,7 @@ division by \code{pow(2, \var{n})} without overflow check. \end{description} -\subsection{Iterator Types \label{typeiter}} +\section{Iterator Types \label{typeiter}} \versionadded{2.2} \index{iterator protocol} @@ -414,7 +414,7 @@ return an iterator object (technically, a generator object) supplying the \method{__iter__()} and \method{next()} methods. -\subsection{Sequence Types --- +\section{Sequence Types --- \class{str}, \class{unicode}, \class{list}, \class{tuple}, \class{buffer}, \class{xrange} \label{typesseq}} @@ -566,7 +566,8 @@ linear concatenation performance across versions and implementations. \end{description} -\subsubsection{String Methods \label{string-methods}} +\subsection{String Methods \label{string-methods}} +\indexii{string}{methods} These are the string methods which both 8-bit strings and Unicode objects support: @@ -618,8 +619,11 @@ For a list of possible encodings, see section~\ref{standard-encodings}. \begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}} Return \code{True} if the string ends with the specified \var{suffix}, -otherwise return \code{False}. With optional \var{start}, test beginning at +otherwise return \code{False}. \var{suffix} can also be a tuple of +suffixes to look for. With optional \var{start}, test beginning at that position. With optional \var{end}, stop comparing at that position. + +\versionchanged[Accept tuples as \var{suffix}]{2.5} \end{methoddesc} \begin{methoddesc}[string]{expandtabs}{\optional{tabsize}} @@ -829,9 +833,12 @@ boundaries. Line breaks are not included in the resulting list unless \begin{methoddesc}[string]{startswith}{prefix\optional{, start\optional{, end}}} Return \code{True} if string starts with the \var{prefix}, otherwise -return \code{False}. With optional \var{start}, test string beginning at +return \code{False}. \var{prefix} can also be a tuple of +suffixes to look for. With optional \var{start}, test string beginning at that position. With optional \var{end}, stop comparing string at that position. + +\versionchanged[Accept tuples as \var{prefix}]{2.5} \end{methoddesc} \begin{methoddesc}[string]{strip}{\optional{chars}} @@ -894,7 +901,7 @@ of length \var{width}. The original string is returned if \end{methoddesc} -\subsubsection{String Formatting Operations \label{typesseq-strings}} +\subsection{String Formatting Operations \label{typesseq-strings}} \index{formatting, string (\%{})} \index{interpolation, string (\%{})} @@ -1065,7 +1072,7 @@ Additional string operations are defined in standard modules \refmodule{re}.\refstmodindex{re} -\subsubsection{XRange Type \label{typesseq-xrange}} +\subsection{XRange Type \label{typesseq-xrange}} The \class{xrange}\obindex{xrange} type is an immutable sequence which is commonly used for looping. The advantage of the \class{xrange} @@ -1077,7 +1084,7 @@ XRange objects have very little behavior: they only support indexing, iteration, and the \function{len()} function. -\subsubsection{Mutable Sequence Types \label{typesseq-mutable}} +\subsection{Mutable Sequence Types \label{typesseq-mutable}} List objects support additional operations that allow in-place modification of the object. @@ -1094,7 +1101,8 @@ The following operations are defined on mutable sequence types (where \lineiii{\var{s}[\var{i}] = \var{x}} {item \var{i} of \var{s} is replaced by \var{x}}{} \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}} - {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{} + {slice of \var{s} from \var{i} to \var{j} + is replaced by the contents of the iterable \var{t}}{} \lineiii{del \var{s}[\var{i}:\var{j}]} {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}} @@ -1208,7 +1216,7 @@ Notes: that the list has been mutated during a sort. \end{description} -\subsection{Set Types --- +\section{Set Types --- \class{set}, \class{frozenset} \label{types-set}} \obindex{set} @@ -1347,7 +1355,7 @@ The design of the set types was based on lessons learned from the \end{seealso} -\subsection{Mapping Types --- \class{dict} \label{typesmapping}} +\section{Mapping Types --- \class{dict} \label{typesmapping}} \obindex{mapping} \obindex{dictionary} @@ -1510,7 +1518,7 @@ For an example, see \module{collections}.\class{defaultdict}. \end{description} -\subsection{File Objects +\section{File Objects \label{bltin-file-objects}} File objects\obindex{file} are implemented using C's \code{stdio} @@ -1783,7 +1791,7 @@ implemented in C will have to provide a writable \end{memberdesc} -\subsection{Context Manager Types \label{typecontextmanager}} +\section{Context Manager Types \label{typecontextmanager}} \versionadded{2.5} \index{context manager} @@ -1864,13 +1872,13 @@ runtime context, the overhead of a single class dictionary lookup is negligible. -\subsection{Other Built-in Types \label{typesother}} +\section{Other Built-in Types \label{typesother}} The interpreter supports several other kinds of objects. Most of these support only one or two operations. -\subsubsection{Modules \label{typesmodules}} +\subsection{Modules \label{typesmodules}} The only special operation on a module is attribute access: \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} @@ -1896,14 +1904,14 @@ written as \code{<module 'os' from '/usr/local/lib/python\shortversion/os.pyc'>}. -\subsubsection{Classes and Class Instances \label{typesobjects}} +\subsection{Classes and Class Instances \label{typesobjects}} \nodename{Classes and Instances} See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python Reference Manual} for these. -\subsubsection{Functions \label{typesfunctions}} +\subsection{Functions \label{typesfunctions}} Function objects are created by function definitions. The only operation on a function object is to call it: @@ -1917,7 +1925,7 @@ different object types. See the \citetitle[../ref/ref.html]{Python Reference Manual} for more information. -\subsubsection{Methods \label{typesmethods}} +\subsection{Methods \label{typesmethods}} \obindex{method} Methods are functions that are called using the attribute notation. @@ -1962,7 +1970,7 @@ See the \citetitle[../ref/ref.html]{Python Reference Manual} for more information. -\subsubsection{Code Objects \label{bltin-code-objects}} +\subsection{Code Objects \label{bltin-code-objects}} \obindex{code} Code objects are used by the implementation to represent @@ -1985,7 +1993,7 @@ See the \citetitle[../ref/ref.html]{Python Reference Manual} for more information. -\subsubsection{Type Objects \label{bltin-type-objects}} +\subsection{Type Objects \label{bltin-type-objects}} Type objects represent the various object types. An object's type is accessed by the built-in function \function{type()}. There are no special @@ -1997,7 +2005,7 @@ for all standard built-in types. Types are written like this: \code{<type 'int'>}. -\subsubsection{The Null Object \label{bltin-null-object}} +\subsection{The Null Object \label{bltin-null-object}} This object is returned by functions that don't explicitly return a value. It supports no special operations. There is exactly one null @@ -2006,7 +2014,7 @@ object, named \code{None} (a built-in name). It is written as \code{None}. -\subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}} +\subsection{The Ellipsis Object \label{bltin-ellipsis-object}} This object is used by extended slice notation (see the \citetitle[../ref/ref.html]{Python Reference Manual}). It supports no @@ -2015,7 +2023,7 @@ special operations. There is exactly one ellipsis object, named It is written as \code{Ellipsis}. -\subsubsection{Boolean Values} +\subsection{Boolean Values} Boolean values are the two constant objects \code{False} and \code{True}. They are used to represent truth values (although other @@ -2032,14 +2040,14 @@ They are written as \code{False} and \code{True}, respectively. \indexii{Boolean}{values} -\subsubsection{Internal Objects \label{typesinternal}} +\subsection{Internal Objects \label{typesinternal}} See the \citetitle[../ref/ref.html]{Python Reference Manual} for this information. It describes stack frame objects, traceback objects, and slice objects. -\subsection{Special Attributes \label{specialattrs}} +\section{Special Attributes \label{specialattrs}} The implementation adds a few special read-only attributes to several object types, where they are relevant. Some of these are not reported diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex index 3992e43..2431251 100644 --- a/Doc/lib/libstringio.tex +++ b/Doc/lib/libstringio.tex @@ -37,6 +37,24 @@ such mixing can cause this method to raise \exception{UnicodeError}. Free the memory buffer. \end{methoddesc} +Example usage: + +\begin{verbatim} +import StringIO + +output = StringIO.StringIO() +output.write('First line.\n') +print >>output, 'Second line.' + +# Retrieve file contents -- this will be +# 'First line.\nSecond line.\n' +contents = output.getvalue() + +# Close object and discard memory buffer -- +# .getvalue() will now raise an exception. +output.close() +\end{verbatim} + \section{\module{cStringIO} --- Faster version of \module{StringIO}} @@ -82,3 +100,22 @@ The following data objects are provided as well: There is a C API to the module as well; refer to the module source for more information. + +Example usage: + +\begin{verbatim} +import cStringIO + +output = cStringIO.StringIO() +output.write('First line.\n') +print >>output, 'Second line.' + +# Retrieve file contents -- this will be +# 'First line.\nSecond line.\n' +contents = output.getvalue() + +# Close object and discard memory buffer -- +# .getvalue() will now raise an exception. +output.close() +\end{verbatim} + diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex index bde92eb..03072f7 100644 --- a/Doc/lib/libsubprocess.tex +++ b/Doc/lib/libsubprocess.tex @@ -107,7 +107,7 @@ for the new process. If \var{universal_newlines} is \constant{True}, the file objects stdout and stderr are opened as text files, but lines may be terminated by -any of \code{'\e n'}, the Unix end-of-line convention, \code{'\e r'}, +any of \code{'\e n'}, the \UNIX{} end-of-line convention, \code{'\e r'}, the Macintosh convention or \code{'\e r\e n'}, the Windows convention. All of these external representations are seen as \code{'\e n'} by the Python program. \note{This feature is only available if Python is built @@ -140,7 +140,7 @@ The arguments are the same as for the Popen constructor. Example: Run command with arguments. Wait for command to complete. If the exit code was zero then return, otherwise raise \exception{CalledProcessError.} The \exception{CalledProcessError} object will have the return code in the -\member{errno} attribute. +\member{returncode} attribute. The arguments are the same as for the Popen constructor. Example: @@ -164,9 +164,8 @@ should prepare for \exception{OSError} exceptions. A \exception{ValueError} will be raised if \class{Popen} is called with invalid arguments. -check_call() will raise \exception{CalledProcessError}, which is a -subclass of \exception{OSError}, if the called process returns a -non-zero return code. +check_call() will raise \exception{CalledProcessError}, if the called +process returns a non-zero return code. \subsubsection{Security} diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex index 6b5b755..702427a 100644 --- a/Doc/lib/libsys.tex +++ b/Doc/lib/libsys.tex @@ -21,7 +21,7 @@ It is always available. \begin{datadesc}{byteorder} An indicator of the native byte order. This will have the value - \code{'big'} on big-endian (most-signigicant byte first) platforms, + \code{'big'} on big-endian (most-significant byte first) platforms, and \code{'little'} on little-endian (least-significant byte first) platforms. \versionadded{2.0} @@ -41,7 +41,7 @@ It is always available. \code{Include/patchlevel.h} if the branch is a tag. Otherwise, it is \code{None}. \versionadded{2.5} -\end{datadesc} +\end{datadesc} \begin{datadesc}{builtin_module_names} A tuple of strings giving the names of all modules that are compiled @@ -55,6 +55,23 @@ It is always available. interpreter. \end{datadesc} +\begin{funcdesc}{_current_frames}{} + Return a dictionary mapping each thread's identifier to the topmost stack + frame currently active in that thread at the time the function is called. + Note that functions in the \refmodule{traceback} module can build the + call stack given such a frame. + + This is most useful for debugging deadlock: this function does not + require the deadlocked threads' cooperation, and such threads' call stacks + are frozen for as long as they remain deadlocked. The frame returned + for a non-deadlocked thread may bear no relationship to that thread's + current activity by the time calling code examines the frame. + + This function should be used for internal and specialized purposes + only. + \versionadded{2.5} +\end{funcdesc} + \begin{datadesc}{dllhandle} Integer specifying the handle of the Python DLL. Availability: Windows. @@ -142,7 +159,7 @@ It is always available. function, \function{exc_info()} will return three \code{None} values until another exception is raised in the current thread or the execution stack returns to a frame where another exception is being handled. - + This function is only needed in only a few obscure situations. These include logging and error handling systems that report information on the last or current exception. This function can also be used to try to free @@ -241,14 +258,14 @@ It is always available. \begin{itemize} \item On Windows 9x, the encoding is ``mbcs''. \item On Mac OS X, the encoding is ``utf-8''. -\item On Unix, the encoding is the user's preference - according to the result of nl_langinfo(CODESET), or None if - the nl_langinfo(CODESET) failed. +\item On \UNIX, the encoding is the user's preference + according to the result of nl_langinfo(CODESET), or \constant{None} + if the \code{nl_langinfo(CODESET)} failed. \item On Windows NT+, file names are Unicode natively, so no conversion - is performed. \code{getfilesystemencoding} still returns ``mbcs'', - as this is the encoding that applications should use when they - explicitly want to convert Unicode strings to byte strings that - are equivalent when used as file names. + is performed. \function{getfilesystemencoding()} still returns + \code{'mbcs'}, as this is the encoding that applications should use + when they explicitly want to convert Unicode strings to byte strings + that are equivalent when used as file names. \end{itemize} \versionadded{2.3} \end{funcdesc} @@ -279,8 +296,8 @@ It is always available. \end{funcdesc} \begin{funcdesc}{getwindowsversion}{} - Return a tuple containing five components, describing the Windows - version currently running. The elements are \var{major}, \var{minor}, + Return a tuple containing five components, describing the Windows + version currently running. The elements are \var{major}, \var{minor}, \var{build}, \var{platform}, and \var{text}. \var{text} contains a string while all other values are integers. @@ -491,7 +508,7 @@ else: be registered using \function{settrace()} for each thread being debugged. \note{The \function{settrace()} function is intended only for implementing debuggers, profilers, coverage tools and the like. - Its behavior is part of the implementation platform, rather than + Its behavior is part of the implementation platform, rather than part of the language definition, and thus may not be available in all Python implementations.} \end{funcdesc} diff --git a/Doc/lib/libtextwrap.tex b/Doc/lib/libtextwrap.tex index 9fb0816..38f9b03 100644 --- a/Doc/lib/libtextwrap.tex +++ b/Doc/lib/libtextwrap.tex @@ -47,12 +47,17 @@ remove indentation from strings that have unwanted whitespace to the left of the text. \begin{funcdesc}{dedent}{text} -Remove any whitespace that can be uniformly removed from the left -of every line in \var{text}. +Remove any common leading whitespace from every line in \var{text}. -This is typically used to make triple-quoted strings line up with -the left edge of screen/whatever, while still presenting it in the -source code in indented form. +This can be used to make triple-quoted strings line up with the left +edge of the display, while still presenting them in the source code +in indented form. + +Note that tabs and spaces are both treated as whitespace, but they are +not equal: the lines \code{" {} hello"} and \code{"\textbackslash{}thello"} +are considered to have no common leading whitespace. (This behaviour is +new in Python 2.5; older versions of this module incorrectly expanded +tabs before searching for common leading whitespace.) For example: \begin{verbatim} diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex index 9573ab3..d007eec 100644 --- a/Doc/lib/libthread.tex +++ b/Doc/lib/libthread.tex @@ -74,6 +74,26 @@ data. Thread identifiers may be recycled when a thread exits and another thread is created. \end{funcdesc} +\begin{funcdesc}{stack_size}{\optional{size}} +Return the thread stack size used when creating new threads. The +optional \var{size} argument specifies the stack size to be used for +subsequently created threads, and must be 0 (use platform or +configured default) or a positive integer value of at least 32,768 (32kB). +If changing the thread stack size is unsupported, a \exception{ThreadError} +is raised. If the specified stack size is invalid, a \exception{ValueError} +is raised and the stack size is unmodified. 32kB is currently the minimum +supported stack size value to guarantee sufficient stack space for the +interpreter itself. Note that some platforms may have particular +restrictions on values for the stack size, such as requiring a minimum +stack size > 32kB or requiring allocation in multiples of the system +memory page size - platform documentation should be referred to for +more information (4kB pages are common; using multiples of 4096 for +the stack size is the suggested approach in the absence of more +specific information). +Availability: Windows, systems with \POSIX{} threads. +\versionadded{2.5} +\end{funcdesc} + Lock objects have the following methods: diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex index 8fb3137..0334750 100644 --- a/Doc/lib/libthreading.tex +++ b/Doc/lib/libthreading.tex @@ -125,6 +125,26 @@ method is called. \versionadded{2.3} \end{funcdesc} +\begin{funcdesc}{stack_size}{\optional{size}} +Return the thread stack size used when creating new threads. The +optional \var{size} argument specifies the stack size to be used for +subsequently created threads, and must be 0 (use platform or +configured default) or a positive integer value of at least 32,768 (32kB). +If changing the thread stack size is unsupported, a \exception{ThreadError} +is raised. If the specified stack size is invalid, a \exception{ValueError} +is raised and the stack size is unmodified. 32kB is currently the minimum +supported stack size value to guarantee sufficient stack space for the +interpreter itself. Note that some platforms may have particular +restrictions on values for the stack size, such as requiring a minimum +stack size > 32kB or requiring allocation in multiples of the system +memory page size - platform documentation should be referred to for +more information (4kB pages are common; using multiples of 4096 for +the stack size is the suggested approach in the absence of more +specific information). +Availability: Windows, systems with \POSIX{} threads. +\versionadded{2.5} +\end{funcdesc} + Detailed interfaces for the objects are documented below. The design of this module is loosely based on Java's threading model. diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex index b39b650..f40838a 100644 --- a/Doc/lib/libtime.tex +++ b/Doc/lib/libtime.tex @@ -226,6 +226,8 @@ if any field in \var{t} is outside of the allowed range. \versionchanged[Allowed \var{t} to be omitted]{2.1} \versionchanged[\exception{ValueError} raised if a field in \var{t} is out of range]{2.4} +\versionchanged[0 is now a legal argument for any position in the time tuple; +if it is normally illegal the value is forced to a correct one.]{2.5} The following directives can be embedded in the \var{format} string. @@ -425,7 +427,7 @@ Where: '16:08:12 05/08/03 AEST' \end{verbatim} -On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it +On many \UNIX{} systems (including *BSD, Linux, Solaris, and Darwin), it is more convenient to use the system's zoneinfo (\manpage{tzfile}{5}) database to specify the timezone rules. To do this, set the \envvar{TZ} environment variable to the path of the required timezone diff --git a/Doc/lib/libturtle.tex b/Doc/lib/libturtle.tex index 638bc07..6161cd9 100644 --- a/Doc/lib/libturtle.tex +++ b/Doc/lib/libturtle.tex @@ -27,6 +27,45 @@ Set angle measurement units to degrees. Set angle measurement units to radians. \end{funcdesc} +\begin{funcdesc}{setup}{**kwargs} +Sets the size and position of the main window. Keywords are: +\begin{itemize} + \item \code{width}: either a size in pixels or a fraction of the screen. + The default is 50\% of the screen. + \item \code{height}: either a size in pixels or a fraction of the screen. + The default is 50\% of the screen. + \item \code{startx}: starting position in pixels from the left edge + of the screen. \code{None} is the default value and + centers the window horizontally on screen. + \item \code{starty}: starting position in pixels from the top edge + of the screen. \code{None} is the default value and + centers the window vertically on screen. +\end{itemize} + + Examples: + +\begin{verbatim} +# Uses default geometry: 50% x 50% of screen, centered. +setup() + +# Sets window to 200x200 pixels, in upper left of screen +setup (width=200, height=200, startx=0, starty=0) + +# Sets window to 75% of screen by 50% of screen, and centers it. +setup(width=.75, height=0.5, startx=None, starty=None) +\end{verbatim} + +\end{funcdesc} + +\begin{funcdesc}{title}{title_str} +Set the window's title to \var{title}. +\end{funcdesc} + +\begin{funcdesc}{done}{} +Enters the Tk main loop. The window will continue to +be displayed until the user closes it or the process is killed. +\end{funcdesc} + \begin{funcdesc}{reset}{} Clear the screen, re-center the pen, and set variables to the default values. @@ -42,6 +81,19 @@ means line are drawn more slowly, with an animation of an arrow along the line. \end{funcdesc} +\begin{funcdesc}{speed}{speed} +Set the speed of the turtle. Valid values for the parameter +\var{speed} are \code{'fastest'} (no delay), \code{'fast'}, +(delay 5ms), \code{'normal'} (delay 10ms), \code{'slow'} +(delay 15ms), and \code{'slowest'} (delay 20ms). +\versionadded{2.5} +\end{funcdesc} + +\begin{funcdesc}{delay}{delay} +Set the speed of the turtle to \var{delay}, which is given +in ms. \versionadded{2.5} +\end{funcdesc} + \begin{funcdesc}{forward}{distance} Go forward \var{distance} steps. \end{funcdesc} @@ -94,6 +146,18 @@ usage is: call \code{fill(1)} before drawing a path you want to fill, and call \code{fill(0)} when you finish to draw the path. \end{funcdesc} +\begin{funcdesc}{begin\_fill}{} +Switch turtle into filling mode; +Must eventually be followed by a corresponding end_fill() call. +Otherwise it will be ignored. +\versionadded{2.5} +\end{funcdesc} + +\begin{funcdesc}{end\_fill}{} +End filling mode, and fill the shape; equivalent to \code{fill(0)}. +\versionadded{2.5} +\end{funcdesc} + \begin{funcdesc}{circle}{radius\optional{, extent}} Draw a circle with radius \var{radius} whose center-point is \var{radius} units left of the turtle. @@ -113,6 +177,49 @@ Go to co-ordinates \var{x}, \var{y}. The co-ordinates may be specified either as two separate arguments or as a 2-tuple. \end{funcdesc} +\begin{funcdesc}{towards}{x, y} +Return the angle of the line from the turtle's position +to the point \var{x}, \var{y}. The co-ordinates may be +specified either as two separate arguments, as a 2-tuple, +or as another pen object. +\versionadded{2.5} +\end{funcdesc} + +\begin{funcdesc}{heading}{} +Return the current orientation of the turtle. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{setheading}{angle} +Set the orientation of the turtle to \var{angle}. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{position}{} +Return the current location of the turtle as an \code{(x,y)} pair. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{setx}{x} +Set the x coordinate of the turtle to \var{x}. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{sety}{y} +Set the y coordinate of the turtle to \var{y}. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{window\_width}{} +Return the width of the canvas window. +\versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{window\_height}{} +Return the height of the canvas window. +\versionadded{2.3} +\end{funcdesc} + This module also does \code{from math import *}, so see the documentation for the \refmodule{math} module for additional constants and functions useful for turtle graphics. @@ -134,19 +241,25 @@ Define a pen. All above functions can be called as a methods on the given pen. The constructor automatically creates a canvas do be drawn on. \end{classdesc} +\begin{classdesc}{Turtle}{} +Define a pen. This is essentially a synonym for \code{Pen()}; +\class{Turtle} is an empty subclass of \class{Pen}. +\end{classdesc} + \begin{classdesc}{RawPen}{canvas} Define a pen which draws on a canvas \var{canvas}. This is useful if you want to use the module to create graphics in a ``real'' program. \end{classdesc} -\subsection{Pen and RawPen Objects \label{pen-rawpen-objects}} +\subsection{Turtle, Pen and RawPen Objects \label{pen-rawpen-objects}} -\class{Pen} and \class{RawPen} objects have all the global functions -described above, except for \function{demo()} as methods, which -manipulate the given pen. +Most of the global functions available in the module are also +available as methods of the \class{Turtle}, \class{Pen} and +\class{RawPen} classes, affecting only the state of the given pen. The only method which is more powerful as a method is -\function{degrees()}. +\function{degrees()}, which takes an optional argument letting +you specify the number of units corresponding to a full circle: \begin{methoddesc}{degrees}{\optional{fullcircle}} \var{fullcircle} is by default 360. This can cause the pen to have any diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex index f8f557d..c80a87a 100644 --- a/Doc/lib/libtypes.tex +++ b/Doc/lib/libtypes.tex @@ -176,6 +176,30 @@ The type of buffer objects created by the \function{buffer()}\bifuncindex{buffer} function. \end{datadesc} +\begin{datadesc}{DictProxyType} +The type of dict proxies, such as \code{TypeType.__dict__}. +\end{datadesc} + +\begin{datadesc}{NotImplementedType} +The type of \code{NotImplemented} +\end{datadesc} + +\begin{datadesc}{GetSetDescriptorType} +The type of objects defined in extension modules with \code{PyGetSetDef}, such +as \code{FrameType.f_locals} or \code{array.array.typecode}. This constant is +not defined in implementations of Python that do not have such extension +types, so for portable code use \code{hasattr(types, 'GetSetDescriptorType')}. +\versionadded{2.5} +\end{datadesc} + +\begin{datadesc}{MemberDescriptorType} +The type of objects defined in extension modules with \code{PyMemberDef}, such +as \code {datetime.timedelta.days}. This constant is not defined in +implementations of Python that do not have such extension types, so for +portable code use \code{hasattr(types, 'MemberDescriptorType')}. +\versionadded{2.5} +\end{datadesc} + \begin{datadesc}{StringTypes} A sequence containing \code{StringType} and \code{UnicodeType} used to facilitate easier checking for any string object. Using this is more diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex index df78152..e7d388f 100644 --- a/Doc/lib/libundoc.tex +++ b/Doc/lib/libundoc.tex @@ -49,7 +49,7 @@ document these. \item[\module{bsddb185}] --- Backwards compatibility module for systems which still use the Berkeley - DB 1.85 module. It is normally only available on certain BSD Unix-based + DB 1.85 module. It is normally only available on certain BSD \UNIX-based systems. It should never be used directly. \end{description} diff --git a/Doc/lib/libunicodedata.tex b/Doc/lib/libunicodedata.tex index dcbda77..435466a 100644 --- a/Doc/lib/libunicodedata.tex +++ b/Doc/lib/libunicodedata.tex @@ -14,11 +14,11 @@ This module provides access to the Unicode Character Database which defines character properties for all Unicode characters. The data in this database is based on the \file{UnicodeData.txt} file version -4.1.0 which is publically available from \url{ftp://ftp.unicode.org/}. +4.1.0 which is publicly available from \url{ftp://ftp.unicode.org/}. The module uses the same names and symbols as defined by the UnicodeData File Format 4.1.0 (see -\url{http://www.unicode.org/Public/4.1-Update/UnicodeData-4.1.0.html}). It +\url{http://www.unicode.org/Public/4.1.0/ucd/UCD.html}). It defines the following functions: \begin{funcdesc}{lookup}{name} @@ -108,7 +108,7 @@ decomposition, and translates each character into its decomposed form. Normal form C (NFC) first applies a canonical decomposition, then composes pre-combined characters again. -In addition to these two forms, there two additional normal forms +In addition to these two forms, there are two additional normal forms based on compatibility equivalence. In Unicode, certain characters are supported which normally would be unified with other characters. For example, U+2160 (ROMAN NUMERAL ONE) is really the same thing as U+0049 @@ -139,3 +139,22 @@ the Unicode database (such as IDNA). \versionadded{2.5} \end{datadesc} + +Examples: + +\begin{verbatim} +>>> unicodedata.lookup('LEFT CURLY BRACKET') +u'{' +>>> unicodedata.name(u'/') +'SOLIDUS' +>>> unicodedata.decimal(u'9') +9 +>>> unicodedata.decimal(u'a') +Traceback (most recent call last): + File "<stdin>", line 1, in ? +ValueError: not a decimal +>>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase +'Lu' +>>> unicodedata.bidirectional(u'\u0660') # 'A'rabic, 'N'umber +'AN' +\end{verbatim} diff --git a/Doc/lib/libunittest.tex b/Doc/lib/libunittest.tex index 51b321e..f40493d 100644 --- a/Doc/lib/libunittest.tex +++ b/Doc/lib/libunittest.tex @@ -10,19 +10,19 @@ \versionadded{2.1} -The Python unit testing framework, often referred to as ``PyUnit,'' is +The Python unit testing framework, sometimes referred to as ``PyUnit,'' is a Python language version of JUnit, by Kent Beck and Erich Gamma. JUnit is, in turn, a Java version of Kent's Smalltalk testing framework. Each is the de facto standard unit testing framework for its respective language. -PyUnit supports test automation, sharing of setup and shutdown code -for tests, aggregation of tests into collections, and independence of +\module{unittest} supports test automation, sharing of setup and shutdown +code for tests, aggregation of tests into collections, and independence of the tests from the reporting framework. The \module{unittest} module provides classes that make it easy to support these qualities for a set of tests. -To achieve this, PyUnit supports some important concepts: +To achieve this, \module{unittest} supports some important concepts: \begin{definitions} \term{test fixture} @@ -33,10 +33,9 @@ starting a server process. \term{test case} A \dfn{test case} is the smallest unit of testing. It checks for a -specific response to a particular set of inputs. PyUnit provides a -base class, \class{TestCase}, which may be used to create new test -cases. You may provide your own implementation that does not subclass -from \class{TestCase}, of course. +specific response to a particular set of inputs. \module{unittest} +provides a base class, \class{TestCase}, which may be used to create +new test cases. \term{test suite} A \dfn{test suite} is a collection of test cases, test suites, or @@ -54,8 +53,8 @@ indicate the results of executing the tests. The test case and test fixture concepts are supported through the \class{TestCase} and \class{FunctionTestCase} classes; the former should be used when creating new tests, and the latter can be used when -integrating existing test code with a PyUnit-driven framework. When -building test fixtures using \class{TestCase}, the \method{setUp()} +integrating existing test code with a \module{unittest}-driven framework. +When building test fixtures using \class{TestCase}, the \method{setUp()} and \method{tearDown()} methods can be overridden to provide initialization and cleanup for the fixture. With \class{FunctionTestCase}, existing functions can be passed to the @@ -74,19 +73,17 @@ the suite is executed, all tests added directly to the suite and in A test runner is an object that provides a single method, \method{run()}, which accepts a \class{TestCase} or \class{TestSuite} object as a parameter, and returns a result object. The class -\class{TestResult} is provided for use as the result object. PyUnit -provide the \class{TextTestRunner} as an example test runner which -reports test results on the standard error stream by default. -Alternate runners can be implemented for other environments (such as -graphical environments) without any need to derive from a specific -class. +\class{TestResult} is provided for use as the result object. +\module{unittest} provides the \class{TextTestRunner} as an example +test runner which reports test results on the standard error stream by +default. Alternate runners can be implemented for other environments +(such as graphical environments) without any need to derive from a +specific class. \begin{seealso} \seemodule{doctest}{Another test-support module with a very different flavor.} - \seetitle[http://pyunit.sourceforge.net/]{PyUnit Web Site}{The - source for further information on PyUnit.} \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk Testing: With Patterns}{Kent Beck's original paper on testing frameworks using the pattern shared by @@ -166,7 +163,7 @@ run from the command line. For example, the last two lines may be replaced with: \begin{verbatim} -suite = unittest.makeSuite(TestSequenceFunctions) +suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions) unittest.TextTestRunner(verbosity=2).run(suite) \end{verbatim} @@ -194,8 +191,8 @@ of the documentation explores the full feature set from first principles. The basic building blocks of unit testing are \dfn{test cases} --- single scenarios that must be set up and checked for correctness. In -PyUnit, test cases are represented by instances of the -\class{TestCase} class in the \refmodule{unittest} module. To make +\module{unittest}, test cases are represented by instances of +\module{unittest}'s \class{TestCase} class. To make your own test cases you must write subclasses of \class{TestCase}, or use \class{FunctionTestCase}. @@ -207,7 +204,7 @@ The testing code of a \class{TestCase} instance should be entirely self contained, such that it can be run either in isolation or in arbitrary combination with any number of other test cases. -The simplest test case subclass will simply override the +The simplest \class{TestCase} subclass will simply override the \method{runTest()} method in order to perform specific testing code: \begin{verbatim} @@ -221,12 +218,13 @@ class DefaultWidgetSizeTestCase(unittest.TestCase): Note that in order to test something, we use the one of the \method{assert*()} or \method{fail*()} methods provided by the -\class{TestCase} base class. If the test fails when the test case -runs, an exception will be raised, and the testing framework will -identify the test case as a \dfn{failure}. Other exceptions that do -not arise from checks made through the \method{assert*()} and -\method{fail*()} methods are identified by the testing framework as -\dfn{errors}. +\class{TestCase} base class. If the test fails, an exception will be +raised, and \module{unittest} will identify the test case as a +\dfn{failure}. Any other exceptions will be treated as \dfn{errors}. +This helps you identify where the problem is: \dfn{failures} are caused by +incorrect results - a 5 where you expected a 6. \dfn{Errors} are caused by +incorrect code - e.g., a \exception{TypeError} caused by an incorrect +function call. The way to run a test case will be described later. For now, note that to construct an instance of such a test case, we call its @@ -237,7 +235,7 @@ testCase = DefaultWidgetSizeTestCase() \end{verbatim} Now, such test cases can be numerous, and their set-up can be -repetitive. In the above case, constructing a ``Widget'' in each of +repetitive. In the above case, constructing a \class{Widget} in each of 100 Widget test case subclasses would mean unsightly duplication. Luckily, we can factor out such set-up code by implementing a method @@ -283,7 +281,7 @@ class SimpleWidgetTestCase(unittest.TestCase): \end{verbatim} If \method{setUp()} succeeded, the \method{tearDown()} method will be -run regardless of whether or not \method{runTest()} succeeded. +run whether \method{runTest()} succeeded or not. Such a working environment for the testing code is called a \dfn{fixture}. @@ -292,8 +290,8 @@ Often, many small test cases will use the same fixture. In this case, we would end up subclassing \class{SimpleWidgetTestCase} into many small one-method classes such as \class{DefaultWidgetSizeTestCase}. This is time-consuming and -discouraging, so in the same vein as JUnit, PyUnit provides a simpler -mechanism: +discouraging, so in the same vein as JUnit, \module{unittest} provides +a simpler mechanism: \begin{verbatim} import unittest @@ -329,9 +327,9 @@ resizeTestCase = WidgetTestCase("testResize") \end{verbatim} Test case instances are grouped together according to the features -they test. PyUnit provides a mechanism for this: the \class{test -suite}, represented by the class \class{TestSuite} in the -\refmodule{unittest} module: +they test. \module{unittest} provides a mechanism for this: the +\dfn{test suite}, represented by \module{unittest}'s \class{TestSuite} +class: \begin{verbatim} widgetTestSuite = unittest.TestSuite() @@ -354,28 +352,30 @@ def suite(): or even: \begin{verbatim} -class WidgetTestSuite(unittest.TestSuite): - def __init__(self): - unittest.TestSuite.__init__(self,map(WidgetTestCase, - ("testDefaultSize", - "testResize"))) -\end{verbatim} +def suite(): + tests = ["testDefaultSize", "testResize"] -(The latter is admittedly not for the faint-hearted!) + return unittest.TestSuite(map(WidgetTestCase, tests)) +\end{verbatim} Since it is a common pattern to create a \class{TestCase} subclass -with many similarly named test functions, there is a convenience -function called \function{makeSuite()} that constructs a test suite -that comprises all of the test cases in a test case class: +with many similarly named test functions, \module{unittest} provides a +\class{TestLoader} class that can be used to automate the process of +creating a test suite and populating it with individual tests. +For example, \begin{verbatim} -suite = unittest.makeSuite(WidgetTestCase) +suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase) \end{verbatim} -Note that when using the \function{makeSuite()} function, the order in -which the various test cases will be run by the test suite is the -order determined by sorting the test function names using the -\function{cmp()} built-in function. +will create a test suite that will run +\code{WidgetTestCase.testDefaultSize()} and \code{WidgetTestCase.testResize}. +\class{TestLoader} uses the \code{'test'} method name prefix to identify +test methods automatically. + +Note that the order in which the various test cases will be run is +determined by sorting the test function names with the built-in +\function{cmp()} function. Often it is desirable to group suites of test cases together, so as to run tests for the whole system at once. This is easy, since @@ -385,13 +385,13 @@ as \class{TestCase} instances can be added to a \class{TestSuite}: \begin{verbatim} suite1 = module1.TheTestSuite() suite2 = module2.TheTestSuite() -alltests = unittest.TestSuite((suite1, suite2)) +alltests = unittest.TestSuite([suite1, suite2]) \end{verbatim} You can place the definitions of test cases and test suites in the same modules as the code they are to test (such as \file{widget.py}), but there are several advantages to placing the test code in a -separate module, such as \file{widgettests.py}: +separate module, such as \file{test_widget.py}: \begin{itemize} \item The test module can be run standalone from the command line. @@ -412,13 +412,12 @@ separate module, such as \file{widgettests.py}: \label{legacy-unit-tests}} Some users will find that they have existing test code that they would -like to run from PyUnit, without converting every old test function to -a \class{TestCase} subclass. +like to run from \module{unittest}, without converting every old test +function to a \class{TestCase} subclass. -For this reason, PyUnit provides a \class{FunctionTestCase} class. -This subclass of \class{TestCase} can be used to wrap an existing test -function. Set-up and tear-down functions can also optionally be -wrapped. +For this reason, \module{unittest} provides a \class{FunctionTestCase} +class. This subclass of \class{TestCase} can be used to wrap an existing +test function. Set-up and tear-down functions can also be provided. Given the following test function: @@ -436,7 +435,8 @@ testcase = unittest.FunctionTestCase(testSomething) \end{verbatim} If there are additional set-up and tear-down methods that should be -called as part of the test case's operation, they can also be provided: +called as part of the test case's operation, they can also be provided +like so: \begin{verbatim} testcase = unittest.FunctionTestCase(testSomething, @@ -444,9 +444,19 @@ testcase = unittest.FunctionTestCase(testSomething, tearDown=deleteSomethingDB) \end{verbatim} -\note{PyUnit supports the use of \exception{AssertionError} -as an indicator of test failure, but does not recommend it. Future -versions may treat \exception{AssertionError} differently.} +To make migrating existing test suites easier, \module{unittest} +supports tests raising \exception{AssertionError} to indicate test failure. +However, it is recommended that you use the explicit +\method{TestCase.fail*()} and \method{TestCase.assert*()} methods instead, +as future versions of \module{unittest} may treat \exception{AssertionError} +differently. + +\note{Even though \class{FunctionTestCase} can be used to quickly convert +an existing test base over to a \module{unittest}-based system, this +approach is not recommended. Taking the time to set up proper +\class{TestCase} subclasses will make future test refactorings infinitely +easier.} + \subsection{Classes and functions @@ -454,11 +464,12 @@ versions may treat \exception{AssertionError} differently.} \begin{classdesc}{TestCase}{} Instances of the \class{TestCase} class represent the smallest - testable units in a set of tests. This class is intended to be used - as a base class, with specific tests being implemented by concrete - subclasses. This class implements the interface needed by the test - runner to allow it to drive the test, and methods that the test code - can use to check for and report various kinds of failures. + testable units in the \module{unittest} universe. This class is + intended to be used as a base class, with specific tests being + implemented by concrete subclasses. This class implements the + interface needed by the test runner to allow it to drive the + test, and methods that the test code can use to check for and + report various kinds of failure. \end{classdesc} \begin{classdesc}{FunctionTestCase}{testFunc\optional{, @@ -474,33 +485,33 @@ versions may treat \exception{AssertionError} differently.} \begin{classdesc}{TestSuite}{\optional{tests}} This class represents an aggregation of individual tests cases and test suites. The class presents the interface needed by the test - runner to allow it to be run as any other test case, but all the - contained tests and test suites are executed. Additional methods - are provided to add test cases and suites to the aggregation. If - \var{tests} is given, it must be a sequence of individual tests that - will be added to the suite. + runner to allow it to be run as any other test case. Running a + \class{TestSuite} instance is the same as iterating over the suite, + running each test individually. + + If \var{tests} is given, it must be an iterable of individual test cases or + other test suites that will be used to build the suite initially. + Additional methods are provided to add test cases and suites to the + collection later on. \end{classdesc} \begin{classdesc}{TestLoader}{} This class is responsible for loading tests according to various criteria and returning them wrapped in a \class{TestSuite}. It can load all tests within a given module or \class{TestCase} - class. When loading from a module, it considers all - \class{TestCase}-derived classes. For each such class, it creates - an instance for each method with a name beginning with the string - \samp{test}. + subclass. \end{classdesc} \begin{datadesc}{defaultTestLoader} - Instance of the \class{TestLoader} class which can be shared. If no + Instance of the \class{TestLoader} class intended to be shared. If no customization of the \class{TestLoader} is needed, this instance can - always be used instead of creating new instances. + be used instead of repeatedly creating new instances. \end{datadesc} \begin{classdesc}{TextTestRunner}{\optional{stream\optional{, descriptions\optional{, verbosity}}}} A basic test runner implementation which prints results on standard - output. It has a few configurable parameters, but is essentially + error. It has a few configurable parameters, but is essentially very simple. Graphical applications which run test suites should provide alternate implementations. \end{classdesc} @@ -510,7 +521,8 @@ versions may treat \exception{AssertionError} differently.} testRunner\optional{, testRunner}}}}}} A command-line program that runs a set of tests; this is primarily for making test modules conveniently executable. The simplest use - for this function is: + for this function is to include the following line at the end of a + test script: \begin{verbatim} if __name__ == '__main__': @@ -518,10 +530,11 @@ if __name__ == '__main__': \end{verbatim} \end{funcdesc} -In some cases, the existing tests may have be written using the +In some cases, the existing tests may have been written using the \refmodule{doctest} module. If so, that module provides a \class{DocTestSuite} class that can automatically build -\class{unittest.TestSuite} instances from the existing test code. +\class{unittest.TestSuite} instances from the existing +\module{doctest}-based tests. \versionadded{2.3} @@ -538,7 +551,7 @@ used to run the test, another used by the test implementation to check conditions and report failures, and some inquiry methods allowing information about the test itself to be gathered. -Methods in the first group are: +Methods in the first group (running the test) are: \begin{methoddesc}[TestCase]{setUp}{} Method called to prepare the test fixture. This is called @@ -562,8 +575,10 @@ Methods in the first group are: Run the test, collecting the result into the test result object passed as \var{result}. If \var{result} is omitted or \constant{None}, a temporary result object is created and used, but is not made - available to the caller. This is equivalent to simply calling the - \class{TestCase} instance. + available to the caller. + + The same effect may be had by simply calling the \class{TestCase} + instance. \end{methoddesc} \begin{methoddesc}[TestCase]{debug}{} @@ -664,10 +679,8 @@ Testing frameworks can use the following methods to collect information on the test: \begin{methoddesc}[TestCase]{countTestCases}{} - Return the number of tests represented by the this test object. For - \class{TestCase} instances, this will always be \code{1}, but this - method is also implemented by the \class{TestSuite} class, which can - return larger values. + Return the number of tests represented by this test object. For + \class{TestCase} instances, this will always be \code{1}. \end{methoddesc} \begin{methoddesc}[TestCase]{defaultTestResult}{} @@ -678,7 +691,7 @@ information on the test: \begin{methoddesc}[TestCase]{id}{} Return a string identifying the specific test case. This is usually the full name of the test method, including the module and class - names. + name. \end{methoddesc} \begin{methoddesc}[TestCase]{shortDescription}{} @@ -694,21 +707,23 @@ information on the test: \class{TestSuite} objects behave much like \class{TestCase} objects, except they do not actually implement a test. Instead, they are used -to aggregate tests into groups that should be run together. Some -additional methods are available to add tests to \class{TestSuite} +to aggregate tests into groups of tests that should be run together. +Some additional methods are available to add tests to \class{TestSuite} instances: \begin{methoddesc}[TestSuite]{addTest}{test} - Add a \class{TestCase} or \class{TestSuite} to the set of tests that - make up the suite. + Add a \class{TestCase} or \class{TestSuite} to the suite. \end{methoddesc} \begin{methoddesc}[TestSuite]{addTests}{tests} - Add all the tests from a sequence of \class{TestCase} and + Add all the tests from an iterable of \class{TestCase} and \class{TestSuite} instances to this test suite. + + This is equivalent to iterating over \var{tests}, calling + \method{addTest()} for each element. \end{methoddesc} -The \method{run()} method is also slightly different: +\class{TestSuite} shares the following methods with \class{TestCase}: \begin{methoddesc}[TestSuite]{run}{result} Run the tests associated with this suite, collecting the result into @@ -717,6 +732,17 @@ The \method{run()} method is also slightly different: result object to be passed in. \end{methoddesc} +\begin{methoddesc}[TestSuite]{debug}{} + Run the tests associated with this suite without collecting the result. + This allows exceptions raised by the test to be propagated to the caller + and can be used to support running tests under a debugger. +\end{methoddesc} + +\begin{methoddesc}[TestSuite]{countTestCases}{} + Return the number of tests represented by this test object, including + all individual tests and sub-suites. +\end{methoddesc} + In the typical usage of a \class{TestSuite} object, the \method{run()} method is invoked by a \class{TestRunner} rather than by the end-user test harness. @@ -727,7 +753,7 @@ test harness. A \class{TestResult} object stores the results of a set of tests. The \class{TestCase} and \class{TestSuite} classes ensure that results are -properly stored; test authors do not need to worry about recording the +properly recorded; test authors do not need to worry about recording the outcome of tests. Testing frameworks built on top of \refmodule{unittest} may want @@ -745,28 +771,41 @@ formatted version of the traceback for the exception. be of interest when inspecting the results of running a set of tests: \begin{memberdesc}[TestResult]{errors} - A list containing pairs of \class{TestCase} instances and the - formatted tracebacks for tests which raised an exception but did not - signal a test failure. + A list containing 2-tuples of \class{TestCase} instances and + formatted tracebacks. Each tuple represents a test which raised an + unexpected exception. \versionchanged[Contains formatted tracebacks instead of \function{sys.exc_info()} results]{2.2} \end{memberdesc} \begin{memberdesc}[TestResult]{failures} - A list containing pairs of \class{TestCase} instances and the - formatted tracebacks for tests which signalled a failure in the code - under test. + A list containing 2-tuples of \class{TestCase} instances and + formatted tracebacks. Each tuple represents a test where a failure + was explicitly signalled using the \method{TestCase.fail*()} or + \method{TestCase.assert*()} methods. \versionchanged[Contains formatted tracebacks instead of \function{sys.exc_info()} results]{2.2} \end{memberdesc} \begin{memberdesc}[TestResult]{testsRun} - The number of tests which have been started. + The total number of tests run so far. \end{memberdesc} \begin{methoddesc}[TestResult]{wasSuccessful}{} - Returns true if all tests run so far have passed, otherwise returns - false. + Returns \constant{True} if all tests run so far have passed, + otherwise returns \constant{False}. +\end{methoddesc} + +\begin{methoddesc}[TestResult]{stop}{} + This method can be called to signal that the set of tests being run + should be aborted by setting the \class{TestResult}'s \code{shouldStop} + attribute to \constant{True}. \class{TestRunner} objects should respect + this flag and return without running any additional tests. + + For example, this feature is used by the \class{TextTestRunner} class + to stop the test framework when the user signals an interrupt from + the keyboard. Interactive tools which provide \class{TestRunner} + implementations can use this in a similar manner. \end{methoddesc} @@ -786,10 +825,9 @@ reporting while tests are being run. \end{methoddesc} \begin{methoddesc}[TestResult]{addError}{test, err} - Called when the test case \var{test} raises an exception without - signalling a test failure. \var{err} is a tuple of the form - returned by \function{sys.exc_info()}: \code{(\var{type}, - \var{value}, \var{traceback})}. + Called when the test case \var{test} raises an unexpected exception + \var{err} is a tuple of the form returned by \function{sys.exc_info()}: + \code{(\var{type}, \var{value}, \var{traceback})}. \end{methoddesc} \begin{methoddesc}[TestResult]{addFailure}{test, err} @@ -800,23 +838,10 @@ reporting while tests are being run. \end{methoddesc} \begin{methoddesc}[TestResult]{addSuccess}{test} - This method is called for a test that does not fail; \var{test} is - the test case object. + Called when the test case \var{test} succeeds. \end{methoddesc} -One additional method is available for \class{TestResult} objects: - -\begin{methoddesc}[TestResult]{stop}{} - This method can be called to signal that the set of tests being run - should be aborted. Once this has been called, the - \class{TestRunner} object return to its caller without running any - additional tests. This is used by the \class{TextTestRunner} class - to stop the test framework when the user signals an interrupt from - the keyboard. Interactive tools which provide runners can use this - in a similar manner. -\end{methoddesc} - \subsection{TestLoader Objects \label{testloader-objects}} @@ -824,15 +849,15 @@ One additional method is available for \class{TestResult} objects: The \class{TestLoader} class is used to create test suites from classes and modules. Normally, there is no need to create an instance of this class; the \refmodule{unittest} module provides an instance -that can be shared as the \code{defaultTestLoader} module attribute. -Using a subclass or instance would allow customization of some +that can be shared as \code{unittest.defaultTestLoader}. +Using a subclass or instance, however, allows customization of some configurable properties. \class{TestLoader} objects have the following methods: \begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass} Return a suite of all tests cases contained in the - \class{TestCase}-derived class \class{testCaseClass}. + \class{TestCase}-derived \class{testCaseClass}. \end{methoddesc} \begin{methoddesc}[TestLoader]{loadTestsFromModule}{module} @@ -842,7 +867,7 @@ configurable properties. method defined for the class. \warning{While using a hierarchy of - \class{Testcase}-derived classes can be convenient in sharing + \class{TestCase}-derived classes can be convenient in sharing fixtures and helper functions, defining test methods on base classes that are not intended to be instantiated directly does not play well with this method. Doing so, however, can be useful when the @@ -853,21 +878,23 @@ configurable properties. Return a suite of all tests cases given a string specifier. The specifier \var{name} is a ``dotted name'' that may resolve - either to a module, a test case class, a test method within a test - case class, or a callable object which returns a \class{TestCase} or - \class{TestSuite} instance. For example, if you have a module - \module{SampleTests} containing a \class{TestCase}-derived class - \class{SampleTestCase} with three test methods (\method{test_one()}, - \method{test_two()}, and \method{test_three()}), the specifier - \code{'SampleTests.SampleTestCase'} would cause this method to - return a suite which will run all three test methods. Using the - specifier \code{'SampleTests.SampleTestCase.test_two'} would cause - it to return a test suite which will run only the + either to a module, a test case class, a \class{TestSuite} instance, + a test method within a test case class, or a callable object which + returns a \class{TestCase} or \class{TestSuite} instance. + + For example, if you have a module \module{SampleTests} containing a + \class{TestCase}-derived class \class{SampleTestCase} with three test + methods (\method{test_one()}, \method{test_two()}, and + \method{test_three()}), the specifier \code{'SampleTests.SampleTestCase'} + would cause this method to return a suite which will run all three test + methods. Using the specifier \code{'SampleTests.SampleTestCase.test_two'} + would cause it to return a test suite which will run only the \method{test_two()} test method. The specifier can refer to modules and packages which have not been imported; they will be imported as a side-effect. - The method optionally resolves \var{name} relative to a given module. + The method optionally resolves \var{name} relative to the given + \var{module}. \end{methoddesc} \begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}} @@ -888,17 +915,22 @@ either by subclassing or assignment on an instance: \begin{memberdesc}[TestLoader]{testMethodPrefix} String giving the prefix of method names which will be interpreted as test methods. The default value is \code{'test'}. + + This affects \method{getTestCaseNames()} and all the + \method{loadTestsFrom*()} methods. \end{memberdesc} \begin{memberdesc}[TestLoader]{sortTestMethodsUsing} Function to be used to compare method names when sorting them in - \method{getTestCaseNames()}. The default value is the built-in - \function{cmp()} function; it can be set to \constant{None} to disable - the sort. + \method{getTestCaseNames()} and all the \method{loadTestsFrom*()} methods. + The default value is the built-in \function{cmp()} function; the attribute + can also be set to \constant{None} to disable the sort. \end{memberdesc} \begin{memberdesc}[TestLoader]{suiteClass} Callable object that constructs a test suite from a list of tests. No methods on the resulting object are needed. The default value is the \class{TestSuite} class. + + This affects all the \method{loadTestsFrom*()} methods. \end{memberdesc} diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex index 0a84c1a..75ee310 100644 --- a/Doc/lib/liburllib.tex +++ b/Doc/lib/liburllib.tex @@ -270,10 +270,10 @@ off completely. Its default value is \code{None}, in which case environmental proxy settings will be used if present, as discussed in the definition of \function{urlopen()}, above. -Additional keyword parameters, collected in \var{x509}, are used for -authentication with the \file{https:} scheme. The keywords -\var{key_file} and \var{cert_file} are supported; both are needed to -actually retrieve a resource at an \file{https:} URL. +Additional keyword parameters, collected in \var{x509}, may be used for +authentication of the client when using the \file{https:} scheme. The keywords +\var{key_file} and \var{cert_file} are supported to provide an +SSL key and certificate; both are needed to support client authentication. \class{URLopener} objects will raise an \exception{IOError} exception if the server returns an error code. diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex index f4351c3..542a7b8 100644 --- a/Doc/lib/liburllib2.tex +++ b/Doc/lib/liburllib2.tex @@ -19,7 +19,8 @@ Open the URL \var{url}, which can be either a string or a \class{Request} object. \var{data} may be a string specifying additional data to send to the -server. Currently HTTP requests are the only ones that use \var{data}; +server, or \code{None} if no such data is needed. +Currently HTTP requests are the only ones that use \var{data}; the HTTP request will be a POST instead of a GET when the \var{data} parameter is provided. \var{data} should be a buffer in the standard \mimetype{application/x-www-form-urlencoded} format. The @@ -97,8 +98,17 @@ The following classes are provided: \optional{, origin_req_host}\optional{, unverifiable}} This class is an abstraction of a URL request. -\var{url} should be a string which is a valid URL. For a description -of \var{data} see the \method{add_data()} description. +\var{url} should be a string containing a valid URL. + +\var{data} may be a string specifying additional data to send to the +server, or \code{None} if no such data is needed. +Currently HTTP requests are the only ones that use \var{data}; +the HTTP request will be a POST instead of a GET when the \var{data} +parameter is provided. \var{data} should be a buffer in the standard +\mimetype{application/x-www-form-urlencoded} format. The +\function{urllib.urlencode()} function takes a mapping or sequence of +2-tuples and returns a string in this format. + \var{headers} should be a dictionary, and will be treated as if \method{add_header()} was called with each key and value as arguments. diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex new file mode 100644 index 0000000..a9d5295 --- /dev/null +++ b/Doc/lib/libuuid.tex @@ -0,0 +1,234 @@ +\section{\module{uuid} --- + UUID objects according to RFC 4122} +\declaremodule{builtin}{uuid} +\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122} +\moduleauthor{Ka-Ping Yee}{ping@zesty.ca} +\sectionauthor{George Yoshida}{quiver@users.sourceforge.net} + +\versionadded{2.5} + +This module provides immutable \class{UUID} objects (the \class{UUID} class) +and the functions \function{uuid1()}, \function{uuid3()}, +\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4, +and 5 UUIDs as specified in \rfc{4122}. + +If all you want is a unique ID, you should probably call +\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()} +may compromise privacy since it creates a UUID containing the computer's +network address. \function{uuid4()} creates a random UUID. + +\begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{, +fields\optional{, int\optional{, version}}}}}} + +%Instances of the UUID class represent UUIDs as specified in RFC 4122. +%UUID objects are immutable, hashable, and usable as dictionary keys. +%Converting a UUID to a string with str() yields something in the form +%'12345678-1234-1234-1234-123456789abc'. The UUID constructor accepts +%four possible forms: a similar string of hexadecimal digits, or a +%string of 16 raw bytes as an argument named 'bytes', or a tuple of +%six integer fields (with 32-bit, 16-bit, 16-bit, 8-bit, 8-bit, and +%48-bit values respectively) as an argument named 'fields', or a single +%128-bit integer as an argument named 'int'. + +Create a UUID from either a string of 32 hexadecimal digits, +a string of 16 bytes as the \var{bytes} argument, a tuple of six +integers (32-bit \var{time_low}, 16-bit \var{time_mid}, +16-bit \var{time_hi_version}, +8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node}) +as the \var{fields} argument, or a single 128-bit integer as the \var{int} +argument. When a string of hex digits is given, curly braces, +hyphens, and a URN prefix are all optional. For example, these +expressions all yield the same UUID: + +\begin{verbatim} +UUID('{12345678-1234-5678-1234-567812345678}') +UUID('12345678123456781234567812345678') +UUID('urn:uuid:12345678-1234-5678-1234-567812345678') +UUID(bytes='\x12\x34\x56\x78'*4) +UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) +UUID(int=0x12345678123456781234567812345678) +\end{verbatim} + +Exactly one of \var{hex}, \var{bytes}, \var{fields}, or \var{int} must +be given. The \var{version} argument is optional; if given, the +resulting UUID will have its variant and version number set according to +RFC 4122, overriding bits in the given \var{hex}, \var{bytes}, +\var{fields}, or \var{int}. + +\end{classdesc} + +\class{UUID} instances have these read-only attributes: + +\begin{memberdesc}{bytes} +The UUID as a 16-byte string. +\end{memberdesc} + +\begin{memberdesc}{fields} +A tuple of the six integer fields of the UUID, which are also available +as six individual attributes and two derived attributes: + +\begin{tableii}{l|l}{member}{Field}{Meaning} + \lineii{time_low}{the first 32 bits of the UUID} + \lineii{time_mid}{the next 16 bits of the UUID} + \lineii{time_hi_version}{the next 16 bits of the UUID} + \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID} + \lineii{clock_seq_low}{the next 8 bits of the UUID} + \lineii{node}{the last 48 bits of the UUID} + \lineii{time}{the 60-bit timestamp} + \lineii{clock_seq}{the 14-bit sequence number} +\end{tableii} + + +\end{memberdesc} + +\begin{memberdesc}{hex} +The UUID as a 32-character hexadecimal string. +\end{memberdesc} + +\begin{memberdesc}{int} +The UUID as a 128-bit integer. +\end{memberdesc} + +\begin{memberdesc}{urn} +The UUID as a URN as specified in RFC 4122. +\end{memberdesc} + +\begin{memberdesc}{variant} +The UUID variant, which determines the internal layout of the UUID. +This will be an integer equal to one of the constants +\constant{RESERVED_NCS}, +\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or +\constant{RESERVED_FUTURE}). +\end{memberdesc} + +\begin{memberdesc}{version} +The UUID version number (1 through 5, meaningful only +when the variant is \constant{RFC_4122}). +\end{memberdesc} + +The \module{uuid} module defines the following functions + +\begin{funcdesc}{getnode}{} +Get the hardware address as a 48-bit positive integer. The first time this +runs, it may launch a separate program, which could be quite slow. If all +attempts to obtain the hardware address fail, we choose a random 48-bit +number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware +address" means the MAC address of a network interface, and on a machine +with multiple network interfaces the MAC address of any one of them may +be returned. +\end{funcdesc} +\index{getnode} + +\begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}} +Generate a UUID from a host ID, sequence number, and the current time. +If \var{node} is not given, \function{getnode()} is used to obtain the +hardware address. +If \var{clock_seq} is given, it is used as the sequence number; +otherwise a random 14-bit sequence number is chosen. +\end{funcdesc} +\index{uuid1} + +\begin{funcdesc}{uuid3}{namespace, name} +Generate a UUID based upon a MD5 hash of the \var{name} string value +drawn from a specified namespace. \var{namespace} +must be one of \constant{NAMESPACE_DNS}, +\constant{NAMESPACE_URL}, \constant{NAMESPACE_OID}, +or \constant{NAMESPACE_X500}. +\end{funcdesc} +\index{uuid3} + +\begin{funcdesc}{uuid4}{} +Generate a random UUID. +\end{funcdesc} +\index{uuid4} + +\begin{funcdesc}{uuid5}{namespace, name} +Generate a UUID based upon a SHA-1 hash of the \var{name} string value +drawn from a specified namespace. \var{namespace} +must be one of \constant{NAMESPACE_DNS}, +\constant{NAMESPACE_URL}, \constant{NAMESPACE_OID}, +or \constant{NAMESPACE_X500}. +\end{funcdesc} +\index{uuid5} + +The \module{uuid} module defines the following namespace constants +for use with \function{uuid3()} or \function{uuid5()}. + +\begin{datadesc}{NAMESPACE_DNS} +Fully-qualified domain name namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_URL} +URL namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_OID} +ISO OID namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_X500} +X.500 DN namespace UUID. +\end{datadesc} + +The \module{uuid} module defines the following constants +for the possible values of the \member{variant} attribute: + +\begin{datadesc}{RESERVED_NCS} +Reserved for NCS compatibility. +\end{datadesc} + +\begin{datadesc}{RFC_4122} +Uses UUID layout specified in \rfc{4122}. +\end{datadesc} + +\begin{datadesc}{RESERVED_MICROSOFT} +Reserved for Microsoft backward compatibility. +\end{datadesc} + +\begin{datadesc}{RESERVED_FUTURE} +Reserved for future definition. +\end{datadesc} + + +\begin{seealso} + \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{ + This specifies a Uniform Resource Name namespace for UUIDs.} +\end{seealso} + +\subsection{Example \label{uuid-example}} + +Here is a typical usage: +\begin{verbatim} +>>> import uuid + +# make a UUID based on the host ID and current time +>>> uuid.uuid1() +UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') + +# make a UUID using an MD5 hash of a namespace UUID and a name +>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') +UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') + +# make a random UUID +>>> uuid.uuid4() +UUID('16fd2706-8baf-433b-82eb-8c7fada847da') + +# make a UUID using a SHA-1 hash of a namespace UUID and a name +>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') +UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') + +# make a UUID from a string of hex digits (braces and hyphens ignored) +>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') + +# convert a UUID to a string of hex digits in standard form +>>> str(x) +'00010203-0405-0607-0809-0a0b0c0d0e0f' + +# get the raw 16 bytes of the UUID +>>> x.bytes +'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' + +# make a UUID from a 16-byte string +>>> uuid.UUID(bytes=x.bytes) +UUID('00010203-0405-0607-0809-0a0b0c0d0e0f') +\end{verbatim} diff --git a/Doc/lib/libwarnings.tex b/Doc/lib/libwarnings.tex index 7b829a0..08c0340 100644 --- a/Doc/lib/libwarnings.tex +++ b/Doc/lib/libwarnings.tex @@ -71,6 +71,11 @@ runtime features.} \lineii{FutureWarning}{Base category for warnings about constructs that will change semantically in the future.} +\lineii{PendingDeprecationWarning}{Base category for warnings about +features that will be deprecated in the future (ignored by default).} + +\lineii{ImportWarning}{Base category for warnings triggered during the +process of importing a module (ignored by default).} \end{tableii} While these are technically built-in exceptions, they are documented @@ -143,6 +148,17 @@ arguments for all \programopt{-W} options without interpretation in it is first imported (invalid options are ignored, after printing a message to \code{sys.stderr}). +The warnings that are ignored by default may be enabled by passing + \programopt{-Wd} to the interpreter. This enables default handling +for all warnings, including those that are normally ignored by +default. This is particular useful for enabling ImportWarning when +debugging problems importing a developed package. ImportWarning can +also be enabled explicitly in Python code using: + +\begin{verbatim} + warnings.simplefilter('default', ImportWarning) +\end{verbatim} + \subsection{Available Functions \label{warning-functions}} @@ -209,14 +225,26 @@ Insert an entry into the list of warnings filters. The entry is inserted at the front by default; if \var{append} is true, it is inserted at the end. This checks the types of the arguments, compiles the message and -module regular expressions, and inserts them as a tuple in front -of the warnings filter. Entries inserted later override entries -inserted earlier, if both match a particular warning. Omitted -arguments default to a value that matches everything. +module regular expressions, and inserts them as a tuple in the +list of warnings filters. Entries closer to the front of the list +override entries later in the list, if both match a particular +warning. Omitted arguments default to a value that matches +everything. +\end{funcdesc} + +\begin{funcdesc}{simplefilter}{action\optional{, + category\optional{, + lineno\optional{, append}}}} +Insert a simple entry into the list of warnings filters. The meaning +of the function parameters is as for \function{filterwarnings()}, but +regular expressions are not needed as the filter inserted always +matches any message in any module as long as the category and line +number match. \end{funcdesc} \begin{funcdesc}{resetwarnings}{} Reset the warnings filter. This discards the effect of all previous calls to \function{filterwarnings()}, including that of the -\programopt{-W} command line options. +\programopt{-W} command line options and calls to +\function{simplefilter()}. \end{funcdesc} diff --git a/Doc/lib/libweakref.tex b/Doc/lib/libweakref.tex index fc949e6..6f676a2 100644 --- a/Doc/lib/libweakref.tex +++ b/Doc/lib/libweakref.tex @@ -65,10 +65,14 @@ class Dict(dict): obj = Dict(red=1, green=2, blue=3) # this object is weak referencable \end{verbatim} -Extension types can easily be made to support weak references; see section -\ref{weakref-extension}, ``Weak References in Extension Types,'' for more -information. - +Extension types can easily be made to support weak references; see +``\ulink{Weak Reference Support}{../ext/weakref-support.html}'' in +\citetitle[../ext/ext.html]{Extending and Embedding the Python +Interpreter}. +% The referenced section used to appear in this document with the +% \label weakref-extension. It would be good to be able to generate a +% redirect for the corresponding HTML page (weakref-extension.html) +% for on-line versions of this document. \begin{classdesc}{ref}{object\optional{, callback}} Return a weak reference to \var{object}. The original object can be @@ -330,83 +334,3 @@ def remember(obj): def id2obj(oid): return _id2obj_dict[oid] \end{verbatim} - - -\subsection{Weak References in Extension Types - \label{weakref-extension}} - -One of the goals of the implementation is to allow any type to -participate in the weak reference mechanism without incurring the -overhead on those objects which do not benefit by weak referencing -(such as numbers). - -For an object to be weakly referencable, the extension must include a -\ctype{PyObject*} field in the instance structure for the use of the -weak reference mechanism; it must be initialized to \NULL{} by the -object's constructor. It must also set the \member{tp_weaklistoffset} -field of the corresponding type object to the offset of the field. -Also, it needs to add \constant{Py_TPFLAGS_HAVE_WEAKREFS} to the -tp_flags slot. For example, the instance type is defined with the -following structure: - -\begin{verbatim} -typedef struct { - PyObject_HEAD - PyClassObject *in_class; /* The class object */ - PyObject *in_dict; /* A dictionary */ - PyObject *in_weakreflist; /* List of weak references */ -} PyInstanceObject; -\end{verbatim} - -The statically-declared type object for instances is defined this way: - -\begin{verbatim} -PyTypeObject PyInstance_Type = { - PyObject_HEAD_INIT(&PyType_Type) - 0, - "module.instance", - - /* Lots of stuff omitted for brevity... */ - - Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_WEAKREFS /* tp_flags */ - 0, /* tp_doc */ - 0, /* tp_traverse */ - 0, /* tp_clear */ - 0, /* tp_richcompare */ - offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */ -}; -\end{verbatim} - -The type constructor is responsible for initializing the weak reference -list to \NULL: - -\begin{verbatim} -static PyObject * -instance_new() { - /* Other initialization stuff omitted for brevity */ - - self->in_weakreflist = NULL; - - return (PyObject *) self; -} -\end{verbatim} - -The only further addition is that the destructor needs to call the -weak reference manager to clear any weak references. This should be -done before any other parts of the destruction have occurred, but is -only required if the weak reference list is non-\NULL: - -\begin{verbatim} -static void -instance_dealloc(PyInstanceObject *inst) -{ - /* Allocate temporaries if needed, but do not begin - destruction just yet. - */ - - if (inst->in_weakreflist != NULL) - PyObject_ClearWeakRefs((PyObject *) inst); - - /* Proceed with object destruction normally. */ -} -\end{verbatim} diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex index e86b578..11d77a1 100644 --- a/Doc/lib/libwebbrowser.tex +++ b/Doc/lib/libwebbrowser.tex @@ -136,6 +136,18 @@ Library Modules} manual. Only on MacOS X platform. \end{description} +Here are some simple examples: + +\begin{verbatim} +url = 'http://www.python.org' + +# Open URL in a new tab, if a browser window is already open. +webbrowser.open_new_tab(url + '/doc') + +# Open URL in new window, raising the window if possible. +webbrowser.open_new(url) +\end{verbatim} + \subsection{Browser Controller Objects \label{browser-controllers}} diff --git a/Doc/lib/libwsgiref.tex b/Doc/lib/libwsgiref.tex new file mode 100755 index 0000000..4b12e9d --- /dev/null +++ b/Doc/lib/libwsgiref.tex @@ -0,0 +1,781 @@ +\section{\module{wsgiref} --- WSGI Utilities and Reference +Implementation} +\declaremodule{}{wsgiref} +\moduleauthor{Phillip J. Eby}{pje@telecommunity.com} +\sectionauthor{Phillip J. Eby}{pje@telecommunity.com} +\modulesynopsis{WSGI Utilities and Reference Implementation} + +\versionadded{2.5} + +The Web Server Gateway Interface (WSGI) is a standard interface +between web server software and web applications written in Python. +Having a standard interface makes it easy to use an application +that supports WSGI with a number of different web servers. + +Only authors of web servers and programming frameworks need to know +every detail and corner case of the WSGI design. You don't need to +understand every detail of WSGI just to install a WSGI application or +to write a web application using an existing framework. + +\module{wsgiref} is a reference implementation of the WSGI specification +that can be used to add WSGI support to a web server or framework. It +provides utilities for manipulating WSGI environment variables and +response headers, base classes for implementing WSGI servers, a demo +HTTP server that serves WSGI applications, and a validation tool that +checks WSGI servers and applications for conformance to the +WSGI specification (\pep{333}). + +% XXX If you're just trying to write a web application... +% XXX should create a URL on python.org to point people to. + + + + + + + + + + + + + + +\subsection{\module{wsgiref.util} -- WSGI environment utilities} +\declaremodule{}{wsgiref.util} + +This module provides a variety of utility functions for working with +WSGI environments. A WSGI environment is a dictionary containing +HTTP request variables as described in \pep{333}. All of the functions +taking an \var{environ} parameter expect a WSGI-compliant dictionary to +be supplied; please see \pep{333} for a detailed specification. + +\begin{funcdesc}{guess_scheme}{environ} +Return a guess for whether \code{wsgi.url_scheme} should be ``http'' or +``https'', by checking for a \code{HTTPS} environment variable in the +\var{environ} dictionary. The return value is a string. + +This function is useful when creating a gateway that wraps CGI or a +CGI-like protocol such as FastCGI. Typically, servers providing such +protocols will include a \code{HTTPS} variable with a value of ``1'' +``yes'', or ``on'' when a request is received via SSL. So, this +function returns ``https'' if such a value is found, and ``http'' +otherwise. +\end{funcdesc} + +\begin{funcdesc}{request_uri}{environ \optional{, include_query=1}} +Return the full request URI, optionally including the query string, +using the algorithm found in the ``URL Reconstruction'' section of +\pep{333}. If \var{include_query} is false, the query string is +not included in the resulting URI. +\end{funcdesc} + +\begin{funcdesc}{application_uri}{environ} +Similar to \function{request_uri}, except that the \code{PATH_INFO} and +\code{QUERY_STRING} variables are ignored. The result is the base URI +of the application object addressed by the request. +\end{funcdesc} + +\begin{funcdesc}{shift_path_info}{environ} +Shift a single name from \code{PATH_INFO} to \code{SCRIPT_NAME} and +return the name. The \var{environ} dictionary is \emph{modified} +in-place; use a copy if you need to keep the original \code{PATH_INFO} +or \code{SCRIPT_NAME} intact. + +If there are no remaining path segments in \code{PATH_INFO}, \code{None} +is returned. + +Typically, this routine is used to process each portion of a request +URI path, for example to treat the path as a series of dictionary keys. +This routine modifies the passed-in environment to make it suitable for +invoking another WSGI application that is located at the target URI. +For example, if there is a WSGI application at \code{/foo}, and the +request URI path is \code{/foo/bar/baz}, and the WSGI application at +\code{/foo} calls \function{shift_path_info}, it will receive the string +``bar'', and the environment will be updated to be suitable for passing +to a WSGI application at \code{/foo/bar}. That is, \code{SCRIPT_NAME} +will change from \code{/foo} to \code{/foo/bar}, and \code{PATH_INFO} +will change from \code{/bar/baz} to \code{/baz}. + +When \code{PATH_INFO} is just a ``/'', this routine returns an empty +string and appends a trailing slash to \code{SCRIPT_NAME}, even though +empty path segments are normally ignored, and \code{SCRIPT_NAME} doesn't +normally end in a slash. This is intentional behavior, to ensure that +an application can tell the difference between URIs ending in \code{/x} +from ones ending in \code{/x/} when using this routine to do object +traversal. + +\end{funcdesc} + +\begin{funcdesc}{setup_testing_defaults}{environ} +Update \var{environ} with trivial defaults for testing purposes. + +This routine adds various parameters required for WSGI, including +\code{HTTP_HOST}, \code{SERVER_NAME}, \code{SERVER_PORT}, +\code{REQUEST_METHOD}, \code{SCRIPT_NAME}, \code{PATH_INFO}, and all of +the \pep{333}-defined \code{wsgi.*} variables. It only supplies default +values, and does not replace any existing settings for these variables. + +This routine is intended to make it easier for unit tests of WSGI +servers and applications to set up dummy environments. It should NOT +be used by actual WSGI servers or applications, since the data is fake! +\end{funcdesc} + + + +In addition to the environment functions above, the +\module{wsgiref.util} module also provides these miscellaneous +utilities: + +\begin{funcdesc}{is_hop_by_hop}{header_name} +Return true if 'header_name' is an HTTP/1.1 ``Hop-by-Hop'' header, as +defined by \rfc{2616}. +\end{funcdesc} + +\begin{classdesc}{FileWrapper}{filelike \optional{, blksize=8192}} +A wrapper to convert a file-like object to an iterator. The resulting +objects support both \method{__getitem__} and \method{__iter__} +iteration styles, for compatibility with Python 2.1 and Jython. +As the object is iterated over, the optional \var{blksize} parameter +will be repeatedly passed to the \var{filelike} object's \method{read()} +method to obtain strings to yield. When \method{read()} returns an +empty string, iteration is ended and is not resumable. + +If \var{filelike} has a \method{close()} method, the returned object +will also have a \method{close()} method, and it will invoke the +\var{filelike} object's \method{close()} method when called. +\end{classdesc} + + + + + + + + + + + + + + + + + + + +\subsection{\module{wsgiref.headers} -- WSGI response header tools} +\declaremodule{}{wsgiref.headers} + +This module provides a single class, \class{Headers}, for convenient +manipulation of WSGI response headers using a mapping-like interface. + +\begin{classdesc}{Headers}{headers} +Create a mapping-like object wrapping \var{headers}, which must be a +list of header name/value tuples as described in \pep{333}. Any changes +made to the new \class{Headers} object will directly update the +\var{headers} list it was created with. + +\class{Headers} objects support typical mapping operations including +\method{__getitem__}, \method{get}, \method{__setitem__}, +\method{setdefault}, \method{__delitem__}, \method{__contains__} and +\method{has_key}. For each of these methods, the key is the header name +(treated case-insensitively), and the value is the first value +associated with that header name. Setting a header deletes any existing +values for that header, then adds a new value at the end of the wrapped +header list. Headers' existing order is generally maintained, with new +headers added to the end of the wrapped list. + +Unlike a dictionary, \class{Headers} objects do not raise an error when +you try to get or delete a key that isn't in the wrapped header list. +Getting a nonexistent header just returns \code{None}, and deleting +a nonexistent header does nothing. + +\class{Headers} objects also support \method{keys()}, \method{values()}, +and \method{items()} methods. The lists returned by \method{keys()} +and \method{items()} can include the same key more than once if there +is a multi-valued header. The \code{len()} of a \class{Headers} object +is the same as the length of its \method{items()}, which is the same +as the length of the wrapped header list. In fact, the \method{items()} +method just returns a copy of the wrapped header list. + +Calling \code{str()} on a \class{Headers} object returns a formatted +string suitable for transmission as HTTP response headers. Each header +is placed on a line with its value, separated by a colon and a space. +Each line is terminated by a carriage return and line feed, and the +string is terminated with a blank line. + +In addition to their mapping interface and formatting features, +\class{Headers} objects also have the following methods for querying +and adding multi-valued headers, and for adding headers with MIME +parameters: + +\begin{methoddesc}{get_all}{name} +Return a list of all the values for the named header. + +The returned list will be sorted in the order they appeared in the +original header list or were added to this instance, and may contain +duplicates. Any fields deleted and re-inserted are always appended to +the header list. If no fields exist with the given name, returns an +empty list. +\end{methoddesc} + + +\begin{methoddesc}{add_header}{name, value, **_params} +Add a (possibly multi-valued) header, with optional MIME parameters +specified via keyword arguments. + +\var{name} is the header field to add. Keyword arguments can be used to +set MIME parameters for the header field. Each parameter must be a +string or \code{None}. Underscores in parameter names are converted to +dashes, since dashes are illegal in Python identifiers, but many MIME +parameter names include dashes. If the parameter value is a string, it +is added to the header value parameters in the form \code{name="value"}. +If it is \code{None}, only the parameter name is added. (This is used +for MIME parameters without a value.) Example usage: + +\begin{verbatim} +h.add_header('content-disposition', 'attachment', filename='bud.gif') +\end{verbatim} + +The above will add a header that looks like this: + +\begin{verbatim} +Content-Disposition: attachment; filename="bud.gif" +\end{verbatim} +\end{methoddesc} +\end{classdesc} + +\subsection{\module{wsgiref.simple_server} -- a simple WSGI HTTP server} +\declaremodule[wsgiref.simpleserver]{}{wsgiref.simple_server} + +This module implements a simple HTTP server (based on +\module{BaseHTTPServer}) that serves WSGI applications. Each server +instance serves a single WSGI application on a given host and port. If +you want to serve multiple applications on a single host and port, you +should create a WSGI application that parses \code{PATH_INFO} to select +which application to invoke for each request. (E.g., using the +\function{shift_path_info()} function from \module{wsgiref.util}.) + + +\begin{funcdesc}{make_server}{host, port, app +\optional{, server_class=\class{WSGIServer} \optional{, +handler_class=\class{WSGIRequestHandler}}}} +Create a new WSGI server listening on \var{host} and \var{port}, +accepting connections for \var{app}. The return value is an instance of +the supplied \var{server_class}, and will process requests using the +specified \var{handler_class}. \var{app} must be a WSGI application +object, as defined by \pep{333}. + +Example usage: +\begin{verbatim}from wsgiref.simple_server import make_server, demo_app + +httpd = make_server('', 8000, demo_app) +print "Serving HTTP on port 8000..." + +# Respond to requests until process is killed +httpd.serve_forever() + +# Alternative: serve one request, then exit +##httpd.handle_request() +\end{verbatim} + +\end{funcdesc} + + + + + + +\begin{funcdesc}{demo_app}{environ, start_response} +This function is a small but complete WSGI application that +returns a text page containing the message ``Hello world!'' +and a list of the key/value pairs provided in the +\var{environ} parameter. It's useful for verifying that a WSGI server +(such as \module{wsgiref.simple_server}) is able to run a simple WSGI +application correctly. +\end{funcdesc} + + +\begin{classdesc}{WSGIServer}{server_address, RequestHandlerClass} +Create a \class{WSGIServer} instance. \var{server_address} should be +a \code{(host,port)} tuple, and \var{RequestHandlerClass} should be +the subclass of \class{BaseHTTPServer.BaseHTTPRequestHandler} that will +be used to process requests. + +You do not normally need to call this constructor, as the +\function{make_server()} function can handle all the details for you. + +\class{WSGIServer} is a subclass +of \class{BaseHTTPServer.HTTPServer}, so all of its methods (such as +\method{serve_forever()} and \method{handle_request()}) are available. +\class{WSGIServer} also provides these WSGI-specific methods: + +\begin{methoddesc}{set_app}{application} +Sets the callable \var{application} as the WSGI application that will +receive requests. +\end{methoddesc} + +\begin{methoddesc}{get_app}{} +Returns the currently-set application callable. +\end{methoddesc} + +Normally, however, you do not need to use these additional methods, as +\method{set_app()} is normally called by \function{make_server()}, and +the \method{get_app()} exists mainly for the benefit of request handler +instances. +\end{classdesc} + + + +\begin{classdesc}{WSGIRequestHandler}{request, client_address, server} +Create an HTTP handler for the given \var{request} (i.e. a socket), +\var{client_address} (a \code{(\var{host},\var{port})} tuple), and +\var{server} (\class{WSGIServer} instance). + +You do not need to create instances of this class directly; they are +automatically created as needed by \class{WSGIServer} objects. You +can, however, subclass this class and supply it as a \var{handler_class} +to the \function{make_server()} function. Some possibly relevant +methods for overriding in subclasses: + +\begin{methoddesc}{get_environ}{} +Returns a dictionary containing the WSGI environment for a request. The +default implementation copies the contents of the \class{WSGIServer} +object's \member{base_environ} dictionary attribute and then adds +various headers derived from the HTTP request. Each call to this method +should return a new dictionary containing all of the relevant CGI +environment variables as specified in \pep{333}. +\end{methoddesc} + +\begin{methoddesc}{get_stderr}{} +Return the object that should be used as the \code{wsgi.errors} stream. +The default implementation just returns \code{sys.stderr}. +\end{methoddesc} + +\begin{methoddesc}{handle}{} +Process the HTTP request. The default implementation creates a handler +instance using a \module{wsgiref.handlers} class to implement the actual +WSGI application interface. +\end{methoddesc} + +\end{classdesc} + + + + + + + + + +\subsection{\module{wsgiref.validate} -- WSGI conformance checker} +\declaremodule{}{wsgiref.validate} +When creating new WSGI application objects, frameworks, servers, or +middleware, it can be useful to validate the new code's conformance +using \module{wsgiref.validate}. This module provides a function that +creates WSGI application objects that validate communications between +a WSGI server or gateway and a WSGI application object, to check both +sides for protocol conformance. + +Note that this utility does not guarantee complete \pep{333} compliance; +an absence of errors from this module does not necessarily mean that +errors do not exist. However, if this module does produce an error, +then it is virtually certain that either the server or application is +not 100\% compliant. + +This module is based on the \module{paste.lint} module from Ian +Bicking's ``Python Paste'' library. + +\begin{funcdesc}{validator}{application} +Wrap \var{application} and return a new WSGI application object. The +returned application will forward all requests to the original +\var{application}, and will check that both the \var{application} and +the server invoking it are conforming to the WSGI specification and to +RFC 2616. + +Any detected nonconformance results in an \exception{AssertionError} +being raised; note, however, that how these errors are handled is +server-dependent. For example, \module{wsgiref.simple_server} and other +servers based on \module{wsgiref.handlers} (that don't override the +error handling methods to do something else) will simply output a +message that an error has occurred, and dump the traceback to +\code{sys.stderr} or some other error stream. + +This wrapper may also generate output using the \module{warnings} module +to indicate behaviors that are questionable but which may not actually +be prohibited by \pep{333}. Unless they are suppressed using Python +command-line options or the \module{warnings} API, any such warnings +will be written to \code{sys.stderr} (\emph{not} \code{wsgi.errors}, +unless they happen to be the same object). +\end{funcdesc} + +\subsection{\module{wsgiref.handlers} -- server/gateway base classes} +\declaremodule{}{wsgiref.handlers} + +This module provides base handler classes for implementing WSGI servers +and gateways. These base classes handle most of the work of +communicating with a WSGI application, as long as they are given a +CGI-like environment, along with input, output, and error streams. + + +\begin{classdesc}{CGIHandler}{} +CGI-based invocation via \code{sys.stdin}, \code{sys.stdout}, +\code{sys.stderr} and \code{os.environ}. This is useful when you have +a WSGI application and want to run it as a CGI script. Simply invoke +\code{CGIHandler().run(app)}, where \code{app} is the WSGI application +object you wish to invoke. + +This class is a subclass of \class{BaseCGIHandler} that sets +\code{wsgi.run_once} to true, \code{wsgi.multithread} to false, and +\code{wsgi.multiprocess} to true, and always uses \module{sys} and +\module{os} to obtain the necessary CGI streams and environment. +\end{classdesc} + + +\begin{classdesc}{BaseCGIHandler}{stdin, stdout, stderr, environ +\optional{, multithread=True \optional{, multiprocess=False}}} + +Similar to \class{CGIHandler}, but instead of using the \module{sys} and +\module{os} modules, the CGI environment and I/O streams are specified +explicitly. The \var{multithread} and \var{multiprocess} values are +used to set the \code{wsgi.multithread} and \code{wsgi.multiprocess} +flags for any applications run by the handler instance. + +This class is a subclass of \class{SimpleHandler} intended for use with +software other than HTTP ``origin servers''. If you are writing a +gateway protocol implementation (such as CGI, FastCGI, SCGI, etc.) that +uses a \code{Status:} header to send an HTTP status, you probably want +to subclass this instead of \class{SimpleHandler}. +\end{classdesc} + + + +\begin{classdesc}{SimpleHandler}{stdin, stdout, stderr, environ +\optional{,multithread=True \optional{, multiprocess=False}}} + +Similar to \class{BaseCGIHandler}, but designed for use with HTTP origin +servers. If you are writing an HTTP server implementation, you will +probably want to subclass this instead of \class{BaseCGIHandler} + +This class is a subclass of \class{BaseHandler}. It overrides the +\method{__init__()}, \method{get_stdin()}, \method{get_stderr()}, +\method{add_cgi_vars()}, \method{_write()}, and \method{_flush()} +methods to support explicitly setting the environment and streams via +the constructor. The supplied environment and streams are stored in +the \member{stdin}, \member{stdout}, \member{stderr}, and +\member{environ} attributes. +\end{classdesc} + +\begin{classdesc}{BaseHandler}{} +This is an abstract base class for running WSGI applications. Each +instance will handle a single HTTP request, although in principle you +could create a subclass that was reusable for multiple requests. + +\class{BaseHandler} instances have only one method intended for external +use: + +\begin{methoddesc}{run}{app} +Run the specified WSGI application, \var{app}. +\end{methoddesc} + +All of the other \class{BaseHandler} methods are invoked by this method +in the process of running the application, and thus exist primarily to +allow customizing the process. + +The following methods MUST be overridden in a subclass: + +\begin{methoddesc}{_write}{data} +Buffer the string \var{data} for transmission to the client. It's okay +if this method actually transmits the data; \class{BaseHandler} +just separates write and flush operations for greater efficiency +when the underlying system actually has such a distinction. +\end{methoddesc} + +\begin{methoddesc}{_flush}{} +Force buffered data to be transmitted to the client. It's okay if this +method is a no-op (i.e., if \method{_write()} actually sends the data). +\end{methoddesc} + +\begin{methoddesc}{get_stdin}{} +Return an input stream object suitable for use as the \code{wsgi.input} +of the request currently being processed. +\end{methoddesc} + +\begin{methoddesc}{get_stderr}{} +Return an output stream object suitable for use as the +\code{wsgi.errors} of the request currently being processed. +\end{methoddesc} + +\begin{methoddesc}{add_cgi_vars}{} +Insert CGI variables for the current request into the \member{environ} +attribute. +\end{methoddesc} + +Here are some other methods and attributes you may wish to override. +This list is only a summary, however, and does not include every method +that can be overridden. You should consult the docstrings and source +code for additional information before attempting to create a customized +\class{BaseHandler} subclass. + + + + + + + + + + + + + + + + +Attributes and methods for customizing the WSGI environment: + +\begin{memberdesc}{wsgi_multithread} +The value to be used for the \code{wsgi.multithread} environment +variable. It defaults to true in \class{BaseHandler}, but may have +a different default (or be set by the constructor) in the other +subclasses. +\end{memberdesc} + +\begin{memberdesc}{wsgi_multiprocess} +The value to be used for the \code{wsgi.multiprocess} environment +variable. It defaults to true in \class{BaseHandler}, but may have +a different default (or be set by the constructor) in the other +subclasses. +\end{memberdesc} + +\begin{memberdesc}{wsgi_run_once} +The value to be used for the \code{wsgi.run_once} environment +variable. It defaults to false in \class{BaseHandler}, but +\class{CGIHandler} sets it to true by default. +\end{memberdesc} + +\begin{memberdesc}{os_environ} +The default environment variables to be included in every request's +WSGI environment. By default, this is a copy of \code{os.environ} at +the time that \module{wsgiref.handlers} was imported, but subclasses can +either create their own at the class or instance level. Note that the +dictionary should be considered read-only, since the default value is +shared between multiple classes and instances. +\end{memberdesc} + +\begin{memberdesc}{server_software} +If the \member{origin_server} attribute is set, this attribute's value +is used to set the default \code{SERVER_SOFTWARE} WSGI environment +variable, and also to set a default \code{Server:} header in HTTP +responses. It is ignored for handlers (such as \class{BaseCGIHandler} +and \class{CGIHandler}) that are not HTTP origin servers. +\end{memberdesc} + + + +\begin{methoddesc}{get_scheme}{} +Return the URL scheme being used for the current request. The default +implementation uses the \function{guess_scheme()} function from +\module{wsgiref.util} to guess whether the scheme should be ``http'' or +``https'', based on the current request's \member{environ} variables. +\end{methoddesc} + +\begin{methoddesc}{setup_environ}{} +Set the \member{environ} attribute to a fully-populated WSGI +environment. The default implementation uses all of the above methods +and attributes, plus the \method{get_stdin()}, \method{get_stderr()}, +and \method{add_cgi_vars()} methods and the \member{wsgi_file_wrapper} +attribute. It also inserts a \code{SERVER_SOFTWARE} key if not present, +as long as the \member{origin_server} attribute is a true value and the +\member{server_software} attribute is set. +\end{methoddesc} + + + + + + + + + + + + + + + + + + + + + + + + + +Methods and attributes for customizing exception handling: + +\begin{methoddesc}{log_exception}{exc_info} +Log the \var{exc_info} tuple in the server log. \var{exc_info} is a +\code{(\var{type}, \var{value}, \var{traceback})} tuple. The default +implementation simply writes the traceback to the request's +\code{wsgi.errors} stream and flushes it. Subclasses can override this +method to change the format or retarget the output, mail the traceback +to an administrator, or whatever other action may be deemed suitable. +\end{methoddesc} + +\begin{memberdesc}{traceback_limit} +The maximum number of frames to include in tracebacks output by the +default \method{log_exception()} method. If \code{None}, all frames +are included. +\end{memberdesc} + +\begin{methoddesc}{error_output}{environ, start_response} +This method is a WSGI application to generate an error page for the +user. It is only invoked if an error occurs before headers are sent +to the client. + +This method can access the current error information using +\code{sys.exc_info()}, and should pass that information to +\var{start_response} when calling it (as described in the ``Error +Handling'' section of \pep{333}). + +The default implementation just uses the \member{error_status}, +\member{error_headers}, and \member{error_body} attributes to generate +an output page. Subclasses can override this to produce more dynamic +error output. + +Note, however, that it's not recommended from a security perspective to +spit out diagnostics to any old user; ideally, you should have to do +something special to enable diagnostic output, which is why the default +implementation doesn't include any. +\end{methoddesc} + + + + +\begin{memberdesc}{error_status} +The HTTP status used for error responses. This should be a status +string as defined in \pep{333}; it defaults to a 500 code and message. +\end{memberdesc} + +\begin{memberdesc}{error_headers} +The HTTP headers used for error responses. This should be a list of +WSGI response headers (\code{(\var{name}, \var{value})} tuples), as +described in \pep{333}. The default list just sets the content type +to \code{text/plain}. +\end{memberdesc} + +\begin{memberdesc}{error_body} +The error response body. This should be an HTTP response body string. +It defaults to the plain text, ``A server error occurred. Please +contact the administrator.'' +\end{memberdesc} + + + + + + + + + + + + + + + + + + + + + + + + +Methods and attributes for \pep{333}'s ``Optional Platform-Specific File +Handling'' feature: + +\begin{memberdesc}{wsgi_file_wrapper} +A \code{wsgi.file_wrapper} factory, or \code{None}. The default value +of this attribute is the \class{FileWrapper} class from +\module{wsgiref.util}. +\end{memberdesc} + +\begin{methoddesc}{sendfile}{} +Override to implement platform-specific file transmission. This method +is called only if the application's return value is an instance of +the class specified by the \member{wsgi_file_wrapper} attribute. It +should return a true value if it was able to successfully transmit the +file, so that the default transmission code will not be executed. +The default implementation of this method just returns a false value. +\end{methoddesc} + + +Miscellaneous methods and attributes: + +\begin{memberdesc}{origin_server} +This attribute should be set to a true value if the handler's +\method{_write()} and \method{_flush()} are being used to communicate +directly to the client, rather than via a CGI-like gateway protocol that +wants the HTTP status in a special \code{Status:} header. + +This attribute's default value is true in \class{BaseHandler}, but +false in \class{BaseCGIHandler} and \class{CGIHandler}. +\end{memberdesc} + +\begin{memberdesc}{http_version} +If \member{origin_server} is true, this string attribute is used to +set the HTTP version of the response set to the client. It defaults to +\code{"1.0"}. +\end{memberdesc} + + + + + +\end{classdesc} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Doc/lib/libzipfile.tex b/Doc/lib/libzipfile.tex index 4e06ef6..3d81e50 100644 --- a/Doc/lib/libzipfile.tex +++ b/Doc/lib/libzipfile.tex @@ -13,11 +13,12 @@ The ZIP file format is a common archive and compression standard. This module provides tools to create, read, write, append, and list a ZIP file. Any advanced use of this module will require an understanding of the format, as defined in -\citetitle[http://www.pkware.com/appnote.html]{PKZIP Application -Note}. +\citetitle[http://www.pkware.com/business_and_developers/developer/appnote/] +{PKZIP Application Note}. This module does not currently handle ZIP files which have appended -comments, or multi-disk ZIP files. +comments, or multi-disk ZIP files. It can handle ZIP files that use the +ZIP64 extensions (that is ZIP files that are more than 4 GByte in size). The available attributes of this module are: @@ -25,6 +26,11 @@ The available attributes of this module are: The error raised for bad ZIP files. \end{excdesc} +\begin{excdesc}{LargeZipFile} + The error raised when a ZIP file would require ZIP64 functionality but that + has not been enabled. +\end{excdesc} + \begin{classdesc*}{ZipFile} The class for reading and writing ZIP files. See ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for @@ -65,9 +71,9 @@ The available attributes of this module are: \begin{seealso} - \seetitle[http://www.pkware.com/appnote.html]{PKZIP Application - Note}{Documentation on the ZIP file format by Phil - Katz, the creator of the format and algorithms used.} + \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/] + {PKZIP Application Note}{Documentation on the ZIP file format by + Phil Katz, the creator of the format and algorithms used.} \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{ Information about the Info-ZIP project's ZIP archive @@ -77,7 +83,7 @@ The available attributes of this module are: \subsection{ZipFile Objects \label{zipfile-objects}} -\begin{classdesc}{ZipFile}{file\optional{, mode\optional{, compression}}} +\begin{classdesc}{ZipFile}{file\optional{, mode\optional{, compression\optional{, allowZip64}}}} Open a ZIP file, where \var{file} can be either a path to a file (a string) or a file-like object. The \var{mode} parameter should be \code{'r'} to read an existing file, \code{'w'} to @@ -100,6 +106,12 @@ cat myzip.zip >> python.exe is specified but the \refmodule{zlib} module is not available, \exception{RuntimeError} is also raised. The default is \constant{ZIP_STORED}. + If \var{allowZip64} is \code{True} zipfile will create ZIP files that use + the ZIP64 extensions when the zipfile is larger than 2 GB. If it is + false (the default) \module{zipfile} will raise an exception when the + ZIP file would require ZIP64 extensions. ZIP64 extensions are disabled by + default because the default \program{zip} and \program{unzip} commands on + \UNIX{} (the InfoZIP utilities) don't support these extensions. \end{classdesc} \begin{methoddesc}{close}{} @@ -132,8 +144,8 @@ cat myzip.zip >> python.exe \end{methoddesc} \begin{methoddesc}{testzip}{} - Read all the files in the archive and check their CRC's. Return the - name of the first bad file, or else return \code{None}. + Read all the files in the archive and check their CRC's and file + headers. Return the name of the first bad file, or else return \code{None}. \end{methoddesc} \begin{methoddesc}{write}{filename\optional{, arcname\optional{, @@ -243,9 +255,9 @@ Instances have the following attributes: \begin{memberdesc}[ZipInfo]{extra} Expansion field data. The - \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application - Note} contains some comments on the internal structure of the data - contained in this string. + \citetitle[http://www.pkware.com/business_and_developers/developer/appnote/] + {PKZIP Application Note} contains some comments on the internal + structure of the data contained in this string. \end{memberdesc} \begin{memberdesc}[ZipInfo]{create_system} @@ -284,10 +296,6 @@ Instances have the following attributes: Byte offset to the file header. \end{memberdesc} -\begin{memberdesc}[ZipInfo]{file_offset} - Byte offset to the start of the file data. -\end{memberdesc} - \begin{memberdesc}[ZipInfo]{CRC} CRC-32 of the uncompressed file. \end{memberdesc} diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex index 770ea21..098e788 100644 --- a/Doc/lib/libzipimport.tex +++ b/Doc/lib/libzipimport.tex @@ -50,9 +50,9 @@ The available attributes of this module are: \begin{seealso} - \seetitle[http://www.pkware.com/appnote.html]{PKZIP Application - Note}{Documentation on the ZIP file format by Phil - Katz, the creator of the format and algorithms used.} + \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/] + {PKZIP Application Note}{Documentation on the ZIP file format by + Phil Katz, the creator of the format and algorithms used.} \seepep{0273}{Import Modules from Zip Archives}{Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 diff --git a/Doc/lib/sqlite3/complete_statement.py b/Doc/lib/sqlite3/complete_statement.py index 89fc250..22525e3 100644 --- a/Doc/lib/sqlite3/complete_statement.py +++ b/Doc/lib/sqlite3/complete_statement.py @@ -24,7 +24,7 @@ while True: if buffer.lstrip().upper().startswith("SELECT"): print cur.fetchall() except sqlite3.Error, e: - print "An error occured:", e.args[0] + print "An error occurred:", e.args[0] buffer = "" con.close() diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex index 405f041..db52cbd 100644 --- a/Doc/lib/tkinter.tex +++ b/Doc/lib/tkinter.tex @@ -18,10 +18,9 @@ implement the Tk widgets as Python classes. In addition, the internal module \module{\_tkinter} provides a threadsafe mechanism which allows Python and Tcl to interact. -Tk is not the only GUI for Python, but is however the most commonly -used one; see section~\ref{other-gui-modules}, ``Other User Interface -Modules and Packages,'' for more information on other GUI toolkits for -Python. +Tk is not the only GUI for Python; see +section~\ref{other-gui-packages}, ``Other User Interface Modules and +Packages,'' for more information on other GUI toolkits for Python. % Other sections I have in mind are % Tkinter internals @@ -103,14 +102,14 @@ of an application. Each instance has its own associated Tcl interpreter. \end{classdesc} \begin{funcdesc}{Tcl}{screenName=None, baseName=None, className='Tk', useTk=0} -The \function{Tcl} function is a factory function which creates an object -much like that created by the \class{Tk} class, except that it does not -initialize the Tk subsystem. This is most often useful when driving the Tcl -interpreter in an environment where one doesn't want to create extraneous -toplevel windows, or where one cannot (i.e. Unix/Linux systems without an X -server). An object created by the \function{Tcl} object can have a Toplevel -window created (and the Tk subsystem initialized) by calling its -\method{loadtk} method. +The \function{Tcl} function is a factory function which creates an +object much like that created by the \class{Tk} class, except that it +does not initialize the Tk subsystem. This is most often useful when +driving the Tcl interpreter in an environment where one doesn't want +to create extraneous toplevel windows, or where one cannot (such as +\UNIX/Linux systems without an X server). An object created by the +\function{Tcl} object can have a Toplevel window created (and the Tk +subsystem initialized) by calling its \method{loadtk} method. \versionadded{2.4} \end{funcdesc} @@ -316,10 +315,10 @@ is called \code{.} (period) and children are delimited by more periods. For example, \code{.myApp.controlPanel.okButton} might be the name of a widget. -\item[\var{options} ] +\item[\var{options}] configure the widget's appearance and in some cases, its behavior. The options come in the form of a list of flags and values. -Flags are proceeded by a `-', like unix shell command flags, and +Flags are proceeded by a `-', like \UNIX{} shell command flags, and values are put in quotes if they are more than one word. \end{description} @@ -1806,24 +1805,29 @@ directly on Python data structures, without having to transfer data through the Tk/Tcl layer.} \end{seealso*} - -Tk is not the only GUI for Python, but is however the -most commonly used one. +Other GUI packages are also available for Python: \begin{seealso*} -\seetitle[http://www.wxwindows.org]{wxWindows}{ -is a GUI toolkit that combines the most attractive attributes of Qt, -Tk, Motif, and GTK+ in one powerful and efficient package. It is -implemented in \Cpp. wxWindows supports two flavors of \UNIX{} -implementation: GTK+ and Motif, and under Windows, it has a standard -Microsoft Foundation Classes (MFC) appearance, because it uses Win32 -widgets. There is a Python class wrapper, independent of Tkinter. - -wxWindows is much richer in widgets than \refmodule{Tkinter}, with its -help system, sophisticated HTML and image viewers, and other -specialized widgets, extensive documentation, and printing capabilities. +\seetitle[http://www.wxpython.org]{wxPython}{ +wxPython is a cross-platform GUI toolkit for Python that is built +around the popular \ulink{wxWidgets}{http://www.wxwidgets.org/} \Cpp{} +toolkit. It provides a native look and feel for applications on +Windows, Mac OS X, and \UNIX{} systems by using each platform's native +widgets where ever possible, (GTK+ on \UNIX-like systems). In +addition to an extensive set of widgets, wxPython provides classes for +online documentation and context sensitive help, printing, HTML +viewing, low-level device context drawing, drag and drop, system +clipboard access, an XML-based resource format and more, including an +ever growing library of user-contributed modules. Both the wxWidgets +and wxPython projects are under active development and continuous +improvement, and have active and helpful user and developer +communities. +} +\seetitle[http://www.amazon.com/exec/obidos/ASIN/1932394621] +{wxPython in Action}{ +The wxPython book, by Noel Rappin and Robin Dunn. } -\seetitle[]{PyQt}{ +\seetitle{PyQt}{ PyQt is a \program{sip}-wrapped binding to the Qt toolkit. Qt is an extensive \Cpp{} GUI toolkit that is available for \UNIX, Windows and Mac OS X. \program{sip} is a tool for generating bindings for \Cpp{} diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex index 944ea1b..12a7cc3 100644 --- a/Doc/mac/libmacfs.tex +++ b/Doc/mac/libmacfs.tex @@ -22,10 +22,10 @@ Whenever a function or method expects a \var{file} argument, this argument can be one of three things:\ (1) a full or partial Macintosh pathname, (2) an \class{FSSpec} object or (3) a 3-tuple \code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in -\citetitle{Inside Macintosh:\ Files}. An \class{FSSpec} can point to +\citetitle{Inside Macintosh:\ Files}. An \class{FSSpec} can point to a non-existing file, as long as the folder containing the file exists. -Under MacPython the same is true for a pathname, but not under unix-Pyton -because of the way pathnames and FSRefs works. See Apple's documentation +Under MacPython the same is true for a pathname, but not under \UNIX-Python +because of the way pathnames and FSRefs works. See Apple's documentation for details. A description of aliases and the diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex index b22b39c..e50b99b 100644 --- a/Doc/mac/libmacos.tex +++ b/Doc/mac/libmacos.tex @@ -25,7 +25,7 @@ The way the interpreter has been linked. As extension modules may be incompatible between linking models, packages could use this information to give more decent error messages. The value is one of \code{'static'} for a statically linked Python, \code{'framework'} for Python in a Mac OS X framework, -\code{'shared'} for Python in a standard unix shared library. +\code{'shared'} for Python in a standard \UNIX{} shared library. Older Pythons could also have the value \code{'cfm'} for Mac OS 9-compatible Python. \end{datadesc} diff --git a/Doc/mac/using.tex b/Doc/mac/using.tex index bfa478e..b21a98e 100644 --- a/Doc/mac/using.tex +++ b/Doc/mac/using.tex @@ -6,7 +6,7 @@ Python on any other \UNIX platform, but there are a number of additional features such as the IDE and the Package Manager that are worth pointing out. Python on Mac OS 9 or earlier can be quite different from Python on -Unix or Windows, but is beyond the scope of this manual, as that platform +\UNIX{} or Windows, but is beyond the scope of this manual, as that platform is no longer supported, starting with Python 2.4. See \url{http://www.cwi.nl/\textasciitilde jack/macpython} for installers for the latest 2.3 release for Mac OS 9 and related documentation. diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex index 2ed8a5d..bad4609 100644 --- a/Doc/ref/ref2.tex +++ b/Doc/ref/ref2.tex @@ -56,7 +56,7 @@ by following the explicit or implicit \emph{line joining} rules. A physical line is a sequence of characters terminated by an end-of-line sequence. In source files, any of the standard platform line -termination sequences can be used - the \UNIX form using \ASCII{} LF +termination sequences can be used - the \UNIX{} form using \ASCII{} LF (linefeed), the Windows form using the \ASCII{} sequence CR LF (return followed by linefeed), or the Macintosh form using the \ASCII{} CR (return) character. All of these forms can be used equally, regardless diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index d0c8ccf..15fc188 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -1307,6 +1307,11 @@ defines mutable objects and implements a \method{__cmp__()} or since the dictionary implementation requires that a key's hash value is immutable (if the object's hash value changes, it will be in the wrong hash bucket). + +\versionchanged[\method{__hash__()} may now also return a long +integer object; the 32-bit integer is then derived from the hash +of that object]{2.5} + \withsubitem{(object method)}{\ttindex{__cmp__()}} \end{methoddesc} @@ -1886,6 +1891,9 @@ method should be the equivalent to using \method{__floordiv__()} and \method{__pow__()} should be defined to accept an optional third argument if the ternary version of the built-in \function{pow()}\bifuncindex{pow} function is to be supported. + +If one of those methods does not support the operation with the +supplied arguments, it should return \code{NotImplemented}. \end{methoddesc} \begin{methoddesc}[numeric object]{__div__}{self, other} @@ -1918,13 +1926,28 @@ called to implement the binary arithmetic operations (\code{+}, \function{pow()}\bifuncindex{pow}, \code{**}, \code{<<}, \code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected (swapped) operands. These functions are only called if the left -operand does not support the corresponding operation. For instance, -to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an -instance of a class that has an \method{__rsub__()} method, -\code{\var{y}.__rsub__(\var{x})} is called. Note that ternary +operand does not support the corresponding operation and the +operands are of different types.\footnote{ + For operands of the same type, it is assumed that if the + non-reflected method (such as \method{__add__()}) fails the + operation is not supported, which is why the reflected method + is not called.} +For instance, to evaluate the expression \var{x}\code{-}\var{y}, +where \var{y} is an instance of a class that has an +\method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})} +is called if \code{\var{x}.__sub__(\var{y})} returns +\var{NotImplemented}. + +Note that ternary \function{pow()}\bifuncindex{pow} will not try calling \method{__rpow__()} (the coercion rules would become too complicated). + +\note{If the right operand's type is a subclass of the left operand's + type and that subclass provides the reflected method for the + operation, this method will be called before the left operand's + non-reflected method. This behavior allows subclasses to + override their ancestors' operations.} \end{methoddesc} \begin{methoddesc}[numeric object]{__iadd__}{self, other} diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex index dcdc823..12a2b92 100644 --- a/Doc/ref/ref4.tex +++ b/Doc/ref/ref4.tex @@ -97,10 +97,20 @@ searched. The global statement must precede all uses of the name. The built-in namespace associated with the execution of a code block is actually found by looking up the name \code{__builtins__} in its global namespace; this should be a dictionary or a module (in the -latter case the module's dictionary is used). Normally, the -\code{__builtins__} namespace is the dictionary of the built-in module -\module{__builtin__} (note: no `s'). If it isn't, restricted -execution\indexii{restricted}{execution} mode is in effect. +latter case the module's dictionary is used). By default, when in the +\module{__main__} module, \code{__builtins__} is the built-in module +\module{__builtin__} (note: no `s'); when in any other module, +\code{__builtins__} is an alias for the dictionary of the +\module{__builtin__} module itself. \code{__builtins__} can be set +to a user-created dictionary to create a weak form of restricted +execution\indexii{restricted}{execution}. + +\begin{notice} + Users should not touch \code{__builtins__}; it is strictly an + implementation detail. Users wanting to override values in the + built-in namespace should \keyword{import} the \module{__builtin__} + (no `s') module and modify its attributes appropriately. +\end{notice} The namespace for a module is automatically created the first time a module is imported. The main module for a script is always called diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex index 89f9977..909e5bb 100644 --- a/Doc/ref/ref5.tex +++ b/Doc/ref/ref5.tex @@ -907,7 +907,10 @@ The operators \code{<}, \code{>}, \code{==}, \code{>=}, \code{<=}, and the values of two objects. The objects need not have the same type. If both are numbers, they are converted to a common type. Otherwise, objects of different types \emph{always} compare unequal, and are -ordered consistently but arbitrarily. +ordered consistently but arbitrarily. You can control comparison +behavior of objects of non-builtin types by defining a \code{__cmp__} +method or rich comparison methods like \code{__gt__}, described in +section~\ref{specialnames}. (This unusual definition of comparison was used to simplify the definition of operations like sorting and the \keyword{in} and @@ -952,7 +955,8 @@ otherwise defined.\footnote{Earlier versions of Python used a dictionary for emptiness by comparing it to \code{\{\}}.} \item -Most other types compare unequal unless they are the same object; +Most other objects of builtin types compare unequal unless they are +the same object; the choice whether one object is considered smaller or larger than another one is made arbitrarily but consistently within one execution of a program. diff --git a/Doc/ref/ref8.tex b/Doc/ref/ref8.tex index 801ab58..45be71d 100644 --- a/Doc/ref/ref8.tex +++ b/Doc/ref/ref8.tex @@ -34,7 +34,7 @@ in the namespace of \module{__main__}. \index{interactive mode} \refbimodindex{__main__} -Under {\UNIX}, a complete program can be passed to the interpreter in +Under \UNIX, a complete program can be passed to the interpreter in three forms: with the \programopt{-c} \var{string} command line option, as a file passed as the first command line argument, or as standard input. If the file or standard input is a tty device, the interpreter enters diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index 4e0a26b..1b08a8e 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -2931,14 +2931,13 @@ submodules with the same name from different packages. The submodules often need to refer to each other. For example, the \module{surround} module might use the \module{echo} module. In fact, -such references -are so common that the \keyword{import} statement first looks in the -containing package before looking in the standard module search path. -Thus, the surround module can simply use \code{import echo} or -\code{from echo import echofilter}. If the imported module is not -found in the current package (the package of which the current module -is a submodule), the \keyword{import} statement looks for a top-level -module with the given name. +such references are so common that the \keyword{import} statement +first looks in the containing package before looking in the standard +module search path. Thus, the \module{surround} module can simply use +\code{import echo} or \code{from echo import echofilter}. If the +imported module is not found in the current package (the package of +which the current module is a submodule), the \keyword{import} +statement looks for a top-level module with the given name. When packages are structured into subpackages (as with the \module{Sound} package in the example), there's no shortcut to refer @@ -2948,6 +2947,24 @@ must be used. For example, if the module in the \module{Sound.Effects} package, it can use \code{from Sound.Effects import echo}. +Starting with Python 2.5, in addition to the implicit relative imports +described above, you can write explicit relative imports with the +\code{from module import name} form of import statement. These explicit +relative imports use leading dots to indicate the current and parent +packages involved in the relative import. From the \module{surround} +module for example, you might use: + +\begin{verbatim} +from . import echo +from .. import Formats +from ..Filters import equalizer +\end{verbatim} + +Note that both explicit and implicit relative imports are based on the +name of the current module. Since the name of the main module is always +\code{"__main__"}, modules intended for use as the main module of a +Python application should always use absolute imports. + \subsection{Packages in Multiple Directories} Packages support one more special attribute, \member{__path__}. This diff --git a/Doc/whatsnew/whatsnew20.tex b/Doc/whatsnew/whatsnew20.tex index 56d15b8..360d7dc 100644 --- a/Doc/whatsnew/whatsnew20.tex +++ b/Doc/whatsnew/whatsnew20.tex @@ -216,7 +216,7 @@ A new module, \module{unicodedata}, provides an interface to Unicode character properties. For example, \code{unicodedata.category(u'A')} returns the 2-character string 'Lu', the 'L' denoting it's a letter, and 'u' meaning that it's uppercase. -\code{u.bidirectional(u'\e x0660')} returns 'AN', meaning that U+0660 is +\code{unicodedata.bidirectional(u'\e u0660')} returns 'AN', meaning that U+0660 is an Arabic number. The \module{codecs} module contains functions to look up existing encodings @@ -571,7 +571,7 @@ def f(*args, **kw): The \keyword{print} statement can now have its output directed to a file-like object by following the \keyword{print} with -\verb|>> file|, similar to the redirection operator in Unix shells. +\verb|>> file|, similar to the redirection operator in \UNIX{} shells. Previously you'd either have to use the \method{write()} method of the file-like object, which lacks the convenience and simplicity of \keyword{print}, or you could assign a new value to @@ -777,7 +777,7 @@ fact will break in 2.0. Some work has been done to make integers and long integers a bit more interchangeable. In 1.5.2, large-file support was added for Solaris, -to allow reading files larger than 2Gb; this made the \method{tell()} +to allow reading files larger than 2~GiB; this made the \method{tell()} method of file objects return a long integer instead of a regular integer. Some code would subtract two file offsets and attempt to use the result to multiply a sequence or slice a string, but this raised a @@ -894,7 +894,7 @@ to be added, and a third argument for the value to be assigned to the name. This third argument is, respectively, a Python object, a C long, or a C string. -A wrapper API was added for Unix-style signal handlers. +A wrapper API was added for \UNIX-style signal handlers. \function{PyOS_getsig()} gets a signal handler and \function{PyOS_setsig()} will set a new handler. @@ -905,7 +905,7 @@ Before Python 2.0, installing modules was a tedious affair -- there was no way to figure out automatically where Python is installed, or what compiler options to use for extension modules. Software authors had to go through an arduous ritual of editing Makefiles and -configuration files, which only really work on Unix and leave Windows +configuration files, which only really work on \UNIX{} and leave Windows and MacOS unsupported. Python users faced wildly differing installation instructions which varied between different extension packages, which made administering a Python installation something of @@ -1222,7 +1222,7 @@ device on Linux, a twin to the existing \module{sunaudiodev} module. (Contributed by Peter Bosch, with fixes by Jeremy Hylton.) \item{\module{mmap}:} An interface to memory-mapped files on both -Windows and Unix. A file's contents can be mapped directly into +Windows and \UNIX. A file's contents can be mapped directly into memory, at which point it behaves like a mutable string, so its contents can be read and modified. They can even be passed to functions that expect ordinary strings, such as the \module{re} @@ -1262,7 +1262,7 @@ distribution, and enhanced to support Unicode. \item{\module{zipfile}:} A module for reading and writing ZIP-format archives. These are archives produced by \program{PKZIP} on -DOS/Windows or \program{zip} on Unix, not to be confused with +DOS/Windows or \program{zip} on \UNIX, not to be confused with \program{gzip}-format files (which are supported by the \module{gzip} module) (Contributed by James C. Ahlstrom.) diff --git a/Doc/whatsnew/whatsnew21.tex b/Doc/whatsnew/whatsnew21.tex index f3d0245..67cbbe4 100644 --- a/Doc/whatsnew/whatsnew21.tex +++ b/Doc/whatsnew/whatsnew21.tex @@ -325,7 +325,7 @@ Rossum.} When compiling Python, the user had to go in and edit the \file{Modules/Setup} file in order to enable various additional modules; the default set is relatively small and limited to modules -that compile on most Unix platforms. This means that on Unix +that compile on most \UNIX{} platforms. This means that on \Unix{} platforms with many more features, most notably Linux, Python installations often don't contain all useful modules they could. @@ -661,7 +661,7 @@ PyUnit. \item The \module{difflib} module contains a class, \class{SequenceMatcher}, which compares two sequences and computes the changes required to transform one sequence into the other. For -example, this module can be used to write a tool similar to the Unix +example, this module can be used to write a tool similar to the \UNIX{} \program{diff} program, and in fact the sample program \file{Tools/scripts/ndiff.py} demonstrates how to write such a script. diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex index a122083..72fd306 100644 --- a/Doc/whatsnew/whatsnew23.tex +++ b/Doc/whatsnew/whatsnew23.tex @@ -1479,7 +1479,7 @@ now return enhanced tuples: ('amk', 500) \end{verbatim} -\item The \module{gzip} module can now handle files exceeding 2~Gb. +\item The \module{gzip} module can now handle files exceeding 2~GiB. \item The new \module{heapq} module contains an implementation of a heap queue algorithm. A heap is an array-like data structure that @@ -1979,7 +1979,7 @@ documentation}{../lib/module-datetime.html}. The \module{getopt} module provides simple parsing of command-line arguments. The new \module{optparse} module (originally named Optik) -provides more elaborate command-line parsing that follows the Unix +provides more elaborate command-line parsing that follows the \UNIX{} conventions, automatically creates the output for \longprogramopt{help}, and can perform different actions for different options. diff --git a/Doc/whatsnew/whatsnew24.tex b/Doc/whatsnew/whatsnew24.tex index 51baece..096b1ec 100644 --- a/Doc/whatsnew/whatsnew24.tex +++ b/Doc/whatsnew/whatsnew24.tex @@ -162,7 +162,7 @@ for link in links: Generator expressions always have to be written inside parentheses, as in the above example. The parentheses signalling a function call also -count, so if you want to create a iterator that will be immediately +count, so if you want to create an iterator that will be immediately passed to a function you could write: \begin{verbatim} diff --git a/Doc/whatsnew/whatsnew25.tex b/Doc/whatsnew/whatsnew25.tex index 4015d98..dcb6ab1 100644 --- a/Doc/whatsnew/whatsnew25.tex +++ b/Doc/whatsnew/whatsnew25.tex @@ -3,10 +3,9 @@ % $Id$ % Fix XXX comments -% Count up the patches and bugs \title{What's New in Python 2.5} -\release{0.2} +\release{0.9} \author{A.M. Kuchling} \authoraddress{\email{amk@amk.ca}} @@ -14,31 +13,57 @@ \maketitle \tableofcontents -This article explains the new features in Python 2.5. No release date -for Python 2.5 has been set; it will probably be released in the -autumn of 2006. \pep{356} describes the planned release schedule. - -Comments, suggestions, and error reports are welcome; please e-mail them -to the author or open a bug in the Python bug tracker. - -% XXX Compare with previous release in 2 - 3 sentences here. - -This article doesn't attempt to provide a complete specification of -the new features, but instead provides a convenient overview. For -full details, you should refer to the documentation for Python 2.5. +This article explains the new features in Python 2.5. The final +release of Python 2.5 is scheduled for August 2006; +\pep{356} describes the planned release schedule. + +The changes in Python 2.5 are an interesting mix of language and +library improvements. The library enhancements will be more important +to Python's user community, I think, because several widely-useful +packages were added. New modules include ElementTree for XML +processing (section~\ref{module-etree}), the SQLite database module +(section~\ref{module-sqlite}), and the \module{ctypes} module for +calling C functions (section~\ref{module-ctypes}). + +The language changes are of middling significance. Some pleasant new +features were added, but most of them aren't features that you'll use +every day. Conditional expressions were finally added to the language +using a novel syntax; see section~\ref{pep-308}. The new +'\keyword{with}' statement will make writing cleanup code easier +(section~\ref{pep-343}). Values can now be passed into generators +(section~\ref{pep-342}). Imports are now visible as either absolute +or relative (section~\ref{pep-328}). Some corner cases of exception +handling are handled better (section~\ref{pep-341}). All these +improvements are worthwhile, but they're improvements to one specific +language feature or another; none of them are broad modifications to +Python's semantics. + +As well as the language and library additions, other improvements and +bugfixes were made throughout the source tree. A search through the +SVN change logs finds there were 334 patches applied and 443 bugs +fixed between Python 2.4 and 2.5. (Both figures are likely to be +underestimates.) + +This article doesn't try to be a complete specification of the new +features; instead changes are briefly introduced using helpful +examples. For full details, you should always refer to the +documentation for Python 2.5. % XXX add hyperlink when the documentation becomes available online. If you want to understand the complete implementation and design rationale, refer to the PEP for a particular new feature. +Comments, suggestions, and error reports for this document are +welcome; please e-mail them to the author or open a bug in the Python +bug tracker. %====================================================================== \section{PEP 308: Conditional Expressions\label{pep-308}} For a long time, people have been requesting a way to write -conditional expressions, expressions that return value A or value B -depending on whether a Boolean value is true or false. A conditional -expression lets you write a single assignment statement that has the -same effect as the following: +conditional expressions, which are expressions that return value A or +value B depending on whether a Boolean value is true or false. A +conditional expression lets you write a single assignment statement +that has the same effect as the following: \begin{verbatim} if condition: @@ -54,7 +79,7 @@ but there was no syntax that was preferred by a clear majority. Candidates included C's \code{cond ? true_v : false_v}, \code{if cond then true_v else false_v}, and 16 other variations. -GvR eventually chose a surprising syntax: +Guido van~Rossum eventually chose a surprising syntax: \begin{verbatim} x = true_value if condition else false_value @@ -126,19 +151,16 @@ Wouters.} \section{PEP 309: Partial Function Application\label{pep-309}} The \module{functools} module is intended to contain tools for -functional-style programming. Currently it only contains a -\class{partial()} function, but new functions will probably be added -in future versions of Python. +functional-style programming. -For programs written in a functional style, it can be useful to +One useful tool in this module is the \function{partial()} function. +For programs written in a functional style, you'll sometimes want to construct variants of existing functions that have some of the parameters filled in. Consider a Python function \code{f(a, b, c)}; you could create a new function \code{g(b, c)} that was equivalent to -\code{f(1, b, c)}. This is called ``partial function application'', -and is provided by the \class{partial} class in the new -\module{functools} module. +\code{f(1, b, c)}. This is called ``partial function application''. -The constructor for \class{partial} takes the arguments +\function{partial} takes the arguments \code{(\var{function}, \var{arg1}, \var{arg2}, ... \var{kwarg1}=\var{value1}, \var{kwarg2}=\var{value2})}. The resulting object is callable, so you can just call it to invoke \var{function} @@ -175,11 +197,40 @@ class Application: \end{verbatim} +Another function in the \module{functools} module is the +\function{update_wrapper(\var{wrapper}, \var{wrapped})} function that +helps you write well-behaved decorators. \function{update_wrapper()} +copies the name, module, and docstring attribute to a wrapper function +so that tracebacks inside the wrapped function are easier to +understand. For example, you might write: + +\begin{verbatim} +def my_decorator(f): + def wrapper(*args, **kwds): + print 'Calling decorated function' + return f(*args, **kwds) + functools.update_wrapper(wrapper, f) + return wrapper +\end{verbatim} + +\function{wraps()} is a decorator that can be used inside your own +decorators to copy the wrapped function's information. An alternate +version of the previous example would be: + +\begin{verbatim} +def my_decorator(f): + @functools.wraps(f) + def wrapper(*args, **kwds): + print 'Calling decorated function' + return f(*args, **kwds) + return wrapper +\end{verbatim} + \begin{seealso} \seepep{309}{Partial Function Application}{PEP proposed and written by -Peter Harris; implemented by Hye-Shik Chang, with adaptations by -Raymond Hettinger.} +Peter Harris; implemented by Hye-Shik Chang and Nick Coghlan, with +adaptations by Raymond Hettinger.} \end{seealso} @@ -361,7 +412,7 @@ specific exceptions. You couldn't combine both \keyword{except} blocks and a combined version was complicated and it wasn't clear what the semantics of the combined should be. -GvR spent some time working with Java, which does support the +Guido van~Rossum spent some time working with Java, which does support the equivalent of combining \keyword{except} blocks and a \keyword{finally} block, and this clarified what the statement should mean. In Python 2.5, you can now write: @@ -554,7 +605,11 @@ once the generator has been exhausted. \seepep{342}{Coroutines via Enhanced Generators}{PEP written by Guido van~Rossum and Phillip J. Eby; implemented by Phillip J. Eby. Includes examples of -some fancier uses of generators as coroutines.} +some fancier uses of generators as coroutines. + +Earlier versions of these features were proposed in +\pep{288} by Raymond Hettinger and \pep{325} by Samuele Pedroni. +} \seeurl{http://en.wikipedia.org/wiki/Coroutine}{The Wikipedia entry for coroutines.} @@ -771,7 +826,7 @@ The new \module{contextlib} module provides some functions and a decorator that are useful for writing objects for use with the '\keyword{with}' statement. -The decorator is called \function{contextfactory}, and lets you write +The decorator is called \function{contextmanager}, and lets you write a single generator function instead of defining a new class. The generator should yield exactly one value. The code up to the \keyword{yield} will be executed as the \method{__enter__()} method, and the value @@ -785,9 +840,9 @@ Our database example from the previous section could be written using this decorator as: \begin{verbatim} -from contextlib import contextfactory +from contextlib import contextmanager -@contextfactory +@contextmanager def db_transaction (connection): cursor = connection.cursor() try: @@ -933,7 +988,7 @@ space for a \ctype{PyObject} representing the item. 2147483647*4 is already more bytes than a 32-bit address space can contain. It's possible to address that much memory on a 64-bit platform, -however. The pointers for a list that size would only require 16GiB +however. The pointers for a list that size would only require 16~GiB of space, so it's not unreasonable that Python programmers might construct lists that large. Therefore, the Python interpreter had to be changed to use some type other than \ctype{int}, and this will be a @@ -1044,10 +1099,10 @@ print d[3], d[4] # Prints 0, 0 \item Both 8-bit and Unicode strings have new \method{partition(sep)} and \method{rpartition(sep)} methods that simplify a common use case. + The \method{find(S)} method is often used to get an index which is then used to slice the string and obtain the pieces that are before and after the separator. - \method{partition(sep)} condenses this pattern into a single method call that returns a 3-tuple containing the substring before the separator, the separator itself, and the @@ -1072,6 +1127,17 @@ Some examples: (Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.) +\item The \method{startswith()} and \method{endswith()} methods +of string types now accept tuples of strings to check for. + +\begin{verbatim} +def is_image_file (filename): + return filename.endswith(('.gif', '.jpg', '.tiff')) +\end{verbatim} + +(Implemented by Georg Brandl following a suggestion by Tom Lynn.) +% RFE #1491485 + \item The \function{min()} and \function{max()} built-in functions gained a \code{key} keyword parameter analogous to the \code{key} argument for \method{sort()}. This parameter supplies a function that @@ -1095,8 +1161,17 @@ print max(L) false values. \function{any()} returns \constant{True} if any value returned by the iterator is true; otherwise it will return \constant{False}. \function{all()} returns \constant{True} only if -all of the values returned by the iterator evaluate as being true. -(Suggested by GvR, and implemented by Raymond Hettinger.) +all of the values returned by the iterator evaluate as true. +(Suggested by Guido van~Rossum, and implemented by Raymond Hettinger.) + +\item The result of a class's \method{__hash__()} method can now +be either a long integer or a regular integer. If a long integer is +returned, the hash of that value is taken. In earlier versions the +hash value was required to be a regular integer, but in 2.5 the +\function{id()} built-in was changed to always return non-negative +numbers, and users often seem to use \code{id(self)} in +\method{__hash__()} methods (though this is discouraged). +% Bug #1536021 \item ASCII is now the default encoding for modules. It's now a syntax error if a module contains string literals with 8-bit @@ -1113,9 +1188,12 @@ a line like this near the top of the source file: to include an \file{__init__.py} module in a package directory. Debugging this mistake can be confusing, and usually requires running Python with the \programopt{-v} switch to log all the paths searched. -In Python 2.5, a new \exception{ImportWarning} warning is raised when +In Python 2.5, a new \exception{ImportWarning} warning is triggered when an import would have picked up a directory as a package but no -\file{__init__.py} was found. (Implemented by Thomas Wouters.) +\file{__init__.py} was found. This warning is silently ignored by default; +provide the \programopt{-Wd} option when running the Python executable +to display the warning message. +(Implemented by Thomas Wouters.) \item The list of base classes in a class definition can now be empty. As an example, this is now legal: @@ -1146,6 +1224,11 @@ produce string representations of themselves, but are also callable. Newbies who try \code{quit()} or \code{exit()} will now exit the interpreter as they expect. (Implemented by Georg Brandl.) +The Python executable now accepts the standard long options +\longprogramopt{help} and \longprogramopt{version}; on Windows, +it also accepts the \programopt{/?} option for displaying a help message. +(Implemented by Georg Brandl.) + %====================================================================== \subsection{Optimizations\label{opts}} @@ -1194,7 +1277,8 @@ Python's allocator functions instead of the system's \item The code generator's peephole optimizer now performs simple constant folding in expressions. If you write something like \code{a = 2+3}, the code generator will do the arithmetic and produce -code corresponding to \code{a = 5}. +code corresponding to \code{a = 5}. (Proposed and implemented +by Raymond Hettinger.) \item Function calls are now faster because code objects now keep the most recently finished frame (a ``zombie frame'') in an internal @@ -1288,10 +1372,13 @@ defaultdict(<type 'list'>, {'c': ['cammin', 'che'], 'e': ['era'], 'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']} \end{verbatim} -The \class{deque} double-ended queue type supplied by the +(Contributed by Guido van~Rossum.) + +\item The \class{deque} double-ended queue type supplied by the \module{collections} module now has a \method{remove(\var{value})} method that removes the first occurrence of \var{value} in the queue, raising \exception{ValueError} if the value isn't found. +(Contributed by Raymond Hettinger.) \item New module: The \module{contextlib} module contains helper functions for use with the new '\keyword{with}' statement. See @@ -1320,6 +1407,17 @@ currently-set limit. The \class{reader} class now has a \member{line_num} attribute that counts the number of physical lines read from the source; records can span multiple physical lines, so \member{line_num} is not the same as the number of records read. + +The CSV parser is now stricter about multi-line quoted +fields. Previously, if a line ended within a quoted field without a +terminating newline character, a newline would be inserted into the +returned field. This behavior caused problems when reading files that +contained carriage return characters within fields, so the code was +changed to return the field without inserting newlines. As a +consequence, if newlines embedded within fields are important, the +input should be split into lines in a manner that preserves the +newline characters. + (Contributed by Skip Montanaro and Andrew McNamara.) \item The \class{datetime} class in the \module{datetime} @@ -1335,11 +1433,27 @@ ts = datetime.strptime('10:13:15 2006-03-07', '%H:%M:%S %Y-%m-%d') \end{verbatim} +\item The \method{SequenceMatcher.get_matching_blocks()} method +in the \module{difflib} module now guarantees to return a minimal list +of blocks describing matching subsequences. Previously, the algorithm would +occasionally break a block of matching elements into two list entries. +(Enhancement by Tim Peters.) + \item The \module{doctest} module gained a \code{SKIP} option that keeps an example from being executed at all. This is intended for code snippets that are usage examples intended for the reader and aren't actually test cases. +An \var{encoding} parameter was added to the \function{testfile()} +function and the \class{DocFileSuite} class to specify the file's +encoding. This makes it easier to use non-ASCII characters in +tests contained within a docstring. (Contributed by Bjorn Tillenius.) +% Patch 1080727 + +\item The \module{email} package has been updated to version 4.0. +% XXX need to provide some more detail here +(Contributed by Barry Warsaw.) + \item The \module{fileinput} module was made more flexible. Unicode filenames are now supported, and a \var{mode} parameter that defaults to \code{"r"} was added to the @@ -1358,6 +1472,7 @@ collector; when these counts reach a specified threshold, a garbage collection sweep will be made. The existing \function{gc.collect()} function now takes an optional \var{generation} argument of 0, 1, or 2 to specify which generation to collect. +(Contributed by Barry Warsaw.) \item The \function{nsmallest()} and \function{nlargest()} functions in the \module{heapq} module @@ -1388,6 +1503,29 @@ itertools.islice(iterable, s.start, s.stop, s.step) (Contributed by Raymond Hettinger.) +\item The \function{format()} function in the \module{locale} module +has been modified and two new functions were added, +\function{format_string()} and \function{currency()}. + +The \function{format()} function's \var{val} parameter could +previously be a string as long as no more than one \%char specifier +appeared; now the parameter must be exactly one \%char specifier with +no surrounding text. An optional \var{monetary} parameter was also +added which, if \code{True}, will use the locale's rules for +formatting currency in placing a separator between groups of three +digits. + +To format strings with multiple \%char specifiers, use the new +\function{format_string()} function that works like \function{format()} +but also supports mixing \%char specifiers with +arbitrary text. + +A new \function{currency()} function was also added that formats a +number according to the current locale's settings. + +(Contributed by Georg Brandl.) +% Patch 1180296 + \item The \module{mailbox} module underwent a massive rewrite to add the capability to modify mailboxes in addition to reading them. A new set of classes that include \class{mbox}, \class{MH}, and @@ -1496,6 +1634,9 @@ tuple slicing, method lookups, and numeric operations, instead of performing many different operations and reducing the result to a single number as \file{pystone.py} does. +\item The \module{pyexpat} module now uses version 2.0 of the Expat parser. +(Contributed by Trent Mick.) + \item The old \module{regex} and \module{regsub} modules, which have been deprecated ever since Python 2.0, have finally been deleted. Other deleted modules: \module{statcache}, \module{tzparse}, @@ -1560,7 +1701,7 @@ year, number, name = s.unpack(data) \end{verbatim} You can also pack and unpack data to and from buffer objects directly -using the \method{pack_to(\var{buffer}, \var{offset}, \var{v1}, +using the \method{pack_into(\var{buffer}, \var{offset}, \var{v1}, \var{v2}, ...)} and \method{unpack_from(\var{buffer}, \var{offset})} methods. This lets you store data directly into an array or a memory-mapped file. @@ -1582,22 +1723,76 @@ string of build information like this: \code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}. (Contributed by Barry Warsaw.) +\item Another new function, \function{sys._current_frames()}, returns +the current stack frames for all running threads as a dictionary +mapping thread identifiers to the topmost stack frame currently active +in that thread at the time the function is called. (Contributed by +Tim Peters.) + \item The \class{TarFile} class in the \module{tarfile} module now has an \method{extractall()} method that extracts all members from the archive into the current working directory. It's also possible to set a different directory as the extraction target, and to unpack only a -subset of the archive's members. +subset of the archive's members. -A tarfile's compression can be autodetected by -using the mode \code{'r|*'}. +The compression used for a tarfile opened in stream mode can now be +autodetected using the mode \code{'r|*'}. % patch 918101 (Contributed by Lars Gust\"abel.) +\item The \module{threading} module now lets you set the stack size +used when new threads are created. The +\function{stack_size(\optional{\var{size}})} function returns the +currently configured stack size, and supplying the optional \var{size} +parameter sets a new value. Not all platforms support changing the +stack size, but Windows, POSIX threading, and OS/2 all do. +(Contributed by Andrew MacIntyre.) +% Patch 1454481 + \item The \module{unicodedata} module has been updated to use version 4.1.0 of the Unicode character database. Version 3.2.0 is required by some specifications, so it's still available as \member{unicodedata.ucd_3_2_0}. +\item New module: the \module{uuid} module generates +universally unique identifiers (UUIDs) according to \rfc{4122}. The +RFC defines several different UUID versions that are generated from a +starting string, from system properties, or purely randomly. This +module contains a \class{UUID} class and +functions named \function{uuid1()}, +\function{uuid3()}, \function{uuid4()}, and +\function{uuid5()} to generate different versions of UUID. (Version 2 UUIDs +are not specified in \rfc{4122} and are not supported by this module.) + +\begin{verbatim} +>>> import uuid +>>> # make a UUID based on the host ID and current time +>>> uuid.uuid1() +UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') + +>>> # make a UUID using an MD5 hash of a namespace UUID and a name +>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') +UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') + +>>> # make a random UUID +>>> uuid.uuid4() +UUID('16fd2706-8baf-433b-82eb-8c7fada847da') + +>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name +>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') +UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') +\end{verbatim} + +(Contributed by Ka-Ping Yee.) + +\item The \module{weakref} module's \class{WeakKeyDictionary} and +\class{WeakValueDictionary} types gained new methods for iterating +over the weak references contained in the dictionary. +\method{iterkeyrefs()} and \method{keyrefs()} methods were +added to \class{WeakKeyDictionary}, and +\method{itervaluerefs()} and \method{valuerefs()} were added to +\class{WeakValueDictionary}. (Contributed by Fred L.~Drake, Jr.) + \item The \module{webbrowser} module received a number of enhancements. It's now usable as a script with \code{python -m webbrowser}, taking a @@ -1609,11 +1804,10 @@ to support this. The module's \function{open()} function supports an additional feature, an \var{autoraise} parameter that signals whether to raise the open window when possible. A number of additional browsers were added to the supported list such as Firefox, Opera, -Konqueror, and elinks. (Contributed by Oleg Broytmann and George +Konqueror, and elinks. (Contributed by Oleg Broytmann and Georg Brandl.) % Patch #754022 - \item The \module{xmlrpclib} module now supports returning \class{datetime} objects for the XML-RPC date type. Supply \code{use_datetime=True} to the \function{loads()} function @@ -1621,6 +1815,12 @@ Brandl.) (Contributed by Skip Montanaro.) % Patch 1120353 +\item The \module{zipfile} module now supports the ZIP64 version of the +format, meaning that a .zip archive can now be larger than 4~GiB and +can contain individual files larger than 4~GiB. (Contributed by +Ronald Oussoren.) +% Patch 1446489 + \item The \module{zlib} module's \class{Compress} and \class{Decompress} objects now support a \method{copy()} method that makes a copy of the object's internal state and returns a new @@ -1711,6 +1911,9 @@ of extension modules, now that \module{ctypes} is included with core Python. \seeurl{http://starship.python.net/crew/theller/ctypes/} {The ctypes web page, with a tutorial, reference, and FAQ.} +\seeurl{../lib/module-ctypes.html}{The documentation +for the \module{ctypes} module.} + \end{seealso} @@ -1822,7 +2025,6 @@ Please read the package's official documentation for more details. \seeurl{http://effbot.org/zone/element-index.htm} {Official documentation for ElementTree.} - \end{seealso} @@ -1873,6 +2075,13 @@ current digest state, \method{digest()} and \method{hexdigest()} return the digest value as a binary string or a string of hex digits, and \method{copy()} returns a new hashing object with the same digest state. +\begin{seealso} + +\seeurl{../lib/module-hashlib.html}{The documentation +for the \module{hashlib} module.} + +\end{seealso} + %====================================================================== \subsection{The sqlite3 package\label{module-sqlite}} @@ -1983,12 +2192,53 @@ For more information about the SQL dialect supported by SQLite, see {The SQLite web page; the documentation describes the syntax and the available data types for the supported SQL dialect.} +\seeurl{../lib/module-sqlite3.html}{The documentation +for the \module{sqlite3} module.} + \seepep{249}{Database API Specification 2.0}{PEP written by Marc-Andr\'e Lemburg.} \end{seealso} +%====================================================================== +\subsection{The wsgiref package\label{module-wsgiref}} + +% XXX should this be in a PEP 333 section instead? + +The Web Server Gateway Interface (WSGI) v1.0 defines a standard +interface between web servers and Python web applications and is +described in \pep{333}. The \module{wsgiref} package is a reference +implementation of the WSGI specification. + +The package includes a basic HTTP server that will run a WSGI +application; this server is useful for debugging but isn't intended for +production use. Setting up a server takes only a few lines of code: + +\begin{verbatim} +from wsgiref import simple_server + +wsgi_app = ... + +host = '' +port = 8000 +httpd = simple_server.make_server(host, port, wsgi_app) +httpd.serve_forever() +\end{verbatim} + +% XXX discuss structure of WSGI applications? +% XXX provide an example using Django or some other framework? + +\begin{seealso} + +\seeurl{http://www.wsgi.org}{A central web site for WSGI-related resources.} + +\seepep{333}{Python Web Server Gateway Interface v1.0}{PEP written by +Phillip J. Eby.} + +\end{seealso} + + % ====================================================================== \section{Build and C API Changes\label{build-api}} @@ -1996,13 +2246,25 @@ Changes to Python's build process and to the C API include: \begin{itemize} +\item The Python source tree was converted from CVS to Subversion, +in a complex migration procedure that was supervised and flawlessly +carried out by Martin von~L\"owis. The procedure was developed as +\pep{347}. + +\item Coverity, a company that markets a source code analysis tool +called Prevent, provided the results of their examination of the Python +source code. The analysis found about 60 bugs that +were quickly fixed. Many of the bugs were refcounting problems, often +occurring in error-handling code. See +\url{http://scan.coverity.com} for the statistics. + \item The largest change to the C API came from \pep{353}, which modifies the interpreter to use a \ctype{Py_ssize_t} type definition instead of \ctype{int}. See the earlier section~\ref{pep-353} for a discussion of this change. -\item The design of the bytecode compiler has changed a great deal, to -no longer generate bytecode by traversing the parse tree. Instead +\item The design of the bytecode compiler has changed a great deal, +no longer generating bytecode by traversing the parse tree. Instead the parse tree is converted to an abstract syntax tree (or AST), and it is the abstract syntax tree that's traversed to produce the bytecode. @@ -2022,12 +2284,13 @@ assignment = ast.body[0] for_loop = ast.body[1] \end{verbatim} -No documentation has been written for the AST code yet. To start -learning about it, read the definition of the various AST nodes in -\file{Parser/Python.asdl}. A Python script reads this file and -generates a set of C structure definitions in -\file{Include/Python-ast.h}. The \cfunction{PyParser_ASTFromString()} -and \cfunction{PyParser_ASTFromFile()}, defined in +No official documentation has been written for the AST code yet, but +\pep{339} discusses the design. To start learning about the code, read the +definition of the various AST nodes in \file{Parser/Python.asdl}. A +Python script reads this file and generates a set of C structure +definitions in \file{Include/Python-ast.h}. The +\cfunction{PyParser_ASTFromString()} and +\cfunction{PyParser_ASTFromFile()}, defined in \file{Include/pythonrun.h}, take Python source as input and return the root of an AST representing the contents. This AST can then be turned into a code object by \cfunction{PyAST_Compile()}. For more @@ -2042,6 +2305,32 @@ Grant Edwards, John Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters, Armin Rigo, and Neil Schemenauer, plus the participants in a number of AST sprints at conferences such as PyCon. +\item Evan Jones's patch to obmalloc, first described in a talk +at PyCon DC 2005, was applied. Python 2.4 allocated small objects in +256K-sized arenas, but never freed arenas. With this patch, Python +will free arenas when they're empty. The net effect is that on some +platforms, when you allocate many objects, Python's memory usage may +actually drop when you delete them and the memory may be returned to +the operating system. (Implemented by Evan Jones, and reworked by Tim +Peters.) + +Note that this change means extension modules must be more careful +when allocating memory. Python's API has many different +functions for allocating memory that are grouped into families. For +example, \cfunction{PyMem_Malloc()}, \cfunction{PyMem_Realloc()}, and +\cfunction{PyMem_Free()} are one family that allocates raw memory, +while \cfunction{PyObject_Malloc()}, \cfunction{PyObject_Realloc()}, +and \cfunction{PyObject_Free()} are another family that's supposed to +be used for creating Python objects. + +Previously these different families all reduced to the platform's +\cfunction{malloc()} and \cfunction{free()} functions. This meant +it didn't matter if you got things wrong and allocated memory with the +\cfunction{PyMem} function but freed it with the \cfunction{PyObject} +function. With 2.5's changes to obmalloc, these families now do different +things and mismatches will probably result in a segfault. You should +carefully test your C extension modules with Python 2.5. + \item The built-in set types now have an official C API. Call \cfunction{PySet_New()} and \cfunction{PyFrozenSet_New()} to create a new set, \cfunction{PySet_Add()} and \cfunction{PySet_Discard()} to @@ -2072,13 +2361,25 @@ Lundh at the NeedForSpeed sprint.) \var{dict})} can now accept a tuple of base classes as its \var{base} argument. (Contributed by Georg Brandl.) +\item The \cfunction{PyErr_Warn()} function for issuing warnings +is now deprecated in favour of \cfunction{PyErr_WarnEx(category, +message, stacklevel)} which lets you specify the number of stack +frames separating this function and the caller. A \var{stacklevel} of +1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is the +function above that, and so forth. (Added by Neal Norwitz.) + \item The CPython interpreter is still written in C, but the code can now be compiled with a {\Cpp} compiler without errors. (Implemented by Anthony Baxter, Martin von~L\"owis, Skip Montanaro.) \item The \cfunction{PyRange_New()} function was removed. It was never documented, never used in the core code, and had dangerously lax -error checking. +error checking. In the unlikely case that your extensions were using +it, you can replace it by something like the following: +\begin{verbatim} +range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll", + start, stop, step); +\end{verbatim} \end{itemize} @@ -2105,54 +2406,6 @@ be searched for. %====================================================================== -\section{Other Changes and Fixes \label{section-other}} - -As usual, there were a bunch of other improvements and bugfixes -scattered throughout the source tree. A search through the SVN change -logs finds there were XXX patches applied and YYY bugs fixed between -Python 2.4 and 2.5. Both figures are likely to be underestimates. - -Some of the more notable changes are: - -\begin{itemize} - -\item Evan Jones's patch to obmalloc, first described in a talk -at PyCon DC 2005, was applied. Python 2.4 allocated small objects in -256K-sized arenas, but never freed arenas. With this patch, Python -will free arenas when they're empty. The net effect is that on some -platforms, when you allocate many objects, Python's memory usage may -actually drop when you delete them, and the memory may be returned to -the operating system. (Implemented by Evan Jones, and reworked by Tim -Peters.) - -Note that this change means extension modules need to be more careful -with how they allocate memory. Python's API has many different -functions for allocating memory that are grouped into families. For -example, \cfunction{PyMem_Malloc()}, \cfunction{PyMem_Realloc()}, and -\cfunction{PyMem_Free()} are one family that allocates raw memory, -while \cfunction{PyObject_Malloc()}, \cfunction{PyObject_Realloc()}, -and \cfunction{PyObject_Free()} are another family that's supposed to -be used for creating Python objects. - -Previously these different families all reduced to the platform's -\cfunction{malloc()} and \cfunction{free()} functions. This meant -it didn't matter if you got things wrong and allocated memory with the -\cfunction{PyMem} function but freed it with the \cfunction{PyObject} -function. With the obmalloc change, these families now do different -things, and mismatches will probably result in a segfault. You should -carefully test your C extension modules with Python 2.5. - -\item Coverity, a company that markets a source code analysis tool - called Prevent, provided the results of their examination of the Python - source code. The analysis found about 60 bugs that - were quickly fixed. Many of the bugs were refcounting problems, often - occurring in error-handling code. See - \url{http://scan.coverity.com} for the statistics. - -\end{itemize} - - -%====================================================================== \section{Porting to Python 2.5\label{porting}} This section lists previously described changes that may require @@ -2170,6 +2423,16 @@ was always a frame object. Because of the \pep{342} changes described in section~\ref{pep-342}, it's now possible for \member{gi_frame} to be \code{None}. +\item Library: the \module{csv} module is now stricter about multi-line quoted +fields. If your files contain newlines embedded within fields, the +input should be split into lines in a manner which preserves the +newline characters. + +\item Library: the \module{locale} module's +\function{format()} function's would previously +accept any string as long as no more than one \%char specifier +appeared. In Python 2.5, the argument must be exactly one \%char +specifier with no surrounding text. \item Library: The \module{pickle} and \module{cPickle} modules no longer accept a return value of \code{None} from the @@ -2206,7 +2469,10 @@ freed with the corresponding family's \cfunction{*_Free()} function. The author would like to thank the following people for offering suggestions, corrections and assistance with various drafts of this -article: Phillip J. Eby, Kent Johnson, Martin von~L\"owis, Fredrik Lundh, -Gustavo Niemeyer, James Pryor, Mike Rovner, Scott Weikart, Thomas Wouters. +article: Georg Brandl, Nick Coghlan, Phillip J. Eby, Lars Gust\"abel, +Raymond Hettinger, Ralf W. Grosse-Kunstleve, Kent Johnson, Iain Lowe, +Martin von~L\"owis, Fredrik Lundh, Andrew McNamara, Skip Montanaro, +Gustavo Niemeyer, Paul Prescod, James Pryor, Mike Rovner, Scott +Weikart, Barry Warsaw, Thomas Wouters. \end{document} |