From python-checkins at python.org Tue Apr 24 15:54:11 2007 From: python-checkins at python.org (kristjan.jonsson) Date: Tue, 24 Apr 2007 15:54:11 +0200 (CEST) Subject: [Stackless-checkins] r54937 - in stackless/branches/release25-maint/Stackless: core/stackless_structs.h core/stacklesseval.c platf/switch_x86_msvc.h Message-ID: <20070424135411.A17841E400A@bag.python.org> Author: kristjan.jonsson Date: Tue Apr 24 15:54:07 2007 New Revision: 54937 Modified: stackless/branches/release25-maint/Stackless/core/stackless_structs.h stackless/branches/release25-maint/Stackless/core/stacklesseval.c stackless/branches/release25-maint/Stackless/platf/switch_x86_msvc.h Log: For Win32, save and restore the SEH register when saving the stack. This is a variable in the Thread Information Block (TIB). This fixes problems with handling exceptions in tasklets. Modified: stackless/branches/release25-maint/Stackless/core/stackless_structs.h ============================================================================== --- stackless/branches/release25-maint/Stackless/core/stackless_structs.h (original) +++ stackless/branches/release25-maint/Stackless/core/stackless_structs.h Tue Apr 24 15:54:07 2007 @@ -5,6 +5,9 @@ extern "C" { #endif +/* platform specific constants (mainly SEH stuff to store )*/ +#include "platf/slp_platformselect.h" + /*** important structures: tasklet ***/ @@ -102,6 +105,9 @@ struct _tasklet *task; int nesting_level; PyThreadState *tstate; +#ifdef _SEH32 + DWORD exception_list; /* SEH handler on Win32 */ +#endif intptr_t *startaddr; intptr_t stack[1]; } PyCStackObject; Modified: stackless/branches/release25-maint/Stackless/core/stacklesseval.c ============================================================================== --- stackless/branches/release25-maint/Stackless/core/stacklesseval.c (original) +++ stackless/branches/release25-maint/Stackless/core/stacklesseval.c Tue Apr 24 15:54:07 2007 @@ -111,6 +111,11 @@ (*cst)->task = task; (*cst)->tstate = ts; (*cst)->nesting_level = ts->st.nesting_level; +#ifdef _SEH32 + //save the SEH handler + (*cst)->exception_list = (DWORD) + __readfsdword(FIELD_OFFSET(NT_TIB, ExceptionList)); +#endif return *cst; } @@ -121,10 +126,18 @@ memcpy((cstprev)->stack, (cstprev)->startaddr - (cstprev)->ob_size, stsizeb); +#ifdef _SEH32 + //save the SEH handler + cstprev->exception_list = (DWORD) + __readfsdword(FIELD_OFFSET(NT_TIB, ExceptionList)); +#endif return stsizeb; } void +#ifdef _SEH32 +#pragma warning(disable:4733) /* disable warning about modifying FS[0] */ +#endif slp_cstack_restore(PyCStackObject *cst) { cst->tstate->st.nesting_level = cst->nesting_level; @@ -132,6 +145,11 @@ cst->task = NULL; memcpy(cst->startaddr - cst->ob_size, &cst->stack, (cst->ob_size) * sizeof(intptr_t)); +#ifdef _SEH32 + //restore the SEH handler + __writefsdword(FIELD_OFFSET(NT_TIB, ExceptionList), (DWORD)(cst->exception_list)); + #pragma warning(default:4733) +#endif } Modified: stackless/branches/release25-maint/Stackless/platf/switch_x86_msvc.h ============================================================================== --- stackless/branches/release25-maint/Stackless/platf/switch_x86_msvc.h (original) +++ stackless/branches/release25-maint/Stackless/platf/switch_x86_msvc.h Tue Apr 24 15:54:07 2007 @@ -22,6 +22,16 @@ * Initial final version after lots of iterations for i386. */ +/* for the SEH things */ +#ifndef _WINDOWS_ +#define WIN32_LEAN_AND_MEAN +#ifdef BYTE +#undef BYTE +#endif +#include +#endif +#define _SEH32 + #define alloca _alloca #define STACK_REFPLUS 1 @@ -36,6 +46,7 @@ #pragma optimize("", off) +#pragma warning(disable:4731) /* disable ebp modification warning */ static int slp_switch(void) { @@ -54,6 +65,7 @@ SLP_RESTORE_STATE(); return 0; } +#pragma warning(default:4731) } #endif _______________________________________________ Stackless-checkins mailing list Stackless-checkins at stackless.com http://www.stackless.com/mailman/listinfo/stackless-checkins From python-checkins at python.org Sat Apr 14 15:05:17 2007 From: python-checkins at python.org (richard.tew) Date: Sat, 14 Apr 2007 15:05:17 +0200 (CEST) Subject: [Stackless-checkins] r54826 - in stackless/branches/release25-maint: Demo/parser/unparse.py Doc/README Doc/api/abstract.tex Doc/api/concrete.tex Doc/api/exceptions.tex Doc/api/memory.tex Doc/api/newtypes.tex Doc/api/utilities.tex Doc/commontex/boilerplate.tex Doc/commontex/license.tex Doc/dist/dist.tex Doc/ext/newtypes.tex Doc/ext/shoddy.c Doc/inst/inst.tex Doc/lib/emailgenerator.tex Doc/lib/libasyncore.tex Doc/lib/libbase64.tex Doc/lib/libbsddb.tex Doc/lib/libbz2.tex Doc/lib/libcollections.tex Doc/lib/libcommands.tex Doc/lib/libcsv.tex Doc/lib/libctypes.tex Doc/lib/libdbhash.tex Doc/lib/libfnmatch.tex Doc/lib/libfuncs.tex Doc/lib/libfunctools.tex Doc/lib/libgetopt.tex Doc/lib/libgettext.tex Doc/lib/libheapq.tex Doc/lib/libimageop.tex Doc/lib/libitertools.tex Doc/lib/liblocale.tex Doc/lib/liblogging.tex Doc/lib/libmailbox.tex Doc/lib/libmmap.tex Doc/lib/libmsilib.tex Doc/lib/libos.tex Doc/lib/libpickle.tex Doc/lib/libpopen2.tex Doc/lib/libprofile.tex Doc/lib/librandom.tex Doc/lib/libshu! til.tex Doc/lib/libsimplexmlrpc.tex Doc/lib/libsmtplib.tex Doc/lib/libsocket.tex Doc/lib/libsqlite3.tex Doc/lib/libstdtypes.tex Doc/lib/libstring.tex Doc/lib/libstruct.tex Doc/lib/libsubprocess.tex Doc/lib/libtarfile.tex Doc/lib/libtempfile.tex Doc/lib/libthreading.tex Doc/lib/libtimeit.tex Doc/lib/libunittest.tex Doc/lib/liburlparse.tex Doc/lib/libwsgiref.tex Doc/lib/tkinter.tex Doc/mac/toolbox.tex Doc/ref/ref1.tex Doc/ref/ref3.tex Doc/ref/ref5.tex Doc/ref/ref6.tex Doc/ref/ref7.tex Doc/tools/py2texi.el Doc/tut/tut.tex Doc/whatsnew/whatsnew25.tex Include/Python-ast.h Include/abstract.h Include/dictobject.h Include/patchlevel.h Include/pystate.h Include/setobject.h LICENSE Lib/CGIHTTPServer.py Lib/Queue.py Lib/SimpleHTTPServer.py Lib/SocketServer.py Lib/StringIO.py Lib/_strptime.py Lib/bisect.py Lib/bsddb/dbobj.py Lib/bsddb/test/test_1413192.py Lib/bsddb/test/test_dbobj.py Lib/codecs.py Lib/compiler/pycodegen.py Lib/compiler/transformer.py Lib/ctypes Lib/ctypes/__init__.py L! ib/ctypes/test/test_callbacks.py Lib/ctypes/test/test_functions.py Lib/ctypes/test/test_loading.py Lib/ctypes/test/test_memfunctions.py Lib/ctypes/test/test_structures.py Lib/ctypes/util.py Lib/decimal.py Lib/difflib.py Lib/distutils/__init__.py Lib/distutils/command/bdist_rpm.py Lib/distutils/command/build_ext.py Lib/distut Message-ID: <20070414130517.4C5521E4003@bag.python.org> Author: richard.tew Date: Sat Apr 14 15:02:57 2007 New Revision: 54826 Added: stackless/branches/release25-maint/Doc/ext/shoddy.c - copied unchanged from r54693, python/branches/release25-maint/Doc/ext/shoddy.c stackless/branches/release25-maint/Lib/test/infinite_reload.py - copied unchanged from r54693, python/branches/release25-maint/Lib/test/infinite_reload.py stackless/branches/release25-maint/Lib/test/test_structmembers.py - copied unchanged from r54693, python/branches/release25-maint/Lib/test/test_structmembers.py stackless/branches/release25-maint/PC/VC6/_sqlite3.dsp - copied unchanged from r54693, python/branches/release25-maint/PC/VC6/_sqlite3.dsp Removed: stackless/branches/release25-maint/PC/VC6/zlib.dsp Modified: stackless/branches/release25-maint/Demo/parser/unparse.py stackless/branches/release25-maint/Doc/README stackless/branches/release25-maint/Doc/api/abstract.tex stackless/branches/release25-maint/Doc/api/concrete.tex stackless/branches/release25-maint/Doc/api/exceptions.tex stackless/branches/release25-maint/Doc/api/memory.tex stackless/branches/release25-maint/Doc/api/newtypes.tex stackless/branches/release25-maint/Doc/api/utilities.tex stackless/branches/release25-maint/Doc/commontex/boilerplate.tex stackless/branches/release25-maint/Doc/commontex/license.tex stackless/branches/release25-maint/Doc/dist/dist.tex stackless/branches/release25-maint/Doc/ext/newtypes.tex stackless/branches/release25-maint/Doc/inst/inst.tex stackless/branches/release25-maint/Doc/lib/emailgenerator.tex stackless/branches/release25-maint/Doc/lib/libasyncore.tex stackless/branches/release25-maint/Doc/lib/libbase64.tex stackless/branches/release25-maint/Doc/lib/libbsddb.tex stackless/branches/release25-maint/Doc/lib/libbz2.tex stackless/branches/release25-maint/Doc/lib/libcollections.tex stackless/branches/release25-maint/Doc/lib/libcommands.tex stackless/branches/release25-maint/Doc/lib/libcsv.tex stackless/branches/release25-maint/Doc/lib/libctypes.tex stackless/branches/release25-maint/Doc/lib/libdbhash.tex stackless/branches/release25-maint/Doc/lib/libfnmatch.tex stackless/branches/release25-maint/Doc/lib/libfuncs.tex stackless/branches/release25-maint/Doc/lib/libfunctools.tex stackless/branches/release25-maint/Doc/lib/libgetopt.tex stackless/branches/release25-maint/Doc/lib/libgettext.tex stackless/branches/release25-maint/Doc/lib/libheapq.tex stackless/branches/release25-maint/Doc/lib/libimageop.tex stackless/branches/release25-maint/Doc/lib/libitertools.tex stackless/branches/release25-maint/Doc/lib/liblocale.tex stackless/branches/release25-maint/Doc/lib/liblogging.tex stackless/branches/release25-maint/Doc/lib/libmailbox.tex stackless/branches/release25-maint/Doc/lib/libmmap.tex stackless/branches/release25-maint/Doc/lib/libmsilib.tex stackless/branches/release25-maint/Doc/lib/libos.tex stackless/branches/release25-maint/Doc/lib/libpickle.tex stackless/branches/release25-maint/Doc/lib/libpopen2.tex stackless/branches/release25-maint/Doc/lib/libprofile.tex stackless/branches/release25-maint/Doc/lib/librandom.tex stackless/branches/release25-maint/Doc/lib/libshutil.tex stackless/branches/release25-maint/Doc/lib/libsimplexmlrpc.tex stackless/branches/release25-maint/Doc/lib/libsmtplib.tex stackless/branches/release25-maint/Doc/lib/libsocket.tex stackless/branches/release25-maint/Doc/lib/libsqlite3.tex stackless/branches/release25-maint/Doc/lib/libstdtypes.tex stackless/branches/release25-maint/Doc/lib/libstring.tex stackless/branches/release25-maint/Doc/lib/libstruct.tex stackless/branches/release25-maint/Doc/lib/libsubprocess.tex stackless/branches/release25-maint/Doc/lib/libtarfile.tex stackless/branches/release25-maint/Doc/lib/libtempfile.tex stackless/branches/release25-maint/Doc/lib/libthreading.tex stackless/branches/release25-maint/Doc/lib/libtimeit.tex stackless/branches/release25-maint/Doc/lib/libunittest.tex stackless/branches/release25-maint/Doc/lib/liburlparse.tex stackless/branches/release25-maint/Doc/lib/libwsgiref.tex stackless/branches/release25-maint/Doc/lib/tkinter.tex stackless/branches/release25-maint/Doc/mac/toolbox.tex stackless/branches/release25-maint/Doc/ref/ref1.tex stackless/branches/release25-maint/Doc/ref/ref3.tex stackless/branches/release25-maint/Doc/ref/ref5.tex stackless/branches/release25-maint/Doc/ref/ref6.tex stackless/branches/release25-maint/Doc/ref/ref7.tex stackless/branches/release25-maint/Doc/tools/py2texi.el stackless/branches/release25-maint/Doc/tut/tut.tex stackless/branches/release25-maint/Doc/whatsnew/whatsnew25.tex stackless/branches/release25-maint/Include/Python-ast.h stackless/branches/release25-maint/Include/abstract.h stackless/branches/release25-maint/Include/dictobject.h stackless/branches/release25-maint/Include/patchlevel.h stackless/branches/release25-maint/Include/pystate.h stackless/branches/release25-maint/Include/setobject.h stackless/branches/release25-maint/LICENSE stackless/branches/release25-maint/Lib/CGIHTTPServer.py stackless/branches/release25-maint/Lib/Queue.py stackless/branches/release25-maint/Lib/SimpleHTTPServer.py stackless/branches/release25-maint/Lib/SocketServer.py stackless/branches/release25-maint/Lib/StringIO.py stackless/branches/release25-maint/Lib/_strptime.py stackless/branches/release25-maint/Lib/bisect.py stackless/branches/release25-maint/Lib/bsddb/dbobj.py stackless/branches/release25-maint/Lib/bsddb/test/test_1413192.py stackless/branches/release25-maint/Lib/bsddb/test/test_dbobj.py stackless/branches/release25-maint/Lib/codecs.py stackless/branches/release25-maint/Lib/compiler/pycodegen.py stackless/branches/release25-maint/Lib/compiler/transformer.py stackless/branches/release25-maint/Lib/ctypes/ (props changed) stackless/branches/release25-maint/Lib/ctypes/__init__.py stackless/branches/release25-maint/Lib/ctypes/test/test_callbacks.py stackless/branches/release25-maint/Lib/ctypes/test/test_functions.py stackless/branches/release25-maint/Lib/ctypes/test/test_loading.py stackless/branches/release25-maint/Lib/ctypes/test/test_memfunctions.py stackless/branches/release25-maint/Lib/ctypes/test/test_structures.py stackless/branches/release25-maint/Lib/ctypes/util.py stackless/branches/release25-maint/Lib/decimal.py stackless/branches/release25-maint/Lib/difflib.py stackless/branches/release25-maint/Lib/distutils/__init__.py stackless/branches/release25-maint/Lib/distutils/command/bdist_rpm.py stackless/branches/release25-maint/Lib/distutils/command/build_ext.py stackless/branches/release25-maint/Lib/distutils/command/install_egg_info.py stackless/branches/release25-maint/Lib/distutils/msvccompiler.py stackless/branches/release25-maint/Lib/email/_parseaddr.py stackless/branches/release25-maint/Lib/email/header.py stackless/branches/release25-maint/Lib/email/message.py stackless/branches/release25-maint/Lib/email/test/test_email.py stackless/branches/release25-maint/Lib/email/test/test_email_renamed.py stackless/branches/release25-maint/Lib/encodings/bz2_codec.py stackless/branches/release25-maint/Lib/encodings/utf_8_sig.py stackless/branches/release25-maint/Lib/encodings/zlib_codec.py stackless/branches/release25-maint/Lib/ftplib.py stackless/branches/release25-maint/Lib/functools.py stackless/branches/release25-maint/Lib/hashlib.py stackless/branches/release25-maint/Lib/heapq.py stackless/branches/release25-maint/Lib/httplib.py stackless/branches/release25-maint/Lib/idlelib/EditorWindow.py stackless/branches/release25-maint/Lib/idlelib/MultiCall.py stackless/branches/release25-maint/Lib/idlelib/NEWS.txt stackless/branches/release25-maint/Lib/idlelib/idlever.py stackless/branches/release25-maint/Lib/imputil.py stackless/branches/release25-maint/Lib/lib-tk/Tix.py stackless/branches/release25-maint/Lib/lib-tk/tkSimpleDialog.py stackless/branches/release25-maint/Lib/logging/__init__.py stackless/branches/release25-maint/Lib/logging/config.py stackless/branches/release25-maint/Lib/logging/handlers.py stackless/branches/release25-maint/Lib/mailbox.py stackless/branches/release25-maint/Lib/os.py stackless/branches/release25-maint/Lib/pdb.py stackless/branches/release25-maint/Lib/pstats.py stackless/branches/release25-maint/Lib/pty.py stackless/branches/release25-maint/Lib/pydoc.py stackless/branches/release25-maint/Lib/random.py stackless/branches/release25-maint/Lib/rfc822.py stackless/branches/release25-maint/Lib/sched.py stackless/branches/release25-maint/Lib/socket.py stackless/branches/release25-maint/Lib/sre.py stackless/branches/release25-maint/Lib/subprocess.py stackless/branches/release25-maint/Lib/tarfile.py stackless/branches/release25-maint/Lib/test/crashers/weakref_in_del.py stackless/branches/release25-maint/Lib/test/pickletester.py stackless/branches/release25-maint/Lib/test/regrtest.py stackless/branches/release25-maint/Lib/test/test_array.py stackless/branches/release25-maint/Lib/test/test_binascii.py stackless/branches/release25-maint/Lib/test/test_builtin.py stackless/branches/release25-maint/Lib/test/test_class.py stackless/branches/release25-maint/Lib/test/test_cmd_line.py stackless/branches/release25-maint/Lib/test/test_codecs.py stackless/branches/release25-maint/Lib/test/test_compiler.py stackless/branches/release25-maint/Lib/test/test_curses.py stackless/branches/release25-maint/Lib/test/test_datetime.py stackless/branches/release25-maint/Lib/test/test_dbm.py stackless/branches/release25-maint/Lib/test/test_defaultdict.py stackless/branches/release25-maint/Lib/test/test_deque.py stackless/branches/release25-maint/Lib/test/test_descr.py stackless/branches/release25-maint/Lib/test/test_dict.py stackless/branches/release25-maint/Lib/test/test_exceptions.py stackless/branches/release25-maint/Lib/test/test_functools.py stackless/branches/release25-maint/Lib/test/test_gdbm.py stackless/branches/release25-maint/Lib/test/test_grammar.py stackless/branches/release25-maint/Lib/test/test_heapq.py stackless/branches/release25-maint/Lib/test/test_import.py stackless/branches/release25-maint/Lib/test/test_itertools.py stackless/branches/release25-maint/Lib/test/test_logging.py stackless/branches/release25-maint/Lib/test/test_mailbox.py stackless/branches/release25-maint/Lib/test/test_nis.py stackless/branches/release25-maint/Lib/test/test_old_mailbox.py stackless/branches/release25-maint/Lib/test/test_operator.py stackless/branches/release25-maint/Lib/test/test_os.py stackless/branches/release25-maint/Lib/test/test_peepholer.py stackless/branches/release25-maint/Lib/test/test_pty.py stackless/branches/release25-maint/Lib/test/test_random.py stackless/branches/release25-maint/Lib/test/test_re.py stackless/branches/release25-maint/Lib/test/test_sax.py stackless/branches/release25-maint/Lib/test/test_set.py stackless/branches/release25-maint/Lib/test/test_sha.py stackless/branches/release25-maint/Lib/test/test_slice.py stackless/branches/release25-maint/Lib/test/test_socket.py stackless/branches/release25-maint/Lib/test/test_socket_ssl.py stackless/branches/release25-maint/Lib/test/test_socketserver.py stackless/branches/release25-maint/Lib/test/test_strptime.py stackless/branches/release25-maint/Lib/test/test_struct.py stackless/branches/release25-maint/Lib/test/test_subprocess.py stackless/branches/release25-maint/Lib/test/test_syntax.py stackless/branches/release25-maint/Lib/test/test_tarfile.py stackless/branches/release25-maint/Lib/test/test_unpack.py stackless/branches/release25-maint/Lib/test/test_urllib.py stackless/branches/release25-maint/Lib/test/test_urllib2net.py stackless/branches/release25-maint/Lib/test/test_userdict.py stackless/branches/release25-maint/Lib/test/test_weakref.py stackless/branches/release25-maint/Lib/threading.py stackless/branches/release25-maint/Lib/trace.py stackless/branches/release25-maint/Lib/unittest.py stackless/branches/release25-maint/Lib/urllib.py stackless/branches/release25-maint/Lib/urllib2.py stackless/branches/release25-maint/Lib/uu.py stackless/branches/release25-maint/Lib/wave.py stackless/branches/release25-maint/Lib/webbrowser.py stackless/branches/release25-maint/Lib/xml/sax/saxutils.py stackless/branches/release25-maint/Mac/BuildScript/build-installer.py stackless/branches/release25-maint/Makefile.pre.in stackless/branches/release25-maint/Misc/ACKS stackless/branches/release25-maint/Misc/NEWS stackless/branches/release25-maint/Misc/RPM/python-2.5.spec stackless/branches/release25-maint/Misc/python-config.in stackless/branches/release25-maint/Modules/_bsddb.c stackless/branches/release25-maint/Modules/_ctypes/ (props changed) stackless/branches/release25-maint/Modules/_ctypes/_ctypes.c stackless/branches/release25-maint/Modules/_ctypes/_ctypes_test.c stackless/branches/release25-maint/Modules/_ctypes/callbacks.c stackless/branches/release25-maint/Modules/_ctypes/libffi/src/powerpc/ffi_darwin.c stackless/branches/release25-maint/Modules/_ctypes/libffi/src/x86/sysv.S stackless/branches/release25-maint/Modules/_ctypes/stgdict.c stackless/branches/release25-maint/Modules/_cursesmodule.c stackless/branches/release25-maint/Modules/_localemodule.c stackless/branches/release25-maint/Modules/_randommodule.c stackless/branches/release25-maint/Modules/_struct.c stackless/branches/release25-maint/Modules/_testcapimodule.c stackless/branches/release25-maint/Modules/arraymodule.c stackless/branches/release25-maint/Modules/binascii.c stackless/branches/release25-maint/Modules/bz2module.c stackless/branches/release25-maint/Modules/cStringIO.c stackless/branches/release25-maint/Modules/collectionsmodule.c stackless/branches/release25-maint/Modules/datetimemodule.c stackless/branches/release25-maint/Modules/itertoolsmodule.c stackless/branches/release25-maint/Modules/main.c stackless/branches/release25-maint/Modules/operator.c stackless/branches/release25-maint/Modules/posixmodule.c stackless/branches/release25-maint/Modules/readline.c stackless/branches/release25-maint/Modules/socketmodule.c stackless/branches/release25-maint/Modules/socketmodule.h stackless/branches/release25-maint/Modules/threadmodule.c stackless/branches/release25-maint/Modules/timemodule.c stackless/branches/release25-maint/Modules/unicodedata.c stackless/branches/release25-maint/Objects/abstract.c stackless/branches/release25-maint/Objects/classobject.c stackless/branches/release25-maint/Objects/complexobject.c stackless/branches/release25-maint/Objects/dictobject.c stackless/branches/release25-maint/Objects/enumobject.c stackless/branches/release25-maint/Objects/exceptions.c stackless/branches/release25-maint/Objects/fileobject.c stackless/branches/release25-maint/Objects/listobject.c stackless/branches/release25-maint/Objects/longobject.c stackless/branches/release25-maint/Objects/obmalloc.c stackless/branches/release25-maint/Objects/setobject.c stackless/branches/release25-maint/Objects/stringobject.c stackless/branches/release25-maint/Objects/typeobject.c stackless/branches/release25-maint/Objects/weakrefobject.c stackless/branches/release25-maint/PC/VC6/_bsddb.dsp stackless/branches/release25-maint/PC/VC6/_ctypes.dsp stackless/branches/release25-maint/PC/VC6/_ctypes_test.dsp stackless/branches/release25-maint/PC/VC6/_elementtree.dsp stackless/branches/release25-maint/PC/VC6/_ssl.mak stackless/branches/release25-maint/PC/VC6/_tkinter.dsp stackless/branches/release25-maint/PC/VC6/bz2.dsp stackless/branches/release25-maint/PC/VC6/pcbuild.dsw stackless/branches/release25-maint/PC/VC6/readme.txt stackless/branches/release25-maint/PC/pyconfig.h stackless/branches/release25-maint/PC/python_nt.rc stackless/branches/release25-maint/PCbuild/_bsddb.vcproj stackless/branches/release25-maint/PCbuild/_ctypes.vcproj stackless/branches/release25-maint/PCbuild/_ctypes_test.vcproj stackless/branches/release25-maint/PCbuild/_elementtree.vcproj stackless/branches/release25-maint/PCbuild/_msi.vcproj stackless/branches/release25-maint/PCbuild/_socket.vcproj stackless/branches/release25-maint/PCbuild/_sqlite3.vcproj stackless/branches/release25-maint/PCbuild/_ssl.mak stackless/branches/release25-maint/PCbuild/_ssl.vcproj stackless/branches/release25-maint/PCbuild/_testcapi.vcproj stackless/branches/release25-maint/PCbuild/_tkinter.vcproj stackless/branches/release25-maint/PCbuild/build_ssl.py stackless/branches/release25-maint/PCbuild/bz2.vcproj stackless/branches/release25-maint/PCbuild/make_buildinfo.vcproj stackless/branches/release25-maint/PCbuild/make_versioninfo.vcproj stackless/branches/release25-maint/PCbuild/pcbuild.sln stackless/branches/release25-maint/PCbuild/pyexpat.vcproj stackless/branches/release25-maint/PCbuild/python.vcproj stackless/branches/release25-maint/PCbuild/python20.wse stackless/branches/release25-maint/PCbuild/pythoncore.vcproj stackless/branches/release25-maint/PCbuild/pythonw.vcproj stackless/branches/release25-maint/PCbuild/select.vcproj stackless/branches/release25-maint/PCbuild/unicodedata.vcproj stackless/branches/release25-maint/PCbuild/w9xpopen.vcproj stackless/branches/release25-maint/PCbuild/winsound.vcproj stackless/branches/release25-maint/PCbuild8/python20.wse stackless/branches/release25-maint/Parser/asdl_c.py stackless/branches/release25-maint/Python/ast.c stackless/branches/release25-maint/Python/ceval.c stackless/branches/release25-maint/Python/compile.c stackless/branches/release25-maint/Python/errors.c stackless/branches/release25-maint/Python/getcopyright.c stackless/branches/release25-maint/Python/import.c stackless/branches/release25-maint/Python/pystate.c stackless/branches/release25-maint/Python/pythonrun.c stackless/branches/release25-maint/Python/structmember.c stackless/branches/release25-maint/Python/sysmodule.c stackless/branches/release25-maint/Python/traceback.c stackless/branches/release25-maint/README stackless/branches/release25-maint/Tools/msi/uuids.py stackless/branches/release25-maint/configure stackless/branches/release25-maint/configure.in stackless/branches/release25-maint/setup.py Log: Merged in changes to the Python release25-maint branch from r52347-54693. Which represent the code as of the 2.5.1c1 release tag. I tested this with Visual C++ Express. The stackless tests passed. The Python tests passed, except for the "test_universal_newlines*" tests in "test_subprocess.py". But this test failure was present before the merge, so the merge can be considered bug free for all intents and purposes. I believe this failure to be a result of using VS8, perhaps if I compiled using PCbuild8 rather than PCbuild, this would have been addressed via some compilation option. Modified: stackless/branches/release25-maint/Demo/parser/unparse.py ============================================================================== --- stackless/branches/release25-maint/Demo/parser/unparse.py (original) +++ stackless/branches/release25-maint/Demo/parser/unparse.py Sat Apr 14 15:02:57 2007 @@ -223,6 +223,9 @@ def _FunctionDef(self, t): self.write("\n") + for deco in t.decorators: + self.fill("@") + self.dispatch(deco) self.fill("def "+t.name + "(") self.dispatch(t.args) self.write(")") Modified: stackless/branches/release25-maint/Doc/README ============================================================================== --- stackless/branches/release25-maint/Doc/README (original) +++ stackless/branches/release25-maint/Doc/README Sat Apr 14 15:02:57 2007 @@ -229,7 +229,7 @@ as long as you don't change or remove the copyright notice: ---------------------------------------------------------------------- -Copyright (c) 2000-2006 Python Software Foundation. +Copyright (c) 2000-2007 Python Software Foundation. All rights reserved. Copyright (c) 2000 BeOpen.com. Modified: stackless/branches/release25-maint/Doc/api/abstract.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/abstract.tex (original) +++ stackless/branches/release25-maint/Doc/api/abstract.tex Sat Apr 14 15:02:57 2007 @@ -810,7 +810,7 @@ the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Count}{PyObject *o, PyObject *value} Return the number of occurrences of \var{value} in \var{o}, that is, return the number of keys for which \code{\var{o}[\var{key}] == \var{value}}. On failure, return \code{-1}. This is equivalent to @@ -824,7 +824,7 @@ expression \samp{\var{value} in \var{o}}. \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Index}{PyObject *o, PyObject *value} Return the first index \var{i} for which \code{\var{o}[\var{i}] == \var{value}}. On error, return \code{-1}. This is equivalent to the Python expression \samp{\var{o}.index(\var{value})}. @@ -874,7 +874,7 @@ \versionadded{2.3} \end{cfuncdesc} -\begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o} +\begin{cfuncdesc}{Py_ssize_t}{PySequence_Fast_GET_SIZE}{PyObject *o} Returns the length of \var{o}, assuming that \var{o} was returned by \cfunction{PySequence_Fast()} and that \var{o} is not \NULL. The size can also be gotten by calling Modified: stackless/branches/release25-maint/Doc/api/concrete.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/concrete.tex (original) +++ stackless/branches/release25-maint/Doc/api/concrete.tex Sat Apr 14 15:02:57 2007 @@ -2082,7 +2082,7 @@ \begin{verbatim} PyObject *key, *value; -int pos = 0; +Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { /* do something interesting with the values... */ @@ -2097,7 +2097,7 @@ \begin{verbatim} PyObject *key, *value; -int pos = 0; +Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { int i = PyInt_AS_LONG(value) + 1; @@ -2879,10 +2879,10 @@ Various date and time objects are supplied by the \module{datetime} module. Before using any of these functions, the header file \file{datetime.h} must be included in your source (note that this is -not include by \file{Python.h}), and macro \cfunction{PyDateTime_IMPORT()} -must be invoked. The macro arranges to put a pointer to a C structure -in a static variable \code{PyDateTimeAPI}, which is used by the following -macros. +not included by \file{Python.h}), and the macro +\cfunction{PyDateTime_IMPORT} must be invoked. The macro puts a +pointer to a C structure into a static variable, +\code{PyDateTimeAPI}, that is used by the following macros. Type-check macros: Modified: stackless/branches/release25-maint/Doc/api/exceptions.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/exceptions.tex (original) +++ stackless/branches/release25-maint/Doc/api/exceptions.tex Sat Apr 14 15:02:57 2007 @@ -328,7 +328,7 @@ default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} \exception{KeyboardInterrupt} exception. If an exception is raised - the error indicator is set and the function returns \code{1}; + the error indicator is set and the function returns \code{-1}; otherwise the function returns \code{0}. The error indicator may or may not be cleared if it was previously set. \end{cfuncdesc} Modified: stackless/branches/release25-maint/Doc/api/memory.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/memory.tex (original) +++ stackless/branches/release25-maint/Doc/api/memory.tex Sat Apr 14 15:02:57 2007 @@ -100,7 +100,9 @@ memory block is resized but is not freed, and the returned pointer is non-\NULL. Unless \var{p} is \NULL, it must have been returned by a previous call to \cfunction{PyMem_Malloc()} or - \cfunction{PyMem_Realloc()}. + \cfunction{PyMem_Realloc()}. If the request fails, + \cfunction{PyMem_Realloc()} returns \NULL{} and \var{p} remains a + valid pointer to the previous memory area. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyMem_Free}{void *p} @@ -124,7 +126,8 @@ \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} Same as \cfunction{PyMem_Realloc()}, but the memory block is resized to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer - cast to \ctype{\var{TYPE}*}. + cast to \ctype{\var{TYPE}*}. On return, \var{p} will be a pointer to + the new memory area, or \NULL{} in the event of failure. \end{cfuncdesc} \begin{cfuncdesc}{void}{PyMem_Del}{void *p} Modified: stackless/branches/release25-maint/Doc/api/newtypes.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/newtypes.tex (original) +++ stackless/branches/release25-maint/Doc/api/newtypes.tex Sat Apr 14 15:02:57 2007 @@ -103,8 +103,6 @@ the value for the \var{methods} argument]{2.3} \end{cfuncdesc} -DL_IMPORT - \begin{cvardesc}{PyObject}{_Py_NoneStruct} Object which is visible in Python as \code{None}. This should only be accessed using the \code{Py_None} macro, which evaluates to a Modified: stackless/branches/release25-maint/Doc/api/utilities.tex ============================================================================== --- stackless/branches/release25-maint/Doc/api/utilities.tex (original) +++ stackless/branches/release25-maint/Doc/api/utilities.tex Sat Apr 14 15:02:57 2007 @@ -930,3 +930,94 @@ If there is an error in the format string, the \exception{SystemError} exception is set and \NULL{} returned. \end{cfuncdesc} + +\section{String conversion and formatting \label{string-formatting}} + +Functions for number conversion and formatted string output. + +\begin{cfuncdesc}{int}{PyOS_snprintf}{char *str, size_t size, + const char *format, \moreargs} +Output not more than \var{size} bytes to \var{str} according to the format +string \var{format} and the extra arguments. See the \UNIX{} man +page \manpage{snprintf}{2}. +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyOS_vsnprintf}{char *str, size_t size, + const char *format, va_list va} +Output not more than \var{size} bytes to \var{str} according to the format +string \var{format} and the variable argument list \var{va}. \UNIX{} +man page \manpage{vsnprintf}{2}. +\end{cfuncdesc} + +\cfunction{PyOS_snprintf} and \cfunction{PyOS_vsnprintf} wrap the +Standard C library functions \cfunction{snprintf()} and +\cfunction{vsnprintf()}. Their purpose is to guarantee consistent +behavior in corner cases, which the Standard C functions do not. + +The wrappers ensure that \var{str}[\var{size}-1] is always +\character{\textbackslash0} upon return. They never write more than +\var{size} bytes (including the trailing \character{\textbackslash0} +into str. Both functions require that \code{\var{str} != NULL}, +\code{\var{size} > 0} and \code{\var{format} != NULL}. + +If the platform doesn't have \cfunction{vsnprintf()} and the buffer +size needed to avoid truncation exceeds \var{size} by more than 512 +bytes, Python aborts with a \var{Py_FatalError}. + +The return value (\var{rv}) for these functions should be interpreted +as follows: + +\begin{itemize} + +\item When \code{0 <= \var{rv} < \var{size}}, the output conversion + was successful and \var{rv} characters were written to \var{str} + (excluding the trailing \character{\textbackslash0} byte at + \var{str}[\var{rv}]). + +\item When \code{\var{rv} >= \var{size}}, the output conversion was + truncated and a buffer with \code{\var{rv} + 1} bytes would have + been needed to succeed. \var{str}[\var{size}-1] is + \character{\textbackslash0} in this case. + +\item When \code{\var{rv} < 0}, ``something bad happened.'' + \var{str}[\var{size}-1] is \character{\textbackslash0} in this case + too, but the rest of \var{str} is undefined. The exact cause of the + error depends on the underlying platform. + +\end{itemize} + +The following functions provide locale-independent string to number +conversions. + +\begin{cfuncdesc}{double}{PyOS_ascii_strtod}{const char *nptr, char **endptr} +Convert a string to a \ctype{double}. This function behaves like the +Standard C function \cfunction{strtod()} does in the C locale. It does +this without changing the current locale, since that would not be +thread-safe. + +\cfunction{PyOS_ascii_strtod} should typically be used for reading +configuration files or other non-user input that should be locale +independent. \versionadded{2.4} + +See the \UNIX{} man page \manpage{strtod}{2} for details. + +\end{cfuncdesc} + +\begin{cfuncdesc}{char *}{PyOS_ascii_formatd}{char *buffer, size_t buf_len, + const char *format, double d} +Convert a \ctype{double} to a string using the \character{.} as the +decimal separator. \var{format} is a \cfunction{printf()}-style format +string specifying the number format. Allowed conversion characters are +\character{e}, \character{E}, \character{f}, \character{F}, +\character{g} and \character{G}. + +The return value is a pointer to \var{buffer} with the converted +string or NULL if the conversion failed. \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{double}{PyOS_ascii_atof}{const char *nptr} +Convert a string to a \ctype{double} in a locale-independent +way. \versionadded{2.4} + +See the \UNIX{} man page \manpage{atof}{2} for details. +\end{cfuncdesc} Modified: stackless/branches/release25-maint/Doc/commontex/boilerplate.tex ============================================================================== --- stackless/branches/release25-maint/Doc/commontex/boilerplate.tex (original) +++ stackless/branches/release25-maint/Doc/commontex/boilerplate.tex Sat Apr 14 15:02:57 2007 @@ -5,5 +5,5 @@ Email: \email{docs at python.org} } -\date{19th September, 2006} % XXX update before final release! +\date{5th April, 2007} % XXX update before final release! \input{patchlevel} % include Python version information Modified: stackless/branches/release25-maint/Doc/commontex/license.tex ============================================================================== --- stackless/branches/release25-maint/Doc/commontex/license.tex (original) +++ stackless/branches/release25-maint/Doc/commontex/license.tex Sat Apr 14 15:02:57 2007 @@ -51,6 +51,7 @@ \linev{2.4.2}{2.4.1}{2005}{PSF}{yes} \linev{2.4.3}{2.4.2}{2006}{PSF}{yes} \linev{2.5}{2.4}{2006}{PSF}{yes} + \linev{2.5.1}{2.5}{2007}{PSF}{yes} \end{tablev} \note{GPL-compatible doesn't mean that we're distributing Modified: stackless/branches/release25-maint/Doc/dist/dist.tex ============================================================================== --- stackless/branches/release25-maint/Doc/dist/dist.tex (original) +++ stackless/branches/release25-maint/Doc/dist/dist.tex Sat Apr 14 15:02:57 2007 @@ -692,7 +692,7 @@ \begin{tableii}{l|l}{code}{Provides Expression}{Explanation} \lineii{mypkg} {Provide \code{mypkg}, using the distribution version} - \lineii{mypkg (1.1} {Provide \code{mypkg} version 1.1, regardless of the + \lineii{mypkg (1.1)} {Provide \code{mypkg} version 1.1, regardless of the distribution version} \end{tableii} Modified: stackless/branches/release25-maint/Doc/ext/newtypes.tex ============================================================================== --- stackless/branches/release25-maint/Doc/ext/newtypes.tex (original) +++ stackless/branches/release25-maint/Doc/ext/newtypes.tex Sat Apr 14 15:02:57 2007 @@ -489,7 +489,6 @@ garbage collection, there are calls that can be made to ``untrack'' the object from garbage collection, however, these calls are advanced and not covered here.} -\item \end{itemize} @@ -930,6 +929,102 @@ collection. Most extensions will use the versions automatically provided. +\subsection{Subclassing other types} + +It is possible to create new extension types that are derived from existing +types. It is easiest to inherit from the built in types, since an extension +can easily use the \class{PyTypeObject} it needs. It can be difficult to +share these \class{PyTypeObject} structures between extension modules. + +In this example we will create a \class{Shoddy} type that inherits from +the builtin \class{list} type. The new type will be completely compatible +with regular lists, but will have an additional \method{increment()} method +that increases an internal counter. + +\begin{verbatim} +>>> import shoddy +>>> s = shoddy.Shoddy(range(3)) +>>> s.extend(s) +>>> print len(s) +6 +>>> print s.increment() +1 +>>> print s.increment() +2 +\end{verbatim} + +\verbatiminput{shoddy.c} + +As you can see, the source code closely resembles the \class{Noddy} examples in previous +sections. We will break down the main differences between them. + +\begin{verbatim} +typedef struct { + PyListObject list; + int state; +} Shoddy; +\end{verbatim} + +The primary difference for derived type objects is that the base type's +object structure must be the first value. The base type will already +include the \cfunction{PyObject_HEAD} at the beginning of its structure. + +When a Python object is a \class{Shoddy} instance, its \var{PyObject*} pointer +can be safely cast to both \var{PyListObject*} and \var{Shoddy*}. + +\begin{verbatim} +static int +Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds) +{ + if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0) + return -1; + self->state = 0; + return 0; +} +\end{verbatim} + +In the \member{__init__} method for our type, we can see how to call through +to the \member{__init__} method of the base type. + +This pattern is important when writing a type with custom \member{new} and +\member{dealloc} methods. The \member{new} method should not actually create the +memory for the object with \member{tp_alloc}, that will be handled by +the base class when calling its \member{tp_new}. + +When filling out the \cfunction{PyTypeObject} for the \class{Shoddy} type, +you see a slot for \cfunction{tp_base}. Due to cross platform compiler +issues, you can't fill that field directly with the \cfunction{PyList_Type}; +it can be done later in the module's \cfunction{init} function. + +\begin{verbatim} +PyMODINIT_FUNC +initshoddy(void) +{ + PyObject *m; + + ShoddyType.tp_base = &PyList_Type; + if (PyType_Ready(&ShoddyType) < 0) + return; + + m = Py_InitModule3("shoddy", NULL, "Shoddy module"); + if (m == NULL) + return; + + Py_INCREF(&ShoddyType); + PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType); +} +\end{verbatim} + +Before calling \cfunction{PyType_Ready}, the type structure must have the +\member{tp_base} slot filled in. When we are deriving a new type, it is +not necessary to fill out the \member{tp_alloc} slot with +\cfunction{PyType_GenericNew} -- the allocate function from the base type +will be inherited. + +After that, calling \cfunction{PyType_Ready} and adding the type object +to the module is the same as with the basic \class{Noddy} examples. + + \section{Type Methods \label{dnt-type-methods}} Modified: stackless/branches/release25-maint/Doc/inst/inst.tex ============================================================================== --- stackless/branches/release25-maint/Doc/inst/inst.tex (original) +++ stackless/branches/release25-maint/Doc/inst/inst.tex Sat Apr 14 15:02:57 2007 @@ -632,7 +632,7 @@ installation base directory when you run the setup script. For example, \begin{verbatim} -python setup.py --install-base=/tmp +python setup.py install --install-base=/tmp \end{verbatim} would install pure modules to \filevar{/tmp/python/lib} in the first Modified: stackless/branches/release25-maint/Doc/lib/emailgenerator.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/emailgenerator.tex (original) +++ stackless/branches/release25-maint/Doc/lib/emailgenerator.tex Sat Apr 14 15:02:57 2007 @@ -33,7 +33,7 @@ line. This is the only guaranteed portable way to avoid having such 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} +{http://www.jwz.org/doc/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{} mailbox format files. Modified: stackless/branches/release25-maint/Doc/lib/libasyncore.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libasyncore.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libasyncore.tex Sat Apr 14 15:02:57 2007 @@ -198,9 +198,11 @@ \end{methoddesc} \begin{methoddesc}{bind}{address} - Bind the socket to \var{address}. The socket must not already - be bound. (The format of \var{address} depends on the address - family --- see above.) + Bind the socket to \var{address}. The socket must not already be + bound. (The format of \var{address} depends on the address family + --- see above.) To mark the socket as re-usable (setting the + \constant{SO_REUSEADDR} option), call the \class{dispatcher} + object's \method{set_reuse_addr()} method. \end{methoddesc} \begin{methoddesc}{accept}{} Modified: stackless/branches/release25-maint/Doc/lib/libbase64.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libbase64.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libbase64.tex Sat Apr 14 15:02:57 2007 @@ -21,7 +21,7 @@ decoding to and from file-like objects as well as strings, but only using the Base64 standard alphabet. -The modern interface provides: +The modern interface, which was introduced in Python 2.4, provides: \begin{funcdesc}{b64encode}{s\optional{, altchars}} Encode a string use Base64. Modified: stackless/branches/release25-maint/Doc/lib/libbsddb.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libbsddb.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libbsddb.tex Sat Apr 14 15:02:57 2007 @@ -2,7 +2,6 @@ Interface to Berkeley DB library} \declaremodule{extension}{bsddb} - \platform{Unix, Windows} \modulesynopsis{Interface to Berkeley DB database library} \sectionauthor{Skip Montanaro}{skip at mojam.com} @@ -16,7 +15,7 @@ \function{pickle.dumps()}. The \module{bsddb} module requires a Berkeley DB library version from -3.3 thru 4.4. +3.3 thru 4.5. \begin{seealso} \seeurl{http://pybsddb.sourceforge.net/} @@ -46,10 +45,10 @@ instances. \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{, - mode\optional{, bsize\optional{, + mode\optional{, pgsize\optional{, ffactor\optional{, nelem\optional{, - cachesize\optional{, hash\optional{, - lorder}}}}}}}}} + cachesize\optional{, lorder\optional{, + hflags}}}}}}}}} Open the hash format file named \var{filename}. Files never intended to be preserved on disk may be created by passing \code{None} as the \var{filename}. The optional @@ -80,7 +79,7 @@ \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{, rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{, -reclen\optional{, bval\optional{, bfname}}}}}}}}}} +rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}} Open a DB record format file named \var{filename}. Files never intended to be preserved on disk may be created by passing \code{None} as the Modified: stackless/branches/release25-maint/Doc/lib/libbz2.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libbz2.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libbz2.tex Sat Apr 14 15:02:57 2007 @@ -90,10 +90,10 @@ \begin{methoddesc}[BZ2File]{seek}{offset\optional{, whence}} Move to new file position. Argument \var{offset} is a byte count. Optional -argument \var{whence} defaults to \code{0} (offset from start of file, -offset should be \code{>= 0}); other values are \code{1} (move relative to -current position, positive or negative), and \code{2} (move relative to end -of file, usually negative, although many platforms allow seeking beyond +argument \var{whence} defaults to \code{os.SEEK_SET} or \code{0} (offset from start of file; +offset should be \code{>= 0}); other values are \code{os.SEEK_CUR} or \code{1} (move relative to +current position; offset can be positive or negative), and \code{os.SEEK_END} or \code{2} (move relative to end +of file; offset is usually negative, although many platforms allow seeking beyond the end of a file). Note that seeking of bz2 files is emulated, and depending on the parameters Modified: stackless/branches/release25-maint/Doc/lib/libcollections.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libcollections.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libcollections.tex Sat Apr 14 15:02:57 2007 @@ -16,7 +16,7 @@ \subsection{\class{deque} objects \label{deque-objects}} \begin{funcdesc}{deque}{\optional{iterable}} - Returns a new deque objected initialized left-to-right (using + Returns a new deque object initialized left-to-right (using \method{append()}) with data from \var{iterable}. If \var{iterable} is not specified, the new deque is empty. @@ -311,16 +311,20 @@ When a letter is first encountered, it is missing from the mapping, so the \member{default_factory} function calls \function{int()} to supply a default count of zero. The increment operation then builds up the count for each -letter. This technique makes counting simpler and faster than an equivalent -technique using \method{dict.get()}: +letter. -\begin{verbatim} ->>> d = {} ->>> for k in s: - d[k] = d.get(k, 0) + 1 +The function \function{int()} which always returns zero is just a special +case of constant functions. A faster and more flexible way to create +constant functions is to use \function{itertools.repeat()} which can supply +any constant value (not just zero): ->>> d.items() -[('i', 4), ('p', 2), ('s', 4), ('m', 1)] +\begin{verbatim} +>>> def constant_factory(value): +... return itertools.repeat(value).next +>>> d = defaultdict(constant_factory('')) +>>> d.update(name='John', action='ran') +>>> '%(name)s %(action)s to %(object)s' % d +'John ran to ' \end{verbatim} Setting the \member{default_factory} to \class{set} makes the Modified: stackless/branches/release25-maint/Doc/lib/libcommands.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libcommands.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libcommands.tex Sat Apr 14 15:02:57 2007 @@ -12,6 +12,11 @@ return any output generated by the command and, optionally, the exit status. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results. Using the +\module{subprocess} module is preferable to using the \module{commands} +module. + The \module{commands} module defines the following functions: @@ -51,3 +56,7 @@ >>> commands.getstatus('/bin/ls') '-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls' \end{verbatim} + +\begin{seealso} + \seemodule{subprocess}{Module for spawning and managing subprocesses.} +\end{seealso} Modified: stackless/branches/release25-maint/Doc/lib/libcsv.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libcsv.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libcsv.tex Sat Apr 14 15:02:57 2007 @@ -345,6 +345,7 @@ \begin{memberdesc}[csv reader]{line_num} The number of lines read from the source iterator. This is not the same as the number of records returned, as records can span multiple lines. + \versionadded{2.5} \end{memberdesc} Modified: stackless/branches/release25-maint/Doc/lib/libctypes.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libctypes.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libctypes.tex Sat Apr 14 15:02:57 2007 @@ -1219,7 +1219,7 @@ 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: +As we can easily check, our array is sorted now: \begin{verbatim} >>> for i in ia: print i, ... @@ -1821,7 +1821,7 @@ \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) +>>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) >>>\end{verbatim} @@ -1848,7 +1848,7 @@ Here is the wrapping with \code{ctypes}: \begin{quote} -\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll +\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError >>> from ctypes.wintypes import BOOL, HWND, RECT >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) >>> paramflags = (1, "hwnd"), (2, "lprect") @@ -2085,10 +2085,10 @@ the type. Some types accept other objects as well. \end{methoddesc} -\begin{methoddesc}{in_dll}{name, library} +\begin{methoddesc}{in_dll}{library, name} 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. +\var{library} is the loaded shared library. \end{methoddesc} Common instance variables of ctypes data types: @@ -2299,12 +2299,10 @@ or error information for a function or method call. \end{classdesc*} -\code{py{\_}object} : classdesc* -\begin{quote} - -Represents the C \code{PyObject *} datatype. Calling this with an -without an argument creates a \code{NULL} \code{PyObject *} pointer. -\end{quote} +\begin{classdesc*}{py_object} +Represents the C \code{PyObject *} datatype. Calling this without an +argument creates a \code{NULL} \code{PyObject *} pointer. +\end{classdesc*} The \code{ctypes.wintypes} module provides quite some other Windows specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}. @@ -2440,5 +2438,6 @@ \subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}} -XXX +Not yet written - please see section~\ref{ctypes-pointers}, pointers and +section~\ref{ctypes-arrays}, arrays in the tutorial. Modified: stackless/branches/release25-maint/Doc/lib/libdbhash.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libdbhash.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libdbhash.tex Sat Apr 14 15:02:57 2007 @@ -2,7 +2,6 @@ DBM-style interface to the BSD database library} \declaremodule{standard}{dbhash} - \platform{Unix, Windows} \modulesynopsis{DBM-style interface to the BSD database library.} \sectionauthor{Fred L. Drake, Jr.}{fdrake at acm.org} Modified: stackless/branches/release25-maint/Doc/lib/libfnmatch.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libfnmatch.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libfnmatch.tex Sat Apr 14 15:02:57 2007 @@ -36,6 +36,19 @@ require a case-sensitive comparison regardless of whether that's standard for your operating system, use \function{fnmatchcase()} instead. + +This example will print all file names in the current directory with the +extension \code{.txt}: + +\begin{verbatim} +import fnmatch +import os + +for file in os.listdir('.'): + if fnmatch.fnmatch(file, '*.txt'): + print file +\end{verbatim} + \end{funcdesc} \begin{funcdesc}{fnmatchcase}{filename, pattern} @@ -50,6 +63,24 @@ \versionadded{2.2} \end{funcdesc} +\begin{funcdesc}{translate}{pattern} +Return the shell-style \var{pattern} converted to a regular +expression. + +Example: + +\begin{verbatim} +>>> import fnmatch, re +>>> +>>> regex = fnmatch.translate('*.txt') +>>> regex +'.*\\.txt$' +>>> reobj = re.compile(regex) +>>> print reobj.match('foobar.txt') +<_sre.SRE_Match object at 0x...> +\end{verbatim} +\end{funcdesc} + \begin{seealso} \seemodule{glob}{\UNIX{} shell-style path expansion.} \end{seealso} Modified: stackless/branches/release25-maint/Doc/lib/libfuncs.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libfuncs.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libfuncs.tex Sat Apr 14 15:02:57 2007 @@ -237,11 +237,11 @@ \code{del \var{x}.\var{foobar}}. \end{funcdesc} -\begin{funcdesc}{dict}{\optional{mapping-or-sequence}} +\begin{funcdesc}{dict}{\optional{arg}} Return a new dictionary initialized from an optional positional argument or from a set of keyword arguments. If no arguments are given, return a new empty dictionary. - If the positional argument is a mapping object, return a dictionary + If the positional argument \var{arg} is a mapping object, return a dictionary mapping the same keys to the same values as does the mapping object. Otherwise the positional argument must be a sequence, a container that supports iteration, or an iterator object. The elements of the argument @@ -414,18 +414,18 @@ \versionadded{2.2} \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} +\begin{funcdesc}{filter}{function, iterable} + Construct a list from those elements of \var{iterable} for which + \var{function} returns true. \var{iterable} may be either a sequence, a + container which supports iteration, or an iterator, If \var{iterable} 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. + \var{iterable} 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 - not \code{None} and \code{[item for item in \var{list} if item]} if + Note that \code{filter(function, \var{iterable})} is equivalent to + \code{[item for item in \var{iterable} if function(item)]} if function is + not \code{None} and \code{[item for item in \var{iterable} if item]} if function is \code{None}. \end{funcdesc} @@ -548,8 +548,9 @@ \begin{funcdesc}{isinstance}{object, classinfo} Return true if the \var{object} argument is an instance of the \var{classinfo} argument, or of a (direct or indirect) subclass - thereof. Also return true if \var{classinfo} is a type object and - \var{object} is an object of that type. If \var{object} is not a + thereof. Also return true if \var{classinfo} is a type object + (new-style class) and \var{object} is an object of that type or of a + (direct or indirect) subclass thereof. If \var{object} is not a class instance or an object of the given type, the function always returns false. If \var{classinfo} is neither a class object nor a type object, it may be a tuple of class or type objects, or may @@ -591,12 +592,12 @@ may be a sequence (string, tuple or list) or a mapping (dictionary). \end{funcdesc} -\begin{funcdesc}{list}{\optional{sequence}} +\begin{funcdesc}{list}{\optional{iterable}} Return a list whose items are the same and in the same order as - \var{sequence}'s items. \var{sequence} may be either a sequence, a + \var{iterable}'s items. \var{iterable} may be either a sequence, a container that supports iteration, or an iterator object. If - \var{sequence} is already a list, a copy is made and returned, - similar to \code{\var{sequence}[:]}. For instance, + \var{iterable} is already a list, a copy is made and returned, + similar to \code{\var{iterable}[:]}. For instance, \code{list('abc')} returns \code{['a', 'b', 'c']} and \code{list( (1, 2, 3) )} returns \code{[1, 2, 3]}. If no argument is given, returns a new empty list, \code{[]}. @@ -622,22 +623,22 @@ are given, returns \code{0L}. \end{funcdesc} -\begin{funcdesc}{map}{function, list, ...} - Apply \var{function} to every item of \var{list} and return a list - of the results. If additional \var{list} arguments are passed, +\begin{funcdesc}{map}{function, iterable, ...} + Apply \var{function} to every item of \var{iterable} and return a list + of the results. If additional \var{iterable} arguments are passed, \var{function} must take that many arguments and is applied to the - items of all lists in parallel; if a list is shorter than another it + items from all iterables in parallel. If one iterable is shorter than another it is assumed to be extended with \code{None} items. If \var{function} is \code{None}, the identity function is assumed; if there are - multiple list arguments, \function{map()} returns a list consisting - of tuples containing the corresponding items from all lists (a kind - of transpose operation). The \var{list} arguments may be any kind - of sequence; the result is always a list. + multiple arguments, \function{map()} returns a list consisting + of tuples containing the corresponding items from all iterables (a kind + of transpose operation). The \var{iterable} arguments may be a sequence + or any iterable object; the result is always a list. \end{funcdesc} -\begin{funcdesc}{max}{s\optional{, args...}\optional{key}} - With a single argument \var{s}, return the largest item of a - non-empty sequence (such as a string, tuple or list). With more +\begin{funcdesc}{max}{iterable\optional{, args...}\optional{key}} + With a single argument \var{iterable}, return the largest item of a + non-empty iterable (such as a string, tuple or list). With more than one argument, return the largest of the arguments. The optional \var{key} argument specifies a one-argument ordering @@ -647,16 +648,16 @@ \versionchanged[Added support for the optional \var{key} argument]{2.5} \end{funcdesc} -\begin{funcdesc}{min}{s\optional{, args...}\optional{key}} - With a single argument \var{s}, return the smallest item of a - non-empty sequence (such as a string, tuple or list). With more +\begin{funcdesc}{min}{iterable\optional{, args...}\optional{key}} + With a single argument \var{iterable}, return the smallest item of a + non-empty iterable (such as a string, tuple or list). With more than one argument, return the smallest of the arguments. The optional \var{key} argument specifies a one-argument ordering function like that used for \method{list.sort()}. The \var{key} argument, if supplied, must be in keyword form (for example, \samp{min(a,b,c,key=func)}). - \versionchanged[Added support for the optional \var{key} argument]{2.5} + \versionchanged[Added support for the optional \var{key} argument]{2.5} \end{funcdesc} \begin{funcdesc}{object}{} @@ -871,17 +872,17 @@ line editing and history features. \end{funcdesc} -\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}} +\begin{funcdesc}{reduce}{function, iterable\optional{, initializer}} Apply \var{function} of two arguments cumulatively to the items of - \var{sequence}, from left to right, so as to reduce the sequence to + \var{iterable}, from left to right, so as to reduce the iterable to a single value. For example, \code{reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])} calculates \code{((((1+2)+3)+4)+5)}. The left argument, \var{x}, is the accumulated value and the right argument, \var{y}, - is the update value from the \var{sequence}. If the optional + is the update value from the \var{iterable}. If the optional \var{initializer} is present, it is placed before the items of the - sequence in the calculation, and serves as a default when the - sequence is empty. If \var{initializer} is not given and - \var{sequence} contains only one item, the first item is returned. + iterable in the calculation, and serves as a default when the + iterable is empty. If \var{initializer} is not given and + \var{iterable} contains only one item, the first item is returned. \end{funcdesc} \begin{funcdesc}{reload}{module} @@ -1087,11 +1088,11 @@ string, \code{''}. \end{funcdesc} -\begin{funcdesc}{sum}{sequence\optional{, start}} - Sums \var{start} and the items of a \var{sequence}, from left to - right, and returns the total. \var{start} defaults to \code{0}. - The \var{sequence}'s items are normally numbers, and are not allowed - to be strings. The fast, correct way to concatenate sequence of +\begin{funcdesc}{sum}{iterable\optional{, start}} + Sums \var{start} and the items of an \var{iterable} from left to + right and returns the total. \var{start} defaults to \code{0}. + The \var{iterable}'s items are normally numbers, and are not allowed + to be strings. The fast, correct way to concatenate a sequence of strings is by calling \code{''.join(\var{sequence})}. Note that \code{sum(range(\var{n}), \var{m})} is equivalent to \code{reduce(operator.add, range(\var{n}), \var{m})} @@ -1121,11 +1122,11 @@ \versionadded{2.2} \end{funcdesc} -\begin{funcdesc}{tuple}{\optional{sequence}} +\begin{funcdesc}{tuple}{\optional{iterable}} Return a tuple whose items are the same and in the same order as - \var{sequence}'s items. \var{sequence} may be a sequence, a + \var{iterable}'s items. \var{iterable} may be a sequence, a container that supports iteration, or an iterator object. - If \var{sequence} is already a tuple, it + If \var{iterable} is already a tuple, it is returned unchanged. For instance, \code{tuple('abc')} returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns \code{(1, 2, 3)}. If no argument is given, returns a new empty Modified: stackless/branches/release25-maint/Doc/lib/libfunctools.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libfunctools.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libfunctools.tex Sat Apr 14 15:02:57 2007 @@ -53,15 +53,16 @@ \begin{funcdesc}{update_wrapper} {wrapper, wrapped\optional{, assigned}\optional{, updated}} -Update a wrapper function to look like the wrapped function. The optional -arguments are tuples to specify which attributes of the original +Update a \var{wrapper} function to look like the \var{wrapped} function. +The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function. The default values for these arguments are the module level constants -\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's name, -module and documentation string) and \var{WRAPPER_UPDATES} (which -updates the wrapper function's instance dictionary). +\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's +\var{__name__}, \var{__module__} and \var{__doc__}, the documentation string) +and \var{WRAPPER_UPDATES} (which updates the wrapper function's \var{__dict__}, +i.e. the instance dictionary). The main intended use for this function is in decorator functions which wrap the decorated function and return the wrapper. If the @@ -85,6 +86,7 @@ ... >>> @my_decorator ... def example(): + ... """Docstring""" ... print 'Called example function' ... >>> example() @@ -92,9 +94,12 @@ Called example function >>> example.__name__ 'example' + >>> example.__doc__ + 'Docstring' \end{verbatim} Without the use of this decorator factory, the name of the example -function would have been \code{'wrapper'}. +function would have been \code{'wrapper'}, and the docstring of the +original \function{example()} would have been lost. \end{funcdesc} Modified: stackless/branches/release25-maint/Doc/lib/libgetopt.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libgetopt.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libgetopt.tex Sat Apr 14 15:02:57 2007 @@ -126,8 +126,9 @@ def main(): try: opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) - except getopt.GetoptError: + except getopt.GetoptError, err: # print help information and exit: + print str(err) # will print something like "option -a not recognized" usage() sys.exit(2) output = None @@ -135,11 +136,13 @@ for o, a in opts: if o == "-v": verbose = True - if o in ("-h", "--help"): + elif o in ("-h", "--help"): usage() sys.exit() - if o in ("-o", "--output"): + elif o in ("-o", "--output"): output = a + else: + assert False, "unhandled option" # ... if __name__ == "__main__": Modified: stackless/branches/release25-maint/Doc/lib/libgettext.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libgettext.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libgettext.tex Sat Apr 14 15:02:57 2007 @@ -102,9 +102,9 @@ return \var{plural} otherwise. The Plural formula is taken from the catalog header. It is a C or -Python expression that has a free variable n; the expression evaluates +Python expression that has a free variable \var{n}; the expression evaluates to the index of the plural in the catalog. See the GNU gettext -documentation for the precise syntax to be used in .po files, and the +documentation for the precise syntax to be used in \file{.po} files and the formulas for a variety of languages. \versionadded{2.3} Modified: stackless/branches/release25-maint/Doc/lib/libheapq.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libheapq.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libheapq.tex Sat Apr 14 15:02:57 2007 @@ -76,14 +76,14 @@ >>> for item in data: ... heappush(heap, item) ... ->>> sorted = [] +>>> ordered = [] >>> while heap: -... sorted.append(heappop(heap)) +... ordered.append(heappop(heap)) ... ->>> print sorted +>>> print ordered [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> data.sort() ->>> print data == sorted +>>> print data == ordered True >>> \end{verbatim} Modified: stackless/branches/release25-maint/Doc/lib/libimageop.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libimageop.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libimageop.tex Sat Apr 14 15:02:57 2007 @@ -19,7 +19,7 @@ \begin{funcdesc}{crop}{image, psize, width, height, x0, y0, x1, y1} -Return the selected part of \var{image}, which should by +Return the selected part of \var{image}, which should be \var{width} by \var{height} in size and consist of pixels of \var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like the \function{gl.lrectread()} parameters, i.e.\ the boundary is Modified: stackless/branches/release25-maint/Doc/lib/libitertools.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libitertools.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libitertools.tex Sat Apr 14 15:02:57 2007 @@ -474,8 +474,8 @@ return izip(mapping.iterkeys(), mapping.itervalues()) def nth(iterable, n): - "Returns the nth item" - return list(islice(iterable, n, n+1)) + "Returns the nth item or raise IndexError" + return list(islice(iterable, n, n+1))[0] def all(seq, pred=None): "Returns True if pred(x) is true for every element in the iterable" @@ -539,5 +539,8 @@ "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')" return izip(*[chain(iterable, repeat(padvalue, n-1))]*n) +def reverse_map(d): + "Return a new dict with swapped keys and values" + return dict(izip(d.itervalues(), d)) \end{verbatim} Modified: stackless/branches/release25-maint/Doc/lib/liblocale.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/liblocale.tex (original) +++ stackless/branches/release25-maint/Doc/lib/liblocale.tex Sat Apr 14 15:02:57 2007 @@ -481,7 +481,7 @@ locale settings. When a call to the \function{setlocale()} function changes the \constant{LC_CTYPE} settings, the variables \code{string.lowercase}, \code{string.uppercase} and -\code{string.letters} are recalculated. Note that this code that uses +\code{string.letters} are recalculated. Note that code that uses these variable through `\keyword{from} ... \keyword{import} ...', e.g.\ \code{from string import letters}, is not affected by subsequent \function{setlocale()} calls. Modified: stackless/branches/release25-maint/Doc/lib/liblogging.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/liblogging.tex (original) +++ stackless/branches/release25-maint/Doc/lib/liblogging.tex Sat Apr 14 15:02:57 2007 @@ -516,8 +516,10 @@ \end{methoddesc} \begin{methoddesc}{findCaller}{} -Finds the caller's source filename and line number. Returns the filename -and line number as a 2-element tuple. +Finds the caller's source filename and line number. Returns the filename, +line number and function name as a 3-element tuple. +\versionchanged[The function name was added. In earlier versions, the +filename and line number were returned as a 2-element tuple.]{2.5} \end{methoddesc} \begin{methoddesc}{handle}{record} @@ -528,8 +530,8 @@ \method{filter()}. \end{methoddesc} -\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info, - func, extra} +\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info + \optional{, func, extra}} This is a factory method which can be overridden in subclasses to create specialized \class{LogRecord} instances. \versionchanged[\var{func} and \var{extra} were added]{2.5} @@ -1397,6 +1399,9 @@ (if available).} \lineii{\%(created)f} {Time when the \class{LogRecord} was created (as returned by \function{time.time()}).} +\lineii{\%(relativeCreated)d} {Time in milliseconds when the LogRecord was + created, relative to the time the logging module was + loaded.} \lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord} was created. By default this is of the form ``2003-07-08 16:49:45,896'' (the numbers after the @@ -1479,7 +1484,7 @@ information to be logged. \begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args, - exc_info} + exc_info \optional{, func}} Returns an instance of \class{LogRecord} initialized with interesting information. The \var{name} is the logger name; \var{lvl} is the numeric level; \var{pathname} is the absolute pathname of the source @@ -1489,7 +1494,9 @@ which, together with \var{msg}, makes up the user message; and \var{exc_info} is the exception tuple obtained by calling \function{sys.exc_info() }(or \constant{None}, if no exception information -is available). +is available). The \var{func} is the name of the function from which the +logging call was made. If not specified, it defaults to \var{None}. +\versionchanged[\var{func} was added]{2.5} \end{classdesc} \begin{methoddesc}{getMessage}{} Modified: stackless/branches/release25-maint/Doc/lib/libmailbox.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libmailbox.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libmailbox.tex Sat Apr 14 15:02:57 2007 @@ -25,22 +25,29 @@ A mailbox, which may be inspected and modified. \end{classdesc*} +The \class{Mailbox} class defines an interface and +is not intended to be instantiated. Instead, format-specific +subclasses should inherit from \class{Mailbox} and your code +should instantiate a particular subclass. + The \class{Mailbox} interface is dictionary-like, with small keys -corresponding to messages. Keys are issued by the \class{Mailbox} instance -with which they will be used and are only meaningful to that \class{Mailbox} -instance. A key continues to identify a message even if the corresponding -message is modified, such as by replacing it with another message. Messages may -be added to a \class{Mailbox} instance using the set-like method -\method{add()} and removed using a \code{del} statement or the set-like methods -\method{remove()} and \method{discard()}. +corresponding to messages. Keys are issued by the \class{Mailbox} +instance with which they will be used and are only meaningful to that +\class{Mailbox} instance. A key continues to identify a message even +if the corresponding message is modified, such as by replacing it with +another message. + +Messages may be added to a \class{Mailbox} instance using the set-like +method \method{add()} and removed using a \code{del} statement or the +set-like methods \method{remove()} and \method{discard()}. \class{Mailbox} interface semantics differ from dictionary semantics in some -noteworthy ways. Each time a message is requested, a new representation -(typically a \class{Message} instance) is generated, based upon the current -state of the mailbox. Similarly, when a message is added to a \class{Mailbox} -instance, the provided message representation's contents are copied. In neither -case is a reference to the message representation kept by the \class{Mailbox} -instance. +noteworthy ways. Each time a message is requested, a new +representation (typically a \class{Message} instance) is generated +based upon the current state of the mailbox. Similarly, when a message +is added to a \class{Mailbox} instance, the provided message +representation's contents are copied. In neither case is a reference +to the message representation kept by the \class{Mailbox} instance. The default \class{Mailbox} iterator iterates over message representations, not keys as the default dictionary iterator does. Moreover, modification of a @@ -51,9 +58,18 @@ \exception{KeyError} exception if the corresponding message is subsequently removed. -\class{Mailbox} itself is intended to define an interface and to be inherited -from by format-specific subclasses but is not intended to be instantiated. -Instead, you should instantiate a subclass. +\begin{notice}[warning] +Be very cautious when modifying mailboxes that might be +simultaneously changed by some other process. The safest mailbox +format to use for such tasks is Maildir; try to avoid using +single-file formats such as mbox for concurrent writing. If you're +modifying a mailbox, you +\emph{must} lock it by calling the \method{lock()} and +\method{unlock()} methods \emph{before} reading any messages in the file +or making any changes by adding or deleting a message. Failing to +lock the mailbox runs the risk of losing messages or corrupting the entire +mailbox. +\end{notice} \class{Mailbox} instances have the following methods: @@ -202,15 +218,16 @@ \begin{methoddesc}{flush}{} Write any pending changes to the filesystem. For some \class{Mailbox} -subclasses, changes are always written immediately and this method does -nothing. +subclasses, changes are always written immediately and \method{flush()} does +nothing, but you should still make a habit of calling this method. \end{methoddesc} \begin{methoddesc}{lock}{} Acquire an exclusive advisory lock on the mailbox so that other processes know not to modify it. An \exception{ExternalClashError} is raised if the lock is not available. The particular locking mechanisms used depend upon the mailbox -format. +format. You should \emph{always} lock the mailbox before making any +modifications to its contents. \end{methoddesc} \begin{methoddesc}{unlock}{} @@ -1373,36 +1390,55 @@ \begin{verbatim} import mailbox destination = mailbox.MH('~/Mail') +destination.lock() for message in mailbox.Babyl('~/RMAIL'): destination.add(MHMessage(message)) +destination.flush() +destination.unlock() \end{verbatim} -An example of sorting mail from numerous mailing lists, being careful to avoid -mail corruption due to concurrent modification by other programs, mail loss due -to interruption of the program, or premature termination due to malformed -messages in the mailbox: +This example sorts mail from several mailing lists into different +mailboxes, being careful to avoid mail corruption due to concurrent +modification by other programs, mail loss due to interruption of the +program, or premature termination due to malformed messages in the +mailbox: \begin{verbatim} import mailbox import email.Errors + list_names = ('python-list', 'python-dev', 'python-bugs') + boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names) -inbox = mailbox.Maildir('~/Maildir', None) +inbox = mailbox.Maildir('~/Maildir', factory=None) + for key in inbox.iterkeys(): try: message = inbox[key] except email.Errors.MessageParseError: continue # The message is malformed. Just leave it. + for name in list_names: list_id = message['list-id'] if list_id and name in list_id: + # Get mailbox to use box = boxes[name] + + # Write copy to disk before removing original. + # If there's a crash, you might duplicate a message, but + # that's better than losing a message completely. box.lock() box.add(message) - box.flush() # Write copy to disk before removing original. + box.flush() box.unlock() + + # Remove original message + inbox.lock() inbox.discard(key) + inbox.flush() + inbox.unlock() break # Found destination, so stop looking. + for box in boxes.itervalues(): box.close() \end{verbatim} Modified: stackless/branches/release25-maint/Doc/lib/libmmap.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libmmap.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libmmap.tex Sat Apr 14 15:02:57 2007 @@ -140,8 +140,9 @@ \begin{methoddesc}{seek}{pos\optional{, whence}} Set the file's current position. \var{whence} argument is optional - and defaults to \code{0} (absolute file positioning); other values - are \code{1} (seek relative to the current position) and \code{2} + and defaults to \code{os.SEEK_SET} or \code{0} (absolute file + positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek + relative to the current position) and \code{os.SEEK_END} or \code{2} (seek relative to the file's end). \end{methoddesc} Modified: stackless/branches/release25-maint/Doc/lib/libmsilib.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libmsilib.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libmsilib.tex Sat Apr 14 15:02:57 2007 @@ -344,8 +344,8 @@ \subsection{Features\label{features}} \begin{classdesc}{Feature}{database, id, title, desc, display\optional{, - level=1\optional{, parent\optional\{, directory\optional{, - attributes=0}}}} + level=1\optional{, parent\optional{, directory\optional{, + attributes=0}}}}} Add a new record to the \code{Feature} table, using the values \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display}, Modified: stackless/branches/release25-maint/Doc/lib/libos.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libos.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libos.tex Sat Apr 14 15:02:57 2007 @@ -361,6 +361,10 @@ errors), \code{None} is returned. Availability: Macintosh, \UNIX, Windows. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results; using that module +is preferable to using this function. + \versionchanged[This function worked unreliably under Windows in earlier versions of Python. This was due to the use of the \cfunction{_popen()} function from the libraries provided with @@ -375,8 +379,13 @@ Availability: Macintosh, \UNIX, Windows. \end{funcdesc} +There are a number of different \function{popen*()} functions that +provide slightly different ways to create subprocesses. Note that the +\module{subprocess} module is easier to use and more powerful; +consider using that module before writing code using the +lower-level \function{popen*()} functions. -For each of the following \function{popen()} variants, if \var{bufsize} is +For each of the \function{popen*()} variants, if \var{bufsize} is specified, it specifies the buffer size for the I/O pipes. \var{mode}, if provided, should be the string \code{'b'} or \code{'t'}; on Windows this is needed to determine whether the file @@ -1545,7 +1554,13 @@ \funcline{spawnve}{mode, path, args, env} \funcline{spawnvp}{mode, file, args} \funcline{spawnvpe}{mode, file, args, env} -Execute the program \var{path} in a new process. If \var{mode} is +Execute the program \var{path} in a new process. + +(Note that the \module{subprocess} module provides more powerful +facilities for spawning new processes and retrieving their results; +using that module is preferable to using these functions.) + +If \var{mode} is \constant{P_NOWAIT}, this function returns the process ID of the new process; if \var{mode} is \constant{P_WAIT}, returns the process's exit code if it exits normally, or \code{-\var{signal}}, where @@ -1682,6 +1697,10 @@ a non-native shell, consult your shell documentation. Availability: Macintosh, \UNIX, Windows. + +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results; using that module +is preferable to using this function. \end{funcdesc} \begin{funcdesc}{times}{} Modified: stackless/branches/release25-maint/Doc/lib/libpickle.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libpickle.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libpickle.tex Sat Apr 14 15:02:57 2007 @@ -519,7 +519,7 @@ version of the object. The next element of the tuple will provide arguments for this callable, and later elements provide additional state information that will subsequently be used to fully reconstruct -the pickled date. +the pickled data. In the unpickling environment this object must be either a class, a callable registered as a ``safe constructor'' (see below), or it must Modified: stackless/branches/release25-maint/Doc/lib/libpopen2.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libpopen2.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libpopen2.tex Sat Apr 14 15:02:57 2007 @@ -2,7 +2,6 @@ Subprocesses with accessible I/O streams} \declaremodule{standard}{popen2} - \platform{Unix, Windows} \modulesynopsis{Subprocesses with accessible standard I/O streams.} \sectionauthor{Drew Csillag}{drew_csillag at geocities.com} @@ -11,10 +10,10 @@ input/output/error pipes and obtain their return codes under \UNIX{} and Windows. -Note that starting with Python 2.0, this functionality is available -using functions from the \refmodule{os} module which have the same -names as the factory functions here, but the order of the return -values is more intuitive in the \refmodule{os} module variants. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results. Using the +\module{subprocess} module is preferable to using the \module{popen2} +module. The primary interface offered by this module is a trio of factory functions. For each of these, if \var{bufsize} is specified, @@ -184,3 +183,7 @@ separate threads to read each of the individual files provided by whichever \function{popen*()} function or \class{Popen*} class was used. + +\begin{seealso} + \seemodule{subprocess}{Module for spawning and managing subprocesses.} +\end{seealso} Modified: stackless/branches/release25-maint/Doc/lib/libprofile.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libprofile.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libprofile.tex Sat Apr 14 15:02:57 2007 @@ -319,7 +319,7 @@ \begin{funcdesc}{run}{command\optional{, filename}} -This function takes a single argument that has can be passed to the +This function takes a single argument that can be passed to the \keyword{exec} statement, and an optional file name. In all cases this routine attempts to \keyword{exec} its first argument, and gather profiling statistics from the execution. If no file name is present, then this Modified: stackless/branches/release25-maint/Doc/lib/librandom.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/librandom.tex (original) +++ stackless/branches/release25-maint/Doc/lib/librandom.tex Sat Apr 14 15:02:57 2007 @@ -185,7 +185,7 @@ \begin{funcdesc}{betavariate}{alpha, beta} Beta distribution. Conditions on the parameters are - \code{\var{alpha} > -1} and \code{\var{beta} > -1}. + \code{\var{alpha} > 0} and \code{\var{beta} > 0}. Returned values range between 0 and 1. \end{funcdesc} Modified: stackless/branches/release25-maint/Doc/lib/libshutil.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libshutil.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libshutil.tex Sat Apr 14 15:02:57 2007 @@ -34,7 +34,9 @@ is the buffer size. In particular, a negative \var{length} value means to copy the data without looping over the source data in chunks; by default the data is read in chunks to avoid uncontrolled - memory consumption. + memory consumption. Note that if the current file position of the + \var{fsrc} object is not 0, only the contents from the current file + position to the end of the file will be copied. \end{funcdesc} \begin{funcdesc}{copymode}{src, dst} Modified: stackless/branches/release25-maint/Doc/lib/libsimplexmlrpc.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libsimplexmlrpc.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libsimplexmlrpc.tex Sat Apr 14 15:02:57 2007 @@ -15,7 +15,7 @@ \begin{classdesc}{SimpleXMLRPCServer}{addr\optional{, requestHandler\optional{, - logRequests\optional{allow_none\optional{, encoding}}}}} + logRequests\optional{, allow_none\optional{, encoding}}}}} Create a new server instance. This class provides methods for registration of functions that can be called by Modified: stackless/branches/release25-maint/Doc/lib/libsmtplib.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libsmtplib.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libsmtplib.tex Sat Apr 14 15:02:57 2007 @@ -173,7 +173,7 @@ The server didn't reply properly to the \samp{HELO} greeting. \item[\exception{SMTPAuthenticationError}] The server didn't accept the username/password combination. - \item[\exception{SMTPError}] + \item[\exception{SMTPException}] No suitable authentication method was found. \end{description} \end{methoddesc} Modified: stackless/branches/release25-maint/Doc/lib/libsocket.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libsocket.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libsocket.tex Sat Apr 14 15:02:57 2007 @@ -241,8 +241,8 @@ This operation assumes that there is a valid address-to-host mapping for the host, and the assumption does not always hold. Note: \function{gethostname()} doesn't always return the fully qualified -domain name; use \code{gethostbyaddr(gethostname())} -(see below). +domain name; use \code{getfqdn()} +(see above). \end{funcdesc} \begin{funcdesc}{gethostbyaddr}{ip_address} @@ -574,6 +574,28 @@ (The format of \var{address} depends on the address family --- see above.) \end{methoddesc} +\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}} +Receive data from the socket, writing it into \var{buffer} instead of +creating a new string. The return value is a pair +\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number +of bytes received and \var{address} is the address of the socket +sending the data. See the \UNIX{} manual page +\manpage{recv}{2} for the meaning of the optional argument +\var{flags}; it defaults to zero. (The format of \var{address} +depends on the address family --- see above.) +\versionadded{2.5} +\end{methoddesc} + +\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}} +Receive up to \var{nbytes} bytes from the socket, +storing the data into a buffer rather than creating a new string. +If \var{nbytes} is not specified (or 0), +receive up to the size available in the given buffer. +See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the +optional argument \var{flags}; it defaults to zero. +\versionadded{2.5} +\end{methoddesc} + \begin{methoddesc}[socket]{send}{string\optional{, flags}} Send data to the socket. The socket must be connected to a remote socket. The optional \var{flags} argument has the same meaning as for @@ -712,14 +734,15 @@ \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.) +Returns a string describing the server's certificate. +Useful for debugging purposes; do not parse the content of this string +because its format can't be parsed unambiguously. \end{methoddesc} \begin{methoddesc}{issuer}{} -Returns a string containing the ASN.1 distinguished name identifying the -issuer of the server's certificate. +Returns a string describing the issuer of the server's certificate. +Useful for debugging purposes; do not parse the content of this string +because its format can't be parsed unambiguously. \end{methoddesc} \subsection{Example \label{socket-example}} Modified: stackless/branches/release25-maint/Doc/lib/libsqlite3.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libsqlite3.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libsqlite3.tex Sat Apr 14 15:02:57 2007 @@ -187,12 +187,12 @@ \end{funcdesc} \begin{funcdesc}{complete_statement}{sql} -Returns \constant{True} if the string \var{sql} one or more complete SQL -statements terminated by semicolons. It does not verify if the SQL is -syntactically correct, only if there are no unclosed string literals and if the +Returns \constant{True} if the string \var{sql} contains one or more complete SQL +statements terminated by semicolons. It does not verify that the SQL is +syntactically correct, only that there are no unclosed string literals and the statement is terminated by a semicolon. -This can be used to build a shell for SQLite, like in the following example: +This can be used to build a shell for SQLite, as in the following example: \verbatiminput{sqlite3/complete_statement.py} \end{funcdesc} Modified: stackless/branches/release25-maint/Doc/lib/libstdtypes.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libstdtypes.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libstdtypes.tex Sat Apr 14 15:02:57 2007 @@ -834,7 +834,7 @@ start\optional{, end}}} Return \code{True} if string starts with the \var{prefix}, otherwise return \code{False}. \var{prefix} can also be a tuple of -suffixes to look for. With optional \var{start}, test string beginning at +prefixes to look for. With optional \var{start}, test string beginning at that position. With optional \var{end}, stop comparing string at that position. @@ -876,6 +876,9 @@ characters have been mapped through the given translation table, which must be a string of length 256. +You can use the \function{maketrans()} helper function in the +\refmodule{string} module to create a translation table. + For Unicode objects, the \method{translate()} method does not accept the optional \var{deletechars} argument. Instead, it returns a copy of the \var{s} where all characters have been mapped @@ -1221,7 +1224,7 @@ \label{types-set}} \obindex{set} -A \dfn{set} object is an unordered collection of immutable values. +A \dfn{set} object is an unordered collection of distinct hashable objects. Common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference. @@ -1424,7 +1427,8 @@ {(3)} \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)} \lineiii{\var{a}.update(\optional{\var{b}})} - {updates (and overwrites) key/value pairs from \var{b}} + {updates \var{a} with key/value pairs from \var{b}, overwriting + existing keys, returns \code{None}} {(9)} \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})} {Creates a new dictionary with keys from \var{seq} and values set to \var{value}} @@ -1674,9 +1678,12 @@ \begin{methoddesc}[file]{seek}{offset\optional{, whence}} Set the file's current position, like \code{stdio}'s \cfunction{fseek()}. - The \var{whence} argument is optional and defaults to \code{0} - (absolute file positioning); other values are \code{1} (seek - relative to the current position) and \code{2} (seek relative to the + The \var{whence} argument is optional and defaults to + \code{os.SEEK_SET} or \code{0} + (absolute file positioning); other values are \code{os.SEEK_CUR} or \code{1} + (seek + relative to the current position) and \code{os.SEEK_END} or \code{2} + (seek relative to the file's end). There is no return value. Note that if the file is opened for appending (mode \code{'a'} or \code{'a+'}), any \method{seek()} operations will be undone at the next write. If the Modified: stackless/branches/release25-maint/Doc/lib/libstring.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libstring.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libstring.tex Sat Apr 14 15:02:57 2007 @@ -220,7 +220,7 @@ \begin{funcdesc}{maketrans}{from, to} Return a translation table suitable for passing to - \function{translate()} or \function{regex.compile()}, that will map + \function{translate()}, that will map each character in \var{from} into the character at the same position in \var{to}; \var{from} and \var{to} must have the same length. Modified: stackless/branches/release25-maint/Doc/lib/libstruct.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libstruct.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libstruct.tex Sat Apr 14 15:02:57 2007 @@ -29,6 +29,15 @@ exactly. \end{funcdesc} +\begin{funcdesc}{pack_into}{fmt, buffer, offset, v1, v2, \moreargs} + Pack the values \code{\var{v1}, \var{v2}, \textrm{\ldots}} according to the given + format, write the packed bytes into the writable \var{buffer} starting at + \var{offset}. + Note that the offset is not an optional argument. + + \versionadded{2.5} +\end{funcdesc} + \begin{funcdesc}{unpack}{fmt, string} Unpack the string (presumably packed by \code{pack(\var{fmt}, \textrm{\ldots})}) according to the given format. The result is a @@ -37,6 +46,16 @@ (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}). \end{funcdesc} +\begin{funcdesc}{unpack_from}{fmt, buffer\optional{,offset \code{= 0}}} + Unpack the \var{buffer} according to tthe given format. + The result is a tuple even if it contains exactly one item. The + \var{buffer} must contain at least the amount of data required by the + format (\code{len(buffer[offset:])} must be at least + \code{calcsize(\var{fmt})}). + + \versionadded{2.5} +\end{funcdesc} + \begin{funcdesc}{calcsize}{fmt} Return the size of the struct (and hence of the string) corresponding to the given format. @@ -195,3 +214,43 @@ \seemodule{array}{Packed binary storage of homogeneous data.} \seemodule{xdrlib}{Packing and unpacking of XDR data.} \end{seealso} + +\subsection{Struct Objects \label{struct-objects}} + +The \module{struct} module also defines the following type: + +\begin{classdesc}{Struct}{format} + Return a new Struct object which writes and reads binary data according to + the format string \var{format}. Creating a Struct object once and calling + its methods is more efficient than calling the \module{struct} functions + with the same format since the format string only needs to be compiled once. + + \versionadded{2.5} +\end{classdesc} + +Compiled Struct objects support the following methods and attributes: + +\begin{methoddesc}[Struct]{pack}{v1, v2, \moreargs} + Identical to the \function{pack()} function, using the compiled format. + (\code{len(result)} will equal \member{self.size}.) +\end{methoddesc} + +\begin{methoddesc}[Struct]{pack_into}{buffer, offset, v1, v2, \moreargs} + Identical to the \function{pack_into()} function, using the compiled format. +\end{methoddesc} + +\begin{methoddesc}[Struct]{unpack}{string} + Identical to the \function{unpack()} function, using the compiled format. + (\code{len(string)} must equal \member{self.size}). +\end{methoddesc} + +\begin{methoddesc}[Struct]{unpack_from}{buffer\optional{,offset + \code{= 0}}} + Identical to the \function{unpack_from()} function, using the compiled format. + (\code{len(buffer[offset:])} must be at least \member{self.size}). +\end{methoddesc} + +\begin{memberdesc}[Struct]{format} + The format string used to construct this Struct object. +\end{memberdesc} + Modified: stackless/branches/release25-maint/Doc/lib/libsubprocess.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libsubprocess.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libsubprocess.tex Sat Apr 14 15:02:57 2007 @@ -12,9 +12,6 @@ codes. This module intends to replace several other, older modules and functions, such as: -% XXX Should add pointers to this module to at least the popen2 -% and commands sections. - \begin{verbatim} os.system os.spawn* Modified: stackless/branches/release25-maint/Doc/lib/libtarfile.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libtarfile.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libtarfile.tex Sat Apr 14 15:02:57 2007 @@ -48,8 +48,8 @@ avoid this. If a compression method is not supported, \exception{CompressionError} is raised. - If \var{fileobj} is specified, it is used as an alternative to - a file object opened for \var{name}. + If \var{fileobj} is specified, it is used as an alternative to a file + object opened for \var{name}. It is supposed to be at position 0. For special purposes, there is a second format for \var{mode}: \code{'filemode|[compression]'}. \function{open()} will return a @@ -155,6 +155,7 @@ If \var{fileobj} is given, it is used for reading or writing data. If it can be determined, \var{mode} is overridden by \var{fileobj}'s mode. + \var{fileobj} will be used from position 0. \begin{notice} \var{fileobj} is not closed, when \class{TarFile} is closed. \end{notice} Modified: stackless/branches/release25-maint/Doc/lib/libtempfile.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libtempfile.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libtempfile.tex Sat Apr 14 15:02:57 2007 @@ -86,7 +86,12 @@ prefix; otherwise, a default prefix is used. If \var{dir} is specified, the file will be created in that directory; -otherwise, a default directory is used. +otherwise, a default directory is used. The default directory is chosen +from a platform-dependent list, but the user of the application can control +the directory location by setting the \var{TMPDIR}, \var{TEMP} or \var{TMP} +environment variables. There is thus no guarantee that the generated +filename will have any nice properties, such as not requiring quoting when +passed to external commands via \code{os.popen()}. If \var{text} is specified, it indicates whether to open the file in binary mode (the default) or text mode. On some platforms, this makes Modified: stackless/branches/release25-maint/Doc/lib/libthreading.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libthreading.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libthreading.tex Sat Apr 14 15:02:57 2007 @@ -15,10 +15,9 @@ This module defines the following functions and objects: \begin{funcdesc}{activeCount}{} -Return the number of currently active \class{Thread} objects. -The returned count is equal to the length of the list returned by +Return the number of \class{Thread} objects currently alive. The +returned count is equal to the length of the list returned by \function{enumerate()}. -A function that returns the number of currently active threads. \end{funcdesc} \begin{funcdesc}{Condition}{} @@ -36,10 +35,10 @@ \end{funcdesc} \begin{funcdesc}{enumerate}{} -Return a list of all currently active \class{Thread} objects. -The list includes daemonic threads, dummy thread objects created -by \function{currentThread()}, and the main thread. It excludes terminated -threads and threads that have not yet been started. +Return a list of all \class{Thread} objects currently alive. The list +includes daemonic threads, dummy thread objects created by +\function{currentThread()}, and the main thread. It excludes +terminated threads and threads that have not yet been started. \end{funcdesc} \begin{funcdesc}{Event}{} @@ -526,12 +525,9 @@ \method{run()} method in a separate thread of control. Once the thread's activity is started, the thread is considered -'alive' and 'active' (these concepts are almost, but not quite -exactly, the same; their definition is intentionally somewhat -vague). It stops being alive and active when its \method{run()} -method terminates -- either normally, or by raising an unhandled -exception. The \method{isAlive()} method tests whether the thread is -alive. +'alive'. It stops being alive when its \method{run()} method terminates +-- either normally, or by raising an unhandled exception. The +\method{isAlive()} method tests whether the thread is alive. Other threads can call a thread's \method{join()} method. This blocks the calling thread until the thread whose \method{join()} method is @@ -551,14 +547,13 @@ initial thread of control in the Python program. It is not a daemon thread. -There is the possibility that ``dummy thread objects'' are -created. These are thread objects corresponding to ``alien -threads''. These are threads of control started outside the -threading module, such as directly from C code. Dummy thread objects -have limited functionality; they are always considered alive, -active, and daemonic, and cannot be \method{join()}ed. They are never -deleted, since it is impossible to detect the termination of alien -threads. +There is the possibility that ``dummy thread objects'' are created. +These are thread objects corresponding to ``alien threads'', which +are threads of control started outside the threading module, such as +directly from C code. Dummy thread objects have limited +functionality; they are always considered alive and daemonic, and +cannot be \method{join()}ed. They are never deleted, since it is +impossible to detect the termination of alien threads. \begin{classdesc}{Thread}{group=None, target=None, name=None, @@ -646,7 +641,8 @@ Return whether the thread is alive. Roughly, a thread is alive from the moment the \method{start()} method -returns until its \method{run()} method terminates. +returns until its \method{run()} method terminates. The module +function \function{enumerate()} returns a list of all alive threads. \end{methoddesc} \begin{methoddesc}{isDaemon}{} @@ -659,8 +655,8 @@ The initial value is inherited from the creating thread. -The entire Python program exits when no active non-daemon -threads are left. +The entire Python program exits when no alive non-daemon threads are +left. \end{methoddesc} Modified: stackless/branches/release25-maint/Doc/lib/libtimeit.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libtimeit.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libtimeit.tex Sat Apr 14 15:02:57 2007 @@ -102,7 +102,7 @@ When called as a program from the command line, the following form is used: \begin{verbatim} -python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] +python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] \end{verbatim} where the following options are understood: Modified: stackless/branches/release25-maint/Doc/lib/libunittest.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libunittest.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libunittest.tex Sat Apr 14 15:02:57 2007 @@ -540,7 +540,7 @@ \begin{funcdesc}{main}{\optional{module\optional{, defaultTest\optional{, argv\optional{, - testRunner\optional{, testRunner}}}}}} + testRunner\optional{, testLoader}}}}}} 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 to include the following line at the end of a Modified: stackless/branches/release25-maint/Doc/lib/liburlparse.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/liburlparse.tex (original) +++ stackless/branches/release25-maint/Doc/lib/liburlparse.tex Sat Apr 14 15:02:57 2007 @@ -89,7 +89,7 @@ \begin{funcdesc}{urlunparse}{parts} Construct a URL from a tuple as returned by \code{urlparse()}. -The \var{parts} argument be any six-item iterable. +The \var{parts} argument can be any six-item iterable. This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent). @@ -133,7 +133,7 @@ \begin{funcdesc}{urlunsplit}{parts} Combine the elements of a tuple as returned by \function{urlsplit()} into a complete URL as a string. -The \var{parts} argument be any five-item iterable. +The \var{parts} argument can be any five-item iterable. This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent). @@ -168,7 +168,7 @@ If you do not want that behavior, preprocess the \var{url} with \function{urlsplit()} and \function{urlunsplit()}, -removing possible \em{scheme} and \em{netloc} parts. +removing possible \emph{scheme} and \emph{netloc} parts. \end{funcdesc} \begin{funcdesc}{urldefrag}{url} Modified: stackless/branches/release25-maint/Doc/lib/libwsgiref.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/libwsgiref.tex (original) +++ stackless/branches/release25-maint/Doc/lib/libwsgiref.tex Sat Apr 14 15:02:57 2007 @@ -26,8 +26,9 @@ 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. +See \url{http://www.wsgi.org} for more information about WSGI, +and links to tutorials and other resources. Modified: stackless/branches/release25-maint/Doc/lib/tkinter.tex ============================================================================== --- stackless/branches/release25-maint/Doc/lib/tkinter.tex (original) +++ stackless/branches/release25-maint/Doc/lib/tkinter.tex Sat Apr 14 15:02:57 2007 @@ -318,7 +318,7 @@ \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 preceded by a `-', like \UNIX{} shell command flags, and values are put in quotes if they are more than one word. \end{description} Modified: stackless/branches/release25-maint/Doc/mac/toolbox.tex ============================================================================== --- stackless/branches/release25-maint/Doc/mac/toolbox.tex (original) +++ stackless/branches/release25-maint/Doc/mac/toolbox.tex Sat Apr 14 15:02:57 2007 @@ -65,7 +65,7 @@ \modulesynopsis{Interface to the Component Manager.} \section{\module{Carbon.CarbonEvt} --- Carbon Event Manager} -\declaremodule{standard}{Carbon.CaronEvt} +\declaremodule{standard}{Carbon.CarbonEvt} \platform{Mac} \modulesynopsis{Interface to the Carbon Event Manager.} Modified: stackless/branches/release25-maint/Doc/ref/ref1.tex ============================================================================== --- stackless/branches/release25-maint/Doc/ref/ref1.tex (original) +++ stackless/branches/release25-maint/Doc/ref/ref1.tex Sat Apr 14 15:02:57 2007 @@ -93,7 +93,7 @@ \index{syntax} \index{notation} -\begin{productionlist} +\begin{productionlist}[*] \production{name}{\token{lc_letter} (\token{lc_letter} | "_")*} \production{lc_letter}{"a"..."z"} \end{productionlist} Modified: stackless/branches/release25-maint/Doc/ref/ref3.tex ============================================================================== --- stackless/branches/release25-maint/Doc/ref/ref3.tex (original) +++ stackless/branches/release25-maint/Doc/ref/ref3.tex Sat Apr 14 15:02:57 2007 @@ -1282,10 +1282,14 @@ \code{\var{x}.__ne__(\var{y})}, \code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and \code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}. -These methods can return any value, but if the comparison operator is -used in a Boolean context, the return value should be interpretable as -a Boolean value, else a \exception{TypeError} will be raised. -By convention, \code{False} is used for false and \code{True} for true. + +A rich comparison method may return the singleton \code{NotImplemented} if it +does not implement the operation for a given pair of arguments. +By convention, \code{False} and \code{True} are returned for a successful +comparison. However, these methods can return any value, so if the +comparison operator is used in a Boolean context (e.g., in the condition +of an \code{if} statement), Python will call \function{bool()} on the +value to determine if the result is true or false. There are no implied relationships among the comparison operators. The truth of \code{\var{x}==\var{y}} does not imply that \code{\var{x}!=\var{y}} @@ -1299,9 +1303,7 @@ \method{__ge__()} are each other's reflection, and \method{__eq__()} and \method{__ne__()} are their own reflection. -Arguments to rich comparison methods are never coerced. A rich -comparison method may return \code{NotImplemented} if it does not -implement the operation for a given pair of arguments. +Arguments to rich comparison methods are never coerced. \end{methoddesc} \begin{methoddesc}[object]{__cmp__}{self, other} @@ -1999,8 +2001,8 @@ \methodline[numeric object]{__ixor__}{self, other} \methodline[numeric object]{__ior__}{self, other} These methods are called to implement the augmented arithmetic -operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=}, -\code{**=}, \code{<<=}, \code{>>=}, \code{\&=}, +operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{//=}, +\code{\%=}, \code{**=}, \code{<<=}, \code{>>=}, \code{\&=}, \code{\textasciicircum=}, \code{|=}). These methods should attempt to do the operation in-place (modifying \var{self}) and return the result (which could be, but does not have to be, \var{self}). If a specific method Modified: stackless/branches/release25-maint/Doc/ref/ref5.tex ============================================================================== --- stackless/branches/release25-maint/Doc/ref/ref5.tex (original) +++ stackless/branches/release25-maint/Doc/ref/ref5.tex Sat Apr 14 15:02:57 2007 @@ -56,7 +56,7 @@ \production{enclosure} {\token{parenth_form} | \token{list_display}} \productioncont{| \token{generator_expression} | \token{dict_display}} - \productioncont{| \token{string_conversion}} + \productioncont{| \token{string_conversion} | \token{yield_atom}} \end{productionlist} @@ -65,6 +65,7 @@ \index{identifier} An identifier occurring as an atom is a name. See +section \ref{identifiers} for lexical definition and section~\ref{naming} for documentation of naming and binding. When the name is bound to an object, evaluation of the atom yields @@ -154,22 +155,20 @@ square brackets: \begin{productionlist} - \production{test} - {\token{or_test} | \token{lambda_form}} - \production{testlist} - {\token{test} ( "," \token{test} )* [ "," ]} \production{list_display} - {"[" [\token{listmaker}] "]"} - \production{listmaker} - {\token{expression} ( \token{list_for} - | ( "," \token{expression} )* [","] )} - \production{list_iter} - {\token{list_for} | \token{list_if}} + {"[" [\token{expression_list} | \token{list_comprehension}] "]"} + \production{list_comprehension} + {\token{expression} \token{list_for}} \production{list_for} - {"for" \token{expression_list} "in" \token{testlist} + {"for" \token{target_list} "in" \token{old_expression_list} [\token{list_iter}]} + \production{old_expression_list} + {\token{old_expression} + [("," \token{old_expression})+ [","]]} + \production{list_iter} + {\token{list_for} | \token{list_if}} \production{list_if} - {"if" \token{test} [\token{list_iter}]} + {"if" \token{old_expression} [\token{list_iter}]} \end{productionlist} A list display yields a new list object. Its contents are specified @@ -200,19 +199,18 @@ \begin{productionlist} \production{generator_expression} - {"(" \token{test} \token{genexpr_for} ")"} + {"(" \token{expression} \token{genexpr_for} ")"} \production{genexpr_for} - {"for" \token{expression_list} "in" \token{test} + {"for" \token{target_list} "in" \token{or_test} [\token{genexpr_iter}]} \production{genexpr_iter} {\token{genexpr_for} | \token{genexpr_if}} \production{genexpr_if} - {"if" \token{test} [\token{genexpr_iter}]} + {"if" \token{old_expression} [\token{genexpr_iter}]} \end{productionlist} A generator expression yields a new generator object. \obindex{generator} -\obindex{generator expression} It consists of a single expression followed by at least one \keyword{for} clause and zero or more \keyword{for} or \keyword{if} clauses. The iterating values of the new generator are those that @@ -311,6 +309,142 @@ \bifuncindex{str} +\subsection{Yield expressions\label{yieldexpr}} +\kwindex{yield} +\indexii{yield}{expression} +\indexii{generator}{function} + +\begin{productionlist} + \production{yield_atom} + {"(" \token{yield_expression} ")"} + \production{yield_expression} + {"yield" [\token{expression_list}]} +\end{productionlist} + +\versionadded{2.5} + +The \keyword{yield} expression is only used when defining a generator +function, and can only be used in the body of a function definition. +Using a \keyword{yield} expression in a function definition is +sufficient to cause that definition to create a generator function +instead of a normal function. + +When a generator function is called, it returns an iterator known as a +generator. That generator then controls the execution of a generator +function. The execution starts when one of the generator's methods is +called. At that time, the execution proceeds to the first +\keyword{yield} expression, where it is suspended again, returning the +value of \grammartoken{expression_list} to generator's caller. By +suspended we mean that all local state is retained, including the +current bindings of local variables, the instruction pointer, and the +internal evaluation stack. When the execution is resumed by calling +one of the generator's methods, the function can proceed exactly as +if the \keyword{yield} expression was just another external call. +The value of the \keyword{yield} expression after resuming depends on +the method which resumed the execution. + +\index{coroutine} + +All of this makes generator functions quite similar to coroutines; they +yield multiple times, they have more than one entry point and their +execution can be suspended. The only difference is that a generator +function cannot control where should the execution continue after it +yields; the control is always transfered to the generator's caller. + +\obindex{generator} + +The following generator's methods can be used to control the execution +of a generator function: + +\exindex{StopIteration} + +\begin{methoddesc}[generator]{next}{} + Starts the execution of a generator function or resumes it at the + last executed \keyword{yield} expression. When a generator function + is resumed with a \method{next()} method, the current \keyword{yield} + expression always evaluates to \constant{None}. The execution then + continues to the next \keyword{yield} expression, where the generator + is suspended again, and the value of the + \grammartoken{expression_list} is returned to \method{next()}'s + caller. If the generator exits without yielding another value, a + \exception{StopIteration} exception is raised. +\end{methoddesc} + +\begin{methoddesc}[generator]{send}{value} + Resumes the execution and ``sends'' a value into the generator + function. The \code{value} argument becomes the result of the + current \keyword{yield} expression. The \method{send()} method + returns the next value yielded by the generator, or raises + \exception{StopIteration} if the generator exits without yielding + another value. + When \method{send()} is called to start the generator, it must be + called with \constant{None} as the argument, because there is no + \keyword{yield} expression that could receieve the value. +\end{methoddesc} + +\begin{methoddesc}[generator]{throw} + {type\optional{, value\optional{, traceback}}} + Raises an exception of type \code{type} at the point where generator + was paused, and returns the next value yielded by the generator + function. If the generator exits without yielding another value, a + \exception{StopIteration} exception is raised. If the generator + function does not catch the passed-in exception, or raises a + different exception, then that exception propagates to the caller. +\end{methoddesc} + +\exindex{GeneratorExit} + +\begin{methoddesc}[generator]{close}{} + Raises a \exception{GeneratorExit} at the point where the generator + function was paused. If the generator function then raises + \exception{StopIteration} (by exiting normally, or due to already + being closed) or \exception{GeneratorExit} (by not catching the + exception), close returns to its caller. If the generator yields a + value, a \exception{RuntimeError} is raised. If the generator raises + any other exception, it is propagated to the caller. \method{close} + does nothing if the generator has already exited due to an exception + or normal exit. +\end{methoddesc} + +Here is a simple example that demonstrates the behavior of generators +and generator functions: + +\begin{verbatim} +>>> def echo(value=None): +... print "Execution starts when 'next()' is called for the first time." +... try: +... while True: +... try: +... value = (yield value) +... except GeneratorExit: +... # never catch GeneratorExit +... raise +... except Exception, e: +... value = e +... finally: +... print "Don't forget to clean up when 'close()' is called." +... +>>> generator = echo(1) +>>> print generator.next() +Execution starts when 'next()' is called for the first time. +1 +>>> print generator.next() +None +>>> print generator.send(2) +2 +>>> generator.throw(TypeError, "spam") +TypeError('spam',) +>>> generator.close() +Don't forget to clean up when 'close()' is called. +\end{verbatim} + +\begin{seealso} + \seepep{0342}{Coroutines via Enhanced Generators} + {The proposal to enhance the API and syntax of generators, + making them usable as simple coroutines.} +\end{seealso} + + \section{Primaries\label{primaries}} \index{primary} @@ -474,9 +608,8 @@ \begin{productionlist} \production{call} - {\token{primary} "(" [\token{argument_list} [","]] ")"} - {\token{primary} "(" [\token{argument_list} [","] | - \token{test} \token{genexpr_for} ] ")"} + {\token{primary} "(" [\token{argument_list} [","]} + \productioncont{ | \token{expression} \token{genexpr_for}] ")"} \production{argument_list} {\token{positional_arguments} ["," \token{keyword_arguments}]} \productioncont{ ["," "*" \token{expression}]} @@ -809,10 +942,9 @@ operations: \begin{productionlist} - % The empty groups below prevent conversion to guillemets. \production{shift_expr} {\token{a_expr} - | \token{shift_expr} ( "<{}<" | ">{}>" ) \token{a_expr}} + | \token{shift_expr} ( "<<" | ">>" ) \token{a_expr}} \end{productionlist} These operators accept plain or long integers as arguments. The @@ -1015,14 +1147,18 @@ \section{Boolean operations\label{Booleans}} +\indexii{Conditional}{expression} \indexii{Boolean}{operation} Boolean operations have the lowest priority of all Python operations: \begin{productionlist} \production{expression} - {\token{or_test} [\token{if} \token{or_test} \token{else} - \token{test}] | \token{lambda_form}} + {\token{conditional_expression} | \token{lambda_form}} + \production{old_expression} + {\token{or_test} | \token{old_lambda_form}} + \production{conditional_expression} + {\token{or_test} ["if" \token{or_test} "else" \token{expression}]} \production{or_test} {\token{and_test} | \token{or_test} "or" \token{and_test}} \production{and_test} @@ -1074,6 +1210,8 @@ \begin{productionlist} \production{lambda_form} {"lambda" [\token{parameter_list}]: \token{expression}} + \production{old_lambda_form} + {"lambda" [\token{parameter_list}]: \token{old_expression}} \end{productionlist} Lambda forms (lambda expressions) have the same syntactic position as Modified: stackless/branches/release25-maint/Doc/ref/ref6.tex ============================================================================== --- stackless/branches/release25-maint/Doc/ref/ref6.tex (original) +++ stackless/branches/release25-maint/Doc/ref/ref6.tex Sat Apr 14 15:02:57 2007 @@ -108,7 +108,8 @@ \begin{productionlist} \production{assignment_stmt} - {(\token{target_list} "=")+ \token{expression_list}} + {(\token{target_list} "=")+ + (\token{expression_list} | \token{yield_expression})} \production{target_list} {\token{target} ("," \token{target})* [","]} \production{target} @@ -273,11 +274,11 @@ \b