[Commits] python.it commit r176 - in
python/python/Doc/branches/2.4.3: api commontex dist ext html
html/icons info isilo lib mac paper-a4 paper-letter ref tools
tut whatsnew
commit a svn.python.it
commit a svn.python.it
Ven 2 Giu 2006 12:53:13 CEST
Author: manlio
Date: Fri Jun 2 12:52:55 2006
New Revision: 176
Added:
python/python/Doc/branches/2.4.3/html/icons/pyfav.png (contents, props changed)
python/python/Doc/branches/2.4.3/lib/libcookielib.tex
python/python/Doc/branches/2.4.3/lib/libdecimal.tex
python/python/Doc/branches/2.4.3/lib/libmodulefinder.tex
python/python/Doc/branches/2.4.3/lib/libpickletools.tex
python/python/Doc/branches/2.4.3/lib/libsmtpd.tex
python/python/Doc/branches/2.4.3/lib/libsubprocess.tex
python/python/Doc/branches/2.4.3/lib/libzipimport.tex
Removed:
python/python/Doc/branches/2.4.3/api/.cvsignore
python/python/Doc/branches/2.4.3/commontex/.cvsignore
python/python/Doc/branches/2.4.3/commontex/patchlevel.tex
python/python/Doc/branches/2.4.3/dist/.cvsignore
python/python/Doc/branches/2.4.3/ext/.cvsignore
python/python/Doc/branches/2.4.3/html/.cvsignore
python/python/Doc/branches/2.4.3/info/.cvsignore
python/python/Doc/branches/2.4.3/isilo/.cvsignore
python/python/Doc/branches/2.4.3/lib/.cvsignore
python/python/Doc/branches/2.4.3/lib/libmpz.tex
python/python/Doc/branches/2.4.3/lib/librotor.tex
python/python/Doc/branches/2.4.3/lib/libxreadlines.tex
python/python/Doc/branches/2.4.3/mac/.cvsignore
python/python/Doc/branches/2.4.3/paper-a4/.cvsignore
python/python/Doc/branches/2.4.3/paper-letter/.cvsignore
python/python/Doc/branches/2.4.3/ref/.cvsignore
python/python/Doc/branches/2.4.3/tools/cvsinfo.py
python/python/Doc/branches/2.4.3/tools/findacks
python/python/Doc/branches/2.4.3/tut/.cvsignore
Modified:
python/python/Doc/branches/2.4.3/commontex/boilerplate.tex
python/python/Doc/branches/2.4.3/commontex/copyright.tex
python/python/Doc/branches/2.4.3/html/about.html
python/python/Doc/branches/2.4.3/lib/asttable.tex
python/python/Doc/branches/2.4.3/lib/email.tex
python/python/Doc/branches/2.4.3/lib/emailencoders.tex
python/python/Doc/branches/2.4.3/lib/emailexc.tex
python/python/Doc/branches/2.4.3/lib/emailheaders.tex
python/python/Doc/branches/2.4.3/lib/emailmessage.tex
python/python/Doc/branches/2.4.3/lib/emailmimebase.tex
python/python/Doc/branches/2.4.3/lib/emailparser.tex
python/python/Doc/branches/2.4.3/lib/emailutil.tex
python/python/Doc/branches/2.4.3/lib/language.tex
python/python/Doc/branches/2.4.3/lib/libarray.tex
python/python/Doc/branches/2.4.3/lib/libasyncore.tex
python/python/Doc/branches/2.4.3/lib/libatexit.tex
python/python/Doc/branches/2.4.3/lib/libbase64.tex
python/python/Doc/branches/2.4.3/lib/libbasehttp.tex
python/python/Doc/branches/2.4.3/lib/libbltin.tex
python/python/Doc/branches/2.4.3/lib/libbsddb.tex
python/python/Doc/branches/2.4.3/lib/libbz2.tex
python/python/Doc/branches/2.4.3/lib/libcalendar.tex
python/python/Doc/branches/2.4.3/lib/libcfgparser.tex
python/python/Doc/branches/2.4.3/lib/libcgi.tex
python/python/Doc/branches/2.4.3/lib/libcgitb.tex
python/python/Doc/branches/2.4.3/lib/libcmath.tex
python/python/Doc/branches/2.4.3/lib/libcmd.tex
python/python/Doc/branches/2.4.3/lib/libcodecs.tex
python/python/Doc/branches/2.4.3/lib/libcodeop.tex
python/python/Doc/branches/2.4.3/lib/libcollections.tex
python/python/Doc/branches/2.4.3/lib/libcookie.tex
python/python/Doc/branches/2.4.3/lib/libcrypt.tex
python/python/Doc/branches/2.4.3/lib/libcsv.tex
python/python/Doc/branches/2.4.3/lib/libdatetime.tex
python/python/Doc/branches/2.4.3/lib/libdis.tex
python/python/Doc/branches/2.4.3/lib/libdl.tex
python/python/Doc/branches/2.4.3/lib/libdoctest.tex
python/python/Doc/branches/2.4.3/lib/libexcs.tex
python/python/Doc/branches/2.4.3/lib/libfcntl.tex
python/python/Doc/branches/2.4.3/lib/libfilecmp.tex
python/python/Doc/branches/2.4.3/lib/libfuture.tex
python/python/Doc/branches/2.4.3/lib/libgc.tex
python/python/Doc/branches/2.4.3/lib/libgdbm.tex
python/python/Doc/branches/2.4.3/lib/libgetopt.tex
python/python/Doc/branches/2.4.3/lib/libgettext.tex
python/python/Doc/branches/2.4.3/lib/libglob.tex
python/python/Doc/branches/2.4.3/lib/libheapq.tex
python/python/Doc/branches/2.4.3/lib/libhotshot.tex
python/python/Doc/branches/2.4.3/lib/libhtmllib.tex
python/python/Doc/branches/2.4.3/lib/libhtmlparser.tex
python/python/Doc/branches/2.4.3/lib/libimaplib.tex
python/python/Doc/branches/2.4.3/lib/libimgfile.tex
python/python/Doc/branches/2.4.3/lib/libimp.tex
python/python/Doc/branches/2.4.3/lib/libitertools.tex
python/python/Doc/branches/2.4.3/lib/liblinecache.tex
python/python/Doc/branches/2.4.3/lib/liblocale.tex
python/python/Doc/branches/2.4.3/lib/liblogging.tex
python/python/Doc/branches/2.4.3/lib/libmarshal.tex
python/python/Doc/branches/2.4.3/lib/libmath.tex
python/python/Doc/branches/2.4.3/lib/libmd5.tex
python/python/Doc/branches/2.4.3/lib/libmimetools.tex
python/python/Doc/branches/2.4.3/lib/libmmap.tex
python/python/Doc/branches/2.4.3/lib/libmultifile.tex
python/python/Doc/branches/2.4.3/lib/libnew.tex
python/python/Doc/branches/2.4.3/lib/libnntplib.tex
python/python/Doc/branches/2.4.3/lib/libos.tex
python/python/Doc/branches/2.4.3/lib/libossaudiodev.tex
python/python/Doc/branches/2.4.3/lib/libpdb.tex
python/python/Doc/branches/2.4.3/lib/libpipes.tex
python/python/Doc/branches/2.4.3/lib/libplatform.tex
python/python/Doc/branches/2.4.3/lib/libpopen2.tex
python/python/Doc/branches/2.4.3/lib/libpoplib.tex
python/python/Doc/branches/2.4.3/lib/libposixpath.tex
python/python/Doc/branches/2.4.3/lib/libpprint.tex
python/python/Doc/branches/2.4.3/lib/libprofile.tex
python/python/Doc/branches/2.4.3/lib/libpwd.tex
python/python/Doc/branches/2.4.3/lib/libpyexpat.tex
python/python/Doc/branches/2.4.3/lib/libqueue.tex
python/python/Doc/branches/2.4.3/lib/librandom.tex
python/python/Doc/branches/2.4.3/lib/libre.tex
python/python/Doc/branches/2.4.3/lib/libreadline.tex
python/python/Doc/branches/2.4.3/lib/librepr.tex
python/python/Doc/branches/2.4.3/lib/libresource.tex
python/python/Doc/branches/2.4.3/lib/librexec.tex
python/python/Doc/branches/2.4.3/lib/librfc822.tex
python/python/Doc/branches/2.4.3/lib/libselect.tex
python/python/Doc/branches/2.4.3/lib/libsets.tex
python/python/Doc/branches/2.4.3/lib/libsgmllib.tex
python/python/Doc/branches/2.4.3/lib/libsha.tex
python/python/Doc/branches/2.4.3/lib/libshelve.tex
python/python/Doc/branches/2.4.3/lib/libshlex.tex
python/python/Doc/branches/2.4.3/lib/libshutil.tex
python/python/Doc/branches/2.4.3/lib/libsignal.tex
python/python/Doc/branches/2.4.3/lib/libsimplehttp.tex
python/python/Doc/branches/2.4.3/lib/libsimplexmlrpc.tex
python/python/Doc/branches/2.4.3/lib/libsmtplib.tex
python/python/Doc/branches/2.4.3/lib/libsocket.tex
python/python/Doc/branches/2.4.3/lib/libsocksvr.tex
python/python/Doc/branches/2.4.3/lib/libstring.tex
python/python/Doc/branches/2.4.3/lib/libstringio.tex
python/python/Doc/branches/2.4.3/lib/libtempfile.tex
python/python/Doc/branches/2.4.3/lib/libtermios.tex
python/python/Doc/branches/2.4.3/lib/libtextwrap.tex
python/python/Doc/branches/2.4.3/lib/libthread.tex
python/python/Doc/branches/2.4.3/lib/libthreading.tex
python/python/Doc/branches/2.4.3/lib/libtime.tex
python/python/Doc/branches/2.4.3/lib/libtraceback.tex
python/python/Doc/branches/2.4.3/lib/libtty.tex
python/python/Doc/branches/2.4.3/lib/libtypes.tex
python/python/Doc/branches/2.4.3/lib/libundoc.tex
python/python/Doc/branches/2.4.3/lib/libunicodedata.tex
python/python/Doc/branches/2.4.3/lib/liburllib.tex
python/python/Doc/branches/2.4.3/lib/liburllib2.tex
python/python/Doc/branches/2.4.3/lib/liburlparse.tex
python/python/Doc/branches/2.4.3/lib/libuserdict.tex
python/python/Doc/branches/2.4.3/lib/libuu.tex
python/python/Doc/branches/2.4.3/lib/libwarnings.tex
python/python/Doc/branches/2.4.3/lib/libweakref.tex
python/python/Doc/branches/2.4.3/lib/libwhrandom.tex
python/python/Doc/branches/2.4.3/lib/libwinreg.tex
python/python/Doc/branches/2.4.3/lib/libxmlrpclib.tex
python/python/Doc/branches/2.4.3/lib/libzipfile.tex
python/python/Doc/branches/2.4.3/lib/libzlib.tex
python/python/Doc/branches/2.4.3/lib/xmldom.tex
python/python/Doc/branches/2.4.3/lib/xmlsaxhandler.tex
python/python/Doc/branches/2.4.3/mac/libaetypes.tex
python/python/Doc/branches/2.4.3/mac/libframework.tex
python/python/Doc/branches/2.4.3/mac/libmacfs.tex
python/python/Doc/branches/2.4.3/mac/libmacic.tex
python/python/Doc/branches/2.4.3/mac/libmacos.tex
python/python/Doc/branches/2.4.3/mac/libmacostools.tex
python/python/Doc/branches/2.4.3/mac/scripting.tex
python/python/Doc/branches/2.4.3/mac/undoc.tex
python/python/Doc/branches/2.4.3/ref/ref7.tex
python/python/Doc/branches/2.4.3/whatsnew/whatsnew20.tex
python/python/Doc/branches/2.4.3/whatsnew/whatsnew21.tex
python/python/Doc/branches/2.4.3/whatsnew/whatsnew22.tex
python/python/Doc/branches/2.4.3/whatsnew/whatsnew23.tex
Log:
preparato branch 2.4.3 per l'aggiornamento traduzioni
Modified: python/python/Doc/branches/2.4.3/commontex/boilerplate.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/commontex/boilerplate.tex (original)
+++ python/python/Doc/branches/2.4.3/commontex/boilerplate.tex Fri Jun 2 12:52:55 2006
@@ -6,6 +6,17 @@
Traduzione presso \\
\strong{http://www.zonapython.it}\\
Email: \email{zap a zonapython.it}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 3
+%[- MARK -] \authoraddress{
+%[- MARK -] \strong{Python Software Foundation}\\
+%[- MARK -] Email: \email{docs a python.org}
+%[- MARK -] }
+%[- MARK -]
+%[- MARK -] -\date{\today} % XXX update before final release!
+%[- MARK -] +\date{29 March 2006} % XXX update before final release!
+%[- MARK -] \input{patchlevel} % include Python version information
+%[- MARK -] END DIFF
}
\date{\today} % XXX update before final release!
Modified: python/python/Doc/branches/2.4.3/commontex/copyright.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/commontex/copyright.tex (original)
+++ python/python/Doc/branches/2.4.3/commontex/copyright.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,13 @@
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 1
+%[- MARK -] -Copyright \copyright{} 2001-2004 Python Software Foundation.
+%[- MARK -] +Copyright \copyright{} 2001-2006 Python Software Foundation.
+%[- MARK -] All rights reserved.
+%[- MARK -]
+%[- MARK -] Copyright \copyright{} 2000 BeOpen.com.
+%[- MARK -] All rights reserved.
+%[- MARK -]
+%[- MARK -] END DIFF
Copyright \copyright{} 2001-2004 Python Software Foundation.
All rights reserved.
Modified: python/python/Doc/branches/2.4.3/html/about.html
==============================================================================
--- python/python/Doc/branches/2.4.3/html/about.html (original)
+++ python/python/Doc/branches/2.4.3/html/about.html Fri Jun 2 12:52:55 2006
@@ -1,3 +1,45 @@
+<!-- [- MARK -] BEGIN DIFF 001 of 2 -->
+<!-- [- MARK -] @@ 7 -->
+<!-- [- MARK -] <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -->
+<!-- [- MARK -] <link rel="contents" href="index.html" title="Python Documentation Index"> -->
+<!-- [- MARK -] <link rel="index" href="modindex.html" title="Global Module Index"> -->
+<!-- [- MARK -] <link rel="start" href="index.html" title="Python Documentation Index"> -->
+<!-- [- MARK -] <link rel="up" href="index.html" title="Python Documentation Index"> -->
+<!-- [- MARK -] - <link rel="SHORTCUT ICON" href="icons/pyfav.gif" type="image/gif"> -->
+<!-- [- MARK -] + <link rel="SHORTCUT ICON" href="icons/pyfav.png" type="image/png"> -->
+<!-- [- MARK -] <link rel="STYLESHEET" href="lib/lib.css"> -->
+<!-- [- MARK -] </head> -->
+<!-- [- MARK -] <body> -->
+<!-- [- MARK -] <div class="navigation"> -->
+<!-- [- MARK -] <table width="100%" cellpadding="0" cellspacing="2"> -->
+<!-- [- MARK -] <tr> -->
+<!-- [- MARK -] <td><img width="32" height="32" align="bottom" border="0" alt="" -->
+<!-- [- MARK -] - src="icons/blank.gif"></td> -->
+<!-- [- MARK -] + src="icons/blank.png"></td> -->
+<!-- [- MARK -] <td><a href="index.html" -->
+<!-- [- MARK -] title="Python Documentation Index"><img width="32" height="32" -->
+<!-- [- MARK -] align="bottom" border="0" alt="up" -->
+<!-- [- MARK -] - src="icons/up.gif"></a></td> -->
+<!-- [- MARK -] + src="icons/up.png"></a></td> -->
+<!-- [- MARK -] <td><img width="32" height="32" align="bottom" border="0" alt="" -->
+<!-- [- MARK -] - src="icons/blank.gif"></td> -->
+<!-- [- MARK -] + src="icons/blank.png"></td> -->
+<!-- [- MARK -] <td align="center" width="100%">About the Python Documentation</td> -->
+<!-- [- MARK -] <td><img width="32" height="32" align="bottom" border="0" alt="" -->
+<!-- [- MARK -] - src="icons/blank.gif"></td> -->
+<!-- [- MARK -] + src="icons/blank.png"></td> -->
+<!-- [- MARK -] <td><img width="32" height="32" align="bottom" border="0" alt="" -->
+<!-- [- MARK -] - src="icons/blank.gif"></td> -->
+<!-- [- MARK -] + src="icons/blank.png"></td> -->
+<!-- [- MARK -] <td><img width="32" height="32" align="bottom" border="0" alt="" -->
+<!-- [- MARK -] - src="icons/blank.gif"></td> -->
+<!-- [- MARK -] + src="icons/blank.png"></td> -->
+<!-- [- MARK -] </tr> -->
+<!-- [- MARK -] </table> -->
+<!-- [- MARK -] <b class="navlabel">Up:</b> -->
+<!-- [- MARK -] <span class="sectref"> -->
+<!-- [- MARK -] <a href="index.html" title="Python Documentation Index"> -->
+<!-- [- MARK -] END DIFF -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
@@ -58,6 +100,24 @@
<h2>Commenti e domande</h2>
+<!-- [- MARK -] BEGIN DIFF 002 of 2 -->
+<!-- [- MARK -] @@ 58 -->
+<!-- [- MARK -] be sent by email to <a href="mailto:docs a python.org" -->
+<!-- [- MARK -] >docs a python.org</a>. If you find specific errors in -->
+<!-- [- MARK -] this document, please report the bug at the <a -->
+<!-- [- MARK -] href="http://sourceforge.net/bugs/?group_id=5470">Python Bug -->
+<!-- [- MARK -] Tracker</a> at <a href="http://sourceforge.net/">SourceForge</a>. -->
+<!-- [- MARK -] + If you are able to provide suggested text, either to replace -->
+<!-- [- MARK -] + existing incorrect or unclear material, or additional text to -->
+<!-- [- MARK -] + supplement what's already available, we'd appreciate the -->
+<!-- [- MARK -] + contribution. There's no need to worry about text markup; our -->
+<!-- [- MARK -] + documentation team will gladly take care of that. -->
+<!-- [- MARK -] </p> -->
+<!-- [- MARK -] -->
+<!-- [- MARK -] <p> Questions regarding how to use the information in this -->
+<!-- [- MARK -] document should be sent to the Python news group, <a -->
+<!-- [- MARK -] href="news:comp.lang.python">comp.lang.python</a>, or the <a -->
+<!-- [- MARK -] END DIFF -->
<p>
Commenti generici e domande riguardanti questa documentazione
devono essere spediti mediante email presso
Added: python/python/Doc/branches/2.4.3/html/icons/pyfav.png
==============================================================================
Binary file. No diff available.
Modified: python/python/Doc/branches/2.4.3/lib/asttable.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/asttable.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/asttable.tex Fri Jun 2 12:52:55 2006
@@ -73,6 +73,22 @@
\hline
\lineiii{Continue}{}{}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 71
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] \lineiii{Continue}{}{}
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] +\lineiii{Decorators}{\member{nodes}}{List of function decorator expressions}
+%[- MARK -] +\hline
+%[- MARK -] +
+%[- MARK -] \lineiii{Dict}{\member{items}}{}
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] \lineiii{Discard}{\member{expr}}{}
+%[- MARK -] \hline
+%[- MARK -] END DIFF
\hline
\lineiii{Dict}{\member{items}}{}
@@ -91,6 +107,36 @@
\lineiii{Exec}{\member{expr}}{}
\lineiii{}{\member{locals}}{}
\lineiii{}{\member{globals}}{}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 89
+%[- MARK -] \lineiii{Exec}{\member{expr}}{}
+%[- MARK -] \lineiii{}{\member{locals}}{}
+%[- MARK -] \lineiii{}{\member{globals}}{}
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] +\lineiii{FloorDiv}{\member{left}}{}
+%[- MARK -] +\lineiii{}{\member{right}}{}
+%[- MARK -] +\hline
+%[- MARK -] +
+%[- MARK -] \lineiii{For}{\member{assign}}{}
+%[- MARK -] \lineiii{}{\member{list}}{}
+%[- MARK -] \lineiii{}{\member{body}}{}
+%[- MARK -] \lineiii{}{\member{else_}}{}
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] \lineiii{From}{\member{modname}}{}
+%[- MARK -] \lineiii{}{\member{names}}{}
+%[- MARK -] \hline
+%[- MARK -]
+%[- MARK -] -\lineiii{Function}{\member{name}}{name used in def, a string}
+%[- MARK -] +\lineiii{Function}{\member{decorators}}{\class{Decorators} or \code{None}}
+%[- MARK -] +\lineiii{}{\member{name}}{name used in def, a string}
+%[- MARK -] \lineiii{}{\member{argnames}}{list of argument names, as strings}
+%[- MARK -] \lineiii{}{\member{defaults}}{list of default values}
+%[- MARK -] \lineiii{}{\member{flags}}{xxx}
+%[- MARK -] \lineiii{}{\member{doc}}{doc string, a string or \code{None}}
+%[- MARK -] \lineiii{}{\member{code}}{the body of the function}
+%[- MARK -] END DIFF
\hline
\lineiii{For}{\member{assign}}{}
Modified: python/python/Doc/branches/2.4.3/lib/email.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/email.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/email.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,26 @@
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 1
+%[- MARK -] -% Copyright (C) 2001,2002 Python Software Foundation
+%[- MARK -] -% Author: barry a zope.com (Barry Warsaw)
+%[- MARK -] +% Copyright (C) 2001-2004 Python Software Foundation
+%[- MARK -] +% Author: barry a python.org (Barry Warsaw)
+%[- MARK -]
+%[- MARK -] \section{\module{email} ---
+%[- MARK -] An email and MIME handling package}
+%[- MARK -]
+%[- MARK -] \declaremodule{standard}{email}
+%[- MARK -] \modulesynopsis{Package supporting the parsing, manipulating, and
+%[- MARK -] generating email messages, including MIME documents.}
+%[- MARK -] -\moduleauthor{Barry A. Warsaw}{barry a zope.com}
+%[- MARK -] -\sectionauthor{Barry A. Warsaw}{barry a zope.com}
+%[- MARK -] +\moduleauthor{Barry A. Warsaw}{barry a python.org}
+%[- MARK -] +\sectionauthor{Barry A. Warsaw}{barry a python.org}
+%[- MARK -]
+%[- MARK -] \versionadded{2.2}
+%[- MARK -]
+%[- MARK -] The \module{email} package is a library for managing email messages,
+%[- MARK -] including MIME and other \rfc{2822}-based message documents. It
+%[- MARK -] END DIFF
% Copyright (C) 2001,2002 Python Software Foundation
% Author: barry a zope.com (Barry Warsaw)
@@ -10,6 +33,21 @@
\moduleauthor{Barry A. Warsaw}{barry a zope.com}
\sectionauthor{Barry A. Warsaw}{barry a zope.com}
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 20
+%[- MARK -] \module{mimecntl}. It is specifically \emph{not} designed to do any
+%[- MARK -] sending of email messages to SMTP (\rfc{2821}) servers; that is the
+%[- MARK -] function of the \refmodule{smtplib} module. The \module{email}
+%[- MARK -] package attempts to be as RFC-compliant as possible, supporting in
+%[- MARK -] addition to \rfc{2822}, such MIME-related RFCs as
+%[- MARK -] -\rfc{2045}-\rfc{2047}, and \rfc{2231}.
+%[- MARK -] +\rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
+%[- MARK -]
+%[- MARK -] The primary distinguishing feature of the \module{email} package is
+%[- MARK -] that it splits the parsing and generating of email messages from the
+%[- MARK -] internal \emph{object model} representation of email. Applications
+%[- MARK -] using the \module{email} package deal primarily with objects; you can
+%[- MARK -] END DIFF
\versionadded{2.2}
Il package \module{email} è una libreria per gestire i messaggi di
@@ -80,6 +118,68 @@
\input{emailcharsets}
\subsection{Encoders -- Codificatori}
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 77
+%[- MARK -] \input{emailcharsets}
+%[- MARK -]
+%[- MARK -] \subsection{Encoders}
+%[- MARK -] \input{emailencoders}
+%[- MARK -]
+%[- MARK -] -\subsection{Exception classes}
+%[- MARK -] +\subsection{Exception and Defect classes}
+%[- MARK -] \input{emailexc}
+%[- MARK -]
+%[- MARK -] \subsection{Miscellaneous utilities}
+%[- MARK -] \input{emailutil}
+%[- MARK -]
+%[- MARK -] \subsection{Iterators}
+%[- MARK -] \input{emailiter}
+%[- MARK -]
+%[- MARK -] -\subsection{Differences from \module{email} v1 (up to Python 2.2.1)}
+%[- MARK -] +\subsection{Package History}
+%[- MARK -]
+%[- MARK -] Version 1 of the \module{email} package was bundled with Python
+%[- MARK -] releases up to Python 2.2.1. Version 2 was developed for the Python
+%[- MARK -] 2.3 release, and backported to Python 2.2.2. It was also available as
+%[- MARK -] -a separate distutils based package. \module{email} version 2 is
+%[- MARK -] -almost entirely backward compatible with version 1, with the
+%[- MARK -] -following differences:
+%[- MARK -] +a separate distutils-based package, and is compatible back to Python 2.1.
+%[- MARK -] +
+%[- MARK -] +\module{email} version 3.0 was released with Python 2.4 and as a separate
+%[- MARK -] +distutils-based package. It is compatible back to Python 2.3.
+%[- MARK -] +
+%[- MARK -] +Here are the differences between \module{email} version 3 and version 2:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item The \class{FeedParser} class was introduced, and the \class{Parser}
+%[- MARK -] + class was implemented in terms of the \class{FeedParser}. All parsing
+%[- MARK -] + there for is non-strict, and parsing will make a best effort never to
+%[- MARK -] + raise an exception. Problems found while parsing messages are stored in
+%[- MARK -] + the message's \var{defect} attribute.
+%[- MARK -] +
+%[- MARK -] +\item All aspects of the API which raised \exception{DeprecationWarning}s in
+%[- MARK -] + version 2 have been removed. These include the \var{_encoder} argument
+%[- MARK -] + to the \class{MIMEText} constructor, the \method{Message.add_payload()}
+%[- MARK -] + method, the \function{Utils.dump_address_pair()} function, and the
+%[- MARK -] + functions \function{Utils.decode()} and \function{Utils.encode()}.
+%[- MARK -] +
+%[- MARK -] +\item New \exception{DeprecationWarning}s have been added to:
+%[- MARK -] + \method{Generator.__call__()}, \method{Message.get_type()},
+%[- MARK -] + \method{Message.get_main_type()}, \method{Message.get_subtype()}, and
+%[- MARK -] + the \var{strict} argument to the \class{Parser} class. These are
+%[- MARK -] + expected to be removed in email 3.1.
+%[- MARK -] +
+%[- MARK -] +\item Support for Pythons earlier than 2.3 has been removed.
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Here are the differences between \module{email} version 2 and version 1:
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -] \item The \module{email.Header} and \module{email.Charset} modules
+%[- MARK -] have been added.
+%[- MARK -]
+%[- MARK -] END DIFF
\input{emailencoders}
\subsection{Classi per le eccezioni}
@@ -220,6 +320,21 @@
\item Il metodo \method{addheader()} è stato rinominato in \method{add_header()}.
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 215
+%[- MARK -]
+%[- MARK -] \item The method \method{addheader()} was renamed to \method{add_header()}.
+%[- MARK -]
+%[- MARK -] \item The method \method{gettype()} was renamed to \method{get_type()}.
+%[- MARK -]
+%[- MARK -] -\item The method\method{getmaintype()} was renamed to
+%[- MARK -] +\item The method \method{getmaintype()} was renamed to
+%[- MARK -] \method{get_main_type()}.
+%[- MARK -]
+%[- MARK -] \item The method \method{getsubtype()} was renamed to
+%[- MARK -] \method{get_subtype()}.
+%[- MARK -]
+%[- MARK -] END DIFF
\item il metodo \method{gettype()} è stato rinominato in \method{get_type()}.
\item il metodo \method{getmaintype()} è stato rinominato in
Modified: python/python/Doc/branches/2.4.3/lib/emailencoders.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailencoders.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailencoders.tex Fri Jun 2 12:52:55 2006
@@ -5,6 +5,29 @@
bisogno di codificare il carico utile per il trasporto attraverso
server email compatibili. Questo è vero specialmente per messaggi di
tipo \mimetype{image/*} e \mimetype{text/*} che contengono dati
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 6
+%[- MARK -] This is especially true for \mimetype{image/*} and \mimetype{text/*}
+%[- MARK -] type messages containing binary data.
+%[- MARK -]
+%[- MARK -] The \module{email} package provides some convenient encodings in its
+%[- MARK -] \module{Encoders} module. These encoders are actually used by the
+%[- MARK -] -\class{MIMEImage} and \class{MIMEText} class constructors to provide default
+%[- MARK -] -encodings. All encoder functions take exactly one argument, the
+%[- MARK -] -message object to encode. They usually extract the payload, encode
+%[- MARK -] -it, and reset the payload to this newly encoded value. They should also
+%[- MARK -] -set the \mailheader{Content-Transfer-Encoding} header as appropriate.
+%[- MARK -] +\class{MIMEAudio} and \class{MIMEImage} class constructors to provide default
+%[- MARK -] +encodings. All encoder functions take exactly one argument, the message
+%[- MARK -] +object to encode. They usually extract the payload, encode it, and reset the
+%[- MARK -] +payload to this newly encoded value. They should also set the
+%[- MARK -] +\mailheader{Content-Transfer-Encoding} header as appropriate.
+%[- MARK -]
+%[- MARK -] Here are the encoding functions provided:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{encode_quopri}{msg}
+%[- MARK -] Encodes the payload into quoted-printable form and sets the
+%[- MARK -] END DIFF
binari.
Il package \module{email} fornisce alcuni codificatori pratici nel
Modified: python/python/Doc/branches/2.4.3/lib/emailexc.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailexc.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailexc.tex Fri Jun 2 12:52:55 2006
@@ -46,6 +46,47 @@
era già uno scalare ed il tipo principale di \mailheader{Content-Type}
del messaggio non sia \mimetype{multipart} o è mancante.
\exception{MultipartConversionError} eredita da
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 50
+%[- MARK -] Since \method{Message.add_payload()} is deprecated, this exception is
+%[- MARK -] rarely raised in practice. However the exception may also be raised
+%[- MARK -] if the \method{attach()} method is called on an instance of a class
+%[- MARK -] derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
+%[- MARK -] \end{excclassdesc}
+%[- MARK -] +
+%[- MARK -] +Here's the list of the defects that the \class{FeedParser} can find while
+%[- MARK -] +parsing messages. Note that the defects are added to the message where the
+%[- MARK -] +problem was found, so for example, if a message nested inside a
+%[- MARK -] +\mimetype{multipart/alternative} had a malformed header, that nested message
+%[- MARK -] +object would have a defect, but the containing messages would not.
+%[- MARK -] +
+%[- MARK -] +All defect classes are subclassed from \class{email.Errors.MessageDefect}, but
+%[- MARK -] +this class is \emph{not} an exception!
+%[- MARK -] +
+%[- MARK -] +\versionadded[All the defect classes were added]{2.4}
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a
+%[- MARK -] + multipart, but had no \mimetype{boundary} parameter.
+%[- MARK -] +
+%[- MARK -] +\item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the
+%[- MARK -] + \mailheader{Content-Type} header was never found.
+%[- MARK -] +
+%[- MARK -] +\item \class{FirstHeaderLineIsContinuationDefect} -- The message had a
+%[- MARK -] + continuation line as its first header line.
+%[- MARK -] +
+%[- MARK -] +\item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found
+%[- MARK -] + in the middle of a header block.
+%[- MARK -] +
+%[- MARK -] +\item \class{MalformedHeaderDefect} -- A header was found that was missing a
+%[- MARK -] + colon, or was otherwise malformed.
+%[- MARK -] +
+%[- MARK -] +\item \class{MultipartInvariantViolationDefect} -- A message claimed to be a
+%[- MARK -] + \mimetype{multipart}, but no subparts were found. Note that when a
+%[- MARK -] + message has this defect, its \method{is_multipart()} method may return
+%[- MARK -] + false even though its content type claims to be \mimetype{multipart}.
+%[- MARK -] +\end{itemize}
+%[- MARK -] END DIFF
\exception{MessageError} e dal built-in \exception{TypeError}.
Poiché \method{Message.add_payload()} è deprecato, questa eccezione
Modified: python/python/Doc/branches/2.4.3/lib/emailheaders.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailheaders.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailheaders.tex Fri Jun 2 12:52:55 2006
@@ -6,6 +6,21 @@
ampiamente usata quando la maggior parte delle email erano composte
esclusivamente da caratteri \ASCII{}. La \rfc{2822} è una
specificazione scritta assumendo che le email contenessero solo
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 8
+%[- MARK -] contains only 7-bit \ASCII{} characters.
+%[- MARK -]
+%[- MARK -] Of course, as email has been deployed worldwide, it has become
+%[- MARK -] internationalized, such that language specific character sets can now
+%[- MARK -] be used in email messages. The base standard still requires email
+%[- MARK -] -messages to be transfered using only 7-bit \ASCII{} characters, so a
+%[- MARK -] +messages to be transferred using only 7-bit \ASCII{} characters, so a
+%[- MARK -] slew of RFCs have been written describing how to encode email
+%[- MARK -] containing non-\ASCII{} characters into \rfc{2822}-compliant format.
+%[- MARK -] These RFCs include \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
+%[- MARK -] The \module{email} package supports these standards in its
+%[- MARK -] \module{email.Header} and \module{email.Charset} modules.
+%[- MARK -] END DIFF
caratteri \ASCII{} a 7 bit.
Naturalmente, come le email si sono diffuse a livello mondiale, sono
@@ -169,6 +184,21 @@
contenente il nome dell'insieme dei caratteri specificato nella
codifica della stringa.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 155
+%[- MARK -] Here's an example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> from email.Header import decode_header
+%[- MARK -] >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
+%[- MARK -] -[('p\\xf6stal', 'iso-8859-1')]
+%[- MARK -] +[('p\xf6stal', 'iso-8859-1')]
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{,
+%[- MARK -] header_name\optional{, continuation_ws}}}}
+%[- MARK -] END DIFF
Ecco un esempio:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/emailmessage.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailmessage.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailmessage.tex Fri Jun 2 12:52:55 2006
@@ -42,6 +42,26 @@
Restituisce l'intero messaggio in una stringa. Quando l'argomento
facoltativo \var{unixfrom} è \code{True}, l'intestazione della busta
viene inclusa nella stringa restituita. Il valore predefinito di
+%[- MARK -] BEGIN DIFF 001 of 5
+%[- MARK -] @@ 35
+%[- MARK -] \begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
+%[- MARK -] Return the entire message flatten as a string. When optional
+%[- MARK -] \var{unixfrom} is \code{True}, the envelope header is included in the
+%[- MARK -] returned string. \var{unixfrom} defaults to \code{False}.
+%[- MARK -]
+%[- MARK -] -Note that this method is provided as a convenience and may not always
+%[- MARK -] -format the message the way you want. For more flexibility,
+%[- MARK -] -instantiate a \class{Generator} instance and use its
+%[- MARK -] +Note that this method is provided as a convenience and may not always format
+%[- MARK -] +the message the way you want. For example, by default it mangles lines that
+%[- MARK -] +begin with \code{From }. For more flexibility, instantiate a
+%[- MARK -] +\class{Generator} instance and use its
+%[- MARK -] \method{flatten()} method directly. For example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] from cStringIO import StringIO
+%[- MARK -] from email.Generator import Generator
+%[- MARK -] END DIFF
\var{unixfrom} è \code{False}.
Notare che questo metodo viene fornito per comodità ma non può
@@ -387,6 +407,34 @@
VALUE)}. Notare che sia\code{CHARSET} che \code{LANGUAGE} possono
essere \code{None}, in qual caso doveva considerare \code{VALUE} come
codificato nel charset \code{us-ascii}. Si può generalmente ignorare
+%[- MARK -] BEGIN DIFF 002 of 5
+%[- MARK -] @@ 357
+%[- MARK -] the form \code{(CHARSET, LANGUAGE, VALUE)}. Note that both \code{CHARSET} and
+%[- MARK -] \code{LANGUAGE} can be \code{None}, in which case you should consider
+%[- MARK -] \code{VALUE} to be encoded in the \code{us-ascii} charset. You can
+%[- MARK -] usually ignore \code{LANGUAGE}.
+%[- MARK -]
+%[- MARK -] -Your application should be prepared to deal with 3-tuple return
+%[- MARK -] -values, and can convert the parameter to a Unicode string like so:
+%[- MARK -] +If your application doesn't care whether the parameter was encoded as in
+%[- MARK -] +\rfc{2231}, you can collapse the parameter value by calling
+%[- MARK -] +\function{email.Utils.collapse_rfc2231_value()}, passing in the return value
+%[- MARK -] +from \method{get_param()}. This will return a suitably decoded Unicode string
+%[- MARK -] +whn the value is a tuple, or the original string unquoted if it isn't. For
+%[- MARK -] +example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -param = msg.get_param('foo')
+%[- MARK -] -if isinstance(param, tuple):
+%[- MARK -] - param = unicode(param[2], param[0] or 'us-ascii')
+%[- MARK -] +rawparam = msg.get_param('foo')
+%[- MARK -] +param = email.Utils.collapse_rfc2231_value(rawparam)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] In any case, the parameter value (either the returned string, or the
+%[- MARK -] \code{VALUE} item in the 3-tuple) is always unquoted, unless
+%[- MARK -] \var{unquote} is set to \code{False}.
+%[- MARK -] END DIFF
\code{LANGUAGE}.
Un'applicazione deve essere pronta a gestire i valori
@@ -462,6 +510,28 @@
\mailheader{MIME-Version}.
\versionadded{2.2.2}
+%[- MARK -] BEGIN DIFF 003 of 5
+%[- MARK -] @@ 429
+%[- MARK -] \versionadded{2.2.2}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
+%[- MARK -] Return the value of the \code{filename} parameter of the
+%[- MARK -] -\mailheader{Content-Disposition} header of the message, or \var{failobj} if
+%[- MARK -] -either the header is missing, or has no \code{filename} parameter.
+%[- MARK -] -The returned string will always be unquoted as per
+%[- MARK -] -\method{Utils.unquote()}.
+%[- MARK -] +\mailheader{Content-Disposition} header of the message. If the header does
+%[- MARK -] +not have a \code{filename} parameter, this method falls back to looking for
+%[- MARK -] +the \code{name} parameter. If neither is found, or the header is missing,
+%[- MARK -] +then \var{failobj} is returned. The returned string will always be unquoted
+%[- MARK -] +as per \method{Utils.unquote()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
+%[- MARK -] Return the value of the \code{boundary} parameter of the
+%[- MARK -] \mailheader{Content-Type} header of the message, or \var{failobj} if either
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
@@ -533,6 +603,21 @@
sotto parte.
Ecco un esempio che stampa il tipo di MIME di tutte le parti di una
+%[- MARK -] BEGIN DIFF 004 of 5
+%[- MARK -] @@ 496
+%[- MARK -] Here's an example that prints the MIME type of every part of a
+%[- MARK -] multipart message structure:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> for part in msg.walk():
+%[- MARK -] ->>> print part.get_content_type()
+%[- MARK -] +... print part.get_content_type()
+%[- MARK -] multipart/report
+%[- MARK -] text/plain
+%[- MARK -] message/delivery-status
+%[- MARK -] text/plain
+%[- MARK -] text/plain
+%[- MARK -] END DIFF
struttura di messaggio multipart:
\begin{verbatim}
@@ -590,6 +675,57 @@
che se si vuole assicurare che un fine riga sia stampato dopo il
limite di chiusura del \mimetype{multipart}, si deve impostare \var{epilogue}
ad una stringa vuota.
+%[- MARK -] BEGIN DIFF 005 of 5
+%[- MARK -] @@ 547
+%[- MARK -] practical sense. The upshot is that if you want to ensure that a
+%[- MARK -] newline get printed after your closing \mimetype{multipart} boundary,
+%[- MARK -] set the \var{epilogue} to the empty string.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] -\subsubsection{Deprecated methods}
+%[- MARK -] +\begin{datadesc}{defects}
+%[- MARK -] +The \var{defects} attribute contains a list of all the problems found when
+%[- MARK -] +parsing this message. See \refmodule{email.Errors} for a detailed description
+%[- MARK -] +of the possible parsing defects.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{datadesc}
+%[- MARK -]
+%[- MARK -] -The following methods are deprecated in \module{email} version 2.
+%[- MARK -] -They are documented here for completeness.
+%[- MARK -] +\subsubsection{Deprecated methods}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[Message]{add_payload}{payload}
+%[- MARK -] -Add \var{payload} to the message object's existing payload. If, prior
+%[- MARK -] -to calling this method, the object's payload was \code{None}
+%[- MARK -] -(i.e. never before set), then after this method is called, the payload
+%[- MARK -] -will be the argument \var{payload}.
+%[- MARK -] -
+%[- MARK -] -If the object's payload was already a list
+%[- MARK -] -(i.e. \method{is_multipart()} returns \code{True}), then \var{payload} is
+%[- MARK -] -appended to the end of the existing payload list.
+%[- MARK -] -
+%[- MARK -] -For any other type of existing payload, \method{add_payload()} will
+%[- MARK -] -transform the new payload into a list consisting of the old payload
+%[- MARK -] -and \var{payload}, but only if the document is already a MIME
+%[- MARK -] -multipart document. This condition is satisfied if the message's
+%[- MARK -] -\mailheader{Content-Type} header's main type is either
+%[- MARK -] -\mimetype{multipart}, or there is no \mailheader{Content-Type}
+%[- MARK -] -header. In any other situation,
+%[- MARK -] -\exception{MultipartConversionError} is raised.
+%[- MARK -] +\versionchanged[The \method{add_payload()} method was removed; use the
+%[- MARK -] +\method{attach()} method instead]{2.4}
+%[- MARK -]
+%[- MARK -] -\deprecated{2.2.2}{Use the \method{attach()} method instead.}
+%[- MARK -] -\end{methoddesc}
+%[- MARK -] +The following methods are deprecated. They are documented here for
+%[- MARK -] +completeness.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Message]{get_type}{\optional{failobj}}
+%[- MARK -] Return the message's content type, as a string of the form
+%[- MARK -] \mimetype{maintype/subtype} as taken from the
+%[- MARK -] \mailheader{Content-Type} header.
+%[- MARK -] END DIFF
\end{datadesc}
\subsubsection{Metodi deprecati}
Modified: python/python/Doc/branches/2.4.3/lib/emailmimebase.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailmimebase.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailmimebase.tex Fri Jun 2 12:52:55 2006
@@ -155,6 +155,32 @@
L'argomento facoltativo \var{_subtype} imposta il sotto tipo del
messaggio; il valore predefinito è \mimetype{rfc822}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 140
+%[- MARK -]
+%[- MARK -] Optional \var{_subtype} sets the subtype of the message; it defaults
+%[- MARK -] to \mimetype{rfc822}.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] -\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
+%[- MARK -] - _charset\optional{, _encoder}}}}
+%[- MARK -] -
+%[- MARK -] +\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}
+%[- MARK -] A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
+%[- MARK -] used to create MIME objects of major type \mimetype{text}.
+%[- MARK -] \var{_text} is the string for the payload. \var{_subtype} is the
+%[- MARK -] minor type and defaults to \mimetype{plain}. \var{_charset} is the
+%[- MARK -] character set of the text and is passed as a parameter to the
+%[- MARK -] \class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No
+%[- MARK -] guessing or encoding is performed on the text data.
+%[- MARK -]
+%[- MARK -] -\deprecated{2.2.2}{The \var{_encoding} argument has been deprecated.
+%[- MARK -] -Encoding now happens implicitly based on the \var{_charset} argument.}
+%[- MARK -] +\versionchanged[The previously deprecated \var{_encoding} argument has
+%[- MARK -] +been removed. Encoding happens implicitly based on the \var{_charset}
+%[- MARK -] +argument]{2.4}
+%[- MARK -] \end{classdesc}
+%[- MARK -] END DIFF
\end{classdesc}
\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
Modified: python/python/Doc/branches/2.4.3/lib/emailparser.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailparser.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailparser.tex Fri Jun 2 12:52:55 2006
@@ -18,6 +18,129 @@
messaggio. Per messaggi MIME, l'oggetto principale restituirà
\code{True} tramite il suo metodo \method{is_multipart()} e le
sotto parti saranno accessibili tramite i metodi \method{get_payload()}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 16
+%[- MARK -] be a string containing the text of the message. For MIME
+%[- MARK -] messages, the root object will return \code{True} from its
+%[- MARK -] \method{is_multipart()} method, and the subparts can be accessed via
+%[- MARK -] the \method{get_payload()} and \method{walk()} methods.
+%[- MARK -]
+%[- MARK -] +There are actually two parser interfaces available for use, the classic
+%[- MARK -] +\class{Parser} API and the incremental \class{FeedParser} API. The classic
+%[- MARK -] +\class{Parser} API is fine if you have the entire text of the message in
+%[- MARK -] +memory as a string, or if the entire message lives in a file on the file
+%[- MARK -] +system. \class{FeedParser} is more appropriate for when you're reading the
+%[- MARK -] +message from a stream which might block waiting for more input (e.g. reading
+%[- MARK -] +an email message from a socket). The \class{FeedParser} can consume and parse
+%[- MARK -] +the message incrementally, and only returns the root object when you close the
+%[- MARK -] +parser\footnote{As of email package version 3.0, introduced in
+%[- MARK -] +Python 2.4, the classic \class{Parser} was re-implemented in terms of the
+%[- MARK -] +\class{FeedParser}, so the semantics and results are identical between the two
+%[- MARK -] +parsers.}.
+%[- MARK -] +
+%[- MARK -] Note that the parser can be extended in limited ways, and of course
+%[- MARK -] you can implement your own parser completely from scratch. There is
+%[- MARK -] no magical connection between the \module{email} package's bundled
+%[- MARK -] parser and the \class{Message} class, so your custom parser can create
+%[- MARK -] message object trees any way it finds necessary.
+%[- MARK -]
+%[- MARK -] -The primary parser class is \class{Parser} which parses both the
+%[- MARK -] -headers and the payload of the message. In the case of
+%[- MARK -] -\mimetype{multipart} messages, it will recursively parse the body of
+%[- MARK -] -the container message. Two modes of parsing are supported,
+%[- MARK -] -\emph{strict} parsing, which will usually reject any non-RFC compliant
+%[- MARK -] -message, and \emph{lax} parsing, which attempts to adjust for common
+%[- MARK -] -MIME formatting problems.
+%[- MARK -] +\subsubsection{FeedParser API}
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +
+%[- MARK -] +The \class{FeedParser} provides an API that is conducive to incremental
+%[- MARK -] +parsing of email messages, such as would be necessary when reading the text of
+%[- MARK -] +an email message from a source that can block (e.g. a socket). The
+%[- MARK -] +\class{FeedParser} can of course be used to parse an email message fully
+%[- MARK -] +contained in a string or a file, but the classic \class{Parser} API may be
+%[- MARK -] +more convenient for such use cases. The semantics and results of the two
+%[- MARK -] +parser APIs are identical.
+%[- MARK -] +
+%[- MARK -] +The \class{FeedParser}'s API is simple; you create an instance, feed it a
+%[- MARK -] +bunch of text until there's no more to feed it, then close the parser to
+%[- MARK -] +retrieve the root message object. The \class{FeedParser} is extremely
+%[- MARK -] +accurate when parsing standards-compliant messages, and it does a very good
+%[- MARK -] +job of parsing non-compliant messages, providing information about how a
+%[- MARK -] +message was deemed broken. It will populate a message object's \var{defects}
+%[- MARK -] +attribute with a list of any problems it found in a message. See the
+%[- MARK -] +\refmodule{email.Errors} module for the list of defects that it can find.
+%[- MARK -] +
+%[- MARK -] +Here is the API for the \class{FeedParser}:
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{FeedParser}{\optional{_factory}}
+%[- MARK -] +Create a \class{FeedParser} instance. Optional \var{_factory} is a
+%[- MARK -] +no-argument callable that will be called whenever a new message object is
+%[- MARK -] +needed. It defaults to the \class{email.Message.Message} class.
+%[- MARK -] +\end{classdesc}
+%[- MARK -]
+%[- MARK -] -The \module{email.Parser} module also provides a second class, called
+%[- MARK -] +\begin{methoddesc}[FeedParser]{feed}{data}
+%[- MARK -] +Feed the \class{FeedParser} some more data. \var{data} should be a
+%[- MARK -] +string containing one or more lines. The lines can be partial and the
+%[- MARK -] +\class{FeedParser} will stitch such partial lines together properly. The
+%[- MARK -] +lines in the string can have any of the common three line endings, carriage
+%[- MARK -] +return, newline, or carriage return and newline (they can even be mixed).
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[FeedParser]{close}{}
+%[- MARK -] +Closing a \class{FeedParser} completes the parsing of all previously fed data,
+%[- MARK -] +and returns the root message object. It is undefined what happens if you feed
+%[- MARK -] +more data to a closed \class{FeedParser}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{Parser class API}
+%[- MARK -] +
+%[- MARK -] +The \class{Parser} provides an API that can be used to parse a message when
+%[- MARK -] +the complete contents of the message are available in a string or file. The
+%[- MARK -] +\module{email.Parser} module also provides a second class, called
+%[- MARK -] \class{HeaderParser} which can be used if you're only interested in
+%[- MARK -] the headers of the message. \class{HeaderParser} can be much faster in
+%[- MARK -] these situations, since it does not attempt to parse the message body,
+%[- MARK -] instead setting the payload to the raw body as a string.
+%[- MARK -] \class{HeaderParser} has the same API as the \class{Parser} class.
+%[- MARK -]
+%[- MARK -] -\subsubsection{Parser class API}
+%[- MARK -] -
+%[- MARK -] \begin{classdesc}{Parser}{\optional{_class\optional{, strict}}}
+%[- MARK -] The constructor for the \class{Parser} class takes an optional
+%[- MARK -] argument \var{_class}. This must be a callable factory (such as a
+%[- MARK -] function or a class), and it is used whenever a sub-message object
+%[- MARK -] needs to be created. It defaults to \class{Message} (see
+%[- MARK -] \refmodule{email.Message}). The factory will be called without
+%[- MARK -] arguments.
+%[- MARK -]
+%[- MARK -] -The optional \var{strict} flag specifies whether strict or lax parsing
+%[- MARK -] -should be performed. Normally, when things like MIME terminating
+%[- MARK -] -boundaries are missing, or when messages contain other formatting
+%[- MARK -] -problems, the \class{Parser} will raise a
+%[- MARK -] -\exception{MessageParseError}. However, when lax parsing is enabled,
+%[- MARK -] -the \class{Parser} will attempt to work around such broken formatting
+%[- MARK -] -to produce a usable message structure (this doesn't mean
+%[- MARK -] -\exception{MessageParseError}s are never raised; some ill-formatted
+%[- MARK -] -messages just can't be parsed). The \var{strict} flag defaults to
+%[- MARK -] -\code{False} since lax parsing usually provides the most convenient
+%[- MARK -] -behavior.
+%[- MARK -] +The optional \var{strict} flag is ignored. \deprecated{2.4}{Because the
+%[- MARK -] +\class{Parser} class is a backward compatible API wrapper around the
+%[- MARK -] +new-in-Python 2.4 \class{FeedParser}, \emph{all} parsing is effectively
+%[- MARK -] +non-strict. You should simply stop passing a \var{strict} flag to the
+%[- MARK -] +\class{Parser} constructor.}
+%[- MARK -]
+%[- MARK -] \versionchanged[The \var{strict} flag was added]{2.2.2}
+%[- MARK -] +\versionchanged[The \var{strict} flag was deprecated]{2.4}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] The other public \class{Parser} methods are:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
+%[- MARK -] END DIFF
e \method{walk()}.
Notare che il parser può essere esteso in modo illimitato ed ovviamente
@@ -152,6 +275,24 @@
sotto messaggio per il loro carico utile. Il messaggio
contenitore esterno restituirà \code{True} per
\method{is_multipart()} ed il loro metodo \method{get_payload()}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 147
+%[- MARK -] (e.g. \mimetype{message/delivery-status} and
+%[- MARK -] \mimetype{message/rfc822}) will also be parsed as container
+%[- MARK -] object containing a list payload of length 1. Their
+%[- MARK -] \method{is_multipart()} method will return \code{True}. The
+%[- MARK -] single element in the list payload will be a sub-message object.
+%[- MARK -] +
+%[- MARK -] +\item Some non-standards compliant messages may not be internally consistent
+%[- MARK -] + about their \mimetype{multipart}-edness. Such messages may have a
+%[- MARK -] + \mailheader{Content-Type} header of type \mimetype{multipart}, but their
+%[- MARK -] + \method{is_multipart()} method may return \code{False}. If such
+%[- MARK -] + messages were parsed with the \class{FeedParser}, they will have an
+%[- MARK -] + instance of the \class{MultipartInvariantViolationDefect} class in their
+%[- MARK -] + \var{defects} attribute list. See \refmodule{email.Errors} for
+%[- MARK -] + details.
+%[- MARK -] \end{itemize}
+%[- MARK -] END DIFF
restituirà la lista della sotto parti di \class{Message}.
\item La maggior parte dei messaggi con content type di
Modified: python/python/Doc/branches/2.4.3/lib/emailutil.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/emailutil.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/emailutil.tex Fri Jun 2 12:52:55 2006
@@ -1,4 +1,19 @@
\declaremodule{standard}{email.Utils}
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 1
+%[- MARK -] \declaremodule{standard}{email.Utils}
+%[- MARK -] \modulesynopsis{Miscellaneous email package utilities.}
+%[- MARK -]
+%[- MARK -] -There are several useful utilities provided with the \module{email}
+%[- MARK -] -package.
+%[- MARK -] +There are several useful utilities provided in the \module{email.Utils}
+%[- MARK -] +module:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{quote}{str}
+%[- MARK -] Return a new string with backslashes in \var{str} replaced by two
+%[- MARK -] backslashes, and double quotes replaced by backslash-double quote.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\modulesynopsis{Varie utilità del package email.}
Ci sono varie utilità molto comode fornite con il package
@@ -86,6 +101,21 @@
per la differenza di timezone. Questo può causare un piccolo errore
intorno ai cambiamenti nell'ora legale, anche se non ci si deve
preoccupare nell'uso comune.
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 82
+%[- MARK -] for the timezone difference. This may yield a slight error around
+%[- MARK -] changes in daylight savings time, though not worth worrying about for
+%[- MARK -] common use.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}}}
+%[- MARK -] +\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}}
+%[- MARK -] Returns a date string as per \rfc{2822}, e.g.:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] Fri, 09 Nov 2001 01:08:47 -0000
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}}}
@@ -99,6 +129,25 @@
Il parametro facoltativo \var{timeval}, se passato, è un valore in
virgola mobile come accettato da \function{time.gmtime()} e
\function{time.localtime()}, altrimenti viene utilizzato il tempo
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 97
+%[- MARK -]
+%[- MARK -] Optional \var{localtime} is a flag that when \code{True}, interprets
+%[- MARK -] \var{timeval}, and returns a date relative to the local timezone
+%[- MARK -] instead of UTC, properly taking daylight savings time into account.
+%[- MARK -] The default is \code{False} meaning UTC is used.
+%[- MARK -] +
+%[- MARK -] +Optional \var{usegmt} is a flag that when \code{True}, outputs a
+%[- MARK -] +date string with the timezone as an ascii string \code{GMT}, rather
+%[- MARK -] +than a numeric \code{-0000}. This is needed for some protocols (such
+%[- MARK -] +as HTTP). This only applies when \var{localtime} is \code{False}.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{make_msgid}{\optional{idstring}}
+%[- MARK -] Returns a string suitable for an \rfc{2822}-compliant
+%[- MARK -] \mailheader{Message-ID} header. Optional \var{idstring} if given, is
+%[- MARK -] END DIFF
corrente.
Il parametro facoltativo \var{localtime} è un'opzione che, quando
@@ -126,6 +175,57 @@
viene passato, \var{s} viene restituita così com'è. Se \var{charset}
viene passato, ma non \var{language}, la stringa viene codificata
utilizzando una stringa vuota per \var{language}.
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 117
+%[- MARK -] and language name to use. If neither is given, \var{s} is returned
+%[- MARK -] as-is. If \var{charset} is given but \var{language} is not, the
+%[- MARK -] string is encoded using the empty string for \var{language}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{,
+%[- MARK -] + fallback_charset}}}
+%[- MARK -] +When a header parameter is encoded in \rfc{2231} format,
+%[- MARK -] +\method{Message.get_param()} may return a 3-tuple containing the character
+%[- MARK -] +set, language, and value. \function{collapse_rfc2231_value()} turns this into
+%[- MARK -] +a unicode string. Optional \var{errors} is passed to the \var{errors}
+%[- MARK -] +argument of the built-in \function{unicode()} function; it defaults to
+%[- MARK -] +\code{replace}. Optional \var{fallback_charset} specifies the character set
+%[- MARK -] +to use if the one in the \rfc{2231} header is not known by Python; it defaults
+%[- MARK -] +to \code{us-ascii}.
+%[- MARK -] +
+%[- MARK -] +For convenience, if the \var{value} passed to
+%[- MARK -] +\function{collapse_rfc2231_value()} is not a tuple, it should be a string and
+%[- MARK -] +it is returned unquoted.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{decode_params}{params}
+%[- MARK -] Decode parameters list according to \rfc{2231}. \var{params} is a
+%[- MARK -] sequence of 2-tuples containing elements of the form
+%[- MARK -] \code{(content-type, string-value)}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -The following functions have been deprecated:
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{dump_address_pair}{pair}
+%[- MARK -] -\deprecated{2.2.2}{Use \function{formataddr()} instead.}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +\versionchanged[The \function{dump_address_pair()} function has been removed;
+%[- MARK -] +use \function{formataddr()} instead]{2.4}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{decode}{s}
+%[- MARK -] -\deprecated{2.2.2}{Use \method{Header.decode_header()} instead.}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
+%[- MARK -] -\deprecated{2.2.2}{Use \method{Header.encode()} instead.}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +\versionchanged[The \function{decode()} function has been removed; use the
+%[- MARK -] +\method{Header.decode_header()} method instead]{2.4}
+%[- MARK -]
+%[- MARK -] +\versionchanged[The \function{encode()} function has been removed; use the
+%[- MARK -] +\method{Header.encode()} method instead]{2.4}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{decode_params}{params}
Modified: python/python/Doc/branches/2.4.3/lib/language.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/language.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/language.tex Fri Jun 2 12:52:55 2006
@@ -1,4 +1,18 @@
\chapter{Servizi del linguaggio Python
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 1
+%[- MARK -] \chapter{Python Language Services
+%[- MARK -] \label{language}}
+%[- MARK -]
+%[- MARK -] Python provides a number of modules to assist in working with the
+%[- MARK -] -Python language. These module support tokenizing, parsing, syntax
+%[- MARK -] +Python language. These modules support tokenizing, parsing, syntax
+%[- MARK -] analysis, bytecode disassembly, and various other facilities.
+%[- MARK -]
+%[- MARK -] These modules include:
+%[- MARK -]
+%[- MARK -] \localmoduletable
+%[- MARK -] END DIFF
\label{language}}
Python fornisce numerosi moduli per aiutarvi a lavorare con il
Modified: python/python/Doc/branches/2.4.3/lib/libarray.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libarray.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libarray.tex Fri Jun 2 12:52:55 2006
@@ -38,6 +38,29 @@
può rappresentare l'intera estensione degli interi(long) senza segno del C.
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 39
+%[- MARK -] The module defines the following type:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{array}{typecode\optional{, initializer}}
+%[- MARK -] Return a new array whose items are restricted by \var{typecode},
+%[- MARK -] and initialized from the optional \var{initializer} value, which
+%[- MARK -] -must be a list or a string. The list or string is passed to the
+%[- MARK -] +must be a list, string, or iterable over elements of the
+%[- MARK -] +appropriate type.
+%[- MARK -] +\versionchanged[Formerly, only lists or strings were accepted]{2.4}
+%[- MARK -] +If given a list or string, the initializer is passed to the
+%[- MARK -] new array's \method{fromlist()}, \method{fromstring()}, or
+%[- MARK -] \method{fromunicode()} method (see below) to add initial items to
+%[- MARK -] -the array.
+%[- MARK -] +the array. Otherwise, the iterable initializer is passed to the
+%[- MARK -] +\method{extend()} method.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{ArrayType}
+%[- MARK -] Obsolete alias for \function{array}.
+%[- MARK -] \end{datadesc}
+%[- MARK -] END DIFF
Il modulo definisce il seguente tipo:
\begin{funcdesc}{array}{typecode\optional{, initializer}}
@@ -105,6 +128,21 @@
8 byte; per gli altri tipi di valori viene sollevata un'eccezione
\exception{RuntimeError}. Questo metodo è utile quando si leggono dati da un
file scritto su una macchina che utilizza un ordine di byte differente.
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 99
+%[- MARK -] values, \exception{RuntimeError} is raised. It is useful when reading
+%[- MARK -] data from a file written on a machine with a different byte order.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{count}{x}
+%[- MARK -] -Return the number of occurences of \var{x} in the array.
+%[- MARK -] +Return the number of occurrences of \var{x} in the array.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{extend}{iterable}
+%[- MARK -] Append items from \var{iterable} to the end of the array. If
+%[- MARK -] \var{iterable} is another array, it must have \emph{exactly} the same
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[array]{count}{x}
@@ -149,6 +187,21 @@
un'eccezione \exception{ValueError}. Usate
\samp{array.fromstring(ustr.decode(enc))} per aggiungere dati Unicode
ad un array di qualche altro tipo.
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 141
+%[- MARK -] append Unicode data to an array of some other type.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{index}{x}
+%[- MARK -] Return the smallest \var{i} such that \var{i} is the index of
+%[- MARK -] -the first occurence of \var{x} in the array.
+%[- MARK -] +the first occurrence of \var{x} in the array.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{insert}{i, x}
+%[- MARK -] Insert a new item with value \var{x} in the array before position
+%[- MARK -] \var{i}. Negative values are treated as being relative to the end
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[array]{index}{x}
@@ -178,6 +231,21 @@
disponibili vengono comunque inseriti nell'array. \var{f} deve essere
un vero oggetto file built-in; un altro oggetto,
anche se possiede un metodo \method{read()}, non è sufficiente.}
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 168
+%[- MARK -] built-in file object; something else with a \method{read()} method won't
+%[- MARK -] do.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{remove}{x}
+%[- MARK -] -Remove the first occurence of \var{x} from the array.
+%[- MARK -] +Remove the first occurrence of \var{x} from the array.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[array]{reverse}{}
+%[- MARK -] Reverse the order of the items in the array.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[array]{remove}{x}
Modified: python/python/Doc/branches/2.4.3/lib/libasyncore.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libasyncore.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libasyncore.tex Fri Jun 2 12:52:55 2006
@@ -46,6 +46,47 @@
Una volta che il canale o i canali è/sono creato/i, la chiamata alla
funzione \function{loop()} attiva il servizio del canale, che continua
finché l'ultimo canale (includendo tutti quelli aggiunti alla mappa
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 42
+%[- MARK -] function activates channel service, which continues until the last
+%[- MARK -] channel (including any that have been added to the map during asynchronous
+%[- MARK -] service) is closed.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{,
+%[- MARK -] - map}}}}
+%[- MARK -] - Enter a polling loop that only terminates after all open channels
+%[- MARK -] - have been closed. All arguments are optional. The \var{timeout}
+%[- MARK -] - argument sets the timeout parameter for the appropriate
+%[- MARK -] - \function{select()} or \function{poll()} call, measured in seconds;
+%[- MARK -] - the default is 30 seconds. The \var{use_poll} parameter, if true,
+%[- MARK -] - indicates that \function{poll()} should be used in preference to
+%[- MARK -] - \function{select()} (the default is \code{False}). The \var{map} parameter
+%[- MARK -] - is a dictionary whose items are the channels to watch. As channels
+%[- MARK -] - are closed they are deleted from their map. If \var{map} is
+%[- MARK -] - omitted, a global map is used (this map is updated by the default
+%[- MARK -] - class \method{__init__()}
+%[- MARK -] - -- make sure you extend, rather than override, \method{__init__()}
+%[- MARK -] - if you want to retain this behavior).
+%[- MARK -] + map\optional{,count}}}}}
+%[- MARK -] + Enter a polling loop that terminates after count passes or all open
+%[- MARK -] + channels have been closed. All arguments are optional. The \var(count)
+%[- MARK -] + parameter defaults to None, resulting in the loop terminating only
+%[- MARK -] + when all channels have been closed. The \var{timeout} argument sets the
+%[- MARK -] + timeout parameter for the appropriate \function{select()} or
+%[- MARK -] + \function{poll()} call, measured in seconds; the default is 30 seconds.
+%[- MARK -] + The \var{use_poll} parameter, if true, indicates that \function{poll()}
+%[- MARK -] + should be used in preference to \function{select()} (the default is
+%[- MARK -] + \code{False}). The \var{map} parameter is a dictionary whose items are
+%[- MARK -] + the channels to watch. As channels are closed they are deleted from their
+%[- MARK -] + map. If \var{map} is omitted, a global map is used (this map is updated
+%[- MARK -] + by the default class \method{__init__()} -- make sure you extend, rather
+%[- MARK -] + than override, \method{__init__()} if you want to retain this behavior).
+%[- MARK -]
+%[- MARK -] Channels (instances of \class{asyncore.dispatcher}, \class{asynchat.async_chat}
+%[- MARK -] and subclasses thereof) can freely be mixed in the map.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
durante i servizi asincroni) non viene chiuso.
\begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{,
Modified: python/python/Doc/branches/2.4.3/lib/libatexit.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libatexit.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libatexit.tex Fri Jun 2 12:52:55 2006
@@ -35,6 +35,24 @@
Registra \var{func} come una funzione da eseguire alla
terminazione del programma. Ciascun argomento facoltativo che viene
passato a \var{func} deve venire passato come argomento di
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 37
+%[- MARK -] \function{sys.exit()} is called or the main module's execution
+%[- MARK -] completes), all functions registered are called in last in, first out
+%[- MARK -] order. The assumption is that lower level modules will normally be
+%[- MARK -] imported before higher level modules and thus must be cleaned up
+%[- MARK -] later.
+%[- MARK -] +
+%[- MARK -] +If an exception is raised during execution of the exit handlers, a
+%[- MARK -] +traceback is printed (unless \exception{SystemExit} is raised) and the
+%[- MARK -] +exception information is saved. After all exit handlers have had a
+%[- MARK -] +chance to run the last exception to be raised is re-raised.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seemodule{readline}{Useful example of \module{atexit} to read and
+%[- MARK -] END DIFF
\function{register()}.
Quando viene terminato normalmente il programma (per esempio, se viene
Modified: python/python/Doc/branches/2.4.3/lib/libbase64.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libbase64.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libbase64.tex Fri Jun 2 12:52:55 2006
@@ -6,6 +6,21 @@
\indexii{base64}{encoding}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 10
+%[- MARK -]
+%[- MARK -] This module provides data encoding and decoding as specified in
+%[- MARK -] \rfc{3548}. This standard defines the Base16, Base32, and Base64
+%[- MARK -] algorithms for encoding and decoding arbitrary binary strings into
+%[- MARK -] text strings that can be safely sent by email, used as parts of URLs,
+%[- MARK -] -or included as part of an HTTP POST request. The encoding algorith is
+%[- MARK -] +or included as part of an HTTP POST request. The encoding algorithm is
+%[- MARK -] not the same as the \program{uuencode} program.
+%[- MARK -]
+%[- MARK -] There are two interfaces provided by this module. The modern
+%[- MARK -] interface supports encoding and decoding string objects using all
+%[- MARK -] three alphabets. The legacy interface provides for encoding and
+%[- MARK -] END DIFF
\index{MIME!base64 encoding}
Questo modulo fornisce la codifica e la decodifica dei dati
Modified: python/python/Doc/branches/2.4.3/lib/libbasehttp.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libbasehttp.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libbasehttp.tex Fri Jun 2 12:52:55 2006
@@ -9,6 +9,21 @@
\indexii{WWW}{server}
\indexii{HTTP}{protocol}
\index{URL}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 12
+%[- MARK -] \index{httpd}
+%[- MARK -]
+%[- MARK -] This module defines two classes for implementing HTTP servers
+%[- MARK -] (Web servers). Usually, this module isn't used directly, but is used
+%[- MARK -] as a basis for building functioning Web servers. See the
+%[- MARK -] -\module{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
+%[- MARK -] +\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
+%[- MARK -] \refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules.
+%[- MARK -]
+%[- MARK -] The first class, \class{HTTPServer}, is a
+%[- MARK -] \class{SocketServer.TCPServer} subclass. It creates and listens at the
+%[- MARK -] HTTP socket, dispatching the requests to a handler. Code to create and
+%[- MARK -] END DIFF
\index{httpd}
Questo modulo definisce due classi per implementare server HTTP
Modified: python/python/Doc/branches/2.4.3/lib/libbltin.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libbltin.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libbltin.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,55 @@
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 1
+%[- MARK -] \section{\module{__builtin__} ---
+%[- MARK -] - Built-in functions}
+%[- MARK -] + Built-in objects}
+%[- MARK -]
+%[- MARK -] \declaremodule[builtin]{builtin}{__builtin__}
+%[- MARK -] -\modulesynopsis{The set of built-in functions.}
+%[- MARK -] +\modulesynopsis{The module that provides the built-in namespace.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] This module provides direct access to all `built-in' identifiers of
+%[- MARK -] -Python; e.g. \code{__builtin__.open} is the full name for the built-in
+%[- MARK -] -function \function{open()}. See section \ref{built-in-funcs}, ``Built-in
+%[- MARK -] -Functions.''
+%[- MARK -] +Python; for example, \code{__builtin__.open} is the full name for the
+%[- MARK -] +built-in function \function{open()}. See chapter~\ref{builtin},
+%[- MARK -] +``Built-in Objects.''
+%[- MARK -] +
+%[- MARK -] +This module is not normally accessed explicitly by most applications,
+%[- MARK -] +but can be useful in modules that provide objects with the same name
+%[- MARK -] +as a built-in value, but in which the built-in of that name is also
+%[- MARK -] +needed. For example, in a module that wants to implement an
+%[- MARK -] +\function{open()} function that wraps the built-in \function{open()},
+%[- MARK -] +this module can be used directly:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import __builtin__
+%[- MARK -] +
+%[- MARK -] +def open(path):
+%[- MARK -] + f = __builtin__.open(path, 'r')
+%[- MARK -] + return UpperCaser(f)
+%[- MARK -] +
+%[- MARK -] +class UpperCaser:
+%[- MARK -] + '''Wrapper around a file that converts output to upper-case.'''
+%[- MARK -] +
+%[- MARK -] + def __init__(self, f):
+%[- MARK -] + self._f = f
+%[- MARK -] +
+%[- MARK -] + def read(self, count=-1):
+%[- MARK -] + return self._f.read(count).upper()
+%[- MARK -] +
+%[- MARK -] + # ...
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +As an implementation detail, most modules have the name
+%[- MARK -] +\code{__builtins__} (note the \character{s}) made available as part of
+%[- MARK -] +their globals. The value of \code{__builtins__} is normally either
+%[- MARK -] +this module or the value of this modules's \member{__dict__}
+%[- MARK -] +attribute. Since this is an implementation detail, it may not be used
+%[- MARK -] +by alternate implementations of Python.
+%[- MARK -] END DIFF
\section{\module{__builtin__} ---
Funzioni built-in}
Modified: python/python/Doc/branches/2.4.3/lib/libbsddb.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libbsddb.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libbsddb.tex Fri Jun 2 12:52:55 2006
@@ -13,6 +13,21 @@
Bsddb generalmente si comportano come dizionari. Chiavi e valori
devono essere stringhe, per usare altri oggetti come chiavi o per
immettere altri tipi di oggetti l'utente deve in qualche modo serializzarli, tipicamente
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 14
+%[- MARK -] other objects as keys or to store other kinds of objects the user must
+%[- MARK -] serialize them somehow, typically using marshal.dumps or pickle.dumps.
+%[- MARK -]
+%[- MARK -] Starting with Python 2.3 the \module{bsddb} module requires the
+%[- MARK -] Berkeley DB library version 3.2 or later (it is known to work with 3.2
+%[- MARK -] -thru 4.2 at the time of this writing).
+%[- MARK -] +through 4.3 at the time of this writing).
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seeurl{http://pybsddb.sourceforge.net/}{Website with documentation
+%[- MARK -] for the new python Berkeley DB interface that closely mirrors the
+%[- MARK -] sleepycat object oriented interface provided in Berkeley DB 3 and 4.}
+%[- MARK -] END DIFF
usando marshal.dumps o pickle.dumps.
A partire da Python 2.3 il modulo \module{bsddb} richiede la libreria
@@ -38,6 +53,84 @@
creano oggetti che accedono all'appropriato tipo del file Berkeley DB.
I primi due argomenti di ogni funzione sono gli stessi. Per riguardo
alla portabilità, solo i primi due argomenti dovrebbero essere usati
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 44
+%[- MARK -] lorder}}}}}}}}}
+%[- MARK -] Open the hash format file named \var{filename}. Files never intended
+%[- MARK -] to be preserved on disk may be created by passing \code{None} as the
+%[- MARK -] \var{filename}. The optional
+%[- MARK -] \var{flag} identifies the mode used to open the file. It may be
+%[- MARK -] -\character{r} (read only, default), \character{w} (read-write) ,
+%[- MARK -] -\character{c} (read-write - create if necessary) or
+%[- MARK -] +\character{r} (read only), \character{w} (read-write) ,
+%[- MARK -] +\character{c} (read-write - create if necessary; the default) or
+%[- MARK -] \character{n} (read-write - truncate to zero length). The other
+%[- MARK -] arguments are rarely used and are just passed to the low-level
+%[- MARK -] \cfunction{dbopen()} function. Consult the Berkeley DB documentation
+%[- MARK -] for their use and interpretation.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
+%[- MARK -] mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
+%[- MARK -] -minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
+%[- MARK -] +minkeypage\optional{, pgsize\optional{, lorder}}}}}}}}}
+%[- MARK -]
+%[- MARK -] Open the btree format file named \var{filename}. Files never intended
+%[- MARK -] to be preserved on disk may be created by passing \code{None} as the
+%[- MARK -] \var{filename}. The optional
+%[- MARK -] \var{flag} identifies the mode used to open the file. It may be
+%[- MARK -] -\character{r} (read only, default), \character{w} (read-write),
+%[- MARK -] -\character{c} (read-write - create if necessary) or
+%[- MARK -] +\character{r} (read only), \character{w} (read-write),
+%[- MARK -] +\character{c} (read-write - create if necessary; the default) or
+%[- MARK -] \character{n} (read-write - truncate to zero length). The other
+%[- MARK -] arguments are rarely used and are just passed to the low-level dbopen
+%[- MARK -] function. Consult the Berkeley DB documentation for their use and
+%[- MARK -] interpretation.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
+%[- MARK -] -rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
+%[- MARK -] +rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{,
+%[- MARK -] reclen\optional{, bval\optional{, bfname}}}}}}}}}}
+%[- MARK -]
+%[- MARK -] Open a DB record format file named \var{filename}. Files never intended
+%[- MARK -] to be preserved on disk may be created by passing \code{None} as the
+%[- MARK -] \var{filename}. The optional
+%[- MARK -] \var{flag} identifies the mode used to open the file. It may be
+%[- MARK -] -\character{r} (read only, default), \character{w} (read-write),
+%[- MARK -] -\character{c} (read-write - create if necessary) or
+%[- MARK -] +\character{r} (read only), \character{w} (read-write),
+%[- MARK -] +\character{c} (read-write - create if necessary; the default) or
+%[- MARK -] \character{n} (read-write - truncate to zero length). The other
+%[- MARK -] arguments are rarely used and are just passed to the low-level dbopen
+%[- MARK -] function. Consult the Berkeley DB documentation for their use and
+%[- MARK -] interpretation.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] -\begin{seealso}
+%[- MARK -] - \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
+%[- MARK -] -\end{seealso}
+%[- MARK -] -
+%[- MARK -] \begin{notice}
+%[- MARK -] Beginning in 2.3 some Unix versions of Python may have a \module{bsddb185}
+%[- MARK -] module. This is present \emph{only} to allow backwards compatibility with
+%[- MARK -] systems which ship with the old Berkeley DB 1.85 database library. The
+%[- MARK -] \module{bsddb185} module should never be used directly in new code.
+%[- MARK -] \end{notice}
+%[- MARK -]
+%[- MARK -] +
+%[- MARK -] +\begin{seealso}
+%[- MARK -] + \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
+%[- MARK -] +\end{seealso}
+%[- MARK -] +
+%[- MARK -] \subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
+%[- MARK -]
+%[- MARK -] Once instantiated, hash, btree and record objects support
+%[- MARK -] the same methods as dictionaries. In addition, they support
+%[- MARK -] the methods listed below.
+%[- MARK -] END DIFF
nella gran parte dei casi.
\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
@@ -135,6 +228,20 @@
al prossimo elemento in maniera ordinata restituendo quella chiave e
quel valore. Per altri database, verrà sollevata l'eccezione
\exception{KeyError} se la chiave non viene trovata nel database.
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 132
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{first}{}
+%[- MARK -] Set the cursor to the first item in the DB file and return it. The order of
+%[- MARK -] keys in the file is unspecified, except in the case of B-Tree databases.
+%[- MARK -] +This method raises \exception{bsddb.error} if the database is empty.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{next}{}
+%[- MARK -] Set the cursor to the next item in the DB file and return it. The order of
+%[- MARK -] keys in the file is unspecified, except in the case of B-Tree databases.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{first}{}
@@ -154,6 +261,20 @@
restituisce. L'ordine delle chiavi non è specificato, eccetto nel
caso di database B-Tree. Questo metodo non è supportato nei database
a tabella di hash (quelli aperti con \function{hashopen()}).
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 150
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{last}{}
+%[- MARK -] Set the cursor to the last item in the DB file and return it. The
+%[- MARK -] order of keys in the file is unspecified. This is not supported on
+%[- MARK -] hashtable databases (those opened with \function{hashopen()}).
+%[- MARK -] +This method raises \exception{bsddb.error} if the database is empty.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{sync}{}
+%[- MARK -] Synchronize the database on disk.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{last}{}
Modified: python/python/Doc/branches/2.4.3/lib/libbz2.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libbz2.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libbz2.tex Fri Jun 2 12:52:55 2006
@@ -86,6 +86,21 @@
Restituisce una lista delle righe lette. L'argomento facoltativo
\var{size}, se passato, è un limite approssimativo del numero di byte
totale delle righe restituite.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 80
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[BZ2File]{xreadlines}{}
+%[- MARK -] For backward compatibility. \class{BZ2File} objects now include the
+%[- MARK -] performance optimizations previously implemented in the
+%[- MARK -] -\refmodule{xreadlines} module.
+%[- MARK -] +\module{xreadlines} module.
+%[- MARK -] \deprecated{2.3}{This exists only for compatibility with the method by
+%[- MARK -] this name on \class{file} objects, which is
+%[- MARK -] deprecated. Use \code{for line in file} instead.}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[BZ2File]{xreadlines}{}
Modified: python/python/Doc/branches/2.4.3/lib/libcalendar.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcalendar.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcalendar.tex Fri Jun 2 12:52:55 2006
@@ -58,6 +58,24 @@
Restituisce il giorno della settimana (\code{0} è Lunedì) per l'anno
\var{year} (\code{1970}--\ldots), mese \var{month}
(\code{1}--\code{12}), giorno \var{day} (\code{1}--\code{31}).
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 57
+%[- MARK -] Returns the day of the week (\code{0} is Monday) for \var{year}
+%[- MARK -] (\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day}
+%[- MARK -] (\code{1}--\code{31}).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{weekheader}{n}
+%[- MARK -] +Return a header containing abbreviated weekday names. \var{n} specifies
+%[- MARK -] +the width in characters for one weekday.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{monthrange}{year, month}
+%[- MARK -] Returns weekday of first day of the month and number of days in month,
+%[- MARK -] for the specified \var{year} and \var{month}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{monthrange}{year, month}
Modified: python/python/Doc/branches/2.4.3/lib/libcfgparser.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcfgparser.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcfgparser.tex Fri Jun 2 12:52:55 2006
@@ -247,6 +247,29 @@
\begin{methoddesc}{items}{section}
Restituisce una lista di coppie \code{(\var{nome}, \var{valore})} per
ogni opzione nella sezione \var{section}.
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 236
+%[- MARK -] Return a list of \code{(\var{name}, \var{value})} pairs for each
+%[- MARK -] option in the given \var{section}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{set}{section, option, value}
+%[- MARK -] -If the given section exists, set the given option to the specified value;
+%[- MARK -] -otherwise raise \exception{NoSectionError}. \var{value} must be a
+%[- MARK -] -string (\class{str} or \class{unicode}); if not, \exception{TypeError}
+%[- MARK -] -is raised.
+%[- MARK -] +If the given section exists, set the given option to the specified
+%[- MARK -] +value; otherwise raise \exception{NoSectionError}. While it is
+%[- MARK -] +possible to use \class{RawConfigParser} (or \class{ConfigParser} with
+%[- MARK -] +\var{raw} parameters set to true) for \emph{internal} storage of
+%[- MARK -] +non-string values, full functionality (including interpolation and
+%[- MARK -] +output to files) can only be achieved using string values.
+%[- MARK -] \versionadded{1.6}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{write}{fileobject}
+%[- MARK -] Write a representation of the configuration to the specified file
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{set}{section, option, value}
@@ -293,6 +316,21 @@
\end{methoddesc}
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 279
+%[- MARK -]
+%[- MARK -] \subsection{ConfigParser Objects \label{ConfigParser-objects}}
+%[- MARK -]
+%[- MARK -] The \class{ConfigParser} class extends some methods of the
+%[- MARK -] \class{RawConfigParser} interface, adding some optional arguments.
+%[- MARK -] -The \class{SafeConfigParser} class implements the same extended
+%[- MARK -] -interface.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
+%[- MARK -] Get an \var{option} value for the named \var{section}. All the
+%[- MARK -] \character{\%} interpolations are expanded in the return values, based
+%[- MARK -] on the defaults passed into the constructor, as well as the options
+%[- MARK -] END DIFF
\subsection{Oggetti ConfigParser \label{ConfigParser-objects}}
La classe \class{ConfigParser} estende alcuni metodi dell'interfaccia
@@ -306,6 +344,28 @@
nei valori restituiti, in base a quelli predefiniti passati al
costruttore, come anche le opzioni fornite tramite \var{vars}, a meno che
l'argomento \var{raw} non sia true.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 295
+%[- MARK -] Return a list of \code{(\var{name}, \var{value})} pairs for each
+%[- MARK -] option in the given \var{section}. Optional arguments have the
+%[- MARK -] same meaning as for the \method{get()} method.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}}
+%[- MARK -] +
+%[- MARK -] +The \class{SafeConfigParser} class implements the same extended
+%[- MARK -] +interface as \class{ConfigParser}, with the following addition:
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{set}{section, option, value}
+%[- MARK -] +If the given section exists, set the given option to the specified
+%[- MARK -] +value; otherwise raise \exception{NoSectionError}. \var{value} must
+%[- MARK -] +be a string (\class{str} or \class{unicode}); if not,
+%[- MARK -] +\exception{TypeError} is raised.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}
Modified: python/python/Doc/branches/2.4.3/lib/libcgi.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcgi.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcgi.tex Fri Jun 2 12:52:55 2006
@@ -30,6 +30,22 @@
informazioni circa la richiesta (come il nome dell'host cliente, l'URL
richiesta, la stringa di ricerca, e parecchie altre cose)
nell'ambiente di shell dello script, esegue lo script e restituisce il
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 34
+%[- MARK -] form data is read this way; at other times the form data is passed via
+%[- MARK -] the ``query string'' part of the URL. This module is intended
+%[- MARK -] to take care of the different cases and provide a simpler interface to
+%[- MARK -] the Python script. It also provides a number of utilities that help
+%[- MARK -] in debugging scripts, and the latest addition is support for file
+%[- MARK -] -uploads from a form (if your browser supports it --- Grail 0.3 and
+%[- MARK -] -Netscape 2.0 do).
+%[- MARK -] +uploads from a form (if your browser supports it).
+%[- MARK -]
+%[- MARK -] The output of a CGI script should consist of two sections, separated
+%[- MARK -] by a blank line. The first section contains a number of headers,
+%[- MARK -] telling the client what kind of data is following. Python code to
+%[- MARK -] generate a minimal header section looks like this:
+%[- MARK -] END DIFF
risultato dello script al cliente.
L'input dello script è connesso anche al cliente, e qualche volta le
@@ -136,6 +152,36 @@
L'attributo \member{value} dell'istanza contiene il valore stringa del
campo. Il metodo \method{getvalue()} restituisce direttamente il
valore della stringa; accetta anche un secondo argomento facoltativo
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 133
+%[- MARK -] \class{FieldStorage} or \class{MiniFieldStorage}
+%[- MARK -] instance but a list of such instances. Similarly, in this situation,
+%[- MARK -] \samp{form.getvalue(\var{key})} would return a list of strings.
+%[- MARK -] If you expect this possibility
+%[- MARK -] (when your HTML form contains multiple fields with the same name), use
+%[- MARK -] -the \function{isinstance()} built-in function to determine whether you
+%[- MARK -] -have a single instance or a list of instances. For example, this
+%[- MARK -] +the \function{getlist()} function, which always returns a list of values (so that you
+%[- MARK -] +do not need to special-case the single item case). For example, this
+%[- MARK -] code concatenates any number of username fields, separated by
+%[- MARK -] commas:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -value = form.getvalue("username", "")
+%[- MARK -] -if isinstance(value, list):
+%[- MARK -] - # Multiple username fields specified
+%[- MARK -] - usernames = ",".join(value)
+%[- MARK -] -else:
+%[- MARK -] - # Single or no username field specified
+%[- MARK -] - usernames = value
+%[- MARK -] +value = form.getlist("username")
+%[- MARK -] +usernames = ",".join(value)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] If a field represents an uploaded file, accessing the value via the
+%[- MARK -] \member{value} attribute or the \function{getvalue()} method reads the
+%[- MARK -] entire file in memory as a string. This may not be what you want.
+%[- MARK -] END DIFF
come predefinito da restituire se la chiave richiesta non è presente.
Se i dati immessi nella form contengono più di un campo con il
@@ -261,6 +307,21 @@
leggibile gli script.
Un approccio più pratico consiste nell'uso dei metodi \method{getfirst()} e
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 244
+%[- MARK -]
+%[- MARK -] A more convenient approach is to use the methods \method{getfirst()}
+%[- MARK -] and \method{getlist()} provided by this higher level interface.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
+%[- MARK -] - Thin method always returns only one value associated with form field
+%[- MARK -] + This method always returns only one value associated with form field
+%[- MARK -] \var{name}. The method returns only the first value in case that
+%[- MARK -] more values were posted under such name. Please note that the order
+%[- MARK -] in which the values are received may vary from browser to browser
+%[- MARK -] and should not be counted on.\footnote{Note that some recent
+%[- MARK -] versions of the HTML specification do state what order the
+%[- MARK -] END DIFF
\method{getlist()} forniti da questa interfaccia di più alto livello.
\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
Modified: python/python/Doc/branches/2.4.3/lib/libcgitb.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcgitb.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcgitb.tex Fri Jun 2 12:52:55 2006
@@ -10,6 +10,21 @@
\index{CGI!exceptions}
\index{CGI!tracebacks}
\index{exceptions!in CGI scripts}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 11
+%[- MARK -] \index{CGI!tracebacks}
+%[- MARK -] \index{exceptions!in CGI scripts}
+%[- MARK -] \index{tracebacks!in CGI scripts}
+%[- MARK -]
+%[- MARK -] The \module{cgitb} module provides a special exception handler for Python
+%[- MARK -] -scripts. (It's name is a bit misleading. It was originally designed to
+%[- MARK -] +scripts. (Its name is a bit misleading. It was originally designed to
+%[- MARK -] display extensive traceback information in HTML for CGI scripts. It was
+%[- MARK -] later generalized to also display this information in plain text.) After
+%[- MARK -] this module is activated, if an uncaught exception occurs, a detailed,
+%[- MARK -] formatted report will be displayed. The report
+%[- MARK -] includes a traceback showing excerpts of the source code for each level,
+%[- MARK -] END DIFF
\index{tracebacks!in CGI scripts}
Il modulo \module{cgitb} fornisce un gestore di eccezioni speciale per
Modified: python/python/Doc/branches/2.4.3/lib/libcmath.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcmath.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcmath.tex Fri Jun 2 12:52:55 2006
@@ -67,6 +67,27 @@
\begin{funcdesc}{exp}{x}
Restituisce il valore esponenziale \code{e**\var{x}}.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 71
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{exp}{x}
+%[- MARK -] Return the exponential value \code{e**\var{x}}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{log}{x}
+%[- MARK -] -Return the natural logarithm of \var{x}.
+%[- MARK -] +\begin{funcdesc}{log}{x\optional{, base}}
+%[- MARK -] +Returns the logarithm of \var{x} to the given \var{base}.
+%[- MARK -] +If the \var{base} is not specified, returns the natural logarithm of \var{x}.
+%[- MARK -] There is one branch cut, from 0 along the negative real axis to
+%[- MARK -] -\infinity, continuous from above.
+%[- MARK -] +\versionchanged[\var{base} argument added]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{log10}{x}
+%[- MARK -] Return the base-10 logarithm of \var{x}.
+%[- MARK -] This has the same branch cut as \function{log()}.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{log}{x}
@@ -130,6 +151,19 @@
(non troppo elementare) che tratti delle variabili complesse per
saperne di più. Per informazioni sulla scelta adatta dei rami di funzione
per gli usi numerici, un buon riferimento può essere il
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 132
+%[- MARK -] information of the proper choice of branch cuts for numerical
+%[- MARK -] purposes, a good reference should be the following:
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seetext{Kahan, W: Branch cuts for complex elementary functions;
+%[- MARK -] - or, Much ado about nothings's sign bit. In Iserles, A.,
+%[- MARK -] + or, Much ado about nothing's sign bit. In Iserles, A.,
+%[- MARK -] and Powell, M. (eds.), \citetitle{The state of the art in
+%[- MARK -] numerical analysis}. Clarendon Press (1987) pp165-211.}
+%[- MARK -] \end{seealso}
+%[- MARK -] END DIFF
seguente:
\begin{seealso}
Modified: python/python/Doc/branches/2.4.3/lib/libcmd.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcmd.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcmd.tex Fri Jun 2 12:52:55 2006
@@ -29,6 +29,21 @@
oggetti file di input e di output che verranno utilizzati
dall'istanza di Cmd o da una sua sotto classe. Se non
specificati, i valori predefiniti saranno \var{sys.stdin} e
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 27
+%[- MARK -] The optional arguments \var{stdin} and \var{stdout} specify the
+%[- MARK -] input and output file objects that the Cmd instance or subclass
+%[- MARK -] instance will use for input and output. If not specified, they
+%[- MARK -] will default to \var{sys.stdin} and \var{sys.stdout}.
+%[- MARK -]
+%[- MARK -] -\versionchanged[The \var{stdin} and \var{stdout} parameters were added.]{2.3}
+%[- MARK -] +\versionchanged[The \var{stdin} and \var{stdout} parameters were added]{2.3}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \subsection{Cmd Objects}
+%[- MARK -] \label{Cmd-objects}
+%[- MARK -]
+%[- MARK -] END DIFF
\var{sys.stdout}.
\versionchanged[Aggiunti i parametri \var{stdin} e \var{stdout}.]{2.3}
@@ -63,6 +78,23 @@
speciale, viene inviata al metodo \method{do_help()} una riga che inizia
con il carattere \character{?}. Come altro caso speciale, viene inviato al metodo
\method{do_shell()}(sempre che sia stato definito) una riga che
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 58
+%[- MARK -] a line beginning with the character \character{?} is dispatched to
+%[- MARK -] the method \method{do_help()}. As another special case, a line
+%[- MARK -] beginning with the character \character{!} is dispatched to the
+%[- MARK -] method \method{do_shell()} (if such a method is defined).
+%[- MARK -]
+%[- MARK -] +This method will return when the \method{postcmd()} method returns a
+%[- MARK -] +true value. The \var{stop} argument to \method{postcmd()} is the
+%[- MARK -] +return value from the command's corresponding \method{do_*()} method.
+%[- MARK -] +
+%[- MARK -] If completion is enabled, completing commands will be done
+%[- MARK -] automatically, and completing of commands args is done by calling
+%[- MARK -] \method{complete_foo()} with arguments \var{text}, \var{line},
+%[- MARK -] \var{begidx}, and \var{endidx}. \var{text} is the string prefix we
+%[- MARK -] are attempting to match: all returned matches must begin with it.
+%[- MARK -] END DIFF
inizia con il carattere \character{!}.
Se il completamento è abilitato, verrà eseguito
@@ -82,6 +114,24 @@
\method{do_help()} elenca tutte le possibili richieste di aiuto (cioè,
tutti i comandi con il metodo \method{help_*()} corrispondente),
oltre a tutti i comandi non documentati.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 81
+%[- MARK -] \begin{methoddesc}{onecmd}{str}
+%[- MARK -] Interpret the argument as though it had been typed in response to the
+%[- MARK -] prompt. This may be overridden, but should not normally need to be;
+%[- MARK -] see the \method{precmd()} and \method{postcmd()} methods for useful
+%[- MARK -] execution hooks. The return value is a flag indicating whether
+%[- MARK -] -interpretation of commands by the interpreter should stop.
+%[- MARK -] +interpretation of commands by the interpreter should stop. If there
+%[- MARK -] +is a \method{do_*()} method for the command \var{str}, the return
+%[- MARK -] +value of that method is returned, otherwise the return value from the
+%[- MARK -] +\method{default()} method is returned.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{emptyline}{}
+%[- MARK -] Method called when an empty line is entered in response to the prompt.
+%[- MARK -] If this method is not overridden, it repeats the last nonempty command
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{onecmd}{str}
Modified: python/python/Doc/branches/2.4.3/lib/libcodecs.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcodecs.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcodecs.tex Fri Jun 2 12:52:55 2006
@@ -227,6 +227,24 @@
\constant{BOM_LE} per \constant{BOM_UTF16_LE} e \constant{BOM_BE} per
\constant{BOM_UTF16_BE}. Gli altri rappresentano il BOM nelle codifiche
UTF-8 e UTF-32.
+%[- MARK -] BEGIN DIFF 001 of 9
+%[- MARK -] @@ 210
+%[- MARK -] for \constant{BOM_UTF16_LE} and \constant{BOM_BE} for \constant{BOM_UTF16_BE}.
+%[- MARK -] The others represent the BOM in UTF-8 and UTF-32 encodings.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] -\subsection{Codec Base Classes}
+%[- MARK -] +\subsection{Codec Base Classes \label{codec-base-classes}}
+%[- MARK -]
+%[- MARK -] -The \module{codecs} defines a set of base classes which define the
+%[- MARK -] +The \module{codecs} module defines a set of base classes which define the
+%[- MARK -] interface and can also be used to easily write you own codecs for use
+%[- MARK -] in Python.
+%[- MARK -]
+%[- MARK -] Each codec has to define four interfaces to make it usable as codec in
+%[- MARK -] Python: stateless encoder, stateless decoder, stream reader and stream
+%[- MARK -] END DIFF
\end{datadesc}
@@ -428,6 +446,75 @@
L'insieme dei valori consentiti per l'argomento \var{errors} può
venire esteso con \function{register_error()}.
+%[- MARK -] BEGIN DIFF 002 of 9
+%[- MARK -] @@ 392
+%[- MARK -]
+%[- MARK -] The set of allowed values for the \var{errors} argument can
+%[- MARK -] be extended with \function{register_error()}.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{read}{\optional{size}}
+%[- MARK -] +\begin{methoddesc}{read}{\optional{size\optional{, chars, \optional{firstline}}}}
+%[- MARK -] Decodes data from the stream and returns the resulting object.
+%[- MARK -]
+%[- MARK -] + \var{chars} indicates the number of characters to read from the
+%[- MARK -] + stream. \function{read()} will never return more than \var{chars}
+%[- MARK -] + characters, but it might return less, if there are not enough
+%[- MARK -] + characters available.
+%[- MARK -] +
+%[- MARK -] \var{size} indicates the approximate maximum number of bytes to read
+%[- MARK -] from the stream for decoding purposes. The decoder can modify this
+%[- MARK -] setting as appropriate. The default value -1 indicates to read and
+%[- MARK -] decode as much as possible. \var{size} is intended to prevent having
+%[- MARK -] to decode huge files in one step.
+%[- MARK -]
+%[- MARK -] + \var{firstline} indicates that it would be sufficient to only return
+%[- MARK -] + the first line, if there are decoding errors on later lines.
+%[- MARK -] +
+%[- MARK -] The method should use a greedy read strategy meaning that it should
+%[- MARK -] read as much data as is allowed within the definition of the encoding
+%[- MARK -] and the given size, e.g. if optional encoding endings or state
+%[- MARK -] markers are available on the stream, these should be read too.
+%[- MARK -] +
+%[- MARK -] + \versionchanged[\var{chars} argument added]{2.4}
+%[- MARK -] + \versionchanged[\var{firstline} argument added]{2.4.2}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{readline}{[size]}
+%[- MARK -] +\begin{methoddesc}{readline}{\optional{size\optional{, keepends}}}
+%[- MARK -] Read one line from the input stream and return the
+%[- MARK -] decoded data.
+%[- MARK -]
+%[- MARK -] - Unlike the \method{readlines()} method, this method inherits
+%[- MARK -] - the line breaking knowledge from the underlying stream's
+%[- MARK -] - \method{readline()} method -- there is currently no support for line
+%[- MARK -] - breaking using the codec decoder due to lack of line buffering.
+%[- MARK -] - Sublcasses should however, if possible, try to implement this method
+%[- MARK -] - using their own knowledge of line breaking.
+%[- MARK -] -
+%[- MARK -] \var{size}, if given, is passed as size argument to the stream's
+%[- MARK -] \method{readline()} method.
+%[- MARK -] +
+%[- MARK -] + If \var{keepends} is false lineends will be stripped from the
+%[- MARK -] + lines returned.
+%[- MARK -] +
+%[- MARK -] + \versionchanged[\var{keepends} argument added]{2.4}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{readlines}{[sizehint]}
+%[- MARK -] +\begin{methoddesc}{readlines}{\optional{sizehint\optional{, keepends}}}
+%[- MARK -] Read all lines available on the input stream and return them as list
+%[- MARK -] of lines.
+%[- MARK -]
+%[- MARK -] Line breaks are implemented using the codec's decoder method and are
+%[- MARK -] - included in the list entries.
+%[- MARK -] + included in the list entries if \var{keepends} is true.
+%[- MARK -]
+%[- MARK -] \var{sizehint}, if given, is passed as \var{size} argument to the
+%[- MARK -] stream's \method{read()} method.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{classdesc}
\begin{methoddesc}{read}{\optional{size}}
@@ -552,6 +639,21 @@
Le istanze \class{StreamRecoder} definiscono le interfacce combinate
delle classi \class{StreamReader} e \class{StreamWriter}. Ereditano
+%[- MARK -] BEGIN DIFF 003 of 9
+%[- MARK -] @@ 511
+%[- MARK -]
+%[- MARK -] \class{StreamRecoder} instances define the combined interfaces of
+%[- MARK -] \class{StreamReader} and \class{StreamWriter} classes. They inherit
+%[- MARK -] all other methods and attribute from the underlying stream.
+%[- MARK -]
+%[- MARK -] -\subsection{Standard Encodings}
+%[- MARK -] +\subsection{Standard Encodings\label{standard-encodings}}
+%[- MARK -]
+%[- MARK -] Python comes with a number of codecs builtin, either implemented as C
+%[- MARK -] functions, or with dictionaries as mapping tables. The following table
+%[- MARK -] lists the codecs by name, together with a few common aliases, and the
+%[- MARK -] languages for which the encoding is likely used. Neither the list of
+%[- MARK -] END DIFF
tutti gli altri metodi ed attributi del flusso sottostante.
\subsection{ Codifica standard}
@@ -585,6 +687,25 @@
\lineiii{ascii}
{646, us-ascii}
+%[- MARK -] BEGIN DIFF 004 of 9
+%[- MARK -] @@ 543
+%[- MARK -] \lineiii{ascii}
+%[- MARK -] {646, us-ascii}
+%[- MARK -] {English}
+%[- MARK -]
+%[- MARK -] \lineiii{big5}
+%[- MARK -] - {big5_tw, csbig5}
+%[- MARK -] + {big5-tw, csbig5}
+%[- MARK -] + {Traditional Chinese}
+%[- MARK -] +
+%[- MARK -] +\lineiii{big5hkscs}
+%[- MARK -] + {big5-hkscs, hkscs}
+%[- MARK -] {Traditional Chinese}
+%[- MARK -]
+%[- MARK -] \lineiii{cp037}
+%[- MARK -] {IBM037, IBM039}
+%[- MARK -] {English}
+%[- MARK -] END DIFF
{Inglese}
\lineiii{big5}
@@ -657,6 +778,23 @@
\lineiii{cp865}
{865, IBM865}
+%[- MARK -] BEGIN DIFF 005 of 9
+%[- MARK -] @@ 614
+%[- MARK -]
+%[- MARK -] \lineiii{cp865}
+%[- MARK -] {865, IBM865}
+%[- MARK -] {Danish, Norwegian}
+%[- MARK -]
+%[- MARK -] +\lineiii{cp866}
+%[- MARK -] + {866, IBM866}
+%[- MARK -] + {Russian}
+%[- MARK -] +
+%[- MARK -] \lineiii{cp869}
+%[- MARK -] {869, CP-GR, IBM869}
+%[- MARK -] {Greek}
+%[- MARK -]
+%[- MARK -] \lineiii{cp874}
+%[- MARK -] END DIFF
{Danese, Norvegese}
\lineiii{cp869}
@@ -669,6 +807,21 @@
\lineiii{cp875}
{}
+%[- MARK -] BEGIN DIFF 006 of 9
+%[- MARK -] @@ 627
+%[- MARK -] \lineiii{cp875}
+%[- MARK -] {}
+%[- MARK -] {Greek}
+%[- MARK -]
+%[- MARK -] \lineiii{cp932}
+%[- MARK -] - {932, ms932, mskanji, ms_kanji}
+%[- MARK -] + {932, ms932, mskanji, ms-kanji}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{cp949}
+%[- MARK -] {949, ms949, uhc}
+%[- MARK -] {Korean}
+%[- MARK -] END DIFF
{Greco}
\lineiii{cp932}
@@ -729,6 +882,90 @@
\lineiii{cp1258}
{windows-1258}
+%[- MARK -] BEGIN DIFF 007 of 9
+%[- MARK -] @@ 687
+%[- MARK -] \lineiii{cp1258}
+%[- MARK -] {windows-1258}
+%[- MARK -] {Vietnamese}
+%[- MARK -]
+%[- MARK -] \lineiii{euc_jp}
+%[- MARK -] - {eucjp, ujis, u_jis}
+%[- MARK -] + {eucjp, ujis, u-jis}
+%[- MARK -] + {Japanese}
+%[- MARK -] +
+%[- MARK -] +\lineiii{euc_jis_2004}
+%[- MARK -] + {jisx0213, eucjis2004}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{euc_jisx0213}
+%[- MARK -] - {jisx0213, eucjisx0213}
+%[- MARK -] + {eucjisx0213}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{euc_kr}
+%[- MARK -] - {euckr, korean, ksc5601, ks_c_5601, ks_c_5601_1987, ksx1001, ks_x_1001}
+%[- MARK -] + {euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001}
+%[- MARK -] {Korean}
+%[- MARK -]
+%[- MARK -] \lineiii{gb2312}
+%[- MARK -] - {chinese, csiso58gb231280, euc_cn, euccn, eucgb2312_cn, gb2312_1980,
+%[- MARK -] - gb2312_80, iso_ir_58}
+%[- MARK -] + {chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980,
+%[- MARK -] + gb2312-80, iso-ir-58}
+%[- MARK -] {Simplified Chinese}
+%[- MARK -]
+%[- MARK -] \lineiii{gbk}
+%[- MARK -] {936, cp936, ms936}
+%[- MARK -] {Unified Chinese}
+%[- MARK -]
+%[- MARK -] \lineiii{gb18030}
+%[- MARK -] - {gb18030_2000}
+%[- MARK -] + {gb18030-2000}
+%[- MARK -] {Unified Chinese}
+%[- MARK -]
+%[- MARK -] \lineiii{hz}
+%[- MARK -] - {hzgb, hz_gb, hz_gb_2312}
+%[- MARK -] + {hzgb, hz-gb, hz-gb-2312}
+%[- MARK -] {Simplified Chinese}
+%[- MARK -]
+%[- MARK -] \lineiii{iso2022_jp}
+%[- MARK -] - {csiso2022jp, iso2022jp, iso_2022_jp}
+%[- MARK -] + {csiso2022jp, iso2022jp, iso-2022-jp}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{iso2022_jp_1}
+%[- MARK -] - {iso2022jp_1, iso_2022_jp_1}
+%[- MARK -] + {iso2022jp-1, iso-2022-jp-1}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{iso2022_jp_2}
+%[- MARK -] - {iso2022jp_2, iso_2022_jp_2}
+%[- MARK -] + {iso2022jp-2, iso-2022-jp-2}
+%[- MARK -] {Japanese, Korean, Simplified Chinese, Western Europe, Greek}
+%[- MARK -]
+%[- MARK -] +\lineiii{iso2022_jp_2004}
+%[- MARK -] + {iso2022jp-2004, iso-2022-jp-2004}
+%[- MARK -] + {Japanese}
+%[- MARK -] +
+%[- MARK -] \lineiii{iso2022_jp_3}
+%[- MARK -] - {iso2022jp_3, iso_2022_jp_3}
+%[- MARK -] + {iso2022jp-3, iso-2022-jp-3}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{iso2022_jp_ext}
+%[- MARK -] - {iso2022jp_ext, iso_2022_jp_ext}
+%[- MARK -] + {iso2022jp-ext, iso-2022-jp-ext}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{iso2022_kr}
+%[- MARK -] - {csiso2022kr, iso2022kr, iso_2022_kr}
+%[- MARK -] + {csiso2022kr, iso2022kr, iso-2022-kr}
+%[- MARK -] {Korean}
+%[- MARK -]
+%[- MARK -] \lineiii{latin_1}
+%[- MARK -] {iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}
+%[- MARK -] {West Europe}
+%[- MARK -] END DIFF
{Vietnamita}
\lineiii{euc_jp}
@@ -877,6 +1114,23 @@
\lineiii{shift_jis}
{csshiftjis, shiftjis, sjis, s_jis}
+%[- MARK -] BEGIN DIFF 008 of 9
+%[- MARK -] @@ 835
+%[- MARK -]
+%[- MARK -] \lineiii{shift_jis}
+%[- MARK -] {csshiftjis, shiftjis, sjis, s_jis}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] +\lineiii{shift_jis_2004}
+%[- MARK -] + {shiftjis2004, sjis_2004, sjis2004}
+%[- MARK -] + {Japanese}
+%[- MARK -] +
+%[- MARK -] \lineiii{shift_jisx0213}
+%[- MARK -] {shiftjisx0213, sjisx0213, s_jisx0213}
+%[- MARK -] {Japanese}
+%[- MARK -]
+%[- MARK -] \lineiii{utf_16}
+%[- MARK -] END DIFF
{Giapponese}
\lineiii{shift_jisx0213}
@@ -990,6 +1244,21 @@
{}
{Unicode string}
{Produce una stringa assimilabile a una costante Unicode
+%[- MARK -] BEGIN DIFF 009 of 9
+%[- MARK -] @@ 950
+%[- MARK -] Python source code}
+%[- MARK -]
+%[- MARK -] \lineiv{unicode_internal}
+%[- MARK -] {}
+%[- MARK -] {Unicode string}
+%[- MARK -] - {Return the internal represenation of the operand}
+%[- MARK -] + {Return the internal representation of the operand}
+%[- MARK -]
+%[- MARK -] \lineiv{uu_codec}
+%[- MARK -] {uu}
+%[- MARK -] {byte string}
+%[- MARK -] {Convert the operand using uuencode}
+%[- MARK -] END DIFF
in codice sorgente Python}
\lineiv{unicode_internal}
Modified: python/python/Doc/branches/2.4.3/lib/libcodeop.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcodeop.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcodeop.tex Fri Jun 2 12:52:55 2006
@@ -15,6 +15,21 @@
un ciclo simile nel vostro programma, probabilmente vorrete usare il
modulo \refmodule{code}.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 17
+%[- MARK -] There are two parts to this job:
+%[- MARK -]
+%[- MARK -] \begin{enumerate}
+%[- MARK -] \item Being able to tell if a line of input completes a Python
+%[- MARK -] statement: in short, telling whether to print
+%[- MARK -] - `\code{>\code{>}>~} or `\code{...~}' next.
+%[- MARK -] + `\code{>\code{>}>~}' or `\code{...~}' next.
+%[- MARK -] \item Remembering which future statements the user has entered, so
+%[- MARK -] subsequent input can be compiled with these in effect.
+%[- MARK -] \end{enumerate}
+%[- MARK -]
+%[- MARK -] The \module{codeop} module provides a way of doing each of these
+%[- MARK -] END DIFF
Due parti suddividono questo lavoro:
\begin{enumerate}
@@ -59,6 +74,21 @@
caratteri di fine riga può essere seguito da garbage arbitraria. Questo
comportamento verrà corretto quando le API per il parser verranno
migliorate.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 56
+%[- MARK -] followed by arbitrary garbage. This will be fixed once the API
+%[- MARK -] for the parser is better.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{Compile}{}
+%[- MARK -] -Instances of this class have \method{__call__()} methods indentical in
+%[- MARK -] +Instances of this class have \method{__call__()} methods identical in
+%[- MARK -] signature to the built-in function \function{compile()}, but with the
+%[- MARK -] difference that if the instance compiles program text containing a
+%[- MARK -] \module{__future__} statement, the instance 'remembers' and compiles
+%[- MARK -] all subsequent program texts with the statement in force.
+%[- MARK -] \end{classdesc}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{classdesc}{Compile}{}
Modified: python/python/Doc/branches/2.4.3/lib/libcollections.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcollections.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcollections.tex Fri Jun 2 12:52:55 2006
@@ -147,6 +147,29 @@
\subsection{Ricette \label{deque-recipes}}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 133
+%[- MARK -] \subsection{Recipes \label{deque-recipes}}
+%[- MARK -]
+%[- MARK -] This section shows various approaches to working with deques.
+%[- MARK -]
+%[- MARK -] The \method{rotate()} method provides a way to implement \class{deque}
+%[- MARK -] -slicing and deletion:
+%[- MARK -] -
+%[- MARK -] -This pure python implementation of \code{del d[n]} shows how to use the
+%[- MARK -] -\method{rotate()} method as a building block for implementing a variety
+%[- MARK -] -of class{deque} operations:
+%[- MARK -] -
+%[- MARK -] +slicing and deletion. For example, a pure python implementation of
+%[- MARK -] +\code{del d[n]} relies on the \method{rotate()} method to position
+%[- MARK -] +elements to be popped:
+%[- MARK -] +
+%[- MARK -] \begin{verbatim}
+%[- MARK -] def delete_nth(d, n):
+%[- MARK -] d.rotate(-n)
+%[- MARK -] d.popleft()
+%[- MARK -] d.rotate(n)
+%[- MARK -] END DIFF
Questa sezione mostra vari approcci per lavorare con i deque.
Il metodo \method{rotate()} fornisce un modo per implementare
@@ -201,6 +224,25 @@
g
h
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 186
+%[- MARK -]
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] Multi-pass data reduction algorithms can be succinctly expressed and
+%[- MARK -] -efficiently coded by extracting elements using multiple calls to
+%[- MARK -] -\method{popleft()}, applying the reduction function, and using
+%[- MARK -] -\method{append()} for adding the result back to the queue.
+%[- MARK -] +efficiently coded by extracting elements with multiple calls to
+%[- MARK -] +\method{popleft()}, applying the reduction function, and calling
+%[- MARK -] +\method{append()} to add the result back to the queue.
+%[- MARK -]
+%[- MARK -] For example, building a balanced binary tree of nested lists entails
+%[- MARK -] reducing two adjacent nodes into one by grouping them in a list:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libcookie.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcookie.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcookie.tex Fri Jun 2 12:52:55 2006
@@ -70,6 +70,23 @@
probabilmente un errore e verrà quanto prima rimosso. Non si deve
utilizzare la classe \class{Cookie} nelle proprie applicazioni, per lo
stesso motivo per cui non si deve utilizzare la classe
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 66
+%[- MARK -] the \class{Cookie} class in your applications, for the same reason why
+%[- MARK -] you should not use the \class{SerialCookie} class.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] + \seemodule{cookielib}{HTTP cookie handling for web
+%[- MARK -] + \emph{clients}. The \module{cookielib} and \module{Cookie}
+%[- MARK -] + modules do not depend on each other.}
+%[- MARK -] +
+%[- MARK -] \seerfc{2109}{HTTP State Management Mechanism}{This is the state
+%[- MARK -] management specification implemented by this module.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] END DIFF
\class{SerialCookie}.
Added: python/python/Doc/branches/2.4.3/lib/libcookielib.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libcookielib.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,692 @@
+%[- MARK -] BEGIN PART 001 of 7
+\section{\module{cookielib} ---
+ Cookie handling for HTTP clients}
+
+\declaremodule{standard}{cookielib}
+\moduleauthor{John J. Lee}{jjl a pobox.com}
+\sectionauthor{John J. Lee}{jjl a pobox.com}
+
+\modulesynopsis{Cookie handling for HTTP clients}
+
+The \module{cookielib} module defines classes for automatic handling
+of HTTP cookies. It is useful for accessing web sites that require
+small pieces of data -- \dfn{cookies} -- to be set on the client
+machine by an HTTP response from a web server, and then returned to
+the server in later HTTP requests.
+
+Both the regular Netscape cookie protocol and the protocol defined by
+\rfc{2965} are handled. RFC 2965 handling is switched off by default.
+\rfc{2109} cookies are parsed as Netscape cookies and subsequently
+treated as RFC 2965 cookies. Note that the great majority of cookies
+on the Internet are Netscape cookies. \module{cookielib} attempts to
+follow the de-facto Netscape cookie protocol (which differs
+substantially from that set out in the original Netscape
+specification), including taking note of the \code{max-age} and
+\code{port} cookie-attributes introduced with RFC 2109. \note{The
+various named parameters found in \mailheader{Set-Cookie} and
+\mailheader{Set-Cookie2} headers (eg. \code{domain} and
+\code{expires}) are conventionally referred to as \dfn{attributes}.
+To distinguish them from Python attributes, the documentation for this
+module uses the term \dfn{cookie-attribute} instead}.
+
+
+The module defines the following exception:
+
+\begin{excdesc}{LoadError}
+Instances of \class{FileCookieJar} raise this exception on failure to
+load cookies from a file.
+\end{excdesc}
+
+
+The following classes are provided:
+
+\begin{classdesc}{CookieJar}{policy=\constant{None}}
+\var{policy} is an object implementing the \class{CookiePolicy}
+interface.
+
+The \class{CookieJar} class stores HTTP cookies. It extracts cookies
+from HTTP requests, and returns them in HTTP responses.
+\class{CookieJar} instances automatically expire contained cookies
+when necessary. Subclasses are also responsible for storing and
+retrieving cookies from a file or database.
+\end{classdesc}
+
+\begin{classdesc}{FileCookieJar}{filename, delayload=\constant{None},
+ policy=\constant{None}}
+\var{policy} is an object implementing the \class{CookiePolicy}
+interface. For the other arguments, see the documentation for the
+corresponding attributes.
+
+A \class{CookieJar} which can load cookies from, and perhaps save
+cookies to, a file on disk. Cookies are \strong{NOT} loaded from the
+named file until either the \method{load()} or \method{revert()}
+method is called. Subclasses of this class are documented in section
+\ref{file-cookie-jar-classes}.
+\end{classdesc}
+
+\begin{classdesc}{CookiePolicy}{}
+This class is responsible for deciding whether each cookie should be
+accepted from / returned to the server.
+\end{classdesc}
+
+\begin{classdesc}{DefaultCookiePolicy}{
+ blocked_domains=\constant{None},
+ allowed_domains=\constant{None},
+ netscape=\constant{True}, rfc2965=\constant{False},
+ hide_cookie2=\constant{False},
+ strict_domain=\constant{False},
+ strict_rfc2965_unverifiable=\constant{True},
+ strict_ns_unverifiable=\constant{False},
+ strict_ns_domain=\constant{DefaultCookiePolicy.DomainLiberal},
+ strict_ns_set_initial_dollar=\constant{False},
+ strict_ns_set_path=\constant{False}
+ }
+
+Constructor arguments should be passed as keyword arguments only.
+\var{blocked_domains} is a sequence of domain names that we never
+accept cookies from, nor return cookies to. \var{allowed_domains} if
+not \constant{None}, this is a sequence of the only domains for which
+we accept and return cookies. For all other arguments, see the
+documentation for \class{CookiePolicy} and \class{DefaultCookiePolicy}
+objects.
+
+\class{DefaultCookiePolicy} implements the standard accept / reject
+rules for Netscape and RFC 2965 cookies. RFC 2109 cookies
+(ie. cookies received in a \mailheader{Set-Cookie} header with a
+version cookie-attribute of 1) are treated according to the RFC 2965
+rules. \class{DefaultCookiePolicy} also provides some parameters to
+allow some fine-tuning of policy.
+\end{classdesc}
+
+\begin{classdesc}{Cookie}{}
+%[- MARK -] BEGIN PART 002 of 7
+This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is
+not expected that users of \module{cookielib} construct their own
+\class{Cookie} instances. Instead, if necessary, call
+\method{make_cookies()} on a \class{CookieJar} instance.
+\end{classdesc}
+
+\begin{seealso}
+
+\seemodule{urllib2}{URL opening with automatic cookie handling.}
+
+\seemodule{Cookie}{HTTP cookie classes, principally useful for
+server-side code. The \module{cookielib} and \module{Cookie} modules
+do not depend on each other.}
+
+\seeurl{http://wwwsearch.sf.net/ClientCookie/}{Extensions to this
+module, including a class for reading Microsoft Internet Explorer
+cookies on Windows.}
+
+\seeurl{http://www.netscape.com/newsref/std/cookie_spec.html}{The
+specification of the original Netscape cookie protocol. Though this
+is still the dominant protocol, the 'Netscape cookie protocol'
+implemented by all the major browsers (and \module{cookielib}) only
+bears a passing resemblance to the one sketched out in
+\code{cookie_spec.html}.}
+
+\seerfc{2109}{HTTP State Management Mechanism}{Obsoleted by RFC 2965.
+Uses \mailheader{Set-Cookie} with version=1.}
+
+\seerfc{2965}{HTTP State Management Mechanism}{The Netscape protocol
+with the bugs fixed. Uses \mailheader{Set-Cookie2} in place of
+\mailheader{Set-Cookie}. Not widely used.}
+
+\seeurl{http://kristol.org/cookie/errata.html}{Unfinished errata to
+RFC 2965.}
+
+\seerfc{2964}{Use of HTTP State Management}{}
+
+\end{seealso}
+
+
+\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
+
+\class{CookieJar} objects support the iterator protocol for iterating
+over contained \class{Cookie} objects.
+
+\class{CookieJar} has the following methods:
+
+\begin{methoddesc}[CookieJar]{add_cookie_header}{request}
+Add correct \mailheader{Cookie} header to \var{request}.
+
+If policy allows (ie. the \member{rfc2965} and \member{hide_cookie2}
+attributes of the \class{CookieJar}'s \class{CookiePolicy} instance
+are true and false respectively), the \mailheader{Cookie2} header is
+also added when appropriate.
+
+The \var{request} object (usually a \class{urllib2.Request} instance)
+must support the methods \method{get_full_url()}, \method{get_host()},
+\method{get_type()}, \method{unverifiable()},
+\method{get_origin_req_host()}, \method{has_header()},
+\method{get_header()}, \method{header_items()}, and
+\method{add_unredirected_header()},as documented by \module{urllib2}.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{extract_cookies}{response, request}
+Extract cookies from HTTP \var{response} and store them in the
+\class{CookieJar}, where allowed by policy.
+
+The \class{CookieJar} will look for allowable \mailheader{Set-Cookie}
+and \mailheader{Set-Cookie2} headers in the \var{response} argument,
+and store cookies as appropriate (subject to the
+\method{CookiePolicy.set_ok()} method's approval).
+
+The \var{response} object (usually the result of a call to
+\method{urllib2.urlopen()}, or similar) should support an
+\method{info()} method, which returns an object with a
+\method{getallmatchingheaders()} method (usually a
+\class{mimetools.Message} instance).
+
+The \var{request} object (usually a \class{urllib2.Request} instance)
+must support the methods \method{get_full_url()}, \method{get_host()},
+\method{unverifiable()}, and \method{get_origin_req_host()}, as
+documented by \module{urllib2}. The request is used to set default
+values for cookie-attributes as well as for checking that the cookie
+is allowed to be set.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{set_policy}{policy}
+Set the \class{CookiePolicy} instance to be used.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{make_cookies}{response, request}
+Return sequence of \class{Cookie} objects extracted from
+\var{response} object.
+
+See the documentation for \method{extract_cookies} for the interfaces
+required of the \var{response} and \var{request} arguments.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{set_cookie_if_ok}{cookie, request}
+Set a \class{Cookie} if policy says it's OK to do so.
+%[- MARK -] BEGIN PART 003 of 7
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{set_cookie}{cookie}
+Set a \class{Cookie}, without checking with policy to see whether or
+not it should be set.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{clear}{\optional{domain\optional{,
+ path\optional{, name}}}}
+Clear some cookies.
+
+If invoked without arguments, clear all cookies. If given a single
+argument, only cookies belonging to that \var{domain} will be removed.
+If given two arguments, cookies belonging to the specified
+\var{domain} and URL \var{path} are removed. If given three
+arguments, then the cookie with the specified \var{domain}, \var{path}
+and \var{name} is removed.
+
+Raises \exception{KeyError} if no matching cookie exists.
+\end{methoddesc}
+
+\begin{methoddesc}[CookieJar]{clear_session_cookies}{}
+Discard all session cookies.
+
+Discards all contained cookies that have a true \member{discard}
+attribute (usually because they had either no \code{max-age} or
+\code{expires} cookie-attribute, or an explicit \code{discard}
+cookie-attribute). For interactive browsers, the end of a session
+usually corresponds to closing the browser window.
+
+Note that the \method{save()} method won't save session cookies
+anyway, unless you ask otherwise by passing a true
+\var{ignore_discard} argument.
+\end{methoddesc}
+
+\class{FileCookieJar} implements the following additional methods:
+
+\begin{methoddesc}[FileCookieJar]{save}{filename=\constant{None},
+ ignore_discard=\constant{False}, ignore_expires=\constant{False}}
+Save cookies to a file.
+
+This base class raises \class{NotImplementedError}. Subclasses may
+leave this method unimplemented.
+
+\var{filename} is the name of file in which to save cookies. If
+\var{filename} is not specified, \member{self.filename} is used (whose
+default is the value passed to the constructor, if any); if
+\member{self.filename} is \constant{None}, \exception{ValueError} is
+raised.
+
+\var{ignore_discard}: save even cookies set to be discarded.
+\var{ignore_expires}: save even cookies that have expired
+
+The file is overwritten if it already exists, thus wiping all the
+cookies it contains. Saved cookies can be restored later using the
+\method{load()} or \method{revert()} methods.
+\end{methoddesc}
+
+\begin{methoddesc}[FileCookieJar]{load}{filename=\constant{None},
+ ignore_discard=\constant{False}, ignore_expires=\constant{False}}
+Load cookies from a file.
+
+Old cookies are kept unless overwritten by newly loaded ones.
+
+Arguments are as for \method{save()}.
+
+The named file must be in the format understood by the class, or
+\exception{LoadError} will be raised.
+\end{methoddesc}
+
+\begin{methoddesc}[FileCookieJar]{revert}{filename=\constant{None},
+ ignore_discard=\constant{False}, ignore_expires=\constant{False}}
+Clear all cookies and reload cookies from a saved file.
+
+Raises \exception{cookielib.LoadError} or \exception{IOError} if
+reversion is not successful; the object's state will not be altered if
+this happens.
+\end{methoddesc}
+
+\class{FileCookieJar} instances have the following public attributes:
+
+\begin{memberdesc}{filename}
+Filename of default file in which to keep cookies. This attribute may
+be assigned to.
+\end{memberdesc}
+
+\begin{memberdesc}{delayload}
+If true, load cookies lazily from disk. This attribute should not be
+assigned to. This is only a hint, since this only affects
+performance, not behaviour (unless the cookies on disk are changing).
+A \class{CookieJar} object may ignore it. None of the
+\class{FileCookieJar} classes included in the standard library lazily
+loads cookies.
+\end{memberdesc}
+
+
+\subsection{FileCookieJar subclasses and co-operation with web browsers
+ \label{file-cookie-jar-classes}}
+
+The following \class{CookieJar} subclasses are provided for reading
+%[- MARK -] BEGIN PART 004 of 7
+and writing . Further \class{CookieJar} subclasses, including one
+that reads Microsoft Internet Explorer cookies, are available at
+\url{http://wwwsearch.sf.net/ClientCookie/}.
+
+\begin{classdesc}{MozillaCookieJar}{filename, delayload=\constant{None},
+ policy=\constant{None}}
+A \class{FileCookieJar} that can load from and save cookies to disk in
+the Mozilla \code{cookies.txt} file format (which is also used by the
+Lynx and Netscape browsers). \note{This loses information about RFC
+2965 cookies, and also about newer or non-standard cookie-attributes
+such as \code{port}.}
+
+\warning{Back up your cookies before saving if you have cookies whose
+loss / corruption would be inconvenient (there are some subtleties
+which may lead to slight changes in the file over a load / save
+round-trip).}
+
+Also note that cookies saved while Mozilla is running will get
+clobbered by Mozilla.
+\end{classdesc}
+
+\begin{classdesc}{LWPCookieJar}{filename, delayload=\constant{None},
+ policy=\constant{None}}
+A \class{FileCookieJar} that can load from and save cookies to disk in
+format compatible with the libwww-perl library's \code{Set-Cookie3}
+file format. This is convenient if you want to store cookies in a
+human-readable file.
+\end{classdesc}
+
+
+\subsection{CookiePolicy Objects \label{cookie-policy-objects}}
+
+Objects implementing the \class{CookiePolicy} interface have the
+following methods:
+
+\begin{methoddesc}[CookiePolicy]{set_ok}{cookie, request}
+Return boolean value indicating whether cookie should be accepted from server.
+
+\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
+an object implementing the interface defined by the documentation for
+\method{CookieJar.extract_cookies()}.
+\end{methoddesc}
+
+\begin{methoddesc}[CookiePolicy]{return_ok}{cookie, request}
+Return boolean value indicating whether cookie should be returned to server.
+
+\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
+an object implementing the interface defined by the documentation for
+\method{CookieJar.add_cookie_header()}.
+\end{methoddesc}
+
+\begin{methoddesc}[CookiePolicy]{domain_return_ok}{domain, request}
+Return false if cookies should not be returned, given cookie domain.
+
+This method is an optimization. It removes the need for checking
+every cookie with a particular domain (which might involve reading
+many files). Returning true from \method{domain_return_ok()} and
+\method{path_return_ok()} leaves all the work to \method{return_ok()}.
+
+If \method{domain_return_ok()} returns true for the cookie domain,
+\method{path_return_ok()} is called for the cookie path. Otherwise,
+\method{path_return_ok()} and \method{return_ok()} are never called
+for that cookie domain. If \method{path_return_ok()} returns true,
+\method{return_ok()} is called with the \class{Cookie} object itself
+for a full check. Otherwise, \method{return_ok()} is never called for
+that cookie path.
+
+Note that \method{domain_return_ok()} is called for every
+\emph{cookie} domain, not just for the \emph{request} domain. For
+example, the function might be called with both \code{".example.com"}
+and \code{"www.example.com"} if the request domain is
+\code{"www.example.com"}. The same goes for
+\method{path_return_ok()}.
+
+The \var{request} argument is as documented for \method{return_ok()}.
+\end{methoddesc}
+
+\begin{methoddesc}[CookiePolicy]{path_return_ok}{path, request}
+Return false if cookies should not be returned, given cookie path.
+
+See the documentation for \method{domain_return_ok()}.
+\end{methoddesc}
+
+
+In addition to implementing the methods above, implementations of the
+\class{CookiePolicy} interface must also supply the following
+attributes, indicating which protocols should be used, and how. All
+of these attributes may be assigned to.
+
+\begin{memberdesc}{netscape}
+Implement Netscape protocol.
+\end{memberdesc}
+\begin{memberdesc}{rfc2965}
+Implement RFC 2965 protocol.
+\end{memberdesc}
+\begin{memberdesc}{hide_cookie2}
+Don't add \mailheader{Cookie2} header to requests (the presence of
+this header indicates to the server that we understand RFC 2965
+cookies).
+\end{memberdesc}
+%[- MARK -] BEGIN PART 005 of 7
+
+The most useful way to define a \class{CookiePolicy} class is by
+subclassing from \class{DefaultCookiePolicy} and overriding some or
+all of the methods above. \class{CookiePolicy} itself may be used as
+a 'null policy' to allow setting and receiving any and all cookies
+(this is unlikely to be useful).
+
+
+\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
+
+Implements the standard rules for accepting and returning cookies.
+
+Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is
+switched off by default.
+
+The easiest way to provide your own policy is to override this class
+and call its methods in your overridden implementations before adding
+your own additional checks:
+
+\begin{verbatim}
+import cookielib
+class MyCookiePolicy(cookielib.DefaultCookiePolicy):
+ def set_ok(self, cookie, request):
+ if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
+ return False
+ if i_dont_want_to_store_this_cookie(cookie):
+ return False
+ return True
+\end{verbatim}
+
+In addition to the features required to implement the
+\class{CookiePolicy} interface, this class allows you to block and
+allow domains from setting and receiving cookies. There are also some
+strictness switches that allow you to tighten up the rather loose
+Netscape protocol rules a little bit (at the cost of blocking some
+benign cookies).
+
+A domain blacklist and whitelist is provided (both off by default).
+Only domains not in the blacklist and present in the whitelist (if the
+whitelist is active) participate in cookie setting and returning. Use
+the \var{blocked_domains} constructor argument, and
+\method{blocked_domains()} and \method{set_blocked_domains()} methods
+(and the corresponding argument and methods for
+\var{allowed_domains}). If you set a whitelist, you can turn it off
+again by setting it to \constant{None}.
+
+Domains in block or allow lists that do not start with a dot must
+equal the cookie domain to be matched. For example,
+\code{"example.com"} matches a blacklist entry of
+\code{"example.com"}, but \code{"www.example.com"} does not. Domains
+that do start with a dot are matched by more specific domains too.
+For example, both \code{"www.example.com"} and
+\code{"www.coyote.example.com"} match \code{".example.com"} (but
+\code{"example.com"} itself does not). IP addresses are an exception,
+and must match exactly. For example, if blocked_domains contains
+\code{"192.168.1.2"} and \code{".168.1.2"}, 192.168.1.2 is blocked,
+but 193.168.1.2 is not.
+
+\class{DefaultCookiePolicy} implements the following additional
+methods:
+
+\begin{methoddesc}[DefaultCookiePolicy]{blocked_domains}{}
+Return the sequence of blocked domains (as a tuple).
+\end{methoddesc}
+
+\begin{methoddesc}[DefaultCookiePolicy]{set_blocked_domains}
+ {blocked_domains}
+Set the sequence of blocked domains.
+\end{methoddesc}
+
+\begin{methoddesc}[DefaultCookiePolicy]{is_blocked}{domain}
+Return whether \var{domain} is on the blacklist for setting or
+receiving cookies.
+\end{methoddesc}
+
+\begin{methoddesc}[DefaultCookiePolicy]{allowed_domains}{}
+Return \constant{None}, or the sequence of allowed domains (as a tuple).
+\end{methoddesc}
+
+\begin{methoddesc}[DefaultCookiePolicy]{set_allowed_domains}
+ {allowed_domains}
+Set the sequence of allowed domains, or \constant{None}.
+\end{methoddesc}
+
+\begin{methoddesc}[DefaultCookiePolicy]{is_not_allowed}{domain}
+Return whether \var{domain} is not on the whitelist for setting or
+receiving cookies.
+\end{methoddesc}
+
+\class{DefaultCookiePolicy} instances have the following attributes,
+which are all initialised from the constructor arguments of the same
+name, and which may all be assigned to.
+
+General strictness switches:
+
+\begin{memberdesc}{strict_domain}
+Don't allow sites to set two-component domains with country-code
+top-level domains like \code{.co.uk}, \code{.gov.uk},
+\code{.co.nz}.etc. This is far from perfect and isn't guaranteed to
+work!
+%[- MARK -] BEGIN PART 006 of 7
+\end{memberdesc}
+
+RFC 2965 protocol strictness switches:
+
+\begin{memberdesc}{strict_rfc2965_unverifiable}
+Follow RFC 2965 rules on unverifiable transactions (usually, an
+unverifiable transaction is one resulting from a redirect or a request
+for an image hosted on another site). If this is false, cookies are
+\emph{never} blocked on the basis of verifiability
+\end{memberdesc}
+
+Netscape protocol strictness switches:
+
+\begin{memberdesc}{strict_ns_unverifiable}
+apply RFC 2965 rules on unverifiable transactions even to Netscape
+cookies
+\end{memberdesc}
+\begin{memberdesc}{strict_ns_domain}
+Flags indicating how strict to be with domain-matching rules for
+Netscape cookies. See below for acceptable values.
+\end{memberdesc}
+\begin{memberdesc}{strict_ns_set_initial_dollar}
+Ignore cookies in Set-Cookie: headers that have names starting with
+\code{'\$'}.
+\end{memberdesc}
+\begin{memberdesc}{strict_ns_set_path}
+Don't allow setting cookies whose path doesn't path-match request URI.
+\end{memberdesc}
+
+\member{strict_ns_domain} is a collection of flags. Its value is
+constructed by or-ing together (for example,
+\code{DomainStrictNoDots|DomainStrictNonDomain} means both flags are
+set).
+
+\begin{memberdesc}{DomainStrictNoDots}
+When setting cookies, the 'host prefix' must not contain a dot
+(eg. \code{www.foo.bar.com} can't set a cookie for \code{.bar.com},
+because \code{www.foo} contains a dot).
+\end{memberdesc}
+\begin{memberdesc}{DomainStrictNonDomain}
+Cookies that did not explicitly specify a \code{domain}
+cookie-attribute can only be returned to a domain equal to the domain
+that set the cookie (eg. \code{spam.example.com} won't be returned
+cookies from \code{example.com} that had no \code{domain}
+cookie-attribute).
+\end{memberdesc}
+\begin{memberdesc}{DomainRFC2965Match}
+When setting cookies, require a full RFC 2965 domain-match.
+\end{memberdesc}
+
+The following attributes are provided for convenience, and are the
+most useful combinations of the above flags:
+
+\begin{memberdesc}{DomainLiberal}
+Equivalent to 0 (ie. all of the above Netscape domain strictness flags
+switched off).
+\end{memberdesc}
+\begin{memberdesc}{DomainStrict}
+Equivalent to \code{DomainStrictNoDots|DomainStrictNonDomain}.
+\end{memberdesc}
+
+
+\subsection{Cookie Objects \label{cookie-objects}}
+
+\class{Cookie} instances have Python attributes roughly corresponding
+to the standard cookie-attributes specified in the various cookie
+standards. The correspondence is not one-to-one, because there are
+complicated rules for assigning default values, and because the
+\code{max-age} and \code{expires} cookie-attributes contain equivalent
+information.
+
+Assignment to these attributes should not be necessary other than in
+rare circumstances in a \class{CookiePolicy} method. The class does
+not enforce internal consistency, so you should know what you're
+doing if you do that.
+
+\begin{memberdesc}[Cookie]{version}
+Integer or \constant{None}. Netscape cookies have version 0. RFC
+2965 and RFC 2109 cookies have version 1.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{name}
+Cookie name (a string).
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{value}
+Cookie value (a string), or \constant{None}.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{port}
+String representing a port or a set of ports (eg. '80', or '80,8080'),
+or \constant{None}.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{path}
+Cookie path (a string, eg. \code{'/acme/rocket_launchers'}).
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{secure}
+True if cookie should only be returned over a secure connection.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{expires}
+Integer expiry date in seconds since epoch, or \constant{None}. See
+also the \method{is_expired()} method.
+\end{memberdesc}
+%[- MARK -] BEGIN PART 007 of 7
+\begin{memberdesc}[Cookie]{discard}
+True if this is a session cookie.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{comment}
+String comment from the server explaining the function of this cookie,
+or \constant{None}.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{comment_url}
+URL linking to a comment from the server explaining the function of
+this cookie, or \constant{None}.
+\end{memberdesc}
+
+\begin{memberdesc}[Cookie]{port_specified}
+True if a port or set of ports was explicitly specified by the server
+(in the \mailheader{Set-Cookie} / \mailheader{Set-Cookie2} header).
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{domain_specified}
+True if a domain was explicitly specified by the server.
+\end{memberdesc}
+\begin{memberdesc}[Cookie]{domain_initial_dot}
+True if the domain explicitly specified by the server began with a
+dot (\code{'.'}).
+\end{memberdesc}
+
+Cookies may have additional non-standard cookie-attributes. These may
+be accessed using the following methods:
+
+\begin{methoddesc}[Cookie]{has_nonstandard_attr}{name}
+Return true if cookie has the named cookie-attribute.
+\end{methoddesc}
+\begin{methoddesc}[Cookie]{get_nonstandard_attr}{name, default=\constant{None}}
+If cookie has the named cookie-attribute, return its value.
+Otherwise, return \var{default}.
+\end{methoddesc}
+\begin{methoddesc}[Cookie]{set_nonstandard_attr}{name, value}
+Set the value of the named cookie-attribute.
+\end{methoddesc}
+
+The \class{Cookie} class also defines the following method:
+
+\begin{methoddesc}[Cookie]{is_expired}{\optional{now=\constant{None}}}
+True if cookie has passed the time at which the server requested it
+should expire. If \var{now} is given (in seconds since the epoch),
+return whether the cookie has expired at the specified time.
+\end{methoddesc}
+
+
+\subsection{Examples \label{cookielib-examples}}
+
+The first example shows the most common usage of \module{cookielib}:
+
+\begin{verbatim}
+import cookielib, urllib2
+cj = cookielib.CookieJar()
+opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+r = opener.open("http://example.com/")
+\end{verbatim}
+
+This example illustrates how to open a URL using your Netscape,
+Mozilla, or Lynx cookies (assumes \UNIX{}/Netscape convention for
+location of the cookies file):
+
+\begin{verbatim}
+import os, cookielib, urllib2
+cj = cookielib.MozillaCookieJar()
+cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
+opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+r = opener.open("http://example.com/")
+\end{verbatim}
+
+The next example illustrates the use of \class{DefaultCookiePolicy}.
+Turn on RFC 2965 cookies, be more strict about domains when setting
+and returning Netscape cookies, and block some domains from setting
+cookies or having them returned:
+
+\begin{verbatim}
+import urllib2
+from cookielib import CookieJar, DefaultCookiePolicy
+policy = DefaultCookiePolicy(
+ rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+ blocked_domains=["ads.net", ".ads.net"])
+cj = CookieJar(policy)
+opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
+r = opener.open("http://example.com/")
+\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libcrypt.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcrypt.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcrypt.tex Fri Jun 2 12:52:55 2006
@@ -16,6 +16,35 @@
vedete anche la relativa pagina man di \UNIX{} per ulteriori dettagli.
Tra i possibili utilizzi annoveriamo la possibilità degli script Python di
accettare password digitate dall'utente o quella di tentare la rottura di
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 15
+%[- MARK -] function based upon a modified DES\indexii{cipher}{DES} algorithm; see
+%[- MARK -] the \UNIX{} man page for further details. Possible uses include
+%[- MARK -] allowing Python scripts to accept typed passwords from the user, or
+%[- MARK -] attempting to crack \UNIX{} passwords with a dictionary.
+%[- MARK -]
+%[- MARK -] +Notice that the behavior of this module depends on the actual implementation
+%[- MARK -] +of the \manpage{crypt}{3}\index{crypt(3)} routine in the running system.
+%[- MARK -] +Therefore, any extensions available on the current implementation will also
+%[- MARK -] +be available on this module.
+%[- MARK -] \begin{funcdesc}{crypt}{word, salt}
+%[- MARK -] \var{word} will usually be a user's password as typed at a prompt or
+%[- MARK -] in a graphical interface. \var{salt} is usually a random
+%[- MARK -] two-character string which will be used to perturb the DES algorithm
+%[- MARK -] in one of 4096 ways. The characters in \var{salt} must be in the
+%[- MARK -] set \regexp{[./a-zA-Z0-9]}. Returns the hashed password as a
+%[- MARK -] string, which will be composed of characters from the same alphabet
+%[- MARK -] as the salt (the first two characters represent the salt itself).
+%[- MARK -] +
+%[- MARK -] + Since a few \manpage{crypt}{3}\index{crypt(3)} extensions allow different
+%[- MARK -] + values, with different sizes in the \var{salt}, it is recommended to use
+%[- MARK -] + the full crypted password as salt when checking for a password.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] A simple example illustrating typical use:
+%[- MARK -]
+%[- MARK -] END DIFF
password \UNIX{} tramite un dizionario.
\begin{funcdesc}{crypt}{word, salt}
@@ -33,6 +62,19 @@
Un semplice esempio ne illustra un utilizzo tipico:
\begin{verbatim}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 38
+%[- MARK -] cryptedpasswd = pwd.getpwnam(username)[1]
+%[- MARK -] if cryptedpasswd:
+%[- MARK -] if cryptedpasswd == 'x' or cryptedpasswd == '*':
+%[- MARK -] raise "Sorry, currently no support for shadow passwords"
+%[- MARK -] cleartext = getpass.getpass()
+%[- MARK -] - return crypt.crypt(cleartext, cryptedpasswd[:2]) == cryptedpasswd
+%[- MARK -] + return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
+%[- MARK -] else:
+%[- MARK -] return 1
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
import crypt, getpass, pwd
def login():
Modified: python/python/Doc/branches/2.4.3/lib/libcsv.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libcsv.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libcsv.tex Fri Jun 2 12:52:55 2006
@@ -349,6 +349,38 @@
\subsection{Esempi}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 312
+%[- MARK -]
+%[- MARK -] The ``Hello, world'' of csv reading is
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import csv
+%[- MARK -] -reader = csv.reader(file("some.csv", "rb"))
+%[- MARK -] +reader = csv.reader(open("some.csv", "rb"))
+%[- MARK -] for row in reader:
+%[- MARK -] print row
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] +To print just the first and last columns of each row try
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import csv
+%[- MARK -] +reader = csv.reader(open("some.csv", "rb"))
+%[- MARK -] +for row in reader:
+%[- MARK -] + print row[0], row[-1]
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] The corresponding simplest possible writing example is
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import csv
+%[- MARK -] -writer = csv.writer(file("some.csv", "wb"))
+%[- MARK -] +writer = csv.writer(open("some.csv", "wb"))
+%[- MARK -] for row in someiterable:
+%[- MARK -] writer.writerow(row)
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
Il programma ``Hello, world'' per la lettura csv è:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libdatetime.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libdatetime.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libdatetime.tex Fri Jun 2 12:52:55 2006
@@ -16,6 +16,21 @@
tempi sia in modalità semplici che complesse. Anche se viene supportata
l'aritmetica di tempi e date, l'implementazione del modulo si focalizza
sopratutto su un'efficiente estrazione delle componenti, per la
+%[- MARK -] BEGIN DIFF 001 of 6
+%[- MARK -] @@ 21
+%[- MARK -] This distinction refers to whether the object has any notion of time
+%[- MARK -] zone, daylight saving time, or other kind of algorithmic or political
+%[- MARK -] time adjustment. Whether a naive \class{datetime} object represents
+%[- MARK -] Coordinated Universal Time (UTC), local time, or time in some other
+%[- MARK -] timezone is purely up to the program, just like it's up to the program
+%[- MARK -] -whether a particular number represents meters, miles, or mass. Naive
+%[- MARK -] +whether a particular number represents metres, miles, or mass. Naive
+%[- MARK -] \class{datetime} objects are easy to understand and to work with, at
+%[- MARK -] the cost of ignoring some aspects of reality.
+%[- MARK -]
+%[- MARK -] For applications requiring more, \class{datetime} and \class{time}
+%[- MARK -] objects have an optional time zone information member,
+%[- MARK -] END DIFF
manipolazione e la formattazione dell'output.
Esistono due categorie di oggetti rappresentanti date e tempi:
@@ -432,6 +447,21 @@
Questa espressione è esatta e non può provocare overflow.
\code{\var{timedelta}.seconds} e \code{\var{timedelta}.microseconds}
sono posti uguali a zero e dopo il calcolo è vera l'espressione
+%[- MARK -] BEGIN DIFF 002 of 6
+%[- MARK -] @@ 396
+%[- MARK -] after.
+%[- MARK -]
+%[- MARK -] \item[(4)]
+%[- MARK -] In other words, \code{date1 < date2}
+%[- MARK -] if and only if \code{\var{date1}.toordinal() <
+%[- MARK -] - \var{date2}.toordinal()}.
+%[- MARK -] + \var{date2}.toordinal()}.
+%[- MARK -] In order to stop comparison from falling back to the default
+%[- MARK -] scheme of comparing object addresses, date comparison
+%[- MARK -] normally raises \exception{TypeError} if the other comparand
+%[- MARK -] isn't also a \class{date} object. However, \code{NotImplemented}
+%[- MARK -] is returned instead if the other comparand has a
+%[- MARK -] END DIFF
\code{\var{date2} + \var{timedelta} == time1}.
\item[(4)]
@@ -460,6 +490,33 @@
dizionario. In contesti booleani, tutti gli oggetti di tipo
\class{date} vengono considerati valori veri.
+%[- MARK -] BEGIN DIFF 003 of 6
+%[- MARK -] @@ 421
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{replace}{year, month, day}
+%[- MARK -] Return a date with the same value, except for those members given
+%[- MARK -] new values by whichever keyword arguments are specified. For
+%[- MARK -] example, if \code{d == date(2002, 12, 31)}, then
+%[- MARK -] - \code{d.replace(day=26) == date(2000, 12, 26)}.
+%[- MARK -] + \code{d.replace(day=26) == date(2002, 12, 26)}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{timetuple}{}
+%[- MARK -] Return a \class{time.struct_time} such as returned by
+%[- MARK -] \function{time.localtime()}. The hours, minutes and seconds are
+%[- MARK -] 0, and the DST flag is -1.
+%[- MARK -] \code{\var{d}.timetuple()} is equivalent to
+%[- MARK -] \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
+%[- MARK -] - 0, 0, 0,
+%[- MARK -] - \var{d}.weekday(),
+%[- MARK -] + 0, 0, 0,
+%[- MARK -] + \var{d}.weekday(),
+%[- MARK -] \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
+%[- MARK -] -1))}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{toordinal}{}
+%[- MARK -] END DIFF
Metodi delle istanze:
\begin{methoddesc}{replace}{year, month, day}
@@ -518,6 +575,21 @@
settimana di un anno ISO è la prima settimana calendariale dell'anno
Gregoriano che contiene un Giovedì. Questa viene definita settimana
numero 1, e l'anno ISO in cui si trova quel Giovedì coincide con il
+%[- MARK -] BEGIN DIFF 004 of 6
+%[- MARK -] @@ 473
+%[- MARK -]
+%[- MARK -] For example, 2004 begins on a Thursday, so the first week of ISO
+%[- MARK -] year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
+%[- MARK -] 2004, so that
+%[- MARK -] \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
+%[- MARK -] - and
+%[- MARK -] + and
+%[- MARK -] \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{isoformat}{}
+%[- MARK -] Return a string representing the date in ISO 8601 format,
+%[- MARK -] END DIFF
suo anno Gregoriano.
Per esempio, l'anno 2004 comincia con un Giovedì, per cui la prima
@@ -760,6 +832,21 @@
\lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
+%[- MARK -] BEGIN DIFF 005 of 6
+%[- MARK -] @@ 685
+%[- MARK -] \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
+%[- MARK -]
+%[- MARK -] \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
+%[- MARK -]
+%[- MARK -] \lineii{\var{datetime1} < \var{datetime2}}
+%[- MARK -] - {Compares \class{datetime} to \class{datetime}.
+%[- MARK -] + {Compares \class{datetime} to \class{datetime}.
+%[- MARK -] (4)}
+%[- MARK -]
+%[- MARK -] \end{tableii}
+%[- MARK -]
+%[- MARK -] \begin{description}
+%[- MARK -] END DIFF
\lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
\lineii{\var{datetime1} < \var{datetime2}}
@@ -822,6 +909,21 @@
\item[(4)]
\var{datetime1} viene considerato inferiore a \var{datetime2} se
+%[- MARK -] BEGIN DIFF 006 of 6
+%[- MARK -] @@ 734
+%[- MARK -] except that the implementation never overflows.
+%[- MARK -]
+%[- MARK -] \item[(4)]
+%[- MARK -]
+%[- MARK -] \var{datetime1} is considered less than \var{datetime2}
+%[- MARK -] -when \var{datetime1} precedes \var{datetime2} in time.
+%[- MARK -] +when \var{datetime1} precedes \var{datetime2} in time.
+%[- MARK -]
+%[- MARK -] If one comparand is naive and
+%[- MARK -] the other is aware, \exception{TypeError} is raised. If both
+%[- MARK -] comparands are aware, and have the same \member{tzinfo} member,
+%[- MARK -] the common \member{tzinfo} member is ignored and the base datetimes
+%[- MARK -] END DIFF
lo precede nel tempo.
Se un termine di paragone è un oggetto "semplice" e l'altro un
Added: python/python/Doc/branches/2.4.3/lib/libdecimal.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libdecimal.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,1301 @@
+%[- MARK -] BEGIN PART 001 of 13
+\section{\module{decimal} ---
+ Decimal floating point arithmetic}
+
+\declaremodule{standard}{decimal}
+\modulesynopsis{Implementation of the General Decimal Arithmetic
+Specification.}
+
+\moduleauthor{Eric Price}{eprice at tjhsst.edu}
+\moduleauthor{Facundo Batista}{facundo at taniquetil.com.ar}
+\moduleauthor{Raymond Hettinger}{python at rcn.com}
+\moduleauthor{Aahz}{aahz at pobox.com}
+\moduleauthor{Tim Peters}{tim.one at comcast.net}
+
+\sectionauthor{Raymond D. Hettinger}{python at rcn.com}
+
+\versionadded{2.4}
+
+The \module{decimal} module provides support for decimal floating point
+arithmetic. It offers several advantages over the \class{float()} datatype:
+
+\begin{itemize}
+
+\item Decimal numbers can be represented exactly. In contrast, numbers like
+\constant{1.1} do not have an exact representation in binary floating point.
+End users typically would not expect \constant{1.1} to display as
+\constant{1.1000000000000001} as it does with binary floating point.
+
+\item The exactness carries over into arithmetic. In decimal floating point,
+\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero. In binary floating
+point, result is \constant{5.5511151231257827e-017}. While near to zero, the
+differences prevent reliable equality testing and differences can accumulate.
+For this reason, decimal would be preferred in accounting applications which
+have strict equality invariants.
+
+\item The decimal module incorporates a notion of significant places so that
+\samp{1.30 + 1.20} is \constant{2.50}. The trailing zero is kept to indicate
+significance. This is the customary presentation for monetary applications. For
+multiplication, the ``schoolbook'' approach uses all the figures in the
+multiplicands. For instance, \samp{1.3 * 1.2} gives \constant{1.56} while
+\samp{1.30 * 1.20} gives \constant{1.5600}.
+
+\item Unlike hardware based binary floating point, the decimal module has a user
+settable precision (defaulting to 28 places) which can be as large as needed for
+a given problem:
+
+\begin{verbatim}
+>>> getcontext().prec = 6
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857")
+>>> getcontext().prec = 28
+>>> Decimal(1) / Decimal(7)
+Decimal("0.1428571428571428571428571429")
+\end{verbatim}
+
+\item Both binary and decimal floating point are implemented in terms of published
+standards. While the built-in float type exposes only a modest portion of its
+capabilities, the decimal module exposes all required parts of the standard.
+When needed, the programmer has full control over rounding and signal handling.
+
+\end{itemize}
+
+
+The module design is centered around three concepts: the decimal number, the
+context for arithmetic, and signals.
+
+A decimal number is immutable. It has a sign, coefficient digits, and an
+exponent. To preserve significance, the coefficient digits do not truncate
+trailing zeroes. Decimals also include special values such as
+\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}. The standard
+also differentiates \constant{-0} from \constant{+0}.
+
+The context for arithmetic is an environment specifying precision, rounding
+rules, limits on exponents, flags indicating the results of operations,
+and trap enablers which determine whether signals are treated as
+exceptions. Rounding options include \constant{ROUND_CEILING},
+\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN},
+\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{ROUND_UP}.
+
+Signals are groups of exceptional conditions arising during the course of
+computation. Depending on the needs of the application, signals may be
+ignored, considered as informational, or treated as exceptions. The signals in
+the decimal module are: \constant{Clamped}, \constant{InvalidOperation},
+\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded},
+\constant{Subnormal}, \constant{Overflow}, and \constant{Underflow}.
+
+For each signal there is a flag and a trap enabler. When a signal is
+encountered, its flag incremented from zero and, then, if the trap enabler
+is set to one, an exception is raised. Flags are sticky, so the user
+needs to reset them before monitoring a calculation.
+
+
+\begin{seealso}
+ \seetext{IBM's General Decimal Arithmetic Specification,
+ \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html]
+ {The General Decimal Arithmetic Specification}.}
+
+ \seetext{IEEE standard 854-1987,
+ \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html]
+ {Unofficial IEEE 854 Text}.}
+\end{seealso}
+%[- MARK -] BEGIN PART 002 of 13
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Quick-start Tutorial \label{decimal-tutorial}}
+
+The usual start to using decimals is importing the module, viewing the current
+context with \function{getcontext()} and, if necessary, setting new values
+for precision, rounding, or enabled traps:
+
+\begin{verbatim}
+>>> from decimal import *
+>>> getcontext()
+Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[], traps=[Overflow, InvalidOperation,
+ DivisionByZero])
+
+>>> getcontext().prec = 7 # Set a new precision
+\end{verbatim}
+
+
+Decimal instances can be constructed from integers, strings or tuples. To
+create a Decimal from a \class{float}, first convert it to a string. This
+serves as an explicit reminder of the details of the conversion (including
+representation error). Decimal numbers include special values such as
+\constant{NaN} which stands for ``Not a number'', positive and negative
+\constant{Infinity}, and \constant{-0}.
+
+\begin{verbatim}
+>>> Decimal(10)
+Decimal("10")
+>>> Decimal("3.14")
+Decimal("3.14")
+>>> Decimal((0, (3, 1, 4), -2))
+Decimal("3.14")
+>>> Decimal(str(2.0 ** 0.5))
+Decimal("1.41421356237")
+>>> Decimal("NaN")
+Decimal("NaN")
+>>> Decimal("-Infinity")
+Decimal("-Infinity")
+\end{verbatim}
+
+
+The significance of a new Decimal is determined solely by the number
+of digits input. Context precision and rounding only come into play during
+arithmetic operations.
+
+\begin{verbatim}
+>>> getcontext().prec = 6
+>>> Decimal('3.0')
+Decimal("3.0")
+>>> Decimal('3.1415926535')
+Decimal("3.1415926535")
+>>> Decimal('3.1415926535') + Decimal('2.7182818285')
+Decimal("5.85987")
+>>> getcontext().rounding = ROUND_UP
+>>> Decimal('3.1415926535') + Decimal('2.7182818285')
+Decimal("5.85988")
+\end{verbatim}
+
+
+Decimals interact well with much of the rest of python. Here is a small
+decimal floating point flying circus:
+
+\begin{verbatim}
+>>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
+>>> max(data)
+Decimal("9.25")
+>>> min(data)
+Decimal("0.03")
+>>> sorted(data)
+[Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"),
+ Decimal("2.35"), Decimal("3.45"), Decimal("9.25")]
+>>> sum(data)
+Decimal("19.29")
+>>> a,b,c = data[:3]
+>>> str(a)
+'1.34'
+>>> float(a)
+1.3400000000000001
+>>> round(a, 1) # round() first converts to binary floating point
+1.3
+>>> int(a)
+1
+>>> a * 5
+Decimal("6.70")
+>>> a * b
+Decimal("2.5058")
+>>> c % a
+Decimal("0.77")
+\end{verbatim}
+
+The \method{quantize()} method rounds a number to a fixed exponent. This
+method is useful for monetary applications that often round results to a fixed
+number of places:
+
+\begin{verbatim}
+>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
+Decimal("7.32")
+%[- MARK -] BEGIN PART 003 of 13
+>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
+Decimal("8")
+\end{verbatim}
+
+As shown above, the \function{getcontext()} function accesses the current
+context and allows the settings to be changed. This approach meets the
+needs of most applications.
+
+For more advanced work, it may be useful to create alternate contexts using
+the Context() constructor. To make an alternate active, use the
+\function{setcontext()} function.
+
+In accordance with the standard, the \module{Decimal} module provides two
+ready to use standard contexts, \constant{BasicContext} and
+\constant{ExtendedContext}. The former is especially useful for debugging
+because many of the traps are enabled:
+
+\begin{verbatim}
+>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
+>>> setcontext(myothercontext)
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857142857142857142857142857142857142857142857142857142857")
+
+>>> ExtendedContext
+Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[], traps=[])
+>>> setcontext(ExtendedContext)
+>>> Decimal(1) / Decimal(7)
+Decimal("0.142857143")
+>>> Decimal(42) / Decimal(0)
+Decimal("Infinity")
+
+>>> setcontext(BasicContext)
+>>> Decimal(42) / Decimal(0)
+Traceback (most recent call last):
+ File "<pyshell#143>", line 1, in -toplevel-
+ Decimal(42) / Decimal(0)
+DivisionByZero: x / 0
+\end{verbatim}
+
+
+Contexts also have signal flags for monitoring exceptional conditions
+encountered during computations. The flags remain set until explicitly
+cleared, so it is best to clear the flags before each set of monitored
+computations by using the \method{clear_flags()} method.
+
+\begin{verbatim}
+>>> setcontext(ExtendedContext)
+>>> getcontext().clear_flags()
+>>> Decimal(355) / Decimal(113)
+Decimal("3.14159292")
+>>> getcontext()
+Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+ capitals=1, flags=[Inexact, Rounded], traps=[])
+\end{verbatim}
+
+The \var{flags} entry shows that the rational approximation to \constant{Pi}
+was rounded (digits beyond the context precision were thrown away) and that
+the result is inexact (some of the discarded digits were non-zero).
+
+Individual traps are set using the dictionary in the \member{traps}
+field of a context:
+
+\begin{verbatim}
+>>> Decimal(1) / Decimal(0)
+Decimal("Infinity")
+>>> getcontext().traps[DivisionByZero] = 1
+>>> Decimal(1) / Decimal(0)
+Traceback (most recent call last):
+ File "<pyshell#112>", line 1, in -toplevel-
+ Decimal(1) / Decimal(0)
+DivisionByZero: x / 0
+\end{verbatim}
+
+Most programs adjust the current context only once, at the beginning of the
+program. And, in many applications, data is converted to \class{Decimal} with
+a single cast inside a loop. With context set and decimals created, the bulk
+of the program manipulates the data no differently than with other Python
+numeric types.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Decimal objects \label{decimal-decimal}}
+
+\begin{classdesc}{Decimal}{\optional{value \optional{, context}}}
+ Constructs a new \class{Decimal} object based from \var{value}.
+
+ \var{value} can be an integer, string, tuple, or another \class{Decimal}
+ object. If no \var{value} is given, returns \code{Decimal("0")}. If
+ \var{value} is a string, it should conform to the decimal numeric string
+ syntax:
+
+ \begin{verbatim}
+ sign ::= '+' | '-'
+ digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+ indicator ::= 'e' | 'E'
+ digits ::= digit [digit]...
+ decimal-part ::= digits '.' [digits] | ['.'] digits
+ exponent-part ::= indicator [sign] digits
+%[- MARK -] BEGIN PART 004 of 13
+ infinity ::= 'Infinity' | 'Inf'
+ nan ::= 'NaN' [digits] | 'sNaN' [digits]
+ numeric-value ::= decimal-part [exponent-part] | infinity
+ numeric-string ::= [sign] numeric-value | [sign] nan
+ \end{verbatim}
+
+ If \var{value} is a \class{tuple}, it should have three components,
+ a sign (\constant{0} for positive or \constant{1} for negative),
+ a \class{tuple} of digits, and an integer exponent. For example,
+ \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}.
+
+ The \var{context} precision does not affect how many digits are stored.
+ That is determined exclusively by the number of digits in \var{value}. For
+ example, \samp{Decimal("3.00000")} records all five zeroes even if the
+ context precision is only three.
+
+ The purpose of the \var{context} argument is determining what to do if
+ \var{value} is a malformed string. If the context traps
+ \constant{InvalidOperation}, an exception is raised; otherwise, the
+ constructor returns a new Decimal with the value of \constant{NaN}.
+
+ Once constructed, \class{Decimal} objects are immutable.
+\end{classdesc}
+
+Decimal floating point objects share many properties with the other builtin
+numeric types such as \class{float} and \class{int}. All of the usual
+math operations and special methods apply. Likewise, decimal objects can
+be copied, pickled, printed, used as dictionary keys, used as set elements,
+compared, sorted, and coerced to another type (such as \class{float}
+or \class{long}).
+
+In addition to the standard numeric properties, decimal floating point objects
+also have a number of specialized methods:
+
+\begin{methoddesc}{adjusted}{}
+ Return the adjusted exponent after shifting out the coefficient's rightmost
+ digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()}
+ returns seven. Used for determining the position of the most significant
+ digit with respect to the decimal point.
+\end{methoddesc}
+
+\begin{methoddesc}{as_tuple}{}
+ Returns a tuple representation of the number:
+ \samp{(sign, digittuple, exponent)}.
+\end{methoddesc}
+
+\begin{methoddesc}{compare}{other\optional{, context}}
+ Compares like \method{__cmp__()} but returns a decimal instance:
+ \begin{verbatim}
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+ \end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{max}{other\optional{, context}}
+ Like \samp{max(self, other)} except that the context rounding rule
+ is applied before returning and that \constant{NaN} values are
+ either signalled or ignored (depending on the context and whether
+ they are signaling or quiet).
+\end{methoddesc}
+
+\begin{methoddesc}{min}{other\optional{, context}}
+ Like \samp{min(self, other)} except that the context rounding rule
+ is applied before returning and that \constant{NaN} values are
+ either signalled or ignored (depending on the context and whether
+ they are signaling or quiet).
+\end{methoddesc}
+
+\begin{methoddesc}{normalize}{\optional{context}}
+ Normalize the number by stripping the rightmost trailing zeroes and
+ converting any result equal to \constant{Decimal("0")} to
+ \constant{Decimal("0e0")}. Used for producing canonical values for members
+ of an equivalence class. For example, \code{Decimal("32.100")} and
+ \code{Decimal("0.321000e+2")} both normalize to the equivalent value
+ \code{Decimal("32.1")}.
+\end{methoddesc}
+
+\begin{methoddesc}{quantize}
+ {exp \optional{, rounding\optional{, context\optional{, watchexp}}}}
+ Quantize makes the exponent the same as \var{exp}. Searches for a
+ rounding method in \var{rounding}, then in \var{context}, and then
+ in the current context.
+
+ If \var{watchexp} is set (default), then an error is returned whenever
+ the resulting exponent is greater than \member{Emax} or less than
+ \member{Etiny}.
+\end{methoddesc}
+
+\begin{methoddesc}{remainder_near}{other\optional{, context}}
+ Computes the modulo as either a positive or negative value depending
+ on which is closest to zero. For instance,
+ \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
+ which is closer to zero than \code{Decimal("4")}.
+
+ If both are equally close, the one chosen will have the same sign
+ as \var{self}.
+\end{methoddesc}
+
+%[- MARK -] BEGIN PART 005 of 13
+\begin{methoddesc}{same_quantum}{other\optional{, context}}
+ Test whether self and other have the same exponent or whether both
+ are \constant{NaN}.
+\end{methoddesc}
+
+\begin{methoddesc}{sqrt}{\optional{context}}
+ Return the square root to full precision.
+\end{methoddesc}
+
+\begin{methoddesc}{to_eng_string}{\optional{context}}
+ Convert to an engineering-type string.
+
+ Engineering notation has an exponent which is a multiple of 3, so there
+ are up to 3 digits left of the decimal place. For example, converts
+ \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
+\end{methoddesc}
+
+\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}}
+ Rounds to the nearest integer without signaling \constant{Inexact}
+ or \constant{Rounded}. If given, applies \var{rounding}; otherwise,
+ uses the rounding method in either the supplied \var{context} or the
+ current context.
+\end{methoddesc}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Context objects \label{decimal-decimal}}
+
+Contexts are environments for arithmetic operations. They govern precision,
+set rules for rounding, determine which signals are treated as exceptions, and
+limit the range for exponents.
+
+Each thread has its own current context which is accessed or changed using
+the \function{getcontext()} and \function{setcontext()} functions:
+
+\begin{funcdesc}{getcontext}{}
+ Return the current context for the active thread.
+\end{funcdesc}
+
+\begin{funcdesc}{setcontext}{c}
+ Set the current context for the active thread to \var{c}.
+\end{funcdesc}
+
+New contexts can formed using the \class{Context} constructor described below.
+In addition, the module provides three pre-made contexts:
+
+
+\begin{classdesc*}{BasicContext}
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ \constant{ROUND_HALF_UP}. All flags are cleared. All traps are enabled
+ (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and
+ \constant{Subnormal}.
+
+ Because many of the traps are enabled, this context is useful for debugging.
+\end{classdesc*}
+
+\begin{classdesc*}{ExtendedContext}
+ This is a standard context defined by the General Decimal Arithmetic
+ Specification. Precision is set to nine. Rounding is set to
+ \constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled
+ (so that exceptions are not raised during computations).
+
+ Because the trapped are disabled, this context is useful for applications
+ that prefer to have result value of \constant{NaN} or \constant{Infinity}
+ instead of raising exceptions. This allows an application to complete a
+ run in the presence of conditions that would otherwise halt the program.
+\end{classdesc*}
+
+\begin{classdesc*}{DefaultContext}
+ This context is used by the \class{Context} constructor as a prototype for
+ new contexts. Changing a field (such a precision) has the effect of
+ changing the default for new contexts creating by the \class{Context}
+ constructor.
+
+ This context is most useful in multi-threaded environments. Changing one of
+ the fields before threads are started has the effect of setting system-wide
+ defaults. Changing the fields after threads have started is not recommended
+ as it would require thread synchronization to prevent race conditions.
+
+ In single threaded environments, it is preferable to not use this context
+ at all. Instead, simply create contexts explicitly as described below.
+
+ The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled
+ traps for Overflow, InvalidOperation, and DivisionByZero.
+\end{classdesc*}
+
+
+In addition to the three supplied contexts, new contexts can be created
+with the \class{Context} constructor.
+
+\begin{classdesc}{Context}{prec=None, rounding=None, traps=None,
+ flags=None, Emin=None, Emax=None, capitals=1}
+ Creates a new context. If a field is not specified or is \constant{None},
+ the default values are copied from the \constant{DefaultContext}. If the
+ \var{flags} field is not specified or is \constant{None}, all flags are
+ cleared.
+
+ The \var{prec} field is a positive integer that sets the precision for
+%[- MARK -] BEGIN PART 006 of 13
+ arithmetic operations in the context.
+
+ The \var{rounding} option is one of:
+ \begin{itemize}
+ \item \constant{ROUND_CEILING} (towards \constant{Infinity}),
+ \item \constant{ROUND_DOWN} (towards zero),
+ \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}),
+ \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero),
+ \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer),
+ \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or
+ \item \constant{ROUND_UP} (away from zero).
+ \end{itemize}
+
+ The \var{traps} and \var{flags} fields list any signals to be set.
+ Generally, new contexts should only set traps and leave the flags clear.
+
+ The \var{Emin} and \var{Emax} fields are integers specifying the outer
+ limits allowable for exponents.
+
+ The \var{capitals} field is either \constant{0} or \constant{1} (the
+ default). If set to \constant{1}, exponents are printed with a capital
+ \constant{E}; otherwise, a lowercase \constant{e} is used:
+ \constant{Decimal('6.02e+23')}.
+\end{classdesc}
+
+The \class{Context} class defines several general purpose methods as well as a
+large number of methods for doing arithmetic directly in a given context.
+
+\begin{methoddesc}{clear_flags}{}
+ Resets all of the flags to \constant{0}.
+\end{methoddesc}
+
+\begin{methoddesc}{copy}{}
+ Return a duplicate of the context.
+\end{methoddesc}
+
+\begin{methoddesc}{create_decimal}{num}
+ Creates a new Decimal instance from \var{num} but using \var{self} as
+ context. Unlike the \class{Decimal} constructor, the context precision,
+ rounding method, flags, and traps are applied to the conversion.
+
+ This is useful because constants are often given to a greater precision than
+ is needed by the application. Another benefit is that rounding immediately
+ eliminates unintended effects from digits beyond the current precision.
+ In the following example, using unrounded inputs means that adding zero
+ to a sum can change the result:
+
+ \begin{verbatim}
+ >>> getcontext().prec = 3
+ >>> Decimal("3.4445") + Decimal("1.0023")
+ Decimal("4.45")
+ >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
+ Decimal("4.44")
+ \end{verbatim}
+
+\end{methoddesc}
+
+\begin{methoddesc}{Etiny}{}
+ Returns a value equal to \samp{Emin - prec + 1} which is the minimum
+ exponent value for subnormal results. When underflow occurs, the
+ exponent is set to \constant{Etiny}.
+\end{methoddesc}
+
+\begin{methoddesc}{Etop}{}
+ Returns a value equal to \samp{Emax - prec + 1}.
+\end{methoddesc}
+
+
+The usual approach to working with decimals is to create \class{Decimal}
+instances and then apply arithmetic operations which take place within the
+current context for the active thread. An alternate approach is to use
+context methods for calculating within a specific context. The methods are
+similar to those for the \class{Decimal} class and are only briefly recounted
+here.
+
+\begin{methoddesc}{abs}{x}
+ Returns the absolute value of \var{x}.
+\end{methoddesc}
+
+\begin{methoddesc}{add}{x, y}
+ Return the sum of \var{x} and \var{y}.
+\end{methoddesc}
+
+\begin{methoddesc}{compare}{x, y}
+ Compares values numerically.
+
+ Like \method{__cmp__()} but returns a decimal instance:
+ \begin{verbatim}
+ a or b is a NaN ==> Decimal("NaN")
+ a < b ==> Decimal("-1")
+ a == b ==> Decimal("0")
+ a > b ==> Decimal("1")
+ \end{verbatim}
+\end{methoddesc}
+
+\begin{methoddesc}{divide}{x, y}
+ Return \var{x} divided by \var{y}.
+\end{methoddesc}
+
+\begin{methoddesc}{divmod}{x, y}
+%[- MARK -] BEGIN PART 007 of 13
+ Divides two numbers and returns the integer part of the result.
+\end{methoddesc}
+
+\begin{methoddesc}{max}{x, y}
+ Compare two values numerically and return the maximum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+\end{methoddesc}
+
+\begin{methoddesc}{min}{x, y}
+ Compare two values numerically and return the minimum.
+
+ If they are numerically equal then the left-hand operand is chosen as the
+ result.
+\end{methoddesc}
+
+\begin{methoddesc}{minus}{x}
+ Minus corresponds to the unary prefix minus operator in Python.
+\end{methoddesc}
+
+\begin{methoddesc}{multiply}{x, y}
+ Return the product of \var{x} and \var{y}.
+\end{methoddesc}
+
+\begin{methoddesc}{normalize}{x}
+ Normalize reduces an operand to its simplest form.
+
+ Essentially a \method{plus} operation with all trailing zeros removed from
+ the result.
+\end{methoddesc}
+
+\begin{methoddesc}{plus}{x}
+ Plus corresponds to the unary prefix plus operator in Python. This
+ operation applies the context precision and rounding, so it is
+ \emph{not} an identity operation.
+\end{methoddesc}
+
+\begin{methoddesc}{power}{x, y\optional{, modulo}}
+ Return \samp{x ** y} to the \var{modulo} if given.
+
+ The right-hand operand must be a whole number whose integer part (after any
+ exponent has been applied) has no more than 9 digits and whose fractional
+ part (if any) is all zeros before any rounding. The operand may be positive,
+ negative, or zero; if negative, the absolute value of the power is used, and
+ the left-hand operand is inverted (divided into 1) before use.
+
+ If the increased precision needed for the intermediate calculations exceeds
+ the capabilities of the implementation then an \constant{InvalidOperation}
+ condition is signaled.
+
+ If, when raising to a negative power, an underflow occurs during the
+ division into 1, the operation is not halted at that point but continues.
+\end{methoddesc}
+
+\begin{methoddesc}{quantize}{x, y}
+ Returns a value equal to \var{x} after rounding and having the exponent of
+ \var{y}.
+
+ Unlike other operations, if the length of the coefficient after the quantize
+ operation would be greater than precision, then an
+ \constant{InvalidOperation} is signaled. This guarantees that, unless there
+ is an error condition, the quantized exponent is always equal to that of the
+ right-hand operand.
+
+ Also unlike other operations, quantize never signals Underflow, even
+ if the result is subnormal and inexact.
+\end{methoddesc}
+
+\begin{methoddesc}{remainder}{x, y}
+ Returns the remainder from integer division.
+
+ The sign of the result, if non-zero, is the same as that of the original
+ dividend.
+\end{methoddesc}
+
+\begin{methoddesc}{remainder_near}{x, y}
+ Computed the modulo as either a positive or negative value depending
+ on which is closest to zero. For instance,
+ \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
+ which is closer to zero than \code{Decimal("4")}.
+
+ If both are equally close, the one chosen will have the same sign
+ as \var{self}.
+\end{methoddesc}
+
+\begin{methoddesc}{same_quantum}{x, y}
+ Test whether \var{x} and \var{y} have the same exponent or whether both are
+ \constant{NaN}.
+\end{methoddesc}
+
+\begin{methoddesc}{sqrt}{}
+ Return the square root to full precision.
+\end{methoddesc}
+
+\begin{methoddesc}{subtract}{x, y}
+ Return the difference between \var{x} and \var{y}.
+\end{methoddesc}
+
+\begin{methoddesc}{to_eng_string}{}
+%[- MARK -] BEGIN PART 008 of 13
+ Convert to engineering-type string.
+
+ Engineering notation has an exponent which is a multiple of 3, so there
+ are up to 3 digits left of the decimal place. For example, converts
+ \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
+\end{methoddesc}
+
+\begin{methoddesc}{to_integral}{x}
+ Rounds to the nearest integer without signaling \constant{Inexact}
+ or \constant{Rounded}.
+\end{methoddesc}
+
+\begin{methoddesc}{to_sci_string}{}
+ Converts a number to a string using scientific notation.
+\end{methoddesc}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Signals \label{decimal-signals}}
+
+Signals represent conditions that arise during computation.
+Each corresponds to one context flag and one context trap enabler.
+
+The context flag is incremented whenever the condition is encountered.
+After the computation, flags may be checked for informational
+purposes (for instance, to determine whether a computation was exact).
+After checking the flags, be sure to clear all flags before starting
+the next computation.
+
+If the context's trap enabler is set for the signal, then the condition
+causes a Python exception to be raised. For example, if the
+\class{DivisionByZero} trap is set, then a \exception{DivisionByZero}
+exception is raised upon encountering the condition.
+
+
+\begin{classdesc*}{Clamped}
+ Altered an exponent to fit representation constraints.
+
+ Typically, clamping occurs when an exponent falls outside the context's
+ \member{Emin} and \member{Emax} limits. If possible, the exponent is
+ reduced to fit by adding zeroes to the coefficient.
+\end{classdesc*}
+
+\begin{classdesc*}{DecimalException}
+ Base class for other signals and is a subclass of
+ \exception{ArithmeticError}.
+\end{classdesc*}
+
+\begin{classdesc*}{DivisionByZero}
+ Signals the division of a non-infinite number by zero.
+
+ Can occur with division, modulo division, or when raising a number to a
+ negative power. If this signal is not trapped, returns
+ \constant{Infinity} or \constant{-Infinity} with the sign determined by
+ the inputs to the calculation.
+\end{classdesc*}
+
+\begin{classdesc*}{Inexact}
+ Indicates that rounding occurred and the result is not exact.
+
+ Signals when non-zero digits were discarded during rounding. The rounded
+ result is returned. The signal flag or trap is used to detect when
+ results are inexact.
+\end{classdesc*}
+
+\begin{classdesc*}{InvalidOperation}
+ An invalid operation was performed.
+
+ Indicates that an operation was requested that does not make sense.
+ If not trapped, returns \constant{NaN}. Possible causes include:
+
+ \begin{verbatim}
+ Infinity - Infinity
+ 0 * Infinity
+ Infinity / Infinity
+ x % 0
+ Infinity % x
+ x._rescale( non-integer )
+ sqrt(-x) and x > 0
+ 0 ** 0
+ x ** (non-integer)
+ x ** Infinity
+ \end{verbatim}
+\end{classdesc*}
+
+\begin{classdesc*}{Overflow}
+ Numerical overflow.
+
+ Indicates the exponent is larger than \member{Emax} after rounding has
+ occurred. If not trapped, the result depends on the rounding mode, either
+ pulling inward to the largest representable finite number or rounding
+ outward to \constant{Infinity}. In either case, \class{Inexact} and
+ \class{Rounded} are also signaled.
+\end{classdesc*}
+
+\begin{classdesc*}{Rounded}
+ Rounding occurred though possibly no information was lost.
+
+ Signaled whenever rounding discards digits; even if those digits are
+%[- MARK -] BEGIN PART 009 of 13
+ zero (such as rounding \constant{5.00} to \constant{5.0}). If not
+ trapped, returns the result unchanged. This signal is used to detect
+ loss of significant digits.
+\end{classdesc*}
+
+\begin{classdesc*}{Subnormal}
+ Exponent was lower than \member{Emin} prior to rounding.
+
+ Occurs when an operation result is subnormal (the exponent is too small).
+ If not trapped, returns the result unchanged.
+\end{classdesc*}
+
+\begin{classdesc*}{Underflow}
+ Numerical underflow with result rounded to zero.
+
+ Occurs when a subnormal result is pushed to zero by rounding.
+ \class{Inexact} and \class{Subnormal} are also signaled.
+\end{classdesc*}
+
+The following table summarizes the hierarchy of signals:
+
+\begin{verbatim}
+ exceptions.ArithmeticError(exceptions.StandardError)
+ DecimalException
+ Clamped
+ DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
+ Inexact
+ Overflow(Inexact, Rounded)
+ Underflow(Inexact, Rounded, Subnormal)
+ InvalidOperation
+ Rounded
+ Subnormal
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Floating Point Notes \label{decimal-notes}}
+
+\subsubsection{Mitigating round-off error with increased precision}
+
+The use of decimal floating point eliminates decimal representation error
+(making it possible to represent \constant{0.1} exactly); however, some
+operations can still incur round-off error when non-zero digits exceed the
+fixed precision.
+
+The effects of round-off error can be amplified by the addition or subtraction
+of nearly offsetting quantities resulting in loss of significance. Knuth
+provides two instructive examples where rounded floating point arithmetic with
+insufficient precision causes the breakdown of the associative and
+distributive properties of addition:
+
+\begin{verbatim}
+# Examples from Seminumerical Algorithms, Section 4.2.2.
+>>> from decimal import *
+>>> getcontext().prec = 8
+
+>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+>>> (u + v) + w
+Decimal("9.5111111")
+>>> u + (v + w)
+Decimal("10")
+
+>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+>>> (u*v) + (u*w)
+Decimal("0.01")
+>>> u * (v+w)
+Decimal("0.0060000")
+\end{verbatim}
+
+The \module{decimal} module makes it possible to restore the identities
+by expanding the precision sufficiently to avoid loss of significance:
+
+\begin{verbatim}
+>>> getcontext().prec = 20
+>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+>>> (u + v) + w
+Decimal("9.51111111")
+>>> u + (v + w)
+Decimal("9.51111111")
+>>>
+>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+>>> (u*v) + (u*w)
+Decimal("0.0060000")
+>>> u * (v+w)
+Decimal("0.0060000")
+\end{verbatim}
+
+\subsubsection{Special values}
+
+The number system for the \module{decimal} module provides special
+values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity},
+\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}.
+
+Infinities can be constructed directly with: \code{Decimal('Infinity')}. Also,
+they can arise from dividing by zero when the \exception{DivisionByZero}
+signal is not trapped. Likewise, when the \exception{Overflow} signal is not
+trapped, infinity can result from rounding beyond the limits of the largest
+representable number.
+
+The infinities are signed (affine) and can be used in arithmetic operations
+%[- MARK -] BEGIN PART 010 of 13
+where they get treated as very large, indeterminate numbers. For instance,
+adding a constant to infinity gives another infinite result.
+
+Some operations are indeterminate and return \constant{NaN}, or if the
+\exception{InvalidOperation} signal is trapped, raise an exception. For
+example, \code{0/0} returns \constant{NaN} which means ``not a number''. This
+variety of \constant{NaN} is quiet and, once created, will flow through other
+computations always resulting in another \constant{NaN}. This behavior can be
+useful for a series of computations that occasionally have missing inputs ---
+it allows the calculation to proceed while flagging specific results as
+invalid.
+
+A variant is \constant{sNaN} which signals rather than remaining quiet
+after every operation. This is a useful return value when an invalid
+result needs to interrupt a calculation for special handling.
+
+The signed zeros can result from calculations that underflow.
+They keep the sign that would have resulted if the calculation had
+been carried out to greater precision. Since their magnitude is
+zero, both positive and negative zeros are treated as equal and their
+sign is informational.
+
+In addition to the two signed zeros which are distinct yet equal,
+there are various representations of zero with differing precisions
+yet equivalent in value. This takes a bit of getting used to. For
+an eye accustomed to normalized floating point representations, it
+is not immediately obvious that the following calculation returns
+a value equal to zero:
+
+\begin{verbatim}
+>>> 1 / Decimal('Infinity')
+Decimal("0E-1000000026")
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Working with threads \label{decimal-threads}}
+
+The \function{getcontext()} function accesses a different \class{Context}
+object for each thread. Having separate thread contexts means that threads
+may make changes (such as \code{getcontext.prec=10}) without interfering with
+other threads.
+
+Likewise, the \function{setcontext()} function automatically assigns its target
+to the current thread.
+
+If \function{setcontext()} has not been called before \function{getcontext()},
+then \function{getcontext()} will automatically create a new context for use
+in the current thread.
+
+The new context is copied from a prototype context called
+\var{DefaultContext}. To control the defaults so that each thread will use the
+same values throughout the application, directly modify the
+\var{DefaultContext} object. This should be done \emph{before} any threads are
+started so that there won't be a race condition between threads calling
+\function{getcontext()}. For example:
+
+\begin{verbatim}
+# Set applicationwide defaults for all threads about to be launched
+DefaultContext.prec = 12
+DefaultContext.rounding = ROUND_DOWN
+DefaultContext.traps = ExtendedContext.traps.copy()
+DefaultContext.traps[InvalidOperation] = 1
+setcontext(DefaultContext)
+
+# Afterwards, the threads can be started
+t1.start()
+t2.start()
+t3.start()
+ . . .
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Recipes \label{decimal-recipes}}
+
+Here are a few recipes that serve as utility functions and that demonstrate
+ways to work with the \class{Decimal} class:
+
+\begin{verbatim}
+def moneyfmt(value, places=2, curr='', sep=',', dp='.',
+ pos='', neg='-', trailneg=''):
+ """Convert Decimal to a money formatted string.
+
+ places: required number of places after the decimal point
+ curr: optional currency symbol before the sign (may be blank)
+ sep: optional grouping separator (comma, period, space, or blank)
+ dp: decimal point indicator (comma or period)
+ only specify as blank when places is zero
+ pos: optional sign for positive numbers: '+', space or blank
+ neg: optional sign for negative numbers: '-', '(', space or blank
+ trailneg:optional trailing minus indicator: '-', ')', space or blank
+
+ >>> d = Decimal('-1234567.8901')
+ >>> moneyfmt(d, curr='$')
+ '-$1,234,567.89'
+ >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
+ '1.234.568-'
+ >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
+ '($1,234,567.89)'
+%[- MARK -] BEGIN PART 011 of 13
+ >>> moneyfmt(Decimal(123456789), sep=' ')
+ '123 456 789.00'
+ >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
+ '<.02>'
+
+ """
+ q = Decimal((0, (1,), -places)) # 2 places --> '0.01'
+ sign, digits, exp = value.quantize(q).as_tuple()
+ assert exp == -places
+ result = []
+ digits = map(str, digits)
+ build, next = result.append, digits.pop
+ if sign:
+ build(trailneg)
+ for i in range(places):
+ if digits:
+ build(next())
+ else:
+ build('0')
+ build(dp)
+ i = 0
+ while digits:
+ build(next())
+ i += 1
+ if i == 3 and digits:
+ i = 0
+ build(sep)
+ build(curr)
+ if sign:
+ build(neg)
+ else:
+ build(pos)
+ result.reverse()
+ return ''.join(result)
+
+def pi():
+ """Compute Pi to the current precision.
+
+ >>> print pi()
+ 3.141592653589793238462643383
+
+ """
+ getcontext().prec += 2 # extra digits for intermediate steps
+ three = Decimal(3) # substitute "three=3.0" for regular floats
+ lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
+ while s != lasts:
+ lasts = s
+ n, na = n+na, na+8
+ d, da = d+da, da+32
+ t = (t * n) / d
+ s += t
+ getcontext().prec -= 2
+ return +s # unary plus applies the new precision
+
+def exp(x):
+ """Return e raised to the power of x. Result type matches input type.
+
+ >>> print exp(Decimal(1))
+ 2.718281828459045235360287471
+ >>> print exp(Decimal(2))
+ 7.389056098930650227230427461
+ >>> print exp(2.0)
+ 7.38905609893
+ >>> print exp(2+0j)
+ (7.38905609893+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num = 0, 0, 1, 1, 1
+ while s != lasts:
+ lasts = s
+ i += 1
+ fact *= i
+ num *= x
+ s += num / fact
+ getcontext().prec -= 2
+ return +s
+
+def cos(x):
+ """Return the cosine of x as measured in radians.
+
+ >>> print cos(Decimal('0.5'))
+ 0.8775825618903727161162815826
+ >>> print cos(0.5)
+ 0.87758256189
+ >>> print cos(0.5+0j)
+ (0.87758256189+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
+ while s != lasts:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ getcontext().prec -= 2
+ return +s
+%[- MARK -] BEGIN PART 012 of 13
+
+def sin(x):
+ """Return the sine of x as measured in radians.
+
+ >>> print sin(Decimal('0.5'))
+ 0.4794255386042030002732879352
+ >>> print sin(0.5)
+ 0.479425538604
+ >>> print sin(0.5+0j)
+ (0.479425538604+0j)
+
+ """
+ getcontext().prec += 2
+ i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
+ while s != lasts:
+ lasts = s
+ i += 2
+ fact *= i * (i-1)
+ num *= x * x
+ sign *= -1
+ s += num / fact * sign
+ getcontext().prec -= 2
+ return +s
+
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Decimal FAQ \label{decimal-faq}}
+
+Q. It is cumbersome to type \code{decimal.Decimal('1234.5')}. Is there a way
+to minimize typing when using the interactive interpreter?
+
+A. Some users abbreviate the constructor to just a single letter:
+
+\begin{verbatim}
+>>> D = decimal.Decimal
+>>> D('1.23') + D('3.45')
+Decimal("4.68")
+\end{verbatim}
+
+
+Q. In a fixed-point application with two decimal places, some inputs
+have many places and need to be rounded. Others are not supposed to have
+excess digits and need to be validated. What methods should be used?
+
+A. The \method{quantize()} method rounds to a fixed number of decimal places.
+If the \constant{Inexact} trap is set, it is also useful for validation:
+
+\begin{verbatim}
+>>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
+
+>>> # Round to two places
+>>> Decimal("3.214").quantize(TWOPLACES)
+Decimal("3.21")
+
+>>> # Validate that a number does not exceed two places
+>>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+Decimal("3.21")
+
+>>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+Traceback (most recent call last):
+ ...
+Inexact: Changed in rounding
+\end{verbatim}
+
+
+Q. Once I have valid two place inputs, how do I maintain that invariant
+throughout an application?
+
+A. Some operations like addition and subtraction automatically preserve fixed
+point. Others, like multiplication and division, change the number of decimal
+places and need to be followed-up with a \method{quantize()} step.
+
+
+Q. There are many ways to express the same value. The numbers
+\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.02E+4} all
+have the same value at various precisions. Is there a way to transform them to
+a single recognizable canonical value?
+
+A. The \method{normalize()} method maps all equivalent values to a single
+representative:
+
+\begin{verbatim}
+>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
+>>> [v.normalize() for v in values]
+[Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
+\end{verbatim}
+
+
+Q. Some decimal values always print with exponential notation. Is there
+a way to get a non-exponential representation?
+
+A. For some values, exponential notation is the only way to express
+the number of significant places in the coefficient. For example,
+expressing \constant{5.0E+3} as \constant{5000} keeps the value
+constant but cannot show the original's two-place significance.
+
+
+%[- MARK -] BEGIN PART 013 of 13
+Q. Is there a way to convert a regular float to a \class{Decimal}?
+
+A. Yes, all binary floating point numbers can be exactly expressed as a
+Decimal. An exact conversion may take more precision than intuition would
+suggest, so trapping \constant{Inexact} will signal a need for more precision:
+
+\begin{verbatim}
+def floatToDecimal(f):
+ "Convert a floating point number to a Decimal with no loss of information"
+ # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
+ # exponent. Double the mantissa until it is an integer. Use the integer
+ # mantissa and exponent to compute an equivalent Decimal. If this cannot
+ # be done exactly, then retry with more precision.
+
+ mantissa, exponent = math.frexp(f)
+ while mantissa != int(mantissa):
+ mantissa *= 2.0
+ exponent -= 1
+ mantissa = int(mantissa)
+
+ oldcontext = getcontext()
+ setcontext(Context(traps=[Inexact]))
+ try:
+ while True:
+ try:
+ return mantissa * Decimal(2) ** exponent
+ except Inexact:
+ getcontext().prec += 1
+ finally:
+ setcontext(oldcontext)
+\end{verbatim}
+
+
+Q. Why isn't the \function{floatToDecimal()} routine included in the module?
+
+A. There is some question about whether it is advisable to mix binary and
+decimal floating point. Also, its use requires some care to avoid the
+representation issues associated with binary floating point:
+
+\begin{verbatim}
+>>> floatToDecimal(1.1)
+Decimal("1.100000000000000088817841970012523233890533447265625")
+\end{verbatim}
+
+
+Q. Within a complex calculation, how can I make sure that I haven't gotten a
+spurious result because of insufficient precision or rounding anomalies.
+
+A. The decimal module makes it easy to test results. A best practice is to
+re-run calculations using greater precision and with various rounding modes.
+Widely differing results indicate insufficient precision, rounding mode
+issues, ill-conditioned inputs, or a numerically unstable algorithm.
+
+
+Q. I noticed that context precision is applied to the results of operations
+but not to the inputs. Is there anything to watch out for when mixing
+values of different precisions?
+
+A. Yes. The principle is that all values are considered to be exact and so
+is the arithmetic on those values. Only the results are rounded. The
+advantage for inputs is that ``what you type is what you get''. A
+disadvantage is that the results can look odd if you forget that the inputs
+haven't been rounded:
+
+\begin{verbatim}
+>>> getcontext().prec = 3
+>>> Decimal('3.104') + D('2.104')
+Decimal("5.21")
+>>> Decimal('3.104') + D('0.000') + D('2.104')
+Decimal("5.20")
+\end{verbatim}
+
+The solution is either to increase precision or to force rounding of inputs
+using the unary plus operation:
+
+\begin{verbatim}
+>>> getcontext().prec = 3
+>>> +Decimal('1.23456789') # unary plus triggers rounding
+Decimal("1.23")
+\end{verbatim}
+
+Alternatively, inputs can be rounded upon creation using the
+\method{Context.create_decimal()} method:
+
+\begin{verbatim}
+>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
+Decimal("1.2345")
+\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libdis.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libdis.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libdis.tex Fri Jun 2 12:52:55 2006
@@ -126,6 +126,23 @@
\begin{opcodedesc}{STOP_CODE}{}
Indica la fine del codice al compilatore, non viene utilizzato
dall'interprete.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 120
+%[- MARK -]
+%[- MARK -] \begin{opcodedesc}{STOP_CODE}{}
+%[- MARK -] Indicates end-of-code to the compiler, not used by the interpreter.
+%[- MARK -] \end{opcodedesc}
+%[- MARK -]
+%[- MARK -] +\begin{opcodedesc}{NOP}{}
+%[- MARK -] +Do nothing code. Used as a placeholder by the bytecode optimizer.
+%[- MARK -] +\end{opcodedesc}
+%[- MARK -] +
+%[- MARK -] \begin{opcodedesc}{POP_TOP}{}
+%[- MARK -] Removes the top-of-stack (TOS) item.
+%[- MARK -] \end{opcodedesc}
+%[- MARK -]
+%[- MARK -] \begin{opcodedesc}{ROT_TWO}{}
+%[- MARK -] END DIFF
\end{opcodedesc}
\begin{opcodedesc}{POP_TOP}{}
@@ -402,6 +419,23 @@
Continua un ciclo a causa di un'istruzione \keyword{continue}.
\var{target} è l'indirizzo in cui saltare(il quale dovrebbe essere una
istruzione \code{FOR_ITER}).
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 390
+%[- MARK -] Continues a loop due to a \keyword{continue} statement. \var{target}
+%[- MARK -] is the address to jump to (which should be a \code{FOR_ITER}
+%[- MARK -] instruction).
+%[- MARK -] \end{opcodedesc}
+%[- MARK -]
+%[- MARK -] +\begin{opcodedesc}{LIST_APPEND}{}
+%[- MARK -] +Calls \code{list.append(TOS1, TOS)}. Used to implement list comprehensions.
+%[- MARK -] +\end{opcodedesc}
+%[- MARK -] +
+%[- MARK -] \begin{opcodedesc}{LOAD_LOCALS}{}
+%[- MARK -] Pushes a reference to the locals of the current scope on the stack.
+%[- MARK -] This is used in the code for a class definition: After the class body
+%[- MARK -] is evaluated, the locals are passed to the class definition.
+%[- MARK -] \end{opcodedesc}
+%[- MARK -] END DIFF
\end{opcodedesc}
\begin{opcodedesc}{LOAD_LOCALS}{}
Modified: python/python/Doc/branches/2.4.3/lib/libdl.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libdl.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libdl.tex Fri Jun 2 12:52:55 2006
@@ -8,6 +8,23 @@
Il modulo \module{dl} definisce un'interfaccia per la funzione
\cfunction{dlopen()} che è l'interfaccia più comune sulle piattaforme
\UNIX{} per gestire dinamicamente delle librerie collegate. Permette al
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 8
+%[- MARK -] The \module{dl} module defines an interface to the
+%[- MARK -] \cfunction{dlopen()} function, which is the most common interface on
+%[- MARK -] \UNIX{} platforms for handling dynamically linked libraries. It allows
+%[- MARK -] the program to call arbitrary functions in such a library.
+%[- MARK -]
+%[- MARK -] +\warning{The \module{dl} module bypasses the Python type system and
+%[- MARK -] +error handling. If used incorrectly it may cause segmentation faults,
+%[- MARK -] +crashes or other incorrect behaviour.}
+%[- MARK -] +
+%[- MARK -] \note{This module will not work unless
+%[- MARK -] \code{sizeof(int) == sizeof(long) == sizeof(char *)}
+%[- MARK -] If this is not the case, \exception{SystemError} will be raised on
+%[- MARK -] import.}
+%[- MARK -]
+%[- MARK -] END DIFF
programma di richiamare funzioni arbitrarie in queste librerie.
\note{Questo modulo non funzionerà a meno che
@@ -22,6 +39,21 @@
indica che il binding (NdT: collegamento, legame) verrà posticipato
(\constant{RTLD_LAZY}) oppure verrà immediatamente eseguito
(\constant{RTLD_NOW}). Il valore predefinito è \constant{RTLD_LAZY}.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 21
+%[- MARK -] Open a shared object file, and return a handle. Mode
+%[- MARK -] signifies late binding (\constant{RTLD_LAZY}) or immediate binding
+%[- MARK -] (\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
+%[- MARK -] systems do not support \constant{RTLD_NOW}.
+%[- MARK -]
+%[- MARK -] -Return value is a \pytype{dlobject}.
+%[- MARK -] +Return value is a \class{dlobject}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] The \module{dl} module defines the following constants:
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{RTLD_LAZY}
+%[- MARK -] END DIFF
Notate che alcuni sistemi non supportano \constant{RTLD_NOW}.
Il valore restituito è un \pytype{dlobject}.
Modified: python/python/Doc/branches/2.4.3/lib/libdoctest.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libdoctest.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libdoctest.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,54 @@
+%[- MARK -] BEGIN DIFF 001 of 6
+%[- MARK -] @@ 1
+%[- MARK -] \section{\module{doctest} ---
+%[- MARK -] - Test docstrings represent reality}
+%[- MARK -] + Test interactive Python examples}
+%[- MARK -]
+%[- MARK -] \declaremodule{standard}{doctest}
+%[- MARK -] -\moduleauthor{Tim Peters}{tim_one a users.sourceforge.net}
+%[- MARK -] -\sectionauthor{Tim Peters}{tim_one a users.sourceforge.net}
+%[- MARK -] +\moduleauthor{Tim Peters}{tim a python.org}
+%[- MARK -] +\sectionauthor{Tim Peters}{tim a python.org}
+%[- MARK -] \sectionauthor{Moshe Zadka}{moshez a debian.org}
+%[- MARK -] +\sectionauthor{Edward Loper}{edloper a users.sourceforge.net}
+%[- MARK -]
+%[- MARK -] -\modulesynopsis{A framework for verifying examples in docstrings.}
+%[- MARK -] +\modulesynopsis{A framework for verifying interactive Python examples.}
+%[- MARK -]
+%[- MARK -] -The \module{doctest} module searches a module's docstrings for text that looks
+%[- MARK -] -like an interactive Python session, then executes all such sessions to verify
+%[- MARK -] -they still work exactly as shown. Here's a complete but small example:
+%[- MARK -] +The \refmodule{doctest} module searches for pieces of text that look like
+%[- MARK -] +interactive Python sessions, and then executes those sessions to
+%[- MARK -] +verify that they work exactly as shown. There are several common ways to
+%[- MARK -] +use doctest:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item To check that a module's docstrings are up-to-date by verifying
+%[- MARK -] + that all interactive examples still work as documented.
+%[- MARK -] +\item To perform regression testing by verifying that interactive
+%[- MARK -] + examples from a test file or a test object work as expected.
+%[- MARK -] +\item To write tutorial documentation for a package, liberally
+%[- MARK -] + illustrated with input-output examples. Depending on whether
+%[- MARK -] + the examples or the expository text are emphasized, this has
+%[- MARK -] + the flavor of "literate testing" or "executable documentation".
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Here's a complete but small example module:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] """
+%[- MARK -] -This is module example.
+%[- MARK -] +This is the "example" module.
+%[- MARK -]
+%[- MARK -] -Example supplies one function, factorial. For example,
+%[- MARK -] +The example module supplies one function, factorial(). For example,
+%[- MARK -]
+%[- MARK -] >>> factorial(5)
+%[- MARK -] 120
+%[- MARK -] """
+%[- MARK -]
+%[- MARK -] END DIFF
\section{\module{doctest} ---
Verifica che le docstring rappresentino la realtà.}
@@ -61,6 +112,412 @@
\end{verbatim}
% allow LaTeX to break here.
+%[- MARK -] BEGIN DIFF 002 of 6
+%[- MARK -] @@ 68
+%[- MARK -] if n+1 == n: # catch a value like 1e300
+%[- MARK -] raise OverflowError("n too large")
+%[- MARK -] result = 1
+%[- MARK -] factor = 2
+%[- MARK -] while factor <= n:
+%[- MARK -] - try:
+%[- MARK -] - result *= factor
+%[- MARK -] - except OverflowError:
+%[- MARK -] - result *= long(factor)
+%[- MARK -] + result *= factor
+%[- MARK -] factor += 1
+%[- MARK -] return result
+%[- MARK -]
+%[- MARK -] def _test():
+%[- MARK -] - import doctest, example
+%[- MARK -] - return doctest.testmod(example)
+%[- MARK -] + import doctest
+%[- MARK -] + doctest.testmod()
+%[- MARK -]
+%[- MARK -] if __name__ == "__main__":
+%[- MARK -] _test()
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] If you run \file{example.py} directly from the command line,
+%[- MARK -] -\module{doctest} works its magic:
+%[- MARK -] +\refmodule{doctest} works its magic:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] $ python example.py
+%[- MARK -] $
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] There's no output! That's normal, and it means all the examples
+%[- MARK -] -worked. Pass \programopt{-v} to the script, and \module{doctest}
+%[- MARK -] +worked. Pass \programopt{-v} to the script, and \refmodule{doctest}
+%[- MARK -] prints a detailed log of what it's trying, and prints a summary at the
+%[- MARK -] end:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] $ python example.py -v
+%[- MARK -] -Running example.__doc__
+%[- MARK -] -Trying: factorial(5)
+%[- MARK -] -Expecting: 120
+%[- MARK -] -ok
+%[- MARK -] -0 of 1 examples failed in example.__doc__
+%[- MARK -] -Running example.factorial.__doc__
+%[- MARK -] -Trying: [factorial(n) for n in range(6)]
+%[- MARK -] -Expecting: [1, 1, 2, 6, 24, 120]
+%[- MARK -] +Trying:
+%[- MARK -] + factorial(5)
+%[- MARK -] +Expecting:
+%[- MARK -] + 120
+%[- MARK -] ok
+%[- MARK -] -Trying: [factorial(long(n)) for n in range(6)]
+%[- MARK -] -Expecting: [1, 1, 2, 6, 24, 120]
+%[- MARK -] +Trying:
+%[- MARK -] + [factorial(n) for n in range(6)]
+%[- MARK -] +Expecting:
+%[- MARK -] + [1, 1, 2, 6, 24, 120]
+%[- MARK -] ok
+%[- MARK -] -Trying: factorial(30)
+%[- MARK -] -Expecting: 265252859812191058636308480000000L
+%[- MARK -] +Trying:
+%[- MARK -] + [factorial(long(n)) for n in range(6)]
+%[- MARK -] +Expecting:
+%[- MARK -] + [1, 1, 2, 6, 24, 120]
+%[- MARK -] ok
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] And so on, eventually ending with:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -Trying: factorial(1e100)
+%[- MARK -] +Trying:
+%[- MARK -] + factorial(1e100)
+%[- MARK -] Expecting:
+%[- MARK -] -Traceback (most recent call last):
+%[- MARK -] - ...
+%[- MARK -] -OverflowError: n too large
+%[- MARK -] + Traceback (most recent call last):
+%[- MARK -] + ...
+%[- MARK -] + OverflowError: n too large
+%[- MARK -] ok
+%[- MARK -] -0 of 8 examples failed in example.factorial.__doc__
+%[- MARK -] +1 items had no tests:
+%[- MARK -] + __main__._test
+%[- MARK -] 2 items passed all tests:
+%[- MARK -] - 1 tests in example
+%[- MARK -] - 8 tests in example.factorial
+%[- MARK -] -9 tests in 2 items.
+%[- MARK -] + 1 tests in __main__
+%[- MARK -] + 8 tests in __main__.factorial
+%[- MARK -] +9 tests in 3 items.
+%[- MARK -] 9 passed and 0 failed.
+%[- MARK -] Test passed.
+%[- MARK -] $
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] That's all you need to know to start making productive use of
+%[- MARK -] -\module{doctest}! Jump in. The docstrings in \file{doctest.py} contain
+%[- MARK -] -detailed information about all aspects of \module{doctest}, and we'll
+%[- MARK -] -just cover the more important points here.
+%[- MARK -] +\refmodule{doctest}! Jump in. The following sections provide full
+%[- MARK -] +details. Note that there are many examples of doctests in
+%[- MARK -] +the standard Python test suite and libraries. Especially useful examples
+%[- MARK -] +can be found in the standard test file \file{Lib/test/test_doctest.py}.
+%[- MARK -]
+%[- MARK -] -\subsection{Normal Usage}
+%[- MARK -] +\subsection{Simple Usage: Checking Examples in
+%[- MARK -] + Docstrings\label{doctest-simple-testmod}}
+%[- MARK -]
+%[- MARK -] -In normal use, end each module \module{M} with:
+%[- MARK -] +The simplest way to start using doctest (but not necessarily the way
+%[- MARK -] +you'll continue to do it) is to end each module \module{M} with:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] def _test():
+%[- MARK -] - import doctest, M # replace M with your module's name
+%[- MARK -] - return doctest.testmod(M) # ditto
+%[- MARK -] + import doctest
+%[- MARK -] + doctest.testmod()
+%[- MARK -]
+%[- MARK -] if __name__ == "__main__":
+%[- MARK -] _test()
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] -If you want to test the module as the main module, you don't need to
+%[- MARK -] -pass M to \function{testmod()}; in this case, it will test the current
+%[- MARK -] -module.
+%[- MARK -] +\refmodule{doctest} then examines docstrings in module \module{M}.
+%[- MARK -]
+%[- MARK -] -Then running the module as a script causes the examples in the docstrings
+%[- MARK -] +Running the module as a script causes the examples in the docstrings
+%[- MARK -] to get executed and verified:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] python M.py
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] This won't display anything unless an example fails, in which case the
+%[- MARK -] failing example(s) and the cause(s) of the failure(s) are printed to stdout,
+%[- MARK -] -and the final line of output is \code{'Test failed.'}.
+%[- MARK -] +and the final line of output is
+%[- MARK -] +\samp{***Test Failed*** \var{N} failures.}, where \var{N} is the
+%[- MARK -] +number of examples that failed.
+%[- MARK -]
+%[- MARK -] Run it with the \programopt{-v} switch instead:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] python M.py -v
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] and a detailed report of all examples tried is printed to standard
+%[- MARK -] output, along with assorted summaries at the end.
+%[- MARK -]
+%[- MARK -] -You can force verbose mode by passing \code{verbose=1} to
+%[- MARK -] +You can force verbose mode by passing \code{verbose=True} to
+%[- MARK -] \function{testmod()}, or
+%[- MARK -] -prohibit it by passing \code{verbose=0}. In either of those cases,
+%[- MARK -] -\code{sys.argv} is not examined by \function{testmod()}.
+%[- MARK -] -
+%[- MARK -] -In any case, \function{testmod()} returns a 2-tuple of ints \code{(\var{f},
+%[- MARK -] -\var{t})}, where \var{f} is the number of docstring examples that
+%[- MARK -] -failed and \var{t} is the total number of docstring examples
+%[- MARK -] -attempted.
+%[- MARK -] -
+%[- MARK -] -\subsection{Which Docstrings Are Examined?}
+%[- MARK -] -
+%[- MARK -] -See the docstrings in \file{doctest.py} for all the details. They're
+%[- MARK -] -unsurprising: the module docstring, and all function, class and method
+%[- MARK -] -docstrings are searched. Optionally, the tester can be directed to
+%[- MARK -] -exclude docstrings attached to objects with private names. Objects
+%[- MARK -] -imported into the module are not searched.
+%[- MARK -] -
+%[- MARK -] -In addition, if \code{M.__test__} exists and "is true", it must be a
+%[- MARK -] -dict, and each entry maps a (string) name to a function object, class
+%[- MARK -] -object, or string. Function and class object docstrings found from
+%[- MARK -] -\code{M.__test__} are searched even if the tester has been
+%[- MARK -] -directed to skip over private names in the rest of the module.
+%[- MARK -] -In output, a key \code{K} in \code{M.__test__} appears with name
+%[- MARK -] +prohibit it by passing \code{verbose=False}. In either of those cases,
+%[- MARK -] +\code{sys.argv} is not examined by \function{testmod()} (so passing
+%[- MARK -] +\programopt{-v} or not has no effect).
+%[- MARK -] +
+%[- MARK -] +For more information on \function{testmod()}, see
+%[- MARK -] +section~\ref{doctest-basic-api}.
+%[- MARK -] +
+%[- MARK -] +\subsection{Simple Usage: Checking Examples in a Text
+%[- MARK -] + File\label{doctest-simple-testfile}}
+%[- MARK -] +
+%[- MARK -] +Another simple application of doctest is testing interactive examples
+%[- MARK -] +in a text file. This can be done with the \function{testfile()}
+%[- MARK -] +function:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -<name of M>.__test__.K
+%[- MARK -] +import doctest
+%[- MARK -] +doctest.testfile("example.txt")
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] -Any classes found are recursively searched similarly, to test docstrings in
+%[- MARK -] -their contained methods and nested classes. While private names reached
+%[- MARK -] -from \module{M}'s globals can be optionally skipped, all names reached from
+%[- MARK -] -\code{M.__test__} are searched.
+%[- MARK -] +That short script executes and verifies any interactive Python
+%[- MARK -] +examples contained in the file \file{example.txt}. The file content
+%[- MARK -] +is treated as if it were a single giant docstring; the file doesn't
+%[- MARK -] +need to contain a Python program! For example, perhaps \file{example.txt}
+%[- MARK -] +contains this:
+%[- MARK -]
+%[- MARK -] -\subsection{What's the Execution Context?}
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +The ``example`` module
+%[- MARK -] +======================
+%[- MARK -]
+%[- MARK -] -By default, each time \function{testmod()} finds a docstring to test, it uses
+%[- MARK -] -a \emph{copy} of \module{M}'s globals, so that running tests on a module
+%[- MARK -] -doesn't change the module's real globals, and so that one test in
+%[- MARK -] -\module{M} can't leave behind crumbs that accidentally allow another test
+%[- MARK -] -to work. This means examples can freely use any names defined at top-level
+%[- MARK -] -in \module{M}, and names defined earlier in the docstring being run.
+%[- MARK -] +Using ``factorial``
+%[- MARK -] +-------------------
+%[- MARK -]
+%[- MARK -] -You can force use of your own dict as the execution context by passing
+%[- MARK -] -\code{globs=your_dict} to \function{testmod()} instead. Presumably this
+%[- MARK -] -would be a copy of \code{M.__dict__} merged with the globals from other
+%[- MARK -] -imported modules.
+%[- MARK -] +This is an example text file in reStructuredText format. First import
+%[- MARK -] +``factorial`` from the ``example`` module:
+%[- MARK -]
+%[- MARK -] -\subsection{What About Exceptions?}
+%[- MARK -] + >>> from example import factorial
+%[- MARK -]
+%[- MARK -] -No problem, as long as the only output generated by the example is the
+%[- MARK -] -traceback itself. For example:
+%[- MARK -] +Now use it:
+%[- MARK -]
+%[- MARK -] -\begin{verbatim}
+%[- MARK -] ->>> [1, 2, 3].remove(42)
+%[- MARK -] -Traceback (most recent call last):
+%[- MARK -] - File "<stdin>", line 1, in ?
+%[- MARK -] -ValueError: list.remove(x): x not in list
+%[- MARK -] ->>>
+%[- MARK -] + >>> factorial(6)
+%[- MARK -] + 120
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] -Note that only the exception type and value are compared (specifically,
+%[- MARK -] -only the last line in the traceback). The various ``File'' lines in
+%[- MARK -] -between can be left out (unless they add significantly to the documentation
+%[- MARK -] -value of the example).
+%[- MARK -] -
+%[- MARK -] -\subsection{Advanced Usage}
+%[- MARK -] -
+%[- MARK -] -Several module level functions are available for controlling how doctests
+%[- MARK -] -are run.
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{debug}{module, name}
+%[- MARK -] - Debug a single docstring containing doctests.
+%[- MARK -] -
+%[- MARK -] - Provide the \var{module} (or dotted name of the module) containing the
+%[- MARK -] - docstring to be debugged and the \var{name} (within the module) of the
+%[- MARK -] - object with the docstring to be debugged.
+%[- MARK -] -
+%[- MARK -] - The doctest examples are extracted (see function \function{testsource()}),
+%[- MARK -] - and written to a temporary file. The Python debugger, \refmodule{pdb},
+%[- MARK -] - is then invoked on that file.
+%[- MARK -] - \versionadded{2.3}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{testmod}{}
+%[- MARK -] - This function provides the most basic interface to the doctests.
+%[- MARK -] - It creates a local instance of class \class{Tester}, runs appropriate
+%[- MARK -] - methods of that class, and merges the results into the global \class{Tester}
+%[- MARK -] - instance, \code{master}.
+%[- MARK -] -
+%[- MARK -] - To get finer control than \function{testmod()} offers, create an instance
+%[- MARK -] - of \class{Tester} with custom policies, or run methods of \code{master}
+%[- MARK -] - directly. See \code{Tester.__doc__} for details.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +Running \code{doctest.testfile("example.txt")} then finds the error
+%[- MARK -] +in this documentation:
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{testsource}{module, name}
+%[- MARK -] - Extract the doctest examples from a docstring.
+%[- MARK -] -
+%[- MARK -] - Provide the \var{module} (or dotted name of the module) containing the
+%[- MARK -] - tests to be extracted and the \var{name} (within the module) of the object
+%[- MARK -] - with the docstring containing the tests to be extracted.
+%[- MARK -] -
+%[- MARK -] - The doctest examples are returned as a string containing Python
+%[- MARK -] - code. The expected output blocks in the examples are converted
+%[- MARK -] - to Python comments.
+%[- MARK -] - \versionadded{2.3}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{DocTestSuite}{\optional{module}}
+%[- MARK -] - Convert doctest tests for a module to a
+%[- MARK -] - \class{\refmodule{unittest}.TestSuite}.
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +File "./example.txt", line 14, in example.txt
+%[- MARK -] +Failed example:
+%[- MARK -] + factorial(6)
+%[- MARK -] +Expected:
+%[- MARK -] + 120
+%[- MARK -] +Got:
+%[- MARK -] + 720
+%[- MARK -] +\end{verbatim}
+%[- MARK -]
+%[- MARK -] - The returned \class{TestSuite} is to be run by the unittest framework
+%[- MARK -] - and runs each doctest in the module. If any of the doctests fail,
+%[- MARK -] - then the synthesized unit test fails, and a \exception{DocTestTestFailure}
+%[- MARK -] - exception is raised showing the name of the file containing the test and a
+%[- MARK -] - (sometimes approximate) line number.
+%[- MARK -] +As with \function{testmod()}, \function{testfile()} won't display anything
+%[- MARK -] +unless an example fails. If an example does fail, then the failing
+%[- MARK -] +example(s) and the cause(s) of the failure(s) are printed to stdout, using
+%[- MARK -] +the same format as \function{testmod()}.
+%[- MARK -] +
+%[- MARK -] +By default, \function{testfile()} looks for files in the calling
+%[- MARK -] +module's directory. See section~\ref{doctest-basic-api} for a
+%[- MARK -] +description of the optional arguments that can be used to tell it to
+%[- MARK -] +look for files in other locations.
+%[- MARK -] +
+%[- MARK -] +Like \function{testmod()}, \function{testfile()}'s verbosity can be
+%[- MARK -] +set with the \programopt{-v} command-line switch or with the optional
+%[- MARK -] +keyword argument \var{verbose}.
+%[- MARK -] +
+%[- MARK -] +For more information on \function{testfile()}, see
+%[- MARK -] +section~\ref{doctest-basic-api}.
+%[- MARK -] +
+%[- MARK -] +\subsection{How It Works\label{doctest-how-it-works}}
+%[- MARK -] +
+%[- MARK -] +This section examines in detail how doctest works: which docstrings it
+%[- MARK -] +looks at, how it finds interactive examples, what execution context it
+%[- MARK -] +uses, how it handles exceptions, and how option flags can be used to
+%[- MARK -] +control its behavior. This is the information that you need to know
+%[- MARK -] +to write doctest examples; for information about actually running
+%[- MARK -] +doctest on these examples, see the following sections.
+%[- MARK -]
+%[- MARK -] - The optional \var{module} argument provides the module to be tested. It
+%[- MARK -] - can be a module object or a (possibly dotted) module name. If not
+%[- MARK -] - specified, the module calling this function is used.
+%[- MARK -] +\subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}}
+%[- MARK -]
+%[- MARK -] - Example using one of the many ways that the \refmodule{unittest} module
+%[- MARK -] - can use a \class{TestSuite}:
+%[- MARK -] +The module docstring, and all function, class and method docstrings are
+%[- MARK -] +searched. Objects imported into the module are not searched.
+%[- MARK -]
+%[- MARK -] - \begin{verbatim}
+%[- MARK -] - import unittest
+%[- MARK -] - import doctest
+%[- MARK -] - import my_module_with_doctests
+%[- MARK -] +In addition, if \code{M.__test__} exists and "is true", it must be a
+%[- MARK -] +dict, and each entry maps a (string) name to a function object, class
+%[- MARK -] +object, or string. Function and class object docstrings found from
+%[- MARK -] +\code{M.__test__} are searched, and strings are treated as if they
+%[- MARK -] +were docstrings. In output, a key \code{K} in \code{M.__test__} appears
+%[- MARK -] +with name
+%[- MARK -]
+%[- MARK -] - suite = doctest.DocTestSuite(my_module_with_doctests)
+%[- MARK -] - runner = unittest.TextTestRunner()
+%[- MARK -] - runner.run(suite)
+%[- MARK -] - \end{verbatim}
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +<name of M>.__test__.K
+%[- MARK -] +\end{verbatim}
+%[- MARK -]
+%[- MARK -] - \versionadded{2.3}
+%[- MARK -] - \warning{This function does not currently search \code{M.__test__}
+%[- MARK -] - and its search technique does not exactly match \function{testmod()} in
+%[- MARK -] - every detail. Future versions will bring the two into convergence.}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +Any classes found are recursively searched similarly, to test docstrings in
+%[- MARK -] +their contained methods and nested classes.
+%[- MARK -]
+%[- MARK -] +\versionchanged[A "private name" concept is deprecated and no longer
+%[- MARK -] + documented]{2.4}
+%[- MARK -]
+%[- MARK -] -\subsection{How are Docstring Examples Recognized?}
+%[- MARK -] +\subsubsection{How are Docstring Examples
+%[- MARK -] + Recognized?\label{doctest-finding-examples}}
+%[- MARK -]
+%[- MARK -] In most cases a copy-and-paste of an interactive console session works
+%[- MARK -] -fine---just make sure the leading whitespace is rigidly consistent
+%[- MARK -] -(you can mix tabs and spaces if you're too lazy to do it right, but
+%[- MARK -] -\module{doctest} is not in the business of guessing what you think a tab
+%[- MARK -] -means).
+%[- MARK -] +fine, but doctest isn't trying to do an exact emulation of any specific
+%[- MARK -] +Python shell. All hard tab characters are expanded to spaces, using
+%[- MARK -] +8-column tab stops. If you don't believe tabs should mean that, too
+%[- MARK -] +bad: don't use hard tabs, or write your own \class{DocTestParser}
+%[- MARK -] +class.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[Expanding tabs to spaces is new; previous versions
+%[- MARK -] + tried to preserve hard tabs, with confusing results]{2.4}
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> # comments are ignored
+%[- MARK -] >>> x = 12
+%[- MARK -] >>> x
+%[- MARK -] END DIFF
\begin{verbatim}
import math
@@ -368,6 +825,61 @@
Per una stampa corretta:
+%[- MARK -] BEGIN DIFF 003 of 6
+%[- MARK -] @@ 354
+%[- MARK -] The fine print:
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -]
+%[- MARK -] \item Expected output cannot contain an all-whitespace line, since such a
+%[- MARK -] - line is taken to signal the end of expected output.
+%[- MARK -] + line is taken to signal the end of expected output. If expected
+%[- MARK -] + output does contain a blank line, put \code{<BLANKLINE>} in your
+%[- MARK -] + doctest example each place a blank line is expected.
+%[- MARK -] + \versionchanged[\code{<BLANKLINE>} was added; there was no way to
+%[- MARK -] + use expected output containing empty lines in
+%[- MARK -] + previous versions]{2.4}
+%[- MARK -]
+%[- MARK -] \item Output to stdout is captured, but not output to stderr (exception
+%[- MARK -] tracebacks are captured via a different means).
+%[- MARK -]
+%[- MARK -] -\item If you continue a line via backslashing in an interactive session, or
+%[- MARK -] - for any other reason use a backslash, you need to double the backslash in
+%[- MARK -] - the docstring version. This is simply because you're in a string, and so
+%[- MARK -] - the backslash must be escaped for it to survive intact. Like:
+%[- MARK -] +\item If you continue a line via backslashing in an interactive session,
+%[- MARK -] + or for any other reason use a backslash, you should use a raw
+%[- MARK -] + docstring, which will preserve your backslashes exactly as you type
+%[- MARK -] + them:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> def f(x):
+%[- MARK -] +... r'''Backslashes in a raw docstring: m\n'''
+%[- MARK -] +>>> print f.__doc__
+%[- MARK -] +Backslashes in a raw docstring: m\n
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + Otherwise, the backslash will be interpreted as part of the string.
+%[- MARK -] + For example, the "{\textbackslash}" above would be interpreted as a
+%[- MARK -] + newline character. Alternatively, you can double each backslash in the
+%[- MARK -] + doctest version (and not use a raw string):
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] ->>> if "yes" == \\
+%[- MARK -] -... "y" + \\
+%[- MARK -] -... "es":
+%[- MARK -] -... print 'yes'
+%[- MARK -] -yes
+%[- MARK -] +>>> def f(x):
+%[- MARK -] +... '''Backslashes in a raw docstring: m\\n'''
+%[- MARK -] +>>> print f.__doc__
+%[- MARK -] +Backslashes in a raw docstring: m\n
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] \item The starting column doesn't matter:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\begin{itemize}
\item L'output atteso non può contenere una riga di spazi vuoti, dato
@@ -400,6 +912,425 @@
>>> import math
>>> math.floor(1.9)
1.0
+%[- MARK -] BEGIN DIFF 004 of 6
+%[- MARK -] @@ 383
+%[- MARK -] 1.0
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] and as many leading whitespace characters are stripped from the
+%[- MARK -] expected output as appeared in the initial \code{'>\code{>}>~'} line
+%[- MARK -] -that triggered it.
+%[- MARK -] +that started the example.
+%[- MARK -] \end{itemize}
+%[- MARK -]
+%[- MARK -] -\subsection{Warnings}
+%[- MARK -] +\subsubsection{What's the Execution Context?\label{doctest-execution-context}}
+%[- MARK -]
+%[- MARK -] -\begin{enumerate}
+%[- MARK -] +By default, each time \refmodule{doctest} finds a docstring to test, it
+%[- MARK -] +uses a \emph{shallow copy} of \module{M}'s globals, so that running tests
+%[- MARK -] +doesn't change the module's real globals, and so that one test in
+%[- MARK -] +\module{M} can't leave behind crumbs that accidentally allow another test
+%[- MARK -] +to work. This means examples can freely use any names defined at top-level
+%[- MARK -] +in \module{M}, and names defined earlier in the docstring being run.
+%[- MARK -] +Examples cannot see names defined in other docstrings.
+%[- MARK -] +
+%[- MARK -] +You can force use of your own dict as the execution context by passing
+%[- MARK -] +\code{globs=your_dict} to \function{testmod()} or
+%[- MARK -] +\function{testfile()} instead.
+%[- MARK -] +
+%[- MARK -] +\subsubsection{What About Exceptions?\label{doctest-exceptions}}
+%[- MARK -] +
+%[- MARK -] +No problem, provided that the traceback is the only output produced by
+%[- MARK -] +the example: just paste in the traceback. Since tracebacks contain
+%[- MARK -] +details that are likely to change rapidly (for example, exact file paths
+%[- MARK -] +and line numbers), this is one case where doctest works hard to be
+%[- MARK -] +flexible in what it accepts.
+%[- MARK -] +
+%[- MARK -] +Simple example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> [1, 2, 3].remove(42)
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] + File "<stdin>", line 1, in ?
+%[- MARK -] +ValueError: list.remove(x): x not in list
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +That doctest succeeds if \exception{ValueError} is raised, with the
+%[- MARK -] +\samp{list.remove(x): x not in list} detail as shown.
+%[- MARK -] +
+%[- MARK -] +The expected output for an exception must start with a traceback
+%[- MARK -] +header, which may be either of the following two lines, indented the
+%[- MARK -] +same as the first line of the example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] +Traceback (innermost last):
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The traceback header is followed by an optional traceback stack, whose
+%[- MARK -] +contents are ignored by doctest. The traceback stack is typically
+%[- MARK -] +omitted, or copied verbatim from an interactive session.
+%[- MARK -] +
+%[- MARK -] +The traceback stack is followed by the most interesting part: the
+%[- MARK -] +line(s) containing the exception type and detail. This is usually the
+%[- MARK -] +last line of a traceback, but can extend across multiple lines if the
+%[- MARK -] +exception has a multi-line detail:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> raise ValueError('multi\n line\ndetail')
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] + File "<stdin>", line 1, in ?
+%[- MARK -] +ValueError: multi
+%[- MARK -] + line
+%[- MARK -] +detail
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The last three lines (starting with \exception{ValueError}) are
+%[- MARK -] +compared against the exception's type and detail, and the rest are
+%[- MARK -] +ignored.
+%[- MARK -] +
+%[- MARK -] +Best practice is to omit the traceback stack, unless it adds
+%[- MARK -] +significant documentation value to the example. So the last example
+%[- MARK -] +is probably better as:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> raise ValueError('multi\n line\ndetail')
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] + ...
+%[- MARK -] +ValueError: multi
+%[- MARK -] + line
+%[- MARK -] +detail
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Note that tracebacks are treated very specially. In particular, in the
+%[- MARK -] +rewritten example, the use of \samp{...} is independent of doctest's
+%[- MARK -] +\constant{ELLIPSIS} option. The ellipsis in that example could be left
+%[- MARK -] +out, or could just as well be three (or three hundred) commas or digits,
+%[- MARK -] +or an indented transcript of a Monty Python skit.
+%[- MARK -] +
+%[- MARK -] +Some details you should read once, but won't need to remember:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +
+%[- MARK -] +\item Doctest can't guess whether your expected output came from an
+%[- MARK -] + exception traceback or from ordinary printing. So, e.g., an example
+%[- MARK -] + that expects \samp{ValueError: 42 is prime} will pass whether
+%[- MARK -] + \exception{ValueError} is actually raised or if the example merely
+%[- MARK -] + prints that traceback text. In practice, ordinary output rarely begins
+%[- MARK -] + with a traceback header line, so this doesn't create real problems.
+%[- MARK -] +
+%[- MARK -] +\item Each line of the traceback stack (if present) must be indented
+%[- MARK -] + further than the first line of the example, \emph{or} start with a
+%[- MARK -] + non-alphanumeric character. The first line following the traceback
+%[- MARK -] + header indented the same and starting with an alphanumeric is taken
+%[- MARK -] + to be the start of the exception detail. Of course this does the
+%[- MARK -] + right thing for genuine tracebacks.
+%[- MARK -] +
+%[- MARK -] +\item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is
+%[- MARK -] + is specified, everything following the leftmost colon is ignored.
+%[- MARK -] +
+%[- MARK -] +\item The interactive shell omits the traceback header line for some
+%[- MARK -] + \exception{SyntaxError}s. But doctest uses the traceback header
+%[- MARK -] + line to distinguish exceptions from non-exceptions. So in the rare
+%[- MARK -] + case where you need to test a \exception{SyntaxError} that omits the
+%[- MARK -] + traceback header, you will need to manually add the traceback header
+%[- MARK -] + line to your test example.
+%[- MARK -] +
+%[- MARK -] +\item For some \exception{SyntaxError}s, Python displays the character
+%[- MARK -] + position of the syntax error, using a \code{\^} marker:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> 1 1
+%[- MARK -] + File "<stdin>", line 1
+%[- MARK -] + 1 1
+%[- MARK -] + ^
+%[- MARK -] +SyntaxError: invalid syntax
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + Since the lines showing the position of the error come before the
+%[- MARK -] + exception type and detail, they are not checked by doctest. For
+%[- MARK -] + example, the following test would pass, even though it puts the
+%[- MARK -] + \code{\^} marker in the wrong location:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> 1 1
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] + File "<stdin>", line 1
+%[- MARK -] + 1 1
+%[- MARK -] + ^
+%[- MARK -] +SyntaxError: invalid syntax
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +\versionchanged[The ability to handle a multi-line exception detail,
+%[- MARK -] + and the \constant{IGNORE_EXCEPTION_DETAIL} doctest option,
+%[- MARK -] + were added]{2.4}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{Option Flags and Directives\label{doctest-options}}
+%[- MARK -] +
+%[- MARK -] +A number of option flags control various aspects of doctest's
+%[- MARK -] +behavior. Symbolic names for the flags are supplied as module constants,
+%[- MARK -] +which can be or'ed together and passed to various functions. The names
+%[- MARK -] +can also be used in doctest directives (see below).
+%[- MARK -] +
+%[- MARK -] +The first group of options define test semantics, controlling
+%[- MARK -] +aspects of how doctest decides whether actual output matches an
+%[- MARK -] +example's expected output:
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
+%[- MARK -] + By default, if an expected output block contains just \code{1},
+%[- MARK -] + an actual output block containing just \code{1} or just
+%[- MARK -] + \code{True} is considered to be a match, and similarly for \code{0}
+%[- MARK -] + versus \code{False}. When \constant{DONT_ACCEPT_TRUE_FOR_1} is
+%[- MARK -] + specified, neither substitution is allowed. The default behavior
+%[- MARK -] + caters to that Python changed the return type of many functions
+%[- MARK -] + from integer to boolean; doctests expecting "little integer"
+%[- MARK -] + output still work in these cases. This option will probably go
+%[- MARK -] + away, but not for several years.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{DONT_ACCEPT_BLANKLINE}
+%[- MARK -] + By default, if an expected output block contains a line
+%[- MARK -] + containing only the string \code{<BLANKLINE>}, then that line
+%[- MARK -] + will match a blank line in the actual output. Because a
+%[- MARK -] + genuinely blank line delimits the expected output, this is
+%[- MARK -] + the only way to communicate that a blank line is expected. When
+%[- MARK -] + \constant{DONT_ACCEPT_BLANKLINE} is specified, this substitution
+%[- MARK -] + is not allowed.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{NORMALIZE_WHITESPACE}
+%[- MARK -] + When specified, all sequences of whitespace (blanks and newlines) are
+%[- MARK -] + treated as equal. Any sequence of whitespace within the expected
+%[- MARK -] + output will match any sequence of whitespace within the actual output.
+%[- MARK -] + By default, whitespace must match exactly.
+%[- MARK -] + \constant{NORMALIZE_WHITESPACE} is especially useful when a line
+%[- MARK -] + of expected output is very long, and you want to wrap it across
+%[- MARK -] + multiple lines in your source.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{ELLIPSIS}
+%[- MARK -] + When specified, an ellipsis marker (\code{...}) in the expected output
+%[- MARK -] + can match any substring in the actual output. This includes
+%[- MARK -] + substrings that span line boundaries, and empty substrings, so it's
+%[- MARK -] + best to keep usage of this simple. Complicated uses can lead to the
+%[- MARK -] + same kinds of "oops, it matched too much!" surprises that \regexp{.*}
+%[- MARK -] + is prone to in regular expressions.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{IGNORE_EXCEPTION_DETAIL}
+%[- MARK -] + When specified, an example that expects an exception passes if
+%[- MARK -] + an exception of the expected type is raised, even if the exception
+%[- MARK -] + detail does not match. For example, an example expecting
+%[- MARK -] + \samp{ValueError: 42} will pass if the actual exception raised is
+%[- MARK -] + \samp{ValueError: 3*14}, but will fail, e.g., if
+%[- MARK -] + \exception{TypeError} is raised.
+%[- MARK -] +
+%[- MARK -] + Note that a similar effect can be obtained using \constant{ELLIPSIS},
+%[- MARK -] + and \constant{IGNORE_EXCEPTION_DETAIL} may go away when Python releases
+%[- MARK -] + prior to 2.4 become uninteresting. Until then,
+%[- MARK -] + \constant{IGNORE_EXCEPTION_DETAIL} is the only clear way to write a
+%[- MARK -] + doctest that doesn't care about the exception detail yet continues
+%[- MARK -] + to pass under Python releases prior to 2.4 (doctest directives
+%[- MARK -] + appear to be comments to them). For example,
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] + File "<stdin>", line 1, in ?
+%[- MARK -] +TypeError: object doesn't support item assignment
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + passes under Python 2.4 and Python 2.3. The detail changed in 2.4,
+%[- MARK -] + to say "does not" instead of "doesn't".
+%[- MARK -] +
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{COMPARISON_FLAGS}
+%[- MARK -] + A bitmask or'ing together all the comparison flags above.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +The second group of options controls how test failures are reported:
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{REPORT_UDIFF}
+%[- MARK -] + When specified, failures that involve multi-line expected and
+%[- MARK -] + actual outputs are displayed using a unified diff.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{REPORT_CDIFF}
+%[- MARK -] + When specified, failures that involve multi-line expected and
+%[- MARK -] + actual outputs will be displayed using a context diff.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{REPORT_NDIFF}
+%[- MARK -] + When specified, differences are computed by \code{difflib.Differ},
+%[- MARK -] + using the same algorithm as the popular \file{ndiff.py} utility.
+%[- MARK -] + This is the only method that marks differences within lines as
+%[- MARK -] + well as across lines. For example, if a line of expected output
+%[- MARK -] + contains digit \code{1} where actual output contains letter \code{l},
+%[- MARK -] + a line is inserted with a caret marking the mismatching column
+%[- MARK -] + positions.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{REPORT_ONLY_FIRST_FAILURE}
+%[- MARK -] + When specified, display the first failing example in each doctest,
+%[- MARK -] + but suppress output for all remaining examples. This will prevent
+%[- MARK -] + doctest from reporting correct examples that break because of
+%[- MARK -] + earlier failures; but it might also hide incorrect examples that
+%[- MARK -] + fail independently of the first failure. When
+%[- MARK -] + \constant{REPORT_ONLY_FIRST_FAILURE} is specified, the remaining
+%[- MARK -] + examples are still run, and still count towards the total number of
+%[- MARK -] + failures reported; only the output is suppressed.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{REPORTING_FLAGS}
+%[- MARK -] + A bitmask or'ing together all the reporting flags above.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +"Doctest directives" may be used to modify the option flags for
+%[- MARK -] +individual examples. Doctest directives are expressed as a special
+%[- MARK -] +Python comment following an example's source code:
+%[- MARK -] +
+%[- MARK -] +\begin{productionlist}[doctest]
+%[- MARK -] + \production{directive}
+%[- MARK -] + {"\#" "doctest:" \token{directive_options}}
+%[- MARK -] + \production{directive_options}
+%[- MARK -] + {\token{directive_option} ("," \token{directive_option})*}
+%[- MARK -] + \production{directive_option}
+%[- MARK -] + {\token{on_or_off} \token{directive_option_name}}
+%[- MARK -] + \production{on_or_off}
+%[- MARK -] + {"+" | "-"}
+%[- MARK -] + \production{directive_option_name}
+%[- MARK -] + {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...}
+%[- MARK -] +\end{productionlist}
+%[- MARK -] +
+%[- MARK -] +Whitespace is not allowed between the \code{+} or \code{-} and the
+%[- MARK -] +directive option name. The directive option name can be any of the
+%[- MARK -] +option flag names explained above.
+%[- MARK -] +
+%[- MARK -] +An example's doctest directives modify doctest's behavior for that
+%[- MARK -] +single example. Use \code{+} to enable the named behavior, or
+%[- MARK -] +\code{-} to disable it.
+%[- MARK -] +
+%[- MARK -] +For example, this test passes:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> print range(20) #doctest: +NORMALIZE_WHITESPACE
+%[- MARK -] +[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+%[- MARK -] +10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
+%[- MARK -] +\end{verbatim}
+%[- MARK -]
+%[- MARK -] -\item \module{doctest} is serious about requiring exact matches in expected
+%[- MARK -] - output. If even a single character doesn't match, the test fails. This
+%[- MARK -] - will probably surprise you a few times, as you learn exactly what Python
+%[- MARK -] - does and doesn't guarantee about output. For example, when printing a
+%[- MARK -] - dict, Python doesn't guarantee that the key-value pairs will be printed
+%[- MARK -] - in any particular order, so a test like
+%[- MARK -] +Without the directive it would fail, both because the actual output
+%[- MARK -] +doesn't have two blanks before the single-digit list elements, and
+%[- MARK -] +because the actual output is on a single line. This test also passes,
+%[- MARK -] +and also requires a directive to do so:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> print range(20) # doctest:+ELLIPSIS
+%[- MARK -] +[0, 1, ..., 18, 19]
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Multiple directives can be used on a single physical line, separated
+%[- MARK -] +by commas:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+%[- MARK -] +[0, 1, ..., 18, 19]
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +If multiple directive comments are used for a single example, then
+%[- MARK -] +they are combined:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> print range(20) # doctest: +ELLIPSIS
+%[- MARK -] +... # doctest: +NORMALIZE_WHITESPACE
+%[- MARK -] +[0, 1, ..., 18, 19]
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +As the previous example shows, you can add \samp{...} lines to your
+%[- MARK -] +example containing only directives. This can be useful when an
+%[- MARK -] +example is too long for a directive to comfortably fit on the same
+%[- MARK -] +line:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> print range(5) + range(10,20) + range(30,40) + range(50,60)
+%[- MARK -] +... # doctest: +ELLIPSIS
+%[- MARK -] +[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Note that since all options are disabled by default, and directives apply
+%[- MARK -] +only to the example they appear in, enabling options (via \code{+} in a
+%[- MARK -] +directive) is usually the only meaningful choice. However, option flags
+%[- MARK -] +can also be passed to functions that run doctests, establishing different
+%[- MARK -] +defaults. In such cases, disabling an option via \code{-} in a directive
+%[- MARK -] +can be useful.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
+%[- MARK -] + \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
+%[- MARK -] + \constant{IGNORE_EXCEPTION_DETAIL},
+%[- MARK -] + \constant{REPORT_UDIFF}, \constant{REPORT_CDIFF},
+%[- MARK -] + \constant{REPORT_NDIFF}, \constant{REPORT_ONLY_FIRST_FAILURE},
+%[- MARK -] + \constant{COMPARISON_FLAGS} and \constant{REPORTING_FLAGS}
+%[- MARK -] + were added; by default \code{<BLANKLINE>} in expected output
+%[- MARK -] + matches an empty line in actual output; and doctest directives
+%[- MARK -] + were added]{2.4}
+%[- MARK -] +
+%[- MARK -] +There's also a way to register new option flag names, although this
+%[- MARK -] +isn't useful unless you intend to extend \refmodule{doctest} internals
+%[- MARK -] +via subclassing:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{register_optionflag}{name}
+%[- MARK -] + Create a new option flag with a given name, and return the new
+%[- MARK -] + flag's integer value. \function{register_optionflag()} can be
+%[- MARK -] + used when subclassing \class{OutputChecker} or
+%[- MARK -] + \class{DocTestRunner} to create new options that are supported by
+%[- MARK -] + your subclasses. \function{register_optionflag} should always be
+%[- MARK -] + called using the following idiom:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + MY_FLAG = register_optionflag('MY_FLAG')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{Warnings\label{doctest-warnings}}
+%[- MARK -] +
+%[- MARK -] +\refmodule{doctest} is serious about requiring exact matches in expected
+%[- MARK -] +output. If even a single character doesn't match, the test fails. This
+%[- MARK -] +will probably surprise you a few times, as you learn exactly what Python
+%[- MARK -] +does and doesn't guarantee about output. For example, when printing a
+%[- MARK -] +dict, Python doesn't guarantee that the key-value pairs will be printed
+%[- MARK -] +in any particular order, so a test like
+%[- MARK -]
+%[- MARK -] % Hey! What happened to Monty Python examples?
+%[- MARK -] % Tim: ask Guido -- it's his example!
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> foo()
+%[- MARK -] {"Hermione": "hippogryph", "Harry": "broomstick"}
+%[- MARK -] ->>>
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] is vulnerable! One workaround is to do
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
+%[- MARK -] True
+%[- MARK -] ->>>
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] instead. Another is to do
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\end{verbatim}
e viene eliminato dall'output atteso un numero di spazi vuoti iniziali
@@ -447,6 +1378,31 @@
Ci sono ancora altri metodi ma ormai vi sarete fatti un'idea.
Un'altra cattiva idea è quella di stampare cose che incorporano un
+%[- MARK -] BEGIN DIFF 005 of 6
+%[- MARK -] @@ 429
+%[- MARK -] Another bad idea is to print things that embed an object address, like
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> id(1.0) # certain to fail some of the time
+%[- MARK -] 7948648
+%[- MARK -] ->>>
+%[- MARK -] +>>> class C: pass
+%[- MARK -] +>>> C() # the default repr() for instances embeds an address
+%[- MARK -] +<__main__.C instance at 0x00AC18F0>
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The \constant{ELLIPSIS} directive gives a nice approach for the last
+%[- MARK -] +example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> C() #doctest: +ELLIPSIS
+%[- MARK -] +<__main__.C instance at 0x...>
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] Floating-point numbers are also subject to small output variations across
+%[- MARK -] platforms, because Python defers to the platform C library for float
+%[- MARK -] formatting, and C libraries vary widely in quality here.
+%[- MARK -] END DIFF
indirizzo di un oggetto, come per esempio
\begin{verbatim}
@@ -479,6 +1435,1130 @@
\end{verbatim}
Inoltre le frazioni semplici sono più facili da capire e sono quindi più
+%[- MARK -] BEGIN DIFF 006 of 6
+%[- MARK -] @@ 456
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] Simple fractions are also easier for people to understand, and that makes
+%[- MARK -] for better documentation.
+%[- MARK -]
+%[- MARK -] -\item Be careful if you have code that must only execute once.
+%[- MARK -] +\subsection{Basic API\label{doctest-basic-api}}
+%[- MARK -] +
+%[- MARK -] +The functions \function{testmod()} and \function{testfile()} provide a
+%[- MARK -] +simple interface to doctest that should be sufficient for most basic
+%[- MARK -] +uses. For a less formal introduction to these two functions, see
+%[- MARK -] +sections \ref{doctest-simple-testmod} and
+%[- MARK -] +\ref{doctest-simple-testfile}.
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{testfile}{filename\optional{, module_relative}\optional{,
+%[- MARK -] + name}\optional{, package}\optional{,
+%[- MARK -] + globs}\optional{, verbose}\optional{,
+%[- MARK -] + report}\optional{, optionflags}\optional{,
+%[- MARK -] + extraglobs}\optional{, raise_on_error}\optional{,
+%[- MARK -] + parser}}
+%[- MARK -] +
+%[- MARK -] + All arguments except \var{filename} are optional, and should be
+%[- MARK -] + specified in keyword form.
+%[- MARK -] +
+%[- MARK -] + Test examples in the file named \var{filename}. Return
+%[- MARK -] + \samp{(\var{failure_count}, \var{test_count})}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{module_relative} specifies how the filename
+%[- MARK -] + should be interpreted:
+%[- MARK -] +
+%[- MARK -] + \begin{itemize}
+%[- MARK -] + \item If \var{module_relative} is \code{True} (the default), then
+%[- MARK -] + \var{filename} specifies an OS-independent module-relative
+%[- MARK -] + path. By default, this path is relative to the calling
+%[- MARK -] + module's directory; but if the \var{package} argument is
+%[- MARK -] + specified, then it is relative to that package. To ensure
+%[- MARK -] + OS-independence, \var{filename} should use \code{/} characters
+%[- MARK -] + to separate path segments, and may not be an absolute path
+%[- MARK -] + (i.e., it may not begin with \code{/}).
+%[- MARK -] + \item If \var{module_relative} is \code{False}, then \var{filename}
+%[- MARK -] + specifies an OS-specific path. The path may be absolute or
+%[- MARK -] + relative; relative paths are resolved with respect to the
+%[- MARK -] + current working directory.
+%[- MARK -] + \end{itemize}
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{name} gives the name of the test; by default,
+%[- MARK -] + or if \code{None}, \code{os.path.basename(\var{filename})} is used.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{package} is a Python package or the name of a
+%[- MARK -] + Python package whose directory should be used as the base directory
+%[- MARK -] + for a module-relative filename. If no package is specified, then
+%[- MARK -] + the calling module's directory is used as the base directory for
+%[- MARK -] + module-relative filenames. It is an error to specify \var{package}
+%[- MARK -] + if \var{module_relative} is \code{False}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{globs} gives a dict to be used as the globals
+%[- MARK -] + when executing examples. A new shallow copy of this dict is
+%[- MARK -] + created for the doctest, so its examples start with a clean slate.
+%[- MARK -] + By default, or if \code{None}, a new empty dict is used.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{extraglobs} gives a dict merged into the
+%[- MARK -] + globals used to execute examples. This works like
+%[- MARK -] + \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
+%[- MARK -] + common key, the associated value in \var{extraglobs} appears in the
+%[- MARK -] + combined dict. By default, or if \code{None}, no extra globals are
+%[- MARK -] + used. This is an advanced feature that allows parameterization of
+%[- MARK -] + doctests. For example, a doctest can be written for a base class, using
+%[- MARK -] + a generic name for the class, then reused to test any number of
+%[- MARK -] + subclasses by passing an \var{extraglobs} dict mapping the generic
+%[- MARK -] + name to the subclass to be tested.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{verbose} prints lots of stuff if true, and prints
+%[- MARK -] + only failures if false; by default, or if \code{None}, it's true
+%[- MARK -] + if and only if \code{'-v'} is in \code{sys.argv}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{report} prints a summary at the end when true,
+%[- MARK -] + else prints nothing at the end. In verbose mode, the summary is
+%[- MARK -] + detailed, else the summary is very brief (in fact, empty if all tests
+%[- MARK -] + passed).
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{optionflags} or's together option flags. See
+%[- MARK -] + section~\ref{doctest-options}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{raise_on_error} defaults to false. If true,
+%[- MARK -] + an exception is raised upon the first failure or unexpected exception
+%[- MARK -] + in an example. This allows failures to be post-mortem debugged.
+%[- MARK -] + Default behavior is to continue running examples.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{parser} specifies a \class{DocTestParser} (or
+%[- MARK -] + subclass) that should be used to extract tests from the files. It
+%[- MARK -] + defaults to a normal parser (i.e., \code{\class{DocTestParser}()}).
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
+%[- MARK -] + globs}\optional{, verbose}\optional{,
+%[- MARK -] + isprivate}\optional{, report}\optional{,
+%[- MARK -] + optionflags}\optional{, extraglobs}\optional{,
+%[- MARK -] + raise_on_error}\optional{, exclude_empty}}
+%[- MARK -] +
+%[- MARK -] + All arguments are optional, and all except for \var{m} should be
+%[- MARK -] + specified in keyword form.
+%[- MARK -] +
+%[- MARK -] + Test examples in docstrings in functions and classes reachable
+%[- MARK -] + from module \var{m} (or module \module{__main__} if \var{m} is not
+%[- MARK -] + supplied or is \code{None}), starting with \code{\var{m}.__doc__}.
+%[- MARK -] +
+%[- MARK -] + Also test examples reachable from dict \code{\var{m}.__test__}, if it
+%[- MARK -] + exists and is not \code{None}. \code{\var{m}.__test__} maps
+%[- MARK -] + names (strings) to functions, classes and strings; function and class
+%[- MARK -] + docstrings are searched for examples; strings are searched directly,
+%[- MARK -] + as if they were docstrings.
+%[- MARK -] +
+%[- MARK -] + Only docstrings attached to objects belonging to module \var{m} are
+%[- MARK -] + searched.
+%[- MARK -] +
+%[- MARK -] + Return \samp{(\var{failure_count}, \var{test_count})}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{name} gives the name of the module; by default,
+%[- MARK -] + or if \code{None}, \code{\var{m}.__name__} is used.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{exclude_empty} defaults to false. If true,
+%[- MARK -] + objects for which no doctests are found are excluded from consideration.
+%[- MARK -] + The default is a backward compatibility hack, so that code still
+%[- MARK -] + using \method{doctest.master.summarize()} in conjunction with
+%[- MARK -] + \function{testmod()} continues to get output for objects with no tests.
+%[- MARK -] + The \var{exclude_empty} argument to the newer \class{DocTestFinder}
+%[- MARK -] + constructor defaults to true.
+%[- MARK -] +
+%[- MARK -] + Optional arguments \var{extraglobs}, \var{verbose}, \var{report},
+%[- MARK -] + \var{optionflags}, \var{raise_on_error}, and \var{globs} are the same as
+%[- MARK -] + for function \function{testfile()} above, except that \var{globs}
+%[- MARK -] + defaults to \code{\var{m}.__dict__}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{isprivate} specifies a function used to
+%[- MARK -] + determine whether a name is private. The default function treats
+%[- MARK -] + all names as public. \var{isprivate} can be set to
+%[- MARK -] + \code{doctest.is_private} to skip over names that are
+%[- MARK -] + private according to Python's underscore naming convention.
+%[- MARK -] + \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
+%[- MARK -] + If you need to skip tests based on name, filter the list returned by
+%[- MARK -] + \code{DocTestFinder.find()} instead.}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[The parameter \var{optionflags} was added]{2.3}
+%[- MARK -]
+%[- MARK -] -If you have module-level code that must only execute once, a more foolproof
+%[- MARK -] -definition of \function{_test()} is
+%[- MARK -] + \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error}
+%[- MARK -] + and \var{exclude_empty} were added]{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +There's also a function to run the doctests associated with a single object.
+%[- MARK -] +This function is provided for backward compatibility. There are no plans
+%[- MARK -] +to deprecate it, but it's rarely useful:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{run_docstring_examples}{f, globs\optional{,
+%[- MARK -] + verbose}\optional{, name}\optional{,
+%[- MARK -] + compileflags}\optional{, optionflags}}
+%[- MARK -] +
+%[- MARK -] + Test examples associated with object \var{f}; for example, \var{f} may
+%[- MARK -] + be a module, function, or class object.
+%[- MARK -] +
+%[- MARK -] + A shallow copy of dictionary argument \var{globs} is used for the
+%[- MARK -] + execution context.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{name} is used in failure messages, and defaults
+%[- MARK -] + to \code{"NoName"}.
+%[- MARK -] +
+%[- MARK -] + If optional argument \var{verbose} is true, output is generated even
+%[- MARK -] + if there are no failures. By default, output is generated only in case
+%[- MARK -] + of an example failure.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{compileflags} gives the set of flags that should
+%[- MARK -] + be used by the Python compiler when running the examples. By default, or
+%[- MARK -] + if \code{None}, flags are deduced corresponding to the set of future
+%[- MARK -] + features found in \var{globs}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{optionflags} works as for function
+%[- MARK -] + \function{testfile()} above.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\subsection{Unittest API\label{doctest-unittest-api}}
+%[- MARK -] +
+%[- MARK -] +As your collection of doctest'ed modules grows, you'll want a way to run
+%[- MARK -] +all their doctests systematically. Prior to Python 2.4, \refmodule{doctest}
+%[- MARK -] +had a barely documented \class{Tester} class that supplied a rudimentary
+%[- MARK -] +way to combine doctests from multiple modules. \class{Tester} was feeble,
+%[- MARK -] +and in practice most serious Python testing frameworks build on the
+%[- MARK -] +\refmodule{unittest} module, which supplies many flexible ways to combine
+%[- MARK -] +tests from multiple sources. So, in Python 2.4, \refmodule{doctest}'s
+%[- MARK -] +\class{Tester} class is deprecated, and \refmodule{doctest} provides two
+%[- MARK -] +functions that can be used to create \refmodule{unittest} test suites from
+%[- MARK -] +modules and text files containing doctests. These test suites can then be
+%[- MARK -] +run using \refmodule{unittest} test runners:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -def _test():
+%[- MARK -] - import doctest, sys
+%[- MARK -] - doctest.testmod()
+%[- MARK -] +import unittest
+%[- MARK -] +import doctest
+%[- MARK -] +import my_module_with_doctests, and_another
+%[- MARK -] +
+%[- MARK -] +suite = unittest.TestSuite()
+%[- MARK -] +for mod in my_module_with_doctests, and_another:
+%[- MARK -] + suite.addTest(doctest.DocTestSuite(mod))
+%[- MARK -] +runner = unittest.TextTestRunner()
+%[- MARK -] +runner.run(suite)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] -\item WYSIWYG isn't always the case, starting in Python 2.3. The
+%[- MARK -] - string form of boolean results changed from \code{'0'} and
+%[- MARK -] - \code{'1'} to \code{'False'} and \code{'True'} in Python 2.3.
+%[- MARK -] - This makes it clumsy to write a doctest showing boolean results that
+%[- MARK -] - passes under multiple versions of Python. In Python 2.3, by default,
+%[- MARK -] - and as a special case, if an expected output block consists solely
+%[- MARK -] - of \code{'0'} and the actual output block consists solely of
+%[- MARK -] - \code{'False'}, that's accepted as an exact match, and similarly for
+%[- MARK -] - \code{'1'} versus \code{'True'}. This behavior can be turned off by
+%[- MARK -] - passing the new (in 2.3) module constant
+%[- MARK -] - \constant{DONT_ACCEPT_TRUE_FOR_1} as the value of \function{testmod()}'s
+%[- MARK -] - new (in 2.3) optional \var{optionflags} argument. Some years after
+%[- MARK -] - the integer spellings of booleans are history, this hack will
+%[- MARK -] - probably be removed again.
+%[- MARK -] +There are two main functions for creating \class{\refmodule{unittest}.TestSuite}
+%[- MARK -] +instances from text files and modules with doctests:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{DocFileSuite}{*paths, **kw}
+%[- MARK -] + Convert doctest tests from one or more text files to a
+%[- MARK -] + \class{\refmodule{unittest}.TestSuite}.
+%[- MARK -] +
+%[- MARK -] + The returned \class{\refmodule{unittest}.TestSuite} is to be run by the
+%[- MARK -] + unittest framework and runs the interactive examples in each file. If an
+%[- MARK -] + example in any file fails, then the synthesized unit test fails, and a
+%[- MARK -] + \exception{failureException} exception is raised showing the name of the
+%[- MARK -] + file containing the test and a (sometimes approximate) line number.
+%[- MARK -] +
+%[- MARK -] + Pass one or more paths (as strings) to text files to be examined.
+%[- MARK -] +
+%[- MARK -] + Options may be provided as keyword arguments:
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{module_relative} specifies how
+%[- MARK -] + the filenames in \var{paths} should be interpreted:
+%[- MARK -] +
+%[- MARK -] + \begin{itemize}
+%[- MARK -] + \item If \var{module_relative} is \code{True} (the default), then
+%[- MARK -] + each filename specifies an OS-independent module-relative
+%[- MARK -] + path. By default, this path is relative to the calling
+%[- MARK -] + module's directory; but if the \var{package} argument is
+%[- MARK -] + specified, then it is relative to that package. To ensure
+%[- MARK -] + OS-independence, each filename should use \code{/} characters
+%[- MARK -] + to separate path segments, and may not be an absolute path
+%[- MARK -] + (i.e., it may not begin with \code{/}).
+%[- MARK -] + \item If \var{module_relative} is \code{False}, then each filename
+%[- MARK -] + specifies an OS-specific path. The path may be absolute or
+%[- MARK -] + relative; relative paths are resolved with respect to the
+%[- MARK -] + current working directory.
+%[- MARK -] + \end{itemize}
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{package} is a Python package or the name
+%[- MARK -] + of a Python package whose directory should be used as the base
+%[- MARK -] + directory for module-relative filenames. If no package is
+%[- MARK -] + specified, then the calling module's directory is used as the base
+%[- MARK -] + directory for module-relative filenames. It is an error to specify
+%[- MARK -] + \var{package} if \var{module_relative} is \code{False}.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{setUp} specifies a set-up function for
+%[- MARK -] + the test suite. This is called before running the tests in each
+%[- MARK -] + file. The \var{setUp} function will be passed a \class{DocTest}
+%[- MARK -] + object. The setUp function can access the test globals as the
+%[- MARK -] + \var{globs} attribute of the test passed.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{tearDown} specifies a tear-down function
+%[- MARK -] + for the test suite. This is called after running the tests in each
+%[- MARK -] + file. The \var{tearDown} function will be passed a \class{DocTest}
+%[- MARK -] + object. The setUp function can access the test globals as the
+%[- MARK -] + \var{globs} attribute of the test passed.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{globs} is a dictionary containing the
+%[- MARK -] + initial global variables for the tests. A new copy of this
+%[- MARK -] + dictionary is created for each test. By default, \var{globs} is
+%[- MARK -] + a new empty dictionary.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{optionflags} specifies the default
+%[- MARK -] + doctest options for the tests, created by or-ing together
+%[- MARK -] + individual option flags. See section~\ref{doctest-options}.
+%[- MARK -] + See function \function{set_unittest_reportflags()} below for
+%[- MARK -] + a better way to set reporting options.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{parser} specifies a \class{DocTestParser} (or
+%[- MARK -] + subclass) that should be used to extract tests from the files. It
+%[- MARK -] + defaults to a normal parser (i.e., \code{\class{DocTestParser}()}).
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{DocTestSuite}{\optional{module}\optional{,
+%[- MARK -] + globs}\optional{, extraglobs}\optional{,
+%[- MARK -] + test_finder}\optional{, setUp}\optional{,
+%[- MARK -] + tearDown}\optional{, checker}}
+%[- MARK -] + Convert doctest tests for a module to a
+%[- MARK -] + \class{\refmodule{unittest}.TestSuite}.
+%[- MARK -] +
+%[- MARK -] + The returned \class{\refmodule{unittest}.TestSuite} is to be run by the
+%[- MARK -] + unittest framework and runs each doctest in the module. If any of the
+%[- MARK -] + doctests fail, then the synthesized unit test fails, and a
+%[- MARK -] + \exception{failureException} exception is raised showing the name of the
+%[- MARK -] + file containing the test and a (sometimes approximate) line number.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{module} provides the module to be tested. It
+%[- MARK -] + can be a module object or a (possibly dotted) module name. If not
+%[- MARK -] + specified, the module calling this function is used.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{globs} is a dictionary containing the
+%[- MARK -] + initial global variables for the tests. A new copy of this
+%[- MARK -] + dictionary is created for each test. By default, \var{globs} is
+%[- MARK -] + a new empty dictionary.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{extraglobs} specifies an extra set of
+%[- MARK -] + global variables, which is merged into \var{globs}. By default, no
+%[- MARK -] + extra globals are used.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{test_finder} is the \class{DocTestFinder}
+%[- MARK -] + object (or a drop-in replacement) that is used to extract doctests
+%[- MARK -] + from the module.
+%[- MARK -] +
+%[- MARK -] + Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags}
+%[- MARK -] + are the same as for function \function{DocFileSuite()} above.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.3}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[The parameters \var{globs}, \var{extraglobs},
+%[- MARK -] + \var{test_finder}, \var{setUp}, \var{tearDown}, and
+%[- MARK -] + \var{optionflags} were added; this function now uses the same search
+%[- MARK -] + technique as \function{testmod()}]{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +Under the covers, \function{DocTestSuite()} creates a
+%[- MARK -] +\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocTestCase}
+%[- MARK -] +instances, and \class{DocTestCase} is a subclass of
+%[- MARK -] +\class{\refmodule{unittest}.TestCase}. \class{DocTestCase} isn't documented
+%[- MARK -] +here (it's an internal detail), but studying its code can answer questions
+%[- MARK -] +about the exact details of \refmodule{unittest} integration.
+%[- MARK -] +
+%[- MARK -] +Similarly, \function{DocFileSuite()} creates a
+%[- MARK -] +\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocFileCase}
+%[- MARK -] +instances, and \class{DocFileCase} is a subclass of \class{DocTestCase}.
+%[- MARK -] +
+%[- MARK -] +So both ways of creating a \class{\refmodule{unittest}.TestSuite} run
+%[- MARK -] +instances of \class{DocTestCase}. This is important for a subtle reason:
+%[- MARK -] +when you run \refmodule{doctest} functions yourself, you can control the
+%[- MARK -] +\refmodule{doctest} options in use directly, by passing option flags to
+%[- MARK -] +\refmodule{doctest} functions. However, if you're writing a
+%[- MARK -] +\refmodule{unittest} framework, \refmodule{unittest} ultimately controls
+%[- MARK -] +when and how tests get run. The framework author typically wants to
+%[- MARK -] +control \refmodule{doctest} reporting options (perhaps, e.g., specified by
+%[- MARK -] +command line options), but there's no way to pass options through
+%[- MARK -] +\refmodule{unittest} to \refmodule{doctest} test runners.
+%[- MARK -] +
+%[- MARK -] +For this reason, \refmodule{doctest} also supports a notion of
+%[- MARK -] +\refmodule{doctest} reporting flags specific to \refmodule{unittest}
+%[- MARK -] +support, via this function:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{set_unittest_reportflags}{flags}
+%[- MARK -] + Set the \refmodule{doctest} reporting flags to use.
+%[- MARK -] +
+%[- MARK -] + Argument \var{flags} or's together option flags. See
+%[- MARK -] + section~\ref{doctest-options}. Only "reporting flags" can be used.
+%[- MARK -] +
+%[- MARK -] + This is a module-global setting, and affects all future doctests run by
+%[- MARK -] + module \refmodule{unittest}: the \method{runTest()} method of
+%[- MARK -] + \class{DocTestCase} looks at the option flags specified for the test case
+%[- MARK -] + when the \class{DocTestCase} instance was constructed. If no reporting
+%[- MARK -] + flags were specified (which is the typical and expected case),
+%[- MARK -] + \refmodule{doctest}'s \refmodule{unittest} reporting flags are or'ed into
+%[- MARK -] + the option flags, and the option flags so augmented are passed to the
+%[- MARK -] + \class{DocTestRunner} instance created to run the doctest. If any
+%[- MARK -] + reporting flags were specified when the \class{DocTestCase} instance was
+%[- MARK -] + constructed, \refmodule{doctest}'s \refmodule{unittest} reporting flags
+%[- MARK -] + are ignored.
+%[- MARK -] +
+%[- MARK -] + The value of the \refmodule{unittest} reporting flags in effect before the
+%[- MARK -] + function was called is returned by the function.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\end{enumerate}
+%[- MARK -]
+%[- MARK -] +\subsection{Advanced API\label{doctest-advanced-api}}
+%[- MARK -]
+%[- MARK -] -\subsection{Soapbox}
+%[- MARK -] +The basic API is a simple wrapper that's intended to make doctest easy
+%[- MARK -] +to use. It is fairly flexible, and should meet most users' needs;
+%[- MARK -] +however, if you require more fine-grained control over testing, or
+%[- MARK -] +wish to extend doctest's capabilities, then you should use the
+%[- MARK -] +advanced API.
+%[- MARK -]
+%[- MARK -] -The first word in ``doctest'' is ``doc,'' and that's why the author
+%[- MARK -] -wrote \refmodule{doctest}: to keep documentation up to date. It so
+%[- MARK -] -happens that \refmodule{doctest} makes a pleasant unit testing
+%[- MARK -] -environment, but that's not its primary purpose.
+%[- MARK -] -
+%[- MARK -] -Choose docstring examples with care. There's an art to this that
+%[- MARK -] -needs to be learned---it may not be natural at first. Examples should
+%[- MARK -] -add genuine value to the documentation. A good example can often be
+%[- MARK -] -worth many words. If possible, show just a few normal cases, show
+%[- MARK -] -endcases, show interesting subtle cases, and show an example of each
+%[- MARK -] -kind of exception that can be raised. You're probably testing for
+%[- MARK -] -endcases and subtle cases anyway in an interactive shell:
+%[- MARK -] -\refmodule{doctest} wants to make it as easy as possible to capture
+%[- MARK -] -those sessions, and will verify they continue to work as designed
+%[- MARK -] -forever after.
+%[- MARK -] +The advanced API revolves around two container classes, which are used
+%[- MARK -] +to store the interactive examples extracted from doctest cases:
+%[- MARK -]
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \class{Example}: A single python statement, paired with its
+%[- MARK -] + expected output.
+%[- MARK -] +\item \class{DocTest}: A collection of \class{Example}s, typically
+%[- MARK -] + extracted from a single docstring or text file.
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Additional processing classes are defined to find, parse, and run, and
+%[- MARK -] +check doctest examples:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \class{DocTestFinder}: Finds all docstrings in a given module,
+%[- MARK -] + and uses a \class{DocTestParser} to create a \class{DocTest}
+%[- MARK -] + from every docstring that contains interactive examples.
+%[- MARK -] +\item \class{DocTestParser}: Creates a \class{DocTest} object from
+%[- MARK -] + a string (such as an object's docstring).
+%[- MARK -] +\item \class{DocTestRunner}: Executes the examples in a
+%[- MARK -] + \class{DocTest}, and uses an \class{OutputChecker} to verify
+%[- MARK -] + their output.
+%[- MARK -] +\item \class{OutputChecker}: Compares the actual output from a
+%[- MARK -] + doctest example with the expected output, and decides whether
+%[- MARK -] + they match.
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +The relationships among these processing classes are summarized in the
+%[- MARK -] +following diagram:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + list of:
+%[- MARK -] ++------+ +---------+
+%[- MARK -] +|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+%[- MARK -] ++------+ | ^ +---------+ | ^ (printed)
+%[- MARK -] + | | | Example | | |
+%[- MARK -] + v | | ... | v |
+%[- MARK -] + DocTestParser | Example | OutputChecker
+%[- MARK -] + +---------+
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{DocTest Objects\label{doctest-DocTest}}
+%[- MARK -] +\begin{classdesc}{DocTest}{examples, globs, name, filename, lineno,
+%[- MARK -] + docstring}
+%[- MARK -] + A collection of doctest examples that should be run in a single
+%[- MARK -] + namespace. The constructor arguments are used to initialize the
+%[- MARK -] + member variables of the same names.
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{DocTest} defines the following member variables. They are
+%[- MARK -] +initialized by the constructor, and should not be modified directly.
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{examples}
+%[- MARK -] + A list of \class{Example} objects encoding the individual
+%[- MARK -] + interactive Python examples that should be run by this test.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{globs}
+%[- MARK -] + The namespace (aka globals) that the examples should be run in.
+%[- MARK -] + This is a dictionary mapping names to values. Any changes to the
+%[- MARK -] + namespace made by the examples (such as binding new variables)
+%[- MARK -] + will be reflected in \member{globs} after the test is run.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{name}
+%[- MARK -] + A string name identifying the \class{DocTest}. Typically, this is
+%[- MARK -] + the name of the object or file that the test was extracted from.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{filename}
+%[- MARK -] + The name of the file that this \class{DocTest} was extracted from;
+%[- MARK -] + or \code{None} if the filename is unknown, or if the
+%[- MARK -] + \class{DocTest} was not extracted from a file.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{lineno}
+%[- MARK -] + The line number within \member{filename} where this
+%[- MARK -] + \class{DocTest} begins, or \code{None} if the line number is
+%[- MARK -] + unavailable. This line number is zero-based with respect to the
+%[- MARK -] + beginning of the file.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{docstring}
+%[- MARK -] + The string that the test was extracted from, or `None` if the
+%[- MARK -] + string is unavailable, or if the test was not extracted from a
+%[- MARK -] + string.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{Example Objects\label{doctest-Example}}
+%[- MARK -] +\begin{classdesc}{Example}{source, want\optional{,
+%[- MARK -] + exc_msg}\optional{, lineno}\optional{,
+%[- MARK -] + indent}\optional{, options}}
+%[- MARK -] + A single interactive example, consisting of a Python statement and
+%[- MARK -] + its expected output. The constructor arguments are used to
+%[- MARK -] + initialize the member variables of the same names.
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{Example} defines the following member variables. They are
+%[- MARK -] +initialized by the constructor, and should not be modified directly.
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{source}
+%[- MARK -] + A string containing the example's source code. This source code
+%[- MARK -] + consists of a single Python statement, and always ends with a
+%[- MARK -] + newline; the constructor adds a newline when necessary.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{want}
+%[- MARK -] + The expected output from running the example's source code (either
+%[- MARK -] + from stdout, or a traceback in case of exception). \member{want}
+%[- MARK -] + ends with a newline unless no output is expected, in which case
+%[- MARK -] + it's an empty string. The constructor adds a newline when
+%[- MARK -] + necessary.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{exc_msg}
+%[- MARK -] + The exception message generated by the example, if the example is
+%[- MARK -] + expected to generate an exception; or \code{None} if it is not
+%[- MARK -] + expected to generate an exception. This exception message is
+%[- MARK -] + compared against the return value of
+%[- MARK -] + \function{traceback.format_exception_only()}. \member{exc_msg}
+%[- MARK -] + ends with a newline unless it's \code{None}. The constructor adds
+%[- MARK -] + a newline if needed.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{lineno}
+%[- MARK -] + The line number within the string containing this example where
+%[- MARK -] + the example begins. This line number is zero-based with respect
+%[- MARK -] + to the beginning of the containing string.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{indent}
+%[- MARK -] + The example's indentation in the containing string, i.e., the
+%[- MARK -] + number of space characters that precede the example's first
+%[- MARK -] + prompt.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{options}
+%[- MARK -] + A dictionary mapping from option flags to \code{True} or
+%[- MARK -] + \code{False}, which is used to override default options for this
+%[- MARK -] + example. Any option flags not contained in this dictionary are
+%[- MARK -] + left at their default value (as specified by the
+%[- MARK -] + \class{DocTestRunner}'s \member{optionflags}).
+%[- MARK -] + By default, no options are set.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{DocTestFinder objects\label{doctest-DocTestFinder}}
+%[- MARK -] +\begin{classdesc}{DocTestFinder}{\optional{verbose}\optional{,
+%[- MARK -] + parser}\optional{, recurse}\optional{,
+%[- MARK -] + exclude_empty}}
+%[- MARK -] + A processing class used to extract the \class{DocTest}s that are
+%[- MARK -] + relevant to a given object, from its docstring and the docstrings
+%[- MARK -] + of its contained objects. \class{DocTest}s can currently be
+%[- MARK -] + extracted from the following object types: modules, functions,
+%[- MARK -] + classes, methods, staticmethods, classmethods, and properties.
+%[- MARK -] +
+%[- MARK -] + The optional argument \var{verbose} can be used to display the
+%[- MARK -] + objects searched by the finder. It defaults to \code{False} (no
+%[- MARK -] + output).
+%[- MARK -] +
+%[- MARK -] + The optional argument \var{parser} specifies the
+%[- MARK -] + \class{DocTestParser} object (or a drop-in replacement) that is
+%[- MARK -] + used to extract doctests from docstrings.
+%[- MARK -] +
+%[- MARK -] + If the optional argument \var{recurse} is false, then
+%[- MARK -] + \method{DocTestFinder.find()} will only examine the given object,
+%[- MARK -] + and not any contained objects.
+%[- MARK -] +
+%[- MARK -] + If the optional argument \var{exclude_empty} is false, then
+%[- MARK -] + \method{DocTestFinder.find()} will include tests for objects with
+%[- MARK -] + empty docstrings.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{DocTestFinder} defines the following method:
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{find}{obj\optional{, name}\optional{,
+%[- MARK -] + module}\optional{, globs}\optional{, extraglobs}}
+%[- MARK -] + Return a list of the \class{DocTest}s that are defined by
+%[- MARK -] + \var{obj}'s docstring, or by any of its contained objects'
+%[- MARK -] + docstrings.
+%[- MARK -] +
+%[- MARK -] + The optional argument \var{name} specifies the object's name; this
+%[- MARK -] + name will be used to construct names for the returned
+%[- MARK -] + \class{DocTest}s. If \var{name} is not specified, then
+%[- MARK -] + \code{\var{obj}.__name__} is used.
+%[- MARK -] +
+%[- MARK -] + The optional parameter \var{module} is the module that contains
+%[- MARK -] + the given object. If the module is not specified or is None, then
+%[- MARK -] + the test finder will attempt to automatically determine the
+%[- MARK -] + correct module. The object's module is used:
+%[- MARK -] +
+%[- MARK -] + \begin{itemize}
+%[- MARK -] + \item As a default namespace, if \var{globs} is not specified.
+%[- MARK -] + \item To prevent the DocTestFinder from extracting DocTests
+%[- MARK -] + from objects that are imported from other modules. (Contained
+%[- MARK -] + objects with modules other than \var{module} are ignored.)
+%[- MARK -] + \item To find the name of the file containing the object.
+%[- MARK -] + \item To help find the line number of the object within its file.
+%[- MARK -] + \end{itemize}
+%[- MARK -] +
+%[- MARK -] + If \var{module} is \code{False}, no attempt to find the module
+%[- MARK -] + will be made. This is obscure, of use mostly in testing doctest
+%[- MARK -] + itself: if \var{module} is \code{False}, or is \code{None} but
+%[- MARK -] + cannot be found automatically, then all objects are considered to
+%[- MARK -] + belong to the (non-existent) module, so all contained objects will
+%[- MARK -] + (recursively) be searched for doctests.
+%[- MARK -] +
+%[- MARK -] + The globals for each \class{DocTest} is formed by combining
+%[- MARK -] + \var{globs} and \var{extraglobs} (bindings in \var{extraglobs}
+%[- MARK -] + override bindings in \var{globs}). A new shallow copy of the globals
+%[- MARK -] + dictionary is created for each \class{DocTest}. If \var{globs} is
+%[- MARK -] + not specified, then it defaults to the module's \var{__dict__}, if
+%[- MARK -] + specified, or \code{\{\}} otherwise. If \var{extraglobs} is not
+%[- MARK -] + specified, then it defaults to \code{\{\}}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{DocTestParser objects\label{doctest-DocTestParser}}
+%[- MARK -] +\begin{classdesc}{DocTestParser}{}
+%[- MARK -] + A processing class used to extract interactive examples from a
+%[- MARK -] + string, and use them to create a \class{DocTest} object.
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{DocTestParser} defines the following methods:
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{get_doctest}{string, globs, name, filename, lineno}
+%[- MARK -] + Extract all doctest examples from the given string, and collect
+%[- MARK -] + them into a \class{DocTest} object.
+%[- MARK -] +
+%[- MARK -] + \var{globs}, \var{name}, \var{filename}, and \var{lineno} are
+%[- MARK -] + attributes for the new \class{DocTest} object. See the
+%[- MARK -] + documentation for \class{DocTest} for more information.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{get_examples}{string\optional{, name}}
+%[- MARK -] + Extract all doctest examples from the given string, and return
+%[- MARK -] + them as a list of \class{Example} objects. Line numbers are
+%[- MARK -] + 0-based. The optional argument \var{name} is a name identifying
+%[- MARK -] + this string, and is only used for error messages.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{parse}{string\optional{, name}}
+%[- MARK -] + Divide the given string into examples and intervening text, and
+%[- MARK -] + return them as a list of alternating \class{Example}s and strings.
+%[- MARK -] + Line numbers for the \class{Example}s are 0-based. The optional
+%[- MARK -] + argument \var{name} is a name identifying this string, and is only
+%[- MARK -] + used for error messages.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{DocTestRunner objects\label{doctest-DocTestRunner}}
+%[- MARK -] +\begin{classdesc}{DocTestRunner}{\optional{checker}\optional{,
+%[- MARK -] + verbose}\optional{, optionflags}}
+%[- MARK -] + A processing class used to execute and verify the interactive
+%[- MARK -] + examples in a \class{DocTest}.
+%[- MARK -] +
+%[- MARK -] + The comparison between expected outputs and actual outputs is done
+%[- MARK -] + by an \class{OutputChecker}. This comparison may be customized
+%[- MARK -] + with a number of option flags; see section~\ref{doctest-options}
+%[- MARK -] + for more information. If the option flags are insufficient, then
+%[- MARK -] + the comparison may also be customized by passing a subclass of
+%[- MARK -] + \class{OutputChecker} to the constructor.
+%[- MARK -] +
+%[- MARK -] + The test runner's display output can be controlled in two ways.
+%[- MARK -] + First, an output function can be passed to
+%[- MARK -] + \method{TestRunner.run()}; this function will be called with
+%[- MARK -] + strings that should be displayed. It defaults to
+%[- MARK -] + \code{sys.stdout.write}. If capturing the output is not
+%[- MARK -] + sufficient, then the display output can be also customized by
+%[- MARK -] + subclassing DocTestRunner, and overriding the methods
+%[- MARK -] + \method{report_start}, \method{report_success},
+%[- MARK -] + \method{report_unexpected_exception}, and \method{report_failure}.
+%[- MARK -] +
+%[- MARK -] + The optional keyword argument \var{checker} specifies the
+%[- MARK -] + \class{OutputChecker} object (or drop-in replacement) that should
+%[- MARK -] + be used to compare the expected outputs to the actual outputs of
+%[- MARK -] + doctest examples.
+%[- MARK -] +
+%[- MARK -] + The optional keyword argument \var{verbose} controls the
+%[- MARK -] + \class{DocTestRunner}'s verbosity. If \var{verbose} is
+%[- MARK -] + \code{True}, then information is printed about each example, as it
+%[- MARK -] + is run. If \var{verbose} is \code{False}, then only failures are
+%[- MARK -] + printed. If \var{verbose} is unspecified, or \code{None}, then
+%[- MARK -] + verbose output is used iff the command-line switch \programopt{-v}
+%[- MARK -] + is used.
+%[- MARK -] +
+%[- MARK -] + The optional keyword argument \var{optionflags} can be used to
+%[- MARK -] + control how the test runner compares expected output to actual
+%[- MARK -] + output, and how it displays failures. For more information, see
+%[- MARK -] + section~\ref{doctest-options}.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{DocTestParser} defines the following methods:
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{report_start}{out, test, example}
+%[- MARK -] + Report that the test runner is about to process the given example.
+%[- MARK -] + This method is provided to allow subclasses of
+%[- MARK -] + \class{DocTestRunner} to customize their output; it should not be
+%[- MARK -] + called directly.
+%[- MARK -] +
+%[- MARK -] + \var{example} is the example about to be processed. \var{test} is
+%[- MARK -] + the test containing \var{example}. \var{out} is the output
+%[- MARK -] + function that was passed to \method{DocTestRunner.run()}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{report_success}{out, test, example, got}
+%[- MARK -] + Report that the given example ran successfully. This method is
+%[- MARK -] + provided to allow subclasses of \class{DocTestRunner} to customize
+%[- MARK -] + their output; it should not be called directly.
+%[- MARK -] +
+%[- MARK -] + \var{example} is the example about to be processed. \var{got} is
+%[- MARK -] + the actual output from the example. \var{test} is the test
+%[- MARK -] + containing \var{example}. \var{out} is the output function that
+%[- MARK -] + was passed to \method{DocTestRunner.run()}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{report_failure}{out, test, example, got}
+%[- MARK -] + Report that the given example failed. This method is provided to
+%[- MARK -] + allow subclasses of \class{DocTestRunner} to customize their
+%[- MARK -] + output; it should not be called directly.
+%[- MARK -] +
+%[- MARK -] + \var{example} is the example about to be processed. \var{got} is
+%[- MARK -] + the actual output from the example. \var{test} is the test
+%[- MARK -] + containing \var{example}. \var{out} is the output function that
+%[- MARK -] + was passed to \method{DocTestRunner.run()}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{report_unexpected_exception}{out, test, example, exc_info}
+%[- MARK -] + Report that the given example raised an unexpected exception.
+%[- MARK -] + This method is provided to allow subclasses of
+%[- MARK -] + \class{DocTestRunner} to customize their output; it should not be
+%[- MARK -] + called directly.
+%[- MARK -] +
+%[- MARK -] + \var{example} is the example about to be processed.
+%[- MARK -] + \var{exc_info} is a tuple containing information about the
+%[- MARK -] + unexpected exception (as returned by \function{sys.exc_info()}).
+%[- MARK -] + \var{test} is the test containing \var{example}. \var{out} is the
+%[- MARK -] + output function that was passed to \method{DocTestRunner.run()}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{run}{test\optional{, compileflags}\optional{,
+%[- MARK -] + out}\optional{, clear_globs}}
+%[- MARK -] + Run the examples in \var{test} (a \class{DocTest} object), and
+%[- MARK -] + display the results using the writer function \var{out}.
+%[- MARK -] +
+%[- MARK -] + The examples are run in the namespace \code{test.globs}. If
+%[- MARK -] + \var{clear_globs} is true (the default), then this namespace will
+%[- MARK -] + be cleared after the test runs, to help with garbage collection.
+%[- MARK -] + If you would like to examine the namespace after the test
+%[- MARK -] + completes, then use \var{clear_globs=False}.
+%[- MARK -] +
+%[- MARK -] + \var{compileflags} gives the set of flags that should be used by
+%[- MARK -] + the Python compiler when running the examples. If not specified,
+%[- MARK -] + then it will default to the set of future-import flags that apply
+%[- MARK -] + to \var{globs}.
+%[- MARK -] +
+%[- MARK -] + The output of each example is checked using the
+%[- MARK -] + \class{DocTestRunner}'s output checker, and the results are
+%[- MARK -] + formatted by the \method{DocTestRunner.report_*} methods.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{summarize}{\optional{verbose}}
+%[- MARK -] + Print a summary of all the test cases that have been run by this
+%[- MARK -] + DocTestRunner, and return a tuple \samp{(\var{failure_count},
+%[- MARK -] + \var{test_count})}.
+%[- MARK -] +
+%[- MARK -] + The optional \var{verbose} argument controls how detailed the
+%[- MARK -] + summary is. If the verbosity is not specified, then the
+%[- MARK -] + \class{DocTestRunner}'s verbosity is used.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{OutputChecker objects\label{doctest-OutputChecker}}
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{OutputChecker}{}
+%[- MARK -] + A class used to check the whether the actual output from a doctest
+%[- MARK -] + example matches the expected output. \class{OutputChecker}
+%[- MARK -] + defines two methods: \method{check_output}, which compares a given
+%[- MARK -] + pair of outputs, and returns true if they match; and
+%[- MARK -] + \method{output_difference}, which returns a string describing the
+%[- MARK -] + differences between two outputs.
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\class{OutputChecker} defines the following methods:
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{check_output}{want, got, optionflags}
+%[- MARK -] + Return \code{True} iff the actual output from an example
+%[- MARK -] + (\var{got}) matches the expected output (\var{want}). These
+%[- MARK -] + strings are always considered to match if they are identical; but
+%[- MARK -] + depending on what option flags the test runner is using, several
+%[- MARK -] + non-exact match types are also possible. See
+%[- MARK -] + section~\ref{doctest-options} for more information about option
+%[- MARK -] + flags.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{output_difference}{example, got, optionflags}
+%[- MARK -] + Return a string describing the differences between the expected
+%[- MARK -] + output for a given example (\var{example}) and the actual output
+%[- MARK -] + (\var{got}). \var{optionflags} is the set of option flags used to
+%[- MARK -] + compare \var{want} and \var{got}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsection{Debugging\label{doctest-debugging}}
+%[- MARK -] +
+%[- MARK -] +Doctest provides several mechanisms for debugging doctest examples:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item Several functions convert doctests to executable Python
+%[- MARK -] + programs, which can be run under the Python debugger, \refmodule{pdb}.
+%[- MARK -] +\item The \class{DebugRunner} class is a subclass of
+%[- MARK -] + \class{DocTestRunner} that raises an exception for the first
+%[- MARK -] + failing example, containing information about that example.
+%[- MARK -] + This information can be used to perform post-mortem debugging on
+%[- MARK -] + the example.
+%[- MARK -] +\item The \refmodule{unittest} cases generated by \function{DocTestSuite()}
+%[- MARK -] + support the \method{debug()} method defined by
+%[- MARK -] + \class{\refmodule{unittest}.TestCase}.
+%[- MARK -] +\item You can add a call to \function{\refmodule{pdb}.set_trace()} in a
+%[- MARK -] + doctest example, and you'll drop into the Python debugger when that
+%[- MARK -] + line is executed. Then you can inspect current values of variables,
+%[- MARK -] + and so on. For example, suppose \file{a.py} contains just this
+%[- MARK -] + module docstring:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +"""
+%[- MARK -] +>>> def f(x):
+%[- MARK -] +... g(x*2)
+%[- MARK -] +>>> def g(x):
+%[- MARK -] +... print x+3
+%[- MARK -] +... import pdb; pdb.set_trace()
+%[- MARK -] +>>> f(3)
+%[- MARK -] +9
+%[- MARK -] +"""
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + Then an interactive Python session may look like this:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> import a, doctest
+%[- MARK -] +>>> doctest.testmod(a)
+%[- MARK -] +--Return--
+%[- MARK -] +> <doctest a[1]>(3)g()->None
+%[- MARK -] +-> import pdb; pdb.set_trace()
+%[- MARK -] +(Pdb) list
+%[- MARK -] + 1 def g(x):
+%[- MARK -] + 2 print x+3
+%[- MARK -] + 3 -> import pdb; pdb.set_trace()
+%[- MARK -] +[EOF]
+%[- MARK -] +(Pdb) print x
+%[- MARK -] +6
+%[- MARK -] +(Pdb) step
+%[- MARK -] +--Return--
+%[- MARK -] +> <doctest a[0]>(2)f()->None
+%[- MARK -] +-> g(x*2)
+%[- MARK -] +(Pdb) list
+%[- MARK -] + 1 def f(x):
+%[- MARK -] + 2 -> g(x*2)
+%[- MARK -] +[EOF]
+%[- MARK -] +(Pdb) print x
+%[- MARK -] +3
+%[- MARK -] +(Pdb) step
+%[- MARK -] +--Return--
+%[- MARK -] +> <doctest a[2]>(1)?()->None
+%[- MARK -] +-> f(3)
+%[- MARK -] +(Pdb) cont
+%[- MARK -] +(0, 3)
+%[- MARK -] +>>>
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[The ability to use \code{\refmodule{pdb}.set_trace()}
+%[- MARK -] + usefully inside doctests was added]{2.4}
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Functions that convert doctests to Python code, and possibly run
+%[- MARK -] +the synthesized code under the debugger:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{script_from_examples}{s}
+%[- MARK -] + Convert text with examples to a script.
+%[- MARK -] +
+%[- MARK -] + Argument \var{s} is a string containing doctest examples. The string
+%[- MARK -] + is converted to a Python script, where doctest examples in \var{s}
+%[- MARK -] + are converted to regular code, and everything else is converted to
+%[- MARK -] + Python comments. The generated script is returned as a string.
+%[- MARK -] + For example,
+%[- MARK -] +
+%[- MARK -] + \begin{verbatim}
+%[- MARK -] + import doctest
+%[- MARK -] + print doctest.script_from_examples(r"""
+%[- MARK -] + Set x and y to 1 and 2.
+%[- MARK -] + >>> x, y = 1, 2
+%[- MARK -] +
+%[- MARK -] + Print their sum:
+%[- MARK -] + >>> print x+y
+%[- MARK -] + 3
+%[- MARK -] + """)
+%[- MARK -] + \end{verbatim}
+%[- MARK -] +
+%[- MARK -] + displays:
+%[- MARK -] +
+%[- MARK -] + \begin{verbatim}
+%[- MARK -] + # Set x and y to 1 and 2.
+%[- MARK -] + x, y = 1, 2
+%[- MARK -] + #
+%[- MARK -] + # Print their sum:
+%[- MARK -] + print x+y
+%[- MARK -] + # Expected:
+%[- MARK -] + ## 3
+%[- MARK -] + \end{verbatim}
+%[- MARK -] +
+%[- MARK -] + This function is used internally by other functions (see below), but
+%[- MARK -] + can also be useful when you want to transform an interactive Python
+%[- MARK -] + session into a Python script.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{testsource}{module, name}
+%[- MARK -] + Convert the doctest for an object to a script.
+%[- MARK -] +
+%[- MARK -] + Argument \var{module} is a module object, or dotted name of a module,
+%[- MARK -] + containing the object whose doctests are of interest. Argument
+%[- MARK -] + \var{name} is the name (within the module) of the object with the
+%[- MARK -] + doctests of interest. The result is a string, containing the
+%[- MARK -] + object's docstring converted to a Python script, as described for
+%[- MARK -] + \function{script_from_examples()} above. For example, if module
+%[- MARK -] + \file{a.py} contains a top-level function \function{f()}, then
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import a, doctest
+%[- MARK -] +print doctest.testsource(a, "a.f")
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + prints a script version of function \function{f()}'s docstring,
+%[- MARK -] + with doctests converted to code, and the rest placed in comments.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.3}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{debug}{module, name\optional{, pm}}
+%[- MARK -] + Debug the doctests for an object.
+%[- MARK -] +
+%[- MARK -] + The \var{module} and \var{name} arguments are the same as for function
+%[- MARK -] + \function{testsource()} above. The synthesized Python script for the
+%[- MARK -] + named object's docstring is written to a temporary file, and then that
+%[- MARK -] + file is run under the control of the Python debugger, \refmodule{pdb}.
+%[- MARK -] +
+%[- MARK -] + A shallow copy of \code{\var{module}.__dict__} is used for both local
+%[- MARK -] + and global execution context.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{pm} controls whether post-mortem debugging is
+%[- MARK -] + used. If \var{pm} has a true value, the script file is run directly, and
+%[- MARK -] + the debugger gets involved only if the script terminates via raising an
+%[- MARK -] + unhandled exception. If it does, then post-mortem debugging is invoked,
+%[- MARK -] + via \code{\refmodule{pdb}.post_mortem()}, passing the traceback object
+%[- MARK -] + from the unhandled exception. If \var{pm} is not specified, or is false,
+%[- MARK -] + the script is run under the debugger from the start, via passing an
+%[- MARK -] + appropriate \function{execfile()} call to \code{\refmodule{pdb}.run()}.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.3}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[The \var{pm} argument was added]{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{debug_src}{src\optional{, pm}\optional{, globs}}
+%[- MARK -] + Debug the doctests in a string.
+%[- MARK -] +
+%[- MARK -] + This is like function \function{debug()} above, except that
+%[- MARK -] + a string containing doctest examples is specified directly, via
+%[- MARK -] + the \var{src} argument.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{pm} has the same meaning as in function
+%[- MARK -] + \function{debug()} above.
+%[- MARK -] +
+%[- MARK -] + Optional argument \var{globs} gives a dictionary to use as both
+%[- MARK -] + local and global execution context. If not specified, or \code{None},
+%[- MARK -] + an empty dictionary is used. If specified, a shallow copy of the
+%[- MARK -] + dictionary is used.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +The \class{DebugRunner} class, and the special exceptions it may raise,
+%[- MARK -] +are of most interest to testing framework authors, and will only be
+%[- MARK -] +sketched here. See the source code, and especially \class{DebugRunner}'s
+%[- MARK -] +docstring (which is a doctest!) for more details:
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{DebugRunner}{\optional{checker}\optional{,
+%[- MARK -] + verbose}\optional{, optionflags}}
+%[- MARK -] +
+%[- MARK -] + A subclass of \class{DocTestRunner} that raises an exception as
+%[- MARK -] + soon as a failure is encountered. If an unexpected exception
+%[- MARK -] + occurs, an \exception{UnexpectedException} exception is raised,
+%[- MARK -] + containing the test, the example, and the original exception. If
+%[- MARK -] + the output doesn't match, then a \exception{DocTestFailure}
+%[- MARK -] + exception is raised, containing the test, the example, and the
+%[- MARK -] + actual output.
+%[- MARK -] +
+%[- MARK -] + For information about the constructor parameters and methods, see
+%[- MARK -] + the documentation for \class{DocTestRunner} in
+%[- MARK -] + section~\ref{doctest-advanced-api}.
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +There are two exceptions that may be raised by \class{DebugRunner}
+%[- MARK -] +instances:
+%[- MARK -] +
+%[- MARK -] +\begin{excclassdesc}{DocTestFailure}{test, example, got}
+%[- MARK -] + An exception thrown by \class{DocTestRunner} to signal that a
+%[- MARK -] + doctest example's actual output did not match its expected output.
+%[- MARK -] + The constructor arguments are used to initialize the member
+%[- MARK -] + variables of the same names.
+%[- MARK -] +\end{excclassdesc}
+%[- MARK -] +\exception{DocTestFailure} defines the following member variables:
+%[- MARK -] +\begin{memberdesc}{test}
+%[- MARK -] + The \class{DocTest} object that was being run when the example failed.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +\begin{memberdesc}{example}
+%[- MARK -] + The \class{Example} that failed.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +\begin{memberdesc}{got}
+%[- MARK -] + The example's actual output.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{excclassdesc}{UnexpectedException}{test, example, exc_info}
+%[- MARK -] + An exception thrown by \class{DocTestRunner} to signal that a
+%[- MARK -] + doctest example raised an unexpected exception. The constructor
+%[- MARK -] + arguments are used to initialize the member variables of the same
+%[- MARK -] + names.
+%[- MARK -] +\end{excclassdesc}
+%[- MARK -] +\exception{UnexpectedException} defines the following member variables:
+%[- MARK -] +\begin{memberdesc}{test}
+%[- MARK -] + The \class{DocTest} object that was being run when the example failed.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +\begin{memberdesc}{example}
+%[- MARK -] + The \class{Example} that failed.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +\begin{memberdesc}{exc_info}
+%[- MARK -] + A tuple containing information about the unexpected exception, as
+%[- MARK -] + returned by \function{sys.exc_info()}.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\subsection{Soapbox\label{doctest-soapbox}}
+%[- MARK -] +
+%[- MARK -] +As mentioned in the introduction, \refmodule{doctest} has grown to have
+%[- MARK -] +three primary uses:
+%[- MARK -] +
+%[- MARK -] +\begin{enumerate}
+%[- MARK -] +\item Checking examples in docstrings.
+%[- MARK -] +\item Regression testing.
+%[- MARK -] +\item Executable documentation / literate testing.
+%[- MARK -] +\end{enumerate}
+%[- MARK -] +
+%[- MARK -] +These uses have different requirements, and it is important to
+%[- MARK -] +distinguish them. In particular, filling your docstrings with obscure
+%[- MARK -] +test cases makes for bad documentation.
+%[- MARK -] +
+%[- MARK -] +When writing a docstring, choose docstring examples with care.
+%[- MARK -] +There's an art to this that needs to be learned---it may not be
+%[- MARK -] +natural at first. Examples should add genuine value to the
+%[- MARK -] +documentation. A good example can often be worth many words.
+%[- MARK -] If done with care, the examples will be invaluable for your users, and
+%[- MARK -] will pay back the time it takes to collect them many times over as the
+%[- MARK -] years go by and things change. I'm still amazed at how often one of
+%[- MARK -] -my \refmodule{doctest} examples stops working after a ``harmless''
+%[- MARK -] +my \refmodule{doctest} examples stops working after a "harmless"
+%[- MARK -] change.
+%[- MARK -]
+%[- MARK -] -For exhaustive testing, or testing boring cases that add no value to the
+%[- MARK -] -docs, define a \code{__test__} dict instead. That's what it's for.
+%[- MARK -] +Doctest also makes an excellent tool for regression testing, especially if
+%[- MARK -] +you don't skimp on explanatory text. By interleaving prose and examples,
+%[- MARK -] +it becomes much easier to keep track of what's actually being tested, and
+%[- MARK -] +why. When a test fails, good prose can make it much easier to figure out
+%[- MARK -] +what the problem is, and how it should be fixed. It's true that you could
+%[- MARK -] +write extensive comments in code-based testing, but few programmers do.
+%[- MARK -] +Many have found that using doctest approaches instead leads to much clearer
+%[- MARK -] +tests. Perhaps this is simply because doctest makes writing prose a little
+%[- MARK -] +easier than writing code, while writing comments in code is a little
+%[- MARK -] +harder. I think it goes deeper than just that: the natural attitude
+%[- MARK -] +when writing a doctest-based test is that you want to explain the fine
+%[- MARK -] +points of your software, and illustrate them with examples. This in
+%[- MARK -] +turn naturally leads to test files that start with the simplest features,
+%[- MARK -] +and logically progress to complications and edge cases. A coherent
+%[- MARK -] +narrative is the result, instead of a collection of isolated functions
+%[- MARK -] +that test isolated bits of functionality seemingly at random. It's
+%[- MARK -] +a different attitude, and produces different results, blurring the
+%[- MARK -] +distinction between testing and explaining.
+%[- MARK -] +
+%[- MARK -] +Regression testing is best confined to dedicated objects or files. There
+%[- MARK -] +are several options for organizing tests:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item Write text files containing test cases as interactive examples,
+%[- MARK -] + and test the files using \function{testfile()} or
+%[- MARK -] + \function{DocFileSuite()}. This is recommended, although is
+%[- MARK -] + easiest to do for new projects, designed from the start to use
+%[- MARK -] + doctest.
+%[- MARK -] +\item Define functions named \code{_regrtest_\textit{topic}} that
+%[- MARK -] + consist of single docstrings, containing test cases for the
+%[- MARK -] + named topics. These functions can be included in the same file
+%[- MARK -] + as the module, or separated out into a separate test file.
+%[- MARK -] +\item Define a \code{__test__} dictionary mapping from regression test
+%[- MARK -] + topics to docstrings containing test cases.
+%[- MARK -] +\end{itemize}
+%[- MARK -] END DIFF
indicate per la documentazione.
\item Fate attenzione se avete del codice da eseguire una sola volta.
Modified: python/python/Doc/branches/2.4.3/lib/libexcs.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libexcs.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libexcs.tex Fri Jun 2 12:52:55 2006
@@ -302,6 +302,21 @@
Questo può verificarsi nell'istruzione \keyword{import}, in
un'istruzione \keyword{exec}, in una chiamata alle funzioni built-in
\function{eval()} o \function{input()}, o nella lettura dello script
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 276
+%[- MARK -] an \keyword{import} statement, in an \keyword{exec} statement, in a call
+%[- MARK -] to the built-in function \function{eval()} or \function{input()}, or
+%[- MARK -] when reading the initial script or standard input (also
+%[- MARK -] interactively).
+%[- MARK -]
+%[- MARK -] - Instances of this class have atttributes \member{filename},
+%[- MARK -] + Instances of this class have attributes \member{filename},
+%[- MARK -] \member{lineno}, \member{offset} and \member{text} for easier access
+%[- MARK -] to the details. \function{str()} of the exception instance returns
+%[- MARK -] only the message.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
iniziale o dello standard input (anche interattivamente).
Istanze di questa classe hanno attributi \member{filename},
@@ -452,6 +467,19 @@
semantica in futuro.
\end{excdesc}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 458
+%[- MARK -] +---Warning
+%[- MARK -] +-- UserWarning
+%[- MARK -] +-- DeprecationWarning
+%[- MARK -] +-- PendingDeprecationWarning
+%[- MARK -] +-- SyntaxWarning
+%[- MARK -] - +-- OverflowWarning
+%[- MARK -] + +-- OverflowWarning (not generated in 2.4; won't exist in 2.5)
+%[- MARK -] +-- RuntimeWarning
+%[- MARK -] +-- FutureWarning
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
La gerarchia delle classi per le eccezioni built-in è:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libfcntl.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libfcntl.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libfcntl.tex Fri Jun 2 12:52:55 2006
@@ -111,6 +111,21 @@
accettati). Per i dettagli, vedete la pagina di manuale \UNIX{}
\manpage{flock(3)}. Su alcuni sistemi questa funzione viene emulata
tramite \cfunction{fcntl()}.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 106
+%[- MARK -] See the \UNIX{} manual \manpage{flock}{3} for details. (On some
+%[- MARK -] systems, this function is emulated using \cfunction{fcntl()}.)
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{lockf}{fd, operation,
+%[- MARK -] - \optional{len, \optional{start, \optional{whence}}}}
+%[- MARK -] + \optional{length, \optional{start, \optional{whence}}}}
+%[- MARK -] This is essentially a wrapper around the \function{fcntl()} locking
+%[- MARK -] calls. \var{fd} is the file descriptor of the file to lock or unlock,
+%[- MARK -] and \var{operation} is one of the following values:
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{lockf}{fd, operation,
@@ -155,6 +170,30 @@
valore predefinito per \var{whence} è \code{0}.
\end{funcdesc}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 149
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] Examples (all on a SVR4 compliant system):
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -import struct, fcntl
+%[- MARK -] +import struct, fcntl, os
+%[- MARK -]
+%[- MARK -] -file = open(...)
+%[- MARK -] -rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
+%[- MARK -] +f = open(...)
+%[- MARK -] +rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
+%[- MARK -]
+%[- MARK -] lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
+%[- MARK -] -rv = fcntl.fcntl(file, fcntl.F_SETLKW, lockdata)
+%[- MARK -] +rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] Note that in the first example the return value variable \var{rv} will
+%[- MARK -] hold an integer value; in the second example it will hold a string
+%[- MARK -] value. The structure lay-out for the \var{lockdata} variable is
+%[- MARK -] END DIFF
Esempi (tutti su sistemi compatibili con SVR4):
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libfilecmp.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libfilecmp.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libfilecmp.tex Fri Jun 2 12:52:55 2006
@@ -79,6 +79,37 @@
\begin{methoddesc}[dircmp]{report}{}
Stampa (su \code{sys.stdout}) il risultato del confronto tra le
directory \var{a} e \var{b}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 69
+%[- MARK -] Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[dircmp]{report_partial_closure}{}
+%[- MARK -] Print a comparison between \var{a} and \var{b} and common immediate
+%[- MARK -] -subdirctories.
+%[- MARK -] +subdirectories.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[dircmp]{report_full_closure}{}
+%[- MARK -] Print a comparison between \var{a} and \var{b} and common
+%[- MARK -] -subdirctories (recursively).
+%[- MARK -] +subdirectories (recursively).
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] The \class{dircmp} offers a number of interesting attributes that may
+%[- MARK -] be used to get various bits of information about the directory trees
+%[- MARK -] being compared.
+%[- MARK -]
+%[- MARK -] Note that via \method{__getattr__()} hooks, all attributes are
+%[- MARK -] -computed lazilly, so there is no speed penalty if only those
+%[- MARK -] +computed lazily, so there is no speed penalty if only those
+%[- MARK -] attributes which are lightweight to compute are used.
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[dircmp]{left_list}
+%[- MARK -] Files and subdirectories in \var{a}, filtered by \var{hide} and
+%[- MARK -] \var{ignore}.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[dircmp]{report_partial_closure}{}
Modified: python/python/Doc/branches/2.4.3/lib/libfuture.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libfuture.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libfuture.tex Fri Jun 2 12:52:55 2006
@@ -65,6 +65,18 @@
Le istanze di classe \class{_Feature} possiedono due metodi
corrispondenti, \method{getOptionalRelease()} e
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 62
+%[- MARK -] \method{getOptionalRelease()} and \method{getMandatoryRelease()}.
+%[- MARK -]
+%[- MARK -] \var{CompilerFlag} is the (bitfield) flag that should be passed in the
+%[- MARK -] fourth argument to the builtin function \function{compile()} to enable
+%[- MARK -] the feature in dynamically compiled code. This flag is stored in the
+%[- MARK -] -\member{compiler_flag} attribute on \class{_Future} instances.
+%[- MARK -] +\member{compiler_flag} attribute on \class{_Feature} instances.
+%[- MARK -]
+%[- MARK -] No feature description will ever be deleted from \module{__future__}.
+%[- MARK -] END DIFF
\method{getMandatoryRelease()}.
\var{CompilerFlag} è l'opzione (campo di bit) che dovrebbe venire
Modified: python/python/Doc/branches/2.4.3/lib/libgc.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libgc.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libgc.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,36 @@
\declaremodule{extension}{gc}
\modulesynopsis{Interfaccia per il rilevatore ciclico garbage collector.}
\moduleauthor{Neil Schemenauer}{nas a arctrix.com}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 4
+%[- MARK -] \declaremodule{extension}{gc}
+%[- MARK -] \modulesynopsis{Interface to the cycle-detecting garbage collector.}
+%[- MARK -] \moduleauthor{Neil Schemenauer}{nas a arctrix.com}
+%[- MARK -] \sectionauthor{Neil Schemenauer}{nas a arctrix.com}
+%[- MARK -]
+%[- MARK -] -The \module{gc} module is only available if the interpreter was built
+%[- MARK -] -with the optional cyclic garbage detector (enabled by default). If
+%[- MARK -] -this was not enabled, an \exception{ImportError} is raised by attempts
+%[- MARK -] -to import this module.
+%[- MARK -] -
+%[- MARK -] This module provides an interface to the optional garbage collector. It
+%[- MARK -] provides the ability to disable the collector, tune the collection
+%[- MARK -] frequency, and set debugging options. It also provides access to
+%[- MARK -] unreachable objects that the collector found but cannot free. Since the
+%[- MARK -] collector supplements the reference counting already used in Python, you
+%[- MARK -] can disable the collector if you are sure your program does not create
+%[- MARK -] reference cycles. Automatic collection can be disabled by calling
+%[- MARK -] \code{gc.disable()}. To debug a leaking program call
+%[- MARK -] -\code{gc.set_debug(gc.DEBUG_LEAK)}.
+%[- MARK -] +\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes
+%[- MARK -] +\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be
+%[- MARK -] +saved in gc.garbage for inspection.
+%[- MARK -]
+%[- MARK -] The \module{gc} module provides the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{enable}{}
+%[- MARK -] Enable automatic garbage collection.
+%[- MARK -] END DIFF
\sectionauthor{Neil Schemenauer}{nas a arctrix.com}
Il modulo \module{gc} è disponibile solo se l'interprete viene compilato
Modified: python/python/Doc/branches/2.4.3/lib/libgdbm.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libgdbm.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libgdbm.tex Fri Jun 2 12:52:55 2006
@@ -37,6 +37,21 @@
\code{'n'} (che crea sempre un nuovo database vuoto).
I seguenti caratteri addizionali possono essere inseriti a seguito
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 38
+%[- MARK -] The following additional characters may be appended to the flag to
+%[- MARK -] control how the database is opened:
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -] \item \code{'f'} --- Open the database in fast mode. Writes to the database
+%[- MARK -] - will not be syncronized.
+%[- MARK -] + will not be synchronized.
+%[- MARK -] \item \code{'s'} --- Synchronized mode. This will cause changes to the database
+%[- MARK -] will be immediately written to the file.
+%[- MARK -] \item \code{'u'} --- Do not lock database.
+%[- MARK -] \end{itemize}
+%[- MARK -]
+%[- MARK -] END DIFF
dell'opzione per controllare in che modo il database venga aperto:
\begin{itemize}
Modified: python/python/Doc/branches/2.4.3/lib/libgetopt.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libgetopt.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libgetopt.tex Fri Jun 2 12:52:55 2006
@@ -27,6 +27,21 @@
\note{Diversamente dal \cfunction{getopt()} GNU, dopo un argomento
non-opzione, anche i successivi argomenti vengono considerati come
non-opzioni. Questo comportamento è simile al modo in cui operano i
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 35
+%[- MARK -] name. Long options which require an argument should be followed by an
+%[- MARK -] equal sign (\character{=}). To accept only long options,
+%[- MARK -] \var{options} should be an empty string. Long options on the command
+%[- MARK -] line can be recognized so long as they provide a prefix of the option
+%[- MARK -] name that matches exactly one of the accepted options. For example,
+%[- MARK -] -it \var{long_options} is \code{['foo', 'frob']}, the option
+%[- MARK -] +if \var{long_options} is \code{['foo', 'frob']}, the option
+%[- MARK -] \longprogramopt{fo} will match as \longprogramopt{foo}, but
+%[- MARK -] \longprogramopt{f} will not match uniquely, so \exception{GetoptError}
+%[- MARK -] will be raised.
+%[- MARK -]
+%[- MARK -] The return value consists of two elements: the first is a list of
+%[- MARK -] END DIFF
sistemi \UNIX{} non-GNU.}
\var{long_options}, se specificato, deve essere una lista di stringhe
@@ -63,6 +78,21 @@
Questo significa che gli argomenti di opzione e di non-opzione possono
venire mescolati tra loro. La funzione \function{getopt()} ferma
l'elaborazione delle opzioni non appena viene incontrato un argomento di
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 63
+%[- MARK -] encountered.
+%[- MARK -]
+%[- MARK -] If the first character of the option string is `+', or if the
+%[- MARK -] environment variable POSIXLY_CORRECT is set, then option processing
+%[- MARK -] stops as soon as a non-option argument is encountered.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{GetoptError}
+%[- MARK -] This is raised when an unrecognized option is found in the argument
+%[- MARK -] list or when an option requiring an argument is given none.
+%[- MARK -] END DIFF
non-opzione.
Se il primo carattere dell'opzione stringa è `+', o se la variabile
Modified: python/python/Doc/branches/2.4.3/lib/libgettext.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libgettext.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libgettext.tex Fri Jun 2 12:52:55 2006
@@ -51,6 +51,27 @@
Per questo motivo, è sempre meglio chiamare
\function{bindtextdomain()} con il suo percorso assoluto,
all'inizio della vostra applicazione.}
+%[- MARK -] BEGIN DIFF 001 of 15
+%[- MARK -] @@ 49
+%[- MARK -] For this reason, it is always best to call
+%[- MARK -] \function{bindtextdomain()} with an explicit absolute path at
+%[- MARK -] the start of your application.}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{bind_textdomain_codeset}{domain\optional{, codeset}}
+%[- MARK -] +Bind the \var{domain} to \var{codeset}, changing the encoding of
+%[- MARK -] +strings returned by the \function{gettext()} family of functions.
+%[- MARK -] +If \var{codeset} is omitted, then the current binding is returned.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{textdomain}{\optional{domain}}
+%[- MARK -] Change or query the current global domain. If \var{domain} is
+%[- MARK -] \code{None}, then the current global domain is returned, otherwise the
+%[- MARK -] global domain is set to \var{domain}, which is returned.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{textdomain}{\optional{domain}}
@@ -65,6 +86,40 @@
localizzazione.
Questa funzione viene di solito usata come \function{_} nello spazio dei
nomi locale (vedete gli esempi a seguito).
+%[- MARK -] BEGIN DIFF 002 of 15
+%[- MARK -] @@ 62
+%[- MARK -] current global domain, language, and locale directory. This function
+%[- MARK -] is usually aliased as \function{_} in the local namespace (see
+%[- MARK -] examples below).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{lgettext}{message}
+%[- MARK -] +Equivalent to \function{gettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \function{bind_textdomain_codeset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{dgettext}{domain, message}
+%[- MARK -] Like \function{gettext()}, but look the message up in the specified
+%[- MARK -] \var{domain}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{ldgettext}{domain, message}
+%[- MARK -] +Equivalent to \function{dgettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \function{bind_textdomain_codeset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{ngettext}{singular, plural, n}
+%[- MARK -]
+%[- MARK -] Like \function{gettext()}, but consider plural forms. If a translation
+%[- MARK -] is found, apply the plural formula to \var{n}, and return the
+%[- MARK -] resulting message (some languages have more than two plural forms).
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{dgettext}{domain, message}
@@ -89,6 +144,43 @@
\versionadded{2.3}
+%[- MARK -] BEGIN DIFF 003 of 15
+%[- MARK -] @@ 85
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -]
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{lngettext}{singular, plural, n}
+%[- MARK -] +Equivalent to \function{ngettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \function{bind_textdomain_codeset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{dngettext}{domain, singular, plural, n}
+%[- MARK -] Like \function{ngettext()}, but look the message up in the specified
+%[- MARK -] \var{domain}.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{ldngettext}{domain, singular, plural, n}
+%[- MARK -] +Equivalent to \function{dngettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \function{bind_textdomain_codeset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] Note that GNU \program{gettext} also defines a \function{dcgettext()}
+%[- MARK -] method, but this was deemed not useful and so it is currently
+%[- MARK -] unimplemented.
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{dngettext}{domain, singular, plural, n}
@@ -114,6 +206,23 @@
print _('This is a translatable string.')
\end{verbatim}
+%[- MARK -] BEGIN DIFF 004 of 15
+%[- MARK -] @@ 116
+%[- MARK -] flexibility and greater convenience than the GNU \program{gettext}
+%[- MARK -] API. It is the recommended way of localizing your Python applications and
+%[- MARK -] modules. \module{gettext} defines a ``translations'' class which
+%[- MARK -] implements the parsing of GNU \file{.mo} format files, and has methods
+%[- MARK -] for returning either standard 8-bit strings or Unicode strings.
+%[- MARK -] -Translations instances can also install themselves in the built-in
+%[- MARK -] -namespace as the function \function{_()}.
+%[- MARK -] +Instances of this ``translations'' class can also install themselves
+%[- MARK -] +in the built-in namespace as the function \function{_()}.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{find}{domain\optional{, localedir\optional{,
+%[- MARK -] languages\optional{, all}}}}
+%[- MARK -] This function implements the standard \file{.mo} file search
+%[- MARK -] algorithm. It takes a \var{domain}, identical to what
+%[- MARK -] END DIFF
\subsection{Classe basata su API}
La classe basata su API del modulo \module{gettext} vi dà maggiore
@@ -156,6 +265,58 @@
viene passato \var{all}, viene restituito un elenco di tutti i nomi
dei file, nell'ordine del quale compare la lista dei linguaggi o delle
variabili d'ambiente.
+%[- MARK -] BEGIN DIFF 005 of 15
+%[- MARK -] @@ 150
+%[- MARK -] is given, it returns a list of all file names, in the order in which
+%[- MARK -] they appear in the languages list or the environment variables.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
+%[- MARK -] - languages\optional{,
+%[- MARK -] - class_,\optional{fallback}}}}}
+%[- MARK -] + languages\optional{, class_\optional{,
+%[- MARK -] + fallback\optional{, codeset}}}}}}
+%[- MARK -] Return a \class{Translations} instance based on the \var{domain},
+%[- MARK -] \var{localedir}, and \var{languages}, which are first passed to
+%[- MARK -] \function{find()} to get a list of the
+%[- MARK -] associated \file{.mo} file paths. Instances with
+%[- MARK -] identical \file{.mo} file names are cached. The actual class instantiated
+%[- MARK -] is either \var{class_} if provided, otherwise
+%[- MARK -] \class{GNUTranslations}. The class's constructor must take a single
+%[- MARK -] -file object argument.
+%[- MARK -] +file object argument. If provided, \var{codeset} will change the
+%[- MARK -] +charset used to encode translated strings.
+%[- MARK -]
+%[- MARK -] If multiple files are found, later files are used as fallbacks for
+%[- MARK -] earlier ones. To allow setting the fallback, \function{copy.copy}
+%[- MARK -] is used to clone each translation object from the cache; the actual
+%[- MARK -] instance data is still shared with the cache.
+%[- MARK -]
+%[- MARK -] If no \file{.mo} file is found, this function raises
+%[- MARK -] \exception{IOError} if \var{fallback} is false (which is the default),
+%[- MARK -] and returns a \class{NullTranslations} instance if \var{fallback} is
+%[- MARK -] true.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[Added the \var{codeset} parameter]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode}}}
+%[- MARK -] +\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode
+%[- MARK -] + \optional{, codeset}}}}
+%[- MARK -] This installs the function \function{_} in Python's builtin namespace,
+%[- MARK -] -based on \var{domain}, and \var{localedir} which are passed to the
+%[- MARK -] -function \function{translation()}. The \var{unicode} flag is passed to
+%[- MARK -] -the resulting translation object's \method{install} method.
+%[- MARK -] +based on \var{domain}, \var{localedir}, and \var{codeset} which are
+%[- MARK -] +passed to the function \function{translation()}. The \var{unicode}
+%[- MARK -] +flag is passed to the resulting translation object's \method{install}
+%[- MARK -] +method.
+%[- MARK -]
+%[- MARK -] As seen below, you usually mark the strings in your application that are
+%[- MARK -] candidates for translation, by wrapping them in a call to the
+%[- MARK -] \function{_()} function, like this:
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
@@ -195,6 +356,21 @@
\begin{verbatim}
print _('Questa stringa deve essere tradotta.')
+%[- MARK -] BEGIN DIFF 006 of 15
+%[- MARK -] @@ 189
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] For convenience, you want the \function{_()} function to be installed in
+%[- MARK -] Python's builtin namespace, so it is easily accessible in all modules
+%[- MARK -] of your application.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[Added the \var{codeset} parameter]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \subsubsection{The \class{NullTranslations} class}
+%[- MARK -] Translation classes are what actually implement the translation of
+%[- MARK -] original source file message strings to translated message strings.
+%[- MARK -] END DIFF
\end{verbatim}
Per comodità, vorrete che la funzione \function{_()} venga installata
@@ -232,6 +408,56 @@
Aggiunge \var{fallback} come oggetto restituito per il corrente
oggetto traduzione. Un oggetto traduzione dovrebbe consultare il
fallback se esso non fornisce una traduzione per il messaggio fornito.
+%[- MARK -] BEGIN DIFF 007 of 15
+%[- MARK -] @@ 221
+%[- MARK -] object. A translation object should consult the fallback if it cannot
+%[- MARK -] provide a translation for a given message.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[NullTranslations]{gettext}{message}
+%[- MARK -] -If a fallback has been set, forward \method{gettext} to the fallback.
+%[- MARK -] +If a fallback has been set, forward \method{gettext()} to the fallback.
+%[- MARK -] +Otherwise, return the translated message. Overridden in derived classes.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[NullTranslations]{lgettext}{message}
+%[- MARK -] +If a fallback has been set, forward \method{lgettext()} to the fallback.
+%[- MARK -] Otherwise, return the translated message. Overridden in derived classes.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[NullTranslations]{ugettext}{message}
+%[- MARK -] -If a fallback has been set, forward \method{ugettext} to the fallback.
+%[- MARK -] +If a fallback has been set, forward \method{ugettext()} to the fallback.
+%[- MARK -] Otherwise, return the translated message as a Unicode string.
+%[- MARK -] Overridden in derived classes.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
+%[- MARK -] -If a fallback has been set, forward \method{ngettext} to the fallback.
+%[- MARK -] +If a fallback has been set, forward \method{ngettext()} to the fallback.
+%[- MARK -] Otherwise, return the translated message. Overridden in derived classes.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n}
+%[- MARK -] +If a fallback has been set, forward \method{ngettext()} to the fallback.
+%[- MARK -] +Otherwise, return the translated message. Overridden in derived classes.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
+%[- MARK -] -If a fallback has been set, forward \method{ungettext} to the fallback.
+%[- MARK -] +If a fallback has been set, forward \method{ungettext()} to the fallback.
+%[- MARK -] Otherwise, return the translated message as a Unicode string.
+%[- MARK -] Overridden in derived classes.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{gettext}{message}
@@ -268,6 +494,33 @@
\begin{methoddesc}[NullTranslations]{charset}{}
Restituisce la variabile ``protetta'' \member{_charset}.
+%[- MARK -] BEGIN DIFF 008 of 15
+%[- MARK -] @@ 254
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[NullTranslations]{charset}{}
+%[- MARK -] Return the ``protected'' \member{_charset} variable.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[NullTranslations]{output_charset}{}
+%[- MARK -] +Return the ``protected'' \member{_output_charset} variable, which
+%[- MARK -] +defines the encoding used to return translated messages.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[NullTranslations]{set_output_charset}{charset}
+%[- MARK -] +Change the ``protected'' \member{_output_charset} variable, which
+%[- MARK -] +defines the encoding used to return translated messages.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
+%[- MARK -] If the \var{unicode} flag is false, this method installs
+%[- MARK -] \method{self.gettext()} into the built-in namespace, binding it to
+%[- MARK -] \samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
+%[- MARK -] instead. By default, \var{unicode} is false.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[NullTranslations]{install}{\optional{unicode}}
@@ -343,6 +596,27 @@
stato impostato un fallback, la ricerca viene trasmessa al metodo
fallback di \method{gettext()}. Altrimenti viene restituito l'id di
\var{message}.
+%[- MARK -] BEGIN DIFF 009 of 15
+%[- MARK -] @@ 321
+%[- MARK -] catalog for the \var{message} id, and a fallback has been set, the
+%[- MARK -] look up is forwarded to the fallback's \method{gettext()} method.
+%[- MARK -] Otherwise, the \var{message} id is returned.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[GNUTranslations]{lgettext}{message}
+%[- MARK -] +Equivalent to \method{gettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \method{set_output_charset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}[GNUTranslations]{ugettext}{message}
+%[- MARK -] Look up the \var{message} id in the catalog and return the
+%[- MARK -] corresponding message string, as a Unicode string. If there is no
+%[- MARK -] entry in the catalog for the \var{message} id, and a fallback has been
+%[- MARK -] set, the look up is forwarded to the fallback's \method{ugettext()}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[GNUTranslations]{ugettext}{message}
@@ -367,6 +641,27 @@
restituito \var{plural}.
\versionadded{2.3}
+%[- MARK -] BEGIN DIFF 010 of 15
+%[- MARK -] @@ 344
+%[- MARK -] returned, and \var{plural} is returned in all other cases.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n}
+%[- MARK -] +Equivalent to \method{gettext()}, but the translation is returned
+%[- MARK -] +in the preferred system encoding, if no other encoding was explicitly
+%[- MARK -] +set with \method{set_output_charset()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
+%[- MARK -] Do a plural-forms lookup of a message id. \var{singular} is used as
+%[- MARK -] the message id for purposes of lookup in the catalog, while \var{n} is
+%[- MARK -] used to determine which plural form to use. The returned message
+%[- MARK -] string is a Unicode string.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
@@ -381,6 +676,21 @@
viene restituito \var{singular}, in tutti gli altri casi viene
restituito \var{plural}.
+%[- MARK -] BEGIN DIFF 011 of 15
+%[- MARK -] @@ 363
+%[- MARK -] n = len(os.listdir('.'))
+%[- MARK -] cat = GNUTranslations(somefile)
+%[- MARK -] message = cat.ungettext(
+%[- MARK -] 'There is %(num)d file in this directory',
+%[- MARK -] 'There are %(num)d files in this directory',
+%[- MARK -] - n) % {'n': n}
+%[- MARK -] + n) % {'num': n}
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
Ecco un esempio:
\begin{verbatim}
@@ -519,6 +829,21 @@
Supponiamo che il vostro modulo sia chiamato ``spam'' ed i vari file
\file{.mo} di traduzione naturale del linguaggio risiedano in
\file{/usr/share/locale} e siano nel formato GNU \program{gettext}.
+%[- MARK -] BEGIN DIFF 012 of 15
+%[- MARK -] @@ 493
+%[- MARK -] you would put at the top of your module:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import gettext
+%[- MARK -] t = gettext.translation('spam', '/usr/share/locale')
+%[- MARK -] -_ = t.gettext
+%[- MARK -] +_ = t.lgettext
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] If your translators were providing you with Unicode strings in their
+%[- MARK -] \file{.po} files, you'd instead do:
+%[- MARK -]
+%[- MARK -] END DIFF
Ecco quello che dovreste scrivere all'inizio del vostro modulo:
\begin{verbatim}
@@ -569,6 +894,25 @@
multiple e quindi passare da una all'altra esplicitamente, così:
\begin{verbatim}
+%[- MARK -] BEGIN DIFF 013 of 15
+%[- MARK -] @@ 538
+%[- MARK -] between them explicitly, like so:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import gettext
+%[- MARK -]
+%[- MARK -] -lang1 = gettext.translation(languages=['en'])
+%[- MARK -] -lang2 = gettext.translation(languages=['fr'])
+%[- MARK -] -lang3 = gettext.translation(languages=['de'])
+%[- MARK -] +lang1 = gettext.translation('myapplication', languages=['en'])
+%[- MARK -] +lang2 = gettext.translation('myapplication', languages=['fr'])
+%[- MARK -] +lang3 = gettext.translation('myapplication', languages=['de'])
+%[- MARK -]
+%[- MARK -] # start by using language1
+%[- MARK -] lang1.install()
+%[- MARK -]
+%[- MARK -] # ... time goes by, user selects language 2
+%[- MARK -] END DIFF
import gettext
lang1 = gettext.translation(languages=['en'])
@@ -665,6 +1009,34 @@
bisogno di istruire il vostro programma a cercare le stringhe marcate
con \function{N_()}. Sia \program{pygettext} che \program{xpot}
supportano questa funzionalità attraverso l'uso di switch da riga di
+%[- MARK -] BEGIN DIFF 014 of 15
+%[- MARK -] @@ 631
+%[- MARK -] \function{_()}. However, you will need to teach your message extraction
+%[- MARK -] program to look for translatable strings marked with \function{N_()}.
+%[- MARK -] \program{pygettext} and \program{xpot} both support this through the
+%[- MARK -] use of command line switches.
+%[- MARK -]
+%[- MARK -] +\subsubsection{\function{gettext()} vs. \function{lgettext()}}
+%[- MARK -] +In Python 2.4 the \function{lgettext()} family of functions were
+%[- MARK -] +introduced. The intention of these functions is to provide an
+%[- MARK -] +alternative which is more compliant with the current
+%[- MARK -] +implementation of GNU gettext. Unlike \function{gettext()}, which
+%[- MARK -] +returns strings encoded with the same codeset used in the
+%[- MARK -] +translation file, \function{lgettext()} will return strings
+%[- MARK -] +encoded with the preferred system encoding, as returned by
+%[- MARK -] +\function{locale.getpreferredencoding()}. Also notice that
+%[- MARK -] +Python 2.4 introduces new functions to explicitly choose
+%[- MARK -] +the codeset used in translated strings. If a codeset is explicitly
+%[- MARK -] +set, even \function{lgettext()} will return translated strings in
+%[- MARK -] +the requested codeset, as would be expected in the GNU gettext
+%[- MARK -] +implementation.
+%[- MARK -] +
+%[- MARK -] \subsection{Acknowledgements}
+%[- MARK -]
+%[- MARK -] The following people contributed code, feedback, design suggestions,
+%[- MARK -] previous implementations, and valuable experience to the creation of
+%[- MARK -] this module:
+%[- MARK -] END DIFF
comando.
\subsection{Riconoscimenti}
@@ -672,6 +1044,16 @@
Le seguenti persone hanno contribuito alla stesura del codice,
resoconti, suggerimenti per l'architettura, precedenti
implementazioni e preziose esperienze la creazione di questo
+%[- MARK -] BEGIN DIFF 015 of 15
+%[- MARK -] @@ 645
+%[- MARK -] \item Juan David Ib\'a\~nez Palomar
+%[- MARK -] \item Marc-Andr\'e Lemburg
+%[- MARK -] \item Martin von L\"owis
+%[- MARK -] \item Fran\c cois Pinard
+%[- MARK -] \item Barry Warsaw
+%[- MARK -] + \item Gustavo Niemeyer
+%[- MARK -] \end{itemize}
+%[- MARK -] END DIFF
modulo:
\begin{itemize}
Modified: python/python/Doc/branches/2.4.3/lib/libglob.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libglob.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libglob.tex Fri Jun 2 12:52:55 2006
@@ -15,6 +15,20 @@
\function{fnmatch.fnmatch()}, e senza invocare una subshell. (Usate
\function{os.path.expanduser()} e \function{os.path.expandvars()} per
l'espansione della variabile tilde e delle altre variabili di shell).
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 19
+%[- MARK -] Returns a possibly-empty list of path names that match \var{pathname},
+%[- MARK -] which must be a string containing a path specification.
+%[- MARK -] \var{pathname} can be either absolute (like
+%[- MARK -] \file{/usr/src/Python-1.5/Makefile}) or relative (like
+%[- MARK -] \file{../../Tools/*/*.gif}), and can contain shell-style wildcards.
+%[- MARK -] +Broken symlinks are included in the results (as in the shell).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] For example, consider a directory containing only the following files:
+%[- MARK -] \file{1.gif}, \file{2.txt}, and \file{card.gif}. \function{glob()}
+%[- MARK -] will produce the following results. Notice how any leading components
+%[- MARK -] END DIFF
\index{filenames!pathname expansion}
\begin{funcdesc}{glob}{pathname}
Modified: python/python/Doc/branches/2.4.3/lib/libheapq.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libheapq.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libheapq.tex Fri Jun 2 12:52:55 2006
@@ -55,6 +55,26 @@
\begin{funcdesc}{heapify}{x}
Trasforma la lista \var{x} in uno heap, sul posto, in un tempo
lineare.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 57
+%[- MARK -] the new \var{item}. The heap size doesn't change.
+%[- MARK -] If the heap is empty, \exception{IndexError} is raised.
+%[- MARK -] This is more efficient than \function{heappop()} followed
+%[- MARK -] by \function{heappush()}, and can be more appropriate when using
+%[- MARK -] a fixed-size heap. Note that the value returned may be larger
+%[- MARK -] -than \var{item}! That constrains reasonable uses of this routine.
+%[- MARK -] +than \var{item}! That constrains reasonable uses of this routine
+%[- MARK -] +unless written as part of a conditional replacement:
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + if item > heap[0]:
+%[- MARK -] + item = heapreplace(heap, item)
+%[- MARK -] +\end{verbatim}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] Example of use:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{heapreplace}{heap, item}
@@ -87,6 +107,38 @@
>>> print data == sorted
True
>>>
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 81
+%[- MARK -] >>> print data == sorted
+%[- MARK -] True
+%[- MARK -] >>>
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] +The module also offers two general purpose functions based on heaps.
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{nlargest}{n, iterable}
+%[- MARK -] +Return a list with the \var{n} largest elements from the dataset defined
+%[- MARK -] +by \var{iterable}. Equivalent to: \code{sorted(iterable, reverse=True)[:n]}
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{nsmallest}{n, iterable}
+%[- MARK -] +Return a list with the \var{n} smallest elements from the dataset defined
+%[- MARK -] +by \var{iterable}. Equivalent to: \code{sorted(iterable)[:n]}
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +Both functions perform best for smaller values of \var{n}. For larger
+%[- MARK -] +values, it is more efficient to use the \function{sorted()} function. Also,
+%[- MARK -] +when \code{n==1}, it is more efficient to use the builtin \function{min()}
+%[- MARK -] +and \function{max()} functions.
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \subsection{Theory}
+%[- MARK -]
+%[- MARK -] (This explanation is due to François Pinard. The Python
+%[- MARK -] code for this module was contributed by Kevin O'Connor.)
+%[- MARK -] END DIFF
\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libhotshot.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libhotshot.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libhotshot.tex Fri Jun 2 12:52:55 2006
@@ -56,6 +56,21 @@
dello script. Tutto ciò che è globale nel modulo
\refmodule[main]{__main__} viene usato sia come globale che come
locale nello script.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 57
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{runcall}{func, *args, **keywords}
+%[- MARK -] Profile a single call of a callable.
+%[- MARK -] Additional positional and keyword arguments may be passed
+%[- MARK -] along; the result of the call is returned, and exceptions are
+%[- MARK -] -allowed to propogate cleanly, while ensuring that profiling is
+%[- MARK -] +allowed to propagate cleanly, while ensuring that profiling is
+%[- MARK -] disabled on the way out.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{runctx}{cmd, globals, locals}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{runcall}{func, *args, **keywords}
Modified: python/python/Doc/branches/2.4.3/lib/libhtmllib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libhtmllib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libhtmllib.tex Fri Jun 2 12:52:55 2006
@@ -30,6 +30,23 @@
Il seguente è un sommario delle interfacce definite da
\class{sgmllib.SGMLParser}:
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 33
+%[- MARK -] \item
+%[- MARK -] The interface to feed data to an instance is through the \method{feed()}
+%[- MARK -] method, which takes a string argument. This can be called with as
+%[- MARK -] little or as much text at a time as desired; \samp{p.feed(a);
+%[- MARK -] p.feed(b)} has the same effect as \samp{p.feed(a+b)}. When the data
+%[- MARK -] -contains complete HTML tags, these are processed immediately;
+%[- MARK -] -incomplete elements are saved in a buffer. To force processing of all
+%[- MARK -] +contains complete HTML markup constructs, these are processed immediately;
+%[- MARK -] +incomplete constructs are saved in a buffer. To force processing of all
+%[- MARK -] unprocessed data, call the \method{close()} method.
+%[- MARK -]
+%[- MARK -] For example, to parse the entire contents of a file, use:
+%[- MARK -] \begin{verbatim}
+%[- MARK -] parser.feed(open('myfile.html').read())
+%[- MARK -] END DIFF
\begin{itemize}
\item
@@ -63,6 +80,34 @@
necessita di chiusura, come \code{<P>}, la classe dovrebbe definire il
metodo \method{do_\var{tag}()}.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 58
+%[- MARK -] method; if a tag requires no closing tag, like \code{<P>}, the class
+%[- MARK -] should define the \method{do_\var{tag}()} method.
+%[- MARK -]
+%[- MARK -] \end{itemize}
+%[- MARK -]
+%[- MARK -] -The module defines a single class:
+%[- MARK -] +The module defines a parser class and an exception:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{HTMLParser}{formatter}
+%[- MARK -] This is the basic HTML parser class. It supports all entity names
+%[- MARK -] required by the XHTML 1.0 Recommendation (\url{http://www.w3.org/TR/xhtml1}).
+%[- MARK -] It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] +\begin{excdesc}{HTMLParseError}
+%[- MARK -] +Exception raised by the \class{HTMLParser} class when it encounters an
+%[- MARK -] +error while parsing.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{excdesc}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seemodule{formatter}{Interface definition for transforming an
+%[- MARK -] abstract flow of formatting events into
+%[- MARK -] specific output events on writer objects.}
+%[- MARK -] END DIFF
\end{itemize}
Il modulo definisce una singola classe:
@@ -122,6 +167,22 @@
L'implementazione predefinita aggiunge una marcatore testuale a pié di
pagina usando un indice nella lista degli iperlink creati da
\method{anchor_bgn()}.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 116
+%[- MARK -] This method is called at the end of an anchor region. The default
+%[- MARK -] implementation adds a textual footnote marker using an index into the
+%[- MARK -] list of hyperlinks created by \method{anchor_bgn()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}}
+%[- MARK -] +\begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{,
+%[- MARK -] + align\optional{, width\optional{, height}}}}}
+%[- MARK -] This method is called to handle images. The default implementation
+%[- MARK -] simply passes the \var{alt} value to the \method{handle_data()}
+%[- MARK -] method.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}}
Modified: python/python/Doc/branches/2.4.3/lib/libhtmlparser.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libhtmlparser.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libhtmlparser.tex Fri Jun 2 12:52:55 2006
@@ -2,6 +2,21 @@
Semplice parser per HTML e XHTML}
\declaremodule{standard}{HTMLParser}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 2
+%[- MARK -] Simple HTML and XHTML parser}
+%[- MARK -]
+%[- MARK -] \declaremodule{standard}{HTMLParser}
+%[- MARK -] \modulesynopsis{A simple parser that can handle HTML and XHTML.}
+%[- MARK -]
+%[- MARK -] +\versionadded{2.2}
+%[- MARK -] +
+%[- MARK -] This module defines a class \class{HTMLParser} which serves as the
+%[- MARK -] basis for parsing text files formatted in HTML\index{HTML} (HyperText
+%[- MARK -] Mark-up Language) and XHTML.\index{XHTML} Unlike the parser in
+%[- MARK -] \refmodule{htmllib}, this parser is not based on the SGML parser in
+%[- MARK -] \refmodule{sgmllib}.
+%[- MARK -] END DIFF
\modulesynopsis{Un semplice parser per gestire HTML e XHTML.}
Questo modulo definisce una classe \class{HTMLParser} che rappresenta
@@ -23,6 +38,30 @@
che il tag di chiusura coincida con quello di apertura e non richiama
il gestore dei tag di chiusura per gli elementi che vengono
implicitamente chiusi dalla chiusura di altri elementi.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 21
+%[- MARK -] Unlike the parser in \refmodule{htmllib}, this parser does not check
+%[- MARK -] that end tags match start tags or call the end-tag handler for
+%[- MARK -] elements which are closed implicitly by closing an outer element.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] +An exception is defined as well:
+%[- MARK -] +
+%[- MARK -] +\begin{excdesc}{HTMLParseError}
+%[- MARK -] +Exception raised by the \class{HTMLParser} class when it encounters an
+%[- MARK -] +error while parsing. This exception provides three attributes:
+%[- MARK -] +\member{msg} is a brief message explaining the error, \member{lineno}
+%[- MARK -] +is the number of the line on which the broken construct was detected,
+%[- MARK -] +and \member{offset} is the number of characters into the line at which
+%[- MARK -] +the construct starts.
+%[- MARK -] +\end{excdesc}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \class{HTMLParser} instances have the following methods:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{reset}{}
+%[- MARK -] Reset the instance. Loses all unprocessed data. This is called
+%[- MARK -] END DIFF
\end{classdesc}
Modified: python/python/Doc/branches/2.4.3/lib/libimaplib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libimaplib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libimaplib.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,44 @@
\declaremodule{standard}{imaplib}
\modulesynopsis{Client per protocollo IMAP4 (richiede i socket).}
\moduleauthor{Piers Lauder}{piers a communitysolutions.com.au}
+%[- MARK -] BEGIN DIFF 001 of 10
+%[- MARK -] @@ 4
+%[- MARK -] \declaremodule{standard}{imaplib}
+%[- MARK -] \modulesynopsis{IMAP4 protocol client (requires sockets).}
+%[- MARK -] \moduleauthor{Piers Lauder}{piers a communitysolutions.com.au}
+%[- MARK -] \sectionauthor{Piers Lauder}{piers a communitysolutions.com.au}
+%[- MARK -]
+%[- MARK -] -% Based on HTML documentation by Piers Lauder <piers a communitysolutions.com.au>;
+%[- MARK -] +% Based on HTML documentation by Piers Lauder
+%[- MARK -] +% <piers a communitysolutions.com.au>;
+%[- MARK -] % converted by Fred L. Drake, Jr. <fdrake a acm.org>.
+%[- MARK -] % Revised by ESR, January 2000.
+%[- MARK -] % Changes for IMAP4_SSL by Tino Lange <Tino.Lange a isg.de>, March 2002
+%[- MARK -] -% Changes for IMAP4_stream by Piers Lauder <piers a communitysolutions.com.au>, November 2002
+%[- MARK -] +% Changes for IMAP4_stream by Piers Lauder
+%[- MARK -] +% <piers a communitysolutions.com.au>, November 2002
+%[- MARK -]
+%[- MARK -] \indexii{IMAP4}{protocol}
+%[- MARK -] \indexii{IMAP4_SSL}{protocol}
+%[- MARK -] \indexii{IMAP4_stream}{protocol}
+%[- MARK -]
+%[- MARK -] -This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL} and \class{IMAP4_stream}, which encapsulate a
+%[- MARK -] +This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL}
+%[- MARK -] +and \class{IMAP4_stream}, which encapsulate a
+%[- MARK -] connection to an IMAP4 server and implement a large subset of the
+%[- MARK -] IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
+%[- MARK -] compatible with IMAP4 (\rfc{1730}) servers, but note that the
+%[- MARK -] \samp{STATUS} command is not supported in IMAP4.
+%[- MARK -]
+%[- MARK -] -Three classes are provided by the \module{imaplib} module, \class{IMAP4} is the base class:
+%[- MARK -] +Three classes are provided by the \module{imaplib} module,
+%[- MARK -] +\class{IMAP4} is the base class:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
+%[- MARK -] This class implements the actual IMAP4 protocol. The connection is
+%[- MARK -] created and protocol version (IMAP4 or IMAP4rev1) is determined when
+%[- MARK -] the instance is initialized.
+%[- MARK -] END DIFF
\sectionauthor{Piers Lauder}{piers a communitysolutions.com.au}
% Based on HTML documentation by Piers Lauder <piers a communitysolutions.com.au>;
@@ -48,6 +86,56 @@
Questa è una sotto classe di \exception{IMAP4.error}. Notare che
chiudendo l'istanza ed istanziandone una nuova è solitamente
possibile recuperare da questa eccezione.
+%[- MARK -] BEGIN DIFF 002 of 10
+%[- MARK -] @@ 45
+%[- MARK -] and instantiating a new one will usually allow recovery from this
+%[- MARK -] exception.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{IMAP4.readonly}
+%[- MARK -] -This exception is raised when a writable mailbox has its status changed by the server. This is a
+%[- MARK -] -sub-class of \exception{IMAP4.error}. Some other client now has write permission,
+%[- MARK -] -and the mailbox will need to be re-opened to re-obtain write permission.
+%[- MARK -] +This exception is raised when a writable mailbox has its status
+%[- MARK -] +changed by the server. This is a sub-class of
+%[- MARK -] +\exception{IMAP4.error}. Some other client now has write permission,
+%[- MARK -] +and the mailbox will need to be re-opened to re-obtain write
+%[- MARK -] +permission.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] There's also a subclass for secure connections:
+%[- MARK -]
+%[- MARK -] -\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, keyfile\optional{, certfile}}}}}
+%[- MARK -] -This is a subclass derived from \class{IMAP4} that connects over an SSL encrypted socket
+%[- MARK -] -(to use this class you need a socket module that was compiled with SSL support).
+%[- MARK -] -If \var{host} is not specified, \code{''} (the local host) is used.
+%[- MARK -] -If \var{port} is omitted, the standard IMAP4-over-SSL port (993) is used.
+%[- MARK -] -\var{keyfile} and \var{certfile} are also optional - they can contain a PEM formatted
+%[- MARK -] -private key and certificate chain file for the SSL connection.
+%[- MARK -] +\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{,
+%[- MARK -] + keyfile\optional{, certfile}}}}}
+%[- MARK -] +This is a subclass derived from \class{IMAP4} that connects over an
+%[- MARK -] +SSL encrypted socket (to use this class you need a socket module that
+%[- MARK -] +was compiled with SSL support). If \var{host} is not specified,
+%[- MARK -] +\code{''} (the local host) is used. If \var{port} is omitted, the
+%[- MARK -] +standard IMAP4-over-SSL port (993) is used. \var{keyfile} and
+%[- MARK -] +\var{certfile} are also optional - they can contain a PEM formatted
+%[- MARK -] +private key and certificate chain file for the SSL connection.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] The second subclass allows for connections created by a child process:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{IMAP4_stream}{command}
+%[- MARK -] This is a subclass derived from \class{IMAP4} that connects
+%[- MARK -] -to the \code{stdin/stdout} file descriptors created by passing \var{command} to \code{os.popen2()}.
+%[- MARK -] +to the \code{stdin/stdout} file descriptors created by passing
+%[- MARK -] +\var{command} to \code{os.popen2()}.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] The following utility functions are defined:
+%[- MARK -]
+%[- MARK -] END DIFF
\end{excdesc}
\begin{excdesc}{IMAP4.readonly}
@@ -144,6 +232,54 @@
della risposta del comando, che il risultato generato dal comando.
Ogni \var{data} è, sia una stringa, che una tupla. Se è una tupla, la
prima parte è l'intestazione della risposta, e la seconda parte
+%[- MARK -] BEGIN DIFF 003 of 10
+%[- MARK -] @@ 132
+%[- MARK -] mandated results from the command. Each \var{data}
+%[- MARK -] is either a string, or a tuple. If a tuple, then the first part
+%[- MARK -] is the header of the response, and the second part contains
+%[- MARK -] the data (ie: 'literal' value).
+%[- MARK -]
+%[- MARK -] +The \var{message_set} options to commands below is a string specifying one
+%[- MARK -] +or more messages to be acted upon. It may be a simple message number
+%[- MARK -] +(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of
+%[- MARK -] +non-contiguous ranges separated by commas (\code{'1:3,6:9'}). A range
+%[- MARK -] +can contain an asterisk to indicate an infinite upper bound
+%[- MARK -] +(\code{'3:*'}).
+%[- MARK -] +
+%[- MARK -] An \class{IMAP4} instance has the following methods:
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{append}{mailbox, flags, date_time, message}
+%[- MARK -] - Append message to named mailbox.
+%[- MARK -] + Append \var{message} to named mailbox.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{authenticate}{func}
+%[- MARK -] - Authenticate command --- requires response processing. This is
+%[- MARK -] - currently unimplemented, and raises an exception.
+%[- MARK -] +\begin{methoddesc}{authenticate}{mechanism, authobject}
+%[- MARK -] + Authenticate command --- requires response processing.
+%[- MARK -] +
+%[- MARK -] + \var{mechanism} specifies which authentication mechanism is to be
+%[- MARK -] + used - it should appear in the instance variable \code{capabilities}
+%[- MARK -] + in the form \code{AUTH=mechanism}.
+%[- MARK -] +
+%[- MARK -] + \var{authobject} must be a callable object:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +data = authobject(response)
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] + It will be called to process server continuation responses.
+%[- MARK -] + It should return \code{data} that will be encoded and sent to server.
+%[- MARK -] + It should return \code{None} if the client abort response \samp{*} should
+%[- MARK -] + be sent instead.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{check}{}
+%[- MARK -] Checkpoint mailbox on server.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
contiene i dati (per esempio: valore 'literal').
Una istanza \class{IMAP4} ha i seguenti metodi:
@@ -178,6 +314,24 @@
\begin{methoddesc}{delete}{mailbox}
Cancella la vecchia mailbox chiamata \var{mailbox}.
+%[- MARK -] BEGIN DIFF 004 of 10
+%[- MARK -] @@ 166
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{delete}{mailbox}
+%[- MARK -] Delete old mailbox named \var{mailbox}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}{deleteacl}{mailbox, who}
+%[- MARK -] + Delete the ACLs (remove any rights) set for who on mailbox.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}{expunge}{}
+%[- MARK -] Permanently remove deleted items from selected mailbox. Generates an
+%[- MARK -] \samp{EXPUNGE} response for each deleted message. Returned data
+%[- MARK -] contains a list of \samp{EXPUNGE} message numbers in order
+%[- MARK -] received.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{expunge}{}
@@ -225,6 +379,24 @@
\begin{methoddesc}{login}{user, password}
Identifica il client utilizzando una password in testo piano. La
\var{password} verrà quotata.
+%[- MARK -] BEGIN DIFF 005 of 10
+%[- MARK -] @@ 210
+%[- MARK -] Identify the client using a plaintext password.
+%[- MARK -] The \var{password} will be quoted.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{login_cram_md5}{user, password}
+%[- MARK -] - Force use of \samp{CRAM-MD5} authentication when identifying the client to protect the password.
+%[- MARK -] - Will only work if the server \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
+%[- MARK -] + Force use of \samp{CRAM-MD5} authentication when identifying the
+%[- MARK -] + client to protect the password. Will only work if the server
+%[- MARK -] + \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{logout}{}
+%[- MARK -] Shutdown connection to server. Returns server \samp{BYE} response.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{login_cram_md5}{user, password}
@@ -247,6 +419,39 @@
tutte le mailbox. I dati restituiti sono tuple contenenti la parte
dell'intestazione della busta del messaggio ed i dati del messaggio
stesso.
+%[- MARK -] BEGIN DIFF 006 of 10
+%[- MARK -] @@ 226
+%[- MARK -] \var{directory} defaults to the top level directory and
+%[- MARK -] \var{pattern} defaults to match any mailbox.
+%[- MARK -] Returned data are tuples of message part envelope and data.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}{myrights}{mailbox}
+%[- MARK -] + Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{namespace}{}
+%[- MARK -] + Returns IMAP namespaces as defined in RFC2342.
+%[- MARK -] +\versionadded{2.3}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}{noop}{}
+%[- MARK -] Send \samp{NOOP} to server.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{open}{host, port}
+%[- MARK -] Opens socket to \var{port} at \var{host}.
+%[- MARK -] The connection objects established by this method
+%[- MARK -] - will be used in the \code{read}, \code{readline}, \code{send}, and \code{shutdown} methods.
+%[- MARK -] + will be used in the \code{read}, \code{readline}, \code{send}, and
+%[- MARK -] + \code{shutdown} methods.
+%[- MARK -] You may override this method.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{partial}{message_num, message_part, start, length}
+%[- MARK -] Fetch truncated part of a message.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{noop}{}
@@ -296,6 +501,37 @@
Restituisce i dati per il codice \var{code} di risposta quando
ricevuto, altrimenti restituisce \code{None}. Restituisce il codice
passato, al posto del tipo abituale.
+%[- MARK -] BEGIN DIFF 007 of 10
+%[- MARK -] @@ 273
+%[- MARK -] Return data for response \var{code} if received, or
+%[- MARK -] \code{None}. Returns the given code, instead of the usual type.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{search}{charset, criterion\optional{, ...}}
+%[- MARK -] - Search mailbox for matching messages. Returned data contains a space
+%[- MARK -] - separated list of matching message numbers. \var{charset} may be
+%[- MARK -] + Search mailbox for matching messages. \var{charset} may be
+%[- MARK -] \code{None}, in which case no \samp{CHARSET} will be specified in the
+%[- MARK -] request to the server. The IMAP protocol requires that at least one
+%[- MARK -] criterion be specified; an exception will be raised when the server
+%[- MARK -] returns an error.
+%[- MARK -]
+%[- MARK -] Example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] # M is a connected IMAP4 instance...
+%[- MARK -] -msgnums = M.search(None, 'FROM', '"LDJ"')
+%[- MARK -] +typ, msgnums = M.search(None, 'FROM', '"LDJ"')
+%[- MARK -]
+%[- MARK -] # or:
+%[- MARK -] -msgnums = M.search(None, '(FROM "LDJ")')
+%[- MARK -] +typ, msgnums = M.search(None, '(FROM "LDJ")')
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}}
+%[- MARK -] Select a mailbox. Returned data is the count of messages in
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{search}{charset, criterion\optional{, ...}}
@@ -350,6 +586,38 @@
\begin{methoddesc}{socket}{}
Restituisce l'istanza socket usata per la connessione al server.
+%[- MARK -] BEGIN DIFF 008 of 10
+%[- MARK -] @@ 324
+%[- MARK -] \begin{methoddesc}{socket}{}
+%[- MARK -] Returns socket instance used to connect to server.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
+%[- MARK -] - The \code{sort} command is a variant of \code{search} with sorting semantics for
+%[- MARK -] - the results. Returned data contains a space
+%[- MARK -] - separated list of matching message numbers.
+%[- MARK -] + The \code{sort} command is a variant of \code{search} with sorting
+%[- MARK -] + semantics for the results. Returned data contains a space separated
+%[- MARK -] + list of matching message numbers.
+%[- MARK -]
+%[- MARK -] Sort has two arguments before the \var{search_criterion}
+%[- MARK -] - argument(s); a parenthesized list of \var{sort_criteria}, and the searching \var{charset}.
+%[- MARK -] - Note that unlike \code{search}, the searching \var{charset} argument is mandatory.
+%[- MARK -] - There is also a \code{uid sort} command which corresponds to \code{sort} the way
+%[- MARK -] - that \code{uid search} corresponds to \code{search}.
+%[- MARK -] - The \code{sort} command first searches the mailbox for messages that
+%[- MARK -] + argument(s); a parenthesized list of \var{sort_criteria}, and the
+%[- MARK -] + searching \var{charset}. Note that unlike \code{search}, the
+%[- MARK -] + searching \var{charset} argument is mandatory. There is also a
+%[- MARK -] + \code{uid sort} command which corresponds to \code{sort} the way
+%[- MARK -] + that \code{uid search} corresponds to \code{search}. The
+%[- MARK -] + \code{sort} command first searches the mailbox for messages that
+%[- MARK -] match the given searching criteria using the charset argument for
+%[- MARK -] the interpretation of strings in the searching criteria. It then
+%[- MARK -] returns the numbers of matching messages.
+%[- MARK -]
+%[- MARK -] This is an \samp{IMAP4rev1} extension command.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
@@ -374,6 +642,71 @@
\begin{methoddesc}{status}{mailbox, names}
Richiede la condizione di stato named per la \var{mailbox}.
+%[- MARK -] BEGIN DIFF 009 of 10
+%[- MARK -] @@ 346
+%[- MARK -] \begin{methoddesc}{status}{mailbox, names}
+%[- MARK -] Request named status conditions for \var{mailbox}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{store}{message_set, command, flag_list}
+%[- MARK -] - Alters flag dispositions for messages in mailbox.
+%[- MARK -] + Alters flag dispositions for messages in mailbox. \var{command} is
+%[- MARK -] + specified by section 6.4.6 of \rfc{2060} as being one of "FLAGS", "+FLAGS",
+%[- MARK -] + or "-FLAGS", optionally with a suffix of ".SILENT".
+%[- MARK -] +
+%[- MARK -] + For example, to set the delete flag on all messages:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +typ, data = M.search(None, 'ALL')
+%[- MARK -] +for num in data[0].split():
+%[- MARK -] + M.store(num, '+FLAGS', '\\Deleted')
+%[- MARK -] +M.expunge()
+%[- MARK -] +\end{verbatim}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{subscribe}{mailbox}
+%[- MARK -] Subscribe to new mailbox.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{thread}{threading_algorithm, charset, search_criterion\optional{, ...}}
+%[- MARK -] - The \code{thread} command is a variant of \code{search} with threading semantics for
+%[- MARK -] - the results. Returned data contains a space
+%[- MARK -] +\begin{methoddesc}{thread}{threading_algorithm, charset,
+%[- MARK -] + search_criterion\optional{, ...}}
+%[- MARK -] + The \code{thread} command is a variant of \code{search} with
+%[- MARK -] + threading semantics for the results. Returned data contains a space
+%[- MARK -] separated list of thread members.
+%[- MARK -]
+%[- MARK -] - Thread members consist of zero or more messages numbers, delimited by spaces,
+%[- MARK -] - indicating successive parent and child.
+%[- MARK -] + Thread members consist of zero or more messages numbers, delimited
+%[- MARK -] + by spaces, indicating successive parent and child.
+%[- MARK -]
+%[- MARK -] Thread has two arguments before the \var{search_criterion}
+%[- MARK -] - argument(s); a \var{threading_algorithm}, and the searching \var{charset}.
+%[- MARK -] - Note that unlike \code{search}, the searching \var{charset} argument is mandatory.
+%[- MARK -] - There is also a \code{uid thread} command which corresponds to \code{thread} the way
+%[- MARK -] - that \code{uid search} corresponds to \code{search}.
+%[- MARK -] - The \code{thread} command first searches the mailbox for messages that
+%[- MARK -] - match the given searching criteria using the charset argument for
+%[- MARK -] - the interpretation of strings in the searching criteria. It thren
+%[- MARK -] - returns the matching messages threaded according to the specified
+%[- MARK -] - threading algorithm.
+%[- MARK -] + argument(s); a \var{threading_algorithm}, and the searching
+%[- MARK -] + \var{charset}. Note that unlike \code{search}, the searching
+%[- MARK -] + \var{charset} argument is mandatory. There is also a \code{uid
+%[- MARK -] + thread} command which corresponds to \code{thread} the way that
+%[- MARK -] + \code{uid search} corresponds to \code{search}. The \code{thread}
+%[- MARK -] + command first searches the mailbox for messages that match the given
+%[- MARK -] + searching criteria using the charset argument for the interpretation
+%[- MARK -] + of strings in the searching criteria. It then returns the matching
+%[- MARK -] + messages threaded according to the specified threading algorithm.
+%[- MARK -]
+%[- MARK -] This is an \samp{IMAP4rev1} extension command. \versionadded{2.4}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{uid}{command, arg\optional{, ...}}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{store}{message_set, command, flag_list}
@@ -458,6 +791,17 @@
mailbox, recupera e stampa tutti i messaggi:
\begin{verbatim}
+%[- MARK -] BEGIN DIFF 010 of 10
+%[- MARK -] @@ 429
+%[- MARK -] M.select()
+%[- MARK -] typ, data = M.search(None, 'ALL')
+%[- MARK -] for num in data[0].split():
+%[- MARK -] typ, data = M.fetch(num, '(RFC822)')
+%[- MARK -] print 'Message %s\n%s\n' % (num, data[0][1])
+%[- MARK -] +M.close()
+%[- MARK -] M.logout()
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
import getpass, imaplib
M = imaplib.IMAP4()
Modified: python/python/Doc/branches/2.4.3/lib/libimgfile.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libimgfile.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libimgfile.tex Fri Jun 2 12:52:55 2006
@@ -46,6 +46,21 @@
ridimensionamento viene effettuato semplicemente scartando o
duplicando i pixel dell'immagine, per cui il risultato potrà non
essere di buona qualità, soprattutto per immagini generate dal
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 38
+%[- MARK -] scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
+%[- MARK -] \var{blur} parameters are omitted scaling is done by
+%[- MARK -] simply dropping or duplicating pixels, so the result will be less than
+%[- MARK -] perfect, especially for computer-generated images.
+%[- MARK -]
+%[- MARK -] -Alternatively, you can specify a filter to use to smoothen the image
+%[- MARK -] +Alternatively, you can specify a filter to use to smooth the image
+%[- MARK -] after scaling. The filter forms supported are \code{'impulse'},
+%[- MARK -] \code{'box'}, \code{'triangle'}, \code{'quadratic'} and
+%[- MARK -] \code{'gaussian'}. If a filter is specified \var{blur} is an optional
+%[- MARK -] parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
+%[- MARK -]
+%[- MARK -] END DIFF
computer.
In alternativa, si può specificare un filtro da usare per rendere
Modified: python/python/Doc/branches/2.4.3/lib/libimp.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libimp.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libimp.tex Fri Jun 2 12:52:55 2006
@@ -144,6 +144,23 @@
\begin{datadesc}{C_EXTENSION}
Il modulo trovato è una libreria condivisa caricabile
dinamicamente.
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 133
+%[- MARK -] \begin{datadesc}{C_EXTENSION}
+%[- MARK -] The module was found as dynamically loadable shared library.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{PY_RESOURCE}
+%[- MARK -] -The module was found as a Macintosh resource. This value can only be
+%[- MARK -] -returned on a Macintosh.
+%[- MARK -] +The module was found as a Mac OS 9 resource. This value can only be
+%[- MARK -] +returned on a Mac OS 9 or earlier Macintosh.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{PKG_DIRECTORY}
+%[- MARK -] The module was found as a package directory.
+%[- MARK -] \end{datadesc}
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{PY_RESOURCE}
@@ -205,6 +222,21 @@
Restituisce \code{True} se esiste un modulo frozen (vedete
\function{init_frozen()}) chiamato \var{name}, o \code{False} se non
esiste il modulo.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 190
+%[- MARK -] Return \code{True} if there is a frozen module (see
+%[- MARK -] \function{init_frozen()}) called \var{name}, or \code{False} if there is
+%[- MARK -] no such module.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{load_compiled}{name, pathname, file}
+%[- MARK -] +\begin{funcdesc}{load_compiled}{name, pathname, \optional{file}}
+%[- MARK -] \indexii{file}{byte-code}
+%[- MARK -] Load and initialize a module implemented as a byte-compiled code file
+%[- MARK -] and return its module object. If the module was already initialized,
+%[- MARK -] it will be initialized \emph{again}. The \var{name} argument is used
+%[- MARK -] to create or access a module object. The \var{pathname} argument
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{load_compiled}{name, pathname, file}
@@ -232,6 +264,21 @@
L'argomento facoltativo \var{file} viene ignorato. (Nota: l'uso delle
librerie dinamiche è altamente legato al sistema in uso, e non tutti
i sistemi lo supportano).
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 216
+%[- MARK -] called. The optional \var{file} argument is ignored. (Note: using
+%[- MARK -] shared libraries is highly system dependent, and not all systems
+%[- MARK -] support it.)
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{load_source}{name, pathname, file}
+%[- MARK -] +\begin{funcdesc}{load_source}{name, pathname\optional{, file}}
+%[- MARK -] Load and initialize a module implemented as a Python source file and
+%[- MARK -] return its module object. If the module was already initialized, it
+%[- MARK -] will be initialized \emph{again}. The \var{name} argument is used to
+%[- MARK -] create or access a module object. The \var{pathname} argument points
+%[- MARK -] to the source file. The \var{file} argument is the source
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{load_source}{name, pathname, file}
Modified: python/python/Doc/branches/2.4.3/lib/libitertools.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libitertools.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libitertools.tex Fri Jun 2 12:52:55 2006
@@ -138,6 +138,21 @@
for x in iterable:
yield x
\end{verbatim}
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 131
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{groupby}{iterable\optional{, key}}
+%[- MARK -] Make an iterator that returns consecutive keys and groups from the
+%[- MARK -] - \var{iterable}. \var{key} is a function computing a key value for each
+%[- MARK -] + \var{iterable}. The \var{key} is a function computing a key value for each
+%[- MARK -] element. If not specified or is \code{None}, \var{key} defaults to an
+%[- MARK -] identity function and returns the element unchanged. Generally, the
+%[- MARK -] iterable needs to already be sorted on the same key function.
+%[- MARK -]
+%[- MARK -] The returned group is itself an iterator that shares the underlying
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{groupby}{iterable\optional{, key}}
@@ -258,6 +273,33 @@
\var{stop} o \var{step}. Questo metodo può venire usato per estrarre
campi specifici da dati che presentano una struttura interna appiattita (per
esempio, un rapporto multi-linea può presentare un campo nome
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 250
+%[- MARK -] third line). Equivalent to:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] def islice(iterable, *args):
+%[- MARK -] s = slice(*args)
+%[- MARK -] - next, stop, step = s.start or 0, s.stop, s.step or 1
+%[- MARK -] - for cnt, element in enumerate(iterable):
+%[- MARK -] - if cnt < next:
+%[- MARK -] - continue
+%[- MARK -] - if stop is not None and cnt >= stop:
+%[- MARK -] - break
+%[- MARK -] - yield element
+%[- MARK -] - next += step
+%[- MARK -] + it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1))
+%[- MARK -] + nexti = it.next()
+%[- MARK -] + for i, element in enumerate(iterable):
+%[- MARK -] + if i == nexti:
+%[- MARK -] + yield element
+%[- MARK -] + nexti = it.next()
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{izip}{*iterables}
+%[- MARK -] Make an iterator that aggregates elements from each of the iterables.
+%[- MARK -] END DIFF
ogni tre linee). Equivalente a:
\begin{verbatim}
@@ -278,6 +320,44 @@
Crea un iteratore che aggrega elementi da ognuno degli iterabili \var{iterables}.
Somiglia a \function{zip()} eccetto per il fatto che restituisce un
iteratore invece di una lista. Questo metodo viene utilizzato per iterazioni lock-step su
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 271
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] def izip(*iterables):
+%[- MARK -] iterables = map(iter, iterables)
+%[- MARK -] while iterables:
+%[- MARK -] - result = [i.next() for i in iterables]
+%[- MARK -] + result = [it.next() for it in iterables]
+%[- MARK -] yield tuple(result)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] \versionchanged[When no iterables are specified, returns a zero length
+%[- MARK -] - iterator instead of raising a TypeError exception]{2.4}
+%[- MARK -] + iterator instead of raising a TypeError exception]{2.4}
+%[- MARK -] +
+%[- MARK -] + Note, the left-to-right evaluation order of the iterables is guaranteed.
+%[- MARK -] + This makes possible an idiom for clustering a data series into n-length
+%[- MARK -] + groups using \samp{izip(*[iter(s)]*n)}. For data that doesn't fit
+%[- MARK -] + n-length groups exactly, the last tuple can be pre-padded with fill
+%[- MARK -] + values using \samp{izip(*[chain(s, [None]*(n-1))]*n)}.
+%[- MARK -] +
+%[- MARK -] + Note, when \function{izip()} is used with unequal length inputs, subsequent
+%[- MARK -] + iteration over the longer iterables cannot reliably be continued after
+%[- MARK -] + \function{izip()} terminates. Potentially, up to one entry will be missing
+%[- MARK -] + from each of the left-over iterables. This occurs because a value is fetched
+%[- MARK -] + from each iterator in-turn, but the process ends when one of the iterators
+%[- MARK -] + terminates. This leaves the last fetched values in limbo (they cannot be
+%[- MARK -] + returned in a final, incomplete tuple and they are cannot be pushed back
+%[- MARK -] + into the iterator for retrieval with \code{it.next()}). In general,
+%[- MARK -] + \function{izip()} should only be used with unequal length inputs when you
+%[- MARK -] + don't care about trailing, unmatched values from the longer iterables.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{repeat}{object\optional{, times}}
+%[- MARK -] Make an iterator that returns \var{object} over and over again.
+%[- MARK -] Runs indefinitely unless the \var{times} argument is specified.
+%[- MARK -] END DIFF
diversi iterabili contemporaneamente. Equivalente a:
\begin{verbatim}
@@ -341,6 +421,21 @@
else:
break
\end{verbatim}
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 330
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tee}{iterable\optional{, n=2}}
+%[- MARK -] Return \var{n} independent iterators from a single iterable.
+%[- MARK -] - The case where \var{n} is two is equivalent to:
+%[- MARK -] + The case where \code{n==2} is equivalent to:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] def tee(iterable):
+%[- MARK -] def gen(next, data={}, cnt=[0]):
+%[- MARK -] for i in count():
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{tee}{iterable\optional{, n=2}}
@@ -471,6 +566,48 @@
def nth(iterable, n):
"Restituisce l'n-esimo elemento"
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 456
+%[- MARK -] "Returns the nth item"
+%[- MARK -] return list(islice(iterable, n, n+1))
+%[- MARK -]
+%[- MARK -] def all(seq, pred=bool):
+%[- MARK -] "Returns True if pred(x) is True for every element in the iterable"
+%[- MARK -] - return False not in imap(pred, seq)
+%[- MARK -] + for elem in ifilterfalse(pred, seq):
+%[- MARK -] + return False
+%[- MARK -] + return True
+%[- MARK -]
+%[- MARK -] def any(seq, pred=bool):
+%[- MARK -] - "Returns True if pred(x) is True at least one element in the iterable"
+%[- MARK -] - return True in imap(pred, seq)
+%[- MARK -] + "Returns True if pred(x) is True for at least one element in the iterable"
+%[- MARK -] + for elem in ifilter(pred, seq):
+%[- MARK -] + return True
+%[- MARK -] + return False
+%[- MARK -]
+%[- MARK -] def no(seq, pred=bool):
+%[- MARK -] "Returns True if pred(x) is False for every element in the iterable"
+%[- MARK -] - return True not in imap(pred, seq)
+%[- MARK -] + for elem in ifilter(pred, seq):
+%[- MARK -] + return False
+%[- MARK -] + return True
+%[- MARK -]
+%[- MARK -] def quantify(seq, pred=bool):
+%[- MARK -] "Count how many times the predicate is True in the sequence"
+%[- MARK -] return sum(imap(pred, seq))
+%[- MARK -]
+%[- MARK -] def padnone(seq):
+%[- MARK -] """Returns the sequence elements and then returns None indefinitely.
+%[- MARK -]
+%[- MARK -] Useful for emulating the behavior of the built-in map() function.
+%[- MARK -] -
+%[- MARK -] """
+%[- MARK -] return chain(seq, repeat(None))
+%[- MARK -]
+%[- MARK -] def ncycles(seq, n):
+%[- MARK -] "Returns the sequence elements n times"
+%[- MARK -] END DIFF
return list(islice(iterable, n, n+1))
def all(seq, pred=bool):
@@ -508,6 +645,20 @@
return list(chain(*listOfLists))
def repeatfunc(func, times=None, *args):
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 492
+%[- MARK -]
+%[- MARK -] def repeatfunc(func, times=None, *args):
+%[- MARK -] """Repeat calls to func with specified arguments.
+%[- MARK -]
+%[- MARK -] Example: repeatfunc(random.random)
+%[- MARK -] -
+%[- MARK -] """
+%[- MARK -] if times is None:
+%[- MARK -] return starmap(func, repeat(args))
+%[- MARK -] else:
+%[- MARK -] return starmap(func, repeat(args, times))
+%[- MARK -] END DIFF
"""Ripete le chiamate a func con gli argomenti specificati.
Esempio: repeatfunc(random.random)
@@ -525,6 +676,20 @@
b.next()
except StopIteration:
pass
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 508
+%[- MARK -] b.next()
+%[- MARK -] except StopIteration:
+%[- MARK -] pass
+%[- MARK -] return izip(a, b)
+%[- MARK -]
+%[- MARK -] +def grouper(n, iterable, padvalue=None):
+%[- MARK -] + "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')"
+%[- MARK -] + return izip(*[chain(iterable, repeat(padvalue, n-1))]*n)
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
return izip(a, b)
\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/liblinecache.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liblinecache.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liblinecache.tex Fri Jun 2 12:52:55 2006
@@ -30,6 +30,25 @@
\begin{funcdesc}{clearcache}{}
Ripulisce la cache. Utilizzate questa funzione se non sono più
necessarie le righe precedentemente lette utilizzando \function{getline()}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 29
+%[- MARK -] \begin{funcdesc}{clearcache}{}
+%[- MARK -] Clear the cache. Use this function if you no longer need lines from
+%[- MARK -] files previously read using \function{getline()}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{checkcache}{}
+%[- MARK -] +\begin{funcdesc}{checkcache}{\optional{filename}}
+%[- MARK -] Check the cache for validity. Use this function if files in the cache
+%[- MARK -] -may have changed on disk, and you require the updated version.
+%[- MARK -] +may have changed on disk, and you require the updated version. If
+%[- MARK -] +\var{filename} is omitted, it will check the whole cache entries.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] Example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{checkcache}{}
Modified: python/python/Doc/branches/2.4.3/lib/liblocale.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liblocale.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liblocale.tex Fri Jun 2 12:52:55 2006
@@ -61,6 +61,21 @@
\begin{funcdesc}{localeconv}{}
Restituisce il database delle convenzioni locali in forma di
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 84
+%[- MARK -] {Equivalent to \code{'grouping'}, used for monetary
+%[- MARK -] values.}
+%[- MARK -] \lineiii{}{\code{'positive_sign'}}
+%[- MARK -] {Symbol used to annotate a positive monetary value.}
+%[- MARK -] \lineiii{}{\code{'negative_sign'}}
+%[- MARK -] - {Symbol used to annotate a nnegative monetary value.}
+%[- MARK -] + {Symbol used to annotate a negative monetary value.}
+%[- MARK -] \lineiii{}{\code{'frac_digits'}}
+%[- MARK -] {Number of fractional digits used in local formatting
+%[- MARK -] of monetary values.}
+%[- MARK -] \lineiii{}{\code{'int_frac_digits'}}
+%[- MARK -] {Number of fractional digits used in international
+%[- MARK -] END DIFF
dizionario. Questo dizionario ha le seguenti stringhe come chiavi:
\begin{tableiii}{l|l|p{3in}}{costante}{Chiave}{Categoria}{Significato}
@@ -423,6 +438,21 @@
usati per rappresentare i valori da 0 a 99.
\end{datadesc}
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 395
+%[- MARK -]
+%[- MARK -] Example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> import locale
+%[- MARK -] ->>> loc = locale.setlocale(locale.LC_ALL) # get current locale
+%[- MARK -] +>>> loc = locale.getlocale(locale.LC_ALL) # get current locale
+%[- MARK -] >>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
+%[- MARK -] >>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
+%[- MARK -] >>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
+%[- MARK -] >>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
+%[- MARK -] >>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
+%[- MARK -] END DIFF
Esempio:
\begin{verbatim}
@@ -496,6 +526,38 @@
\function{setlocale()}, se non per individuare la localizzazione
corrente. Ma poiché il valore restituito può venire usato in modo
portabile solo per ripristinarlo, questo non è molto utile (eccetto
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 454
+%[- MARK -] Extension modules should never call \function{setlocale()}, except to
+%[- MARK -] find out what the current locale is. But since the return value can
+%[- MARK -] only be used portably to restore it, that is not very useful (except
+%[- MARK -] perhaps to find out whether or not the locale is \samp{C}).
+%[- MARK -]
+%[- MARK -] -When Python is embedded in an application, if the application sets the
+%[- MARK -] -locale to something specific before initializing Python, that is
+%[- MARK -] -generally okay, and Python will use whatever locale is set,
+%[- MARK -] -\emph{except} that the \constant{LC_NUMERIC} locale should always be
+%[- MARK -] -\samp{C}.
+%[- MARK -] -
+%[- MARK -] -The \function{setlocale()} function in the \module{locale} module
+%[- MARK -] -gives the Python programmer the impression that you can manipulate the
+%[- MARK -] -\constant{LC_NUMERIC} locale setting, but this not the case at the C
+%[- MARK -] -level: C code will always find that the \constant{LC_NUMERIC} locale
+%[- MARK -] -setting is \samp{C}. This is because too much would break when the
+%[- MARK -] -decimal point character is set to something else than a period
+%[- MARK -] -(e.g. the Python parser would break). Caveat: threads that run
+%[- MARK -] -without holding Python's global interpreter lock may occasionally find
+%[- MARK -] -that the numeric locale setting differs; this is because the only
+%[- MARK -] -portable way to implement this feature is to set the numeric locale
+%[- MARK -] -settings to what the user requests, extract the relevant
+%[- MARK -] -characteristics, and then restore the \samp{C} numeric locale.
+%[- MARK -] -
+%[- MARK -] When Python code uses the \module{locale} module to change the locale,
+%[- MARK -] this also affects the embedding application. If the embedding
+%[- MARK -] application doesn't want this to happen, it should remove the
+%[- MARK -] \module{_locale} extension module (which does all the work) from the
+%[- MARK -] table of built-in modules in the \file{config.c} file, and make sure
+%[- MARK -] END DIFF
forse che per capire se la localizzazione è \samp{C} oppure no).
Quando Python è incluso in una applicazione, se l'applicazione imposta
@@ -529,6 +591,32 @@
accessibile dalle librerie condivise.
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 486
+%[- MARK -] \subsection{Access to message catalogs \label{locale-gettext}}
+%[- MARK -]
+%[- MARK -] The locale module exposes the C library's gettext interface on systems
+%[- MARK -] that provide this interface. It consists of the functions
+%[- MARK -] \function{gettext()}, \function{dgettext()}, \function{dcgettext()},
+%[- MARK -] -\function{textdomain()}, and \function{bindtextdomain()}. These are
+%[- MARK -] -similar to the same functions in the \refmodule{gettext} module, but use
+%[- MARK -] -the C library's binary format for message catalogs, and the C
+%[- MARK -] -library's search algorithms for locating message catalogs.
+%[- MARK -] +\function{textdomain()}, \function{bindtextdomain()}, and
+%[- MARK -] +\function{bind_textdomain_codeset()}. These are similar to the same
+%[- MARK -] +functions in the \refmodule{gettext} module, but use the C library's
+%[- MARK -] +binary format for message catalogs, and the C library's search
+%[- MARK -] +algorithms for locating message catalogs.
+%[- MARK -]
+%[- MARK -] Python applications should normally find no need to invoke these
+%[- MARK -] functions, and should use \refmodule{gettext} instead. A known
+%[- MARK -] exception to this rule are applications that link use additional C
+%[- MARK -] libraries which internally invoke \cfunction{gettext()} or
+%[- MARK -] -\function{cdgettext()}. For these applications, it may be necessary to
+%[- MARK -] +\function{dcgettext()}. For these applications, it may be necessary to
+%[- MARK -] bind the text domain, so that the libraries can properly locate their
+%[- MARK -] message catalogs.
+%[- MARK -] END DIFF
\subsection{Accesso al cataloghi dei messaggi \label{locale-gettext}}
Il modulo locale presenta l'interfaccia Gettext della libreria del C su
Modified: python/python/Doc/branches/2.4.3/lib/liblogging.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liblogging.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liblogging.tex Fri Jun 2 12:52:55 2006
@@ -34,6 +34,45 @@
\method{error()} e \method{critical()}, che duplicano i livelli
predefiniti. Non siete costretti ad usare questi livelli: potete
specificarne di propri ed usare il metodo più generale \class{Logger},
+%[- MARK -] BEGIN DIFF 001 of 21
+%[- MARK -] @@ 33
+%[- MARK -] \method{critical()}, which mirror the default levels. You are not
+%[- MARK -] constrained to use these levels: you can specify your own and use a
+%[- MARK -] more general \class{Logger} method, \method{log()}, which takes an
+%[- MARK -] explicit level argument.
+%[- MARK -]
+%[- MARK -] +The numeric values of logging levels are given in the following table. These
+%[- MARK -] +are primarily of interest if you want to define your own levels, and need
+%[- MARK -] +them to have specific values relative to the predefined levels. If you
+%[- MARK -] +define a level with the same numeric value, it overwrites the predefined
+%[- MARK -] +value; the predefined name is lost.
+%[- MARK -] +
+%[- MARK -] +\begin{tableii}{l|l}{code}{Level}{Numeric value}
+%[- MARK -] + \lineii{CRITICAL}{50}
+%[- MARK -] + \lineii{ERROR}{40}
+%[- MARK -] + \lineii{WARNING}{30}
+%[- MARK -] + \lineii{INFO}{20}
+%[- MARK -] + \lineii{DEBUG}{10}
+%[- MARK -] + \lineii{NOTSET}{0}
+%[- MARK -] +\end{tableii}
+%[- MARK -] +
+%[- MARK -] Levels can also be associated with loggers, being set either by the
+%[- MARK -] developer or through loading a saved logging configuration. When a
+%[- MARK -] logging method is called on a logger, the logger compares its own
+%[- MARK -] level with the level associated with the method call. If the logger's
+%[- MARK -] level is higher than the method call's, no logging message is actually
+%[- MARK -] generated. This is the basic mechanism controlling the verbosity of
+%[- MARK -] logging output.
+%[- MARK -]
+%[- MARK -] Logging messages are encoded as instances of the \class{LogRecord} class.
+%[- MARK -] -When a logger decides to actually log an event, an \class{LogRecord}
+%[- MARK -] +When a logger decides to actually log an event, a \class{LogRecord}
+%[- MARK -] instance is created from the logging message.
+%[- MARK -]
+%[- MARK -] Logging messages are subjected to a dispatch mechanism through the
+%[- MARK -] use of \dfn{handlers}, which are instances of subclasses of the
+%[- MARK -] \class{Handler} class. Handlers are responsible for ensuring that a logged
+%[- MARK -] END DIFF
\method{log()}, che prende un esplicito argomento di livello.
I livelli possono anche essere associati ai logger, essendo
@@ -79,6 +118,30 @@
\item Le istanze \class{StreamHandler} inviano i messaggi di errore
agli stream (oggetti simil-file).
+%[- MARK -] BEGIN DIFF 002 of 21
+%[- MARK -] @@ 75
+%[- MARK -] streams (file-like objects).
+%[- MARK -]
+%[- MARK -] \item \class{FileHandler} instances send error messages to disk
+%[- MARK -] files.
+%[- MARK -]
+%[- MARK -] +\item \class{BaseRotatingHandler} is the base class for handlers that
+%[- MARK -] +rotate log files at a certain point. It is not meant to be instantiated
+%[- MARK -] +directly. Instead, use \class{RotatingFileHandler} or
+%[- MARK -] +\class{TimedRotatingFileHandler}.
+%[- MARK -] +
+%[- MARK -] \item \class{RotatingFileHandler} instances send error messages to disk
+%[- MARK -] files, with support for maximum log file sizes and log file rotation.
+%[- MARK -]
+%[- MARK -] +\item \class{TimedRotatingFileHandler} instances send error messages to
+%[- MARK -] +disk files rotating the log file at certain timed intervals.
+%[- MARK -] +
+%[- MARK -] \item \class{SocketHandler} instances send error messages to
+%[- MARK -] TCP/IP sockets.
+%[- MARK -]
+%[- MARK -] \item \class{DatagramHandler} instances send error messages to UDP
+%[- MARK -] sockets.
+%[- MARK -] END DIFF
\item Le istanze \class{FileHandler} inviano i messaggi di errori a file su disco.
\item Le istanze \class{RotatingFileHandler} inviano i messaggi di
@@ -142,6 +205,54 @@
altri vengono scartati.
In aggiunta alle classi descritte precedentemente, esistono anche un
+%[- MARK -] BEGIN DIFF 003 of 21
+%[- MARK -] @@ 132
+%[- MARK -] In addition to the classes described above, there are a number of module-
+%[- MARK -] level functions.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getLogger}{\optional{name}}
+%[- MARK -] Return a logger with the specified name or, if no name is specified, return
+%[- MARK -] -a logger which is the root logger of the hierarchy.
+%[- MARK -] +a logger which is the root logger of the hierarchy. If specified, the name
+%[- MARK -] +is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"}
+%[- MARK -] +or \var{"a.b.c.d"}. Choice of these names is entirely up to the developer
+%[- MARK -] +who is using logging.
+%[- MARK -]
+%[- MARK -] All calls to this function with a given name return the same logger instance.
+%[- MARK -] This means that logger instances never need to be passed between different
+%[- MARK -] parts of an application.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{getLoggerClass}{}
+%[- MARK -] +Return either the standard \class{Logger} class, or the last class passed to
+%[- MARK -] +\function{setLoggerClass()}. This function may be called from within a new
+%[- MARK -] +class definition, to ensure that installing a customised \class{Logger} class
+%[- MARK -] +will not undo customisations already applied by other code. For example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + class MyLogger(logging.getLoggerClass()):
+%[- MARK -] + # ... override behaviour here
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] Logs a message with level \constant{DEBUG} on the root logger.
+%[- MARK -] The \var{msg} is the message format string, and the \var{args} are the
+%[- MARK -] arguments which are merged into \var{msg}. The only keyword argument in
+%[- MARK -] \var{kwargs} which is inspected is \var{exc_info} which, if it does not
+%[- MARK -] -evaluate as false, causes exception information (via a call to
+%[- MARK -] -\function{sys.exc_info()}) to be added to the logging message.
+%[- MARK -] +evaluate as false, causes exception information to be added to the logging
+%[- MARK -] +message. If an exception tuple (in the format returned by
+%[- MARK -] +\function{sys.exc_info()}) is provided, it is used; otherwise,
+%[- MARK -] +\function{sys.exc_info()} is called to get the exception information.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] Logs a message with level \constant{INFO} on the root logger.
+%[- MARK -] The arguments are interpreted as for \function{debug()}.
+%[- MARK -] END DIFF
certo numero di funzioni a livello di modulo.
\begin{funcdesc}{getLogger}{\optional{name}}
@@ -196,6 +307,24 @@
\function{debug()}. Informazioni sull'eccezione verranno aggiunte al
messaggio di log. Questa funzione deve essere chiamata solo da un
handler dell'eccezione.
+%[- MARK -] BEGIN DIFF 004 of 21
+%[- MARK -] @@ 175
+%[- MARK -] The arguments are interpreted as for \function{debug()}. Exception info
+%[- MARK -] is added to the logging message. This function should only be called
+%[- MARK -] from an exception handler.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] +Logs a message with level \var{level} on the root logger.
+%[- MARK -] +The other arguments are interpreted as for \function{debug()}.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{disable}{lvl}
+%[- MARK -] Provides an overriding level \var{lvl} for all loggers which takes
+%[- MARK -] precedence over the logger's own level. When the need arises to
+%[- MARK -] temporarily throttle logging output down across the whole application,
+%[- MARK -] this function can be useful.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{disable}{lvl}
@@ -214,6 +343,60 @@
tutti i livelli usati devono essere registrati usando questa funzione,
i livelli dovrebbero essere interi positivi crescenti all'aumentare
dell'ordine di accuratezza.
+%[- MARK -] BEGIN DIFF 005 of 21
+%[- MARK -] @@ 198
+%[- MARK -] Returns the textual representation of logging level \var{lvl}. If the
+%[- MARK -] level is one of the predefined levels \constant{CRITICAL},
+%[- MARK -] \constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
+%[- MARK -] then you get the corresponding string. If you have associated levels
+%[- MARK -] with names using \function{addLevelName()} then the name you have associated
+%[- MARK -] -with \var{lvl} is returned. Otherwise, the string "Level \%s" \% lvl is
+%[- MARK -] -returned.
+%[- MARK -] +with \var{lvl} is returned. If a numeric value corresponding to one of the
+%[- MARK -] +defined levels is passed in, the corresponding string representation is
+%[- MARK -] +returned. Otherwise, the string "Level \%s" \% lvl is returned.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{makeLogRecord}{attrdict}
+%[- MARK -] Creates and returns a new \class{LogRecord} instance whose attributes are
+%[- MARK -] defined by \var{attrdict}. This function is useful for taking a pickled
+%[- MARK -] \class{LogRecord} attribute dictionary, sent over a socket, and reconstituting
+%[- MARK -] it as a \class{LogRecord} instance at the receiving end.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{basicConfig}{}
+%[- MARK -] +\begin{funcdesc}{basicConfig}{\optional{**kwargs}}
+%[- MARK -] Does basic configuration for the logging system by creating a
+%[- MARK -] \class{StreamHandler} with a default \class{Formatter} and adding it to
+%[- MARK -] the root logger. The functions \function{debug()}, \function{info()},
+%[- MARK -] \function{warning()}, \function{error()} and \function{critical()} will call
+%[- MARK -] \function{basicConfig()} automatically if no handlers are defined for the
+%[- MARK -] root logger.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[Formerly, \function{basicConfig} did not take any keyword
+%[- MARK -] +arguments]{2.4}
+%[- MARK -] +
+%[- MARK -] +The following keyword arguments are supported.
+%[- MARK -] +
+%[- MARK -] +\begin{tableii}{l|l}{code}{Format}{Description}
+%[- MARK -] +\lineii{filename}{Specifies that a FileHandler be created, using the
+%[- MARK -] +specified filename, rather than a StreamHandler.}
+%[- MARK -] +\lineii{filemode}{Specifies the mode to open the file, if filename is
+%[- MARK -] +specified (if filemode is unspecified, it defaults to 'a').}
+%[- MARK -] +\lineii{format}{Use the specified format string for the handler.}
+%[- MARK -] +\lineii{datefmt}{Use the specified date/time format.}
+%[- MARK -] +\lineii{level}{Set the root logger level to the specified level.}
+%[- MARK -] +\lineii{stream}{Use the specified stream to initialize the StreamHandler.
+%[- MARK -] +Note that this argument is incompatible with 'filename' - if both
+%[- MARK -] +are present, 'stream' is ignored.}
+%[- MARK -] +\end{tableii}
+%[- MARK -] +
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{shutdown}{}
+%[- MARK -] Informs the logging system to perform an orderly shutdown by flushing and
+%[- MARK -] closing all handlers.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{getLevelName}{lvl}
@@ -256,6 +439,23 @@
\method{Logger.__init__()}. Questa funzione di solito viene chiamata
prima che ogni logger venga istanziato dalle applicazioni che hanno
la necessità di utilizzare un proprio logger personalizzato.
+%[- MARK -] BEGIN DIFF 006 of 21
+%[- MARK -] @@ 241
+%[- MARK -] the Python standard library.}
+%[- MARK -] \seelink{http://www.red-dove.com/python_logging.html}
+%[- MARK -] {Original Python \module{logging} package}
+%[- MARK -] {This is the original source for the \module{logging}
+%[- MARK -] package. The version of the package available from this
+%[- MARK -] - site is suitable for use with Python 2.1.x and 2.2.x, which
+%[- MARK -] - do not include the \module{logging} package in the standard
+%[- MARK -] + site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x,
+%[- MARK -] + which do not include the \module{logging} package in the standard
+%[- MARK -] library.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{Logger Objects}
+%[- MARK -] END DIFF
\end{funcdesc}
@@ -283,6 +483,38 @@
Se viene valutata come falsa, i messaggi di log non vengono trasmessi
da questo logger o dai logger figli al livello più alto di logger
(superclasse). Il costruttore imposta questo attributo ad 1.
+%[- MARK -] BEGIN DIFF 007 of 21
+%[- MARK -] @@ 263
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{setLevel}{lvl}
+%[- MARK -] Sets the threshold for this logger to \var{lvl}. Logging messages
+%[- MARK -] which are less severe than \var{lvl} will be ignored. When a logger is
+%[- MARK -] created, the level is set to \constant{NOTSET} (which causes all messages
+%[- MARK -] -to be processed in the root logger, or delegation to the parent in non-root
+%[- MARK -] -loggers).
+%[- MARK -] +to be processed when the logger is the root logger, or delegation to the
+%[- MARK -] +parent when the logger is a non-root logger). Note that the root logger
+%[- MARK -] +is created with level \constant{WARNING}.
+%[- MARK -] +
+%[- MARK -] +The term "delegation to the parent" means that if a logger has a level
+%[- MARK -] +of NOTSET, its chain of ancestor loggers is traversed until either an
+%[- MARK -] +ancestor with a level other than NOTSET is found, or the root is
+%[- MARK -] +reached.
+%[- MARK -] +
+%[- MARK -] +If an ancestor is found with a level other than NOTSET, then that
+%[- MARK -] +ancestor's level is treated as the effective level of the logger where
+%[- MARK -] +the ancestor search began, and is used to determine how a logging
+%[- MARK -] +event is handled.
+%[- MARK -] +
+%[- MARK -] +If the root is reached, and it has a level of NOTSET, then all
+%[- MARK -] +messages will be processed. Otherwise, the root's level will be used
+%[- MARK -] +as the effective level.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{isEnabledFor}{lvl}
+%[- MARK -] Indicates if a message of severity \var{lvl} would be processed by
+%[- MARK -] this logger. This method checks first the module-level level set by
+%[- MARK -] END DIFF
\end{datadesc}
\begin{methoddesc}{setLevel}{lvl}
@@ -308,6 +540,25 @@
Altrimenti la gerarchia viene percorsa all'indietro fino alla cima,
fintanto che non viene trovato un valore diverso di \constant{NOTSET}.
Quindi, se il valore viene trovato, viene restituito.
+%[- MARK -] BEGIN DIFF 008 of 21
+%[- MARK -] @@ 286
+%[- MARK -] \begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] Logs a message with level \constant{DEBUG} on this logger.
+%[- MARK -] The \var{msg} is the message format string, and the \var{args} are the
+%[- MARK -] arguments which are merged into \var{msg}. The only keyword argument in
+%[- MARK -] \var{kwargs} which is inspected is \var{exc_info} which, if it does not
+%[- MARK -] -evaluate as false, causes exception information (via a call to
+%[- MARK -] -\function{sys.exc_info()}) to be added to the logging message.
+%[- MARK -] +evaluate as false, causes exception information to be added to the logging
+%[- MARK -] +message. If an exception tuple (as provided by \function{sys.exc_info()})
+%[- MARK -] +is provided, it is used; otherwise, \function{sys.exc_info()} is called
+%[- MARK -] +to get the exception information.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] Logs a message with level \constant{INFO} on this logger.
+%[- MARK -] The arguments are interpreted as for \method{debug()}.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
@@ -340,6 +591,21 @@
Registra un messaggio con livello \constant{CRITICAL} su questo
logger. Gli argomenti vengono interpretati come nel caso di
\method{debug()}.
+%[- MARK -] BEGIN DIFF 009 of 21
+%[- MARK -] @@ 311
+%[- MARK -] Logs a message with level \constant{CRITICAL} on this logger.
+%[- MARK -] The arguments are interpreted as for \method{debug()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
+%[- MARK -] -Logs a message with level \var{lvl} on this logger.
+%[- MARK -] +Logs a message with integer level \var{lvl} on this logger.
+%[- MARK -] The other arguments are interpreted as for \method{debug()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{exception}{msg\optional{, *args}}
+%[- MARK -] Logs a message with level \constant{ERROR} on this logger.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
@@ -392,6 +658,350 @@
\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
Questo è un metodo factory che può essere sovrascritto in classi
derivate per creare istanze specializzate di \class{LogRecord}.
+%[- MARK -] BEGIN DIFF 010 of 21
+%[- MARK -] @@ 361
+%[- MARK -] \begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
+%[- MARK -] This is a factory method which can be overridden in subclasses to create
+%[- MARK -] specialized \class{LogRecord} instances.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\subsection{Basic example \label{minimal-example}}
+%[- MARK -] +
+%[- MARK -] +\versionchanged[formerly \function{basicConfig} did not take any keyword
+%[- MARK -] +arguments]{2.4}
+%[- MARK -] +
+%[- MARK -] +The \module{logging} package provides a lot of flexibility, and its
+%[- MARK -] +configuration can appear daunting. This section demonstrates that simple
+%[- MARK -] +use of the logging package is possible.
+%[- MARK -] +
+%[- MARK -] +The simplest example shows logging to the console:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging
+%[- MARK -] +
+%[- MARK -] +logging.debug('A debug message')
+%[- MARK -] +logging.info('Some information')
+%[- MARK -] +logging.warning('A shot across the bows')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +If you run the above script, you'll see this:
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +WARNING:root:A shot across the bows
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Because no particular logger was specified, the system used the root logger.
+%[- MARK -] +The debug and info messages didn't appear because by default, the root
+%[- MARK -] +logger is configured to only handle messages with a severity of WARNING
+%[- MARK -] +or above. The message format is also a configuration default, as is the output
+%[- MARK -] +destination of the messages - \code{sys.stderr}. The severity level,
+%[- MARK -] +the message format and destination can be easily changed, as shown in
+%[- MARK -] +the example below:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging
+%[- MARK -] +
+%[- MARK -] +logging.basicConfig(level=logging.DEBUG,
+%[- MARK -] + format='%(asctime)s %(levelname)s %(message)s',
+%[- MARK -] + filename='/tmp/myapp.log',
+%[- MARK -] + filemode='w')
+%[- MARK -] +logging.debug('A debug message')
+%[- MARK -] +logging.info('Some information')
+%[- MARK -] +logging.warning('A shot across the bows')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The \method{basicConfig()} method is used to change the configuration
+%[- MARK -] +defaults, which results in output (written to \code{/tmp/myapp.log})
+%[- MARK -] +which should look something like the following:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +2004-07-02 13:00:08,743 DEBUG A debug message
+%[- MARK -] +2004-07-02 13:00:08,743 INFO Some information
+%[- MARK -] +2004-07-02 13:00:08,743 WARNING A shot across the bows
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +This time, all messages with a severity of DEBUG or above were handled,
+%[- MARK -] +and the format of the messages was also changed, and output went to the
+%[- MARK -] +specified file rather than the console.
+%[- MARK -] +
+%[- MARK -] +Formatting uses standard Python string formatting - see section
+%[- MARK -] +\ref{typesseq-strings}. The format string takes the following
+%[- MARK -] +common specifiers. For a complete list of specifiers, consult the
+%[- MARK -] +\class{Formatter} documentation.
+%[- MARK -] +
+%[- MARK -] +\begin{tableii}{l|l}{code}{Format}{Description}
+%[- MARK -] +\lineii{\%(name)s} {Name of the logger (logging channel).}
+%[- MARK -] +\lineii{\%(levelname)s}{Text logging level for the message
+%[- MARK -] + (\code{'DEBUG'}, \code{'INFO'},
+%[- MARK -] + \code{'WARNING'}, \code{'ERROR'},
+%[- MARK -] + \code{'CRITICAL'}).}
+%[- MARK -] +\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
+%[- MARK -] + was created. By default this is of the form
+%[- MARK -] + ``2003-07-08 16:49:45,896'' (the numbers after the
+%[- MARK -] + comma are millisecond portion of the time).}
+%[- MARK -] +\lineii{\%(message)s} {The logged message.}
+%[- MARK -] +\end{tableii}
+%[- MARK -] +
+%[- MARK -] +To change the date/time format, you can pass an additional keyword parameter,
+%[- MARK -] +\var{datefmt}, as in the following:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging
+%[- MARK -] +
+%[- MARK -] +logging.basicConfig(level=logging.DEBUG,
+%[- MARK -] + format='%(asctime)s %(levelname)-8s %(message)s',
+%[- MARK -] + datefmt='%a, %d %b %Y %H:%M:%S',
+%[- MARK -] + filename='/temp/myapp.log',
+%[- MARK -] + filemode='w')
+%[- MARK -] +logging.debug('A debug message')
+%[- MARK -] +logging.info('Some information')
+%[- MARK -] +logging.warning('A shot across the bows')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +which would result in output like
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
+%[- MARK -] +Fri, 02 Jul 2004 13:06:18 INFO Some information
+%[- MARK -] +Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The date format string follows the requirements of \function{strftime()} -
+%[- MARK -] +see the documentation for the \refmodule{time} module.
+%[- MARK -] +
+%[- MARK -] +If, instead of sending logging output to the console or a file, you'd rather
+%[- MARK -] +use a file-like object which you have created separately, you can pass it
+%[- MARK -] +to \function{basicConfig()} using the \var{stream} keyword argument. Note
+%[- MARK -] +that if both \var{stream} and \var{filename} keyword arguments are passed,
+%[- MARK -] +the \var{stream} argument is ignored.
+%[- MARK -] +
+%[- MARK -] +Of course, you can put variable information in your output. To do this,
+%[- MARK -] +simply have the message be a format string and pass in additional arguments
+%[- MARK -] +containing the variable information, as in the following example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging
+%[- MARK -] +
+%[- MARK -] +logging.basicConfig(level=logging.DEBUG,
+%[- MARK -] + format='%(asctime)s %(levelname)-8s %(message)s',
+%[- MARK -] + datefmt='%a, %d %b %Y %H:%M:%S',
+%[- MARK -] + filename='/temp/myapp.log',
+%[- MARK -] + filemode='w')
+%[- MARK -] +logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +which would result in
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\subsection{Logging to multiple destinations \label{multiple-destinations}}
+%[- MARK -] +
+%[- MARK -] +Let's say you want to log to console and file with different message formats
+%[- MARK -] +and in differing circumstances. Say you want to log messages with levels
+%[- MARK -] +of DEBUG and higher to file, and those messages at level INFO and higher to
+%[- MARK -] +the console. Let's also assume that the file should contain timestamps, but
+%[- MARK -] +the console messages should not. Here's how you can achieve this:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging
+%[- MARK -] +
+%[- MARK -] +# set up logging to file - see previous section for more details
+%[- MARK -] +logging.basicConfig(level=logging.DEBUG,
+%[- MARK -] + format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
+%[- MARK -] + datefmt='%m-%d %H:%M',
+%[- MARK -] + filename='/temp/myapp.log',
+%[- MARK -] + filemode='w')
+%[- MARK -] +# define a Handler which writes INFO messages or higher to the sys.stderr
+%[- MARK -] +console = logging.StreamHandler()
+%[- MARK -] +console.setLevel(logging.INFO)
+%[- MARK -] +# set a format which is simpler for console use
+%[- MARK -] +formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
+%[- MARK -] +# tell the handler to use this format
+%[- MARK -] +console.setFormatter(formatter)
+%[- MARK -] +# add the handler to the root logger
+%[- MARK -] +logging.getLogger('').addHandler(console)
+%[- MARK -] +
+%[- MARK -] +# Now, we can log to the root logger, or any other logger. First the root...
+%[- MARK -] +logging.info('Jackdaws love my big sphinx of quartz.')
+%[- MARK -] +
+%[- MARK -] +# Now, define a couple of other loggers which might represent areas in your
+%[- MARK -] +# application:
+%[- MARK -] +
+%[- MARK -] +logger1 = logging.getLogger('myapp.area1')
+%[- MARK -] +logger2 = logging.getLogger('myapp.area2')
+%[- MARK -] +
+%[- MARK -] +logger1.debug('Quick zephyrs blow, vexing daft Jim.')
+%[- MARK -] +logger1.info('How quickly daft jumping zebras vex.')
+%[- MARK -] +logger2.warning('Jail zesty vixen who grabbed pay from quack.')
+%[- MARK -] +logger2.error('The five boxing wizards jump quickly.')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +When you run this, on the console you will see
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +root : INFO Jackdaws love my big sphinx of quartz.
+%[- MARK -] +myapp.area1 : INFO How quickly daft jumping zebras vex.
+%[- MARK -] +myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
+%[- MARK -] +myapp.area2 : ERROR The five boxing wizards jump quickly.
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +and in the file you will see something like
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
+%[- MARK -] +10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
+%[- MARK -] +10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
+%[- MARK -] +10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
+%[- MARK -] +10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +As you can see, the DEBUG message only shows up in the file. The other
+%[- MARK -] +messages are sent to both destinations.
+%[- MARK -] +
+%[- MARK -] +This example uses console and file handlers, but you can use any number and
+%[- MARK -] +combination of handlers you choose.
+%[- MARK -] +
+%[- MARK -] +\subsection{Sending and receiving logging events across a network
+%[- MARK -] +\label{network-logging}}
+%[- MARK -] +
+%[- MARK -] +Let's say you want to send logging events across a network, and handle them
+%[- MARK -] +at the receiving end. A simple way of doing this is attaching a
+%[- MARK -] +\class{SocketHandler} instance to the root logger at the sending end:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import logging, logging.handlers
+%[- MARK -] +
+%[- MARK -] +rootLogger = logging.getLogger('')
+%[- MARK -] +rootLogger.setLevel(logging.DEBUG)
+%[- MARK -] +socketHandler = logging.handlers.SocketHandler('localhost',
+%[- MARK -] + logging.handlers.DEFAULT_TCP_LOGGING_PORT)
+%[- MARK -] +# don't bother with a formatter, since a socket handler sends the event as
+%[- MARK -] +# an unformatted pickle
+%[- MARK -] +rootLogger.addHandler(socketHandler)
+%[- MARK -] +
+%[- MARK -] +# Now, we can log to the root logger, or any other logger. First the root...
+%[- MARK -] +logging.info('Jackdaws love my big sphinx of quartz.')
+%[- MARK -] +
+%[- MARK -] +# Now, define a couple of other loggers which might represent areas in your
+%[- MARK -] +# application:
+%[- MARK -] +
+%[- MARK -] +logger1 = logging.getLogger('myapp.area1')
+%[- MARK -] +logger2 = logging.getLogger('myapp.area2')
+%[- MARK -] +
+%[- MARK -] +logger1.debug('Quick zephyrs blow, vexing daft Jim.')
+%[- MARK -] +logger1.info('How quickly daft jumping zebras vex.')
+%[- MARK -] +logger2.warning('Jail zesty vixen who grabbed pay from quack.')
+%[- MARK -] +logger2.error('The five boxing wizards jump quickly.')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +At the receiving end, you can set up a receiver using the
+%[- MARK -] +\module{SocketServer} module. Here is a basic working example:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import cPickle
+%[- MARK -] +import logging
+%[- MARK -] +import logging.handlers
+%[- MARK -] +import SocketServer
+%[- MARK -] +import struct
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
+%[- MARK -] + """Handler for a streaming logging request.
+%[- MARK -] +
+%[- MARK -] + This basically logs the record using whatever logging policy is
+%[- MARK -] + configured locally.
+%[- MARK -] + """
+%[- MARK -] +
+%[- MARK -] + def handle(self):
+%[- MARK -] + """
+%[- MARK -] + Handle multiple requests - each expected to be a 4-byte length,
+%[- MARK -] + followed by the LogRecord in pickle format. Logs the record
+%[- MARK -] + according to whatever policy is configured locally.
+%[- MARK -] + """
+%[- MARK -] + while 1:
+%[- MARK -] + chunk = self.connection.recv(4)
+%[- MARK -] + if len(chunk) < 4:
+%[- MARK -] + break
+%[- MARK -] + slen = struct.unpack(">L", chunk)[0]
+%[- MARK -] + chunk = self.connection.recv(slen)
+%[- MARK -] + while len(chunk) < slen:
+%[- MARK -] + chunk = chunk + self.connection.recv(slen - len(chunk))
+%[- MARK -] + obj = self.unPickle(chunk)
+%[- MARK -] + record = logging.makeLogRecord(obj)
+%[- MARK -] + self.handleLogRecord(record)
+%[- MARK -] +
+%[- MARK -] + def unPickle(self, data):
+%[- MARK -] + return cPickle.loads(data)
+%[- MARK -] +
+%[- MARK -] + def handleLogRecord(self, record):
+%[- MARK -] + # if a name is specified, we use the named logger rather than the one
+%[- MARK -] + # implied by the record.
+%[- MARK -] + if self.server.logname is not None:
+%[- MARK -] + name = self.server.logname
+%[- MARK -] + else:
+%[- MARK -] + name = record.name
+%[- MARK -] + logger = logging.getLogger(name)
+%[- MARK -] + # N.B. EVERY record gets logged. This is because Logger.handle
+%[- MARK -] + # is normally called AFTER logger-level filtering. If you want
+%[- MARK -] + # to do filtering, do it at the client end to save wasting
+%[- MARK -] + # cycles and network bandwidth!
+%[- MARK -] + logger.handle(record)
+%[- MARK -] +
+%[- MARK -] +class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
+%[- MARK -] + """simple TCP socket-based logging receiver suitable for testing.
+%[- MARK -] + """
+%[- MARK -] +
+%[- MARK -] + allow_reuse_address = 1
+%[- MARK -] +
+%[- MARK -] + def __init__(self, host='localhost',
+%[- MARK -] + port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
+%[- MARK -] + handler=LogRecordStreamHandler):
+%[- MARK -] + SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
+%[- MARK -] + self.abort = 0
+%[- MARK -] + self.timeout = 1
+%[- MARK -] + self.logname = None
+%[- MARK -] +
+%[- MARK -] + def serve_until_stopped(self):
+%[- MARK -] + import select
+%[- MARK -] + abort = 0
+%[- MARK -] + while not abort:
+%[- MARK -] + rd, wr, ex = select.select([self.socket.fileno()],
+%[- MARK -] + [], [],
+%[- MARK -] + self.timeout)
+%[- MARK -] + if rd:
+%[- MARK -] + self.handle_request()
+%[- MARK -] + abort = self.abort
+%[- MARK -] +
+%[- MARK -] +def main():
+%[- MARK -] + logging.basicConfig(
+%[- MARK -] + format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
+%[- MARK -] + tcpserver = LogRecordSocketReceiver()
+%[- MARK -] + print "About to start TCP server..."
+%[- MARK -] + tcpserver.serve_until_stopped()
+%[- MARK -] +
+%[- MARK -] +if __name__ == "__main__":
+%[- MARK -] + main()
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +First run the server, and then the client. On the client side, nothing is
+%[- MARK -] +printed on the console; on the server side, you should see something like:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +About to start TCP server...
+%[- MARK -] + 59 root INFO Jackdaws love my big sphinx of quartz.
+%[- MARK -] + 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
+%[- MARK -] + 69 myapp.area1 INFO How quickly daft jumping zebras vex.
+%[- MARK -] + 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
+%[- MARK -] + 69 myapp.area2 ERROR The five boxing wizards jump quickly.
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] \subsection{Handler Objects}
+%[- MARK -]
+%[- MARK -] Handlers have the following attributes and methods. Note that
+%[- MARK -] \class{Handler} is never instantiated directly; this class acts as a
+%[- MARK -] base for more useful subclasses. However, the \method{__init__()}
+%[- MARK -] END DIFF
\end{methoddesc}
\subsection{Oggetti Handler}
@@ -463,6 +1073,31 @@
emette lo specifico record di logging. Sostituisce l'attuale
emissione del record con una acquisizione/rilascio del lock del thread
di I/O.
+%[- MARK -] BEGIN DIFF 011 of 21
+%[- MARK -] @@ 427
+%[- MARK -] filters which may have been added to the handler. Wraps the actual
+%[- MARK -] emission of the record with acquisition/release of the I/O thread
+%[- MARK -] lock.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}{handleError}{}
+%[- MARK -] +\begin{methoddesc}{handleError}{record}
+%[- MARK -] This method should be called from handlers when an exception is
+%[- MARK -] -encountered during an emit() call. By default it does nothing,
+%[- MARK -] +encountered during an \method{emit()} call. By default it does nothing,
+%[- MARK -] which means that exceptions get silently ignored. This is what is
+%[- MARK -] mostly wanted for a logging system - most users will not care
+%[- MARK -] about errors in the logging system, they are more interested in
+%[- MARK -] application errors. You could, however, replace this with a custom
+%[- MARK -] -handler if you wish.
+%[- MARK -] +handler if you wish. The specified record is the one which was being
+%[- MARK -] +processed when the exception occurred.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{format}{record}
+%[- MARK -] Do formatting for a record - if a formatter is set, use it.
+%[- MARK -] Otherwise, use the default formatter for the module.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{handleError}{}
@@ -542,6 +1177,21 @@
\subsubsection{RotatingFileHandler}
La classe \class{RotatingFileHandler} supporta la rotazione dei file
+%[- MARK -] BEGIN DIFF 012 of 21
+%[- MARK -] @@ 504
+%[- MARK -] \begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
+%[- MARK -] maxBytes\optional{, backupCount}}}}
+%[- MARK -] Returns a new instance of the \class{RotatingFileHandler} class. The
+%[- MARK -] specified file is opened and used as the stream for logging. If
+%[- MARK -] \var{mode} is not specified, \code{'a'} is used. By default, the
+%[- MARK -] -file grows indefinitely.
+%[- MARK -] +file grows indefinitely.
+%[- MARK -]
+%[- MARK -] You can use the \var{maxBytes} and
+%[- MARK -] \var{backupCount} values to allow the file to \dfn{rollover} at a
+%[- MARK -] predetermined size. When the size is about to be exceeded, the file is
+%[- MARK -] closed and a new file is silently opened for output. Rollover occurs
+%[- MARK -] END DIFF
di log sul disco.
\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
@@ -550,6 +1200,76 @@
\class{RotatingFileHandler}. Il file specificato viene aperto ed
utilizzato come flusso per il logging. Se \var{mode} non viene
specificato, viene adottato \constant{'a'}.
+%[- MARK -] BEGIN DIFF 013 of 21
+%[- MARK -] @@ 520
+%[- MARK -] \file{app.log}, you would get \file{app.log},
+%[- MARK -] \file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being
+%[- MARK -] written to is always \file{app.log}. When this file is filled, it is
+%[- MARK -] closed and renamed to \file{app.log.1}, and if files \file{app.log.1},
+%[- MARK -] \file{app.log.2}, etc. exist, then they are renamed to \file{app.log.2},
+%[- MARK -] -\file{app.log.3} etc. respectively.
+%[- MARK -] +\file{app.log.3} etc. respectively.
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{doRollover}{}
+%[- MARK -] +Does a rollover, as described above.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{emit}{record}
+%[- MARK -] +Outputs the record to the file, catering for rollover as described previously.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\subsubsection{TimedRotatingFileHandler}
+%[- MARK -] +
+%[- MARK -] +The \class{TimedRotatingFileHandler} class supports rotation of disk log files
+%[- MARK -] +at certain timed intervals.
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{TimedRotatingFileHandler}{filename
+%[- MARK -] + \optional{,when
+%[- MARK -] + \optional{,interval
+%[- MARK -] + \optional{,backupCount}}}}
+%[- MARK -] +
+%[- MARK -] +Returns a new instance of the \class{TimedRotatingFileHandler} class. The
+%[- MARK -] +specified file is opened and used as the stream for logging. On rotating
+%[- MARK -] +it also sets the filename suffix. Rotating happens based on the product
+%[- MARK -] +of \var{when} and \var{interval}.
+%[- MARK -] +
+%[- MARK -] +You can use the \var{when} to specify the type of \var{interval}. The
+%[- MARK -] +list of possible values is, note that they are not case sensitive:
+%[- MARK -] +
+%[- MARK -] +\begin{tableii}{l|l}{}{Value}{Type of interval}
+%[- MARK -] + \lineii{S}{Seconds}
+%[- MARK -] + \lineii{M}{Minutes}
+%[- MARK -] + \lineii{H}{Hours}
+%[- MARK -] + \lineii{D}{Days}
+%[- MARK -] + \lineii{W}{Week day (0=Monday)}
+%[- MARK -] + \lineii{midnight}{Roll over at midnight}
+%[- MARK -] +\end{tableii}
+%[- MARK -] +
+%[- MARK -] +If \var{backupCount} is non-zero, the system will save old log files by
+%[- MARK -] +appending the extensions ".1", ".2" etc., to the filename. For example,
+%[- MARK -] +with a \var{backupCount} of 5 and a base file name of \file{app.log},
+%[- MARK -] +you would get \file{app.log}, \file{app.log.1}, \file{app.log.2}, up to
+%[- MARK -] +\file{app.log.5}. The file being written to is always \file{app.log}.
+%[- MARK -] +When this file is filled, it is closed and renamed to \file{app.log.1},
+%[- MARK -] +and if files \file{app.log.1}, \file{app.log.2}, etc. exist, then they
+%[- MARK -] +are renamed to \file{app.log.2}, \file{app.log.3} etc. respectively.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{doRollover}{}
+%[- MARK -] Does a rollover, as described above.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{emit}{record}
+%[- MARK -] Outputs the record to the file, catering for rollover as described
+%[- MARK -] -in \method{setRollover()}.
+%[- MARK -] +above.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \subsubsection{SocketHandler}
+%[- MARK -]
+%[- MARK -] The \class{SocketHandler} class sends logging output to a network
+%[- MARK -] END DIFF
Non esiste un limite predefinito sulla dimensione del file.
Potete utilizzare i valori \var{maxBytes} e \var{backupCount} per
@@ -756,6 +1476,22 @@
\subsubsection{SMTPHandler}
La classe \class{SMTPHandler} supporta l'invio dei messaggi di loggin
+%[- MARK -] BEGIN DIFF 014 of 21
+%[- MARK -] @@ 707
+%[- MARK -] address via SMTP.
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
+%[- MARK -] Returns a new instance of the \class{SMTPHandler} class. The
+%[- MARK -] instance is initialized with the from and to addresses and subject
+%[- MARK -] -line of the email. The \var{toaddrs} should be a list of strings without
+%[- MARK -] -domain names (That's what the \var{mailhost} is for). To specify a
+%[- MARK -] +line of the email. The \var{toaddrs} should be a list of strings. To specify a
+%[- MARK -] non-standard SMTP port, use the (host, port) tuple format for the
+%[- MARK -] \var{mailhost} argument. If you use a string, the standard SMTP port
+%[- MARK -] is used.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
ad un indirizzo email via SMTP.
\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
@@ -877,6 +1613,20 @@
sezione \ref{typesseq-strings}, ``Operazioni sulla formattazione delle
stringhe'' per ulteriori informazioni in merito.
+%[- MARK -] BEGIN DIFF 015 of 21
+%[- MARK -] @@ 843
+%[- MARK -] ``2003-07-08 16:49:45,896'' (the numbers after the
+%[- MARK -] comma are millisecond portion of the time).}
+%[- MARK -] \lineii{\%(msecs)d} {Millisecond portion of the time when the
+%[- MARK -] \class{LogRecord} was created.}
+%[- MARK -] \lineii{\%(thread)d} {Thread ID (if available).}
+%[- MARK -] +\lineii{\%(threadName)s} {Thread name (if available).}
+%[- MARK -] \lineii{\%(process)d} {Process ID (if available).}
+%[- MARK -] \lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.}
+%[- MARK -] \end{tableii}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
+%[- MARK -] END DIFF
Attualmente, le chiavi di mappatura utili in un \class{LogRecord} sono:
\begin{tableii}{l|l}{code}{Formato}{Descrizione}
@@ -983,6 +1733,23 @@
args per creare un campo messaggio nel record. Il record include
anche informazioni su quando il record è stato creato, la riga
sorgente da cui la chiamata di logging è stata fatta, ed ogni
+%[- MARK -] BEGIN DIFF 016 of 21
+%[- MARK -] @@ 914
+%[- MARK -] using msg \% args to create the message field of the record. The record
+%[- MARK -] also includes information such as when the record was created, the
+%[- MARK -] source line where the logging call was made, and any exception
+%[- MARK -] information to be logged.
+%[- MARK -]
+%[- MARK -] -\class{LogRecord} has no methods; it's just a repository for
+%[- MARK -] -information about the logging event. The only reason it's a class
+%[- MARK -] -rather than a dictionary is to facilitate extension.
+%[- MARK -] -
+%[- MARK -] \begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
+%[- MARK -] exc_info}
+%[- MARK -] Returns an instance of \class{LogRecord} initialized with interesting
+%[- MARK -] information. The \var{name} is the logger name; \var{lvl} is the
+%[- MARK -] numeric level; \var{pathname} is the absolute pathname of the source
+%[- MARK -] END DIFF
informazione sulle eccezioni da registrare.
\class{LogRecord} non ha metodi: è solo un deposito di informazioni circa
@@ -1002,6 +1769,24 @@
è la tupla di eccezione ottenuta attraverso la chiamata
\function{sys.exc_info() } (o \constant{None}, se nessuna informazione
di eccezione è disponibile).
+%[- MARK -] BEGIN DIFF 017 of 21
+%[- MARK -] @@ 932
+%[- MARK -] \var{exc_info} is the exception tuple obtained by calling
+%[- MARK -] \function{sys.exc_info() }(or \constant{None}, if no exception information
+%[- MARK -] is available).
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}{getMessage}{}
+%[- MARK -] +Returns the message for this \class{LogRecord} instance after merging any
+%[- MARK -] +user-supplied arguments with the message.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \subsection{Thread Safety}
+%[- MARK -]
+%[- MARK -] The logging module is intended to be thread-safe without any special work
+%[- MARK -] needing to be done by its clients. It achieves this though using threading
+%[- MARK -] locks; there is one lock to serialize access to the module's shared data,
+%[- MARK -] END DIFF
\end{classdesc}
\subsection{Sicurezza dei thread}
@@ -1035,6 +1820,24 @@
fornisce un meccanismo per offrire una scelta e caricare la
configurazione voluta). In modo predefinito viene passato a
ConfigParser e può essere specificato nell'argomento \var{defaults}.
+%[- MARK -] BEGIN DIFF 018 of 21
+%[- MARK -] @@ 969
+%[- MARK -] configurations. If no port is specified, the module's default
+%[- MARK -] \constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
+%[- MARK -] will be sent as a file suitable for processing by \function{fileConfig()}.
+%[- MARK -] Returns a \class{Thread} instance on which you can call \method{start()}
+%[- MARK -] to start the server, and which you can \method{join()} when appropriate.
+%[- MARK -] -To stop the server, call \function{stopListening()}.
+%[- MARK -] +To stop the server, call \function{stopListening()}. To send a configuration
+%[- MARK -] +to the socket, read in the configuration file and send it to the socket
+%[- MARK -] +as a string of bytes preceded by a four-byte length packed in binary using
+%[- MARK -] +struct.\code{pack(">L", n)}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{stopListening}{}
+%[- MARK -] Stops the listening server which was created with a call to
+%[- MARK -] \function{listen()}. This is typically called before calling \method{join()}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{listen}{\optional{port}}
@@ -1121,6 +1924,21 @@
handlers=hand01
propagate=1
qualname=compiler.parser
+%[- MARK -] BEGIN DIFF 019 of 21
+%[- MARK -] @@ 1049
+%[- MARK -] to determine the effective level of the logger. The \code{propagate}
+%[- MARK -] entry is set to 1 to indicate that messages must propagate to handlers
+%[- MARK -] higher up the logger hierarchy from this logger, or 0 to indicate that
+%[- MARK -] messages are \strong{not} propagated to handlers up the hierarchy. The
+%[- MARK -] \code{qualname} entry is the hierarchical channel name of the logger,
+%[- MARK -] -for example, the name used by the application to get the logger.
+%[- MARK -] +that is to say the name used by the application to get the logger.
+%[- MARK -]
+%[- MARK -] Sections which specify handler configuration are exemplified by the
+%[- MARK -] following.
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\end{verbatim}
Le voci degli \code{handlers} e di \code{level} vengono interpretate
@@ -1186,6 +2004,43 @@
class=handlers.SysLogHandler
level=ERROR
formatter=form05
+%[- MARK -] BEGIN DIFF 020 of 21
+%[- MARK -] @@ 1105
+%[- MARK -] level=ERROR
+%[- MARK -] formatter=form05
+%[- MARK -] args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
+%[- MARK -]
+%[- MARK -] [handler_hand06]
+%[- MARK -] -class=NTEventLogHandler
+%[- MARK -] +class=handlers.NTEventLogHandler
+%[- MARK -] level=CRITICAL
+%[- MARK -] formatter=form06
+%[- MARK -] args=('Python Application', '', 'Application')
+%[- MARK -]
+%[- MARK -] [handler_hand07]
+%[- MARK -] -class=SMTPHandler
+%[- MARK -] +class=handlers.SMTPHandler
+%[- MARK -] level=WARN
+%[- MARK -] formatter=form07
+%[- MARK -] args=('localhost', 'from a abc', ['user1 a abc', 'user2 a xyz'], 'Logger Subject')
+%[- MARK -]
+%[- MARK -] [handler_hand08]
+%[- MARK -] -class=MemoryHandler
+%[- MARK -] +class=handlers.MemoryHandler
+%[- MARK -] level=NOTSET
+%[- MARK -] formatter=form08
+%[- MARK -] target=
+%[- MARK -] args=(10, ERROR)
+%[- MARK -]
+%[- MARK -] [handler_hand09]
+%[- MARK -] -class=HTTPHandler
+%[- MARK -] +class=handlers.HTTPHandler
+%[- MARK -] level=NOTSET
+%[- MARK -] formatter=form09
+%[- MARK -] args=('localhost:9022', '/log', 'GET')
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] END DIFF
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
[handler_hand06]
@@ -1221,6 +2076,56 @@
[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
+%[- MARK -] BEGIN DIFF 021 of 21
+%[- MARK -] @@ 1145
+%[- MARK -] string. If empty, the package substitutes ISO8601 format date/times, which
+%[- MARK -] is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
+%[- MARK -] The ISO8601 format also specifies milliseconds, which are appended to the
+%[- MARK -] result of using the above format string, with a comma separator. An example
+%[- MARK -] time in ISO8601 format is \code{2003-01-23 00:29:50,411}.
+%[- MARK -] -
+%[- MARK -] -\subsection{Using the logging package}
+%[- MARK -] -
+%[- MARK -] -\subsubsection{Basic example - log to a file}
+%[- MARK -] -
+%[- MARK -] -Here's a simple logging example that just logs to a file. In order,
+%[- MARK -] -it creates a \class{Logger} instance, then a \class{FileHandler}
+%[- MARK -] -and a \class{Formatter}. It attaches the \class{Formatter} to the
+%[- MARK -] -\class{FileHandler}, then the \class{FileHandler} to the \class{Logger}.
+%[- MARK -] -Finally, it sets a debug level for the logger.
+%[- MARK -] -
+%[- MARK -] -\begin{verbatim}
+%[- MARK -] -import logging
+%[- MARK -] -logger = logging.getLogger('myapp')
+%[- MARK -] -hdlr = logging.FileHandler('/var/tmp/myapp.log')
+%[- MARK -] -formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
+%[- MARK -] -hdlr.setFormatter(formatter)
+%[- MARK -] -logger.addHandler(hdlr)
+%[- MARK -] -logger.setLevel(logging.WARNING)
+%[- MARK -] -\end{verbatim}
+%[- MARK -] -
+%[- MARK -] -We can use this logger object now to write entries to the log file:
+%[- MARK -] -
+%[- MARK -] -\begin{verbatim}
+%[- MARK -] -logger.error('We have a problem')
+%[- MARK -] -logger.info('While this is just chatty')
+%[- MARK -] -\end{verbatim}
+%[- MARK -] -
+%[- MARK -] -If we look in the file that was created, we'll see something like this:
+%[- MARK -] -\begin{verbatim}
+%[- MARK -] -2003-07-08 16:49:45,896 ERROR We have a problem
+%[- MARK -] -\end{verbatim}
+%[- MARK -] -
+%[- MARK -] -The info message was not written to the file: we called the
+%[- MARK -] -\method{setLevel()} method to say we only wanted \constant{WARNING} or
+%[- MARK -] -worse, so the info message is discarded.
+%[- MARK -] -
+%[- MARK -] -The timestamp is of the form
+%[- MARK -] -``year-month-day hour:minutes:seconds,milliseconds.''
+%[- MARK -] -Note that despite the three digits of precision in the milliseconds field,
+%[- MARK -] -not all systems provide time with this much precision.
+%[- MARK -] -
+%[- MARK -] END DIFF
\end{verbatim}
La voce \code{format} è la stringa di formato principale, e la voce
Modified: python/python/Doc/branches/2.4.3/lib/libmarshal.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmarshal.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmarshal.tex Fri Jun 2 12:52:55 2006
@@ -65,6 +65,34 @@
Esistono funzioni di lettura/scrittura sui file simili alle funzioni che operano
sulle stringhe.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 60
+%[- MARK -] There are functions that read/write files as well as functions
+%[- MARK -] operating on strings.
+%[- MARK -]
+%[- MARK -] The module defines these functions:
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{dump}{value, file}
+%[- MARK -] +\begin{funcdesc}{dump}{value, file\optional{, version}}
+%[- MARK -] Write the value on the open file. The value must be a supported
+%[- MARK -] type. The file must be an open file object such as
+%[- MARK -] \code{sys.stdout} or returned by \function{open()} or
+%[- MARK -] \function{posix.popen()}. It must be opened in binary mode
+%[- MARK -] (\code{'wb'} or \code{'w+b'}).
+%[- MARK -]
+%[- MARK -] If the value has (or contains an object that has) an unsupported type,
+%[- MARK -] a \exception{ValueError} exception is raised --- but garbage data
+%[- MARK -] will also be written to the file. The object will not be properly
+%[- MARK -] read back by \function{load()}.
+%[- MARK -] +
+%[- MARK -] + \versionadded[The \var{version} argument indicates the data
+%[- MARK -] + format that \code{dump} should use (see below)]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{load}{file}
+%[- MARK -] Read one value from the open file and return it. If no valid value
+%[- MARK -] is read, raise \exception{EOFError}, \exception{ValueError} or
+%[- MARK -] END DIFF
Il modulo definisce queste funzioni:
\begin{funcdesc}{dump}{value, file}
@@ -91,6 +119,41 @@
serializzato (da marshal) con \function{dump()}, \function{load()},
sostituirà \code{None} ai tipi che non possono venire
deserializzati.}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 84
+%[- MARK -] \warning{If an object containing an unsupported type was
+%[- MARK -] marshalled with \function{dump()}, \function{load()} will substitute
+%[- MARK -] \code{None} for the unmarshallable type.}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{dumps}{value}
+%[- MARK -] +\begin{funcdesc}{dumps}{value\optional{, version}}
+%[- MARK -] Return the string that would be written to a file by
+%[- MARK -] \code{dump(\var{value}, \var{file})}. The value must be a supported
+%[- MARK -] type. Raise a \exception{ValueError} exception if value has (or
+%[- MARK -] contains an object that has) an unsupported type.
+%[- MARK -] +
+%[- MARK -] + \versionadded[The \var{version} argument indicates the data
+%[- MARK -] + format that \code{dumps} should use (see below)]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{loads}{string}
+%[- MARK -] Convert the string to a value. If no valid value is found, raise
+%[- MARK -] \exception{EOFError}, \exception{ValueError} or
+%[- MARK -] \exception{TypeError}. Extra characters in the string are ignored.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +In addition, the following constants are defined:
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{version}
+%[- MARK -] + Indicates the format that the module uses. Version 0 is the
+%[- MARK -] + historical format, version 1 (added in Python 2.4) shares
+%[- MARK -] + interned strings. The current version is 1.
+%[- MARK -] +
+%[- MARK -] + \versionadded{2.4}
+%[- MARK -] +\end{datadesc}
+%[- MARK -] \ No newline at end of file
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{dumps}{valore}
Modified: python/python/Doc/branches/2.4.3/lib/libmath.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmath.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmath.tex Fri Jun 2 12:52:55 2006
@@ -15,6 +15,244 @@
li supportano e quelle che non lo fanno. Ricevere un'eccezione piuttosto che
un risultato complesso consente di rilevare immediatamente la presenza di inaspettati numeri
complessi usati come un parametro, cosìcchè il programmatore possa
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 16
+%[- MARK -] complex result allows earlier detection of the unexpected complex
+%[- MARK -] number used as a parameter, so that the programmer can determine how
+%[- MARK -] and why it was generated in the first place.
+%[- MARK -]
+%[- MARK -] The following functions are provided by this module. Except
+%[- MARK -] -when explicitly noted otherwise, all return values are floats:
+%[- MARK -] +when explicitly noted otherwise, all return values are floats.
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{acos}{x}
+%[- MARK -] -Return the arc cosine of \var{x}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{asin}{x}
+%[- MARK -] -Return the arc sine of \var{x}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{atan}{x}
+%[- MARK -] -Return the arc tangent of \var{x}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{atan2}{y, x}
+%[- MARK -] -Return \code{atan(\var{y} / \var{x})}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +Number-theoretic and representation functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{ceil}{x}
+%[- MARK -] -Return the ceiling of \var{x} as a float.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{cos}{x}
+%[- MARK -] -Return the cosine of \var{x}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{cosh}{x}
+%[- MARK -] -Return the hyperbolic cosine of \var{x}.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{degrees}{x}
+%[- MARK -] -Converts angle \var{x} from radians to degrees.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{exp}{x}
+%[- MARK -] -Return \code{e**\var{x}}.
+%[- MARK -] +Return the ceiling of \var{x} as a float, the smallest integer value
+%[- MARK -] +greater than or equal to \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fabs}{x}
+%[- MARK -] Return the absolute value of \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{floor}{x}
+%[- MARK -] -Return the floor of \var{x} as a float.
+%[- MARK -] +Return the floor of \var{x} as a float, the largest integer value
+%[- MARK -] +less than or equal to \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fmod}{x, y}
+%[- MARK -] Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
+%[- MARK -] Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
+%[- MARK -] -the same result.
+%[- MARK -] +the same result. The intent of the C standard is that
+%[- MARK -] +\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite
+%[- MARK -] +precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer
+%[- MARK -] +\var{n} such that the result has the same sign as \var{x} and
+%[- MARK -] +magnitude less than \code{abs(\var{y})}. Python's
+%[- MARK -] +\code{\var{x} \%\ \var{y}} returns a result with the sign of
+%[- MARK -] +\var{y} instead, and may not be exactly computable for float arguments.
+%[- MARK -] +For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the
+%[- MARK -] +result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which
+%[- MARK -] +cannot be represented exactly as a float, and rounds to the surprising
+%[- MARK -] +\code{1e100}. For this reason, function \function{fmod()} is generally
+%[- MARK -] +preferred when working with floats, while Python's
+%[- MARK -] +\code{\var{x} \%\ \var{y}} is preferred when working with integers.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{frexp}{x}
+%[- MARK -] -% Blessed by Tim.
+%[- MARK -] Return the mantissa and exponent of \var{x} as the pair
+%[- MARK -] \code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an
+%[- MARK -] -integer such that \code{\var{x} == \var{m} * 2**\var{e}}.
+%[- MARK -] +integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly.
+%[- MARK -] If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
+%[- MARK -] -\code{0.5 <= abs(\var{m}) < 1}.
+%[- MARK -] +\code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the
+%[- MARK -] +internal representation of a float in a portable way.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{hypot}{x, y}
+%[- MARK -] -Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
+%[- MARK -] +\begin{funcdesc}{ldexp}{x, i}
+%[- MARK -] +Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of
+%[- MARK -] +function \function{frexp()}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{ldexp}{x, i}
+%[- MARK -] -Return \code{\var{x} * (2**\var{i})}.
+%[- MARK -] +\begin{funcdesc}{modf}{x}
+%[- MARK -] +Return the fractional and integer parts of \var{x}. Both results
+%[- MARK -] +carry the sign of \var{x}, and both are floats.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +Note that \function{frexp()} and \function{modf()} have a different
+%[- MARK -] +call/return pattern than their C equivalents: they take a single
+%[- MARK -] +argument and return a pair of values, rather than returning their
+%[- MARK -] +second return value through an `output parameter' (there is no such
+%[- MARK -] +thing in Python).
+%[- MARK -] +
+%[- MARK -] +For the \function{ceil()}, \function{floor()}, and \function{modf()}
+%[- MARK -] +functions, note that \emph{all} floating-point numbers of sufficiently
+%[- MARK -] +large magnitude are exact integers. Python floats typically carry no more
+%[- MARK -] +than 53 bits of precision (the same as the platform C double type), in
+%[- MARK -] +which case any float \var{x} with \code{abs(\var{x}) >= 2**52}
+%[- MARK -] +necessarily has no fractional bits.
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +Power and logarithmic functions:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{exp}{x}
+%[- MARK -] +Return \code{e**\var{x}}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{log}{x\optional{, base}}
+%[- MARK -] -Returns the logarithm of \var{x} to the given \var{base}.
+%[- MARK -] -If the \var{base} is not specified, returns the natural logarithm of \var{x}.
+%[- MARK -] +Return the logarithm of \var{x} to the given \var{base}.
+%[- MARK -] +If the \var{base} is not specified, return the natural logarithm of \var{x}
+%[- MARK -] +(that is, the logarithm to base \emph{e}).
+%[- MARK -] \versionchanged[\var{base} argument added]{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{log10}{x}
+%[- MARK -] Return the base-10 logarithm of \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{modf}{x}
+%[- MARK -] -Return the fractional and integer parts of \var{x}. Both results
+%[- MARK -] -carry the sign of \var{x}. The integer part is returned as a float.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] \begin{funcdesc}{pow}{x, y}
+%[- MARK -] Return \code{\var{x}**\var{y}}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{radians}{x}
+%[- MARK -] -Converts angle \var{x} from degrees to radians.
+%[- MARK -] +\begin{funcdesc}{sqrt}{x}
+%[- MARK -] +Return the square root of \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{sin}{x}
+%[- MARK -] -Return the sine of \var{x}.
+%[- MARK -] +Trigonometric functions:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{acos}{x}
+%[- MARK -] +Return the arc cosine of \var{x}, in radians.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{sinh}{x}
+%[- MARK -] -Return the hyperbolic sine of \var{x}.
+%[- MARK -] +\begin{funcdesc}{asin}{x}
+%[- MARK -] +Return the arc sine of \var{x}, in radians.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{sqrt}{x}
+%[- MARK -] -Return the square root of \var{x}.
+%[- MARK -] +\begin{funcdesc}{atan}{x}
+%[- MARK -] +Return the arc tangent of \var{x}, in radians.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{atan2}{y, x}
+%[- MARK -] +Return \code{atan(\var{y} / \var{x})}, in radians.
+%[- MARK -] +The result is between \code{-pi} and \code{pi}.
+%[- MARK -] +The vector in the plane from the origin to point \code{(\var{x}, \var{y})}
+%[- MARK -] +makes this angle with the positive X axis.
+%[- MARK -] +The point of \function{atan2()} is that the signs of both inputs are
+%[- MARK -] +known to it, so it can compute the correct quadrant for the angle.
+%[- MARK -] +For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4},
+%[- MARK -] +but \code{atan2(-1, -1)} is \code{-3*pi/4}.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{cos}{x}
+%[- MARK -] +Return the cosine of \var{x} radians.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{hypot}{x, y}
+%[- MARK -] +Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
+%[- MARK -] +This is the length of the vector from the origin to point
+%[- MARK -] +\code{(\var{x}, \var{y})}.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{sin}{x}
+%[- MARK -] +Return the sine of \var{x} radians.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tan}{x}
+%[- MARK -] -Return the tangent of \var{x}.
+%[- MARK -] +Return the tangent of \var{x} radians.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +Angular conversion:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{degrees}{x}
+%[- MARK -] +Converts angle \var{x} from radians to degrees.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{radians}{x}
+%[- MARK -] +Converts angle \var{x} from degrees to radians.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +Hyperbolic functions:
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{cosh}{x}
+%[- MARK -] +Return the hyperbolic cosine of \var{x}.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{sinh}{x}
+%[- MARK -] +Return the hyperbolic sine of \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tanh}{x}
+%[- MARK -] Return the hyperbolic tangent of \var{x}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -Note that \function{frexp()} and \function{modf()} have a different
+%[- MARK -] -call/return pattern than their C equivalents: they take a single
+%[- MARK -] -argument and return a pair of values, rather than returning their
+%[- MARK -] -second return value through an `output parameter' (there is no such
+%[- MARK -] -thing in Python).
+%[- MARK -] -
+%[- MARK -] The module also defines two mathematical constants:
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{pi}
+%[- MARK -] The mathematical constant \emph{pi}.
+%[- MARK -] \end{datadesc}
+%[- MARK -] END DIFF
determinare come e perché l'eccezione venne inizialmente generata.
Le seguenti funzioni vengono fornite da questo modulo. Tranne quando
Modified: python/python/Doc/branches/2.4.3/lib/libmd5.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmd5.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmd5.tex Fri Jun 2 12:52:55 2006
@@ -41,6 +41,21 @@
\begin{datadesc}{digest_size}
La dimensione in bytes del digest risultante. \`E sempre
\code{16}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 41
+%[- MARK -] \begin{datadesc}{digest_size}
+%[- MARK -] The size of the resulting digest in bytes. This is always
+%[- MARK -] \code{16}.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] -md5 objects support the following methods:
+%[- MARK -] +The md5 module provides the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{new}{\optional{arg}}
+%[- MARK -] Return a new md5 object. If \var{arg} is present, the method call
+%[- MARK -] \code{update(\var{arg})} is made.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{datadesc}
Gli oggetti md5 supportano i seguenti metodi:
Modified: python/python/Doc/branches/2.4.3/lib/libmimetools.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmimetools.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmimetools.tex Fri Jun 2 12:52:55 2006
@@ -56,6 +56,21 @@
Legge, fino ad incontrare un \EOF{}, blocchi dal file \var{input} e li
scrive nel file \var{output}. La grandezza di un blocco è fissata a
\code{8192}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 55
+%[- MARK -] open file \var{output}. The block size is currently fixed at 8192.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] - \seemodule{email}{Comprehensive email handling package; supercedes
+%[- MARK -] + \seemodule{email}{Comprehensive email handling package; supersedes
+%[- MARK -] the \module{mimetools} module.}
+%[- MARK -] \seemodule{rfc822}{Provides the base class for
+%[- MARK -] \class{mimetools.Message}.}
+%[- MARK -] \seemodule{multifile}{Support for reading files which contain
+%[- MARK -] distinct parts, such as MIME data.}
+%[- MARK -] END DIFF
\end{funcdesc}
Modified: python/python/Doc/branches/2.4.3/lib/libmmap.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmmap.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmmap.tex Fri Jun 2 12:52:55 2006
@@ -24,6 +24,37 @@
parametro \var{fileno}. Altrimenti, si può aprire il file usando la
funzione \function{os.open()}, che restituisce direttamente un
descrittore di file (il file necessita comunque di essere chiuso al
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 33
+%[- MARK -] \var{access} is not specified, Windows mmap returns a write-through
+%[- MARK -] mapping. The initial memory values for all three access types are
+%[- MARK -] taken from the specified file. Assignment to an
+%[- MARK -] \constant{ACCESS_READ} memory map raises a \exception{TypeError}
+%[- MARK -] exception. Assignment to an \constant{ACCESS_WRITE} memory map
+%[- MARK -] -affects both memory and the underlying file. Assigment to an
+%[- MARK -] +affects both memory and the underlying file. Assignment to an
+%[- MARK -] \constant{ACCESS_COPY} memory map affects memory but does not update
+%[- MARK -] the underlying file.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
+%[- MARK -] \strong{(Windows version)} Maps \var{length} bytes from the file
+%[- MARK -] specified by the file handle \var{fileno}, and returns a mmap
+%[- MARK -] - object. If \var{length} is \code{0}, the maximum length of the map
+%[- MARK -] - will be the current size of the file when \function{mmap()} is
+%[- MARK -] - called.
+%[- MARK -] -
+%[- MARK -] + object. If \var{length} is larger than the current size of the file,
+%[- MARK -] + the file is extended to contain \var{length} bytes. If \var{length}
+%[- MARK -] + is \code{0}, the maximum length of the map is the current size
+%[- MARK -] + of the file, except that if the file is empty Windows raises an
+%[- MARK -] + exception (you cannot create an empty mapping on Windows).
+%[- MARK -] +
+%[- MARK -] \var{tagname}, if specified and not \code{None}, is a string giving
+%[- MARK -] a tag name for the mapping. Windows allows you to have many
+%[- MARK -] different mappings against the same file. If you specify the name
+%[- MARK -] of an existing tag, that tag is opened, otherwise a new tag of this
+%[- MARK -] name is created. If this parameter is omitted or \code{None}, the
+%[- MARK -] END DIFF
termine).
Per entrambe le versioni \UNIX{} e Windows della funzione,
@@ -57,6 +88,35 @@
parametro viene omesso o è \code{None}, la mappatura viene creata
senza nome. Evitando di usare il parametro tag il codice
rimarrà portabile fra \UNIX{} e Windows.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 59
+%[- MARK -] \begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
+%[- MARK -] prot\optional{, access}}}}
+%[- MARK -] \strong{(\UNIX{} version)} Maps \var{length} bytes from the file
+%[- MARK -] specified by the file descriptor \var{fileno}, and returns a mmap
+%[- MARK -] object.
+%[- MARK -] -
+%[- MARK -] +
+%[- MARK -] \var{flags} specifies the nature of the mapping.
+%[- MARK -] \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
+%[- MARK -] changes to the contents of the mmap object will be private to this
+%[- MARK -] process, and \constant{MAP_SHARED} creates a mapping that's shared
+%[- MARK -] with all other processes mapping the same areas of the file. The
+%[- MARK -] default value is \constant{MAP_SHARED}.
+%[- MARK -] -
+%[- MARK -] +
+%[- MARK -] \var{prot}, if specified, gives the desired memory protection; the
+%[- MARK -] two most useful values are \constant{PROT_READ} and
+%[- MARK -] \constant{PROT_WRITE}, to specify that the pages may be read or
+%[- MARK -] written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
+%[- MARK -] -
+%[- MARK -] +
+%[- MARK -] \var{access} may be specified in lieu of \var{flags} and \var{prot}
+%[- MARK -] as an optional keyword parameter. It is an error to specify both
+%[- MARK -] \var{flags}, \var{prot} and \var{access}. See the description of
+%[- MARK -] \var{access} above for information on how to use this parameter.
+%[- MARK -] \end{funcdescni}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
@@ -127,6 +187,26 @@
\begin{methoddesc}{read_byte}{}
Restituisce una stringa di lunghezza 1 contenente il carattere alla
posizione corrente nel file, e la fa avanzare di 1.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 121
+%[- MARK -] Returns a string of length 1 containing the character at the current
+%[- MARK -] file position, and advances the file position by 1.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{readline}{}
+%[- MARK -] - Returns a single line, starting at the current file position and up to
+%[- MARK -] + Returns a single line, starting at the current file position and up to
+%[- MARK -] the next newline.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{resize}{\var{newsize}}
+%[- MARK -] + Resizes the map and the underlying file, if any.
+%[- MARK -] If the mmap was created with \constant{ACCESS_READ} or
+%[- MARK -] \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{seek}{pos\optional{, whence}}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{readline}{}
Added: python/python/Doc/branches/2.4.3/lib/libmodulefinder.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libmodulefinder.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,50 @@
+%[- MARK -] BEGIN PART 001 of 1
+\section{\module{modulefinder} ---
+ Find modules used by a script}
+\sectionauthor{A.M. Kuchling}{amk a amk.ca}
+
+\declaremodule{standard}{modulefinder}
+\modulesynopsis{Find modules used by a script.}
+
+This module provides a \class{ModuleFinder} class that can be used to
+determine the set of modules imported by a script.
+\code{modulefinder.py} can also be run as a script, giving the
+filename of a Python script as its argument, after which a report of
+the imported modules will be printed.
+
+\begin{funcdesc}{AddPackagePath}{pkg_name, path}
+Record that the package named \var{pkg_name} can be found in the specified \var{path}.
+\end{funcdesc}
+
+\begin{funcdesc}{ReplacePackage}{oldname, newname}
+Allows specifying that the module named \var{oldname} is in fact
+the package named \var{newname}. The most common usage would be
+to handle how the \module{_xmlplus} package replaces the \module{xml}
+package.
+\end{funcdesc}
+
+\begin{classdesc}{ModuleFinder}{\optional{path=None, debug=0, excludes=[], replace_paths=[]}}
+
+This class provides \method{run_script()} and \method{report()}
+methods to determine the set of modules imported by a script.
+\var{path} can be a list of directories to search for modules; if not
+specified, \code{sys.path} is used.
+\var{debug} sets the debugging level; higher values make the class print
+debugging messages about what it's doing.
+\var{excludes} is a list of module names to exclude from the analysis.
+\var{replace_paths} is a list of \code{(\var{oldpath}, \var{newpath})}
+tuples that will be replaced in module paths.
+\end{classdesc}
+
+\begin{methoddesc}[ModuleFinder]{report}{}
+Print a report to standard output that lists the modules imported by the script
+and their
+paths, as well as modules that are missing or seem to be missing.
+\end{methoddesc}
+
+\begin{methoddesc}[ModuleFinder]{run_script}{pathname}
+Analyze the contents of the \var{pathname} file, which must contain
+Python code.
+\end{methoddesc}
+
+
Modified: python/python/Doc/branches/2.4.3/lib/libmultifile.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libmultifile.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libmultifile.tex Fri Jun 2 12:52:55 2006
@@ -36,6 +36,21 @@
marcatori di fine. Multifile è progettata per supportare l'analisi di
messaggi che potrebbero avere parti di messaggio annidate multiple,
ognuna con la propria corrispondenza per il divisore di sezione ed il
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 33
+%[- MARK -] end-markers. MultiFile is designed to support parsing of
+%[- MARK -] messages that may have multiple nested message parts, each with its
+%[- MARK -] own pattern for section-divider and end-marker lines.
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] - \seemodule{email}{Comprehensive email handling package; supercedes
+%[- MARK -] + \seemodule{email}{Comprehensive email handling package; supersedes
+%[- MARK -] the \module{multifile} module.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{MultiFile Objects \label{MultiFile-objects}}
+%[- MARK -] END DIFF
marcatore di fine.
\begin{seealso}
@@ -102,6 +117,25 @@
effettivi sui delimitatori; se restituisce sempre falso rallenterà
semplicemente la velocità d'elaborazione, ma non provocherà il
fallimento dei test stessi.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 90
+%[- MARK -] boundary tests; if it always returns false it will merely slow
+%[- MARK -] processing, not cause it to fail.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{push}{str}
+%[- MARK -] -Push a boundary string. When an appropriately decorated version of
+%[- MARK -] -this boundary is found as an input line, it will be interpreted as a
+%[- MARK -] -section-divider or end-marker. All subsequent
+%[- MARK -] +Push a boundary string. When a decorated version of this boundary
+%[- MARK -] +is found as an input line, it will be interpreted as a section-divider
+%[- MARK -] +or end-marker (depending on the decoration, see \rfc{2045}). All subsequent
+%[- MARK -] reads will return the empty string to indicate end-of-file, until a
+%[- MARK -] call to \method{pop()} removes the boundary a or \method{next()} call
+%[- MARK -] reenables it.
+%[- MARK -]
+%[- MARK -] It is possible to push more than one boundary. Encountering the
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{push}{str}
Modified: python/python/Doc/branches/2.4.3/lib/libnew.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libnew.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libnew.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,21 @@
\declaremodule{builtin}{new}
\sectionauthor{Moshe Zadka}{moshez a zadka.site.co.il}
\modulesynopsis{Interfaccia alla creazione in runtime
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 9
+%[- MARK -] The \module{new} module allows an interface to the interpreter object
+%[- MARK -] creation functions. This is for use primarily in marshal-type functions,
+%[- MARK -] when a new object needs to be created ``magically'' and not by using the
+%[- MARK -] regular creation functions. This module provides a low-level interface
+%[- MARK -] to the interpreter, so care must be exercised when using this module.
+%[- MARK -] +It is possible to supply non-sensical arguments which crash the
+%[- MARK -] +interpreter when the object is used.
+%[- MARK -]
+%[- MARK -] The \module{new} module defines the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{instance}{class\optional{, dict}}
+%[- MARK -] This function creates an instance of \var{class} with dictionary
+%[- MARK -] END DIFF
dell'implementazione di oggetti.}
@@ -45,6 +60,24 @@
lnotab}
Questa funzione è un'interfaccia alla funzione C \cfunction{PyCode_New()}.
%XXX This is still undocumented!!!!!!!!!!!
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 43
+%[- MARK -] This function is an interface to the \cfunction{PyCode_New()} C
+%[- MARK -] function.
+%[- MARK -] %XXX This is still undocumented!!!!!!!!!!!
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{module}{name}
+%[- MARK -] +\begin{funcdesc}{module}{name[, doc]}
+%[- MARK -] This function returns a new module object with name \var{name}.
+%[- MARK -] \var{name} must be a string.
+%[- MARK -] +The optional \var{doc} argument can have any type.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{classobj}{name, baseclasses, dict}
+%[- MARK -] This function returns a new class object, with name \var{name}, derived
+%[- MARK -] from \var{baseclasses} (which should be a tuple of classes) and with
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{module}{name}
Modified: python/python/Doc/branches/2.4.3/lib/libnntplib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libnntplib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libnntplib.tex Fri Jun 2 12:52:55 2006
@@ -51,6 +51,40 @@
'205 news.cwi.nl closing connection. Goodbye.'
\end{verbatim}
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 52
+%[- MARK -]
+%[- MARK -] The module itself defines the following items:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{NNTP}{host\optional{, port
+%[- MARK -] \optional{, user\optional{, password
+%[- MARK -] - \optional{, readermode}}}}}
+%[- MARK -] + \optional{, readermode}
+%[- MARK -] + \optional{, usenetrc}}}}}
+%[- MARK -] Return a new instance of the \class{NNTP} class, representing a
+%[- MARK -] connection to the NNTP server running on host \var{host}, listening at
+%[- MARK -] port \var{port}. The default \var{port} is 119. If the optional
+%[- MARK -] \var{user} and \var{password} are provided,
+%[- MARK -] -or if suitable credentials are present in \file{~/.netrc},
+%[- MARK -] +or if suitable credentials are present in \file{~/.netrc} and the
+%[- MARK -] +optional flag \var{usenetrc} is true (the default),
+%[- MARK -] the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to
+%[- MARK -] identify and authenticate the user to the server. If the optional
+%[- MARK -] flag \var{readermode} is true, then a \samp{mode reader} command is
+%[- MARK -] sent before authentication is performed. Reader mode is sometimes
+%[- MARK -] necessary if you are connecting to an NNTP server on the local machine
+%[- MARK -] and intend to call reader-specific commands, such as \samp{group}. If
+%[- MARK -] you get unexpected \code{NNTPPermanentError}s, you might need to set
+%[- MARK -] \var{readermode}. \var{readermode} defaults to \code{None}.
+%[- MARK -] +\var{usenetrc} defaults to \code{True}.
+%[- MARK -] +
+%[- MARK -] +\versionchanged[\var{usenetrc} argument added]{2.4}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{NNTPError}{}
+%[- MARK -] Derived from the standard exception \code{Exception}, this is the base
+%[- MARK -] class for all exceptions raised by the \code{nntplib} module.
+%[- MARK -] END DIFF
Il modulo definisce i seguenti elementi:
\begin{classdesc}{NNTP}{host\optional{, port
@@ -152,6 +186,21 @@
oggetto file, inizierà chiamando\method{write()} su di esso per
memorizzare le righe del risultato del comando. Se \var{file} viene
fornito, la \var{lista} restituita sarà una lista vuota.
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 149
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{newnews}{group, date, time, \optional{file}}
+%[- MARK -] Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
+%[- MARK -] \code{'*'}, and \var{date} and \var{time} have the same meaning as for
+%[- MARK -] \method{newgroups()}. Return a pair \code{(\var{response},
+%[- MARK -] -\var{articles})} where \var{articles} is a list of article ids.
+%[- MARK -] +\var{articles})} where \var{articles} is a list of message ids.
+%[- MARK -] If the \var{file} parameter is supplied, then the output of the
+%[- MARK -] \samp{NEWNEWS} command is stored in a file. If \var{file} is a string,
+%[- MARK -] then the method will open a file object with that name, write to it
+%[- MARK -] then close it. If \var{file} is a file object, then it will start
+%[- MARK -] calling \method{write()} on it to store the lines of the command output.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{newnews}{group, date, time, \optional{file}}
@@ -186,6 +235,40 @@
chiamato il metodo \method{write()} per memorizzare le righe del
risultato del comando. Se \var{file} viene indicato, la lista
\var{list}, restituita è una lista vuota.
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 175
+%[- MARK -] then close it. If \var{file} is a file object, then it will start
+%[- MARK -] calling \method{write()} on it to store the lines of the command output.
+%[- MARK -] If \var{file} is supplied, then the returned \var{list} is an empty list.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}{descriptions}{grouppattern}
+%[- MARK -] +Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat
+%[- MARK -] +string as specified in RFC2980 (it's essentially the same as DOS or UNIX
+%[- MARK -] +shell wildcard strings). Return a pair \code{(\var{response},
+%[- MARK -] +\var{list})}, where \var{list} is a list of tuples containing
+%[- MARK -] +\code{(\var{name}, \var{title})}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}{description}{group}
+%[- MARK -] +Get a description for a single group \var{group}. If more than one group
+%[- MARK -] +matches (if 'group' is a real wildmat string), return the first match.
+%[- MARK -] +If no group matches, return an empty string.
+%[- MARK -] +
+%[- MARK -] +This elides the response code from the server. If the response code is
+%[- MARK -] +needed, use \method{descriptions()}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \begin{methoddesc}{group}{name}
+%[- MARK -] Send a \samp{GROUP} command, where \var{name} is the group name.
+%[- MARK -] Return a tuple \code{(\var{response}, \var{count}, \var{first},
+%[- MARK -] \var{last}, \var{name})} where \var{count} is the (estimated) number
+%[- MARK -] of articles in the group, \var{first} is the first article number in
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{group}{name}
@@ -208,6 +291,21 @@
file, il metodo chiamerà \method{write()} per memorizzare le righe del
risultato del comando. Se \var{file} viene indicato, la lista
restituita è una lista vuota.
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 200
+%[- MARK -] \begin{methoddesc}{stat}{id}
+%[- MARK -] Send a \samp{STAT} command, where \var{id} is the message id (enclosed
+%[- MARK -] in \character{<} and \character{>}) or an article number (as a string).
+%[- MARK -] Return a triple \code{(\var{response}, \var{number}, \var{id})} where
+%[- MARK -] \var{number} is the article number (as a string) and \var{id} is the
+%[- MARK -] -article id (enclosed in \character{<} and \character{>}).
+%[- MARK -] +message id (enclosed in \character{<} and \character{>}).
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{next}{}
+%[- MARK -] Send a \samp{NEXT} command. Return as for \method{stat()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{stat}{id}
@@ -259,6 +357,21 @@
\begin{methoddesc}{slave}{}
Invia un comando \samp{SLAVE}. Restituisce la risposta del server
\var{response}.
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 247
+%[- MARK -] but is a common extension. The \var{header} argument is a header
+%[- MARK -] keyword, e.g. \code{'subject'}. The \var{string} argument should have
+%[- MARK -] the form \code{'\var{first}-\var{last}'} where \var{first} and
+%[- MARK -] \var{last} are the first and last article numbers to search. Return a
+%[- MARK -] pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
+%[- MARK -] -pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
+%[- MARK -] +pairs \code{(\var{id}, \var{text})}, where \var{id} is an article number
+%[- MARK -] (as a string) and \var{text} is the text of the requested header for
+%[- MARK -] that article.
+%[- MARK -] If the \var{file} parameter is supplied, then the output of the
+%[- MARK -] \samp{XHDR} command is stored in a file. If \var{file} is a string,
+%[- MARK -] then the method will open a file object with that name, write to it
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{xhdr}{header, string, \optional{file}}
@@ -288,6 +401,23 @@
news correttamente costruito, incluse le intestazioni richieste. Il
metodo \method{post()} inserisce automaticamente l'escape per le linee
che iniziano con \samp{.}.
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 267
+%[- MARK -] including the required headers. The \method{post()} method
+%[- MARK -] automatically escapes lines beginning with \samp{.}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{ihave}{id, file}
+%[- MARK -] -Send an \samp{IHAVE} command. If the response is not an error, treat
+%[- MARK -] +Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in
+%[- MARK -] +\character{<} and \character{>}).
+%[- MARK -] +If the response is not an error, treat
+%[- MARK -] \var{file} exactly as for the \method{post()} method.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{date}{}
+%[- MARK -] Return a triple \code{(\var{response}, \var{date}, \var{time})},
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{ihave}{id, file}
@@ -301,6 +431,22 @@
e l'ora corrente in un formato adatto ai metodi \method{newnews()} e
\method{newgroups()}. Questa è un'estensione facoltativa NNTP e
potrebbe non essere supportata da tutti i server.
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 292
+%[- MARK -] then close it. If \var{file} is a file object, then it will start
+%[- MARK -] calling \method{write()} on it to store the lines of the command output.
+%[- MARK -] If \var{file} is supplied, then the returned \var{list} is an empty list.
+%[- MARK -] This is an optional NNTP extension, and may not be supported by all
+%[- MARK -] servers.
+%[- MARK -] +
+%[- MARK -] +RFC2980 says ``It is suggested that this extension be deprecated''. Use
+%[- MARK -] +\method{descriptions()} or \method{description()} instead.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{xover}{start, end, \optional{file}}
+%[- MARK -] Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
+%[- MARK -] of tuples, one for each article in the range delimited by the \var{start}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{xgtitle}{name, \optional{file}}
Modified: python/python/Doc/branches/2.4.3/lib/libos.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libos.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libos.tex Fri Jun 2 12:52:55 2006
@@ -93,6 +93,50 @@
Un oggetto mappa che rappresenta le variabili di ambiente. Per
esempio, \code{environ['HOME']} è il percorso della vostra home
directory (su alcune piattaforme), ed è equivalente a chiamare
+%[- MARK -] BEGIN DIFF 001 of 41
+%[- MARK -] @@ 88
+%[- MARK -] \begin{datadesc}{environ}
+%[- MARK -] A mapping object representing the string environment. For example,
+%[- MARK -] \code{environ['HOME']} is the pathname of your home directory (on some
+%[- MARK -] platforms), and is equivalent to \code{getenv("HOME")} in C.
+%[- MARK -]
+%[- MARK -] +This mapping is captured the first time the \module{os} module is
+%[- MARK -] +imported, typically during Python startup as part of processing
+%[- MARK -] +\file{site.py}. Changes to the environment made after this time are
+%[- MARK -] +not reflected in \code{os.environ}, except for changes made by modifying
+%[- MARK -] +\code{os.environ} directly.
+%[- MARK -] +
+%[- MARK -] If the platform supports the \function{putenv()} function, this
+%[- MARK -] mapping may be used to modify the environment as well as query the
+%[- MARK -] environment. \function{putenv()} will be called automatically when
+%[- MARK -] -the mapping is modified. \note{On some platforms, including
+%[- MARK -] -FreeBSD and Mac OS X, setting \code{environ} may cause memory leaks.
+%[- MARK -] -Refer to the system documentation for putenv.}
+%[- MARK -] +the mapping is modified.
+%[- MARK -] +\note{Calling \function{putenv()} directly does not change
+%[- MARK -] +\code{os.environ}, so it's better to modify \code{os.environ}.}
+%[- MARK -] +\note{On some platforms, including FreeBSD and Mac OS X, setting
+%[- MARK -] +\code{environ} may cause memory leaks. Refer to the system documentation
+%[- MARK -] +for \cfunction{putenv()}.}
+%[- MARK -] +
+%[- MARK -] +If \function{putenv()} is not provided, a modified copy of this mapping
+%[- MARK -] +may be passed to the appropriate process-creation functions to cause
+%[- MARK -] +child processes to use a modified environment.
+%[- MARK -] +
+%[- MARK -] +If the platform supports the \function{unsetenv()} function, you can
+%[- MARK -] +delete items in this mapping to unset environment variables.
+%[- MARK -] +\function{unsetenv()} will be called automatically when an item is
+%[- MARK -] +deleted from \code{os.environ}.
+%[- MARK -]
+%[- MARK -] -If \function{putenv()} is not provided, this mapping may be passed to
+%[- MARK -] -the appropriate process-creation functions to cause child processes to
+%[- MARK -] -use a modified environment.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdescni}{chdir}{path}
+%[- MARK -] \funclineni{fchdir}{fd}
+%[- MARK -] \funclineni{getcwd}{}
+%[- MARK -] END DIFF
\code{getenv("HOME")} in C.
Se la piattaforma supporta la funzione \function{putenv()}, questa
@@ -311,6 +355,33 @@
\withsubitem{(nel modulo socket)}{\ttindex{gethostbyaddr()}}
\code{socket.gethostbyaddr(socket.gethostname())}.
Disponibilità: versioni recenti di \UNIX.
+%[- MARK -] BEGIN DIFF 002 of 41
+%[- MARK -] @@ 296
+%[- MARK -] \withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}
+%[- MARK -] \code{socket.gethostbyaddr(socket.gethostname())}.
+%[- MARK -] Availability: recent flavors of \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] +\begin{funcdesc}{unsetenv}{varname}
+%[- MARK -] +\index{environment variables!deleting}
+%[- MARK -] +Unset (delete) the environment variable named \var{varname}. Such
+%[- MARK -] +changes to the environment affect subprocesses started with
+%[- MARK -] +\function{os.system()}, \function{popen()} or \function{fork()} and
+%[- MARK -] +\function{execv()}. Availability: most flavors of \UNIX, Windows.
+%[- MARK -] +
+%[- MARK -] +When \function{unsetenv()} is
+%[- MARK -] +supported, deletion of items in \code{os.environ} is automatically
+%[- MARK -] +translated into a corresponding call to \function{unsetenv()}; however,
+%[- MARK -] +calls to \function{unsetenv()} don't update \code{os.environ}, so it is
+%[- MARK -] +actually preferable to delete items of \code{os.environ}.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -]
+%[- MARK -] \subsection{File Object Creation \label{os-newstreams}}
+%[- MARK -]
+%[- MARK -] These functions create new file objects.
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
@@ -331,6 +402,21 @@
cominciare con una delle tre lettere \character{r}, \character{w}, o
\character{a}, altrimenti viene sollevata un'eccezione
\exception{ValueError}]{2.3}
+%[- MARK -] BEGIN DIFF 003 of 41
+%[- MARK -] @@ 326
+%[- MARK -] argument to the built-in \function{open()} function. The exit status of
+%[- MARK -] the command (encoded in the format specified for \function{wait()}) is
+%[- MARK -] available as the return value of the \method{close()} method of the file
+%[- MARK -] object, except that when the exit status is zero (termination without
+%[- MARK -] errors), \code{None} is returned.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -]
+%[- MARK -] \versionchanged[This function worked unreliably under Windows in
+%[- MARK -] earlier versions of Python. This was due to the use of the
+%[- MARK -] \cfunction{_popen()} function from the libraries provided with
+%[- MARK -] Windows. Newer versions of Python do not use the broken
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
@@ -353,6 +439,39 @@
nuove versioni di Python non usano l'implementazione
\cfunction{_popen()} difettosa fornita dalle librerie di
Windows]{2.0}
+%[- MARK -] BEGIN DIFF 004 of 41
+%[- MARK -] @@ 339
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tmpfile}{}
+%[- MARK -] Return a new file object opened in update mode (\samp{w+b}). The file
+%[- MARK -] has no directory entries associated with it and will be automatically
+%[- MARK -] deleted once there are no file descriptors for the file.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] -For each of these \function{popen()} variants, if \var{bufsize} is
+%[- MARK -] +For each of the following \function{popen()} variants, if \var{bufsize} is
+%[- MARK -] specified, it specifies the buffer size for the I/O pipes.
+%[- MARK -] \var{mode}, if provided, should be the string \code{'b'} or
+%[- MARK -] \code{'t'}; on Windows this is needed to determine whether the file
+%[- MARK -] objects should be opened in binary or text mode. The default value
+%[- MARK -] for \var{mode} is \code{'t'}.
+%[- MARK -]
+%[- MARK -] -These methods do not make it possible to retrieve the return code from
+%[- MARK -] +Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in
+%[- MARK -] +which case arguments will be passed directly to the program without shell
+%[- MARK -] +intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will
+%[- MARK -] +be passed to the shell (as with \function{os.system()}).
+%[- MARK -] +
+%[- MARK -] +These methods do not make it possible to retrieve the exit status from
+%[- MARK -] the child processes. The only way to control the input and output
+%[- MARK -] streams and also retrieve the return codes is to use the
+%[- MARK -] \class{Popen3} and \class{Popen4} classes from the \refmodule{popen2}
+%[- MARK -] module; these are only available on \UNIX.
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{tmpfile}{}
@@ -381,6 +500,44 @@
Per una discussione delle possibili condizioni di deadlock collegate
all'uso di queste funzioni, vedete ``\ulink{Problemi con il controllo
di flusso}{popen2-flow-control.html}''
+%[- MARK -] BEGIN DIFF 005 of 41
+%[- MARK -] @@ 364
+%[- MARK -] (section~\ref{popen2-flow-control}).
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}
+%[- MARK -] Executes \var{cmd} as a sub-process. Returns the file objects
+%[- MARK -] \code{(\var{child_stdin}, \var{child_stdout})}.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}}
+%[- MARK -] Executes \var{cmd} as a sub-process. Returns the file objects
+%[- MARK -] \code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}
+%[- MARK -] Executes \var{cmd} as a sub-process. Returns the file objects
+%[- MARK -] \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +(Note that \code{\var{child_stdin}, \var{child_stdout}, and
+%[- MARK -] +\var{child_stderr}} are named from the point of view of the child
+%[- MARK -] +process, so \var{child_stdin} is the child's standard input.)
+%[- MARK -] +
+%[- MARK -] This functionality is also available in the \refmodule{popen2} module
+%[- MARK -] using functions of the same names, but the return values of those
+%[- MARK -] functions have a different order.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] END DIFF
(sezione~\ref{popen2-flow-control}).
\begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}
@@ -431,6 +588,21 @@
\begin{funcdesc}{dup}{fd}
Restituisce un duplicato del descrittore di file \var{fd}.
Disponibilità: Macintosh, \UNIX, Windows.
+%[- MARK -] BEGIN DIFF 006 of 41
+%[- MARK -] @@ 414
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{dup2}{fd, fd2}
+%[- MARK -] Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
+%[- MARK -] first if necessary.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fdatasync}{fd}
+%[- MARK -] Force write of file with filedescriptor \var{fd} to disk.
+%[- MARK -] Does not force update of metadata.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{dup2}{fd, fd2}
@@ -443,6 +615,33 @@
Forza la scrittura su disco del file con descrittore \var{fd}. Non
forza l'aggiornamento dei metadata.
Disponibilità: \UNIX.
+%[- MARK -] BEGIN DIFF 007 of 41
+%[- MARK -] @@ 433
+%[- MARK -] others). Some platforms define additional names as well. The names
+%[- MARK -] known to the host operating system are given in the
+%[- MARK -] \code{pathconf_names} dictionary. For configuration variables not
+%[- MARK -] included in that mapping, passing an integer for \var{name} is also
+%[- MARK -] accepted.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -]
+%[- MARK -] If \var{name} is a string and is not known, \exception{ValueError} is
+%[- MARK -] raised. If a specific value for \var{name} is not supported by the
+%[- MARK -] host system, even if it is included in \code{pathconf_names}, an
+%[- MARK -] \exception{OSError} is raised with \constant{errno.EINVAL} for the
+%[- MARK -] error number.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fstat}{fd}
+%[- MARK -] Return status for file descriptor \var{fd}, like \function{stat()}.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fstatvfs}{fd}
+%[- MARK -] Return information about the filesystem containing the file associated
+%[- MARK -] with file descriptor \var{fd}, like \function{statvfs()}.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{fpathconf}{fd, name}
@@ -482,6 +681,35 @@
\begin{funcdesc}{fsync}{fd}
Forza la scrittura su disco del file descritto da \var{fd}. In \UNIX,
questa funzione chiama la funzione nativa \cfunction{fsync()}; in
+%[- MARK -] BEGIN DIFF 008 of 41
+%[- MARK -] @@ 462
+%[- MARK -]
+%[- MARK -] If you're starting with a Python file object \var{f}, first do
+%[- MARK -] \code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())},
+%[- MARK -] to ensure that all internal buffers associated with \var{f} are written
+%[- MARK -] to disk.
+%[- MARK -] -Availability: \UNIX, and Windows starting in 2.2.3.
+%[- MARK -] +Availability: Macintosh, \UNIX, and Windows starting in 2.2.3.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{ftruncate}{fd, length}
+%[- MARK -] Truncate the file corresponding to file descriptor \var{fd},
+%[- MARK -] so that it is at most \var{length} bytes in size.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{isatty}{fd}
+%[- MARK -] Return \code{True} if the file descriptor \var{fd} is open and
+%[- MARK -] connected to a tty(-like) device, else \code{False}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{lseek}{fd, pos, how}
+%[- MARK -] Set the current position of file descriptor \var{fd} to position
+%[- MARK -] \var{pos}, modified by \var{how}: \code{0} to set the position
+%[- MARK -] END DIFF
Windows, viene chiamata la funzione \cfunction{_commit()}.
Partendo da un oggetto file di Python \var{f}, dovete prima eseguire
@@ -532,6 +760,28 @@
un ``oggetto file'' con metodi \method{read()} e \method{write()} (e
molti altri).
\end{notice}
+%[- MARK -] BEGIN DIFF 009 of 41
+%[- MARK -] @@ 511
+%[- MARK -] \begin{funcdesc}{openpty}{}
+%[- MARK -] Open a new pseudo-terminal pair. Return a pair of file descriptors
+%[- MARK -] \code{(\var{master}, \var{slave})} for the pty and the tty,
+%[- MARK -] respectively. For a (slightly) more portable approach, use the
+%[- MARK -] \refmodule{pty}\refstmodindex{pty} module.
+%[- MARK -] -Availability: Some flavors of \UNIX.
+%[- MARK -] +Availability: Macintosh, Some flavors of \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{pipe}{}
+%[- MARK -] Create a pipe. Return a pair of file descriptors \code{(\var{r},
+%[- MARK -] \var{w})} usable for reading and writing, respectively.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{read}{fd, n}
+%[- MARK -] Read at most \var{n} bytes from file descriptor \var{fd}.
+%[- MARK -] Return a string containing the bytes read. If the end of the file
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{openpty}{}
@@ -564,6 +814,37 @@
\function{fdopen()} o \code{sys.stdin}, usate i suoi metodi
\method{read()} o \method{readline()}.
\end{notice}
+%[- MARK -] BEGIN DIFF 010 of 41
+%[- MARK -] @@ 540
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tcgetpgrp}{fd}
+%[- MARK -] Return the process group associated with the terminal given by
+%[- MARK -] \var{fd} (an open file descriptor as returned by \function{open()}).
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tcsetpgrp}{fd, pg}
+%[- MARK -] Set the process group associated with the terminal given by
+%[- MARK -] \var{fd} (an open file descriptor as returned by \function{open()})
+%[- MARK -] to \var{pg}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{ttyname}{fd}
+%[- MARK -] Return a string which specifies the terminal device associated with
+%[- MARK -] file-descriptor \var{fd}. If \var{fd} is not associated with a terminal
+%[- MARK -] device, an exception is raised.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability:Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{write}{fd, str}
+%[- MARK -] Write the string \var{str} to file descriptor \var{fd}.
+%[- MARK -] Return the number of bytes actually written.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{tcgetpgrp}{fd}
@@ -603,6 +884,50 @@
I seguenti elementi dato sono disponibili per la creazione del parametro
+%[- MARK -] BEGIN DIFF 011 of 41
+%[- MARK -] @@ 579
+%[- MARK -] \var{flags} parameter to the \function{open()} function.
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{O_RDONLY}
+%[- MARK -] \dataline{O_WRONLY}
+%[- MARK -] \dataline{O_RDWR}
+%[- MARK -] -\dataline{O_NDELAY}
+%[- MARK -] -\dataline{O_NONBLOCK}
+%[- MARK -] \dataline{O_APPEND}
+%[- MARK -] -\dataline{O_DSYNC}
+%[- MARK -] -\dataline{O_RSYNC}
+%[- MARK -] -\dataline{O_SYNC}
+%[- MARK -] -\dataline{O_NOCTTY}
+%[- MARK -] \dataline{O_CREAT}
+%[- MARK -] \dataline{O_EXCL}
+%[- MARK -] \dataline{O_TRUNC}
+%[- MARK -] Options for the \var{flag} argument to the \function{open()} function.
+%[- MARK -] These can be bit-wise OR'd together.
+%[- MARK -] Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] -% XXX O_NDELAY, O_NONBLOCK, O_DSYNC, O_RSYNC, O_SYNC, O_NOCTTY are not on Windows.
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{O_DSYNC}
+%[- MARK -] +\dataline{O_RSYNC}
+%[- MARK -] +\dataline{O_SYNC}
+%[- MARK -] +\dataline{O_NDELAY}
+%[- MARK -] +\dataline{O_NONBLOCK}
+%[- MARK -] +\dataline{O_NOCTTY}
+%[- MARK -] +More options for the \var{flag} argument to the \function{open()} function.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{O_BINARY}
+%[- MARK -] Option for the \var{flag} argument to the \function{open()} function.
+%[- MARK -] This can be bit-wise OR'd together with those listed above.
+%[- MARK -] -Availability: Macintosh, Windows.
+%[- MARK -] +Availability: Windows.
+%[- MARK -] % XXX need to check on the availability of this one.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{O_NOINHERIT}
+%[- MARK -] \dataline{O_SHORT_LIVED}
+%[- MARK -] END DIFF
\var{flags} della funzione \function{open()}.
\begin{datadesc}{O_RDONLY}
@@ -643,6 +968,31 @@
Disponibilità: Windows.
\end{datadesc}
+%[- MARK -] BEGIN DIFF 012 of 41
+%[- MARK -] @@ 625
+%[- MARK -] to test the existence of \var{path}, or it can be the inclusive OR of
+%[- MARK -] one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to
+%[- MARK -] test permissions. Return \constant{True} if access is allowed,
+%[- MARK -] \constant{False} if not.
+%[- MARK -] See the \UNIX{} man page \manpage{access}{2} for more information.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] +
+%[- MARK -] +\note{Using \function{access()} to check if a user is authorized to e.g.
+%[- MARK -] +open a file before actually doing so using \function{open()} creates a
+%[- MARK -] +security hole, because the user might exploit the short time interval
+%[- MARK -] +between checking and opening the file to manipulate it.}
+%[- MARK -] +
+%[- MARK -] +\note{I/O operations may fail even when \function{access()}
+%[- MARK -] +indicates that they would succeed, particularly for operations
+%[- MARK -] +on network filesystems which may have permissions semantics
+%[- MARK -] +beyond the usual \POSIX{} permission-bit model.}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{F_OK}
+%[- MARK -] Value to pass as the \var{mode} parameter of \function{access()} to
+%[- MARK -] test the existence of \var{path}.
+%[- MARK -] END DIFF
\subsection{File e directory \label{os-file-dir}}
\begin{funcdesc}{access}{path, mode}
@@ -698,6 +1048,37 @@
Restituisce una stringa rappresentante la directory di lavoro
corrente.
Disponibilità: Macintosh, \UNIX, Windows.
+%[- MARK -] BEGIN DIFF 013 of 41
+%[- MARK -] @@ 669
+%[- MARK -] Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getcwdu}{}
+%[- MARK -] Return a Unicode object representing the current working directory.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{chroot}{path}
+%[- MARK -] Change the root directory of the current process to \var{path}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.2}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{chmod}{path, mode}
+%[- MARK -] Change the mode of \var{path} to the numeric \var{mode}.
+%[- MARK -] \var{mode} may take one of the following values
+%[- MARK -] -(as defined in the \module{stat} module):
+%[- MARK -] +(as defined in the \module{stat} module) or bitwise or-ed
+%[- MARK -] +combinations of them:
+%[- MARK -] \begin{itemize}
+%[- MARK -] \item \code{S_ISUID}
+%[- MARK -] \item \code{S_ISGID}
+%[- MARK -] \item \code{S_ENFMT}
+%[- MARK -] \item \code{S_ISVTX}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{getcwdu}{}
@@ -711,6 +1092,107 @@
Cambia la directory radice del processo corrente nel valore \var{path}.
Disponibilità: \UNIX.
\versionadded{2.2}
+%[- MARK -] BEGIN DIFF 014 of 41
+%[- MARK -] @@ 704
+%[- MARK -] \item \code{S_IRWXO}
+%[- MARK -] \item \code{S_IROTH}
+%[- MARK -] \item \code{S_IWOTH}
+%[- MARK -] \item \code{S_IXOTH}
+%[- MARK -] \end{itemize}
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] +
+%[- MARK -] +\note{Although Windows supports \function{chmod()}, you can only
+%[- MARK -] +set the file's read-only flag with it (via the \code{S_IWRITE}
+%[- MARK -] +and \code{S_IREAD} constants or a corresponding integer value).
+%[- MARK -] +All other bits are ignored.}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{chown}{path, uid, gid}
+%[- MARK -] Change the owner and group id of \var{path} to the numeric \var{uid}
+%[- MARK -] -and \var{gid}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +and \var{gid}. To leave one of the ids unchanged, set it to -1.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{lchown}{path, uid, gid}
+%[- MARK -] Change the owner and group id of \var{path} to the numeric \var{uid}
+%[- MARK -] and gid. This function will not follow symbolic links.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{link}{src, dst}
+%[- MARK -] Create a hard link pointing to \var{src} named \var{dst}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{listdir}{path}
+%[- MARK -] Return a list containing the names of the entries in the directory.
+%[- MARK -] The list is in arbitrary order. It does not include the special
+%[- MARK -] entries \code{'.'} and \code{'..'} even if they are present in the
+%[- MARK -] directory.
+%[- MARK -] Availability: Macintosh, \UNIX, Windows.
+%[- MARK -]
+%[- MARK -] \versionchanged[On Windows NT/2k/XP and Unix, if \var{path} is a Unicode
+%[- MARK -] -object, the result will be a list of Unicode objects.]{2.3}
+%[- MARK -] +object, the result will be a list of Unicode objects]{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{lstat}{path}
+%[- MARK -] Like \function{stat()}, but do not follow symbolic links.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{mkfifo}{path\optional{, mode}}
+%[- MARK -] Create a FIFO (a named pipe) named \var{path} with numeric mode
+%[- MARK -] \var{mode}. The default \var{mode} is \code{0666} (octal). The current
+%[- MARK -] umask value is first masked out from the mode.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -]
+%[- MARK -] FIFOs are pipes that can be accessed like regular files. FIFOs exist
+%[- MARK -] until they are deleted (for example with \function{os.unlink()}).
+%[- MARK -] Generally, FIFOs are used as rendezvous between ``client'' and
+%[- MARK -] ``server'' type processes: the server opens the FIFO for reading, and
+%[- MARK -] the client opens it for writing. Note that \function{mkfifo()}
+%[- MARK -] doesn't open the FIFO --- it just creates the rendezvous point.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{mknod}{path\optional{, mode=0600, device}}
+%[- MARK -] +\begin{funcdesc}{mknod}{filename\optional{, mode=0600, device}}
+%[- MARK -] Create a filesystem node (file, device special file or named pipe)
+%[- MARK -] -named filename. \var{mode} specifies both the permissions to use and
+%[- MARK -] +named \var{filename}. \var{mode} specifies both the permissions to use and
+%[- MARK -] the type of node to be created, being combined (bitwise OR) with one
+%[- MARK -] of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are
+%[- MARK -] available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device}
+%[- MARK -] defines the newly created device special file (probably using
+%[- MARK -] \function{os.makedev()}), otherwise it is ignored.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{major}{device}
+%[- MARK -] -Extracts a device major number from a raw device number.
+%[- MARK -] +Extracts the device major number from a raw device number (usually
+%[- MARK -] +the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{minor}{device}
+%[- MARK -] -Extracts a device minor number from a raw device number.
+%[- MARK -] +Extracts the device minor number from a raw device number (usually
+%[- MARK -] +the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{makedev}{major, minor}
+%[- MARK -] Composes a raw device number from the major and minor device numbers.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{chmod}{path, mode}
@@ -831,6 +1313,28 @@
ignorato. Dove usato, il valore corrente di umask viene prima applicato
come maschera.
Disponibilità: Macintosh, \UNIX, Windows.
+%[- MARK -] BEGIN DIFF 015 of 41
+%[- MARK -] @@ 796
+%[- MARK -] \index{UNC paths!and \function{os.makedirs()}}
+%[- MARK -] Like \function{mkdir()},
+%[- MARK -] but makes all intermediate-level directories needed to contain the
+%[- MARK -] leaf directory. Throws an \exception{error} exception if the leaf
+%[- MARK -] directory already exists or cannot be created. The default \var{mode}
+%[- MARK -] -is \code{0777} (octal). This function does not properly handle UNC
+%[- MARK -] -paths (only relevant on Windows systems; Universal Naming Convention
+%[- MARK -] -paths are those that use the `\code{\e\e host\e path}' syntax).
+%[- MARK -] +is \code{0777} (octal). On some systems, \var{mode} is ignored.
+%[- MARK -] +Where it is used, the current umask value is first masked out.
+%[- MARK -] +\note{\function{makedirs()} will become confused if the path elements
+%[- MARK -] +to create include \var{os.pardir}.}
+%[- MARK -] \versionadded{1.5.2}
+%[- MARK -] +\versionchanged[This function now handles UNC paths correctly]{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{pathconf}{path, name}
+%[- MARK -] Return system configuration information relevant to a named file.
+%[- MARK -] \var{name} specifies the configuration value to retrieve; it may be a
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{makedirs}{path\optional{, mode}}
@@ -844,6 +1348,21 @@
Naming Convention) sono quelli che usano la sintassi
`\code{\e\e host\e path}'.
\versionadded{1.5.2}
+%[- MARK -] BEGIN DIFF 016 of 41
+%[- MARK -] @@ 812
+%[- MARK -] others). Some platforms define additional names as well. The names
+%[- MARK -] known to the host operating system are given in the
+%[- MARK -] \code{pathconf_names} dictionary. For configuration variables not
+%[- MARK -] included in that mapping, passing an integer for \var{name} is also
+%[- MARK -] accepted.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -]
+%[- MARK -] If \var{name} is a string and is not known, \exception{ValueError} is
+%[- MARK -] raised. If a specific value for \var{name} is not supported by the
+%[- MARK -] host system, even if it is included in \code{pathconf_names}, an
+%[- MARK -] \exception{OSError} is raised with \constant{errno.EINVAL} for the
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{pathconf}{path, name}
@@ -864,6 +1383,30 @@
\var{name} non viene supportato dal sistema ospite anche se presente in
\code{pathconf_names}, viene sollevata un'eccezione \exception{OSError}
con un valore pari a \constant{errno.EINVAL} come codice di errore.
+%[- MARK -] BEGIN DIFF 017 of 41
+%[- MARK -] @@ 826
+%[- MARK -] \begin{datadesc}{pathconf_names}
+%[- MARK -] Dictionary mapping names accepted by \function{pathconf()} and
+%[- MARK -] \function{fpathconf()} to the integer values defined for those names
+%[- MARK -] by the host operating system. This can be used to determine the set
+%[- MARK -] of names known to the system.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{readlink}{path}
+%[- MARK -] Return a string representing the path to which the symbolic link
+%[- MARK -] points. The result may be either an absolute or relative pathname; if
+%[- MARK -] it is relative, it may be converted to an absolute pathname using
+%[- MARK -] \code{os.path.join(os.path.dirname(\var{path}), \var{result})}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{remove}{path}
+%[- MARK -] Remove the file \var{path}. If \var{path} is a directory,
+%[- MARK -] \exception{OSError} is raised; see \function{rmdir()} below to remove
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{datadesc}{pathconf_names}
@@ -893,6 +1436,33 @@
viene reso disponibile fino al momento in cui il file non sia più in
uso.
Disponibilità: Macintosh, \UNIX, Windows.
+%[- MARK -] BEGIN DIFF 018 of 41
+%[- MARK -] @@ 852
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{removedirs}{path}
+%[- MARK -] \index{directory!deleting}
+%[- MARK -] Removes directories recursively. Works like
+%[- MARK -] \function{rmdir()} except that, if the leaf directory is
+%[- MARK -] -successfully removed, directories corresponding to rightmost path
+%[- MARK -] -segments will be pruned way until either the whole path is consumed or
+%[- MARK -] -an error is raised (which is ignored, because it generally means that
+%[- MARK -] -a parent directory is not empty). Throws an \exception{error}
+%[- MARK -] -exception if the leaf directory could not be successfully removed.
+%[- MARK -] +successfully removed, \function{removedirs()}
+%[- MARK -] +tries to successively remove every parent directory mentioned in
+%[- MARK -] +\var{path} until an error is raised (which is ignored, because
+%[- MARK -] +it generally means that a parent directory is not empty).
+%[- MARK -] +For example, \samp{os.removedirs('foo/bar/baz')} will first remove
+%[- MARK -] +the directory \samp{'foo/bar/baz'}, and then remove \samp{'foo/bar'}
+%[- MARK -] +and \samp{'foo'} if they are empty.
+%[- MARK -] +Raises \exception{OSError} if the leaf directory could not be
+%[- MARK -] +successfully removed.
+%[- MARK -] \versionadded{1.5.2}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{rename}{src, dst}
+%[- MARK -] Rename the file or directory \var{src} to \var{dst}. If \var{dst} is
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{removedirs}{path}
@@ -957,6 +1527,21 @@
\member{st_atime} (tempo dell'accesso più recente), \member{st_mtime}
(tempo della modifica dei contenuti più recente), \member{st_ctime}
(dipende dalla piattaforma; tempo indicante il più recente cambiamento
+%[- MARK -] BEGIN DIFF 019 of 41
+%[- MARK -] @@ 913
+%[- MARK -] the time of creation on Windows).
+%[- MARK -]
+%[- MARK -] \versionchanged [If \function{stat_float_times} returns true, the time
+%[- MARK -] values are floats, measuring seconds. Fractions of a second may be
+%[- MARK -] reported if the system supports that. On Mac OS, the times are always
+%[- MARK -] -floats. See \function{stat_float_times} for further discussion. ]{2.3}
+%[- MARK -] +floats. See \function{stat_float_times} for further discussion]{2.3}
+%[- MARK -]
+%[- MARK -] On some Unix systems (such as Linux), the following attributes may
+%[- MARK -] also be available:
+%[- MARK -] \member{st_blocks} (number of blocks allocated for file),
+%[- MARK -] \member{st_blksize} (filesystem blocksize),
+%[- MARK -] END DIFF
dei metadata su \UNIX{}, tempo di creazione su Windows).
\versionchanged [Se \function{stat_float_times} restituisce vero, i
@@ -980,6 +1565,41 @@
Su sistemi RISCOS, sono anche disponibili i seguenti attributi:
\member{st_ftype} (tipo di file),
\member{st_attrs} (attributi),
+%[- MARK -] BEGIN DIFF 020 of 41
+%[- MARK -] @@ 950
+%[- MARK -] More items may be added at the end by some implementations.
+%[- MARK -] The standard module \refmodule{stat}\refstmodindex{stat} defines
+%[- MARK -] functions and constants that are useful for extracting information
+%[- MARK -] from a \ctype{stat} structure.
+%[- MARK -] (On Windows, some items are filled with dummy values.)
+%[- MARK -] +
+%[- MARK -] +\note{The exact meaning and resolution of the \member{st_atime},
+%[- MARK -] + \member{st_mtime}, and \member{st_ctime} members depends on the
+%[- MARK -] + operating system and the file system. For example, on Windows systems
+%[- MARK -] + using the FAT or FAT32 file systems, \member{st_mtime} has 2-second
+%[- MARK -] + resolution, and \member{st_atime} has only 1-day resolution. See
+%[- MARK -] + your operating system documentation for details.}
+%[- MARK -] +
+%[- MARK -] Availability: Macintosh, \UNIX, Windows.
+%[- MARK -]
+%[- MARK -] \versionchanged
+%[- MARK -] [Added access to values as attributes of the returned object]{2.2}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{stat_float_times}{\optional{newvalue}}
+%[- MARK -] Determine whether \class{stat_result} represents time stamps as float
+%[- MARK -] -objects. If newval is True, future calls to stat() return floats, if
+%[- MARK -] -it is False, future calls return ints. If newval is omitted, return
+%[- MARK -] -the current setting.
+%[- MARK -] +objects. If \var{newvalue} is \code{True}, future calls to \function{stat()}
+%[- MARK -] +return floats, if it is \code{False}, future calls return ints.
+%[- MARK -] +If \var{newvalue} is omitted, return the current setting.
+%[- MARK -]
+%[- MARK -] For compatibility with older Python versions, accessing
+%[- MARK -] \class{stat_result} as a tuple always returns integers. For
+%[- MARK -] compatibility with Python 2.2, accessing the time stamps by field name
+%[- MARK -] also returns integers. Applications that want to determine the
+%[- MARK -] END DIFF
\member{st_obtype} (tipo di oggetto).
Per compatibilità con le versioni precedenti, il valore restituito da
@@ -1038,6 +1658,20 @@
disattivare la caratteristica fino a che la libreria non sia stata
corretta.
+%[- MARK -] BEGIN DIFF 021 of 41
+%[- MARK -] @@ 987
+%[- MARK -] \begin{funcdesc}{statvfs}{path}
+%[- MARK -] Perform a \cfunction{statvfs()} system call on the given path. The
+%[- MARK -] return value is an object whose attributes describe the filesystem on
+%[- MARK -] the given path, and correspond to the members of the
+%[- MARK -] \ctype{statvfs} structure, namely:
+%[- MARK -] +\member{f_bsize},
+%[- MARK -] \member{f_frsize},
+%[- MARK -] \member{f_blocks},
+%[- MARK -] \member{f_bfree},
+%[- MARK -] \member{f_bavail},
+%[- MARK -] \member{f_files},
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{statvfs}{path}
@@ -1074,6 +1708,46 @@
\begin{funcdesc}{symlink}{src, dst}
Crea un link simbolico che punta a \var{src}, chiamandolo \var{dst}.
Disponibilità: \UNIX.
+%[- MARK -] BEGIN DIFF 022 of 41
+%[- MARK -] @@ 1029
+%[- MARK -] On \UNIX, the environment variable \envvar{TMPDIR} overrides
+%[- MARK -] \var{dir}, while on Windows the \envvar{TMP} is used. The specific
+%[- MARK -] behavior of this function depends on the C library implementation;
+%[- MARK -] some aspects are underspecified in system documentation.
+%[- MARK -] \warning{Use of \function{tempnam()} is vulnerable to symlink attacks;
+%[- MARK -] -consider using \function{tmpfile()} instead.}
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +consider using \function{tmpfile()} (section \ref{os-newstreams})
+%[- MARK -] +instead.} Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{tmpnam}{}
+%[- MARK -] Return a unique path name that is reasonable for creating a temporary
+%[- MARK -] file. This will be an absolute path that names a potential directory
+%[- MARK -] entry in a common location for temporary files. Applications are
+%[- MARK -] responsible for properly creating and managing files created using
+%[- MARK -] paths returned by \function{tmpnam()}; no automatic cleanup is
+%[- MARK -] provided.
+%[- MARK -] \warning{Use of \function{tmpnam()} is vulnerable to symlink attacks;
+%[- MARK -] -consider using \function{tmpfile()} instead.}
+%[- MARK -] -Availability: \UNIX, Windows. This function probably shouldn't be used
+%[- MARK -] -on Windows, though: Microsoft's implementation of \function{tmpnam()}
+%[- MARK -] -always creates a name in the root directory of the current drive, and
+%[- MARK -] -that's generally a poor location for a temp file (depending on
+%[- MARK -] -privileges, you may not even be able to open a file using this name).
+%[- MARK -] +consider using \function{tmpfile()} (section \ref{os-newstreams})
+%[- MARK -] +instead.} Availability: \UNIX, Windows. This function probably
+%[- MARK -] +shouldn't be used on Windows, though: Microsoft's implementation of
+%[- MARK -] +\function{tmpnam()} always creates a name in the root directory of the
+%[- MARK -] +current drive, and that's generally a poor location for a temp file
+%[- MARK -] +(depending on privileges, you may not even be able to open a file
+%[- MARK -] +using this name).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{TMP_MAX}
+%[- MARK -] The maximum number of unique names that \function{tmpnam()} will
+%[- MARK -] generate before reusing names.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}}
@@ -1128,6 +1802,25 @@
\function{remove()} con un altro nome; il nome \function{unlink()} è
nella tradizione \UNIX{}.
Disponibilità: Macintosh, \UNIX, Windows.
+%[- MARK -] BEGIN DIFF 023 of 41
+%[- MARK -] @@ 1067
+%[- MARK -] Set the access and modified times of the file specified by \var{path}.
+%[- MARK -] If \var{times} is \code{None}, then the file's access and modified
+%[- MARK -] times are set to the current time. Otherwise, \var{times} must be a
+%[- MARK -] 2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})}
+%[- MARK -] which is used to set the access and modified times, respectively.
+%[- MARK -] +Whether a directory can be given for \var{path} depends on whether the
+%[- MARK -] +operating system implements directories as files (for example, Windows
+%[- MARK -] +does not). Note that the exact times you set here may not be returned
+%[- MARK -] +by a subsequent \function{stat()} call, depending on the resolution
+%[- MARK -] +with which your operating system records access and modification times;
+%[- MARK -] +see \function{stat()}.
+%[- MARK -] \versionchanged[Added support for \code{None} for \var{times}]{2.0}
+%[- MARK -] Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{walk}{top\optional{, topdown\code{=True}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{utime}{path, times}
@@ -1167,6 +1860,26 @@
sotto directory. (le directory vengono generate dall'alto in basso).
Se \var{topdown} vale falso, la tripla di una specifica directory viene
generata dopo le triple di tutte le sue sotto directory (le directory
+%[- MARK -] BEGIN DIFF 024 of 41
+%[- MARK -] @@ 1103
+%[- MARK -] remain in \var{dirnames}; this can be used to prune the search,
+%[- MARK -] impose a specific order of visiting, or even to inform \function{walk()}
+%[- MARK -] about directories the caller creates or renames before it resumes
+%[- MARK -] \function{walk()} again. Modifying \var{dirnames} when \var{topdown} is
+%[- MARK -] false is ineffective, because in bottom-up mode the directories in
+%[- MARK -] -\var{dirnames} are generated before \var{dirnames} itself is generated.
+%[- MARK -] +\var{dirnames} are generated before \var{dirpath} itself is generated.
+%[- MARK -]
+%[- MARK -] By default errors from the \code{os.listdir()} call are ignored. If
+%[- MARK -] optional argument \var{onerror} is specified, it should be a function;
+%[- MARK -] -it will be called with one argument, an os.error instance. It can
+%[- MARK -] +it will be called with one argument, an \exception{OSError} instance. It can
+%[- MARK -] report the error to continue with the walk, or raise the exception
+%[- MARK -] to abort the walk. Note that the filename is available as the
+%[- MARK -] \code{filename} attribute of the exception object.
+%[- MARK -]
+%[- MARK -] \begin{notice}
+%[- MARK -] END DIFF
vengono generate dal basso in alto).
Quando \var{topdown} vale vero, il chiamante può modificare la lista
@@ -1210,6 +1923,46 @@
Questo esempio stampa il numero di byte usato da ciascun file, esclusi
quelli di tipo directory, che si trovi in una sotto directory di quella
+%[- MARK -] BEGIN DIFF 025 of 41
+%[- MARK -] @@ 1137
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import os
+%[- MARK -] from os.path import join, getsize
+%[- MARK -] for root, dirs, files in os.walk('python/Lib/email'):
+%[- MARK -] print root, "consumes",
+%[- MARK -] - print sum([getsize(join(root, name)) for name in files]),
+%[- MARK -] + print sum(getsize(join(root, name)) for name in files),
+%[- MARK -] print "bytes in", len(files), "non-directory files"
+%[- MARK -] if 'CVS' in dirs:
+%[- MARK -] dirs.remove('CVS') # don't visit CVS directories
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] In the next example, walking the tree bottom up is essential:
+%[- MARK -] \function{rmdir()} doesn't allow deleting a directory before the
+%[- MARK -] directory is empty:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -import os
+%[- MARK -] -from os.path import join
+%[- MARK -] -# Delete everything reachable from the directory named in 'top'.
+%[- MARK -] +# Delete everything reachable from the directory named in 'top',
+%[- MARK -] +# assuming there are no symbolic links.
+%[- MARK -] # CAUTION: This is dangerous! For example, if top == '/', it
+%[- MARK -] # could delete all your disk files.
+%[- MARK -] +import os
+%[- MARK -] for root, dirs, files in os.walk(top, topdown=False):
+%[- MARK -] for name in files:
+%[- MARK -] - os.remove(join(root, name))
+%[- MARK -] + os.remove(os.path.join(root, name))
+%[- MARK -] for name in dirs:
+%[- MARK -] - os.rmdir(join(root, name))
+%[- MARK -] + os.rmdir(os.path.join(root, name))
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
di partenza, escluse le directory CVS e le loro sotto directory.
\begin{verbatim}
@@ -1257,6 +2010,21 @@
funzione \cfunction{main()} di un programma. Per esempio,
\samp{os.execv('/bin/echo', ['foo', 'bar'])} stamperà solamente
\samp{bar} sullo standard output; \samp{foo} verrà apparentemente
+%[- MARK -] BEGIN DIFF 026 of 41
+%[- MARK -] @@ 1183
+%[- MARK -] Generate a \constant{SIGABRT} signal to the current process. On
+%[- MARK -] \UNIX, the default behavior is to produce a core dump; on Windows, the
+%[- MARK -] process immediately returns an exit code of \code{3}. Be aware that
+%[- MARK -] programs which use \function{signal.signal()} to register a handler
+%[- MARK -] for \constant{SIGABRT} will behave differently.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{execl}{path, arg0, arg1, \moreargs}
+%[- MARK -] \funcline{execle}{path, arg0, arg1, \moreargs, env}
+%[- MARK -] \funcline{execlp}{file, arg0, arg1, \moreargs}
+%[- MARK -] END DIFF
ignorato.
@@ -1284,6 +2052,23 @@
chiamante. In \UNIX, il nuovo eseguibile viene caricato nel processo
corrente, e avrà lo stesso identificativo del processo in cui viene
eseguita la chiamata. Eventuali errori verranno riportati come
+%[- MARK -] BEGIN DIFF 027 of 41
+%[- MARK -] @@ 1207
+%[- MARK -] with if the number of parameters is fixed when the code is written;
+%[- MARK -] the individual parameters simply become additional parameters to the
+%[- MARK -] \function{execl*()} functions. The \character{v} variants are good
+%[- MARK -] when the number of parameters is variable, with the arguments being
+%[- MARK -] passed in a list or tuple as the \var{args} parameter. In either
+%[- MARK -] -case, the arguments to the child process must start with the name of
+%[- MARK -] -the command being run.
+%[- MARK -] +case, the arguments to the child process should start with the name of
+%[- MARK -] +the command being run, but this is not enforced.
+%[- MARK -]
+%[- MARK -] The variants which include a \character{p} near the end
+%[- MARK -] (\function{execlp()}, \function{execlpe()}, \function{execvp()},
+%[- MARK -] and \function{execvpe()}) will use the \envvar{PATH} environment
+%[- MARK -] variable to locate the program \var{file}. When the environment is
+%[- MARK -] END DIFF
eccezioni \exception{OSError}.
Le varianti \character{l} e \character{v} delle funzioni
@@ -1309,6 +2094,28 @@
\function{execle()}, \function{execv()} ed \function{execve()} non
faranno uso della variabile di ambiente \envvar{PATH} per localizzare
l'eseguibile; in questo caso l'argomento \var{path} deve contenere
+%[- MARK -] BEGIN DIFF 028 of 41
+%[- MARK -] @@ 1229
+%[- MARK -] the \var{env} parameter must be a mapping which is used to define the
+%[- MARK -] environment variables for the new process; the \function{execl()},
+%[- MARK -] \function{execlp()}, \function{execv()}, and \function{execvp()}
+%[- MARK -] all cause the new process to inherit the environment of the current
+%[- MARK -] process.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{_exit}{n}
+%[- MARK -] Exit to the system with status \var{n}, without calling cleanup
+%[- MARK -] handlers, flushing stdio buffers, etc.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -]
+%[- MARK -] \begin{notice}
+%[- MARK -] The standard way to exit is \code{sys.exit(\var{n})}.
+%[- MARK -] \function{_exit()} should normally only be used in the child process
+%[- MARK -] after a \function{fork()}.
+%[- MARK -] END DIFF
un percorso appropriato, relativo o assoluto, per arrivare ad esso.
Per \function{execle()}, \function{execlpe()}, \function{execve()} e
@@ -1332,6 +2139,198 @@
\function{_exit()} dovrebbe venire usata normalmente solo da processi
figli creati da \function{fork()}.
\end{notice}
+%[- MARK -] BEGIN DIFF 029 of 41
+%[- MARK -] @@ 1248
+%[- MARK -]
+%[- MARK -] The following exit codes are a defined, and can be used with
+%[- MARK -] \function{_exit()}, although they are not required. These are
+%[- MARK -] typically used for system programs written in Python, such as a
+%[- MARK -] mail server's external command delivery program.
+%[- MARK -] +\note{Some of these may not be available on all \UNIX{} platforms,
+%[- MARK -] +since there is some variation. These constants are defined where they
+%[- MARK -] +are defined by the underlying platform.}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_OK}
+%[- MARK -] Exit code that means no error occurred.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_USAGE}
+%[- MARK -] Exit code that means the command was used incorrectly, such as when
+%[- MARK -] the wrong number of arguments are given.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_DATAERR}
+%[- MARK -] Exit code that means the input data was incorrect.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_NOINPUT}
+%[- MARK -] Exit code that means an input file did not exist or was not readable.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_NOUSER}
+%[- MARK -] Exit code that means a specified user did not exist.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_NOHOST}
+%[- MARK -] Exit code that means a specified host did not exist.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_UNAVAILABLE}
+%[- MARK -] Exit code that means that a required service is unavailable.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_SOFTWARE}
+%[- MARK -] Exit code that means an internal software error was detected.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_OSERR}
+%[- MARK -] Exit code that means an operating system error was detected, such as
+%[- MARK -] the inability to fork or create a pipe.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_OSFILE}
+%[- MARK -] Exit code that means some system file did not exist, could not be
+%[- MARK -] opened, or had some other kind of error.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_CANTCREAT}
+%[- MARK -] Exit code that means a user specified output file could not be created.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_IOERR}
+%[- MARK -] Exit code that means that an error occurred while doing I/O on some file.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_TEMPFAIL}
+%[- MARK -] Exit code that means a temporary failure occurred. This indicates
+%[- MARK -] something that may not really be an error, such as a network
+%[- MARK -] connection that couldn't be made during a retryable operation.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_PROTOCOL}
+%[- MARK -] Exit code that means that a protocol exchange was illegal, invalid, or
+%[- MARK -] not understood.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_NOPERM}
+%[- MARK -] Exit code that means that there were insufficient permissions to
+%[- MARK -] perform the operation (but not intended for file system problems).
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_CONFIG}
+%[- MARK -] Exit code that means that some kind of configuration error occurred.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{EX_NOTFOUND}
+%[- MARK -] Exit code that means something like ``an entry was not found''.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{fork}{}
+%[- MARK -] Fork a child process. Return \code{0} in the child, the child's
+%[- MARK -] process id in the parent.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{forkpty}{}
+%[- MARK -] Fork a child process, using a new pseudo-terminal as the child's
+%[- MARK -] controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
+%[- MARK -] where \var{pid} is \code{0} in the child, the new child's process id
+%[- MARK -] in the parent, and \var{fd} is the file descriptor of the master end
+%[- MARK -] of the pseudo-terminal. For a more portable approach, use the
+%[- MARK -] \refmodule{pty} module.
+%[- MARK -] -Availability: Some flavors of \UNIX.
+%[- MARK -] +Availability: Macintosh, Some flavors of \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{kill}{pid, sig}
+%[- MARK -] \index{process!killing}
+%[- MARK -] \index{process!signalling}
+%[- MARK -] Kill the process \var{pid} with signal \var{sig}. Constants for the
+%[- MARK -] specific signals available on the host platform are defined in the
+%[- MARK -] \refmodule{signal} module.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{killpg}{pgid, sig}
+%[- MARK -] \index{process!killing}
+%[- MARK -] \index{process!signalling}
+%[- MARK -] Kill the process group \var{pgid} with the signal \var{sig}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{nice}{increment}
+%[- MARK -] Add \var{increment} to the process's ``niceness''. Return the new
+%[- MARK -] niceness.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{plock}{op}
+%[- MARK -] Lock program segments into memory. The value of \var{op}
+%[- MARK -] (defined in \code{<sys/lock.h>}) determines which segments are locked.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdescni}{popen}{\unspecified}
+%[- MARK -] \funclineni{popen2}{\unspecified}
+%[- MARK -] \funclineni{popen3}{\unspecified}
+%[- MARK -] END DIFF
\end{funcdesc}
Vengono definiti i seguenti codici di uscita utilizzabili con
@@ -1580,6 +2579,33 @@
\function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()}
non sono disponibili in Windows.
\versionadded{1.6}
+%[- MARK -] BEGIN DIFF 030 of 41
+%[- MARK -] @@ 1481
+%[- MARK -] \dataline{P_NOWAITO}
+%[- MARK -] Possible values for the \var{mode} parameter to the \function{spawn*()}
+%[- MARK -] family of functions. If either of these values is given, the
+%[- MARK -] \function{spawn*()} functions will return as soon as the new process
+%[- MARK -] has been created, with the process ID as the return value.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{1.6}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{P_WAIT}
+%[- MARK -] Possible value for the \var{mode} parameter to the \function{spawn*()}
+%[- MARK -] family of functions. If this is given as \var{mode}, the
+%[- MARK -] \function{spawn*()} functions will not return until the new process
+%[- MARK -] has run to completion and will return the exit code of the process the
+%[- MARK -] run is successful, or \code{-\var{signal}} if a signal kills the
+%[- MARK -] process.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \versionadded{1.6}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{P_DETACH}
+%[- MARK -] \dataline{P_OVERLAY}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{datadesc}{P_NOWAIT}
@@ -1660,6 +2686,43 @@
\code{0}; in sistemi con \program{cmd.exe} (Windows NT, 2000 e XP)
questo valore corrisponde allo stato di uscita del comando eseguito;
per sistemi che usano una shell non nativa, consultate la
+%[- MARK -] BEGIN DIFF 031 of 41
+%[- MARK -] @@ 1546
+%[- MARK -] \envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME)
+%[- MARK -] this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000
+%[- MARK -] and XP) this is the exit status of the command run; on systems using
+%[- MARK -] a non-native shell, consult your shell documentation.
+%[- MARK -]
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{times}{}
+%[- MARK -] Return a 5-tuple of floating point numbers indicating accumulated
+%[- MARK -] (processor or other)
+%[- MARK -] times, in seconds. The items are: user time, system time, children's
+%[- MARK -] user time, children's system time, and elapsed real time since a fixed
+%[- MARK -] point in the past, in that order. See the \UNIX{} manual page
+%[- MARK -] \manpage{times}{2} or the corresponding Windows Platform API
+%[- MARK -] documentation.
+%[- MARK -] -Availability: \UNIX, Windows.
+%[- MARK -] +Availability: Macintosh, \UNIX, Windows.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{wait}{}
+%[- MARK -] Wait for completion of a child process, and return a tuple containing
+%[- MARK -] its pid and exit status indication: a 16-bit number, whose low byte is
+%[- MARK -] the signal number that killed the process, and whose high byte is the
+%[- MARK -] exit status (if the signal number is zero); the high bit of the low
+%[- MARK -] byte is set if a core file was produced.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{waitpid}{pid, options}
+%[- MARK -] The details of this function differ on \UNIX{} and Windows.
+%[- MARK -]
+%[- MARK -] END DIFF
documentazione della shell.
Disponibilità: \UNIX, Windows.
@@ -1720,6 +2783,26 @@
necessariamente ad un processo figlio. La funzione \function{spawn()}
chiamata con \constant{P_NOWAIT} restituisce degli handle adatti per
venire usati con questa funzione.
+%[- MARK -] BEGIN DIFF 032 of 41
+%[- MARK -] @@ 1602
+%[- MARK -] The \function{spawn()} functions called with \constant{P_NOWAIT}
+%[- MARK -] return suitable process handles.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{WNOHANG}
+%[- MARK -] -The option for \function{waitpid()} to avoid hanging if no child
+%[- MARK -] -process status is available immediately.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +The option for \function{waitpid()} to return immediately if no child
+%[- MARK -] +process status is available immediately. The function returns
+%[- MARK -] +\code{(0, 0)} in this case.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{WCONTINUED}
+%[- MARK -] This option causes child processes to be reported if they have been
+%[- MARK -] continued from a job control stop since their status was last
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{datadesc}{WNOHANG}
@@ -1736,6 +2819,21 @@
stato.
Disponibilità: alcuni sistemi \UNIX{}.
\versionadded{2.3}
+%[- MARK -] BEGIN DIFF 033 of 41
+%[- MARK -] @@ 1619
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{WUNTRACED}
+%[- MARK -] This option causes child processes to be reported if they have been
+%[- MARK -] stopped but their current state has not been reported since they were
+%[- MARK -] stopped.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] The following functions take a process status code as returned by
+%[- MARK -] \function{system()}, \function{wait()}, or \function{waitpid()} as a
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{WUNTRACED}
@@ -1749,6 +2847,21 @@
Le seguenti funzioni accettano come argomento un codice di uscita di un
processo come restituito da \function{system()}, \function{wait()},
o \function{waitpid()}. Possono venire usate per determinare il modo
+%[- MARK -] BEGIN DIFF 034 of 41
+%[- MARK -] @@ 1631
+%[- MARK -] process.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WCOREDUMP}{status}
+%[- MARK -] Returns \code{True} if a core dump was generated for the process,
+%[- MARK -] otherwise it returns \code{False}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WIFCONTINUED}{status}
+%[- MARK -] Returns \code{True} if the process has been continued from a job
+%[- MARK -] END DIFF
in cui è terminato il processo.
\begin{funcdesc}{WCOREDUMP}{status}
@@ -1769,6 +2882,48 @@
Restituisce \code{True} se il processo viene bloccato, altrimenti
restituisce \code{False}.
Disponibilità: \UNIX.
+%[- MARK -] BEGIN DIFF 035 of 41
+%[- MARK -] @@ 1651
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WIFSIGNALED}{status}
+%[- MARK -] Returns \code{True} if the process exited due to a signal, otherwise
+%[- MARK -] it returns \code{False}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WIFEXITED}{status}
+%[- MARK -] Returns \code{True} if the process exited using the \manpage{exit}{2}
+%[- MARK -] system call, otherwise it returns \code{False}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WEXITSTATUS}{status}
+%[- MARK -] If \code{WIFEXITED(\var{status})} is true, return the integer
+%[- MARK -] parameter to the \manpage{exit}{2} system call. Otherwise, the return
+%[- MARK -] value is meaningless.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WSTOPSIG}{status}
+%[- MARK -] Return the signal which caused the process to stop.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{WTERMSIG}{status}
+%[- MARK -] Return the signal which caused the process to exit.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{Miscellaneous System Information \label{os-path}}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{WIFSIGNALED}{status}
@@ -1802,6 +2957,21 @@
\end{funcdesc}
+%[- MARK -] BEGIN DIFF 036 of 41
+%[- MARK -] @@ 1691
+%[- MARK -] others). Some platforms define additional names as well. The names
+%[- MARK -] known to the host operating system are given in the
+%[- MARK -] \code{confstr_names} dictionary. For configuration variables not
+%[- MARK -] included in that mapping, passing an integer for \var{name} is also
+%[- MARK -] accepted.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -]
+%[- MARK -] If the configuration value specified by \var{name} isn't defined, the
+%[- MARK -] empty string is returned.
+%[- MARK -]
+%[- MARK -] If \var{name} is a string and is not known, \exception{ValueError} is
+%[- MARK -] END DIFF
\subsection{Informazioni di sistema di vario tipo \label{os-path}}
@@ -1825,6 +2995,29 @@
supportato dal sistema, anche se incluso in \code{confstr_names}, viene
sollevata l'eccezione \exception{OSError} con un codice di errore
\constant{errno.EINVAL}.
+%[- MARK -] BEGIN DIFF 037 of 41
+%[- MARK -] @@ 1707
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{confstr_names}
+%[- MARK -] Dictionary mapping names accepted by \function{confstr()} to the
+%[- MARK -] integer values defined for those names by the host operating system.
+%[- MARK -] This can be used to determine the set of names known to the system.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getloadavg}{}
+%[- MARK -] Return the number of processes in the system run queue averaged over
+%[- MARK -] -the last 1, 5, and 15 minutes or raises OSError if the load average
+%[- MARK -] -was unobtainable.
+%[- MARK -] +the last 1, 5, and 15 minutes or raises \exception{OSError} if the load
+%[- MARK -] +average was unobtainable.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{sysconf}{name}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{datadesc}{confstr_names}
@@ -1841,6 +3034,29 @@
l'eccezione OSError se questo dato non è ottenibile.
\versionadded{2.3}
+%[- MARK -] BEGIN DIFF 038 of 41
+%[- MARK -] @@ 1725
+%[- MARK -] If the configuration value specified by \var{name} isn't defined,
+%[- MARK -] \code{-1} is returned. The comments regarding the \var{name}
+%[- MARK -] parameter for \function{confstr()} apply here as well; the dictionary
+%[- MARK -] that provides information on the known names is given by
+%[- MARK -] \code{sysconf_names}.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{sysconf_names}
+%[- MARK -] Dictionary mapping names accepted by \function{sysconf()} to the
+%[- MARK -] integer values defined for those names by the host operating system.
+%[- MARK -] This can be used to determine the set of names known to the system.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +Availability: Macintosh, \UNIX.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] The follow data values are used to support path manipulation
+%[- MARK -] operations. These are defined for all platforms.
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{sysconf}{name}
@@ -1867,6 +3083,38 @@
definite per tutte le piattaforme.
Nel modulo \refmodule{os.path} vengono definite operazioni di più alto
+%[- MARK -] BEGIN DIFF 039 of 41
+%[- MARK -] @@ 1746
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{curdir}
+%[- MARK -] The constant string used by the operating system to refer to the current
+%[- MARK -] directory.
+%[- MARK -] -For example: \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
+%[- MARK -] +For example: \code{'.'} for \POSIX{} or \code{':'} for Mac OS 9.
+%[- MARK -] Also available via \module{os.path}.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{pardir}
+%[- MARK -] The constant string used by the operating system to refer to the parent
+%[- MARK -] directory.
+%[- MARK -] -For example: \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
+%[- MARK -] +For example: \code{'..'} for \POSIX{} or \code{'::'} for Mac OS 9.
+%[- MARK -] Also available via \module{os.path}.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{sep}
+%[- MARK -] The character used by the operating system to separate pathname components,
+%[- MARK -] -for example, \character{/} for \POSIX{} or \character{:} for the
+%[- MARK -] -Macintosh. Note that knowing this is not sufficient to be able to
+%[- MARK -] +for example, \character{/} for \POSIX{} or \character{:} for
+%[- MARK -] +Mac OS 9. Note that knowing this is not sufficient to be able to
+%[- MARK -] parse or concatenate pathnames --- use \function{os.path.split()} and
+%[- MARK -] \function{os.path.join()} --- but it is occasionally useful.
+%[- MARK -] Also available via \module{os.path}.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] END DIFF
livello sui nomi dei percorsi.
@@ -1907,6 +3155,21 @@
per esempio, il carattere \character{.} nel nome \file{os.py}.
\`E anche disponibile nel modulo \module{os.path}.
\versionadded{2.2}
+%[- MARK -] BEGIN DIFF 040 of 41
+%[- MARK -] @@ 1783
+%[- MARK -] \versionadded{2.2}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{pathsep}
+%[- MARK -] The character conventionally used by the operating system to separate
+%[- MARK -] -search patch components (as in \envvar{PATH}), such as \character{:} for
+%[- MARK -] +search path components (as in \envvar{PATH}), such as \character{:} for
+%[- MARK -] \POSIX{} or \character{;} for Windows.
+%[- MARK -] Also available via \module{os.path}.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{defpath}
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{pathsep}
@@ -1922,6 +3185,41 @@
funzioni di tipo \function{exec*p*()} e \function{spawn*p*()}, nel caso
in cui l'ambiente non abbia una chiave \code{'PATH'}.
\`E anche disponibile nel modulo \module{os.path}.
+%[- MARK -] BEGIN DIFF 041 of 41
+%[- MARK -] @@ 1801
+%[- MARK -] The string used to separate (or, rather, terminate) lines on the
+%[- MARK -] current platform. This may be a single character, such as \code{'\e
+%[- MARK -] n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters,
+%[- MARK -] for example, \code{'\e r\e n'} for Windows.
+%[- MARK -] \end{datadesc}
+%[- MARK -] +
+%[- MARK -] +\begin{datadesc}{devnull}
+%[- MARK -] +The file path of the null device.
+%[- MARK -] +For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for
+%[- MARK -] +Mac OS 9.
+%[- MARK -] +Also available via \module{os.path}.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{datadesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +\subsection{Miscellaneous Functions \label{os-miscfunc}}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{urandom}{n}
+%[- MARK -] +Return a string of \var{n} random bytes suitable for cryptographic use.
+%[- MARK -] +
+%[- MARK -] +This function returns random bytes from an OS-specific
+%[- MARK -] +randomness source. The returned data should be unpredictable enough for
+%[- MARK -] +cryptographic applications, though its exact quality depends on the OS
+%[- MARK -] +implementation. On a UNIX-like system this will query /dev/urandom, and
+%[- MARK -] +on Windows it will use CryptGenRandom. If a randomness source is not
+%[- MARK -] +found, \exception{NotImplementedError} will be raised.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{linesep}
Modified: python/python/Doc/branches/2.4.3/lib/libossaudiodev.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libossaudiodev.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libossaudiodev.tex Fri Jun 2 12:52:55 2006
@@ -171,10 +171,61 @@
\begin{methoddesc}[audio device]{nonblock}{}
Pone la periferica in modalità non bloccante. Una volta in modo
non bloccante, non c'è modo di farla tornare in modo bloccante.
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 164
+%[- MARK -] is no way to return it to blocking mode.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[audio device]{getfmts}{}
+%[- MARK -] Return a bitmask of the audio output formats supported by the
+%[- MARK -] -soundcard. On a typical Linux system, these formats are:
+%[- MARK -] +soundcard. Some of the formats supported by OSS are:
+%[- MARK -]
+%[- MARK -] \begin{tableii}{l|l}{constant}{Format}{Description}
+%[- MARK -] \lineii{AFMT_MU_LAW}
+%[- MARK -] {a logarithmic encoding (used by Sun \code{.au} files and
+%[- MARK -] \filenq{/dev/audio})}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[audio device]{getfmts}{}
Restituisce una maschera dei bit dei formati audio supportati dalla
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 178
+%[- MARK -] {a 4:1 compressed format defined by the Interactive Multimedia
+%[- MARK -] Association}
+%[- MARK -] \lineii{AFMT_U8}
+%[- MARK -] {Unsigned, 8-bit audio}
+%[- MARK -] \lineii{AFMT_S16_LE}
+%[- MARK -] - {Unsigned, 16-bit audio, little-endian byte order (as used by
+%[- MARK -] + {Signed, 16-bit audio, little-endian byte order (as used by
+%[- MARK -] Intel processors)}
+%[- MARK -] \lineii{AFMT_S16_BE}
+%[- MARK -] - {Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
+%[- MARK -] + {Signed, 16-bit audio, big-endian byte order (as used by 68k,
+%[- MARK -] PowerPC, Sparc)}
+%[- MARK -] \lineii{AFMT_S8}
+%[- MARK -] {Signed, 8 bit audio}
+%[- MARK -] \lineii{AFMT_U16_LE}
+%[- MARK -] - {Signed, 16-bit little-endian audio}
+%[- MARK -] + {Unsigned, 16-bit little-endian audio}
+%[- MARK -] \lineii{AFMT_U16_BE}
+%[- MARK -] - {Signed, 16-bit big-endian audio}
+%[- MARK -] + {Unsigned, 16-bit big-endian audio}
+%[- MARK -] \end{tableii}
+%[- MARK -] -Most systems support only a subset of these formats. Many devices only
+%[- MARK -] -support \constant{AFMT_U8}; the most common format used today is
+%[- MARK -] -\constant{AFMT_S16_LE}.
+%[- MARK -] +Consult the OSS documentation for a full list of audio formats, and note
+%[- MARK -] +that most devices support only a subset of these formats. Some older
+%[- MARK -] +devices only support \constant{AFMT_U8}; the most common format used
+%[- MARK -] +today is \constant{AFMT_S16_LE}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[audio device]{setfmt}{format}
+%[- MARK -] Try to set the current audio format to \var{format}---see
+%[- MARK -] \method{getfmts()} for a list. Returns the audio format that the device
+%[- MARK -] END DIFF
scheda sonora. Su un tpico sistema Linux, questi formati sono:
\begin{tableii}{l|l}{constant}{Formato}{Descrizione}
@@ -264,6 +315,21 @@
ed alcuni semplici calcoli.
\begin{methoddesc}[audio device]{setparameters}
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 259
+%[- MARK -] methods. If \var{strict} is true, \method{setparameters()} checks to
+%[- MARK -] see if each parameter was actually set to the requested value, and
+%[- MARK -] raises \exception{OSSAudioError} if not. Returns a tuple (\var{format},
+%[- MARK -] \var{nchannels}, \var{samplerate}) indicating the parameter values that
+%[- MARK -] were actually set by the device driver (i.e., the same as the return
+%[- MARK -] -valus of \method{setfmt()}, \method{channels()}, and \method{speed()}).
+%[- MARK -] +values of \method{setfmt()}, \method{channels()}, and \method{speed()}).
+%[- MARK -]
+%[- MARK -] For example,
+%[- MARK -] \begin{verbatim}
+%[- MARK -] (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
{format, nchannels, samplerate \optional{, strict=False}}
Imposta i parametri della chiave audio di campionatura: il formato
Modified: python/python/Doc/branches/2.4.3/lib/libpdb.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpdb.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpdb.tex Fri Jun 2 12:52:55 2006
@@ -37,6 +37,30 @@
\end{verbatim}
\file{pdb.py} può anche venire invocato come script per
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 37
+%[- MARK -]
+%[- MARK -] \file{pdb.py} can also be invoked as
+%[- MARK -] a script to debug other scripts. For example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -python /usr/local/lib/python1.5/pdb.py myscript.py
+%[- MARK -] +python -m pdb myscript.py
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] +When invoked as a script, pdb will automatically enter post-mortem debugging
+%[- MARK -] +if the program being debugged exits abnormally. After post-mortem debugging
+%[- MARK -] +(or after normal exit of the program), pdb will restart the program.
+%[- MARK -] +Automatic restarting preserves pdb's state (such as breakpoints) and in most
+%[- MARK -] +cases is more useful than quitting the debugger upon program's exit.
+%[- MARK -] +\versionadded[Restarting post-mortem behavior added]{2.4}
+%[- MARK -] +
+%[- MARK -] Typical usage to inspect a crashed program is:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> import pdb
+%[- MARK -] >>> import mymodule
+%[- MARK -] END DIFF
effettuare il debug di altri script. Per esempio:
\begin{verbatim}
@@ -299,6 +323,21 @@
è un comando del debugger; esso esegue l'istruzione
\keyword{print} di Python.}
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 283
+%[- MARK -] value. \note{\samp{print} can also be used, but is not a debugger
+%[- MARK -] command --- this executes the Python \keyword{print} statement.}
+%[- MARK -]
+%[- MARK -] \item[pp \var{expression}]
+%[- MARK -]
+%[- MARK -] -Like the \samp{p} command, except the value of the exception is
+%[- MARK -] +Like the \samp{p} command, except the value of the expression is
+%[- MARK -] pretty-printed using the \module{pprint} module.
+%[- MARK -]
+%[- MARK -] \item[alias \optional{\var{name} \optional{command}}]
+%[- MARK -]
+%[- MARK -] Creates an alias called \var{name} that executes \var{command}. The
+%[- MARK -] END DIFF
\item[pp \var{expression}]
Come il comando \samp{p}, ad eccezione del fatto che il valore
@@ -414,6 +453,21 @@
Un'eccezione è stata sollevata. Viene chiamata la funzione di tracciamento locale;
\var{arg} è una tupla di tre elementi
(\code{(\var{eccezione}, \var{valore}, \var{traceback})}); il valore
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 391
+%[- MARK -] \var{traceback})}; the return value specifies the new local trace
+%[- MARK -] function.
+%[- MARK -]
+%[- MARK -] \item[\code{'c_call'}]
+%[- MARK -] A C function is about to be called. This may be an extension function
+%[- MARK -] -or a builtin. \var{arg} is the C function name.
+%[- MARK -] +or a builtin. \var{arg} is the C function object.
+%[- MARK -]
+%[- MARK -] \item[\code{'c_return'}]
+%[- MARK -] A C function has returned. \var{arg} is \code{None}.
+%[- MARK -]
+%[- MARK -] \item[\code{'c_exception'}]
+%[- MARK -] END DIFF
restituito specifica la nuova funzione di tracciamento locale.
\item[\code{'c_call'}]
Added: python/python/Doc/branches/2.4.3/lib/libpickletools.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libpickletools.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,33 @@
+%[- MARK -] BEGIN PART 001 of 1
+\section{\module{pickletools} --- Tools for pickle developers.}
+
+\declaremodule{standard}{pickletools}
+\modulesynopsis{Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.}
+
+This module contains various constants relating to the intimate
+details of the \refmodule{pickle} module, some lengthy comments about
+the implementation, and a few useful functions for analyzing pickled
+data. The contents of this module are useful for Python core
+developers who are working on the \module{pickle} and \module{cPickle}
+implementations; ordinary users of the \module{pickle} module probably
+won't find the \module{pickletools} module relevant.
+
+\begin{funcdesc}{dis}{pickle\optional{, out=None, memo=None, indentlevel=4}}
+Outputs a symbolic disassembly of the pickle to the file-like object
+\var{out}, defaulting to \code{sys.stdout}. \var{pickle} can be a
+string or a file-like object. \var{memo} can be a Python dictionary
+that will be used as the pickle's memo; it can be used to perform
+disassemblies across multiple pickles created by the same pickler.
+Successive levels, indicated by \code{MARK} opcodes in the stream, are
+indented by \var{indentlevel} spaces.
+\end{funcdesc}
+
+\begin{funcdesc}{genops}{pickle}
+Provides an iterator over all of the opcodes in a pickle, returning a
+sequence of \code{(\var{opcode}, \var{arg}, \var{pos})} triples.
+\var{opcode} is an instance of an \class{OpcodeInfo} class; \var{arg}
+is the decoded value, as a Python object, of the opcode's argument;
+\var{pos} is the position at which this opcode is located.
+\var{pickle} can be a string or a file-like object.
+\end{funcdesc}
+
Modified: python/python/Doc/branches/2.4.3/lib/libpipes.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpipes.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpipes.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,21 @@
\declaremodule{standard}{pipes}
\platform{Unix}
\sectionauthor{Moshe Zadka}{moshez a zadka.site.co.il}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 6
+%[- MARK -] \sectionauthor{Moshe Zadka}{moshez a zadka.site.co.il}
+%[- MARK -] \modulesynopsis{A Python interface to \UNIX\ shell pipelines.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] The \module{pipes} module defines a class to abstract the concept of
+%[- MARK -] -a \emph{pipeline} --- a sequence of convertors from one file to
+%[- MARK -] +a \emph{pipeline} --- a sequence of converters from one file to
+%[- MARK -] another.
+%[- MARK -]
+%[- MARK -] Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
+%[- MARK -] compatible shell for \function{os.system()} and \function{os.popen()}
+%[- MARK -] is required.
+%[- MARK -] END DIFF
\modulesynopsis{Una interfaccia Python per le pipeline della shell \UNIX{}.}
Modified: python/python/Doc/branches/2.4.3/lib/libplatform.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libplatform.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libplatform.tex Fri Jun 2 12:52:55 2006
@@ -14,6 +14,21 @@
Linux inserito nella sezione \UNIX{}.
\end{notice}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 15
+%[- MARK -]
+%[- MARK -] \subsection{Cross Platform}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
+%[- MARK -] Queries the given executable (defaults to the Python interpreter
+%[- MARK -] - binary) for various architecture informations.
+%[- MARK -] + binary) for various architecture information.
+%[- MARK -]
+%[- MARK -] Returns a tuple \code{(bits, linkage)} which contain information about
+%[- MARK -] the bit architecture and the linkage format used for the
+%[- MARK -] executable. Both values are returned as strings.
+%[- MARK -]
+%[- MARK -] END DIFF
\subsection{Multi piattaforma}
\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
Modified: python/python/Doc/branches/2.4.3/lib/libpopen2.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpopen2.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpopen2.tex Fri Jun 2 12:52:55 2006
@@ -23,6 +23,33 @@
pipe I/O. Il parametro \var{mode}, se fornito, dovrebbe esere la
stringa \code{'b'} o \code{'t'}; in Windows questo è necessario per
determinare se gli oggetti file devono venire aperti in modo binario o
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 22
+%[- MARK -] provided, should be the string \code{'b'} or \code{'t'}; on Windows
+%[- MARK -] this is needed to determine whether the file objects should be opened
+%[- MARK -] in binary or text mode. The default value for \var{mode} is
+%[- MARK -] \code{'t'}.
+%[- MARK -]
+%[- MARK -] +On \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed
+%[- MARK -] +directly to the program without shell intervention (as with
+%[- MARK -] +\function{os.spawnv()}). If \var{cmd} is a string it will be passed to the
+%[- MARK -] +shell (as with \function{os.system()}).
+%[- MARK -] +
+%[- MARK -] The only way to retrieve the return codes for the child processes is
+%[- MARK -] by using the \method{poll()} or \method{wait()} methods on the
+%[- MARK -] \class{Popen3} and \class{Popen4} classes; these are only available on
+%[- MARK -] \UNIX. This information is not available when using the
+%[- MARK -] \function{popen2()}, \function{popen3()}, and \function{popen4()}
+%[- MARK -] functions, or the equivalent functions in the \refmodule{os} module.
+%[- MARK -] +(Note that the tuples returned by the \refmodule{os} module's functions
+%[- MARK -] +are in a different order from the ones returned by the \module{popen2}
+%[- MARK -] +module.)
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}}
+%[- MARK -] Executes \var{cmd} as a sub-process. Returns the file objects
+%[- MARK -] \code{(\var{child_stdout}, \var{child_stdin})}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
in modo testo. Il valore predefinito per \var{mode} è \code{'t'}.
L'unico modo di recuperare i codici restituiti per i processi figli
@@ -76,6 +103,20 @@
standard output. Istanze di questa classe vengono tipicamente
generate usando \function{popen4()}.
\versionadded{2.0}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 70
+%[- MARK -] same file object as standard output. These are typically created
+%[- MARK -] using \function{popen4()}.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] \subsection{Popen3 and Popen4 Objects \label{popen3-objects}}
+%[- MARK -]
+%[- MARK -] Instances of the \class{Popen3} and \class{Popen4} classes have the
+%[- MARK -] following methods:
+%[- MARK -]
+%[- MARK -] END DIFF
\end{classdesc}
Modified: python/python/Doc/branches/2.4.3/lib/libpoplib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpoplib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpoplib.tex Fri Jun 2 12:52:55 2006
@@ -112,6 +112,23 @@
\begin{methoddesc}{stat}{}
Ottiene lo stato della mailbox. Il risultato è una tupla di due
interi: (\code{(\var{numero dei messaggi}, \var{dimensione della mailbox})}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 106
+%[- MARK -] \code{(\var{message count}, \var{mailbox size})}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{list}{\optional{which}}
+%[- MARK -] Request message list, result is in the form
+%[- MARK -] -\code{(\var{response}, ['mesg_num octets', ...])}. If \var{which} is
+%[- MARK -] -set, it is the message to list.
+%[- MARK -] +\code{(\var{response}, ['mesg_num octets', ...], \var{octets})}.
+%[- MARK -] +If \var{which} is set, it is the message to list.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{retr}{which}
+%[- MARK -] Retrieve whole message number \var{which}, and set its seen flag.
+%[- MARK -] Result is in form \code{(\var{response}, ['line', ...], \var{octets})}.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{list}{\optional{which}}
Modified: python/python/Doc/branches/2.4.3/lib/libposixpath.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libposixpath.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libposixpath.tex Fri Jun 2 12:52:55 2006
@@ -42,6 +42,62 @@
Restituisce il nome di directory contenuto nel percorso \var{path}.
Corrisponde alla prima metà della coppia restituita da
\code{split(\var{path})}.
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 41
+%[- MARK -] half of the pair returned by \code{split(\var{path})}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{exists}{path}
+%[- MARK -] Return \code{True} if \var{path} refers to an existing path.
+%[- MARK -] +Returns \code{False} for broken symbolic links.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{lexists}{path}
+%[- MARK -] +Return \code{True} if \var{path} refers to an existing path.
+%[- MARK -] +Returns \code{True} for broken symbolic links.
+%[- MARK -] +Equivalent to \function{exists()} on platforms lacking
+%[- MARK -] +\function{os.lstat()}.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{expanduser}{path}
+%[- MARK -] -Return the argument with an initial component of \samp{\~} or
+%[- MARK -] -\samp{\~\var{user}} replaced by that \var{user}'s home directory. An
+%[- MARK -] -initial \samp{\~{}} is replaced by the environment variable
+%[- MARK -] -\envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the
+%[- MARK -] -password directory through the built-in module
+%[- MARK -] -\refmodule{pwd}\refbimodindex{pwd}. If the expansion fails, or if the
+%[- MARK -] -path does not begin with a tilde, the path is returned unchanged. On
+%[- MARK -] -the Macintosh, this always returns \var{path} unchanged.
+%[- MARK -] +On \UNIX, return the argument with an initial component of \samp{\~} or
+%[- MARK -] +\samp{\~\var{user}} replaced by that \var{user}'s home directory.
+%[- MARK -] +An initial \samp{\~} is replaced by the environment variable
+%[- MARK -] +\envvar{HOME} if it is set; otherwise the current user's home directory
+%[- MARK -] +is looked up in the password directory through the built-in module
+%[- MARK -] +\refmodule{pwd}\refbimodindex{pwd}.
+%[- MARK -] +An initial \samp{\~\var{user}} is looked up directly in the
+%[- MARK -] +password directory.
+%[- MARK -] +
+%[- MARK -] +On Windows, only \samp{\~} is supported; it is replaced by the
+%[- MARK -] +environment variable \envvar{HOME} or by a combination of
+%[- MARK -] +\envvar{HOMEDRIVE} and \envvar{HOMEPATH}.
+%[- MARK -] +
+%[- MARK -] +If the expansion fails or if the
+%[- MARK -] +path does not begin with a tilde, the path is returned unchanged.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{expandvars}{path}
+%[- MARK -] Return the argument with environment variables expanded. Substrings
+%[- MARK -] of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
+%[- MARK -] replaced by the value of environment variable \var{name}. Malformed
+%[- MARK -] variable names and references to non-existing variables are left
+%[- MARK -] -unchanged. On the Macintosh, this always returns \var{path}
+%[- MARK -] unchanged.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getatime}{path}
+%[- MARK -] Return the time of last access of \var{path}. The return
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{exists}{path}
@@ -171,6 +227,34 @@
converte in minuscole tutte le lettere di \var{path}. In
Windows, converte inoltre le barre \character{/} in barre rovesciate
\character{\e}.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 149
+%[- MARK -] slashes.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{normpath}{path}
+%[- MARK -] Normalize a pathname. This collapses redundant separators and
+%[- MARK -] -up-level references, e.g. \code{A//B}, \code{A/./B} and
+%[- MARK -] +up-level references so that \code{A//B}, \code{A/./B} and
+%[- MARK -] \code{A/foo/../B} all become \code{A/B}. It does not normalize the
+%[- MARK -] case (use \function{normcase()} for that). On Windows, it converts
+%[- MARK -] -forward slashes to backward slashes.
+%[- MARK -] +forward slashes to backward slashes. It should be understood that this may
+%[- MARK -] +change the meaning of the path if it contains symbolic links!
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{realpath}{path}
+%[- MARK -] Return the canonical path of the specified filename, eliminating any
+%[- MARK -] -symbolic links encountered in the path.
+%[- MARK -] -Availability: \UNIX.
+%[- MARK -] +symbolic links encountered in the path (if they are supported by the
+%[- MARK -] +operating system).
+%[- MARK -] \versionadded{2.2}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{samefile}{path1, path2}
+%[- MARK -] Return \code{True} if both pathname arguments refer to the same file or
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{normpath}{path}
@@ -246,6 +330,38 @@
\code{\var{radice} + \var{estensione} == \var{path}}, e con
\var{ext} vuoto oppure iniziante con un punto e contenente al
massimo un punto.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 216
+%[- MARK -] such that \code{\var{root} + \var{ext} == \var{path}},
+%[- MARK -] and \var{ext} is empty or begins with a period and contains
+%[- MARK -] at most one period.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{splitunc}{path}
+%[- MARK -] +Split the pathname \var{path} into a pair \code{(\var{unc}, \var{rest})}
+%[- MARK -] +so that \var{unc} is the UNC mount point (such as \code{r'\e\e host\e mount'}),
+%[- MARK -] +if present, and \var{rest} the rest of the path (such as
+%[- MARK -] +\code{r'\e path\e file.ext'}). For paths containing drive letters, \var{unc}
+%[- MARK -] +will always be the empty string.
+%[- MARK -] +Availability: Windows.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{walk}{path, visit, arg}
+%[- MARK -] Calls the function \var{visit} with arguments
+%[- MARK -] \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
+%[- MARK -] directory tree rooted at \var{path} (including \var{path} itself, if it
+%[- MARK -] is a directory). The argument \var{dirname} specifies the visited
+%[- MARK -] directory, the argument \var{names} lists the files in the directory
+%[- MARK -] (gotten from \code{os.listdir(\var{dirname})}).
+%[- MARK -] The \var{visit} function may modify \var{names} to
+%[- MARK -] -influence the set of directories visited below \var{dirname}, e.g., to
+%[- MARK -] +influence the set of directories visited below \var{dirname}, e.g. to
+%[- MARK -] avoid visiting certain parts of the tree. (The object referred to by
+%[- MARK -] \var{names} must be modified in place, using \keyword{del} or slice
+%[- MARK -] assignment.)
+%[- MARK -]
+%[- MARK -] \begin{notice}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{walk}{path, visit, arg}
Modified: python/python/Doc/branches/2.4.3/lib/libpprint.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpprint.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpprint.tex Fri Jun 2 12:52:55 2006
@@ -190,6 +190,21 @@
Questo metodo viene fornito come estensione per consentire alle classi
derivate di modificare il modo in cui gli oggetti vengono convertiti in
stringhe. L'implementazione predefinita utilizza le caratteristiche
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 194
+%[- MARK -] \function{id()} of objects that are part of the current presentation
+%[- MARK -] context (direct and indirect containers for \var{object} that are
+%[- MARK -] affecting the presentation) as the keys; if an object needs to be
+%[- MARK -] presented which is already represented in \var{context}, the third
+%[- MARK -] return value should be true. Recursive calls to the \method{format()}
+%[- MARK -] -method should add additionaly entries for containers to this
+%[- MARK -] +method should add additional entries for containers to this
+%[- MARK -] dictionary. The fourth argument, \var{maxlevels}, gives the requested
+%[- MARK -] limit to recursion; this will be \code{0} if there is no requested
+%[- MARK -] limit. This argument should be passed unmodified to recursive calls.
+%[- MARK -] The fourth argument, \var{level} gives the current level; recursive
+%[- MARK -] calls should be passed a value less than that of the current call.
+%[- MARK -] END DIFF
proprie della implementazione di \function{saferepr()}.
\begin{methoddesc}{format}{object, context, maxlevels, level}
Modified: python/python/Doc/branches/2.4.3/lib/libprofile.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libprofile.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libprofile.tex Fri Jun 2 12:52:55 2006
@@ -134,6 +134,21 @@
\end{verbatim}
Il file \file{profile.py} può anche venire utilizzato come script per
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 126
+%[- MARK -]
+%[- MARK -] The file \file{profile.py} can also be invoked as
+%[- MARK -] a script to profile another script. For example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -python /usr/local/lib/python1.5/profile.py myscript.py
+%[- MARK -] +python -m profile myscript.py
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] \file{profile.py} accepts two optional arguments on the command line:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
analizzare un altro script. Per esempio:
\begin{verbatim}
@@ -554,6 +569,30 @@
\end{methoddesc}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 534
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \section{Limitations \label{profile-limits}}
+%[- MARK -]
+%[- MARK -] -There are two fundamental limitations on this profiler. The first is
+%[- MARK -] -that it relies on the Python interpreter to dispatch \dfn{call},
+%[- MARK -] -\dfn{return}, and \dfn{exception} events. Compiled \C{} code does not
+%[- MARK -] -get interpreted, and hence is ``invisible'' to the profiler. All time
+%[- MARK -] -spent in \C{} code (including built-in functions) will be charged to the
+%[- MARK -] -Python function that invoked the \C{} code. If the \C{} code calls out
+%[- MARK -] -to some native Python code, then those calls will be profiled
+%[- MARK -] -properly.
+%[- MARK -] -
+%[- MARK -] -The second limitation has to do with accuracy of timing information.
+%[- MARK -] +One limitation has to do with accuracy of timing information.
+%[- MARK -] There is a fundamental problem with deterministic profilers involving
+%[- MARK -] accuracy. The most obvious restriction is that the underlying ``clock''
+%[- MARK -] is only ticking at a rate (typically) of about .001 seconds. Hence no
+%[- MARK -] measurements will be more accurate than the underlying clock. If
+%[- MARK -] enough measurements are taken, then the ``error'' will tend to average
+%[- MARK -] END DIFF
\section{Limitazioni \label{profile-limits}}
Questo profiler ha fondamentalmente due limitazioni. La prima è che
Modified: python/python/Doc/branches/2.4.3/lib/libpwd.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpwd.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpwd.tex Fri Jun 2 12:52:55 2006
@@ -27,6 +27,25 @@
Gli elementi uid e gid sono valori interi, gli altri sono stringhe.
Nel caso una voce richiesta non possa essere trovata viene sollevata
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 27
+%[- MARK -]
+%[- MARK -] \note{In traditional \UNIX{} the field \code{pw_passwd} usually
+%[- MARK -] contains a password encrypted with a DES derived algorithm (see module
+%[- MARK -] \refmodule{crypt}\refbimodindex{crypt}). However most modern unices
+%[- MARK -] use a so-called \emph{shadow password} system. On those unices the
+%[- MARK -] -field \code{pw_passwd} only contains a asterisk (\code{'*'}) or the
+%[- MARK -] +\var{pw_passwd} field only contains an asterisk (\code{'*'}) or the
+%[- MARK -] letter \character{x} where the encrypted password is stored in a file
+%[- MARK -] -\file{/etc/shadow} which is not world readable.}
+%[- MARK -] +\file{/etc/shadow} which is not world readable. Whether the \var{pw_passwd}
+%[- MARK -] +field contains anything useful is system-dependent.}
+%[- MARK -]
+%[- MARK -] It defines the following items:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getpwuid}{uid}
+%[- MARK -] Return the password database entry for the given numeric user ID.
+%[- MARK -] END DIFF
l'eccezione \exception{KeyError}.
\note{Tradizionalmente in \UNIX{} il campo \code{pw_passwd} contiene
Modified: python/python/Doc/branches/2.4.3/lib/libpyexpat.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libpyexpat.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libpyexpat.tex Fri Jun 2 12:52:55 2006
@@ -160,6 +160,40 @@
figlio viene creato con \member{ordered_attributes},
\member{returns_unicode} e \member{specified_attributes} impostati al
valore di questo parser.
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 154
+%[- MARK -] The child parser is created with the \member{ordered_attributes},
+%[- MARK -] \member{returns_unicode} and \member{specified_attributes} set to the
+%[- MARK -] values of this parser.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[xmlparser]{UseForeignDTD}{\optional{flag}}
+%[- MARK -] +Calling this with a true value for \var{flag} (the default) will cause
+%[- MARK -] +Expat to call the \member{ExternalEntityRefHandler} with
+%[- MARK -] +\constant{None} for all arguments to allow an alternate DTD to be
+%[- MARK -] +loaded. If the document does not contain a document type declaration,
+%[- MARK -] +the \member{ExternalEntityRefHandler} will still be called, but the
+%[- MARK -] +\member{StartDoctypeDeclHandler} and \member{EndDoctypeDeclHandler}
+%[- MARK -] +will not be called.
+%[- MARK -] +
+%[- MARK -] +Passing a false value for \var{flag} will cancel a previous call that
+%[- MARK -] +passed a true value, but otherwise has no effect.
+%[- MARK -] +
+%[- MARK -] +This method can only be called before the \method{Parse()} or
+%[- MARK -] +\method{ParseFile()} methods are called; calling it after either of
+%[- MARK -] +those have been called causes \exception{ExpatError} to be raised with
+%[- MARK -] +the \member{code} attribute set to
+%[- MARK -] +\constant{errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.3}
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \class{xmlparser} objects have the following attributes:
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[xmlparser]{buffer_size}
+%[- MARK -] The size of the buffer used when \member{buffer_text} is true. This
+%[- MARK -] END DIFF
\end{methoddesc}
@@ -246,6 +280,39 @@
\begin{memberdesc}[xmlparser]{ErrorLineNumber}
Il numero della riga dove viene riscontrato l'errore.
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 234
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[xmlparser]{ErrorLineNumber}
+%[- MARK -] Line number at which an error occurred.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] +The following attributes contain values relating to the current parse
+%[- MARK -] +location in an \class{xmlparser} object. During a callback reporting
+%[- MARK -] +a parse event they indicate the location of the first of the sequence
+%[- MARK -] +of characters that generated the event. When called outside of a
+%[- MARK -] +callback, the position indicated will be just past the last parse
+%[- MARK -] +event (regardless of whether there was an associated callback).
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}[xmlparser]{CurrentByteIndex}
+%[- MARK -] +Current byte index in the parser input.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}[xmlparser]{CurrentColumnNumber}
+%[- MARK -] +Current column number in the parser input.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}[xmlparser]{CurrentLineNumber}
+%[- MARK -] +Current line number in the parser input.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] Here is the list of handlers that can be set. To set a handler on an
+%[- MARK -] \class{xmlparser} object \var{o}, use
+%[- MARK -] \code{\var{o}.\var{handlername} = \var{func}}. \var{handlername} must
+%[- MARK -] be taken from the following list, and \var{func} must be a callable
+%[- MARK -] object accepting the correct number of arguments. The arguments are
+%[- MARK -] END DIFF
\end{memberdesc}
Qui c'è una lista dei gestori che possono essere impostati. Per
@@ -281,6 +348,21 @@
internamente un altro documento ed è presente un dichiarazione del
suddetto sotto insieme. Questo richiede la versione di Expat 1.2 o più
recente.
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 267
+%[- MARK -] contains and internal document declaration subset.
+%[- MARK -] This requires Expat version 1.2 or newer.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[xmlparser]{EndDoctypeDeclHandler}{}
+%[- MARK -] -Called when Expat is done parsing the document type delaration.
+%[- MARK -] +Called when Expat is done parsing the document type declaration.
+%[- MARK -] This requires Expat version 1.2 or newer.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[xmlparser]{ElementDeclHandler}{name, model}
+%[- MARK -] Called once for each element type declaration. \var{name} is the name
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[xmlparser]{EndDoctypeDeclHandler}{}
@@ -342,6 +424,21 @@
presente solo nella versione 1.2 della libreria Expat; per versioni
più recenti, usare invece \member{EntityDeclHandler}. La funzione
sottostante nella libreria di Expat è stata dichiarata obsoleta.
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 336
+%[- MARK -] Called for all entity declarations. For parameter and internal
+%[- MARK -] entities, \var{value} will be a string giving the declared contents
+%[- MARK -] of the entity; this will be \code{None} for external entities. The
+%[- MARK -] \var{notationName} parameter will be \code{None} for parsed entities,
+%[- MARK -] and the name of the notation for unparsed entities.
+%[- MARK -] -\var{is_parameter_entity} will be true if the entity is a paremeter
+%[- MARK -] +\var{is_parameter_entity} will be true if the entity is a parameter
+%[- MARK -] entity or false for general entities (most applications only need to
+%[- MARK -] be concerned with general entities).
+%[- MARK -] This is only available starting with version 1.95.0 of the Expat
+%[- MARK -] library.
+%[- MARK -] \versionadded{2.1}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[xmlparser]{EntityDeclHandler}{entityName,
@@ -392,6 +489,21 @@
Chiamato per i commenti. \var{data} è il testo del commento, escluso
i caratteri di inizio `\code{<!-}\code{-}' e fine
`\code{-}\code{->}'`'.
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 374
+%[- MARK -] the leading `\code{<!-}\code{-}' and trailing `\code{-}\code{->}'.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{}
+%[- MARK -] Called at the start of a CDATA section. This and
+%[- MARK -] -\member{StartCdataSectionHandler} are needed to be able to identify
+%[- MARK -] +\member{EndCdataSectionHandler} are needed to be able to identify
+%[- MARK -] the syntactical start and end for CDATA sections.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[xmlparser]{EndCdataSectionHandler}{}
+%[- MARK -] Called at the end of a CDATA section.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{}
@@ -651,6 +763,21 @@
\begin{datadescni}{XML_ERROR_PARAM_ENTITY_REF}
Un riferimento ad un parametro di entità che è stato trovato dove non
era consentito.
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 622
+%[- MARK -] \begin{datadescni}{XML_ERROR_PARAM_ENTITY_REF}
+%[- MARK -] A parameter entity reference was found where it was not allowed.
+%[- MARK -] \end{datadescni}
+%[- MARK -]
+%[- MARK -] \begin{datadescni}{XML_ERROR_PARTIAL_CHAR}
+%[- MARK -] -
+%[- MARK -] +An incomplete character was found in the input.
+%[- MARK -] \end{datadescni}
+%[- MARK -]
+%[- MARK -] \begin{datadescni}{XML_ERROR_RECURSIVE_ENTITY_REF}
+%[- MARK -] An entity reference contained another reference to the same entity;
+%[- MARK -] possibly via a different name, and possibly indirectly.
+%[- MARK -] END DIFF
\end{datadescni}
\begin{datadescni}{XML_ERROR_PARTIAL_CHAR}
@@ -680,6 +807,95 @@
\begin{datadescni}{XML_ERROR_UNDEFINED_ENTITY}
\`E stato creato un riferimento ad un'entità che non era stata
definita.
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 650
+%[- MARK -] \end{datadescni}
+%[- MARK -]
+%[- MARK -] \begin{datadescni}{XML_ERROR_UNKNOWN_ENCODING}
+%[- MARK -] The document encoding is not supported by Expat.
+%[- MARK -] \end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_UNCLOSED_CDATA_SECTION}
+%[- MARK -] +A CDATA marked section was not closed.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_EXTERNAL_ENTITY_HANDLING}
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_NOT_STANDALONE}
+%[- MARK -] +The parser determined that the document was not ``standalone'' though
+%[- MARK -] +it declared itself to be in the XML declaration, and the
+%[- MARK -] +\member{NotStandaloneHandler} was set and returned \code{0}.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_UNEXPECTED_STATE}
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_ENTITY_DECLARED_IN_PE}
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_FEATURE_REQUIRES_XML_DTD}
+%[- MARK -] +An operation was requested that requires DTD support to be compiled
+%[- MARK -] +in, but Expat was configured without DTD support. This should never
+%[- MARK -] +be reported by a standard build of the \module{xml.parsers.expat}
+%[- MARK -] +module.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}
+%[- MARK -] +A behavioral change was requested after parsing started that can only
+%[- MARK -] +be changed before parsing has started. This is (currently) only
+%[- MARK -] +raised by \method{UseForeignDTD()}.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_UNBOUND_PREFIX}
+%[- MARK -] +An undeclared prefix was found when namespace processing was enabled.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_UNDECLARING_PREFIX}
+%[- MARK -] +The document attempted to remove the namespace declaration associated
+%[- MARK -] +with a prefix.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_INCOMPLETE_PE}
+%[- MARK -] +A parameter entity contained incomplete markup.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_XML_DECL}
+%[- MARK -] +The document contained no document element at all.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_TEXT_DECL}
+%[- MARK -] +There was an error parsing a text declaration in an external entity.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_PUBLICID}
+%[- MARK -] +Characters were found in the public id that are not allowed.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_SUSPENDED}
+%[- MARK -] +The requested operation was made on a suspended parser, but isn't
+%[- MARK -] +allowed. This includes attempts to provide additional input or to
+%[- MARK -] +stop the parser.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_NOT_SUSPENDED}
+%[- MARK -] +An attempt to resume the parser was made when the parser had not been
+%[- MARK -] +suspended.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_ABORTED}
+%[- MARK -] +This should not be reported to Python applications.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_FINISHED}
+%[- MARK -] +The requested operation was made on a parser which was finished
+%[- MARK -] +parsing input, but isn't allowed. This includes attempts to provide
+%[- MARK -] +additional input or to stop the parser.
+%[- MARK -] +\end{datadescni}
+%[- MARK -] +
+%[- MARK -] +\begin{datadescni}{XML_ERROR_SUSPEND_PE}
+%[- MARK -] +\end{datadescni}
+%[- MARK -] END DIFF
\end{datadescni}
\begin{datadescni}{XML_ERROR_UNKNOWN_ENCODING}
Modified: python/python/Doc/branches/2.4.3/lib/libqueue.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libqueue.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libqueue.tex Fri Jun 2 12:52:55 2006
@@ -21,6 +21,28 @@
bloccato una volta raggiunto questo limite, fino a che gli elementi
della coda siano esauriti. Se \var{maxsize} è minore o uguale a zero,
la dimensione della coda è infinita.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 24
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{Empty}
+%[- MARK -] Exception raised when non-blocking \method{get()} (or
+%[- MARK -] \method{get_nowait()}) is called on a \class{Queue} object which is
+%[- MARK -] -empty or locked.
+%[- MARK -] +empty.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{Full}
+%[- MARK -] Exception raised when non-blocking \method{put()} (or
+%[- MARK -] \method{put_nowait()}) is called on a \class{Queue} object which is
+%[- MARK -] -full or locked.
+%[- MARK -] +full.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] \subsection{Queue Objects}
+%[- MARK -] \label{QueueObjects}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{classdesc}
\begin{excdesc}{Empty}
@@ -47,6 +69,21 @@
\begin{methoddesc}{qsize}{}
Restituisce la dimensione approssimativa della coda. A causa delle
semantiche multithread, questo valore non è attendibile.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 49
+%[- MARK -] semantics, this number is not reliable.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{empty}{}
+%[- MARK -] Return \code{True} if the queue is empty, \code{False} otherwise.
+%[- MARK -] -Becauseof multithreading semantics, this is not reliable.
+%[- MARK -] +Because of multithreading semantics, this is not reliable.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{full}{}
+%[- MARK -] Return \code{True} if the queue is full, \code{False} otherwise.
+%[- MARK -] Because of multithreading semantics, this is not reliable.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{empty}{}
Modified: python/python/Doc/branches/2.4.3/lib/librandom.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/librandom.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/librandom.tex Fri Jun 2 12:52:55 2006
@@ -55,6 +55,25 @@
\versionchanged[Sostituito Wichmann-Hill con MersenneTwister]{2.3}
+%[- MARK -] BEGIN DIFF 001 of 5
+%[- MARK -] @@ 59
+%[- MARK -] \begin{funcdesc}{seed}{\optional{x}}
+%[- MARK -] Initialize the basic random number generator.
+%[- MARK -] Optional argument \var{x} can be any hashable object.
+%[- MARK -] If \var{x} is omitted or \code{None}, current system time is used;
+%[- MARK -] current system time is also used to initialize the generator when the
+%[- MARK -] - module is first imported.
+%[- MARK -] + module is first imported. If randomness sources are provided by the
+%[- MARK -] + operating system, they are used instead of the system time (see the
+%[- MARK -] + \function{os.urandom()}
+%[- MARK -] + function for details on availability). \versionchanged[formerly,
+%[- MARK -] + operating system resources were not used]{2.4}
+%[- MARK -] If \var{x} is not \code{None} or an int or long,
+%[- MARK -] \code{hash(\var{x})} is used instead.
+%[- MARK -] If \var{x} is an int or long, \var{x} is used directly.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
Funzioni di calcolo:
\begin{funcdesc}{seed}{\optional{x}}
@@ -81,6 +100,21 @@
lo stato interno del generatore come era al momento della chiamata
di \function{setstate()}.
\versionadded{2.1}
+%[- MARK -] BEGIN DIFF 002 of 5
+%[- MARK -] @@ 91
+%[- MARK -] instances into the same internal state, and then \method{jumpahead()}
+%[- MARK -] can be used to force the instances' states far apart.
+%[- MARK -] \versionadded{2.1}
+%[- MARK -] \versionchanged[Instead of jumping to a specific state, \var{n} steps
+%[- MARK -] ahead, \method{jumpahead(\var{n})} jumps to another state likely to be
+%[- MARK -] - separated by many steps.]{2.3}
+%[- MARK -] + separated by many steps]{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getrandbits}{k}
+%[- MARK -] Returns a python \class{long} int with \var{k} random bits.
+%[- MARK -] This method is supplied with the MersenneTwister generator and some
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{jumpahead}{n}
@@ -123,6 +157,20 @@
\end{funcdesc}
+%[- MARK -] BEGIN DIFF 003 of 5
+%[- MARK -] @@ 123
+%[- MARK -]
+%[- MARK -] Functions for sequences:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{choice}{seq}
+%[- MARK -] Return a random element from the non-empty sequence \var{seq}.
+%[- MARK -] + If \var{seq} is empty, raises \exception{IndexError}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{shuffle}{x\optional{, random}}
+%[- MARK -] Shuffle the sequence \var{x} in place.
+%[- MARK -] The optional argument \var{random} is a 0-argument function
+%[- MARK -] END DIFF
Funzioni per le sequenze:
\begin{funcdesc}{choice}{seq}
@@ -234,6 +282,21 @@
\begin{funcdesc}{weibullvariate}{alpha, beta}
Distribuzione Weibull. \var{alpha} è il parametro di scala e
\var{beta} il parametro di forma.
+%[- MARK -] BEGIN DIFF 004 of 5
+%[- MARK -] @@ 225
+%[- MARK -] \begin{funcdesc}{weibullvariate}{alpha, beta}
+%[- MARK -] Weibull distribution. \var{alpha} is the scale parameter and
+%[- MARK -] \var{beta} is the shape parameter.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -Alternative Generator
+%[- MARK -] +Alternative Generators
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{WichmannHill}{\optional{seed}}
+%[- MARK -] Class that implements the Wichmann-Hill algorithm as the core generator.
+%[- MARK -] Has all of the same methods as \class{Random} plus the \method{whseed}
+%[- MARK -] method described below. Because this class is implemented in pure
+%[- MARK -] END DIFF
\end{funcdesc}
Generatori alternativi
@@ -255,6 +318,31 @@
garantisce che diversi argomenti interi producano diversi
stati interni e non può generare più di 2**24 stati interni
distinti.
+%[- MARK -] BEGIN DIFF 005 of 5
+%[- MARK -] @@ 244
+%[- MARK -] See \function{seed} for details. \function{whseed} does not guarantee
+%[- MARK -] that distinct integer arguments yield distinct internal states, and can
+%[- MARK -] yield no more than about 2**24 distinct internal states in all.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{classdesc}{SystemRandom}{\optional{seed}}
+%[- MARK -] +Class that uses the \function{os.urandom()} function for generating
+%[- MARK -] +random numbers from sources provided by the operating system.
+%[- MARK -] +Not available on all systems.
+%[- MARK -] +Does not rely on software state and sequences are not reproducible.
+%[- MARK -] +Accordingly, the \method{seed()} and \method{jumpahead()} methods
+%[- MARK -] +have no effect and are ignored. The \method{getstate()} and
+%[- MARK -] +\method{setstate()} methods raise \exception{NotImplementedError} if
+%[- MARK -] +called.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A
+%[- MARK -] 623-dimensionally equidistributed uniform pseudorandom
+%[- MARK -] number generator'',
+%[- MARK -] \citetitle{ACM Transactions on Modeling and Computer Simulation}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{seealso}
Modified: python/python/Doc/branches/2.4.3/lib/libre.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libre.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libre.tex Fri Jun 2 12:52:55 2006
@@ -87,6 +87,23 @@
Alcuni caratteri, come \character{|} o \character{(}, sono speciali.
I caratteri speciali possono indicare sia classi di carattere
ordinarie, sia modificatori dell'interpretazione delle espressioni
+%[- MARK -] BEGIN DIFF 001 of 12
+%[- MARK -] @@ 76
+%[- MARK -] Some characters, like \character{|} or \character{(}, are special.
+%[- MARK -] Special characters either stand for classes of ordinary characters, or
+%[- MARK -] affect how the regular expressions around them are interpreted.
+%[- MARK -]
+%[- MARK -] The special characters are:
+%[- MARK -] -
+%[- MARK -] -\begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in}
+%[- MARK -] +%
+%[- MARK -] +\begin{description}
+%[- MARK -]
+%[- MARK -] \item[\character{.}] (Dot.) In the default mode, this matches any
+%[- MARK -] character except a newline. If the \constant{DOTALL} flag has been
+%[- MARK -] specified, this matches any character including a newline.
+%[- MARK -]
+%[- MARK -] END DIFF
regolari indicate da questi.
I caratteri speciali sono:
@@ -348,6 +365,30 @@
semplice sistema di corrispondenza per gli indirizzi e-mail, che
corrisponderà con \code{'<user a host.com>'} e
\code{'user a host.com'}, ma non con \code{'<user a host.com'}.
+%[- MARK -] BEGIN DIFF 002 of 12
+%[- MARK -] @@ 304
+%[- MARK -] \regexp{(<)?(\e w+@\e w+(?:\e .\e w+)+)(?(1)>)} is a poor email matching
+%[- MARK -] pattern, which will match with \code{'<user a host.com>'} as well as
+%[- MARK -] \code{'user a host.com'}, but not with \code{'<user a host.com'}.
+%[- MARK -] \versionadded{2.4}
+%[- MARK -]
+%[- MARK -] -\end{list}
+%[- MARK -] +\end{description}
+%[- MARK -]
+%[- MARK -] The special sequences consist of \character{\e} and a character from the
+%[- MARK -] list below. If the ordinary character is not on the list, then the
+%[- MARK -] resulting RE will match the second character. For example,
+%[- MARK -] \regexp{\e\$} matches the character \character{\$}.
+%[- MARK -] -
+%[- MARK -] -\begin{list}{}{\leftmargin 0.7in \labelwidth 0.65in}
+%[- MARK -] +%
+%[- MARK -] +\begin{description}
+%[- MARK -]
+%[- MARK -] \item[\code{\e \var{number}}] Matches the contents of the group of the
+%[- MARK -] same number. Groups are numbered starting from 1. For example,
+%[- MARK -] \regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not
+%[- MARK -] \code{'the end'} (note
+%[- MARK -] END DIFF
\versionadded{2.4}
\end{list}
@@ -391,6 +432,54 @@
\item[\code{\e B}] Corrisponde alla stringa vuota, ma solo quando
\emph{non} si trova all'inizio o alla fine di una parola. Questo
è l'opposto di {}\code{\e b}, quindi è anche esseo soggetto alle
+%[- MARK -] BEGIN DIFF 003 of 12
+%[- MARK -] @@ 340
+%[- MARK -]
+%[- MARK -] \item[\code{\e B}] Matches the empty string, but only when it is \emph{not}
+%[- MARK -] at the beginning or end of a word. This is just the opposite of {}\code{\e
+%[- MARK -] b}, so is also subject to the settings of \code{LOCALE} and \code{UNICODE}.
+%[- MARK -]
+%[- MARK -] -\item[\code{\e d}]Matches any decimal digit; this is
+%[- MARK -] -equivalent to the set \regexp{[0-9]}.
+%[- MARK -] +\item[\code{\e d}]When the \constant{UNICODE} flag is not specified, matches
+%[- MARK -] +any decimal digit; this is equivalent to the set \regexp{[0-9]}.
+%[- MARK -] +With \constant{UNICODE}, it will match whatever is classified as a digit
+%[- MARK -] +in the Unicode character properties database.
+%[- MARK -]
+%[- MARK -] -\item[\code{\e D}]Matches any non-digit character; this is
+%[- MARK -] -equivalent to the set \regexp{[{\textasciicircum}0-9]}.
+%[- MARK -] +\item[\code{\e D}]When the \constant{UNICODE} flag is not specified, matches
+%[- MARK -] +any non-digit character; this is equivalent to the set
+%[- MARK -] +\regexp{[{\textasciicircum}0-9]}. With \constant{UNICODE}, it will match
+%[- MARK -] +anything other than character marked as digits in the Unicode character
+%[- MARK -] +properties database.
+%[- MARK -]
+%[- MARK -] -\item[\code{\e s}]Matches any whitespace character; this is
+%[- MARK -] +\item[\code{\e s}]When the \constant{LOCALE} and \constant{UNICODE}
+%[- MARK -] +flags are not specified, matches any whitespace character; this is
+%[- MARK -] equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}.
+%[- MARK -] -
+%[- MARK -] -\item[\code{\e S}]Matches any non-whitespace character; this is
+%[- MARK -] -equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]}.
+%[- MARK -] +With \constant{LOCALE}, it will match this set plus whatever characters
+%[- MARK -] +are defined as space for the current locale. If \constant{UNICODE} is set,
+%[- MARK -] +this will match the characters \regexp{[ \e t\e n\e r\e f\e v]} plus
+%[- MARK -] +whatever is classified as space in the Unicode character properties
+%[- MARK -] +database.
+%[- MARK -] +
+%[- MARK -] +\item[\code{\e S}]When the \constant{LOCALE} and \constant{UNICODE}
+%[- MARK -] +flags are not specified, matches any non-whitespace character; this is
+%[- MARK -] +equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]}
+%[- MARK -] +With \constant{LOCALE}, it will match any character not in this set,
+%[- MARK -] +and not defined as space in the current locale. If \constant{UNICODE}
+%[- MARK -] +is set, this will match anything other than \regexp{[ \e t\e n\e r\e f\e v]}
+%[- MARK -] +and characters marked as space in the Unicode character properties database.
+%[- MARK -]
+%[- MARK -] \item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE}
+%[- MARK -] flags are not specified, matches any alphanumeric character and the
+%[- MARK -] underscore; this is equivalent to the set
+%[- MARK -] \regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set
+%[- MARK -] END DIFF
impostazioni di \code{LOCALE} e \code{UNICODE}.
\item[\code{\e d}] Corrisponde ogni cifra decimale; è equivalente
@@ -428,6 +517,21 @@
i caratteri segnati come alfanumerici nel database delle proprietà
dei caratteri Unicode.
+%[- MARK -] BEGIN DIFF 004 of 12
+%[- MARK -] @@ 372
+%[- MARK -] \regexp{[0-9_]} and characters marked as alphanumeric in the Unicode
+%[- MARK -] character properties database.
+%[- MARK -]
+%[- MARK -] \item[\code{\e Z}]Matches only at the end of the string.
+%[- MARK -]
+%[- MARK -] -\end{list}
+%[- MARK -] +\end{description}
+%[- MARK -]
+%[- MARK -] Most of the standard escapes supported by Python string literals are
+%[- MARK -] also accepted by the regular expression parser:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] END DIFF
\item[\code{\e Z}] Corrisponde solo alla fine della stringa.
\end{list}
@@ -440,6 +544,22 @@
\a \b \f \n
\r \t \v \x
\\
+%[- MARK -] BEGIN DIFF 005 of 12
+%[- MARK -] @@ 385
+%[- MARK -] \\
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] Octal escapes are included in a limited form: If the first digit is a
+%[- MARK -] 0, or if there are three octal digits, it is considered an octal
+%[- MARK -] -escape. Otherwise, it is a group reference.
+%[- MARK -] +escape. Otherwise, it is a group reference. As for string literals,
+%[- MARK -] +octal escapes are always at most three digits in length.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] % Note the lack of a period in the section title; it causes problems
+%[- MARK -] % with readers of the GNU info version. See http://www.python.org/sf/581414.
+%[- MARK -] \subsection{Matching vs Searching \label{matching-searching}}
+%[- MARK -] END DIFF
\end{verbatim}
Gli escape ottali vengono inclusi in una forma limitata: se la prima
@@ -479,6 +599,25 @@
\subsection{Contenuti del modulo}
+%[- MARK -] BEGIN DIFF 006 of 12
+%[- MARK -] @@ 421
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{Module Contents}
+%[- MARK -] \nodename{Contents of Module re}
+%[- MARK -]
+%[- MARK -] -The module defines the following functions and constants, and an exception:
+%[- MARK -] -
+%[- MARK -] +The module defines several functions, constants, and an exception. Some of the
+%[- MARK -] +functions are simplified versions of the full featured methods for compiled
+%[- MARK -] +regular expressions. Most non-trivial applications always use the compiled
+%[- MARK -] +form.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{compile}{pattern\optional{, flags}}
+%[- MARK -] Compile a regular expression pattern into a regular expression
+%[- MARK -] object, which can be used for matching using its \function{match()} and
+%[- MARK -] \function{search()} methods, described below.
+%[- MARK -] END DIFF
\nodename{Contents of Module re}
Il modulo definisce le seguenti funzioni e costanti, e un'eccezione:
@@ -522,6 +661,23 @@
Effettua una corrispondenza case-insensitive; espressioni come
\regexp{[A-Z]} corrisponderanno anche alle lettere minuscole.
Non viene influenzato dalla localizzazione corrente.
+%[- MARK -] BEGIN DIFF 007 of 12
+%[- MARK -] @@ 463
+%[- MARK -] current locale.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{L}
+%[- MARK -] \dataline{LOCALE}
+%[- MARK -] -Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and
+%[- MARK -] -\regexp{\e B} dependent on the current locale.
+%[- MARK -] +Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
+%[- MARK -] +\regexp{\e s} and \regexp{\e S} dependent on the current locale.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{M}
+%[- MARK -] \dataline{MULTILINE}
+%[- MARK -] When specified, the pattern character \character{\textasciicircum}
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{L}
@@ -548,6 +704,24 @@
Fa in modo che il carattere speciale \character{.} corrisponda ad ogni
carattere, incluso il fine riga; senza questa opzione, \character{.}
corrisponderà a qualsiasi cosa, \emph{eccetto} il fine riga.
+%[- MARK -] BEGIN DIFF 008 of 12
+%[- MARK -] @@ 488
+%[- MARK -] anything \emph{except} a newline.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{U}
+%[- MARK -] \dataline{UNICODE}
+%[- MARK -] -Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, and
+%[- MARK -] -\regexp{\e B} dependent on the Unicode character properties database.
+%[- MARK -] +Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
+%[- MARK -] +\regexp{\e d}, \regexp{\e D}, \regexp{\e s} and \regexp{\e S}
+%[- MARK -] +dependent on the Unicode character properties database.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{X}
+%[- MARK -] \dataline{VERBOSE}
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{U}
@@ -614,6 +788,38 @@
Questa funzione combina ed estende le funzionalità delle vecchie
\function{regsub.split()} e \function{regsub.splitx()}.
+%[- MARK -] BEGIN DIFF 009 of 12
+%[- MARK -] @@ 549
+%[- MARK -]
+%[- MARK -] This function combines and extends the functionality of
+%[- MARK -] the old \function{regsub.split()} and \function{regsub.splitx()}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{findall}{pattern, string}
+%[- MARK -] +\begin{funcdesc}{findall}{pattern, string\optional{, flags}}
+%[- MARK -] Return a list of all non-overlapping matches of \var{pattern} in
+%[- MARK -] \var{string}. If one or more groups are present in the pattern,
+%[- MARK -] return a list of groups; this will be a list of tuples if the
+%[- MARK -] pattern has more than one group. Empty matches are included in the
+%[- MARK -] result unless they touch the beginning of another match.
+%[- MARK -] \versionadded{1.5.2}
+%[- MARK -] + \versionchanged[Added the optional flags argument]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{finditer}{pattern, string}
+%[- MARK -] +\begin{funcdesc}{finditer}{pattern, string\optional{, flags}}
+%[- MARK -] Return an iterator over all non-overlapping matches for the RE
+%[- MARK -] \var{pattern} in \var{string}. For each match, the iterator returns
+%[- MARK -] a match object. Empty matches are included in the result unless they
+%[- MARK -] touch the beginning of another match.
+%[- MARK -] \versionadded{2.2}
+%[- MARK -] + \versionchanged[Added the optional flags argument]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{sub}{pattern, repl, string\optional{, count}}
+%[- MARK -] Return the string obtained by replacing the leftmost non-overlapping
+%[- MARK -] occurrences of \var{pattern} in \var{string} by the replacement
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{findall}{pattern, string}
@@ -658,6 +864,23 @@
Se \var{repl} è una funzione, viene chiamata per ogni occorrenza
(senza sovrapposizioni) del \var{pattern}. La funzione prende un
singolo oggetto corrispondente come argomento, e restituisce la
+%[- MARK -] BEGIN DIFF 010 of 12
+%[- MARK -] @@ 591
+%[- MARK -] occurrence of \var{pattern}. The function takes a single match
+%[- MARK -] object argument, and returns the replacement string. For example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> def dashrepl(matchobj):
+%[- MARK -] -.... if matchobj.group(0) == '-': return ' '
+%[- MARK -] -.... else: return '-'
+%[- MARK -] +... if matchobj.group(0) == '-': return ' '
+%[- MARK -] +... else: return '-'
+%[- MARK -] >>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
+%[- MARK -] 'pro--gram files'
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] The pattern may be a string or an RE object; if you need to specify
+%[- MARK -] END DIFF
stringa sostitutiva. Per esempio:
\begin{verbatim}
@@ -772,6 +995,28 @@
\begin{methoddesc}[RegexObject]{split}{string\optional{,
maxsplit\code{ = 0}}}
Identica alla funzione \function{split()}, utilizzando il modello compilato.
+%[- MARK -] BEGIN DIFF 011 of 12
+%[- MARK -] @@ 692
+%[- MARK -] \begin{methoddesc}[RegexObject]{split}{string\optional{,
+%[- MARK -] maxsplit\code{ = 0}}}
+%[- MARK -] Identical to the \function{split()} function, using the compiled pattern.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[RegexObject]{findall}{string}
+%[- MARK -] +\begin{methoddesc}[RegexObject]{findall}{string\optional{, pos\optional{,
+%[- MARK -] + endpos}}}
+%[- MARK -] Identical to the \function{findall()} function, using the compiled pattern.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[RegexObject]{finditer}{string}
+%[- MARK -] +\begin{methoddesc}[RegexObject]{finditer}{string\optional{, pos\optional{,
+%[- MARK -] + endpos}}}
+%[- MARK -] Identical to the \function{finditer()} function, using the compiled pattern.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
+%[- MARK -] Identical to the \function{sub()} function, using the compiled pattern.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[RegexObject]{findall}{string}
@@ -923,6 +1168,24 @@
\function{match()} del \class{RegexObject}. Questi è l'indice nella
stringa oltre il quale l'automa dell'espressione regolare non andrà a
cercare una corrispondenza.
+%[- MARK -] BEGIN DIFF 012 of 12
+%[- MARK -] @@ 836
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[MatchObject]{lastindex}
+%[- MARK -] The integer index of the last matched capturing group, or \code{None}
+%[- MARK -] if no group was matched at all. For example, the expressions
+%[- MARK -] \regexp{(a)b}, \regexp{((a)(b))}, and \regexp{((ab))} will have
+%[- MARK -] -\code{lastindex == 1} if applyied to the string \code{'ab'},
+%[- MARK -] +\code{lastindex == 1} if applied to the string \code{'ab'},
+%[- MARK -] while the expression \regexp{(a)(b)} will have \code{lastindex == 2},
+%[- MARK -] -if applyied to the same string.
+%[- MARK -] +if applied to the same string.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[MatchObject]{lastgroup}
+%[- MARK -] The name of the last matched capturing group, or \code{None} if the
+%[- MARK -] group didn't have a name, or if no group was matched at all.
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{memberdesc}[MatchObject]{lastindex}
Modified: python/python/Doc/branches/2.4.3/lib/libreadline.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libreadline.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libreadline.tex Fri Jun 2 12:52:55 2006
@@ -73,6 +73,29 @@
Restituisce il contenuto corrente degli elementi dello storico in
\var{index}.
\versionadded{2.3}
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 69
+%[- MARK -] \begin{funcdesc}{get_history_item}{index}
+%[- MARK -] Return the current contents of history item at \var{index}.
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{remove_history_item}{pos}
+%[- MARK -] +Remove history item specified by its position from the history.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{replace_history_item}{pos, line}
+%[- MARK -] +Replace history item specified by its position with the given line.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{redisplay}{}
+%[- MARK -] Change what's displayed on the screen to reflect the current contents
+%[- MARK -] of the line buffer. \versionadded{2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{redisplay}{}
@@ -139,6 +162,20 @@
\begin{funcdesc}{add_history}{line}
Aggiunge una riga allo storico nel buffer, come se fosse l'ultima
riga digitata.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 125
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{add_history}{line}
+%[- MARK -] Append a line to the history buffer, as if it was the last line typed.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seemodule{rlcompleter}{Completion of Python identifiers at the
+%[- MARK -] interactive prompt.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
@@ -155,6 +192,42 @@
salvare automaticamente i file dello storico chiamati \file{.pyhist}
dalla home directory dell'utente. Il codice sottostante verrebbe
normalmente eseguito automaticamente durante le sessioni interattive
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 152
+%[- MARK -] pass
+%[- MARK -] import atexit
+%[- MARK -] atexit.register(readline.write_history_file, histfile)
+%[- MARK -] del os, histfile
+%[- MARK -] \end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The following example extends the \class{code.InteractiveConsole} class to
+%[- MARK -] +support history save/restore.
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import code
+%[- MARK -] +import readline
+%[- MARK -] +import atexit
+%[- MARK -] +import os
+%[- MARK -] +
+%[- MARK -] +class HistoryConsole(code.InteractiveConsole):
+%[- MARK -] + def __init__(self, locals=None, filename="<console>",
+%[- MARK -] + histfile=os.path.expanduser("~/.console-history")):
+%[- MARK -] + code.InteractiveConsole.__init__(self)
+%[- MARK -] + self.init_history(histfile)
+%[- MARK -] +
+%[- MARK -] + def init_history(self, histfile):
+%[- MARK -] + readline.parse_and_bind("tab: complete")
+%[- MARK -] + if hasattr(readline, "read_history_file"):
+%[- MARK -] + try:
+%[- MARK -] + readline.read_history_file(histfile)
+%[- MARK -] + except IOError:
+%[- MARK -] + pass
+%[- MARK -] + atexit.register(self.save_history, histfile)
+%[- MARK -] +
+%[- MARK -] + def save_history(self, histfile):
+%[- MARK -] + readline.write_history_file(histfile)
+%[- MARK -] +\end{verbatim}
+%[- MARK -] END DIFF
dal file \envvar{PYTHONSTARTUP} dell'utente.
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/librepr.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/librepr.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/librepr.tex Fri Jun 2 12:52:55 2006
@@ -51,6 +51,30 @@
\begin{memberdesc}{maxlevel}
Profondità limite nella creazione di rappresentazioni ricorsive.
Il valore predefinito è \code{6}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 50
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{maxdict}
+%[- MARK -] \memberline{maxlist}
+%[- MARK -] \memberline{maxtuple}
+%[- MARK -] +\memberline{maxset}
+%[- MARK -] +\memberline{maxfrozenset}
+%[- MARK -] +\memberline{maxdeque}
+%[- MARK -] +\memberline{maxarray}
+%[- MARK -] Limits on the number of entries represented for the named object
+%[- MARK -] - type. The default for \member{maxdict} is \code{4}, for the others,
+%[- MARK -] - \code{6}.
+%[- MARK -] + type. The default is \code{4} for \member{maxdict}, \code{5} for
+%[- MARK -] + \member{maxarray}, and \code{6} for the others.
+%[- MARK -] + \versionadded[\member{maxset}, \member{maxfrozenset},
+%[- MARK -] + and \member{set}]{2.4}.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{maxlong}
+%[- MARK -] Maximum number of characters in the representation for a long
+%[- MARK -] integer. Digits are dropped from the middle. The default is
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{memberdesc}{maxdict}
Modified: python/python/Doc/branches/2.4.3/lib/libresource.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libresource.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libresource.tex Fri Jun 2 12:52:55 2006
@@ -41,6 +41,21 @@
\manpage{getrlimit}{2}. Le risorse mostrate sotto vengono supportate
quando il sistema operativo sottostante a sua volta le supporta; le risorse che
non possono venire controllate o gestite dal sistema operativo non
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 42
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{getrlimit}{resource}
+%[- MARK -] Returns a tuple \code{(\var{soft}, \var{hard})} with the current
+%[- MARK -] soft and hard limits of \var{resource}. Raises \exception{ValueError} if
+%[- MARK -] an invalid resource is specified, or \exception{error} if the
+%[- MARK -] - underyling system call fails unexpectedly.
+%[- MARK -] + underlying system call fails unexpectedly.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{setrlimit}{resource, limits}
+%[- MARK -] Sets new limits of consumption of \var{resource}. The \var{limits}
+%[- MARK -] argument must be a tuple \code{(\var{soft}, \var{hard})} of two
+%[- MARK -] END DIFF
vengono definite in questo modulo su quelle piattaforme.
\begin{funcdesc}{getrlimit}{resource}
@@ -56,6 +71,21 @@
L'argomento \var{limits} deve essere una tupla
\code{(\var{soft}, \var{hard})} di due numeri interi che descrivono i
nuovi limiti. Si può utilizzare un valore di \code{-1} per
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 54
+%[- MARK -] specify the maximum possible upper limit.
+%[- MARK -]
+%[- MARK -] Raises \exception{ValueError} if an invalid resource is specified,
+%[- MARK -] if the new soft limit exceeds the hard limit, or if a process tries
+%[- MARK -] to raise its hard limit (unless the process has an effective UID of
+%[- MARK -] - super-user). Can also raise \exception{error} if the underyling
+%[- MARK -] + super-user). Can also raise \exception{error} if the underlying
+%[- MARK -] system call fails.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] These symbols define resources whose consumption can be controlled
+%[- MARK -] using the \function{setrlimit()} and \function{getrlimit()} functions
+%[- MARK -] END DIFF
specificare il limite superiore massimo possibile.
Solleva l'eccezione \exception{ValueError} se viene specificata una
Modified: python/python/Doc/branches/2.4.3/lib/librexec.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/librexec.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/librexec.tex Fri Jun 2 12:52:55 2006
@@ -201,6 +201,21 @@
valore della classe base e concatenare funzioni proibite addizionali --
quando nuove funzioni built-in pericolose verranno aggiunte a Python,
verranno aggiunte anche a questo modulo).
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 198
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{ok_builtin_modules}
+%[- MARK -] Contains the names of built-in modules which can be safely imported.
+%[- MARK -] The value for \class{RExec} is \code{('audioop', 'array', 'binascii',
+%[- MARK -] 'cmath', 'errno', 'imageop', 'marshal', 'math', 'md5', 'operator',
+%[- MARK -] -'parser', 'regex', 'rotor', 'select', 'sha', '_sre', 'strop',
+%[- MARK -] +'parser', 'regex', 'select', 'sha', '_sre', 'strop',
+%[- MARK -] 'struct', 'time')}. A similar remark about overriding this variable
+%[- MARK -] applies --- use the value from the base class as a starting point.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{ok_path}
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{memberdesc}{ok_builtin_modules}
Modified: python/python/Doc/branches/2.4.3/lib/librfc822.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/librfc822.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/librfc822.tex Fri Jun 2 12:52:55 2006
@@ -144,6 +144,21 @@
fuso orario; questo potrebbe portare ad un minimo errore sulle date di
passaggio all'ora legale, comunque non tale da preoccupare per i
comuni utilizzi.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 127
+%[- MARK -] switch dates. Not enough to worry about for common use.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] - \seemodule{email}{Comprehensive email handling package; supercedes
+%[- MARK -] + \seemodule{email}{Comprehensive email handling package; supersedes
+%[- MARK -] the \module{rfc822} module.}
+%[- MARK -] \seemodule{mailbox}{Classes to read various mailbox formats produced
+%[- MARK -] by end-user mail programs.}
+%[- MARK -] \seemodule{mimetools}{Subclass of \class{rfc822.Message} that
+%[- MARK -] handles MIME encoded messages.}
+%[- MARK -] END DIFF
\end{funcdesc}
Modified: python/python/Doc/branches/2.4.3/lib/libselect.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libselect.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libselect.tex Fri Jun 2 12:52:55 2006
@@ -49,6 +49,21 @@
Il valore restituito è una terna di liste di oggetti pronti:
reimpostazioni dei primi tre argomenti. Quando viene raggiunto il
timeout senza che un descrittore di file sia pronto, vengono restituite
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 59
+%[- MARK -] an appropriate \method{fileno()} method (that really returns a file
+%[- MARK -] descriptor, not just a random integer).
+%[- MARK -] \note{File objects on Windows are not acceptable, but sockets
+%[- MARK -] are.\index{WinSock} On Windows, the underlying \cfunction{select()}
+%[- MARK -] function is provided by the WinSock library, and does not handle file
+%[- MARK -] -desciptors that don't originate from WinSock.}
+%[- MARK -] +descriptors that don't originate from WinSock.}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \subsection{Polling Objects
+%[- MARK -] \label{poll-objects}}
+%[- MARK -]
+%[- MARK -] END DIFF
tre liste vuote.
Tra i tipi di oggetti accettati nelle sequenze ci sono gli oggetti
Modified: python/python/Doc/branches/2.4.3/lib/libsets.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsets.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsets.tex Fri Jun 2 12:52:55 2006
@@ -31,6 +31,24 @@
\method{__hash__()}, ma non possiede i metodi che alterano il contenuto
dell'insieme. Sia \class{Set} che \class{ImmutableSet} derivano da
\class{BaseSet}, una classe astratta utile per definire che cosa sia un
+%[- MARK -] BEGIN DIFF 001 of 5
+%[- MARK -] @@ 28
+%[- MARK -] method but omits methods which alter the contents of the set. Both
+%[- MARK -] \class{Set} and \class{ImmutableSet} derive from \class{BaseSet}, an
+%[- MARK -] abstract class useful for determining whether something is a set:
+%[- MARK -] \code{isinstance(\var{obj}, BaseSet)}.
+%[- MARK -]
+%[- MARK -] -The set classes are implemented using dictionaries. As a result, sets
+%[- MARK -] +The set classes are implemented using dictionaries. Accordingly, the
+%[- MARK -] +requirements for set elements are the same as those for dictionary keys;
+%[- MARK -] +namely, that the element defines both \method{__eq__} and \method{__hash__}.
+%[- MARK -] +As a result, sets
+%[- MARK -] cannot contain mutable elements such as lists or dictionaries.
+%[- MARK -] However, they can contain immutable collections such as tuples or
+%[- MARK -] instances of \class{ImmutableSet}. For convenience in implementing
+%[- MARK -] sets of sets, inner sets are automatically converted to immutable
+%[- MARK -] form, for example, \code{Set([Set(['dog'])])} is transformed to
+%[- MARK -] END DIFF
insieme: \code{isinstance(\var{obj}, BaseSet)}.
Le classi set vengono implementate usando i dizionari. Di conseguenza,
@@ -83,6 +101,21 @@
\lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
{controlla se ogni elemento di \var{s} appartiene a \var{t}}
\lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
+%[- MARK -] BEGIN DIFF 002 of 5
+%[- MARK -] @@ 77
+%[- MARK -] {test whether every element in \var{s} is in \var{t}}
+%[- MARK -] \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
+%[- MARK -] {test whether every element in \var{t} is in \var{s}}
+%[- MARK -]
+%[- MARK -] \hline
+%[- MARK -] - \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}}
+%[- MARK -] + \lineiii{\var{s}.union(\var{t})}{\var{s} \textbar{} \var{t}}
+%[- MARK -] {new set with elements from both \var{s} and \var{t}}
+%[- MARK -] \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
+%[- MARK -] {new set with elements common to \var{s} and \var{t}}
+%[- MARK -] \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
+%[- MARK -] {new set with elements in \var{s} but not in \var{t}}
+%[- MARK -] END DIFF
{controlla se ogni elemento di \var{t} appartiene a \var{s}}
\hline
@@ -139,6 +172,23 @@
\lineii{hash(\var{s})}{restituisce un valore hash per \var{s}}
\end{tableii}
+%[- MARK -] BEGIN DIFF 003 of 5
+%[- MARK -] @@ 128
+%[- MARK -]
+%[- MARK -] The following table lists operations available in \class{Set}
+%[- MARK -] but not found in \class{ImmutableSet}:
+%[- MARK -]
+%[- MARK -] \begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
+%[- MARK -] - \lineiii{\var{s}.union_update(\var{t})}
+%[- MARK -] - {\var{s} |= \var{t}}
+%[- MARK -] + \lineiii{\var{s}.update(\var{t})}
+%[- MARK -] + {\var{s} \textbar= \var{t}}
+%[- MARK -] {return set \var{s} with elements added from \var{t}}
+%[- MARK -] \lineiii{\var{s}.intersection_update(\var{t})}
+%[- MARK -] {\var{s} \&= \var{t}}
+%[- MARK -] {return set \var{s} keeping only elements also found in \var{t}}
+%[- MARK -] \lineiii{\var{s}.difference_update(\var{t})}
+%[- MARK -] END DIFF
La seguente tabella elenca le operazioni disponibili in \class{Set} ma che non si trovano in \class{ImmutableSet}:
\begin{tableiii}{c|c|l}{code}{Operazione}{Equivalente}{Risultato}
@@ -169,6 +219,31 @@
\var{s}; solleva l'eccezione KeyError se vuoto}
\lineiii{\var{s}.clear()}{}
{rimuove tutti gli elementi dall'insieme \var{s}}
+%[- MARK -] BEGIN DIFF 004 of 5
+%[- MARK -] @@ 156
+%[- MARK -] KeyError if empty}
+%[- MARK -] \lineiii{\var{s}.clear()}{}
+%[- MARK -] {remove all elements from set \var{s}}
+%[- MARK -] \end{tableiii}
+%[- MARK -]
+%[- MARK -] -Note, the non-operator versions of \method{union_update()},
+%[- MARK -] +Note, the non-operator versions of \method{update()},
+%[- MARK -] \method{intersection_update()}, \method{difference_update()}, and
+%[- MARK -] \method{symmetric_difference_update()} will accept any iterable as
+%[- MARK -] an argument.
+%[- MARK -] \versionchanged[Formerly all arguments were required to be sets]{2.3.1}
+%[- MARK -]
+%[- MARK -] +Also note, the module also includes a \method{union_update()} method
+%[- MARK -] +which is an alias for \method{update()}. The method is included for
+%[- MARK -] +backwards compatibility. Programmers should prefer the
+%[- MARK -] +\method{update()} method because it is supported by the builtin
+%[- MARK -] +\class{set()} and \class{frozenset()} types.
+%[- MARK -]
+%[- MARK -] \subsection{Example \label{set-example}}
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> from sets import Set
+%[- MARK -] END DIFF
\end{tableiii}
Notate, le versioni non operatore di \method{union_update()},
@@ -239,6 +314,39 @@
Gli oggetti \class{Set} implementano il metodo
\method{__as_temporarily_immutable__()} il quale restituisce l'oggetto
\class{Set} incapsulato in una nuova classe
+%[- MARK -] BEGIN DIFF 005 of 5
+%[- MARK -] @@ 226
+%[- MARK -] The two mechanisms for adding hashability are normally invisible to the
+%[- MARK -] user; however, a conflict can arise in a multi-threaded environment
+%[- MARK -] where one thread is updating a set while another has temporarily wrapped it
+%[- MARK -] in \class{_TemporarilyImmutableSet}. In other words, sets of mutable sets
+%[- MARK -] are not thread-safe.
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +\subsection{Comparison to the built-in \class{set} types
+%[- MARK -] + \label{comparison-to-builtin-set}}
+%[- MARK -] +
+%[- MARK -] +The built-in \class{set} and \class{frozenset} types were designed based
+%[- MARK -] +on lessons learned from the \module{sets} module. The key differences are:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \class{Set} and \class{ImmutableSet} were renamed to \class{set} and
+%[- MARK -] + \class{frozenset}.
+%[- MARK -] +\item There is no equivalent to \class{BaseSet}. Instead, use
+%[- MARK -] + \code{isinstance(x, (set, frozenset))}.
+%[- MARK -] +\item The hash algorithm for the built-ins performs significantly better
+%[- MARK -] + (fewer collisions) for most datasets.
+%[- MARK -] +\item The built-in versions have more space efficient pickles.
+%[- MARK -] +\item The built-in versions do not have a \method{union_update()} method.
+%[- MARK -] + Instead, use the \method{update()} method which is equivalent.
+%[- MARK -] +\item The built-in versions do not have a \method{_repr(sorted=True)} method.
+%[- MARK -] + Instead, use the built-in \function{repr()} and \function{sorted()}
+%[- MARK -] + functions: \code{repr(sorted(s))}.
+%[- MARK -] +\item The built-in version does not have a protocol for automatic conversion
+%[- MARK -] + to immutable. Many found this feature to be confusing and no one
+%[- MARK -] + in the community reported having found real uses for it.
+%[- MARK -] +\end{itemize}
+%[- MARK -] END DIFF
\class{_TemporarilyImmutableSet}.
I due meccanismi per aggiungere la possibilità di calcolare il
Modified: python/python/Doc/branches/2.4.3/lib/libsgmllib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsgmllib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsgmllib.tex Fri Jun 2 12:52:55 2006
@@ -13,6 +13,20 @@
modulo esiste solamente come base per il modulo
\refmodule{htmllib}. Un altro parser HTML che supporta XHTML ed offre
un'interfaccia leggermente differente è disponibile nel modulo
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 12
+%[- MARK -] --- it only parses SGML insofar as it is used by HTML, and the module
+%[- MARK -] only exists as a base for the \refmodule{htmllib} module. Another
+%[- MARK -] HTML parser which supports XHTML and offers a somewhat different
+%[- MARK -] interface is available in the \refmodule{HTMLParser} module.
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] \begin{classdesc}{SGMLParser}{}
+%[- MARK -] The \class{SGMLParser} class is instantiated without arguments.
+%[- MARK -] The parser is hardcoded to recognize the following
+%[- MARK -] constructs:
+%[- MARK -]
+%[- MARK -] END DIFF
\refmodule{HTMLParser}.
@@ -38,6 +52,30 @@
se inseriti tra \samp{>} ed immediatamente preceduti da \samp{--}.
\end{itemize}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 38
+%[- MARK -] \samp{>} and the immediately preceding \samp{--}.
+%[- MARK -]
+%[- MARK -] \end{itemize}
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] -\class{SGMLParser} instances have the following interface methods:
+%[- MARK -] +A single exception is defined as well:
+%[- MARK -] +
+%[- MARK -] +\begin{excdesc}{SGMLParseError}
+%[- MARK -] +Exception raised by the \class{SGMLParser} class when it encounters an
+%[- MARK -] +error while parsing.
+%[- MARK -] +\versionadded{2.1}
+%[- MARK -] +\end{excdesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +\class{SGMLParser} instances have the following methods:
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{reset}{}
+%[- MARK -] Reset the instance. Loses all unprocessed data. This is called
+%[- MARK -] implicitly at instantiation time.
+%[- MARK -] END DIFF
\end{classdesc}
Le istanze di \class{SGMLParser} hanno la seguente interfaccia a
Modified: python/python/Doc/branches/2.4.3/lib/libsha.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsha.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsha.tex Fri Jun 2 12:52:55 2006
@@ -62,6 +62,33 @@
Restituisce una copia (``clone'') dell'oggetto sha. Può essere usato
per calcolare efficientemente i digest di quelle stringhe che
condividono una medesima sottostringa iniziale.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 65
+%[- MARK -] efficiently compute the digests of strings that share a common initial
+%[- MARK -] substring.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] - \seetitle[http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt]
+%[- MARK -] + \seetitle[http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf]
+%[- MARK -] {Secure Hash Standard}
+%[- MARK -] {The Secure Hash Algorithm is defined by NIST document FIPS
+%[- MARK -] - PUB 180-1:
+%[- MARK -] - \citetitle[http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt]
+%[- MARK -] - {Secure Hash Standard}, published in April of 1995. It is
+%[- MARK -] - available online as plain text (at least one diagram was
+%[- MARK -] - omitted) and as PDF at
+%[- MARK -] - \url{http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.pdf}.}
+%[- MARK -] + PUB 180-2:
+%[- MARK -] + \citetitle[http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf]
+%[- MARK -] + {Secure Hash Standard}, published in August 2002.}
+%[- MARK -]
+%[- MARK -] \seetitle[http://csrc.nist.gov/encryption/tkhash.html]
+%[- MARK -] {Cryptographic Toolkit (Secure Hashing)}
+%[- MARK -] {Links from NIST to various information on secure hashing.}
+%[- MARK -] \end{seealso}
+%[- MARK -] +
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{seealso}
Modified: python/python/Doc/branches/2.4.3/lib/libshelve.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libshelve.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libshelve.tex Fri Jun 2 12:52:55 2006
@@ -12,6 +12,21 @@
Questo include la maggior parte delle istanze di classe, tipi di dati
ricorsivi ed oggetti contenenti molti condivisi oggetti derivati.
Le chiavi sono stringhe ordinarie.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 16
+%[- MARK -] \begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}\optional{,binary=\code{None}}}}}}
+%[- MARK -] Open a persistent dictionary. The filename specified is the base filename
+%[- MARK -] for the underlying database. As a side-effect, an extension may be added to
+%[- MARK -] the filename and more than one file may be created. By default, the
+%[- MARK -] underlying database file is opened for reading and writing. The optional
+%[- MARK -] -{}\var{flag} pararameter has the same interpretation as the \var{flag}
+%[- MARK -] +{}\var{flag} parameter has the same interpretation as the \var{flag}
+%[- MARK -] parameter of \function{anydbm.open}.
+%[- MARK -]
+%[- MARK -] By default, version 0 pickles are used to serialize values.
+%[- MARK -] The version of the pickle protocol can be specified with the
+%[- MARK -] \var{protocol} parameter. \versionchanged[The \var{protocol}
+%[- MARK -] END DIFF
\refstmodindex{pickle}
\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}\optional{,binary=\code{None}}}}}}
@@ -48,6 +63,27 @@
Gli oggetti shelve supportano tutti i metodi supportati dai
dizionari. Questo semplifica la transizione di dizionari basati sugli
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 41
+%[- MARK -]
+%[- MARK -] Shelve objects support all methods supported by dictionaries. This eases
+%[- MARK -] the transition from dictionary based scripts to those requiring persistent
+%[- MARK -] storage.
+%[- MARK -]
+%[- MARK -] +One additional method is supported:
+%[- MARK -] +\begin{methoddesc}[Shelf]{sync}{}
+%[- MARK -] +Write back all entries in the cache if the shelf was opened with
+%[- MARK -] +\var{writeback} set to \var{True}. Also empty the cache and synchronize
+%[- MARK -] +the persistent dictionary on disk, if feasible. This is called automatically
+%[- MARK -] +when the shelf is closed with \method{close()}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] \subsection{Restrictions}
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -]
+%[- MARK -] \item
+%[- MARK -] END DIFF
script in dizionari che richiedono la memorizzazione persistente.
\subsection{Restrizioni}
Modified: python/python/Doc/branches/2.4.3/lib/libshlex.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libshlex.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libshlex.tex Fri Jun 2 12:52:55 2006
@@ -15,6 +15,21 @@
\UNIX{}. Questo risulterà spesso utile nella scrittura di
minilinguaggi, (per esempio nell'esecuzione di file di controllo
per le applicazioni Python) o per analizzare stringhe racchiuse tra
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 13
+%[- MARK -] The \class{shlex} class makes it easy to write lexical analyzers for
+%[- MARK -] simple syntaxes resembling that of the \UNIX{} shell. This will often
+%[- MARK -] be useful for writing minilanguages, (for example, in run control
+%[- MARK -] files for Python applications) or for parsing quoted strings.
+%[- MARK -]
+%[- MARK -] +\note{The \module{shlex} module currently does not support Unicode input.}
+%[- MARK -] +
+%[- MARK -] The \module{shlex} module defines the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{split}{s\optional{, comments}}
+%[- MARK -] Split the string \var{s} using shell-like syntax. If \var{comments} is
+%[- MARK -] \constant{False} (the default), the parsing of comments in the given
+%[- MARK -] END DIFF
virgolette.
Il modulo \module{shlex} definisce le seguenti funzioni:
Modified: python/python/Doc/branches/2.4.3/lib/libshutil.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libshutil.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libshutil.tex Fri Jun 2 12:52:55 2006
@@ -94,6 +94,21 @@
risultanti da una fallita rimozione verranno ignorati; se impostato a
\constant{False} o omesso, tali errori verranno trattati da un gestore
specificato da \var{onerror} o, se questo viene omesso, solleveranno
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 88
+%[- MARK -] \var{onerror} or, if that is omitted, they raise an exception.
+%[- MARK -]
+%[- MARK -] If \var{onerror} is provided, it must be a callable that accepts
+%[- MARK -] three parameters: \var{function}, \var{path}, and \var{excinfo}.
+%[- MARK -] The first parameter, \var{function}, is the function which raised
+%[- MARK -] - the exception; it will be \function{os.remove()} or
+%[- MARK -] + the exception; it will be \function{os.listdir()}, \function{os.remove()} or
+%[- MARK -] \function{os.rmdir()}. The second parameter, \var{path}, will be
+%[- MARK -] the path name passed to \var{function}. The third parameter,
+%[- MARK -] \var{excinfo}, will be the exception information return by
+%[- MARK -] \function{sys.exc_info()}. Exceptions raised by \var{onerror} will
+%[- MARK -] not be caught.
+%[- MARK -] END DIFF
un'eccezione.
Se viene fornito \var{onerror}, deve essere un oggetto chiamabile che
Modified: python/python/Doc/branches/2.4.3/lib/libsignal.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsignal.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsignal.tex Fri Jun 2 12:52:55 2006
@@ -143,6 +143,26 @@
Quando i thread sono abilitati, questa funzione può essere chiamata
unicamente dal thread principale; chiamandola da altri thread verrà
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 137
+%[- MARK -] When threads are enabled, this function can only be called from the
+%[- MARK -] main thread; attempting to call it from other threads will cause a
+%[- MARK -] \exception{ValueError} exception to be raised.
+%[- MARK -]
+%[- MARK -] The \var{handler} is called with two arguments: the signal number
+%[- MARK -] - and the current stack frame (\code{None} or a frame object; see the
+%[- MARK -] - reference manual for a description of frame objects).
+%[- MARK -] -\obindex{frame}
+%[- MARK -] + and the current stack frame (\code{None} or a frame object;
+%[- MARK -] + for a description of frame objects, see the reference manual section
+%[- MARK -] + on the standard type hierarchy or see the attribute descriptions in
+%[- MARK -] + the \refmodule{inspect} module).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \subsection{Example}
+%[- MARK -] \nodename{Signal Example}
+%[- MARK -]
+%[- MARK -] END DIFF
sollevata un'eccezione \exception{ValueError}.
L'\var{handler} viene chiamato con due argomenti: il numero di
Modified: python/python/Doc/branches/2.4.3/lib/libsimplehttp.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsimplehttp.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsimplehttp.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,38 @@
\declaremodule{standard}{SimpleHTTPServer}
\sectionauthor{Moshe Zadka}{moshez a zadka.site.co.il}
\modulesynopsis{Questo modulo fornisce un gestore di richieste di base
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 6
+%[- MARK -] \modulesynopsis{This module provides a basic request handler for HTTP
+%[- MARK -] servers.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] The \module{SimpleHTTPServer} module defines a request-handler class,
+%[- MARK -] -interface compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler}
+%[- MARK -] -which serves files only from a base directory.
+%[- MARK -] +interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler},
+%[- MARK -] +that serves files only from a base directory.
+%[- MARK -]
+%[- MARK -] The \module{SimpleHTTPServer} module defines the following class:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server}
+%[- MARK -] -This class is used, to serve files from current directory and below,
+%[- MARK -] +This class is used to serve files from the current directory and below,
+%[- MARK -] directly mapping the directory structure to HTTP requests.
+%[- MARK -]
+%[- MARK -] -A lot of the work is done by the base class
+%[- MARK -] -\class{BaseHTTPServer.BaseHTTPRequestHandler}, such as parsing the
+%[- MARK -] -request. This class implements the \function{do_GET()} and
+%[- MARK -] -\function{do_HEAD()} functions.
+%[- MARK -] +A lot of the work, such as parsing the request, is done by the base
+%[- MARK -] +class \class{BaseHTTPServer.BaseHTTPRequestHandler}. This class
+%[- MARK -] +implements the \function{do_GET()} and \function{do_HEAD()} functions.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] The \class{SimpleHTTPRequestHandler} defines the following member
+%[- MARK -] variables:
+%[- MARK -]
+%[- MARK -] END DIFF
per server HTTP.}
@@ -31,6 +63,69 @@
\begin{memberdesc}{server_version}
Questa sarà \code{"SimpleHTTP/" + __version__}, dove
\code{__version__} viene definita nel modulo.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 30
+%[- MARK -] This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__}
+%[- MARK -] is defined in the module.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{extensions_map}
+%[- MARK -] -A dictionary mapping suffixes into MIME types. Default is signified
+%[- MARK -] -by an empty string, and is considered to be \code{text/plain}.
+%[- MARK -] +A dictionary mapping suffixes into MIME types. The default is signified
+%[- MARK -] +by an empty string, and is considered to be \code{application/octet-stream}.
+%[- MARK -] The mapping is used case-insensitively, and so should contain only
+%[- MARK -] lower-cased keys.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] The \class{SimpleHTTPRequestHandler} defines the following methods:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{do_HEAD}{}
+%[- MARK -] This method serves the \code{'HEAD'} request type: it sends the
+%[- MARK -] headers it would send for the equivalent \code{GET} request. See the
+%[- MARK -] -\method{do_GET()} method for more complete explanation of the possible
+%[- MARK -] +\method{do_GET()} method for a more complete explanation of the possible
+%[- MARK -] headers.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{do_GET}{}
+%[- MARK -] The request is mapped to a local file by interpreting the request as
+%[- MARK -] a path relative to the current working directory.
+%[- MARK -]
+%[- MARK -] -If the request was mapped to a directory, a \code{403} respond is output,
+%[- MARK -] -followed by the explanation \code{'Directory listing not supported'}.
+%[- MARK -] -Any \exception{IOError} exception in opening the requested file, is mapped
+%[- MARK -] -to a \code{404}, \code{'File not found'} error. Otherwise, the content
+%[- MARK -] -type is guessed using the \var{extensions_map} variable.
+%[- MARK -] -
+%[- MARK -] -A \code{'Content-type:'} with the guessed content type is output, and
+%[- MARK -] -then a blank line, signifying end of headers, and then the contents of
+%[- MARK -] -the file. The file is always opened in binary mode.
+%[- MARK -] +If the request was mapped to a directory, the directory is checked for
+%[- MARK -] +a file named \code{index.html} or \code{index.htm} (in that order).
+%[- MARK -] +If found, the file's contents are returned; otherwise a directory
+%[- MARK -] +listing is generated by calling the \method{list_directory()} method.
+%[- MARK -] +This method uses \function{os.listdir()} to scan the directory, and
+%[- MARK -] +returns a \code{404} error response if the \function{listdir()} fails.
+%[- MARK -] +
+%[- MARK -] +If the request was mapped to a file, it is opened and the contents are
+%[- MARK -] +returned. Any \exception{IOError} exception in opening the requested
+%[- MARK -] +file is mapped to a \code{404}, \code{'File not found'}
+%[- MARK -] +error. Otherwise, the content type is guessed by calling the
+%[- MARK -] +\method{guess_type()} method, which in turn uses the
+%[- MARK -] +\var{extensions_map} variable.
+%[- MARK -] +
+%[- MARK -] +A \code{'Content-type:'} header with the guessed content type is
+%[- MARK -] +output, followed by a blank line signifying the end of the headers,
+%[- MARK -] +and then the contents of the file are output. If the file's MIME type
+%[- MARK -] +starts with \code{text/} the file is opened in text mode; otherwise
+%[- MARK -] +binary mode is used.
+%[- MARK -]
+%[- MARK -] For example usage, see the implementation of the \function{test()}
+%[- MARK -] function.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{memberdesc}{extensions_map}
Modified: python/python/Doc/branches/2.4.3/lib/libsimplexmlrpc.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsimplexmlrpc.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsimplexmlrpc.tex Fri Jun 2 12:52:55 2006
@@ -55,6 +55,56 @@
\code{\var{function}.__name__}. \var{name} può essere una stringa
normale o Unicode, e può contenere caratteri non validi negli
identificatori Python, incluso il carattere della virgola.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 53
+%[- MARK -] used. \var{name} can be either a normal or Unicode string, and may
+%[- MARK -] contain characters not legal in Python identifiers, including the
+%[- MARK -] period character.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance}
+%[- MARK -] +\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{,
+%[- MARK -] + allow_dotted_names}}
+%[- MARK -] Register an object which is used to expose method names which have
+%[- MARK -] not been registered using \method{register_function()}. If
+%[- MARK -] \var{instance} contains a \method{_dispatch()} method, it is called
+%[- MARK -] - with the requested method name and the parameters from the request;
+%[- MARK -] - the return value is returned to the client as the result. If
+%[- MARK -] + with the requested method name and the parameters from the request. Its
+%[- MARK -] + API is \code{def \method{_dispatch}(self, method, params)} (note that
+%[- MARK -] + \var{params} does not represent a variable argument list). If it calls an
+%[- MARK -] + underlying function to perform its task, that function is called as
+%[- MARK -] + \code{func(*params)}, expanding the parameter list.
+%[- MARK -] + The return value from \method{_dispatch()} is returned to the client as
+%[- MARK -] + the result. If
+%[- MARK -] \var{instance} does not have a \method{_dispatch()} method, it is
+%[- MARK -] - searched for an attribute matching the name of the requested method;
+%[- MARK -] + searched for an attribute matching the name of the requested method.
+%[- MARK -] +
+%[- MARK -] + If the optional \var{allow_dotted_names} argument is true and the
+%[- MARK -] + instance does not have a \method{_dispatch()} method, then
+%[- MARK -] if the requested method name contains periods, each component of the
+%[- MARK -] method name is searched for individually, with the effect that a
+%[- MARK -] simple hierarchical search is performed. The value found from this
+%[- MARK -] search is then called with the parameters from the request, and the
+%[- MARK -] return value is passed back to the client.
+%[- MARK -] +
+%[- MARK -] + \begin{notice}[warning]
+%[- MARK -] + Enabling the \var{allow_dotted_names} option allows intruders to access
+%[- MARK -] + your module's global variables and may allow intruders to execute
+%[- MARK -] + arbitrary code on your machine. Only use this option on a secure,
+%[- MARK -] + closed network.
+%[- MARK -] + \end{notice}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[\var{allow_dotted_names} was added to plug a security hole;
+%[- MARK -] + prior versions are insecure]{2.3.5, 2.4.1}
+%[- MARK -] +
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{register_introspection_functions}{}
+%[- MARK -] Registers the XML-RPC introspection functions \code{system.listMethods},
+%[- MARK -] \code{system.methodHelp} and \code{system.methodSignature}.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance}
@@ -80,6 +130,21 @@
Registra le funzioni multichiamata XML-RPC \code{system.multicall}.
\end{methoddesc}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 82
+%[- MARK -]
+%[- MARK -] Example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] class MyFuncs:
+%[- MARK -] - def div(self, x, y) : return div(x,y)
+%[- MARK -] + def div(self, x, y) : return x // y
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] server = SimpleXMLRPCServer(("localhost", 8000))
+%[- MARK -] server.register_function(pow)
+%[- MARK -] server.register_function(lambda x,y: x+y, 'add')
+%[- MARK -] END DIFF
Esempio:
\begin{verbatim}
Added: python/python/Doc/branches/2.4.3/lib/libsmtpd.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libsmtpd.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,64 @@
+%[- MARK -] BEGIN PART 001 of 1
+\section{\module{smtpd} ---
+ SMTP Server}
+
+\declaremodule{standard}{smtpd}
+
+\moduleauthor{Barry Warsaw}{barry a zope.com}
+\sectionauthor{Moshe Zadka}{moshez a moshez.org}
+
+\modulesynopsis{Implement a flexible SMTP server}
+
+This module offers several classes to implement SMTP servers. One is
+a generic do-nothing implementation, which can be overridden, while
+the other two offer specific mail-sending strategies.
+
+
+\subsection{SMTPServer Objects}
+
+\begin{classdesc}{SMTPServer}{localaddr, remoteaddr}
+Create a new \class{SMTPServer} object, which binds to local address
+\var{localaddr}. It will treat \var{remoteaddr} as an upstream SMTP
+relayer. It inherits from \class{asyncore.dispatcher}, and so will
+insert itself into \refmodule{asyncore}'s event loop on instantiation.
+\end{classdesc}
+
+\begin{methoddesc}[SMTPServer]{process_message}{peer, mailfrom, rcpttos, data}
+Raise \exception{NotImplementedError} exception. Override this in
+subclasses to do something useful with this message. Whatever was
+passed in the constructor as \var{remoteaddr} will be available as the
+\member{_remoteaddr} attribute. \var{peer} is the remote host's address,
+\var{mailfrom} is the envelope originator, \var{rcpttos} are the
+envelope recipients and \var{data} is a string containing the contents
+of the e-mail (which should be in \rfc{2822} format).
+\end{methoddesc}
+
+
+\subsection{DebuggingServer Objects}
+
+\begin{classdesc}{DebuggingServer}{localaddr, remoteaddr}
+Create a new debugging server. Arguments are as per
+\class{SMTPServer}. Messages will be discarded, and printed on
+stdout.
+\end{classdesc}
+
+
+\subsection{PureProxy Objects}
+
+\begin{classdesc}{PureProxy}{localaddr, remoteaddr}
+Create a new pure proxy server. Arguments are as per \class{SMTPServer}.
+Everything will be relayed to \var{remoteaddr}. Note that running
+this has a good chance to make you into an open relay, so please be
+careful.
+\end{classdesc}
+
+
+\subsection{MailmanProxy Objects}
+
+\begin{classdesc}{MailmanProxy}{localaddr, remoteaddr}
+Create a new pure proxy server. Arguments are as per
+\class{SMTPServer}. Everything will be relayed to \var{remoteaddr},
+unless local mailman configurations knows about an address, in which
+case it will be handled via mailman. Note that running this has a
+good chance to make you into an open relay, so please be careful.
+\end{classdesc}
Modified: python/python/Doc/branches/2.4.3/lib/libsmtplib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsmtplib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsmtplib.tex Fri Jun 2 12:52:55 2006
@@ -195,6 +195,34 @@
Se vengono forniti \var{keyfile} e \var{certfile}, questi vengono
passati alla funzione \function{ssl()} del modulo \refmodule{socket}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 188
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{,
+%[- MARK -] mail_options, rcpt_options}}
+%[- MARK -] Send mail. The required arguments are an \rfc{822} from-address
+%[- MARK -] -string, a list of \rfc{822} to-address strings, and a message string.
+%[- MARK -] -The caller may pass a list of ESMTP options (such as \samp{8bitmime})
+%[- MARK -] -to be used in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP
+%[- MARK -] -options (such as \samp{DSN} commands) that should be used with all
+%[- MARK -] -\samp{RCPT} commands can be passed as \var{rcpt_options}. (If you
+%[- MARK -] -need to use different ESMTP options to different recipients you have
+%[- MARK -] -to use the low-level methods such as \method{mail}, \method{rcpt} and
+%[- MARK -] +string, a list of \rfc{822} to-address strings (a bare string will be
+%[- MARK -] +treated as a list with 1 address), and a message string. The caller
+%[- MARK -] +may pass a list of ESMTP options (such as \samp{8bitmime}) to be used
+%[- MARK -] +in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP options
+%[- MARK -] +(such as \samp{DSN} commands) that should be used with all \samp{RCPT}
+%[- MARK -] +commands can be passed as \var{rcpt_options}. (If you need to use
+%[- MARK -] +different ESMTP options to different recipients you have to use the
+%[- MARK -] +low-level methods such as \method{mail}, \method{rcpt} and
+%[- MARK -] \method{data} to send the message.)
+%[- MARK -]
+%[- MARK -] \note{The \var{from_addr} and \var{to_addrs} parameters are
+%[- MARK -] used to construct the message envelope used by the transport agents.
+%[- MARK -] The \class{SMTP} does not modify the message headers in any way.}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{,
Modified: python/python/Doc/branches/2.4.3/lib/libsocket.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsocket.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsocket.tex Fri Jun 2 12:52:55 2006
@@ -2,6 +2,22 @@
Interfaccia di rete di basso livello}
\declaremodule{builtin}{socket}
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 5
+%[- MARK -] \modulesynopsis{Low-level networking interface.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] This module provides access to the BSD \emph{socket} interface.
+%[- MARK -] It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
+%[- MARK -] -OS/2, and probably additional platforms.
+%[- MARK -] +OS/2, and probably additional platforms. \note{Some behavior may be
+%[- MARK -] +platform dependent, since calls are made to the operating system socket APIs.}
+%[- MARK -]
+%[- MARK -] For an introduction to socket programming (in C), see the following
+%[- MARK -] papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
+%[- MARK -] Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
+%[- MARK -] Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
+%[- MARK -] END DIFF
\modulesynopsis{Interfaccia di rete di basso livello.}
@@ -199,6 +215,23 @@
descritto sopra. Leggere i sorgenti di \refmodule{httplib} ed altri
moduli di libreria per un utilizzo tipico della funzione.
\versionadded{2.2}
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 200
+%[- MARK -] Return a fully qualified domain name for \var{name}.
+%[- MARK -] If \var{name} is omitted or empty, it is interpreted as the local
+%[- MARK -] host. To find the fully qualified name, the hostname returned by
+%[- MARK -] \function{gethostbyaddr()} is checked, then aliases for the host, if
+%[- MARK -] available. The first name which includes a period is selected. In
+%[- MARK -] -case no fully qualified domain name is available, the hostname is
+%[- MARK -] -returned.
+%[- MARK -] +case no fully qualified domain name is available, the hostname as
+%[- MARK -] +returned by \function{gethostname()} is returned.
+%[- MARK -] \versionadded{2.0}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{gethostbyname}{hostname}
+%[- MARK -] Translate a host name to IPv4 address format. The IPv4 address is
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{getfqdn}{\optional{nome}}
@@ -279,6 +312,32 @@
per socket aperti in modalità ``raw'' (\constant{SOCK_RAW}); per le
normali modalità adottate con i socket, il protocollo corretto è
scelto automaticamente se è omesso oppure zero.
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 270
+%[- MARK -] opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
+%[- MARK -] modes, the correct protocol is chosen automatically if the protocol is
+%[- MARK -] omitted or zero.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{getservbyname}{servicename, protocolname}
+%[- MARK -] +\begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}}
+%[- MARK -] Translate an Internet service name and protocol name to a port number
+%[- MARK -] -for that service. The protocol name should be \code{'tcp'} or
+%[- MARK -] -\code{'udp'}.
+%[- MARK -] +for that service. The optional protocol name, if given, should be
+%[- MARK -] +\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{getservbyport}{port\optional{, protocolname}}
+%[- MARK -] +Translate an Internet port number and protocol name to a service name
+%[- MARK -] +for that service. The optional protocol name, if given, should be
+%[- MARK -] +\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{socket}{\optional{family\optional{,
+%[- MARK -] type\optional{, proto}}}}
+%[- MARK -] Create a new socket using the given address family, socket type and
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{getservbyname}{servicename, protocolname}
@@ -307,6 +366,28 @@
\class{SSLObject}.
\warning{Questa funzione non effettua nessuna verifica di certificazione!}
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 295
+%[- MARK -] success, a new \class{SSLObject} is returned.
+%[- MARK -]
+%[- MARK -] \warning{This does not do any certificate verification!}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}
+%[- MARK -] +Build a pair of connected socket objects using the given address
+%[- MARK -] +family, socket type, and protocol number. Address family, socket type,
+%[- MARK -] +and protocol number are as for the \function{socket()} function above.
+%[- MARK -] +The default family is \constant{AF_UNIX} if defined on the platform;
+%[- MARK -] +otherwise, the default is \constant{AF_INET}.
+%[- MARK -] +Availability: \UNIX. \versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
+%[- MARK -] Build a socket object from an existing file descriptor (an integer as
+%[- MARK -] returned by a file object's \method{fileno()} method). Address family,
+%[- MARK -] socket type and protocol number are as for the \function{socket()} function
+%[- MARK -] above. The file descriptor should refer to a socket, but this is not
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
@@ -560,6 +641,21 @@
\var{bufsize} sono interpretati nello stesso modo della funzione
built-in \function{file()}; leggere ``Funzioni built-in'' (sezione
\ref{built-in-funcs}) per ulteriori informazioni.
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 539
+%[- MARK -] Receive data from the socket. The return value is a string representing
+%[- MARK -] the data received. The maximum amount of data to be received
+%[- MARK -] at once is specified by \var{bufsize}. See the \UNIX{} manual page
+%[- MARK -] \manpage{recv}{2} for the meaning of the optional argument
+%[- MARK -] \var{flags}; it defaults to zero.
+%[- MARK -] +\note{For best match with hardware and network realities, the value of
+%[- MARK -] +\var{bufsize} should be a relatively small power of 2, for example, 4096.}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
+%[- MARK -] Receive data from the socket. The return value is a pair
+%[- MARK -] \code{(\var{string}, \var{address})} where \var{string} is a string
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
@@ -741,6 +837,21 @@
\begin{verbatim}
# Programma client Echo
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 712
+%[- MARK -] s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+%[- MARK -] s.connect((HOST, PORT))
+%[- MARK -] s.send('Hello, world')
+%[- MARK -] data = s.recv(1024)
+%[- MARK -] s.close()
+%[- MARK -] -print 'Received', `data`
+%[- MARK -] +print 'Received', repr(data)
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] The next two examples are identical to the above two, but support both
+%[- MARK -] IPv4 and IPv6.
+%[- MARK -] The server side will listen to the first address family available
+%[- MARK -] END DIFF
import socket
HOST = 'daring.cwi.nl' # Il nodo remoto
@@ -801,6 +912,17 @@
\begin{verbatim}
# Programma client Echo
import socket
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 788
+%[- MARK -] print 'could not open socket'
+%[- MARK -] sys.exit(1)
+%[- MARK -] s.send('Hello, world')
+%[- MARK -] data = s.recv(1024)
+%[- MARK -] s.close()
+%[- MARK -] -print 'Received', `data`
+%[- MARK -] +print 'Received', repr(data)
+%[- MARK -] \end{verbatim}
+%[- MARK -] END DIFF
import sys
HOST = 'daring.cwi.nl' # Il nodo remoto
Modified: python/python/Doc/branches/2.4.3/lib/libsocksvr.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libsocksvr.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libsocksvr.tex Fri Jun 2 12:52:55 2006
@@ -54,6 +54,99 @@
Le classi server hanno gli stessi metodi ed attributi esterni,
indipendentemente dal protocollo che utilizzano.
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 50
+%[- MARK -] Server classes have the same external methods and attributes, no
+%[- MARK -] matter what network protocol they use:
+%[- MARK -]
+%[- MARK -] \setindexsubitem{(SocketServer protocol)}
+%[- MARK -]
+%[- MARK -] +\subsection{Server Creation Notes}
+%[- MARK -] +
+%[- MARK -] +There are five classes in an inheritance diagram, four of which represent
+%[- MARK -] +synchronous servers of four types:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + +------------+
+%[- MARK -] + | BaseServer |
+%[- MARK -] + +------------+
+%[- MARK -] + |
+%[- MARK -] + v
+%[- MARK -] + +-----------+ +------------------+
+%[- MARK -] + | TCPServer |------->| UnixStreamServer |
+%[- MARK -] + +-----------+ +------------------+
+%[- MARK -] + |
+%[- MARK -] + v
+%[- MARK -] + +-----------+ +--------------------+
+%[- MARK -] + | UDPServer |------->| UnixDatagramServer |
+%[- MARK -] + +-----------+ +--------------------+
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not
+%[- MARK -] +from \class{UnixStreamServer} -- the only difference between an IP and a
+%[- MARK -] +Unix stream server is the address family, which is simply repeated in both
+%[- MARK -] +unix server classes.
+%[- MARK -] +
+%[- MARK -] +Forking and threading versions of each type of server can be created using
+%[- MARK -] +the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For
+%[- MARK -] +instance, a threading UDP server class is created as follows:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The mix-in class must come first, since it overrides a method defined in
+%[- MARK -] +\class{UDPServer}. Setting the various member variables also changes the
+%[- MARK -] +behavior of the underlying server mechanism.
+%[- MARK -] +
+%[- MARK -] +To implement a service, you must derive a class from
+%[- MARK -] +\class{BaseRequestHandler} and redefine its \method{handle()} method. You
+%[- MARK -] +can then run various versions of the service by combining one of the server
+%[- MARK -] +classes with your request handler class. The request handler class must be
+%[- MARK -] +different for datagram or stream services. This can be hidden by using the
+%[- MARK -] +handler subclasses \class{StreamRequestHandler} or \class{DatagramRequestHandler}.
+%[- MARK -] +
+%[- MARK -] +Of course, you still have to use your head! For instance, it makes no sense
+%[- MARK -] +to use a forking server if the service contains state in memory that can be
+%[- MARK -] +modified by different requests, since the modifications in the child process
+%[- MARK -] +would never reach the initial state kept in the parent process and passed to
+%[- MARK -] +each child. In this case, you can use a threading server, but you will
+%[- MARK -] +probably have to use locks to protect the integrity of the shared data.
+%[- MARK -] +
+%[- MARK -] +On the other hand, if you are building an HTTP server where all data is
+%[- MARK -] +stored externally (for instance, in the file system), a synchronous class
+%[- MARK -] +will essentially render the service "deaf" while one request is being
+%[- MARK -] +handled -- which may be for a very long time if a client is slow to receive
+%[- MARK -] +all the data it has requested. Here a threading or forking server is
+%[- MARK -] +appropriate.
+%[- MARK -] +
+%[- MARK -] +In some cases, it may be appropriate to process part of a request
+%[- MARK -] +synchronously, but to finish processing in a forked child depending on the
+%[- MARK -] +request data. This can be implemented by using a synchronous server and
+%[- MARK -] +doing an explicit fork in the request handler class \method{handle()}
+%[- MARK -] +method.
+%[- MARK -] +
+%[- MARK -] +Another approach to handling multiple simultaneous requests in an
+%[- MARK -] +environment that supports neither threads nor \function{fork()} (or where
+%[- MARK -] +these are too expensive or inappropriate for the service) is to maintain an
+%[- MARK -] +explicit table of partially finished requests and to use \function{select()}
+%[- MARK -] +to decide which request to work on next (or whether to handle a new incoming
+%[- MARK -] +request). This is particularly important for stream services where each
+%[- MARK -] +client can potentially be connected for a long time (if threads or
+%[- MARK -] +subprocesses cannot be used).
+%[- MARK -] +
+%[- MARK -] %XXX should data and methods be intermingled, or separate?
+%[- MARK -] % how should the distinction between class and instance variables be
+%[- MARK -] % drawn?
+%[- MARK -]
+%[- MARK -] +\subsection{Server Objects}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{fileno}{}
+%[- MARK -] Return an integer file descriptor for the socket on which the server
+%[- MARK -] is listening. This function is most commonly passed to
+%[- MARK -] \function{select.select()}, to allow monitoring multiple servers in the
+%[- MARK -] same process.
+%[- MARK -] END DIFF
\setindexsubitem{(SocketServer protocol)}
%XXX should data and methods be intermingled, or separate?
@@ -108,6 +201,21 @@
% XXX should class variables be covered before instance variables, or
% vice versa?
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 104
+%[- MARK -]
+%[- MARK -] The server classes support the following class variables:
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{allow_reuse_address}
+%[- MARK -] Whether the server will allow the reuse of an address. This defaults
+%[- MARK -] -to \code{False}, and can be set in subclasses to change the policy.
+%[- MARK -] +to \constant{False}, and can be set in subclasses to change the policy.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{request_queue_size}
+%[- MARK -] The size of the request queue. If it takes a long time to process a
+%[- MARK -] single request, any requests that arrive while the server is busy are
+%[- MARK -] END DIFF
La classe server supporta le seguenti variabili di classe:
\begin{datadesc}{allow_reuse_address}
@@ -167,6 +275,42 @@
% Is there any point in documenting the following two functions?
% What would the purpose of overriding them be: initializing server
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 158
+%[- MARK -] % Is there any point in documenting the following two functions?
+%[- MARK -] % What would the purpose of overriding them be: initializing server
+%[- MARK -] % instance variables, adding new network families?
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{server_activate}{}
+%[- MARK -] -Called by the server's constructor to activate the server.
+%[- MARK -] +Called by the server's constructor to activate the server. The default
+%[- MARK -] +behavior just \method{listen}s to the server's socket.
+%[- MARK -] May be overridden.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{server_bind}{}
+%[- MARK -] Called by the server's constructor to bind the socket to the desired
+%[- MARK -] address. May be overridden.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{verify_request}{request, client_address}
+%[- MARK -] -Must return a Boolean value; if the value is true, the request will be
+%[- MARK -] -processed, and if it's false, the request will be denied.
+%[- MARK -] +Must return a Boolean value; if the value is \constant{True}, the request will be
+%[- MARK -] +processed, and if it's \constant{False}, the request will be denied.
+%[- MARK -] This function can be overridden to implement access controls for a server.
+%[- MARK -] -The default implementation always return true.
+%[- MARK -] +The default implementation always returns \constant{True}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\subsection{RequestHandler Objects}
+%[- MARK -] +
+%[- MARK -] The request handler class must define a new \method{handle()} method,
+%[- MARK -] and can override any of the following methods. A new instance is
+%[- MARK -] created for each request.
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{finish}{}
+%[- MARK -] END DIFF
% instance variables, adding new network families?
\begin{funcdesc}{server_activate}{}
@@ -196,6 +340,36 @@
pulizia richiesta. L'implementazione predefinita non fa nulla. Se
\method{setup()} o \method{handle()} sollevano un'eccezione, questa
funzione non verrà chiamata.
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 187
+%[- MARK -] function will not be called.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{handle}{}
+%[- MARK -] This function must do all the work required to service a request.
+%[- MARK -] +The default implementation does nothing.
+%[- MARK -] Several instance attributes are available to it; the request is
+%[- MARK -] available as \member{self.request}; the client address as
+%[- MARK -] \member{self.client_address}; and the server instance as
+%[- MARK -] \member{self.server}, in case it needs access to per-server
+%[- MARK -] information.
+%[- MARK -]
+%[- MARK -] The type of \member{self.request} is different for datagram or stream
+%[- MARK -] services. For stream services, \member{self.request} is a socket
+%[- MARK -] object; for datagram services, \member{self.request} is a string.
+%[- MARK -] -However, this can be hidden by using the mix-in request handler
+%[- MARK -] -classes
+%[- MARK -] +However, this can be hidden by using the request handler subclasses
+%[- MARK -] \class{StreamRequestHandler} or \class{DatagramRequestHandler}, which
+%[- MARK -] override the \method{setup()} and \method{finish()} methods, and
+%[- MARK -] -provides \member{self.rfile} and \member{self.wfile} attributes.
+%[- MARK -] +provide \member{self.rfile} and \member{self.wfile} attributes.
+%[- MARK -] \member{self.rfile} and \member{self.wfile} can be read or written,
+%[- MARK -] respectively, to get the request data or return data to the client.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{setup}{}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{handle}{}
Modified: python/python/Doc/branches/2.4.3/lib/libstring.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libstring.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libstring.tex Fri Jun 2 12:52:55 2006
@@ -2,6 +2,29 @@
Operazioni comuni sulle stringhe}
\declaremodule{standard}{string}
+%[- MARK -] BEGIN DIFF 001 of 5
+%[- MARK -] @@ 2
+%[- MARK -] Common string operations}
+%[- MARK -]
+%[- MARK -] \declaremodule{standard}{string}
+%[- MARK -] \modulesynopsis{Common string operations.}
+%[- MARK -]
+%[- MARK -] +The \module{string} module contains a number of useful constants and classes,
+%[- MARK -] +as well as some deprecated legacy functions that are also available as methods
+%[- MARK -] +on strings. See the module \refmodule{re}\refstmodindex{re} for string
+%[- MARK -] +functions based on regular expressions.
+%[- MARK -]
+%[- MARK -] -This module defines some constants useful for checking character
+%[- MARK -] -classes and some useful string functions. See the module
+%[- MARK -] -\refmodule{re}\refstmodindex{re} for string functions based on regular
+%[- MARK -] -expressions.
+%[- MARK -] +\subsection{String constants}
+%[- MARK -]
+%[- MARK -] The constants defined in this module are:
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{ascii_letters}
+%[- MARK -] The concatenation of the \constant{ascii_lowercase} and
+%[- MARK -] END DIFF
\modulesynopsis{Operazioni comuni sulle stringhe.}
@@ -84,6 +107,173 @@
tabulazione, fine riga, return, formfeed e tabulazioni verticali. Non
cambiate la sua definizione: l'effetto sulle funzioni
\function{strip()} e \function{split()} è indefinito.
+%[- MARK -] BEGIN DIFF 002 of 5
+%[- MARK -] @@ 84
+%[- MARK -] return, formfeed, and vertical tab. Do not change its definition ---
+%[- MARK -] the effect on the routines \function{strip()} and \function{split()}
+%[- MARK -] is undefined.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] +\subsection{Template strings}
+%[- MARK -]
+%[- MARK -] -Many of the functions provided by this module are also defined as
+%[- MARK -] -methods of string and Unicode objects; see ``String Methods'' (section
+%[- MARK -] -\ref{string-methods}) for more information on those.
+%[- MARK -] -The functions defined in this module are:
+%[- MARK -] +Templates provide simpler string substitutions as described in \pep{292}.
+%[- MARK -] +Instead of the normal \samp{\%}-based substitutions, Templates support
+%[- MARK -] +\samp{\$}-based substitutions, using the following rules:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \samp{\$\$} is an escape; it is replaced with a single \samp{\$}.
+%[- MARK -] +
+%[- MARK -] +\item \samp{\$identifier} names a substitution placeholder matching a mapping
+%[- MARK -] + key of "identifier". By default, "identifier" must spell a Python
+%[- MARK -] + identifier. The first non-identifier character after the \samp{\$}
+%[- MARK -] + character terminates this placeholder specification.
+%[- MARK -] +
+%[- MARK -] +\item \samp{\$\{identifier\}} is equivalent to \samp{\$identifier}. It is
+%[- MARK -] + required when valid identifier characters follow the placeholder but are
+%[- MARK -] + not part of the placeholder, such as "\$\{noun\}ification".
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Any other appearance of \samp{\$} in the string will result in a
+%[- MARK -] +\exception{ValueError} being raised.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +
+%[- MARK -] +The \module{string} module provides a \class{Template} class that implements
+%[- MARK -] +these rules. The methods of \class{Template} are:
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{Template}{template}
+%[- MARK -] +The constructor takes a single argument which is the template string.
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}}
+%[- MARK -] +Performs the template substitution, returning a new string. \var{mapping} is
+%[- MARK -] +any dictionary-like object with keys that match the placeholders in the
+%[- MARK -] +template. Alternatively, you can provide keyword arguments, where the
+%[- MARK -] +keywords are the placeholders. When both \var{mapping} and \var{kws} are
+%[- MARK -] +given and there are duplicates, the placeholders from \var{kws} take
+%[- MARK -] +precedence.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}}
+%[- MARK -] +Like \method{substitute()}, except that if placeholders are missing from
+%[- MARK -] +\var{mapping} and \var{kws}, instead of raising a \exception{KeyError}
+%[- MARK -] +exception, the original placeholder will appear in the resulting string
+%[- MARK -] +intact. Also, unlike with \method{substitute()}, any other appearances of the
+%[- MARK -] +\samp{\$} will simply return \samp{\$} instead of raising
+%[- MARK -] +\exception{ValueError}.
+%[- MARK -] +
+%[- MARK -] +While other exceptions may still occur, this method is called ``safe'' because
+%[- MARK -] +substitutions always tries to return a usable string instead of raising an
+%[- MARK -] +exception. In another sense, \method{safe_substitute()} may be anything other
+%[- MARK -] +than safe, since it will silently ignore malformed templates containing
+%[- MARK -] +dangling delimiters, unmatched braces, or placeholders that are not valid
+%[- MARK -] +Python identifiers.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\class{Template} instances also provide one public data attribute:
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}[string]{template}
+%[- MARK -] +This is the object passed to the constructor's \var{template} argument. In
+%[- MARK -] +general, you shouldn't change it, but read-only access is not enforced.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +Here is an example of how to use a Template:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +>>> from string import Template
+%[- MARK -] +>>> s = Template('$who likes $what')
+%[- MARK -] +>>> s.substitute(who='tim', what='kung pao')
+%[- MARK -] +'tim likes kung pao'
+%[- MARK -] +>>> d = dict(who='tim')
+%[- MARK -] +>>> Template('Give $who $100').substitute(d)
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] +[...]
+%[- MARK -] +ValueError: Invalid placeholder in string: line 1, col 10
+%[- MARK -] +>>> Template('$who likes $what').substitute(d)
+%[- MARK -] +Traceback (most recent call last):
+%[- MARK -] +[...]
+%[- MARK -] +KeyError: 'what'
+%[- MARK -] +>>> Template('$who likes $what').safe_substitute(d)
+%[- MARK -] +'tim likes $what'
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Advanced usage: you can derive subclasses of \class{Template} to customize the
+%[- MARK -] +placeholder syntax, delimiter character, or the entire regular expression used
+%[- MARK -] +to parse template strings. To do this, you can override these class
+%[- MARK -] +attributes:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \var{delimiter} -- This is the literal string describing a placeholder
+%[- MARK -] + introducing delimiter. The default value \samp{\$}. Note that this
+%[- MARK -] + should \emph{not} be a regular expression, as the implementation will
+%[- MARK -] + call \method{re.escape()} on this string as needed.
+%[- MARK -] +\item \var{idpattern} -- This is the regular expression describing the pattern
+%[- MARK -] + for non-braced placeholders (the braces will be added automatically as
+%[- MARK -] + appropriate). The default value is the regular expression
+%[- MARK -] + \samp{[_a-z][_a-z0-9]*}.
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +Alternatively, you can provide the entire regular expression pattern by
+%[- MARK -] +overriding the class attribute \var{pattern}. If you do this, the value must
+%[- MARK -] +be a regular expression object with four named capturing groups. The
+%[- MARK -] +capturing groups correspond to the rules given above, along with the invalid
+%[- MARK -] +placeholder rule:
+%[- MARK -] +
+%[- MARK -] +\begin{itemize}
+%[- MARK -] +\item \var{escaped} -- This group matches the escape sequence,
+%[- MARK -] + e.g. \samp{\$\$}, in the default pattern.
+%[- MARK -] +\item \var{named} -- This group matches the unbraced placeholder name; it
+%[- MARK -] + should not include the delimiter in capturing group.
+%[- MARK -] +\item \var{braced} -- This group matches the brace enclosed placeholder name;
+%[- MARK -] + it should not include either the delimiter or braces in the capturing
+%[- MARK -] + group.
+%[- MARK -] +\item \var{invalid} -- This group matches any other delimiter pattern (usually
+%[- MARK -] + a single delimiter), and it should appear last in the regular
+%[- MARK -] + expression.
+%[- MARK -] +\end{itemize}
+%[- MARK -] +
+%[- MARK -] +\subsection{String functions}
+%[- MARK -] +
+%[- MARK -] +The following functions are available to operate on string and Unicode
+%[- MARK -] +objects. They are not available as string methods.
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{capwords}{s}
+%[- MARK -] + Split the argument into words using \function{split()}, capitalize
+%[- MARK -] + each word using \function{capitalize()}, and join the capitalized
+%[- MARK -] + words using \function{join()}. Note that this replaces runs of
+%[- MARK -] + whitespace characters by a single space, and removes leading and
+%[- MARK -] + trailing whitespace.
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{funcdesc}{maketrans}{from, to}
+%[- MARK -] + Return a translation table suitable for passing to
+%[- MARK -] + \function{translate()} or \function{regex.compile()}, that will map
+%[- MARK -] + each character in \var{from} into the character at the same position
+%[- MARK -] + in \var{to}; \var{from} and \var{to} must have the same length.
+%[- MARK -] +
+%[- MARK -] + \warning{Don't use strings derived from \constant{lowercase}
+%[- MARK -] + and \constant{uppercase} as arguments; in some locales, these don't have
+%[- MARK -] + the same length. For case conversions, always use
+%[- MARK -] + \function{lower()} and \function{upper()}.}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] +\subsection{Deprecated string functions}
+%[- MARK -] +
+%[- MARK -] +The following list of functions are also defined as methods of string and
+%[- MARK -] +Unicode objects; see ``String Methods'' (section
+%[- MARK -] +\ref{string-methods}) for more information on those. You should consider
+%[- MARK -] +these functions as deprecated, although they will not be removed until Python
+%[- MARK -] +3.0. The functions defined in this module are:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{atof}{s}
+%[- MARK -] \deprecated{2.0}{Use the \function{float()} built-in function.}
+%[- MARK -] Convert a string to a floating point number. The string must have
+%[- MARK -] the standard syntax for a floating point literal in Python,
+%[- MARK -] END DIFF
\end{datadesc}
@@ -142,6 +332,30 @@
\begin{funcdesc}{capitalize}{parola}
Restituisce una copia della \var{parola} con soltanto il suo primo
carattere in maiuscolo.
+%[- MARK -] BEGIN DIFF 003 of 5
+%[- MARK -] @@ 136
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{capitalize}{word}
+%[- MARK -] Return a copy of \var{word} with only its first character capitalized.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{capwords}{s}
+%[- MARK -] - Split the argument into words using \function{split()}, capitalize
+%[- MARK -] - each word using \function{capitalize()}, and join the capitalized
+%[- MARK -] - words using \function{join()}. Note that this replaces runs of
+%[- MARK -] - whitespace characters by a single space, and removes leading and
+%[- MARK -] - trailing whitespace.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] \begin{funcdesc}{expandtabs}{s\optional{, tabsize}}
+%[- MARK -] - Expand tabs in a string, i.e.\ replace them by one or more spaces,
+%[- MARK -] + Expand tabs in a string replacing them by one or more spaces,
+%[- MARK -] depending on the current column and the given tab size. The column
+%[- MARK -] number is reset to zero after each newline occurring in the string.
+%[- MARK -] This doesn't understand other non-printing characters or escape
+%[- MARK -] sequences. The tab size defaults to 8.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{capwords}{s}
@@ -197,6 +411,31 @@
\begin{funcdesc}{lower}{s}
Restituisce una copia di \var{s}, ma con le lettere maiuscole
convertite in minuscole.
+%[- MARK -] BEGIN DIFF 004 of 5
+%[- MARK -] @@ 186
+%[- MARK -] \begin{funcdesc}{lower}{s}
+%[- MARK -] Return a copy of \var{s}, but with upper case letters converted to
+%[- MARK -] lower case.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{maketrans}{from, to}
+%[- MARK -] - Return a translation table suitable for passing to
+%[- MARK -] - \function{translate()} or \function{regex.compile()}, that will map
+%[- MARK -] - each character in \var{from} into the character at the same position
+%[- MARK -] - in \var{to}; \var{from} and \var{to} must have the same length.
+%[- MARK -] -
+%[- MARK -] - \warning{Don't use strings derived from \constant{lowercase}
+%[- MARK -] - and \constant{uppercase} as arguments; in some locales, these don't have
+%[- MARK -] - the same length. For case conversions, always use
+%[- MARK -] - \function{lower()} and \function{upper()}.}
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] \begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
+%[- MARK -] Return a list of the words of the string \var{s}. If the optional
+%[- MARK -] second argument \var{sep} is absent or \code{None}, the words are
+%[- MARK -] separated by arbitrary strings of whitespace characters (space, tab,
+%[- MARK -] newline, return, formfeed). If the second argument \var{sep} is
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{maketrans}{from, to}
@@ -282,6 +521,21 @@
questo metodo.
\versionchanged[Il parametro \var{chars} non può essere passato in
versioni precedenti alla 2.2]{2.2.3}
+%[- MARK -] BEGIN DIFF 005 of 5
+%[- MARK -] @@ 269
+%[- MARK -] \var{chars} is omitted or \code{None}, whitespace characters are
+%[- MARK -] removed. If given and not \code{None}, \var{chars} must be a string;
+%[- MARK -] the characters in the string will be stripped from the end of the
+%[- MARK -] string this method is called on.
+%[- MARK -] \versionchanged[The \var{chars} parameter was added. The \var{chars}
+%[- MARK -] -parameter cannot be passed in 2.2 versions]{2.2.3}
+%[- MARK -] +parameter cannot be passed in earlier 2.2 versions]{2.2.3}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{strip}{s\optional{, chars}}
+%[- MARK -] Return a copy of the string with leading and trailing characters
+%[- MARK -] removed. If \var{chars} is omitted or \code{None}, whitespace
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{rstrip}{s\optional{, chars}}
Modified: python/python/Doc/branches/2.4.3/lib/libstringio.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libstringio.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libstringio.tex Fri Jun 2 12:52:55 2006
@@ -8,6 +8,20 @@
Questo modulo implementa una classe simile a file, \class{StringIO}, che
legge e scrive un buffer stringa (anche conosciuto come
\emph{file di memoria}). Vedete la descrizione degli oggetti file per
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 12
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{StringIO}{\optional{buffer}}
+%[- MARK -] When a \class{StringIO} object is created, it can be initialized
+%[- MARK -] to an existing string by passing the string to the constructor.
+%[- MARK -] If no string is given, the \class{StringIO} will start empty.
+%[- MARK -] +In both cases, the initial file position starts at zero.
+%[- MARK -]
+%[- MARK -] The \class{StringIO} object can accept either Unicode or 8-bit
+%[- MARK -] strings, but mixing the two may take some care. If both are used,
+%[- MARK -] 8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that
+%[- MARK -] use the 8th bit) will cause a \exception{UnicodeError} to be raised
+%[- MARK -] END DIFF
le operazioni (sezione \ref{bltin-file-objects}).
\begin{classdesc}{StringIO}{\optional{buffer}}
Added: python/python/Doc/branches/2.4.3/lib/libsubprocess.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libsubprocess.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,391 @@
+%[- MARK -] BEGIN PART 001 of 4
+\section{\module{subprocess} --- Subprocess management}
+
+\declaremodule{standard}{subprocess}
+\modulesynopsis{Subprocess management.}
+\moduleauthor{Peter \AA strand}{astrand a lysator.liu.se}
+\sectionauthor{Peter \AA strand}{astrand a lysator.liu.se}
+
+\versionadded{2.4}
+
+The \module{subprocess} module allows you to spawn new processes,
+connect to their input/output/error pipes, and obtain their return
+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*
+os.popen*
+popen2.*
+commands.*
+\end{verbatim}
+
+Information about how the \module{subprocess} module can be used to
+replace these modules and functions can be found in the following
+sections.
+
+\subsection{Using the subprocess Module}
+
+This module defines one class called \class{Popen}:
+
+\begin{classdesc}{Popen}{args, bufsize=0, executable=None,
+ stdin=None, stdout=None, stderr=None,
+ preexec_fn=None, close_fds=False, shell=False,
+ cwd=None, env=None, universal_newlines=False,
+ startupinfo=None, creationflags=0}
+
+Arguments are:
+
+\var{args} should be a string, or a sequence of program arguments. The
+program to execute is normally the first item in the args sequence or
+string, but can be explicitly set by using the executable argument.
+
+On \UNIX{}, with \var{shell=False} (default): In this case, the Popen
+class uses \method{os.execvp()} to execute the child program.
+\var{args} should normally be a sequence. A string will be treated as a
+sequence with the string as the only item (the program to execute).
+
+On \UNIX{}, with \var{shell=True}: If args is a string, it specifies the
+command string to execute through the shell. If \var{args} is a
+sequence, the first item specifies the command string, and any
+additional items will be treated as additional shell arguments.
+
+On Windows: the \class{Popen} class uses CreateProcess() to execute
+the child program, which operates on strings. If \var{args} is a
+sequence, it will be converted to a string using the
+\method{list2cmdline} method. Please note that not all MS Windows
+applications interpret the command line the same way:
+\method{list2cmdline} is designed for applications using the same
+rules as the MS C runtime.
+
+\var{bufsize}, if given, has the same meaning as the corresponding
+argument to the built-in open() function: \constant{0} means unbuffered,
+\constant{1} means line buffered, any other positive value means use a
+buffer of (approximately) that size. A negative \var{bufsize} means to
+use the system default, which usually means fully buffered. The default
+value for \var{bufsize} is \constant{0} (unbuffered).
+
+The \var{executable} argument specifies the program to execute. It is
+very seldom needed: Usually, the program to execute is defined by the
+\var{args} argument. If \var{shell=True}, the \var{executable}
+argument specifies which shell to use. On \UNIX{}, the default shell
+is /bin/sh. On Windows, the default shell is specified by the COMSPEC
+environment variable.
+
+\var{stdin}, \var{stdout} and \var{stderr} specify the executed
+programs' standard input, standard output and standard error file
+handles, respectively. Valid values are \code{PIPE}, an existing file
+descriptor (a positive integer), an existing file object, and
+\code{None}. \code{PIPE} indicates that a new pipe to the child
+should be created. With \code{None}, no redirection will occur; the
+child's file handles will be inherited from the parent. Additionally,
+\var{stderr} can be \code{STDOUT}, which indicates that the stderr
+data from the applications should be captured into the same file
+handle as for stdout.
+
+If \var{preexec_fn} is set to a callable object, this object will be
+called in the child process just before the child is executed.
+
+If \var{close_fds} is true, all file descriptors except \constant{0},
+\constant{1} and \constant{2} will be closed before the child process is
+executed.
+
+If \var{shell} is \constant{True}, the specified command will be
+executed through the shell.
+
+If \var{cwd} is not \code{None}, the current directory will be changed
+to cwd before the child is executed.
+%[- MARK -] BEGIN PART 002 of 4
+
+If \var{env} is not \code{None}, it defines the environment variables
+for the new process.
+
+If \var{universal_newlines} is \constant{True}, the file objects stdout
+and stderr are opened as text files, but lines may be terminated by
+any of \code{'\e n'}, the Unix end-of-line convention, \code{'\e r'},
+the Macintosh convention or \code{'\e r\e n'}, the Windows convention.
+All of these external representations are seen as \code{'\e n'} by the
+Python program. \note{This feature is only available if Python is built
+with universal newline support (the default). Also, the newlines
+attribute of the file objects \member{stdout}, \member{stdin} and
+\member{stderr} are not updated by the communicate() method.}
+
+The \var{startupinfo} and \var{creationflags}, if given, will be
+passed to the underlying CreateProcess() function. They can specify
+things such as appearance of the main window and priority for the new
+process. (Windows only)
+\end{classdesc}
+
+\subsubsection{Convenience Functions}
+
+This module also defines one shortcut function:
+
+\begin{funcdesc}{call}{*args, **kwargs}
+Run command with arguments. Wait for command to complete, then
+return the \member{returncode} attribute.
+
+The arguments are the same as for the Popen constructor. Example:
+
+\begin{verbatim}
+ retcode = call(["ls", "-l"])
+\end{verbatim}
+\end{funcdesc}
+
+
+\subsubsection{Exceptions}
+
+Exceptions raised in the child process, before the new program has
+started to execute, will be re-raised in the parent. Additionally,
+the exception object will have one extra attribute called
+\member{child_traceback}, which is a string containing traceback
+information from the childs point of view.
+
+The most common exception raised is \exception{OSError}. This occurs,
+for example, when trying to execute a non-existent file. Applications
+should prepare for \exception{OSError} exceptions.
+
+A \exception{ValueError} will be raised if \class{Popen} is called
+with invalid arguments.
+
+
+\subsubsection{Security}
+
+Unlike some other popen functions, this implementation will never call
+/bin/sh implicitly. This means that all characters, including shell
+metacharacters, can safely be passed to child processes.
+
+
+\subsection{Popen Objects}
+
+Instances of the \class{Popen} class have the following methods:
+
+\begin{methoddesc}{poll}{}
+Check if child process has terminated. Returns returncode
+attribute.
+\end{methoddesc}
+
+\begin{methoddesc}{wait}{}
+Wait for child process to terminate. Returns returncode attribute.
+\end{methoddesc}
+
+\begin{methoddesc}{communicate}{input=None}
+Interact with process: Send data to stdin. Read data from stdout and
+stderr, until end-of-file is reached. Wait for process to terminate.
+The optional \var{input} argument should be a string to be sent to the
+child process, or \code{None}, if no data should be sent to the child.
+
+communicate() returns a tuple (stdout, stderr).
+
+\note{The data read is buffered in memory, so do not use this method
+if the data size is large or unlimited.}
+\end{methoddesc}
+
+The following attributes are also available:
+
+\begin{memberdesc}{stdin}
+If the \var{stdin} argument is \code{PIPE}, this attribute is a file
+object that provides input to the child process. Otherwise, it is
+\code{None}.
+\end{memberdesc}
+
+\begin{memberdesc}{stdout}
+If the \var{stdout} argument is \code{PIPE}, this attribute is a file
+object that provides output from the child process. Otherwise, it is
+\code{None}.
+\end{memberdesc}
+
+\begin{memberdesc}{stderr}
+If the \var{stderr} argument is \code{PIPE}, this attribute is file
+%[- MARK -] BEGIN PART 003 of 4
+object that provides error output from the child process. Otherwise,
+it is \code{None}.
+\end{memberdesc}
+
+\begin{memberdesc}{pid}
+The process ID of the child process.
+\end{memberdesc}
+
+\begin{memberdesc}{returncode}
+The child return code. A \code{None} value indicates that the process
+hasn't terminated yet. A negative value -N indicates that the child
+was terminated by signal N (\UNIX{} only).
+\end{memberdesc}
+
+
+\subsection{Replacing Older Functions with the subprocess Module}
+
+In this section, "a ==> b" means that b can be used as a replacement
+for a.
+
+\note{All functions in this section fail (more or less) silently if
+the executed program cannot be found; this module raises an
+\exception{OSError} exception.}
+
+In the following examples, we assume that the subprocess module is
+imported with "from subprocess import *".
+
+\subsubsection{Replacing /bin/sh shell backquote}
+
+\begin{verbatim}
+output=`mycmd myarg`
+==>
+output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
+\end{verbatim}
+
+\subsubsection{Replacing shell pipe line}
+
+\begin{verbatim}
+output=`dmesg | grep hda`
+==>
+p1 = Popen(["dmesg"], stdout=PIPE)
+p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
+output = p2.communicate()[0]
+\end{verbatim}
+
+\subsubsection{Replacing os.system()}
+
+\begin{verbatim}
+sts = os.system("mycmd" + " myarg")
+==>
+p = Popen("mycmd" + " myarg", shell=True)
+sts = os.waitpid(p.pid, 0)
+\end{verbatim}
+
+Notes:
+
+\begin{itemize}
+\item Calling the program through the shell is usually not required.
+\item It's easier to look at the \member{returncode} attribute than
+ the exit status.
+\end{itemize}
+
+A more realistic example would look like this:
+
+\begin{verbatim}
+try:
+ retcode = call("mycmd" + " myarg", shell=True)
+ if retcode < 0:
+ print >>sys.stderr, "Child was terminated by signal", -retcode
+ else:
+ print >>sys.stderr, "Child returned", retcode
+except OSError, e:
+ print >>sys.stderr, "Execution failed:", e
+\end{verbatim}
+
+\subsubsection{Replacing os.spawn*}
+
+P_NOWAIT example:
+
+\begin{verbatim}
+pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
+==>
+pid = Popen(["/bin/mycmd", "myarg"]).pid
+\end{verbatim}
+
+P_WAIT example:
+
+\begin{verbatim}
+retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
+==>
+retcode = call(["/bin/mycmd", "myarg"])
+\end{verbatim}
+
+Vector example:
+
+\begin{verbatim}
+os.spawnvp(os.P_NOWAIT, path, args)
+==>
+Popen([path] + args[1:])
+\end{verbatim}
+%[- MARK -] BEGIN PART 004 of 4
+
+Environment example:
+
+\begin{verbatim}
+os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
+==>
+Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
+\end{verbatim}
+
+\subsubsection{Replacing os.popen*}
+
+\begin{verbatim}
+pipe = os.popen(cmd, mode='r', bufsize)
+==>
+pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
+\end{verbatim}
+
+\begin{verbatim}
+pipe = os.popen(cmd, mode='w', bufsize)
+==>
+pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
+\end{verbatim}
+
+\begin{verbatim}
+(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
+==>
+p = Popen(cmd, shell=True, bufsize=bufsize,
+ stdin=PIPE, stdout=PIPE, close_fds=True)
+(child_stdin, child_stdout) = (p.stdin, p.stdout)
+\end{verbatim}
+
+\begin{verbatim}
+(child_stdin,
+ child_stdout,
+ child_stderr) = os.popen3(cmd, mode, bufsize)
+==>
+p = Popen(cmd, shell=True, bufsize=bufsize,
+ stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
+(child_stdin,
+ child_stdout,
+ child_stderr) = (p.stdin, p.stdout, p.stderr)
+\end{verbatim}
+
+\begin{verbatim}
+(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
+==>
+p = Popen(cmd, shell=True, bufsize=bufsize,
+ stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
+(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
+\end{verbatim}
+
+\subsubsection{Replacing popen2.*}
+
+\note{If the cmd argument to popen2 functions is a string, the command
+is executed through /bin/sh. If it is a list, the command is directly
+executed.}
+
+\begin{verbatim}
+(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
+==>
+p = Popen(["somestring"], shell=True, bufsize=bufsize,
+ stdin=PIPE, stdout=PIPE, close_fds=True)
+(child_stdout, child_stdin) = (p.stdout, p.stdin)
+\end{verbatim}
+
+\begin{verbatim}
+(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
+==>
+p = Popen(["mycmd", "myarg"], bufsize=bufsize,
+ stdin=PIPE, stdout=PIPE, close_fds=True)
+(child_stdout, child_stdin) = (p.stdout, p.stdin)
+\end{verbatim}
+
+The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen,
+except that:
+
+\begin{itemize}
+\item subprocess.Popen raises an exception if the execution fails
+
+\item the \var{capturestderr} argument is replaced with the \var{stderr}
+ argument.
+
+\item stdin=PIPE and stdout=PIPE must be specified.
+
+\item popen2 closes all file descriptors by default, but you have to
+ specify close_fds=True with subprocess.Popen.
+\end{itemize}
Modified: python/python/Doc/branches/2.4.3/lib/libtempfile.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtempfile.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtempfile.tex Fri Jun 2 12:52:55 2006
@@ -154,6 +154,20 @@
e a nessuna delle funzioni precedenti, Python cerca una lista standard
di directory ed imposta \var{tempdir} alla prima directory nella quale
l'utente che effettua la chiamata abbia il permesso di creare dei file.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 144
+%[- MARK -] \item The directory named by the \envvar{TMPDIR} environment variable.
+%[- MARK -] \item The directory named by the \envvar{TEMP} environment variable.
+%[- MARK -] \item The directory named by the \envvar{TMP} environment variable.
+%[- MARK -] \item A platform-specific location:
+%[- MARK -] \begin{itemize}
+%[- MARK -] - \item On Macintosh, the \file{Temporary Items} folder.
+%[- MARK -] \item On RiscOS, the directory named by the
+%[- MARK -] \envvar{Wimp\$ScrapDir} environment variable.
+%[- MARK -] \item On Windows, the directories
+%[- MARK -] \file{C:$\backslash$TEMP},
+%[- MARK -] \file{C:$\backslash$TMP},
+%[- MARK -] END DIFF
La lista è:
\begin{enumerate}
Modified: python/python/Doc/branches/2.4.3/lib/libtermios.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtermios.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtermios.tex Fri Jun 2 12:52:55 2006
@@ -94,6 +94,35 @@
una chiamata separata a \function{tcgetattr()} e un'istruzione
\keyword{try} ... \keyword{finally} per assicurarsi che siano
ripristinati esattamente i vecchi attributi tty, senza riguardo a
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 102
+%[- MARK -] passwd = raw_input(prompt)
+%[- MARK -] finally:
+%[- MARK -] termios.tcsetattr(fd, termios.TCSADRAIN, old)
+%[- MARK -] return passwd
+%[- MARK -] \end{verbatim}
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\section{\module{TERMIOS} ---
+%[- MARK -] - Constants used with the \module{termios} module}
+%[- MARK -] -
+%[- MARK -] -\declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
+%[- MARK -] - \platform{Unix}
+%[- MARK -] -\modulesynopsis{Symbolic constants required to use the
+%[- MARK -] - \module{termios} module.}
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\indexii{\POSIX}{I/O control}
+%[- MARK -] -\indexii{tty}{I/O control}
+%[- MARK -] -
+%[- MARK -] -\deprecated{2.1}{Import needed constants from \refmodule{termios}
+%[- MARK -] - instead.}
+%[- MARK -] -
+%[- MARK -] -This module defines the symbolic constants required to use the
+%[- MARK -] -\refmodule{termios}\refbimodindex{termios} module (see the previous
+%[- MARK -] -section). See the \POSIX{} or \UNIX{} manual pages for a list of
+%[- MARK -] -those constants.
+%[- MARK -] END DIFF
quanto avviene:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libtextwrap.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtextwrap.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtextwrap.tex Fri Jun 2 12:52:55 2006
@@ -99,6 +99,21 @@
siano parole individuali più lunghe di \member{width},
\class{TextWrapper} garantisce che non vengano mandate in output delle
righe più lunghe di \member{width} caratteri.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 95
+%[- MARK -] will be longer than \member{width} characters.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{expand_tabs}
+%[- MARK -] (default: \code{True}) If true, then all tab characters in \var{text}
+%[- MARK -] -will be expanded to spaces using the \method{expand_tabs()} method of
+%[- MARK -] +will be expanded to spaces using the \method{expandtabs()} method of
+%[- MARK -] \var{text}.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{replace_whitespace}
+%[- MARK -] (default: \code{True}) If true, each whitespace character (as defined
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{memberdesc}{expand_tabs}
Modified: python/python/Doc/branches/2.4.3/lib/libthread.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libthread.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libthread.tex Fri Jun 2 12:52:55 2006
@@ -79,6 +79,26 @@
\end{funcdesc}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 79
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
+%[- MARK -] Without the optional argument, this method acquires the lock
+%[- MARK -] unconditionally, if necessary waiting until it is released by another
+%[- MARK -] thread (only one thread at a time can acquire a lock --- that's their
+%[- MARK -] -reason for existence), and returns \code{None}. If the integer
+%[- MARK -] +reason for existence). If the integer
+%[- MARK -] \var{waitflag} argument is present, the action depends on its
+%[- MARK -] value: if it is zero, the lock is only acquired if it can be acquired
+%[- MARK -] immediately without waiting, while if it is nonzero, the lock is
+%[- MARK -] -acquired unconditionally as before. If an argument is present, the
+%[- MARK -] +acquired unconditionally as before. The
+%[- MARK -] return value is \code{True} if the lock is acquired successfully,
+%[- MARK -] \code{False} if not.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[lock]{release}{}
+%[- MARK -] END DIFF
Gli oggetti lock hanno i seguenti metodi:
\begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
Modified: python/python/Doc/branches/2.4.3/lib/libthreading.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libthreading.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libthreading.tex Fri Jun 2 12:52:55 2006
@@ -48,6 +48,38 @@
gestisce una opzione che può essere impostata a vero con il metodo
\method{set()} e resettata a falso con il metodo \method{clear()}. Il
metodo \method{wait()} si bloccca fino a che l'opzione è vera.
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 47
+%[- MARK -] a flag that can be set to true with the \method{set()} method and
+%[- MARK -] reset to false with the \method{clear()} method. The \method{wait()}
+%[- MARK -] method blocks until the flag is true.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{classdesc*}{local}{}
+%[- MARK -] +A class that represents thread-local data. Thread-local data are data
+%[- MARK -] +whose values are thread specific. To manage thread-local data, just
+%[- MARK -] +create an instance of \class{local} (or a subclass) and store
+%[- MARK -] +attributes on it:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +mydata = threading.local()
+%[- MARK -] +mydata.x = 1
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +The instance's values will be different for separate threads.
+%[- MARK -] +
+%[- MARK -] +For more details and extensive examples, see the documentation string
+%[- MARK -] +of the \module{_threading_local} module.
+%[- MARK -] +
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{classdesc*}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{Lock}{}
+%[- MARK -] A factory function that returns a new primitive lock object. Once
+%[- MARK -] a thread has acquired it, subsequent attempts to acquire it block,
+%[- MARK -] until it is released; any thread may release it.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{Lock}{}
@@ -153,6 +185,22 @@
Tutti i metodi sono eseguiti atomicamente.
\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 146
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
+%[- MARK -] Acquire a lock, blocking or non-blocking.
+%[- MARK -]
+%[- MARK -] When invoked without arguments, block until the lock is
+%[- MARK -] -unlocked, then set it to locked, and return. There is no
+%[- MARK -] -return value in this case.
+%[- MARK -] +unlocked, then set it to locked, and return true.
+%[- MARK -]
+%[- MARK -] When invoked with the \var{blocking} argument set to true, do the
+%[- MARK -] same thing as when called without arguments, and return true.
+%[- MARK -]
+%[- MARK -] When invoked with the \var{blocking} argument set to false, do not
+%[- MARK -] END DIFF
Acquisisce un lock, bloccante o non bloccante.
Quando viene invocato senza argomenti, si blocca fino a che il lock è
@@ -596,6 +644,26 @@
Questo blocca il thread chiamante
fino a che termini il thread il cui metodo \method{join()} è stato
chiamato -- normalmente, o attraverso un'eccezione non gestita -- o
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 574
+%[- MARK -] method is called terminates -- either normally or through an
+%[- MARK -] unhandled exception -- or until the optional timeout occurs.
+%[- MARK -]
+%[- MARK -] When the \var{timeout} argument is present and not \code{None}, it
+%[- MARK -] should be a floating point number specifying a timeout for the
+%[- MARK -] -operation in seconds (or fractions thereof).
+%[- MARK -] +operation in seconds (or fractions thereof). As \method{join()} always
+%[- MARK -] +returns \code{None}, you must call \method{isAlive()} to decide whether
+%[- MARK -] +a timeout happened.
+%[- MARK -] +
+%[- MARK -] +When the \var{timeout} argument is not present or \code{None}, the
+%[- MARK -] +operation will block until the thread terminates.
+%[- MARK -]
+%[- MARK -] A thread can be \method{join()}ed many times.
+%[- MARK -]
+%[- MARK -] A thread cannot join itself because this would cause a
+%[- MARK -] deadlock.
+%[- MARK -] END DIFF
fino a che sopravvenga il timeout facoltativo.
Quando l'argomento \var{timeout} è presente e diverso da \code{None},
Modified: python/python/Doc/branches/2.4.3/lib/libtime.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtime.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtime.tex Fri Jun 2 12:52:55 2006
@@ -169,6 +169,61 @@
virgola mobile, basato sulla funzione Win32
\cfunction{QueryPerformanceCounter()}. La risoluzione tipicamente è
migliore di un microsecondo.
+%[- MARK -] BEGIN DIFF 001 of 6
+%[- MARK -] @@ 155
+%[- MARK -] The resolution is typically better than one microsecond.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{ctime}{\optional{secs}}
+%[- MARK -] Convert a time expressed in seconds since the epoch to a string
+%[- MARK -] -representing local time. If \var{secs} is not provided, the current time
+%[- MARK -] -as returned by \function{time()} is used. \code{ctime(\var{secs})}
+%[- MARK -] -is equivalent to \code{asctime(localtime(\var{secs}))}.
+%[- MARK -] +representing local time. If \var{secs} is not provided or
+%[- MARK -] +\constant{None}, the current time as returned by \function{time()} is
+%[- MARK -] +used. \code{ctime(\var{secs})} is equivalent to
+%[- MARK -] +\code{asctime(localtime(\var{secs}))}.
+%[- MARK -] Locale information is not used by \function{ctime()}.
+%[- MARK -] \versionchanged[Allowed \var{secs} to be omitted]{2.1}
+%[- MARK -] +\versionchanged[If \var{secs} is \constant{None}, the current time is
+%[- MARK -] + used]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{daylight}
+%[- MARK -] Nonzero if a DST timezone is defined.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{gmtime}{\optional{secs}}
+%[- MARK -] Convert a time expressed in seconds since the epoch to a \class{struct_time}
+%[- MARK -] in UTC in which the dst flag is always zero. If \var{secs} is not
+%[- MARK -] -provided, the current time as returned by \function{time()} is used.
+%[- MARK -] -Fractions of a second are ignored. See above for a description of the
+%[- MARK -] -\class{struct_time} object.
+%[- MARK -] +provided or \constant{None}, the current time as returned by
+%[- MARK -] +\function{time()} is used. Fractions of a second are ignored. See
+%[- MARK -] +above for a description of the \class{struct_time} object. See
+%[- MARK -] +\function{calendar.timegm()} for the inverse of this function.
+%[- MARK -] \versionchanged[Allowed \var{secs} to be omitted]{2.1}
+%[- MARK -] +\versionchanged[If \var{secs} is \constant{None}, the current time is
+%[- MARK -] + used]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{localtime}{\optional{secs}}
+%[- MARK -] -Like \function{gmtime()} but converts to local time. The dst flag is
+%[- MARK -] -set to \code{1} when DST applies to the given time.
+%[- MARK -] +Like \function{gmtime()} but converts to local time. If \var{secs} is
+%[- MARK -] +not provided or \constant{None}, the current time as returned by
+%[- MARK -] +\function{time()} is used. The dst flag is set to \code{1} when DST
+%[- MARK -] +applies to the given time.
+%[- MARK -] \versionchanged[Allowed \var{secs} to be omitted]{2.1}
+%[- MARK -] +\versionchanged[If \var{secs} is \constant{None}, the current time is
+%[- MARK -] + used]{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{mktime}{t}
+%[- MARK -] This is the inverse function of \function{localtime()}. Its argument
+%[- MARK -] is the \class{struct_time} or full 9-tuple (since the dst flag is
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{ctime}{\optional{secs}}
@@ -225,6 +280,22 @@
intercettazione del segnale. Inoltre, il tempo di sospensione
potrebbe essere maggiore di quello richiesto di una quantità
arbitraria, a seguito della schedulazione di altre attività nel sistema.
+%[- MARK -] BEGIN DIFF 002 of 6
+%[- MARK -] @@ 213
+%[- MARK -] provided, the current time as returned by \function{localtime()} is
+%[- MARK -] used. \var{format} must be a string. \exception{ValueError} is raised
+%[- MARK -] if any field in \var{t} is outside of the allowed range.
+%[- MARK -] \versionchanged[Allowed \var{t} to be omitted]{2.1}
+%[- MARK -] \versionchanged[\exception{ValueError} raised if a field in \var{t} is
+%[- MARK -] -out of range.]{2.4}
+%[- MARK -] +out of range]{2.4}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] The following directives can be embedded in the \var{format} string.
+%[- MARK -] They are shown without the optional field width and precision
+%[- MARK -] specification, and are replaced by the indicated characters in the
+%[- MARK -] \function{strftime()} result:
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{strftime}{format\optional{, t}}
@@ -242,6 +313,26 @@
Le seguenti direttive possono venire inserite nella stringa
\var{format}. Vengono mostrate senza specificare il campo facoltativo
di ampiezza e precisione, e vengono sostituite dai caratteri indicati
+%[- MARK -] BEGIN DIFF 003 of 6
+%[- MARK -] @@ 236
+%[- MARK -] \lineiii{\%M}{Minute as a decimal number [00,59].}{}
+%[- MARK -] \lineiii{\%p}{Locale's equivalent of either AM or PM.}{(1)}
+%[- MARK -] \lineiii{\%S}{Second as a decimal number [00,61].}{(2)}
+%[- MARK -] \lineiii{\%U}{Week number of the year (Sunday as the first day of the
+%[- MARK -] week) as a decimal number [00,53]. All days in a new year
+%[- MARK -] - preceding the first Sunday are considered to be in week 0.}{}
+%[- MARK -] + preceding the first Sunday are considered to be in week 0.}{(3)}
+%[- MARK -] \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
+%[- MARK -] \lineiii{\%W}{Week number of the year (Monday as the first day of the
+%[- MARK -] week) as a decimal number [00,53]. All days in a new year
+%[- MARK -] - preceding the first Monday are considered to be in week 0.}{}
+%[- MARK -] + preceding the first Monday are considered to be in week 0.}{(3)}
+%[- MARK -] \lineiii{\%x}{Locale's appropriate date representation.}{}
+%[- MARK -] \lineiii{\%X}{Locale's appropriate time representation.}{}
+%[- MARK -] \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
+%[- MARK -] \lineiii{\%Y}{Year with century as a decimal number.}{}
+%[- MARK -] \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
+%[- MARK -] END DIFF
nel risultato di \function{strftime()}.
\begin{tableiii}{c|p{24em}|c}{code}{Direttiva}{Significato}{Note}
@@ -283,6 +374,23 @@
\end{tableiii}
\noindent
+%[- MARK -] BEGIN DIFF 004 of 6
+%[- MARK -] @@ 260
+%[- MARK -] directive only affects the output hour field if the \code{\%I} directive
+%[- MARK -] is used to parse the hour.
+%[- MARK -] \item[(2)]
+%[- MARK -] The range really is \code{0} to \code{61}; this accounts for leap
+%[- MARK -] seconds and the (very rare) double leap seconds.
+%[- MARK -] + \item[(3)]
+%[- MARK -] + When used with the \function{strptime()} function, \code{\%U} and \code{\%W}
+%[- MARK -] + are only used in calculations when the day of the week and the year are
+%[- MARK -] + specified.
+%[- MARK -] \end{description}
+%[- MARK -]
+%[- MARK -] Here is an example, a format for dates compatible with that specified
+%[- MARK -] in the \rfc{2822} Internet email standard.
+%[- MARK -] \footnote{The use of \code{\%Z} is now
+%[- MARK -] END DIFF
Note:
\begin{description}
@@ -322,6 +430,21 @@
portabile.
L'ampiezza per il campo è normalmente 2, ad eccezione di \code{\%j}
in cui è 3.
+%[- MARK -] BEGIN DIFF 005 of 6
+%[- MARK -] @@ 297
+%[- MARK -] \code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
+%[- MARK -] returned by \function{ctime()}. If \var{string} cannot be parsed
+%[- MARK -] according to \var{format}, \exception{ValueError} is raised. If the
+%[- MARK -] string to be parsed has excess data after parsing,
+%[- MARK -] \exception{ValueError} is raised. The default values used to fill in
+%[- MARK -] -any missing data is \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
+%[- MARK -] +any missing data are \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
+%[- MARK -]
+%[- MARK -] Support for the \code{\%Z} directive is based on the values contained in
+%[- MARK -] \code{tzname} and whether \code{daylight} is true. Because of this,
+%[- MARK -] it is platform-specific except for recognizing UTC and GMT which are
+%[- MARK -] always known (and are considered to be non-daylight savings
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{strptime}{string\optional{, format}}
@@ -397,6 +520,29 @@
\item[std offset [dst [offset] [,start[/time], end[/time]]]]
\end{itemize}
+%[- MARK -] BEGIN DIFF 006 of 6
+%[- MARK -] @@ 359
+%[- MARK -] Where:
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -] \item[std and dst]
+%[- MARK -] Three or more alphanumerics giving the timezone abbreviations.
+%[- MARK -] - These will be propogated into time.tzname
+%[- MARK -] + These will be propagated into time.tzname
+%[- MARK -]
+%[- MARK -] \item[offset]
+%[- MARK -] The offset has the form: \plusminus{} hh[:mm[:ss]].
+%[- MARK -] This indicates the value added the local time to arrive at UTC.
+%[- MARK -] If preceded by a '-', the timezone is east of the Prime
+%[- MARK -] Meridian; otherwise, it is west. If no offset follows
+%[- MARK -] - dst, summmer time is assumed to be one hour ahead of standard time.
+%[- MARK -] + dst, summer time is assumed to be one hour ahead of standard time.
+%[- MARK -]
+%[- MARK -] \item[start[/time],end[/time]]
+%[- MARK -] Indicates when to change to and back from DST. The format of the
+%[- MARK -] start and end dates are one of the following:
+%[- MARK -]
+%[- MARK -] END DIFF
Dove:
\begin{itemize}
Modified: python/python/Doc/branches/2.4.3/lib/libtraceback.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtraceback.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtraceback.tex Fri Jun 2 12:52:55 2006
@@ -50,6 +50,21 @@
per recuperare le stesse informazioni in modalità threadsafe (NdT: di
sicuro utilizzo con i thread) invece di usare le variabili
deprecate.)
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 46
+%[- MARK -] fact, it uses \function{sys.exc_info()} to retrieve the same
+%[- MARK -] information in a thread-safe way instead of using the deprecated
+%[- MARK -] variables.)
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{format_exc}{\optional{limit\optional{, file}}}
+%[- MARK -] +\begin{funcdesc}{format_exc}{\optional{limit}}
+%[- MARK -] This is like \code{print_exc(\var{limit})} but returns a string
+%[- MARK -] instead of printing to a file.
+%[- MARK -] \versionadded{2.4}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{format_exc}{\optional{limite\optional{, file}}}
Modified: python/python/Doc/branches/2.4.3/lib/libtty.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtty.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtty.tex Fri Jun 2 12:52:55 2006
@@ -14,6 +14,32 @@
\module{tty} richiede il modulo \refmodule{termios}, percui funzionerà
solamente sui sistemi \UNIX.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 16
+%[- MARK -]
+%[- MARK -] The \module{tty} module defines the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{setraw}{fd\optional{, when}}
+%[- MARK -] Change the mode of the file descriptor \var{fd} to raw. If \var{when}
+%[- MARK -] -is omitted, it defaults to \constant{TERMIOS.TCAFLUSH}, and is passed
+%[- MARK -] +is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
+%[- MARK -] to \function{termios.tcsetattr()}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{setcbreak}{fd\optional{, when}}
+%[- MARK -] Change the mode of file descriptor \var{fd} to cbreak. If \var{when}
+%[- MARK -] -is omitted, it defaults to \constant{TERMIOS.TCAFLUSH}, and is passed
+%[- MARK -] +is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
+%[- MARK -] to \function{termios.tcsetattr()}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seemodule{termios}{Low-level terminal control interface.}
+%[- MARK -] - \seemodule[TERMIOSuppercase]{TERMIOS}{Constants useful for terminal
+%[- MARK -] - control operations.}
+%[- MARK -] \end{seealso}
+%[- MARK -] END DIFF
Il modulo \module{tty} definisce le seguenti funzioni:
\begin{funcdesc}{setraw}{fd\optional{, when}}
Modified: python/python/Doc/branches/2.4.3/lib/libtypes.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libtypes.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libtypes.tex Fri Jun 2 12:52:55 2006
@@ -2,6 +2,21 @@
Nomi per i tipi built-in}
\declaremodule{standard}{types}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 6
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] This module defines names for some object types that are used by
+%[- MARK -] the standard Python interpreter, but not for the types defined by various
+%[- MARK -] extension modules. Also, it does not include some of the types that
+%[- MARK -] -arise during processing such the \code{listiterator} type.
+%[- MARK -] +arise during processing such as the \code{listiterator} type.
+%[- MARK -] It is safe to use \samp{from types import *} ---
+%[- MARK -] the module does not export any names besides the ones listed here.
+%[- MARK -] New names exported by future versions of this module will all end in
+%[- MARK -] \samp{Type}.
+%[- MARK -]
+%[- MARK -] END DIFF
\modulesynopsis{Nomi per i tipi built-in.}
Modified: python/python/Doc/branches/2.4.3/lib/libundoc.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libundoc.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libundoc.tex Fri Jun 2 12:52:55 2006
@@ -13,6 +13,24 @@
\section{Frameworks}
I framework sono difficili da documentare, ma ripagano dello sforzo
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 13
+%[- MARK -]
+%[- MARK -] Frameworks tend to be harder to document, but are well worth the
+%[- MARK -] effort spent.
+%[- MARK -]
+%[- MARK -] \begin{description}
+%[- MARK -] -\item[\module{test}]
+%[- MARK -] ---- Regression testing framework. This is used for the Python
+%[- MARK -] -regression test, but is useful for other Python libraries as well.
+%[- MARK -] -This is a package rather than a single module.
+%[- MARK -] +\item None at this time.
+%[- MARK -] \end{description}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \section{Miscellaneous useful utilities}
+%[- MARK -]
+%[- MARK -] END DIFF
fatto.
\begin{description}
@@ -29,6 +47,35 @@
\begin{description}
\item[\module{bdb}]
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 30
+%[- MARK -] \item[\module{bdb}]
+%[- MARK -] --- A generic Python debugger base class (used by pdb).
+%[- MARK -]
+%[- MARK -] \item[\module{ihooks}]
+%[- MARK -] --- Import hook support (for \refmodule{rexec}; may become obsolete).
+%[- MARK -] -
+%[- MARK -] -\item[\module{platform}]
+%[- MARK -] ---- This module tries to retrieve as much platform identifying data as
+%[- MARK -] -possible. It makes this information available via function APIs.
+%[- MARK -] -If called from the command line, it prints the platform information
+%[- MARK -] -concatenated as single string to \code{sys.stdout}. The output format
+%[- MARK -] -is useable as part of a filename.
+%[- MARK -] -\versionadded{2.3}
+%[- MARK -] -
+%[- MARK -] -\item[\module{smtpd}]
+%[- MARK -] ---- An SMTP daemon implementation which meets the minimum requirements
+%[- MARK -] -for \rfc{821} conformance.
+%[- MARK -] \end{description}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] +
+%[- MARK -] \section{Platform specific modules}
+%[- MARK -]
+%[- MARK -] These modules are used to implement the \refmodule{os.path} module,
+%[- MARK -] and are not documented beyond this mention. There's little need to
+%[- MARK -] document these.
+%[- MARK -] END DIFF
--- Una classe generica base di debugger per Python (utilizzata da pdb).
\item[\module{ihooks}]
@@ -83,6 +130,23 @@
\item[\module{sunaudio}]
--- Interpreta le intestazioni audio Sun (può diventare obsoleto o un
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 82
+%[- MARK -] --- Interpret Sun audio headers (may become obsolete or a tool/demo).
+%[- MARK -]
+%[- MARK -] \item[\module{toaiff}]
+%[- MARK -] --- Convert "arbitrary" sound files to AIFF files; should probably
+%[- MARK -] become a tool or demo. Requires the external program \program{sox}.
+%[- MARK -] -
+%[- MARK -] -\item[\module{ossaudiodev}]
+%[- MARK -] ---- Play audio data via the Open Sound System API. This is usable on
+%[- MARK -] -Linux, some flavors of BSD, and some commercial \UNIX{} platforms.
+%[- MARK -] \end{description}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \section{Obsolete \label{obsolete-modules}}
+%[- MARK -]
+%[- MARK -] END DIFF
tool/demo).
\item[\module{toaiff}]
@@ -225,6 +289,24 @@
\item[\module{ni}]
--- Importa i moduli in ``packages.'' Il supporto basilare per i
package adesso è built-in. Il supporto built-in è molto simile a
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 214
+%[- MARK -] built in. The built-in support is very similar to what is provided in
+%[- MARK -] this module.
+%[- MARK -]
+%[- MARK -] \item[\module{rand}]
+%[- MARK -] --- Old interface to the random number generator.
+%[- MARK -] -
+%[- MARK -] -\item[\module{soundex}]
+%[- MARK -] ---- Algorithm for collapsing names which sound similar to a shared
+%[- MARK -] -key. The specific algorithm doesn't seem to match any published
+%[- MARK -] -algorithm. (This is an extension module.)
+%[- MARK -] \end{description}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \section{SGI-specific Extension modules}
+%[- MARK -]
+%[- MARK -] END DIFF
quello fornito da questo modulo.
\item[\module{rand}]
Modified: python/python/Doc/branches/2.4.3/lib/libunicodedata.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libunicodedata.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libunicodedata.tex Fri Jun 2 12:52:55 2006
@@ -72,6 +72,28 @@
Restituisce la classe canonica combinata, assegnata al carattere
Unicode \var{unichr} come intero. Restituisce \code{0} se nessuna
classe combinata viene definita.
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 69
+%[- MARK -] Returns the canonical combining class assigned to the Unicode
+%[- MARK -] character \var{unichr} as integer. Returns \code{0} if no combining
+%[- MARK -] class is defined.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] +\begin{funcdesc}{east_asian_width}{unichr}
+%[- MARK -] + Returns the east asian width assigned to the Unicode character
+%[- MARK -] + \var{unichr} as string.
+%[- MARK -] +\versionadded{2.4}
+%[- MARK -] +\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{mirrored}{unichr}
+%[- MARK -] - Returns the mirrored property of assigned to the Unicode character
+%[- MARK -] + Returns the mirrored property assigned to the Unicode character
+%[- MARK -] \var{unichr} as integer. Returns \code{1} if the character has been
+%[- MARK -] identified as a ``mirrored'' character in bidirectional text,
+%[- MARK -] \code{0} otherwise.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{mirrored}{unichr}
@@ -128,6 +150,17 @@
In aggiunta, il modulo rende disponibile la seguente costante:
\begin{datadesc}{unidata_version}
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 121
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{unidata_version}
+%[- MARK -] The version of the Unicode database used in this module.
+%[- MARK -]
+%[- MARK -] \versionadded{2.3}
+%[- MARK -] -\end{datadesc}
+%[- MARK -] \ No newline at end of file
+%[- MARK -] +\end{datadesc}
+%[- MARK -] END DIFF
La versione del database Unicode usato in questo modulo.
\versionadded{2.3}
Modified: python/python/Doc/branches/2.4.3/lib/liburllib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liburllib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liburllib.tex Fri Jun 2 12:52:55 2006
@@ -17,6 +17,21 @@
dei nomi di file. Vengono applicate alcune restrizioni: può aprire
solo URL in lettura, e non sono disponibili funzioni di seek.
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 21
+%[- MARK -] \begin{funcdesc}{urlopen}{url\optional{, data\optional{, proxies}}}
+%[- MARK -] Open a network object denoted by a URL for reading. If the URL does
+%[- MARK -] not have a scheme identifier, or if it has \file{file:} as its scheme
+%[- MARK -] identifier, this opens a local file (without universal newlines);
+%[- MARK -] otherwise it opens a socket to a server somewhere on the network. If
+%[- MARK -] -the connection cannot be made, or if the server returns an error code,
+%[- MARK -] +the connection cannot be made
+%[- MARK -] the \exception{IOError} exception is raised. If all went well, a
+%[- MARK -] file-like object is returned. This supports the following methods:
+%[- MARK -] \method{read()}, \method{readline()}, \method{readlines()}, \method{fileno()},
+%[- MARK -] \method{close()}, \method{info()} and \method{geturl()}. It also has
+%[- MARK -] proper support for the iterator protocol.
+%[- MARK -] END DIFF
Definisce le seguenti funzioni pubbliche:
\begin{funcdesc}{urlopen}{url\optional{, data\optional{, proxies}}}
@@ -98,6 +113,21 @@
dizionario vuoto ottiene il risultato di non permettere l'uso di alcun
proxy, e \code{None} (il valore predefinito) causa l'uso delle
impostazioni proxy dell'ambiente, come discusso precedentemente. Per
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 95
+%[- MARK -] used, and \code{None} (the default value) causes environmental proxy
+%[- MARK -] settings to be used as discussed above. For example:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] # Use http://www.someproxy.com:3128 for http proxying
+%[- MARK -] -proxies = proxies={'http': 'http://www.someproxy.com:3128'}
+%[- MARK -] +proxies = {'http': 'http://www.someproxy.com:3128'}
+%[- MARK -] filehandle = urllib.urlopen(some_url, proxies=proxies)
+%[- MARK -] # Don't use any proxies
+%[- MARK -] filehandle = urllib.urlopen(some_url, proxies={})
+%[- MARK -] # Use proxies from environment - both versions are equivalent
+%[- MARK -] filehandle = urllib.urlopen(some_url, proxies=None)
+%[- MARK -] END DIFF
esempio:
\begin{verbatim}
@@ -167,6 +197,23 @@
con il seguente codice:
\begin{verbatim}
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 158
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] import urllib
+%[- MARK -]
+%[- MARK -] class AppURLopener(urllib.FancyURLopener):
+%[- MARK -] - def __init__(self, *args):
+%[- MARK -] - self.version = "App/1.7"
+%[- MARK -] - urllib.FancyURLopener.__init__(self, *args)
+%[- MARK -] + version = "App/1.7"
+%[- MARK -]
+%[- MARK -] urllib._urlopener = AppURLopener()
+%[- MARK -] \end{verbatim}
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] END DIFF
import urllib
class AppURLopener(urllib.FancyURLopener):
@@ -253,6 +300,25 @@
Classe di base per l'apertura e la lettura delle URL. Finché si avrà
bisogno di supportare l'apertura di oggetti usando schemi diversi da
\file{http:}, \file{ftp:}, \file{gopher:} o \file{file:},
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 241
+%[- MARK -]
+%[- MARK -] By default, the \class{URLopener} class sends a
+%[- MARK -] \mailheader{User-Agent} header of \samp{urllib/\var{VVV}}, where
+%[- MARK -] \var{VVV} is the \module{urllib} version number. Applications can
+%[- MARK -] define their own \mailheader{User-Agent} header by subclassing
+%[- MARK -] -\class{URLopener} or \class{FancyURLopener} and setting the instance
+%[- MARK -] -attribute \member{version} to an appropriate string value before the
+%[- MARK -] -\method{open()} method is called.
+%[- MARK -] +\class{URLopener} or \class{FancyURLopener} and setting the class
+%[- MARK -] +attribute \member{version} to an appropriate string value in the
+%[- MARK -] +subclass definition.
+%[- MARK -]
+%[- MARK -] The optional \var{proxies} parameter should be a dictionary mapping
+%[- MARK -] scheme names to proxy URLs, where an empty dictionary turns proxies
+%[- MARK -] off completely. Its default value is \code{None}, in which case
+%[- MARK -] environmental proxy settings will be used if present, as discussed in
+%[- MARK -] END DIFF
probabilmente si vorrà usare \class{FancyURLopener}.
Predefinitamente, la classe \class{URLopener} invia
@@ -269,6 +335,22 @@
imposta il proxy completamente ad off. Il suo valore predefinito è
\code{None}, nel cui caso le impostazioni d'ambiente del proxy
verranno usate se presenti, come discusso precedentemente nella
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 255
+%[- MARK -]
+%[- MARK -] Additional keyword parameters, collected in \var{x509}, are used for
+%[- MARK -] authentication with the \file{https:} scheme. The keywords
+%[- MARK -] \var{key_file} and \var{cert_file} are supported; both are needed to
+%[- MARK -] actually retrieve a resource at an \file{https:} URL.
+%[- MARK -] +
+%[- MARK -] +\class{URLopener} objects will raise an \exception{IOError} exception
+%[- MARK -] +if the server returns an error code.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{FancyURLopener}{...}
+%[- MARK -] \class{FancyURLopener} subclasses \class{URLopener} providing default
+%[- MARK -] handling for the following HTTP response codes: 301, 302, 303, 307 and
+%[- MARK -] END DIFF
definizione di \function{urlopen()}.
Parametri di chiavi addizionali, raccolte in \var{x509}, vengono usate
@@ -287,6 +369,23 @@
viene fornita l'autenticazione base dell'HTTP. Per i codici di
risposta 30x, la ricorsione viene controllata dal valore
dell'attributo \var{maxtries}, che ha un valore predefinito impostato a
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 266
+%[- MARK -] \mailheader{Location} header is used to fetch the actual URL. For 401
+%[- MARK -] response codes (authentication required), basic HTTP authentication is
+%[- MARK -] performed. For the 30x response codes, recursion is bounded by the
+%[- MARK -] value of the \var{maxtries} attribute, which defaults to 10.
+%[- MARK -]
+%[- MARK -] +For all other response codes, the method \method{http_error_default()}
+%[- MARK -] +is called which you can override in subclasses to handle the error
+%[- MARK -] +appropriately.
+%[- MARK -] +
+%[- MARK -] \note{According to the letter of \rfc{2616}, 301 and 302 responses to
+%[- MARK -] POST requests must not be automatically redirected without
+%[- MARK -] confirmation by the user. In reality, browsers do allow automatic
+%[- MARK -] redirection of these responses, changing the POST to a GET, and
+%[- MARK -] \module{urllib} reproduces this behaviour.}
+%[- MARK -] END DIFF
10.
\note{In accordo alle indicazioni dell'\rfc{2616}, le risposte 301 e
@@ -348,6 +447,36 @@
Per il protocollo \indexii{Gopher}{protocol}, il tipo di informazione è
codificata nell'URL; non c'è attualmente nessun modo facile per
estrarlo. Se il dato restituito è HTML, si può usare il modulo
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 327
+%[- MARK -] in the URL; there is currently no easy way to extract it. If the
+%[- MARK -] returned data is HTML, you can use the module
+%[- MARK -] \refmodule{htmllib}\refstmodindex{htmllib} to parse it.
+%[- MARK -]
+%[- MARK -] \item
+%[- MARK -] +The code handling the FTP\index{FTP} protocol cannot differentiate
+%[- MARK -] +between a file and a directory. This can lead to unexpected behavior
+%[- MARK -] +when attempting to read a URL that points to a file that is not
+%[- MARK -] +accessible. If the URL ends in a \code{/}, it is assumed to refer to
+%[- MARK -] +a directory and will be handled accordingly. But if an attempt to
+%[- MARK -] +read a file leads to a 550 error (meaning the URL cannot be found or
+%[- MARK -] +is not accessible, often for permission reasons), then the path is
+%[- MARK -] +treated as a directory in order to handle the case when a directory is
+%[- MARK -] +specified by a URL but the trailing \code{/} has been left off. This can
+%[- MARK -] +cause misleading results when you try to fetch a file whose read
+%[- MARK -] +permissions make it inaccessible; the FTP code will try to read it,
+%[- MARK -] +fail with a 550 error, and then perform a directory listing for the
+%[- MARK -] +unreadable file. If fine-grained control is needed, consider using the
+%[- MARK -] +\module{ftplib} module, subclassing \class{FancyURLOpener}, or changing
+%[- MARK -] +\var{_urlopener} to meet your needs.
+%[- MARK -] +
+%[- MARK -] +\item
+%[- MARK -] This module does not support the use of proxies which require
+%[- MARK -] authentication. This may be implemented in the future.
+%[- MARK -]
+%[- MARK -] \item
+%[- MARK -] Although the \module{urllib} module contains (undocumented) routines
+%[- MARK -] END DIFF
\refmodule{htmllib}\refstmodindex{htmllib} per analizzarlo.
\item
Modified: python/python/Doc/branches/2.4.3/lib/liburllib2.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liburllib2.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liburllib2.tex Fri Jun 2 12:52:55 2006
@@ -6,6 +6,29 @@
\sectionauthor{Moshe Zadka}{moshez a users.sourceforge.net}
\modulesynopsis{Una libreria estensibile per l'apertura delle URL che
+%[- MARK -] BEGIN DIFF 001 of 12
+%[- MARK -] @@ 8
+%[- MARK -] \modulesynopsis{An extensible library for opening URLs using a variety of
+%[- MARK -] protocols}
+%[- MARK -]
+%[- MARK -] The \module{urllib2} module defines functions and classes which help
+%[- MARK -] in opening URLs (mostly HTTP) in a complex world --- basic and digest
+%[- MARK -] -authentication, redirections and more.
+%[- MARK -] +authentication, redirections, cookies and more.
+%[- MARK -]
+%[- MARK -] The \module{urllib2} module defines the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{urlopen}{url\optional{, data}}
+%[- MARK -] Open the URL \var{url}, which can be either a string or a \class{Request}
+%[- MARK -] -object (currently the code checks that it really is a \class{Request}
+%[- MARK -] -instance, or an instance of a subclass of \class{Request}).
+%[- MARK -] +object.
+%[- MARK -]
+%[- MARK -] \var{data} should be a string, which specifies additional data to
+%[- MARK -] send to the server. In HTTP requests, which are the only ones that
+%[- MARK -] support \var{data}, it should be a buffer in the format of
+%[- MARK -] \mimetype{application/x-www-form-urlencoded}, for example one returned
+%[- MARK -] END DIFF
usa svariati protocolli}
Il modulo \module{urllib2} definisce funzioni e classi che aiutano
@@ -32,6 +55,35 @@
\item \method{geturl()} --- restituisce l'URL della risorsa recuperata
\item \method{info()} --- restituisce le meta informazioni della
pagina, come un oggetto simile ad un dizionario
+%[- MARK -] BEGIN DIFF 002 of 12
+%[- MARK -] @@ 32
+%[- MARK -] \item \method{info()} --- return the meta-information of the page, as
+%[- MARK -] a dictionary-like object
+%[- MARK -] \end{itemize}
+%[- MARK -]
+%[- MARK -] Raises \exception{URLError} on errors.
+%[- MARK -] +
+%[- MARK -] +Note that \code{None} may be returned if no handler handles the
+%[- MARK -] +request (though the default installed global \class{OpenerDirector}
+%[- MARK -] +uses \class{UnknownHandler} to ensure this never happens).
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{install_opener}{opener}
+%[- MARK -] -Install an \class{OpenerDirector} instance as the default opener.
+%[- MARK -] -The code does not check for a real \class{OpenerDirector}, and any
+%[- MARK -] -class with the appropriate interface will work.
+%[- MARK -] +Install an \class{OpenerDirector} instance as the default global
+%[- MARK -] +opener. Installing an opener is only necessary if you want urlopen to
+%[- MARK -] +use that opener; otherwise, simply call \method{OpenerDirector.open()}
+%[- MARK -] +instead of \function{urlopen()}. The code does not check for a real
+%[- MARK -] +\class{OpenerDirector}, and any class with the appropriate interface
+%[- MARK -] +will work.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{build_opener}{\optional{handler, \moreargs}}
+%[- MARK -] Return an \class{OpenerDirector} instance, which chains the
+%[- MARK -] handlers in the order given. \var{handler}s can be either instances
+%[- MARK -] END DIFF
\end{itemize}
In caso di errore solleva l'eccezione \exception{URLError}.
@@ -91,6 +143,46 @@
\end{excdesc}
+%[- MARK -] BEGIN DIFF 003 of 12
+%[- MARK -] @@ 85
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] The following classes are provided:
+%[- MARK -]
+%[- MARK -] -\begin{classdesc}{Request}{url\optional{, data\optional{, headers}}}
+%[- MARK -] +\begin{classdesc}{Request}{url\optional{, data}\optional{, headers}
+%[- MARK -] + \optional{, origin_req_host}\optional{, unverifiable}}
+%[- MARK -] This class is an abstraction of a URL request.
+%[- MARK -]
+%[- MARK -] \var{url} should be a string which is a valid URL. For a description
+%[- MARK -] of \var{data} see the \method{add_data()} description.
+%[- MARK -] \var{headers} should be a dictionary, and will be treated as if
+%[- MARK -] \method{add_header()} was called with each key and value as arguments.
+%[- MARK -] +
+%[- MARK -] +The final two arguments are only of interest for correct handling of
+%[- MARK -] +third-party HTTP cookies:
+%[- MARK -] +
+%[- MARK -] +\var{origin_req_host} should be the request-host of the origin
+%[- MARK -] +transaction, as defined by \rfc{2965}. It defaults to
+%[- MARK -] +\code{cookielib.request_host(self)}. This is the host name or IP
+%[- MARK -] +address of the original request that was initiated by the user. For
+%[- MARK -] +example, if the request is for an image in an HTML document, this
+%[- MARK -] +should be the request-host of the request for the page containing the
+%[- MARK -] +image.
+%[- MARK -] +
+%[- MARK -] +\var{unverifiable} should indicate whether the request is
+%[- MARK -] +unverifiable, as defined by RFC 2965. It defaults to False. An
+%[- MARK -] +unverifiable request is one whose URL the user did not have the option
+%[- MARK -] +to approve. For example, if the request is for an image in an HTML
+%[- MARK -] +document, and the user had no option to approve the automatic fetching
+%[- MARK -] +of the image, this should be true.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{OpenerDirector}{}
+%[- MARK -] The \class{OpenerDirector} class opens URLs via \class{BaseHandler}s
+%[- MARK -] chained together. It manages the chaining of handlers, and recovery
+%[- MARK -] END DIFF
Sono disponibili le seguenti classi:
\begin{classdesc}{Request}{url\optional{, data\optional{, headers}}}
@@ -122,6 +214,30 @@
\begin{classdesc}{HTTPRedirectHandler}{}
Una classe che gestisce le redirezioni.
+%[- MARK -] BEGIN DIFF 004 of 12
+%[- MARK -] @@ 114
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{HTTPRedirectHandler}{}
+%[- MARK -] A class to handle redirections.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] +\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}}
+%[- MARK -] +A class to handle HTTP Cookies.
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] \begin{classdesc}{ProxyHandler}{\optional{proxies}}
+%[- MARK -] Cause requests to go through a proxy.
+%[- MARK -] If \var{proxies} is given, it must be a dictionary mapping
+%[- MARK -] protocol names to URLs of proxies.
+%[- MARK -] The default is to read the list of proxies from the environment
+%[- MARK -] -variables \var{protocol}_proxy.
+%[- MARK -] +variables \envvar{<protocol>_proxy}.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{HTTPPasswordMgr}{}
+%[- MARK -] Keep a database of
+%[- MARK -] \code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})}
+%[- MARK -] END DIFF
\end{classdesc}
\begin{classdesc}{ProxyHandler}{\optional{proxies}}
@@ -228,6 +344,35 @@
\subsection{Oggetti Request \label{request-objects}}
I seguenti metodi descrivono tutto delle interfacce pubbliche
+%[- MARK -] BEGIN DIFF 005 of 12
+%[- MARK -] @@ 215
+%[- MARK -]
+%[- MARK -] The following methods describe all of \class{Request}'s public interface,
+%[- MARK -] and so all must be overridden in subclasses.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Request]{add_data}{data}
+%[- MARK -] -Set the \class{Request} data to \var{data}. This is ignored
+%[- MARK -] -by all handlers except HTTP handlers --- and there it should be an
+%[- MARK -] -\mimetype{application/x-www-form-encoded} buffer, and will change the
+%[- MARK -] -request to be \code{POST} rather than \code{GET}.
+%[- MARK -] +Set the \class{Request} data to \var{data}. This is ignored by all
+%[- MARK -] +handlers except HTTP handlers --- and there it should be a byte
+%[- MARK -] +string, and will change the request to be \code{POST} rather than
+%[- MARK -] +\code{GET}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Request]{get_method}{}
+%[- MARK -] Return a string indicating the HTTP request method. This is only
+%[- MARK -] -meaningful for HTTP requests, and currently always takes one of the
+%[- MARK -] -values ("GET", "POST").
+%[- MARK -] +meaningful for HTTP requests, and currently always returns
+%[- MARK -] +\code{'GET'} or \code{'POST'}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Request]{has_data}{}
+%[- MARK -] Return whether the instance has a non-\code{None} data.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\class{Request}, e tutte devono essere sovrascritte in sotto classi.
\begin{methoddesc}[Request]{add_data}{data}
@@ -297,6 +442,125 @@
Prepara la richiesta connettendosi a un proxy server. \var{host} e
\var{type} rimpiazzeranno quelli dell'instanza, ed il selettore
dell'istanza sarà l'URL originale fornita nel costruttore.
+%[- MARK -] BEGIN DIFF 006 of 12
+%[- MARK -] @@ 280
+%[- MARK -] Prepare the request by connecting to a proxy server. The \var{host}
+%[- MARK -] and \var{type} will replace those of the instance, and the instance's
+%[- MARK -] selector will be the original URL given in the constructor.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddesc}[Request]{get_origin_req_host}{}
+%[- MARK -] +Return the request-host of the origin transaction, as defined by
+%[- MARK -] +\rfc{2965}. See the documentation for the \class{Request}
+%[- MARK -] +constructor.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[Request]{is_unverifiable}{}
+%[- MARK -] +Return whether the request is unverifiable, as defined by RFC 2965.
+%[- MARK -] +See the documentation for the \class{Request} constructor.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \subsection{OpenerDirector Objects \label{opener-director-objects}}
+%[- MARK -]
+%[- MARK -] \class{OpenerDirector} instances have the following methods:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[OpenerDirector]{add_handler}{handler}
+%[- MARK -] \var{handler} should be an instance of \class{BaseHandler}. The
+%[- MARK -] -following methods are searched, and added to the possible chains.
+%[- MARK -] +following methods are searched, and added to the possible chains (note
+%[- MARK -] +that HTTP errors are a special case).
+%[- MARK -]
+%[- MARK -] \begin{itemize}
+%[- MARK -] \item \method{\var{protocol}_open()} ---
+%[- MARK -] signal that the handler knows how to open \var{protocol} URLs.
+%[- MARK -] - \item \method{\var{protocol}_error_\var{type}()} ---
+%[- MARK -] - signal that the handler knows how to handle \var{type} errors from
+%[- MARK -] - \var{protocol}.
+%[- MARK -] + \item \method{http_error_\var{type}()} ---
+%[- MARK -] + signal that the handler knows how to handle HTTP errors with HTTP
+%[- MARK -] + error code \var{type}.
+%[- MARK -] + \item \method{\var{protocol}_error()} ---
+%[- MARK -] + signal that the handler knows how to handle errors from
+%[- MARK -] + (non-\code{http}) \var{protocol}.
+%[- MARK -] \item \method{\var{protocol}_request()} ---
+%[- MARK -] signal that the handler knows how to pre-process \var{protocol}
+%[- MARK -] requests.
+%[- MARK -] \item \method{\var{protocol}_response()} ---
+%[- MARK -] signal that the handler knows how to post-process \var{protocol}
+%[- MARK -] responses.
+%[- MARK -] \end{itemize}
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[OpenerDirector]{close}{}
+%[- MARK -] -Explicitly break cycles, and delete all the handlers.
+%[- MARK -] -Because the \class{OpenerDirector} needs to know the registered handlers,
+%[- MARK -] -and a handler needs to know who the \class{OpenerDirector} who called
+%[- MARK -] -it is, there is a reference cycle. Even though recent versions of Python
+%[- MARK -] -have cycle-collection, it is sometimes preferable to explicitly break
+%[- MARK -] -the cycles.
+%[- MARK -] -\end{methoddesc}
+%[- MARK -] -
+%[- MARK -] \begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}}
+%[- MARK -] Open the given \var{url} (which can be a request object or a string),
+%[- MARK -] optionally passing the given \var{data}.
+%[- MARK -] Arguments, return values and exceptions raised are the same as those
+%[- MARK -] of \function{urlopen()} (which simply calls the \method{open()} method
+%[- MARK -] -on the default installed \class{OpenerDirector}).
+%[- MARK -] +on the currently installed global \class{OpenerDirector}).
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
+%[- MARK -] arg\optional{, \moreargs}}}
+%[- MARK -] -Handle an error in a given protocol. This will call the registered
+%[- MARK -] +Handle an error of the given protocol. This will call the registered
+%[- MARK -] error handlers for the given protocol with the given arguments (which
+%[- MARK -] are protocol specific). The HTTP protocol is a special case which
+%[- MARK -] uses the HTTP response code to determine the specific error handler;
+%[- MARK -] refer to the \method{http_error_*()} methods of the handler classes.
+%[- MARK -]
+%[- MARK -] Return values and exceptions raised are the same as those
+%[- MARK -] of \function{urlopen()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +OpenerDirector objects open URLs in three stages:
+%[- MARK -] +
+%[- MARK -] +The order in which these methods are called within each stage is
+%[- MARK -] +determined by sorting the handler instances.
+%[- MARK -] +
+%[- MARK -] +\begin{enumerate}
+%[- MARK -] + \item Every handler with a method named like
+%[- MARK -] + \method{\var{protocol}_request()} has that method called to
+%[- MARK -] + pre-process the request.
+%[- MARK -] +
+%[- MARK -] + \item Handlers with a method named like
+%[- MARK -] + \method{\var{protocol}_open()} are called to handle the request.
+%[- MARK -] + This stage ends when a handler either returns a
+%[- MARK -] + non-\constant{None} value (ie. a response), or raises an exception
+%[- MARK -] + (usually URLError). Exceptions are allowed to propagate.
+%[- MARK -] +
+%[- MARK -] + In fact, the above algorithm is first tried for methods named
+%[- MARK -] + \method{default_open}. If all such methods return
+%[- MARK -] + \constant{None}, the algorithm is repeated for methods named like
+%[- MARK -] + \method{\var{protocol}_open()}. If all such methods return
+%[- MARK -] + \constant{None}, the algorithm is repeated for methods named
+%[- MARK -] + \method{unknown_open()}.
+%[- MARK -] +
+%[- MARK -] + Note that the implementation of these methods may involve calls of
+%[- MARK -] + the parent \class{OpenerDirector} instance's \method{.open()} and
+%[- MARK -] + \method{.error()} methods.
+%[- MARK -] +
+%[- MARK -] + \item Every handler with a method named like
+%[- MARK -] + \method{\var{protocol}_response()} has that method called to
+%[- MARK -] + post-process the response.
+%[- MARK -] +
+%[- MARK -] +\end{enumerate}
+%[- MARK -]
+%[- MARK -] \subsection{BaseHandler Objects \label{base-handler-objects}}
+%[- MARK -]
+%[- MARK -] \class{BaseHandler} objects provide a couple of methods that are
+%[- MARK -] directly useful, and others that are meant to be used by derived
+%[- MARK -] END DIFF
\end{methoddesc}
@@ -368,6 +632,25 @@
\begin{methoddesc}[BaseHandler]{close}{}
Rimuove ogni padre.
+%[- MARK -] BEGIN DIFF 007 of 12
+%[- MARK -] @@ 349
+%[- MARK -] \begin{methoddesc}[BaseHandler]{close}{}
+%[- MARK -] Remove any parents.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] The following members and methods should only be used by classes
+%[- MARK -] -derived from \class{BaseHandler}:
+%[- MARK -] +derived from \class{BaseHandler}. \note{The convention has been
+%[- MARK -] +adopted that subclasses defining \method{\var{protocol}_request()} or
+%[- MARK -] +\method{\var{protocol}_response()} methods are named
+%[- MARK -] +\class{*Processor}; all others are named \class{*Handler}.}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}[BaseHandler]{parent}
+%[- MARK -] A valid \class{OpenerDirector}, which can be used to open using a
+%[- MARK -] different protocol, or handle errors.
+%[- MARK -] \end{memberdesc}
+%[- MARK -] END DIFF
\end{methoddesc}
I seguenti membri e metodi dovrebbero essere usati solo da classi
@@ -444,6 +727,42 @@
Argomenti, valori restituiti ed eccezioni sollevate dovrebbero esser
le stesse come per \method{http_error_default()}.
+%[- MARK -] BEGIN DIFF 008 of 12
+%[- MARK -] @@ 421
+%[- MARK -]
+%[- MARK -] Arguments, return values and exceptions raised should be the same as
+%[- MARK -] for \method{http_error_default()}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req}
+%[- MARK -] +This method is \emph{not} defined in \class{BaseHandler}, but
+%[- MARK -] +subclasses should define it if they want to pre-process requests of
+%[- MARK -] +the given protocol.
+%[- MARK -] +
+%[- MARK -] +This method, if defined, will be called by the parent
+%[- MARK -] +\class{OpenerDirector}. \var{req} will be a \class{Request} object.
+%[- MARK -] +The return value should be a \class{Request} object.
+%[- MARK -] +\end{methoddescni}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response}
+%[- MARK -] +This method is \emph{not} defined in \class{BaseHandler}, but
+%[- MARK -] +subclasses should define it if they want to post-process responses of
+%[- MARK -] +the given protocol.
+%[- MARK -] +
+%[- MARK -] +This method, if defined, will be called by the parent
+%[- MARK -] +\class{OpenerDirector}. \var{req} will be a \class{Request} object.
+%[- MARK -] +\var{response} will be an object implementing the same interface as
+%[- MARK -] +the return value of \function{urlopen()}. The return value should
+%[- MARK -] +implement the same interface as the return value of
+%[- MARK -] +\function{urlopen()}.
+%[- MARK -] +\end{methoddescni}
+%[- MARK -] +
+%[- MARK -] \subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}}
+%[- MARK -]
+%[- MARK -] \note{Some HTTP redirections require action from this module's client
+%[- MARK -] code. If this is the case, \exception{HTTPError} is raised. See
+%[- MARK -] \rfc{2616} for details of the precise meanings of the various
+%[- MARK -] END DIFF
\end{methoddesc}
\subsection{Oggetti HTTPRedirectHandler \label{http-redirect-handler}}
@@ -451,6 +770,30 @@
\note{Alcune redirezioni HTTP richiedono un'azione dal codice di
questo modulo cliente. Se è questo il caso, viene sollevata
l'eccezione \exception{HTTPError}. Vedere l'\rfc{2616} per i
+%[- MARK -] BEGIN DIFF 009 of 12
+%[- MARK -] @@ 432
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
+%[- MARK -] fp, code, msg, hdrs}
+%[- MARK -] Return a \class{Request} or \code{None} in response to a redirect.
+%[- MARK -] This is called by the default implementations of the
+%[- MARK -] -\method{http_error_30*()} methods when a redirection is received
+%[- MARK -] -from the server. If a redirection should take place, return a new
+%[- MARK -] +\method{http_error_30*()} methods when a redirection is received from
+%[- MARK -] +the server. If a redirection should take place, return a new
+%[- MARK -] \class{Request} to allow \method{http_error_30*()} to perform the
+%[- MARK -] -redirect. Otherwise, raise \exception{HTTPError} if no other
+%[- MARK -] -\class{Handler} should try to handle this URL, or return \code{None}
+%[- MARK -] -if you can't but another \class{Handler} might.
+%[- MARK -] +redirect. Otherwise, raise \exception{HTTPError} if no other handler
+%[- MARK -] +should try to handle this URL, or return \code{None} if you can't but
+%[- MARK -] +another handler might.
+%[- MARK -]
+%[- MARK -] \begin{notice}
+%[- MARK -] The default implementation of this method does not strictly
+%[- MARK -] follow \rfc{2616}, which says that 301 and 302 responses to \code{POST}
+%[- MARK -] requests must not be automatically redirected without confirmation by
+%[- MARK -] END DIFF
dettagli del preciso significato dei vari codici di redirezione.}
\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
@@ -500,6 +843,28 @@
fp, code, msg, hdrs}
Lo stesso di \method{http_error_301()}, ma chiamato per risposte
'temporary redirect' (temporaneamente rediretto).
+%[- MARK -] BEGIN DIFF 010 of 12
+%[- MARK -] @@ 476
+%[- MARK -] The same as \method{http_error_301()}, but called for the
+%[- MARK -] `temporary redirect' response.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] +\subsection{HTTPCookieProcessor Objects \label{http-cookie-processor}}
+%[- MARK -] +
+%[- MARK -] +\class{HTTPCookieProcessor} instances have one attribute:
+%[- MARK -] +
+%[- MARK -] +\begin{memberdesc}{cookiejar}
+%[- MARK -] +The \class{cookielib.CookieJar} in which cookies are stored.
+%[- MARK -] +\end{memberdesc}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] \subsection{ProxyHandler Objects \label{proxy-handler}}
+%[- MARK -]
+%[- MARK -] \begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request}
+%[- MARK -] The \class{ProxyHandler} will have a method
+%[- MARK -] \method{\var{protocol}_open()} for every \var{protocol} which has a
+%[- MARK -] END DIFF
\end{methoddesc}
@@ -695,6 +1060,22 @@
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html
+%[- MARK -] BEGIN DIFF 011 of 12
+%[- MARK -] @@ 666
+%[- MARK -] <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+%[- MARK -] <?xml-stylesheet href="./css/ht2html
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] Here we are sending a data-stream to the stdin of a CGI and reading
+%[- MARK -] -the data it returns to us:
+%[- MARK -] +the data it returns to us. Note that this example will only work when the
+%[- MARK -] +Python installation supports SSL.
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] >>> import urllib2
+%[- MARK -] >>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
+%[- MARK -] ... data='This data is passed to stdin of the CGI')
+%[- MARK -] END DIFF
\end{verbatim}
Qui, si sta inviando un flusso di dati attraverso lo stdin di una CGI
@@ -709,6 +1090,75 @@
Got Data: "This data is passed to stdin of the CGI"
\end{verbatim}
+%[- MARK -] BEGIN DIFF 012 of 12
+%[- MARK -] @@ 685
+%[- MARK -] #!/usr/bin/env python
+%[- MARK -] import sys
+%[- MARK -] data = sys.stdin.read()
+%[- MARK -] print 'Content-type: text-plain\n\nGot Data: "%s"' % data
+%[- MARK -] \end{verbatim}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +Use of Basic HTTP Authentication:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import urllib2
+%[- MARK -] +# Create an OpenerDirector with support for Basic HTTP Authentication...
+%[- MARK -] +auth_handler = urllib2.HTTPBasicAuthHandler()
+%[- MARK -] +auth_handler.add_password('realm', 'host', 'username', 'password')
+%[- MARK -] +opener = urllib2.build_opener(auth_handler)
+%[- MARK -] +# ...and install it globally so it can be used with urlopen.
+%[- MARK -] +urllib2.install_opener(opener)
+%[- MARK -] +urllib2.urlopen('http://www.example.com/login.html')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\function{build_opener()} provides many handlers by default, including a
+%[- MARK -] +\class{ProxyHandler}. By default, \class{ProxyHandler} uses the
+%[- MARK -] +environment variables named \code{<scheme>_proxy}, where \code{<scheme>}
+%[- MARK -] +is the URL scheme involved. For example, the \envvar{http_proxy}
+%[- MARK -] +environment variable is read to obtain the HTTP proxy's URL.
+%[- MARK -] +
+%[- MARK -] +This example replaces the default \class{ProxyHandler} with one that uses
+%[- MARK -] +programatically-supplied proxy URLs, and adds proxy authorization support
+%[- MARK -] +with \class{ProxyBasicAuthHandler}.
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
+%[- MARK -] +proxy_auth_handler = urllib2.HTTPBasicAuthHandler()
+%[- MARK -] +proxy_auth_handler.add_password('realm', 'host', 'username', 'password')
+%[- MARK -] +
+%[- MARK -] +opener = build_opener(proxy_handler, proxy_auth_handler)
+%[- MARK -] +# This time, rather than install the OpenerDirector, we use it directly:
+%[- MARK -] +opener.open('http://www.example.com/login.html')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +Adding HTTP headers:
+%[- MARK -] +
+%[- MARK -] +Use the \var{headers} argument to the \class{Request} constructor, or:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import urllib2
+%[- MARK -] +req = urllib2.Request('http://www.example.com/')
+%[- MARK -] +req.add_header('Referer', 'http://www.python.org/')
+%[- MARK -] +r = urllib2.urlopen(req)
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +\class{OpenerDirector} automatically adds a \mailheader{User-Agent}
+%[- MARK -] +header to every \class{Request}. To change this:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import urllib2
+%[- MARK -] +opener = urllib2.build_opener()
+%[- MARK -] +opener.addheaders = [('User-agent', 'Mozilla/5.0')]
+%[- MARK -] +opener.open('http://www.example.com/')
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Also, remember that a few standard headers
+%[- MARK -] +(\mailheader{Content-Length}, \mailheader{Content-Type} and
+%[- MARK -] +\mailheader{Host}) are added when the \class{Request} is passed to
+%[- MARK -] +\function{urlopen()} (or \method{OpenerDirector.open()}).
+%[- MARK -] END DIFF
Il codice per il CGI di esempio usato nel precedente esempio è:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/liburlparse.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/liburlparse.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/liburlparse.tex Fri Jun 2 12:52:55 2006
@@ -15,6 +15,29 @@
Uniform Resource Locator (URL) in componenti (schema di
indirizzamento, indirizzo di rete, percorso etc. etc.), per
ricombinare i componenti in una stringa URL, e per convertire una
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 17
+%[- MARK -] string, and to convert a ``relative URL'' to an absolute URL given a
+%[- MARK -] ``base URL.''
+%[- MARK -]
+%[- MARK -] The module has been designed to match the Internet RFC on Relative
+%[- MARK -] Uniform Resource Locators (and discovered a bug in an earlier
+%[- MARK -] -draft!).
+%[- MARK -] +draft!). It supports the following URL schemes:
+%[- MARK -] +\code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http},
+%[- MARK -] +\code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news},
+%[- MARK -] +\code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu},
+%[- MARK -] +\code{shttp}, \code{sip}, \code{snews}, \code{svn}, \code{svn+ssh},
+%[- MARK -] +\code{telnet}, \code{wais}.
+%[- MARK -]
+%[- MARK -] -It defines the following functions:
+%[- MARK -] +The \module{urlparse} module defines the following functions:
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{urlparse}{urlstring\optional{, default_scheme\optional{, allow_fragments}}}
+%[- MARK -] Parse a URL into 6 components, returning a 6-tuple: (addressing
+%[- MARK -] scheme, network location, path, parameters, query, fragment
+%[- MARK -] identifier). This corresponds to the general structure of a URL:
+%[- MARK -] END DIFF
``URL relativa'' in una URL assoluta indicando una ``URL di base''.
Il modulo è stato progettato per essere rispondente alle RFC Internet
@@ -65,6 +88,25 @@
differente, ma equivalente, se le URL che erano state originariamente
utilizzate avevano delimitatori ridondanti, per esempio ? con una
interrogazione vuota (il loro stadio intermedio è equivalente).
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 67
+%[- MARK -] default_scheme\optional{, allow_fragments}}}
+%[- MARK -] This is similar to \function{urlparse()}, but does not split the
+%[- MARK -] params from the URL. This should generally be used instead of
+%[- MARK -] \function{urlparse()} if the more recent URL syntax allowing
+%[- MARK -] parameters to be applied to each segment of the \var{path} portion of
+%[- MARK -] -the URL (see \rfc{2396}). A separate function is needed to separate
+%[- MARK -] -the path segments and parameters. This function returns a 5-tuple:
+%[- MARK -] -(addressing scheme, network location, path, query, fragment
+%[- MARK -] +the URL (see \rfc{2396}) is wanted. A separate function is needed to
+%[- MARK -] +separate the path segments and parameters. This function returns a
+%[- MARK -] +5-tuple: (addressing scheme, network location, path, query, fragment
+%[- MARK -] identifier).
+%[- MARK -] \versionadded{2.2}
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{urlunsplit}{tuple}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{urlsplit}{urlstring\optional{,
Modified: python/python/Doc/branches/2.4.3/lib/libuserdict.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libuserdict.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libuserdict.tex Fri Jun 2 12:52:55 2006
@@ -2,6 +2,70 @@
Wrapper per classi di oggetti dizionario}
\declaremodule{standard}{UserDict}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 2
+%[- MARK -] Class wrapper for dictionary objects}
+%[- MARK -]
+%[- MARK -] \declaremodule{standard}{UserDict}
+%[- MARK -] \modulesynopsis{Class wrapper for dictionary objects.}
+%[- MARK -]
+%[- MARK -] -\note{This module is available for backward compatibility only. If
+%[- MARK -] -you are writing code that does not need to work with versions of
+%[- MARK -] -Python earlier than Python 2.2, please consider subclassing directly
+%[- MARK -] -from the built-in \class{dict} type.}
+%[- MARK -]
+%[- MARK -] -This module defines a class that acts as a wrapper around
+%[- MARK -] -dictionary objects. It is a useful base class for
+%[- MARK -] -your own dictionary-like classes, which can inherit from
+%[- MARK -] -them and override existing methods or add new ones. In this way one
+%[- MARK -] -can add new behaviors to dictionaries.
+%[- MARK -] -
+%[- MARK -] -The module also defines a mixin defining all dictionary methods for
+%[- MARK -] -classes that already have a minimum mapping interface. This greatly
+%[- MARK -] -simplifies writing classes that need to be substitutable for
+%[- MARK -] +The module defines a mixin, \class{DictMixin}, defining all dictionary
+%[- MARK -] +methods for classes that already have a minimum mapping interface. This
+%[- MARK -] +greatly simplifies writing classes that need to be substitutable for
+%[- MARK -] dictionaries (such as the shelve module).
+%[- MARK -]
+%[- MARK -] +This also module defines a class, \class{UserDict}, that acts as a wrapper
+%[- MARK -] +around dictionary objects. The need for this class has been largely
+%[- MARK -] +supplanted by the ability to subclass directly from \class{dict} (a feature
+%[- MARK -] +that became available starting with Python version 2.2). Prior to the
+%[- MARK -] +introduction of \class{dict}, the \class{UserDict} class was used to
+%[- MARK -] +create dictionary-like sub-classes that obtained new behaviors by overriding
+%[- MARK -] +existing methods or adding new ones.
+%[- MARK -] +
+%[- MARK -] The \module{UserDict} module defines the \class{UserDict} class
+%[- MARK -] and \class{DictMixin}:
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{UserDict}{\optional{initialdata}}
+%[- MARK -] Class that simulates a dictionary. The instance's
+%[- MARK -] contents are kept in a regular dictionary, which is accessible via the
+%[- MARK -] \member{data} attribute of \class{UserDict} instances. If
+%[- MARK -] \var{initialdata} is provided, \member{data} is initialized with its
+%[- MARK -] contents; note that a reference to \var{initialdata} will not be kept,
+%[- MARK -] -allowing it be used for other purposes.
+%[- MARK -] +allowing it be used for other purposes. \note{For backward compatibility,
+%[- MARK -] +instances of \class{UserDict} are not iterable.}
+%[- MARK -] +\end{classdesc}
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{IterableUserDict}{\optional{initialdata}}
+%[- MARK -] +Subclass of \class{UserDict} that supports direct iteration (e.g.
+%[- MARK -] +\code{for key in myDict}).
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] In addition to supporting the methods and operations of mappings (see
+%[- MARK -] -section \ref{typesmapping}), \class{UserDict} instances provide the
+%[- MARK -] -following attribute:
+%[- MARK -] +section \ref{typesmapping}), \class{UserDict} and
+%[- MARK -] +\class{IterableUserDict} instances provide the following attribute:
+%[- MARK -]
+%[- MARK -] \begin{memberdesc}{data}
+%[- MARK -] A real dictionary used to store the contents of the \class{UserDict}
+%[- MARK -] class.
+%[- MARK -] \end{memberdesc}
+%[- MARK -] END DIFF
\modulesynopsis{Wrapper per classi di oggetti dizionario.}
\note{Questo modulo è disponibile solo per compatibilità all'indietro.
@@ -51,6 +115,21 @@
ciascuno dei metodi indicati sopra, integra progressivamente maggiori
funzionalità. Per esempio, definendo tutti i metodi tranne
\method{__delitem__} si precluderà soltanto \method{pop} e
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 49
+%[- MARK -] This mixin should be used as a superclass. Adding each of the
+%[- MARK -] above methods adds progressively more functionality. For instance,
+%[- MARK -] defining all but \method{__delitem__} will preclude only \method{pop}
+%[- MARK -] and \method{popitem} from the full interface.
+%[- MARK -]
+%[- MARK -] -In addition to the four base methods, progessively more efficiency
+%[- MARK -] +In addition to the four base methods, progressively more efficiency
+%[- MARK -] comes with defining \method{__contains__()}, \method{__iter__()}, and
+%[- MARK -] \method{iteritems()}.
+%[- MARK -]
+%[- MARK -] Since the mixin has no knowledge of the subclass constructor, it
+%[- MARK -] does not define \method{__init__()} or \method{copy()}.
+%[- MARK -] END DIFF
\method{popitem} dall'interfaccia completa.
In aggiunta ai quattro metodi di base, viene progressivamente raggiunta
Modified: python/python/Doc/branches/2.4.3/lib/libuu.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libuu.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libuu.tex Fri Jun 2 12:52:55 2006
@@ -31,6 +31,39 @@
consentire la successiva decodifica del file. Il valore predefinito
viene preso rispettivamente da \var{in_file} o \code{'-'} e
\code{0666}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 29
+%[- MARK -] the defaults for the results of decoding the file. The default
+%[- MARK -] defaults are taken from \var{in_file}, or \code{'-'} and \code{0666}
+%[- MARK -] respectively.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode}}}
+%[- MARK -] +\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode\optional{, quiet}}}}
+%[- MARK -] This call decodes uuencoded file \var{in_file} placing the result on
+%[- MARK -] file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is
+%[- MARK -] used to set the permission bits if the file must be
+%[- MARK -] created. Defaults for \var{out_file} and \var{mode} are taken from
+%[- MARK -] the uuencode header. However, if the file specified in the header
+%[- MARK -] already exists, a \exception{uu.Error} is raised.
+%[- MARK -] +
+%[- MARK -] + \function{decode()} may print a warning to standard error if the
+%[- MARK -] + input was produced by an incorrect uuencoder and Python could
+%[- MARK -] + recover from that error. Setting \var{quiet} to a true value
+%[- MARK -] + silences this warning.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{excclassdesc}{Error}{}
+%[- MARK -] Subclass of \exception{Exception}, this can be raised by
+%[- MARK -] \function{uu.decode()} under various situations, such as described
+%[- MARK -] - above, but also including a badly formated header, or truncated
+%[- MARK -] + above, but also including a badly formatted header, or truncated
+%[- MARK -] input file.
+%[- MARK -] \end{excclassdesc}
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] \seemodule{binascii}{Support module containing \ASCII-to-binary
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode}}}
Modified: python/python/Doc/branches/2.4.3/lib/libwarnings.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libwarnings.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libwarnings.tex Fri Jun 2 12:52:55 2006
@@ -42,6 +42,21 @@
venire aggiunte al filtro attraverso la funzione
\function{filterwarnings()} e reimpostate allo stato predefinito
mediante la funzione
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 37
+%[- MARK -] Rules can be added to the filter by calling
+%[- MARK -] \function{filterwarnings()} and reset to its default state by calling
+%[- MARK -] \function{resetwarnings()}.
+%[- MARK -]
+%[- MARK -] The printing of warning messages is done by calling
+%[- MARK -] -\function{showwarning()}, which may be overidden; the default
+%[- MARK -] +\function{showwarning()}, which may be overridden; the default
+%[- MARK -] implementation of this function formats the message by calling
+%[- MARK -] \function{formatwarning()}, which is also available for use by custom
+%[- MARK -] implementations.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] END DIFF
\function{resetwarnings()}.
La stampa dei messaggi di avvertimento viene eseguita chiamando la
Modified: python/python/Doc/branches/2.4.3/lib/libweakref.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libweakref.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libweakref.tex Fri Jun 2 12:52:55 2006
@@ -7,6 +7,21 @@
\moduleauthor{Martin von L\"owis}{martin a loewis.home.cs.tu-berlin.de}
\sectionauthor{Fred L. Drake, Jr.}{fdrake a acm.org}
+%[- MARK -] BEGIN DIFF 001 of 5
+%[- MARK -] @@ 8
+%[- MARK -] \moduleauthor{Martin von L\"owis}{martin a loewis.home.cs.tu-berlin.de}
+%[- MARK -] \sectionauthor{Fred L. Drake, Jr.}{fdrake a acm.org}
+%[- MARK -]
+%[- MARK -] \versionadded{2.1}
+%[- MARK -]
+%[- MARK -] +% When making changes to the examples in this file, be sure to update
+%[- MARK -] +% Lib/test/test_weakref.py::libreftest too!
+%[- MARK -]
+%[- MARK -] The \module{weakref} module allows the Python programmer to create
+%[- MARK -] \dfn{weak references} to objects.
+%[- MARK -]
+%[- MARK -] In the following, the term \dfn{referent} means the
+%[- MARK -] END DIFF
\versionadded{2.1}
@@ -49,6 +64,44 @@
necessitano - di regola non è necessario creare i propri riferimenti
deboli direttamente. L'implementazione di basso livello usata dal
dizionario debole viene mostrata dal modulo \module{weakref} per
+%[- MARK -] BEGIN DIFF 002 of 5
+%[- MARK -] @@ 46
+%[- MARK -] low-level machinery used by the weak dictionary implementations is exposed
+%[- MARK -] by the \module{weakref} module for the benefit of advanced uses.
+%[- MARK -]
+%[- MARK -] Not all objects can be weakly referenced; those objects which can
+%[- MARK -] include class instances, functions written in Python (but not in C),
+%[- MARK -] -and methods (both bound and unbound). Extension types can easily
+%[- MARK -] -be made to support weak references; see section \ref{weakref-extension},
+%[- MARK -] -``Weak References in Extension Types,'' for more information.
+%[- MARK -] +methods (both bound and unbound), sets, frozensets, file objects,
+%[- MARK -] +generators, type objects, DBcursor objects from the \module{bsddb} module,
+%[- MARK -] +sockets, arrays, deques, and regular expression pattern objects.
+%[- MARK -] +\versionchanged[Added support for files, sockets, arrays, and patterns]{2.4}
+%[- MARK -]
+%[- MARK -] +Several builtin types such as \class{list} and \class{dict} do not
+%[- MARK -] +directly support weak references but can add support through subclassing:
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{ref}{object\optional{, callback}}
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +class Dict(dict):
+%[- MARK -] + pass
+%[- MARK -] +
+%[- MARK -] +obj = Dict(red=1, green=2, blue=3) # this object is weak referencable
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +Extension types can easily be made to support weak references; see section
+%[- MARK -] +\ref{weakref-extension}, ``Weak References in Extension Types,'' for more
+%[- MARK -] +information.
+%[- MARK -] +
+%[- MARK -] +
+%[- MARK -] +\begin{classdesc}{ref}{object\optional{, callback}}
+%[- MARK -] Return a weak reference to \var{object}. The original object can be
+%[- MARK -] retrieved by calling the reference object if the referent is still
+%[- MARK -] alive; if the referent is no longer alive, calling the reference
+%[- MARK -] object will cause \constant{None} to be returned. If \var{callback} is
+%[- MARK -] provided and not \constant{None},
+%[- MARK -] END DIFF
beneficiarne negli usi più avanzati.
Non tutti gli oggetti possono venire riferiti debolmente;
@@ -86,6 +139,25 @@
l'\var{oggetto} è stato rimosso. Se la funzione \function{hash()}
viene chiamata per la prima volta solo dopo che l'\var{oggetto} è
stato rimosso, la chiamata solleverà un'eccezione
+%[- MARK -] BEGIN DIFF 003 of 5
+%[- MARK -] @@ 83
+%[- MARK -] the referents are still alive, two references have the same
+%[- MARK -] equality relationship as their referents (regardless of the
+%[- MARK -] \var{callback}). If either referent has been deleted, the
+%[- MARK -] references are equal only if the reference objects are the same
+%[- MARK -] object.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] +
+%[- MARK -] + \versionchanged[This is now a subclassable type rather than a
+%[- MARK -] + factory function; it derives from \class{object}]
+%[- MARK -] + {2.4}
+%[- MARK -] +\end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{proxy}{object\optional{, callback}}
+%[- MARK -] Return a proxy to \var{object} which uses a weak reference. This
+%[- MARK -] supports use of the proxy in most contexts instead of requiring the
+%[- MARK -] explicit dereferencing used with weak reference objects. The
+%[- MARK -] END DIFF
\exception{TypeError}.
I riferimenti deboli supportano i test di uguaglianza, ma non di
@@ -217,6 +289,21 @@
Per verificare che un oggetto con riferimento debole esista ancora, si
dovrà utilizzare l'espressione \code{\var{ref}() is not None}.
Normalmente, il codice di un'applicazione che necessita di usare un
+%[- MARK -] BEGIN DIFF 004 of 5
+%[- MARK -] @@ 207
+%[- MARK -] \begin{verbatim}
+%[- MARK -] # r is a weak reference object
+%[- MARK -] o = r()
+%[- MARK -] if o is None:
+%[- MARK -] # referent has been garbage collected
+%[- MARK -] - print "Object has been allocated; can't frobnicate."
+%[- MARK -] + print "Object has been deallocated; can't frobnicate."
+%[- MARK -] else:
+%[- MARK -] print "Object is still live!"
+%[- MARK -] o.do_something_useful()
+%[- MARK -] \end{verbatim}
+%[- MARK -]
+%[- MARK -] END DIFF
riferimento ad un oggetto dovrebbe seguire questo modello:
\begin{verbatim}
@@ -235,6 +322,51 @@
altro thread può provocare l'invalidamento di un riferimento debole
prima che questo venga chiamato (dal thread attuale - NDT); l'esempio
appena mostrato è sicuro sia in applicazioni multi thread che in
+%[- MARK -] BEGIN DIFF 005 of 5
+%[- MARK -] @@ 219
+%[- MARK -] threaded applications; another thread can cause a weak reference to
+%[- MARK -] become invalidated before the weak reference is called; the
+%[- MARK -] idiom shown above is safe in threaded applications as well as
+%[- MARK -] single-threaded applications.
+%[- MARK -]
+%[- MARK -] +Specialized versions of \class{ref} objects can be created through
+%[- MARK -] +subclassing. This is used in the implementation of the
+%[- MARK -] +\class{WeakValueDictionary} to reduce the memory overhead for each
+%[- MARK -] +entry in the mapping. This may be most useful to associate additional
+%[- MARK -] +information with a reference, but could also be used to insert
+%[- MARK -] +additional processing on calls to retrieve the referent.
+%[- MARK -] +
+%[- MARK -] +This example shows how a subclass of \class{ref} can be used to store
+%[- MARK -] +additional information about an object and affect the value that's
+%[- MARK -] +returned when the referent is accessed:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +import weakref
+%[- MARK -] +
+%[- MARK -] +class ExtendedRef(weakref.ref):
+%[- MARK -] + def __init__(self, ob, callback=None, **annotations):
+%[- MARK -] + super(ExtendedRef, self).__init__(ob, callback)
+%[- MARK -] + self.__counter = 0
+%[- MARK -] + for k, v in annotations.iteritems():
+%[- MARK -] + setattr(self, k, v)
+%[- MARK -] +
+%[- MARK -] + def __call__(self):
+%[- MARK -] + """Return a pair containing the referent and the number of
+%[- MARK -] + times the reference has been called.
+%[- MARK -] + """
+%[- MARK -] + ob = super(ExtendedRef, self).__call__()
+%[- MARK -] + if ob is not None:
+%[- MARK -] + self.__counter += 1
+%[- MARK -] + ob = (ob, self.__counter)
+%[- MARK -] + return ob
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -]
+%[- MARK -] \subsection{Example \label{weakref-example}}
+%[- MARK -]
+%[- MARK -] This simple example shows how an application can use objects IDs to
+%[- MARK -] retrieve objects that it has seen before. The IDs of the objects can
+%[- MARK -] END DIFF
applicazioni single thread.
Modified: python/python/Doc/branches/2.4.3/lib/libwhrandom.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libwhrandom.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libwhrandom.tex Fri Jun 2 12:52:55 2006
@@ -9,6 +9,22 @@
\note{Questo modulo era un componente del modulo \refmodule{random}
nelle versioni di Python antecedenti alla 2.1. Non viene più utilizzato.
Non usate questo modulo direttamente; usate \refmodule{random} al
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 12
+%[- MARK -] \refmodule{random} instead.}
+%[- MARK -]
+%[- MARK -] This module implements a Wichmann-Hill pseudo-random number generator
+%[- MARK -] class that is also named \class{whrandom}. Instances of the
+%[- MARK -] \class{whrandom} class conform to the Random Number Generator
+%[- MARK -] -interface described in section \ref{rng-objects}. They also offer the
+%[- MARK -] +interface described in the docs for the \refmodule{random} module.
+%[- MARK -] +They also offer the
+%[- MARK -] following method, specific to the Wichmann-Hill algorithm:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[whrandom]{seed}{\optional{x, y, z}}
+%[- MARK -] Initializes the random number generator from the integers \var{x},
+%[- MARK -] \var{y} and \var{z}. When the module is first imported, the random
+%[- MARK -] END DIFF
suo posto.}
Questo modulo implementa una classe generatrice di numeri
@@ -28,6 +44,21 @@
di inizializzazione apparentemente differenti sono uguali, con le
relative conseguenze nella serie di numeri pseudo casuali
prodotti dal generatore.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 27
+%[- MARK -] are replaced by ones. This causes some apparently different seeds
+%[- MARK -] to be equal, with the corresponding result on the pseudo-random
+%[- MARK -] series produced by the generator.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] +Other supported methods include:
+%[- MARK -] +
+%[- MARK -] \begin{funcdesc}{choice}{seq}
+%[- MARK -] Chooses a random element from the non-empty sequence \var{seq} and returns it.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{randint}{a, b}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{funcdesc}{choice}{seq}
Modified: python/python/Doc/branches/2.4.3/lib/libwinreg.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libwinreg.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libwinreg.tex Fri Jun 2 12:52:55 2006
@@ -24,6 +24,25 @@
\begin{funcdesc}{CloseKey}{hkey}
Chiude una chiave di registro precedentemente aperta. L'argomento
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 23
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{CloseKey}{hkey}
+%[- MARK -] Closes a previously opened registry key.
+%[- MARK -] The hkey argument specifies a previously opened key.
+%[- MARK -]
+%[- MARK -] - Note that if \var{hkey} is not closed using this method, (or the
+%[- MARK -] - \method{handle.Close()} closed when the \var{hkey} object is
+%[- MARK -] - destroyed by Python.
+%[- MARK -] + Note that if \var{hkey} is not closed using this method (or via
+%[- MARK -] + \method{handle.Close()}), it is closed when the \var{hkey} object
+%[- MARK -] + is destroyed by Python.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{ConnectRegistry}{computer_name, key}
+%[- MARK -] Establishes a connection to a predefined registry handle on
+%[- MARK -] END DIFF
hkey specifica la chiave precedentemente aperta.
Notare che \var{hkey} non permette di chiudere la chiave di
@@ -407,6 +426,23 @@
Questo oggetto supporta anche la semantica del confronto, così gli
oggetti gestori verranno valutati come uguali se si riferiscono al
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 385
+%[- MARK -]
+%[- MARK -] The object also support comparison semantics, so handle
+%[- MARK -] objects will compare true if they both reference the same
+%[- MARK -] underlying Windows handle value.
+%[- MARK -]
+%[- MARK -] - Handle objects can be converted to an integer (eg, using the
+%[- MARK -] - builtin \function{int()} function, in which case the underlying
+%[- MARK -] + Handle objects can be converted to an integer (e.g., using the
+%[- MARK -] + builtin \function{int()} function), in which case the underlying
+%[- MARK -] Windows handle value is returned. You can also use the
+%[- MARK -] \method{Detach()} method to return the integer handle, and
+%[- MARK -] also disconnect the Windows handle from the handle object.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{Close}{}
+%[- MARK -] END DIFF
medesimo valore sottostante del gestore Windows.
Gli oggetti gestori possono essere convertiti in un intero (per
Modified: python/python/Doc/branches/2.4.3/lib/libxmlrpclib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libxmlrpclib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libxmlrpclib.tex Fri Jun 2 12:52:55 2006
@@ -3,6 +3,21 @@
\declaremodule{standard}{xmlrpclib}
\modulesynopsis{Accesso a client XML-RPC.}
\moduleauthor{Fredrik Lundh}{fredrik a pythonware.com}
+%[- MARK -] BEGIN DIFF 001 of 7
+%[- MARK -] @@ 3
+%[- MARK -] \declaremodule{standard}{xmlrpclib}
+%[- MARK -] \modulesynopsis{XML-RPC client access.}
+%[- MARK -] \moduleauthor{Fredrik Lundh}{fredrik a pythonware.com}
+%[- MARK -] \sectionauthor{Eric S. Raymond}{esr a snark.thyrsus.com}
+%[- MARK -]
+%[- MARK -] -% Not everyting is documented yet. It might be good to describe
+%[- MARK -] +% Not everything is documented yet. It might be good to describe
+%[- MARK -] % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
+%[- MARK -]
+%[- MARK -] \versionadded{2.2}
+%[- MARK -]
+%[- MARK -] XML-RPC is a Remote Procedure Call method that uses XML passed via
+%[- MARK -] END DIFF
\sectionauthor{Eric S. Raymond}{esr a snark.thyrsus.com}
% Not everyting is documented yet. It might be good to describe
@@ -16,6 +31,21 @@
indicato da una URI) e gli vengono restituiti dei dati strutturati.
Questo modulo supporta la scrittura di codice client XML-RPC; gestisce
tutti i dettagli sulla traduzione tra oggetti Python conformi e XML
+%[- MARK -] BEGIN DIFF 002 of 7
+%[- MARK -] @@ 30
+%[- MARK -] fourth argument is a debugging flag. If \var{allow_none} is true,
+%[- MARK -] the Python constant \code{None} will be translated into XML; the
+%[- MARK -] default behaviour is for \code{None} to raise a \exception{TypeError}.
+%[- MARK -] This is a commonly-used extension to the XML-RPC specification, but isn't
+%[- MARK -] supported by all clients and servers; see
+%[- MARK -] -\url{http://ontosys.com/xml-rpc/extensions.html} for a description.
+%[- MARK -] +\url{http://ontosys.com/xml-rpc/extensions.php} for a description.
+%[- MARK -]
+%[- MARK -] Both the HTTP and HTTPS transports support the URL syntax extension for
+%[- MARK -] HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The
+%[- MARK -] \code{user:pass} portion will be base64-encoded as an HTTP `Authorization'
+%[- MARK -] header, and sent to the remote server as part of the connection process
+%[- MARK -] END DIFF
durante le operazioni.
\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
@@ -96,6 +126,28 @@
compatibiltà con il passato. Il nuovo codice dovrebbe usare
\class{ServerProxy}.
+%[- MARK -] BEGIN DIFF 003 of 7
+%[- MARK -] @@ 89
+%[- MARK -]
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{seealso}
+%[- MARK -] - \seetitle[http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto.html]
+%[- MARK -] + \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]
+%[- MARK -] {XML-RPC HOWTO}{A good description of XML operation and
+%[- MARK -] client software in several languages. Contains pretty much
+%[- MARK -] everything an XML-RPC client developer needs to know.}
+%[- MARK -] \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
+%[- MARK -] {XML-RPC-Hacks page}{Extensions for various open-source
+%[- MARK -] - libraries to support instrospection and multicall.}
+%[- MARK -] + libraries to support introspection and multicall.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{ServerProxy Objects \label{serverproxy-objects}}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{classdesc}
@@ -182,6 +234,21 @@
\end{methoddesc}
+%[- MARK -] BEGIN DIFF 004 of 7
+%[- MARK -] @@ 168
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{DateTime Objects \label{datetime-objects}}
+%[- MARK -]
+%[- MARK -] -This class may initialized from date in seconds since the epoch, a
+%[- MARK -] +This class may be initialized with seconds since the epoch, a
+%[- MARK -] time tuple, or an ISO 8601 time/date string. It has the following
+%[- MARK -] methods, supported mainly for internal use by the
+%[- MARK -] marshalling/unmarshalling code:
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{decode}{string}
+%[- MARK -] END DIFF
\subsection{Oggetti DateTime \label{datetime-objects}}
Questa classe può essere inizializzata dalla data in secondi da epoch,
@@ -196,6 +263,21 @@
\begin{methoddesc}{encode}{out}
Scrive la codifica XML-RPC di questo elemento DateTime sull'output
dell'oggetto flusso.
+%[- MARK -] BEGIN DIFF 005 of 7
+%[- MARK -] @@ 182
+%[- MARK -] \begin{methoddesc}{encode}{out}
+%[- MARK -] Write the XML-RPC encoding of this DateTime item to the out stream object.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] It also supports certain of Python's built-in operators through
+%[- MARK -] -\method{_cmp__} and \method{__repr__} methods.
+%[- MARK -] +\method{__cmp__} and \method{__repr__} methods.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{Binary Objects \label{binary-objects}}
+%[- MARK -]
+%[- MARK -] This class may initialized from string data (which may include NULs).
+%[- MARK -] END DIFF
\end{methoddesc}
Supporta anche alcuni operatori built-in di Python attraverso i metodi
@@ -225,6 +307,21 @@
\begin{methoddesc}[Binary]{encode}{out}
Scrive la codifica base64 XML-RPC di questo elemento binario
sull'output dell'oggetto flusso.
+%[- MARK -] BEGIN DIFF 006 of 7
+%[- MARK -] @@ 209
+%[- MARK -] Write the XML-RPC base 64 encoding of this binary item to the out
+%[- MARK -] stream object.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] It also supports certain of Python's built-in operators through a
+%[- MARK -] -\method{_cmp__()} method.
+%[- MARK -] +\method{__cmp__()} method.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsection{Fault Objects \label{fault-objects}}
+%[- MARK -]
+%[- MARK -] A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
+%[- MARK -] END DIFF
\end{methoddesc}
Supporta anche alcuni operati built-in di Python come il metodo
@@ -272,6 +369,25 @@
\subsection{Oggetti MultiCall}
+%[- MARK -] BEGIN DIFF 007 of 7
+%[- MARK -] @@ 254
+%[- MARK -]
+%[- MARK -] \subsection{MultiCall Objects}
+%[- MARK -]
+%[- MARK -] \versionadded{2.4}
+%[- MARK -]
+%[- MARK -] -In \url{http://www.xmlrpc.com/discuss/msgReader\$1208}, an approach
+%[- MARK -] -is presented to encapsulate multiple calls to a remote server into
+%[- MARK -] -a single request.
+%[- MARK -] +In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach
+%[- MARK -] +is presented to encapsulate multiple calls to a remote server into a
+%[- MARK -] +single request.
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{MultiCall}{server}
+%[- MARK -]
+%[- MARK -] Create an object used to boxcar method calls. \var{server} is the
+%[- MARK -] eventual target of the call. Calls can be made to the result object,
+%[- MARK -] END DIFF
\versionadded{2.4}
All'indirizzo \url{http://www.xmlrpc.com/discuss/msgReader\$1208},
Modified: python/python/Doc/branches/2.4.3/lib/libzipfile.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libzipfile.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libzipfile.tex Fri Jun 2 12:52:55 2006
@@ -33,6 +33,21 @@
\begin{classdesc*}{PyZipFile}
Classe per creare archivi ZIP contenenti librerie Python.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 34
+%[- MARK -] \begin{classdesc*}{PyZipFile}
+%[- MARK -] Class for creating ZIP archives containing Python libraries.
+%[- MARK -] \end{classdesc*}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
+%[- MARK -] - Class used the represent infomation about a member of an archive.
+%[- MARK -] + Class used to represent information about a member of an archive.
+%[- MARK -] Instances of this class are returned by the \method{getinfo()} and
+%[- MARK -] \method{infolist()} methods of \class{ZipFile} objects. Most users
+%[- MARK -] of the \module{zipfile} module will not need to create these, but
+%[- MARK -] only use those created by this module.
+%[- MARK -] \var{filename} should be the full name of the archive member, and
+%[- MARK -] END DIFF
\end{classdesc*}
\begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
Added: python/python/Doc/branches/2.4.3/lib/libzipimport.tex
==============================================================================
--- (empty file)
+++ python/python/Doc/branches/2.4.3/lib/libzipimport.tex Fri Jun 2 12:52:55 2006
@@ -0,0 +1,135 @@
+%[- MARK -] BEGIN PART 001 of 2
+\section{\module{zipimport} ---
+ Import modules from Zip archives}
+
+\declaremodule{standard}{zipimport}
+\modulesynopsis{support for importing Python modules from ZIP archives.}
+\moduleauthor{Just van Rossum}{just a letterror.com}
+
+\versionadded{2.3}
+
+This module adds the ability to import Python modules (\file{*.py},
+\file{*.py[co]}) and packages from ZIP-format archives. It is usually
+not needed to use the \module{zipimport} module explicitly; it is
+automatically used by the builtin \keyword{import} mechanism for
+\code{sys.path} items that are paths to ZIP archives.
+
+Typically, \code{sys.path} is a list of directory names as strings. This
+module also allows an item of \code{sys.path} to be a string naming a ZIP
+file archive. The ZIP archive can contain a subdirectory structure to
+support package imports, and a path within the archive can be specified to
+only import from a subdirectory. For example, the path
+\file{/tmp/example.zip/lib/} would only import from the
+\file{lib/} subdirectory within the archive.
+
+Any files may be present in the ZIP archive, but only files \file{.py} and
+\file{.py[co]} are available for import. ZIP import of dynamic modules
+(\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only
+contains \file{.py} files, Python will not attempt to modify the archive
+by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that
+if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather
+slow.
+
+Using the built-in \function{reload()} function will
+fail if called on a module loaded from a ZIP archive; it is unlikely that
+\function{reload()} would be needed, since this would imply that the ZIP
+has been altered during runtime.
+
+The available attributes of this module are:
+
+\begin{excdesc}{ZipImporterError}
+ Exception raised by zipimporter objects. It's a subclass of
+ \exception{ImportError}, so it can be caught as \exception{ImportError},
+ too.
+\end{excdesc}
+
+\begin{classdesc*}{zipimporter}
+ The class for importing ZIP files. See
+ ``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects})
+ for constructor details.
+\end{classdesc*}
+
+
+\begin{seealso}
+ \seetitle[http://www.pkware.com/appnote.html]{PKZIP Application
+ Note}{Documentation on the ZIP file format by Phil
+ Katz, the creator of the format and algorithms used.}
+
+ \seepep{0273}{Import Modules from Zip Archives}{Written by James C.
+ Ahlstrom, who also provided an implementation. Python 2.3
+ follows the specification in PEP 273, but uses an
+ implementation written by Just van Rossum that uses the import
+ hooks described in PEP 302.}
+
+ \seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help
+ this module work.}
+\end{seealso}
+
+
+\subsection{zipimporter Objects \label{zipimporter-objects}}
+
+\begin{classdesc}{zipimporter}{archivepath}
+ Create a new zipimporter instance. \var{archivepath} must be a path to
+ a zipfile. \class{ZipImportError} is raised if \var{archivepath} doesn't
+ point to a valid ZIP archive.
+\end{classdesc}
+
+\begin{methoddesc}{find_module}{fullname\optional{, path}}
+ Search for a module specified by \var{fullname}. \var{fullname} must be
+ the fully qualified (dotted) module name. It returns the zipimporter
+ instance itself if the module was found, or \constant{None} if it wasn't.
+ The optional \var{path} argument is ignored---it's there for
+ compatibility with the importer protocol.
+\end{methoddesc}
+
+\begin{methoddesc}{get_code}{fullname}
+ Return the code object for the specified module. Raise
+ \class{ZipImportError} if the module couldn't be found.
+\end{methoddesc}
+
+\begin{methoddesc}{get_data}{pathname}
+ Return the data associated with \var{pathname}. Raise \exception{IOError}
+ if the file wasn't found.
+\end{methoddesc}
+
+\begin{methoddesc}{get_source}{fullname}
+ Return the source code for the specified module. Raise
+ \class{ZipImportError} if the module couldn't be found, return
+ \constant{None} if the archive does contain the module, but has
+ no source for it.
+\end{methoddesc}
+
+%[- MARK -] BEGIN PART 002 of 2
+\begin{methoddesc}{is_package}{fullname}
+ Return True if the module specified by \var{fullname} is a package.
+ Raise \class{ZipImportError} if the module couldn't be found.
+\end{methoddesc}
+
+\begin{methoddesc}{load_module}{fullname}
+ Load the module specified by \var{fullname}. \var{fullname} must be the
+ fully qualified (dotted) module name. It returns the imported
+ module, or raises \class{ZipImportError} if it wasn't found.
+\end{methoddesc}
+
+\subsection{Examples}
+\nodename{zipimport Examples}
+
+Here is an example that imports a module from a ZIP archive - note that
+the \module{zipimport} module is not explicitly used.
+
+\begin{verbatim}
+$ unzip -l /tmp/example.zip
+Archive: /tmp/example.zip
+ Length Date Time Name
+ -------- ---- ---- ----
+ 8467 11-26-02 22:30 jwzthreading.py
+ -------- -------
+ 8467 1 file
+$ ./python
+Python 2.3 (#1, Aug 1 2003, 19:54:32)
+>>> import sys
+>>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
+>>> import jwzthreading
+>>> jwzthreading.__file__
+'/tmp/example.zip/jwzthreading.py'
+\end{verbatim}
Modified: python/python/Doc/branches/2.4.3/lib/libzlib.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/libzlib.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/libzlib.tex Fri Jun 2 12:52:55 2006
@@ -3,6 +3,28 @@
\declaremodule{builtin}{zlib}
\modulesynopsis{Interfaccia di basso livello di routine per la
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 6
+%[- MARK -] routines compatible with \program{gzip}.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] For applications that require data compression, the functions in this
+%[- MARK -] module allow compression and decompression, using the zlib library.
+%[- MARK -] -The zlib library has its own home page at
+%[- MARK -] -\url{http://www.gzip.org/zlib/}. Version 1.1.3 is the
+%[- MARK -] -most recent version as of September 2000; use a later version if one
+%[- MARK -] -is available. There are known incompatibilities between the Python
+%[- MARK -] -module and earlier versions of the zlib library.
+%[- MARK -] +The zlib library has its own home page at \url{http://www.gzip.org/zlib/}.
+%[- MARK -] +There are known incompatibilities between the Python module and
+%[- MARK -] +versions of the zlib library earlier than 1.1.3; 1.1.3 has a security
+%[- MARK -] +vulnerability, so we recommend using 1.1.4 or later.
+%[- MARK -]
+%[- MARK -] The available exception and functions in this module are:
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{error}
+%[- MARK -] Exception raised on compression and decompression errors.
+%[- MARK -] END DIFF
compressione e decompressione, compatibile con \program{gzip}.}
@@ -153,6 +175,21 @@
dovete alimentarli (possibilmente con ulteriori concatenazioni) con
una successiva chiamata al metodo \method{decompress}, in modo da
ottenere l'output corretto.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 144
+%[- MARK -] concatenated to it) back to a subsequent \method{decompress} method
+%[- MARK -] call in order to get correct output.
+%[- MARK -] \end{memberdesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[Decompress]{decompress}{string}{\optional{max_length}}
+%[- MARK -] +\begin{methoddesc}[Decompress]{decompress}{string\optional{, max_length}}
+%[- MARK -] Decompress \var{string}, returning a string containing the
+%[- MARK -] uncompressed data corresponding to at least part of the data in
+%[- MARK -] \var{string}. This data should be concatenated to the output produced
+%[- MARK -] by any preceding calls to the
+%[- MARK -] \method{decompress()} method. Some of the input data may be preserved
+%[- MARK -] END DIFF
\end{memberdesc}
Modified: python/python/Doc/branches/2.4.3/lib/xmldom.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/xmldom.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/xmldom.tex Fri Jun 2 12:52:55 2006
@@ -78,6 +78,23 @@
conformità non viene richiesta (le implementazioni sono libere
comunque di supportare una stretta aderenza all'IDL). Vedere la
sezione \ref{dom-conformance}, ``Conformità,'' per una dettagliata
+%[- MARK -] BEGIN DIFF 001 of 8
+%[- MARK -] @@ 82
+%[- MARK -] {The W3C recommendation for the
+%[- MARK -] DOM supported by \module{xml.dom.minidom}.}
+%[- MARK -] \seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
+%[- MARK -] full-featured implementation of DOM should use the PyXML
+%[- MARK -] package.}
+%[- MARK -] - \seetitle[http://cgi.omg.org/cgi-bin/doc?orbos/99-08-02.pdf]{CORBA
+%[- MARK -] - Scripting with Python}
+%[- MARK -] + \seetitle[http://www.omg.org/docs/formal/02-11-05.pdf]{Python
+%[- MARK -] + Language Mapping Specification}
+%[- MARK -] {This specifies the mapping from OMG IDL to Python.}
+%[- MARK -] \end{seealso}
+%[- MARK -]
+%[- MARK -] \subsection{Module Contents}
+%[- MARK -]
+%[- MARK -] END DIFF
discussione dei requisiti di conformità.
@@ -226,6 +243,37 @@
particolari opzioni nel DOM di cui tali applicazioni hanno bisogno.
Il DOM di livello 2 aggiunge la particolare facoltà di creare nuovi
oggetti \class{Document} e \class{DocumentType} usando direttamente
+%[- MARK -] BEGIN DIFF 002 of 8
+%[- MARK -] @@ 211
+%[- MARK -] the DOM they are using. DOM Level~2 added the ability to create new
+%[- MARK -] \class{Document} and \class{DocumentType} objects using the
+%[- MARK -] \class{DOMImplementation} as well.
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
+%[- MARK -] +Return true if the feature identified by the pair of strings
+%[- MARK -] +\var{feature} and \var{version} is implemented.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[DOMImplementation]{createDocument}{namespaceUri, qualifiedName, doctype}
+%[- MARK -] +Return a new \class{Document} object (the root of the DOM), with a
+%[- MARK -] +child \class{Element} object having the given \var{namespaceUri} and
+%[- MARK -] +\var{qualifiedName}. The \var{doctype} must be a \class{DocumentType}
+%[- MARK -] +object created by \method{createDocumentType()}, or \code{None}.
+%[- MARK -] +In the Python DOM API, the first two arguments can also be \code{None}
+%[- MARK -] +in order to indicate that no \class{Element} child is to be created.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[DOMImplementation]{createDocumentType}{qualifiedName, publicId, systemId}
+%[- MARK -] +Return a new \class{DocumentType} object that encapsulates the given
+%[- MARK -] +\var{qualifiedName}, \var{publicId}, and \var{systemId} strings,
+%[- MARK -] +representing the information contained in an XML document type
+%[- MARK -] +declaration.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \subsubsection{Node Objects \label{dom-node-objects}}
+%[- MARK -]
+%[- MARK -] END DIFF
\class{DOMImplementation}.
\begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
@@ -355,6 +403,23 @@
\begin{methoddesc}[Node]{appendChild}{newChild}
Aggiunge un nuovo nodo figlio per questo nodo alla fine della lista
dei figli, restituendo \var{newChild}.
+%[- MARK -] BEGIN DIFF 003 of 8
+%[- MARK -] @@ 338
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
+%[- MARK -] Insert a new child node before an existing child. It must be the case
+%[- MARK -] that \var{refChild} is a child of this node; if not,
+%[- MARK -] -\exception{ValueError} is raised. \var{newChild} is returned.
+%[- MARK -] +\exception{ValueError} is raised. \var{newChild} is returned. If
+%[- MARK -] +\var{refChild} is \code{None}, it inserts \var{newChild} at the end of
+%[- MARK -] +the children's list.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Node]{removeChild}{oldChild}
+%[- MARK -] Remove a child node. \var{oldChild} must be a child of this node; if
+%[- MARK -] not, \exception{ValueError} is raised. \var{oldChild} is returned on
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
@@ -572,6 +637,56 @@
\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
Come l'equivalente metodo nella classe \class{Document}.
+%[- MARK -] BEGIN DIFF 004 of 8
+%[- MARK -] @@ 541
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
+%[- MARK -] Same as equivalent method in the \class{Document} class.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[Element]{getAttribute}{attname}
+%[- MARK -] -Return an attribute value as a string.
+%[- MARK -] +\begin{methoddesc}[Element]{hasAttribute}{name}
+%[- MARK -] +Returns true if the element has an attribute named by \var{name}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[Element]{hasAttributeNS}{namespaceURI, localName}
+%[- MARK -] +Returns true if the element has an attribute named by
+%[- MARK -] +\var{namespaceURI} and \var{localName}.
+%[- MARK -] +\end{methoddesc}
+%[- MARK -] +
+%[- MARK -] +\begin{methoddesc}[Element]{getAttribute}{name}
+%[- MARK -] +Return the value of the attribute named by \var{name} as a
+%[- MARK -] +string. If no such attribute exists, an empty string is returned,
+%[- MARK -] +as if the attribute had no value.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{getAttributeNode}{attrname}
+%[- MARK -] Return the \class{Attr} node for the attribute named by
+%[- MARK -] \var{attrname}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName}
+%[- MARK -] -Return an attribute value as a string, given a \var{namespaceURI} and
+%[- MARK -] -\var{localName}.
+%[- MARK -] +Return the value of the attribute named by \var{namespaceURI} and
+%[- MARK -] +\var{localName} as a string. If no such attribute exists, an empty
+%[- MARK -] +string is returned, as if the attribute had no value.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{getAttributeNodeNS}{namespaceURI, localName}
+%[- MARK -] Return an attribute value as a node, given a \var{namespaceURI} and
+%[- MARK -] \var{localName}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[Element]{removeAttribute}{attname}
+%[- MARK -] +\begin{methoddesc}[Element]{removeAttribute}{name}
+%[- MARK -] Remove an attribute by name. No exception is raised if there is no
+%[- MARK -] matching attribute.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{removeAttributeNode}{oldAttr}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[Element]{getAttribute}{attname}
@@ -608,6 +723,36 @@
Rimuove un attributo per nome. Notare che viene usato
\var{localName}, non un \var{qname}. Nessuna eccezione viene
sollevata se non ci sono attributi corrispondenti.
+%[- MARK -] BEGIN DIFF 005 of 8
+%[- MARK -] @@ 575
+%[- MARK -] \begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName}
+%[- MARK -] Remove an attribute by name. Note that it uses a localName, not a
+%[- MARK -] qname. No exception is raised if there is no matching attribute.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] -\begin{methoddesc}[Element]{setAttribute}{attname, value}
+%[- MARK -] +\begin{methoddesc}[Element]{setAttribute}{name, value}
+%[- MARK -] Set an attribute value from a string.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{setAttributeNode}{newAttr}
+%[- MARK -] -Add a new attibute node to the element, replacing an existing
+%[- MARK -] +Add a new attribute node to the element, replacing an existing
+%[- MARK -] attribute if necessary if the \member{name} attribute matches. If a
+%[- MARK -] replacement occurs, the old attribute node will be returned. If
+%[- MARK -] \var{newAttr} is already in use, \exception{InuseAttributeErr} will be
+%[- MARK -] raised.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[Element]{setAttributeNodeNS}{newAttr}
+%[- MARK -] -Add a new attibute node to the element, replacing an existing
+%[- MARK -] +Add a new attribute node to the element, replacing an existing
+%[- MARK -] attribute if necessary if the \member{namespaceURI} and
+%[- MARK -] \member{localName} attributes match. If a replacement occurs, the old
+%[- MARK -] attribute node will be returned. If \var{newAttr} is already in use,
+%[- MARK -] \exception{InuseAttributeErr} will be raised.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[Element]{setAttribute}{attname, value}
@@ -665,6 +810,21 @@
\begin{memberdesc}[NamedNodeMap]{length}
La lunghezza della lista degli attributi.
+%[- MARK -] BEGIN DIFF 006 of 8
+%[- MARK -] @@ 635
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}[NamedNodeMap]{item}{index}
+%[- MARK -] Return an attribute with a particular index. The order you get the
+%[- MARK -] attributes in is arbitrary but will be consistent for the life of a
+%[- MARK -] DOM. Each item is an attribute node. Get its value with the
+%[- MARK -] -\member{value} attribbute.
+%[- MARK -] +\member{value} attribute.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] There are also experimental methods that give this class more mapping
+%[- MARK -] behavior. You can use them or you can use the standardized
+%[- MARK -] \method{getAttribute*()} family of methods on the \class{Element}
+%[- MARK -] END DIFF
\end{memberdesc}
\begin{methoddesc}[NamedNodeMap]{item}{index}
@@ -794,6 +954,21 @@
\begin{excdesc}{InvalidModificationErr}
Viene sollevata quando viene effettuato un tentativo di modificare il tipo di un nodo.
+%[- MARK -] BEGIN DIFF 007 of 8
+%[- MARK -] @@ 758
+%[- MARK -] \begin{excdesc}{InvalidModificationErr}
+%[- MARK -] Raised when an attempt is made to modify the type of a node.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{InvalidStateErr}
+%[- MARK -] - Raised when an attempt is made to use an object that is not or is no
+%[- MARK -] + Raised when an attempt is made to use an object that is not defined or is no
+%[- MARK -] longer usable.
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{NamespaceErr}
+%[- MARK -] If an attempt is made to change any object in a way that is not
+%[- MARK -] END DIFF
\end{excdesc}
\begin{excdesc}{InvalidStateErr}
@@ -922,6 +1097,25 @@
con esperienza nell'uso di DOM e CORBA in Python non considera questo
un problema. Gli attributi che vengono dichiarati in sola lettura,
\keyword{readonly}, possono non limitare l'accesso in scrittura in
+%[- MARK -] BEGIN DIFF 008 of 8
+%[- MARK -] @@ 882
+%[- MARK -] clients, the implementers with experience using DOM over CORBA from
+%[- MARK -] Python do not consider this a problem. Attributes that are declared
+%[- MARK -] \keyword{readonly} may not restrict write access in all DOM
+%[- MARK -] implementations.
+%[- MARK -]
+%[- MARK -] -Additionally, the accessor functions are not required. If provided,
+%[- MARK -] +In the Python DOM API, accessor functions are not required. If provided,
+%[- MARK -] they should take the form defined by the Python IDL mapping, but
+%[- MARK -] these methods are considered unnecessary since the attributes are
+%[- MARK -] accessible directly from Python. ``Set'' accessors should never be
+%[- MARK -] provided for \keyword{readonly} attributes.
+%[- MARK -] +
+%[- MARK -] +The IDL definitions do not fully embody the requirements of the W3C DOM
+%[- MARK -] +API, such as the notion of certain objects, such as the return value of
+%[- MARK -] +\method{getElementsByTagName()}, being ``live''. The Python DOM API
+%[- MARK -] +does not require implementations to enforce such requirements.
+%[- MARK -] END DIFF
tutte le implementazioni DOM.
In aggiunta, la funzione di accesso non viene richiesta. Se fornita,
Modified: python/python/Doc/branches/2.4.3/lib/xmlsaxhandler.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/lib/xmlsaxhandler.tex (original)
+++ python/python/Doc/branches/2.4.3/lib/xmlsaxhandler.tex Fri Jun 2 12:52:55 2006
@@ -6,6 +6,21 @@
\sectionauthor{Martin v. L\"owis}{martin a v.loewis.de}
\moduleauthor{Lars Marius Garshol}{larsga a garshol.priv.no}
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 12
+%[- MARK -] The SAX API defines four kinds of handlers: content handlers, DTD
+%[- MARK -] handlers, error handlers, and entity resolvers. Applications normally
+%[- MARK -] only need to implement those interfaces whose events they are
+%[- MARK -] interested in; they can implement the interfaces in a single object or
+%[- MARK -] in multiple objects. Handler implementations should inherit from the
+%[- MARK -] -base classes provided in the module \module{xml.sax}, so that all
+%[- MARK -] +base classes provided in the module \module{xml.sax.handler}, so that all
+%[- MARK -] methods get default implementations.
+%[- MARK -]
+%[- MARK -] \begin{classdesc*}{ContentHandler}
+%[- MARK -] This is the main callback interface in SAX, and the one most
+%[- MARK -] important to applications. The order of events in this interface
+%[- MARK -] END DIFF
\versionadded{2.0}
@@ -65,6 +80,21 @@
spazio dei nomi e, facoltativamente non riporta il prefisso
originale (predefinito).\\
accesso: (analisi) sola lettura; (non analisi) lettura/scrittura.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 63
+%[- MARK -] optionally do not report original prefixed names (default).\\
+%[- MARK -] access: (parsing) read-only; (not parsing) read/write
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{feature_string_interning}
+%[- MARK -] - Value: \code{"http://xml.org/sax/features/string-interning"}
+%[- MARK -] + Value: \code{"http://xml.org/sax/features/string-interning"}\\
+%[- MARK -] true: All element names, prefixes, attribute names, Namespace URIs, and
+%[- MARK -] local names are interned using the built-in intern function.\\
+%[- MARK -] false: Names are not necessarily interned, although they may be (default).\\
+%[- MARK -] access: (parsing) read-only; (not parsing) read/write
+%[- MARK -] \end{datadesc}
+%[- MARK -] END DIFF
\end{datadesc}
\begin{datadesc}{feature_string_interning}
Modified: python/python/Doc/branches/2.4.3/mac/libaetypes.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libaetypes.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libaetypes.tex Fri Jun 2 12:52:55 2006
@@ -127,6 +127,21 @@
equivalenti agli specificatori d'oggetto AppleScript. \`E necessario
passare all'istanziazione di un selettore \code{which} e,
facoltativamente, un oggetto parent \code{fr}.
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 119
+%[- MARK -] Specifiers. Upon instantiation you should pass a selector in
+%[- MARK -] \code{which}, and optionally a parent object in \code{fr}.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] \begin{classdesc}{NProperty}{fr}
+%[- MARK -] -Abstract basclass for an OSA property. The subclass should set the class
+%[- MARK -] +Abstract baseclass for an OSA property. The subclass should set the class
+%[- MARK -] attributes \code{want} and \code{which} to designate which property we
+%[- MARK -] are talking about. Instances of subclasses of this class are Object
+%[- MARK -] Specifiers.
+%[- MARK -] \end{classdesc}
+%[- MARK -]
+%[- MARK -] END DIFF
\end{classdesc}
\begin{classdesc}{NProperty}{fr}
Modified: python/python/Doc/branches/2.4.3/mac/libframework.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libframework.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libframework.tex Fri Jun 2 12:52:55 2006
@@ -13,6 +13,22 @@
funzionalità desiderata. Sovrascrivere funzionalità spesso può essere
fatto in vari differenti livelli, cioè, per gestire click in una
singola finestra di dialogo in modo non standard non è necessario
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 13
+%[- MARK -] wanted. Overriding functionality can often be done on various
+%[- MARK -] different levels, i.e. to handle clicks in a single dialog window in a
+%[- MARK -] non-standard way it is not necessary to override the complete event
+%[- MARK -] handling.
+%[- MARK -]
+%[- MARK -] -The \module{FrameWork} is still very much work-in-progress, and the
+%[- MARK -] +Work on the \module{FrameWork} has pretty much stopped, now that
+%[- MARK -] +\module{PyObjC} is available for full Cocoa access from Python, and the
+%[- MARK -] documentation describes only the most important functionality, and not
+%[- MARK -] in the most logical manner at that. Examine the source or the examples
+%[- MARK -] for more details. The following are some comments posted on the
+%[- MARK -] MacPython newsgroup about the strengths and limitations of
+%[- MARK -] \module{FrameWork}:
+%[- MARK -] END DIFF
sovrascrivere completamente la gestione dell'evento.
Il \module{FrameWork} è perennemente in lavorazione, la documentazione
@@ -153,6 +169,21 @@
all'interno di \var{our_dispatch} o dalle sue chiamate, da questo può
risultare un ciclo infinito se il codice viene chiamato attraverso il
ciclo interno del gestore di eventi di Python.
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 149
+%[- MARK -] asynchronous event handling. This will tell the inner interpreter loop
+%[- MARK -] to call the application event handler \var{async_dispatch} whenever events
+%[- MARK -] are available. This will cause FrameWork window updates and the user
+%[- MARK -] interface to remain working during long computations, but will slow the
+%[- MARK -] interpreter down and may cause surprising results in non-reentrant code
+%[- MARK -] -(such as FrameWork itself). By default \var{async_dispatch} will immedeately
+%[- MARK -] +(such as FrameWork itself). By default \var{async_dispatch} will immediately
+%[- MARK -] call \var{our_dispatch} but you may override this to handle only certain
+%[- MARK -] events asynchronously. Events you do not handle will be passed to Sioux
+%[- MARK -] and such.
+%[- MARK -]
+%[- MARK -] The old on/off value is returned.
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}[Application]{asyncevents}{onoff}
Modified: python/python/Doc/branches/2.4.3/mac/libmacfs.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libmacfs.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libmacfs.tex Fri Jun 2 12:52:55 2006
@@ -4,6 +4,22 @@
\declaremodule{standard}{macfs}
\platform{Mac}
\modulesynopsis{Supporto per FSSpec, l'Alias Manager, l'alias di
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 7
+%[- MARK -] \program{finder} aliases, and the Standard File package.}
+%[- MARK -]
+%[- MARK -] \deprecated{2.3}{The macfs module should be considered obsolete. For
+%[- MARK -] \class{FSSpec}, \class{FSRef} and \class{Alias} handling use the
+%[- MARK -] \module{Carbon.File} or \refmodule{Carbon.Folder} module. For file
+%[- MARK -] -dialogs use the \refmodule{EasyDialogs} module.}
+%[- MARK -] +dialogs use the \refmodule{EasyDialogs} module. Also, this module is
+%[- MARK -] +known to not work correctly with UFS partitions.}
+%[- MARK -]
+%[- MARK -] This module provides access to Macintosh \class{FSSpec} handling, the
+%[- MARK -] Alias Manager, \program{finder} aliases and the Standard File package.
+%[- MARK -] \index{Macintosh Alias Manager}
+%[- MARK -] \index{Alias Manager, Macintosh}
+%[- MARK -] END DIFF
\program{finder} e il File package standard.}
\deprecated{2.3}{Si può considerare obsoleto il
Modified: python/python/Doc/branches/2.4.3/mac/libmacic.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libmacic.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libmacic.tex Fri Jun 2 12:52:55 2006
@@ -3,6 +3,28 @@
\declaremodule{builtin}{ic}
\platform{Mac}
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 4
+%[- MARK -] \declaremodule{builtin}{ic}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Access to Internet Config.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] -This module provides access to Macintosh Internet
+%[- MARK -] -Config\index{Internet Config} package,
+%[- MARK -] -which stores preferences for Internet programs such as mail address,
+%[- MARK -] -default homepage, etc. Also, Internet Config contains an elaborate set
+%[- MARK -] -of mappings from Macintosh creator/type codes to foreign filename
+%[- MARK -] -extensions plus information on how to transfer files (binary, ascii,
+%[- MARK -] -etc.). Since MacOS 9, this module is a control panel named Internet.
+%[- MARK -] +This module provides access to various internet-related preferences
+%[- MARK -] +set through \program{System Preferences} or the \program{Finder}.
+%[- MARK -]
+%[- MARK -] There is a low-level companion module
+%[- MARK -] \module{icglue}\refbimodindex{icglue} which provides the basic
+%[- MARK -] Internet Config access functionality. This low-level module is not
+%[- MARK -] documented, but the docstrings of the routines document the parameters
+%[- MARK -] END DIFF
\modulesynopsis{Accesso ad Internet Config.}
@@ -73,6 +95,21 @@
consentiti anche per l'assegnamento.
Rispetto al dizionario d'interfaccia, gli oggetti \class{IC} hanno i
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 72
+%[- MARK -] Besides the dictionary interface, \class{IC} objects have the
+%[- MARK -] following methods:
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{launchurl}{url\optional{, hint}}
+%[- MARK -] -Parse the given URL, lauch the correct application and pass it the
+%[- MARK -] +Parse the given URL, launch the correct application and pass it the
+%[- MARK -] URL. The optional \var{hint} can be a scheme name such as
+%[- MARK -] \code{'mailto:'}, in which case incomplete URLs are completed with this
+%[- MARK -] scheme. If \var{hint} is not provided, incomplete URLs are invalid.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] END DIFF
seguenti metodi:
@@ -94,6 +131,21 @@
l'intero URL dove l'utente ha premuto il mouse. Come sopra,
\var{hint} è uno schema facoltativo usato per completare gli URL
incompleti.
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 90
+%[- MARK -] complete incomplete URLs.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{mapfile}{file}
+%[- MARK -] Return the mapping entry for the given \var{file}, which can be passed
+%[- MARK -] -as either a filename or an \function{macfs.FSSpec()} result, and which
+%[- MARK -] +as either a filename or an \function{FSSpec()} result, and which
+%[- MARK -] need not exist.
+%[- MARK -]
+%[- MARK -] The mapping entry is returned as a tuple \code{(\var{version},
+%[- MARK -] \var{type}, \var{creator}, \var{postcreator}, \var{flags},
+%[- MARK -] \var{extension}, \var{appname}, \var{postappname}, \var{mimetype},
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{mapfile}{file}
@@ -125,6 +177,19 @@
La voce mappata viene restituita nello stesso formato per
\var{mapfile}.
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 120
+%[- MARK -] The mapping entry is returned in the same format as for \var{mapfile}.
+%[- MARK -] \end{methoddesc}
+%[- MARK -]
+%[- MARK -] \begin{methoddesc}{settypecreator}{file}
+%[- MARK -] Given an existing \var{file}, specified either as a filename or as an
+%[- MARK -] -\function{macfs.FSSpec()} result, set its creator and type correctly based
+%[- MARK -] +\function{FSSpec()} result, set its creator and type correctly based
+%[- MARK -] on its extension. The finder is told about the change, so the finder
+%[- MARK -] icon will be updated quickly.
+%[- MARK -] \end{methoddesc}
+%[- MARK -] END DIFF
\end{methoddesc}
\begin{methoddesc}{settypecreator}{file}
Modified: python/python/Doc/branches/2.4.3/mac/libmacos.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libmacos.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libmacos.tex Fri Jun 2 12:52:55 2006
@@ -13,6 +13,40 @@
attenzione.
Si noti l'uso delle maiuscole nel nome del modulo; questo deriva da
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 12
+%[- MARK -]
+%[- MARK -] Note the capitalization of the module name; this is a historical
+%[- MARK -] artifact.
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{runtimemodel}
+%[- MARK -] -Either\code{'carbon'} or \code{'macho'}. This
+%[- MARK -] -signifies whether this Python uses the Mac OS X and Mac OS 9 compatible
+%[- MARK -] -CarbonLib style or the Mac OS
+%[- MARK -] -X-only Mach-O style. In earlier versions of Python the value could
+%[- MARK -] -also be \code{'ppc'} for the classic Mac OS 8 runtime model.
+%[- MARK -] +Always \code{'macho'}, from Python 2.4 on.
+%[- MARK -] +In earlier versions of Python the value could
+%[- MARK -] +also be \code{'ppc'} for the classic Mac OS 8 runtime model or
+%[- MARK -] +\code{'carbon'} for the Mac OS 9 runtime model.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{datadesc}{linkmodel}
+%[- MARK -] The way the interpreter has been linked. As extension modules may be
+%[- MARK -] incompatible between linking models, packages could use this information to give
+%[- MARK -] more decent error messages. The value is one of \code{'static'} for a
+%[- MARK -] statically linked Python, \code{'framework'} for Python in a Mac OS X framework,
+%[- MARK -] -\code{'shared'} for Python in a standard unix shared library and
+%[- MARK -] -\code{'cfm'} for the Mac OS 9-compatible Python.
+%[- MARK -] +\code{'shared'} for Python in a standard unix shared library.
+%[- MARK -] +Older Pythons could also have the value
+%[- MARK -] +\code{'cfm'} for Mac OS 9-compatible Python.
+%[- MARK -] \end{datadesc}
+%[- MARK -]
+%[- MARK -] \begin{excdesc}{Error}
+%[- MARK -] This exception is raised on MacOS generated errors, either from
+%[- MARK -] functions in this module or from other mac-specific modules like the
+%[- MARK -] END DIFF
una lunga storia.
\begin{datadesc}{runtimemodel}
@@ -41,6 +75,101 @@
una descrizione testuale del codice d'errore. Nel modulo
\refmodule{macerrors}\refstmodindex{macerrors} vengono definiti i
nomi simbolici per tutti i codici d'errore conosciuti.
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 37
+%[- MARK -] \cdata{OSErr} value) and a textual description of the error code.
+%[- MARK -] Symbolic names for all known error codes are defined in the standard
+%[- MARK -] module \refmodule{macerrors}.\refstmodindex{macerrors}
+%[- MARK -] \end{excdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{SetEventHandler}{handler}
+%[- MARK -] -In the inner interpreter loop Python will occasionally check for events,
+%[- MARK -] -unless disabled with \function{ScheduleParams()}. With this function you
+%[- MARK -] -can pass a Python event-handler function that will be called if an event
+%[- MARK -] -is available. The event is passed as parameter and the function should return
+%[- MARK -] -non-zero if the event has been fully processed, otherwise event processing
+%[- MARK -] -continues (by passing the event to the console window package, for instance).
+%[- MARK -] -
+%[- MARK -] -Call \function{SetEventHandler()} without a parameter to clear the
+%[- MARK -] -event handler. Setting an event handler while one is already set is an
+%[- MARK -] -error.
+%[- MARK -] -
+%[- MARK -] -Availability: MacPython-OS9.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{,
+%[- MARK -] - besocial\optional{, interval\optional{,
+%[- MARK -] - bgyield}}}}}}
+%[- MARK -] -Influence the interpreter inner loop event handling. \var{Interval}
+%[- MARK -] -specifies how often (in seconds, floating point) the interpreter
+%[- MARK -] -should enter the event processing code. When true, \var{doint} causes
+%[- MARK -] -interrupt (command-dot) checking to be done. \var{evtmask} tells the
+%[- MARK -] -interpreter to do event processing for events in the mask (redraws,
+%[- MARK -] -mouseclicks to switch to other applications, etc). The \var{besocial}
+%[- MARK -] -flag gives other processes a chance to run. They are granted minimal
+%[- MARK -] -runtime when Python is in the foreground and \var{bgyield} seconds per
+%[- MARK -] -\var{interval} when Python runs in the background.
+%[- MARK -] -
+%[- MARK -] -All parameters are optional, and default to the current value. The return
+%[- MARK -] -value of this function is a tuple with the old values of these options.
+%[- MARK -] -Initial defaults are that all processing is enabled, checking is done every
+%[- MARK -] -quarter second and the processor is given up for a quarter second when in the
+%[- MARK -] -background.
+%[- MARK -] -
+%[- MARK -] -The most common use case is to call \code{SchedParams(0, 0)} to completely disable
+%[- MARK -] -event handling in the interpreter mainloop.
+%[- MARK -] -
+%[- MARK -] -Availability: MacPython-OS9.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] -\begin{funcdesc}{HandleEvent}{ev}
+%[- MARK -] -Pass the event record \var{ev} back to the Python event loop, or
+%[- MARK -] -possibly to the handler for the \code{sys.stdout} window (based on the
+%[- MARK -] -compiler used to build Python). This allows Python programs that do
+%[- MARK -] -their own event handling to still have some command-period and
+%[- MARK -] -window-switching capability.
+%[- MARK -] -
+%[- MARK -] -If you attempt to call this function from an event handler set through
+%[- MARK -] -\function{SetEventHandler()} you will get an exception.
+%[- MARK -] -
+%[- MARK -] -Availability: MacPython-OS9.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{GetErrorString}{errno}
+%[- MARK -] Return the textual description of MacOS error code \var{errno}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] -\begin{funcdesc}{splash}{resid}
+%[- MARK -] -This function will put a splash window
+%[- MARK -] -on-screen, with the contents of the DLOG resource specified by
+%[- MARK -] -\var{resid}. Calling with a zero argument will remove the splash
+%[- MARK -] -screen. This function is useful if you want an applet to post a splash screen
+%[- MARK -] -early in initialization without first having to load numerous
+%[- MARK -] -extension modules.
+%[- MARK -] -
+%[- MARK -] -Availability: MacPython-OS9.
+%[- MARK -] -\end{funcdesc}
+%[- MARK -] -
+%[- MARK -] \begin{funcdesc}{DebugStr}{message \optional{, object}}
+%[- MARK -] -On Mac OS 9, drop to the low-level debugger with message \var{message}. The
+%[- MARK -] -optional \var{object} argument is not used, but can easily be
+%[- MARK -] -inspected from the debugger. On Mac OS X the string is simply printed
+%[- MARK -] -to stderr.
+%[- MARK -] -
+%[- MARK -] -Note that you should use this function with extreme care: if no
+%[- MARK -] -low-level debugger like MacsBug is installed this call will crash your
+%[- MARK -] -system. It is intended mainly for developers of Python extension
+%[- MARK -] -modules.
+%[- MARK -] +On Mac OS X the string is simply printed to stderr (on older
+%[- MARK -] +Mac OS systems more elaborate functionality was available),
+%[- MARK -] +but it provides a convenient location to attach a breakpoint
+%[- MARK -] +in a low-level debugger like \program{gdb}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{SysBeep}{}
+%[- MARK -] Ring the bell.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{excdesc}
\begin{funcdesc}{SetEventHandler}{handler}
@@ -161,6 +290,17 @@
della funzione built-in \function{open()}. L'oggetto restituito ha
una semantica simil-file, ma non è un oggetto file Python, per cui ci
possono essere delle sottili differenze.
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 153
+%[- MARK -] for instance when running on Mac OS X Server or when logged in via ssh,
+%[- MARK -] or when the current interpreter is not running from a fullblown application
+%[- MARK -] bundle. A script runs from an application bundle either when it has been
+%[- MARK -] started with \program{pythonw} instead of \program{python} or when running
+%[- MARK -] as an applet.
+%[- MARK -] -
+%[- MARK -] -On Mac OS 9 the method always returns \code{True}.
+%[- MARK -] \end{funcdesc}
+%[- MARK -] END DIFF
\end{funcdesc}
\begin{funcdesc}{WMAvailable}{}
Modified: python/python/Doc/branches/2.4.3/mac/libmacostools.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/libmacostools.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/libmacostools.tex Fri Jun 2 12:52:55 2006
@@ -3,6 +3,23 @@
\declaremodule{standard}{macostools}
\platform{Mac}
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 6
+%[- MARK -] \modulesynopsis{Convenience routines for file manipulation.}
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] This module contains some convenience routines for file-manipulation
+%[- MARK -] on the Macintosh. All file parameters can be specified as
+%[- MARK -] -pathnames, \class{FSRef} or \class{FSSpec} objects.
+%[- MARK -] +pathnames, \class{FSRef} or \class{FSSpec} objects. This module
+%[- MARK -] +expects a filesystem which supports forked files, so it should not
+%[- MARK -] +be used on UFS partitions.
+%[- MARK -]
+%[- MARK -] The \module{macostools} module defines the following functions:
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \begin{funcdesc}{copy}{src, dst\optional{, createpath\optional{, copytimes}}}
+%[- MARK -] END DIFF
\modulesynopsis{Procedure di utilità per la manipolazione dei file.}
Modified: python/python/Doc/branches/2.4.3/mac/scripting.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/scripting.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/scripting.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,21 @@
+%[- MARK -] BEGIN DIFF 001 of 1
+%[- MARK -] @@ 1
+%[- MARK -] \chapter{MacPython OSA Modules \label{scripting}}
+%[- MARK -]
+%[- MARK -] -Python has a fairly complete implementation of the Open Scripting
+%[- MARK -] -Architecure (OSA, also commonly referred to as AppleScript), allowing
+%[- MARK -] +This chapter describes the current implementation of the Open Scripting
+%[- MARK -] +Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
+%[- MARK -] you to control scriptable applications from your Python program,
+%[- MARK -] -and with a fairly pythonic interface.
+%[- MARK -] +and with a fairly pythonic interface. Development on this set of modules
+%[- MARK -] +has stopped, and a replacement is expected for Python 2.5.
+%[- MARK -]
+%[- MARK -] For a description of the various components of AppleScript and OSA, and
+%[- MARK -] to get an understanding of the architecture and terminology, you should
+%[- MARK -] read Apple's documentation. The "Applescript Language Guide" explains
+%[- MARK -] the conceptual model and the terminology, and documents the standard
+%[- MARK -] END DIFF
\chapter{Moduli OSA MAcPython \label{scripting}}
Python implementa quasi del tutto l'Open Scripting Architecture (OSA,
Modified: python/python/Doc/branches/2.4.3/mac/undoc.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/mac/undoc.tex (original)
+++ python/python/Doc/branches/2.4.3/mac/undoc.tex Fri Jun 2 12:52:55 2006
@@ -19,6 +19,31 @@
\declaremodule{standard}{buildtools}
\platform{Mac}
\modulesynopsis{Modulo di aiuto per BuildApplet, BuildApplication e
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 19
+%[- MARK -] \declaremodule{standard}{buildtools}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Helper module for BuildApplet, BuildApplication and
+%[- MARK -] macfreeze.}
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] -\section{\module{py_resource} --- Resources from Python code}
+%[- MARK -] -\declaremodule[pyresource]{standard}{py_resource}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Helper to create \texttt{'PYC~'} resources for compiled
+%[- MARK -] - applications.}
+%[- MARK -] -
+%[- MARK -] -This module is primarily used as a help module for
+%[- MARK -] -\program{BuildApplet} and \program{BuildApplication}. It is able to
+%[- MARK -] -store compiled Python code as \texttt{'PYC~'} resources in a file.
+%[- MARK -] -
+%[- MARK -] +\deprecated{2.4}
+%[- MARK -]
+%[- MARK -] \section{\module{cfmfile} --- Code Fragment Resource module}
+%[- MARK -] \declaremodule{standard}{cfmfile}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Code Fragment Resource module.}
+%[- MARK -] END DIFF
macfreeze.}
@@ -42,6 +67,20 @@
\module{cfmfile} è un modulo che capisce i Frammenti di Codice e le
risorse ``cfrg'' che lo accompagnano. Può analizzare, fonderle
insieme ed è usato da BuildApplication per combinare tutti i moduli
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 41
+%[- MARK -] \module{cfmfile} is a module that understands Code Fragments and the
+%[- MARK -] accompanying ``cfrg'' resources. It can parse them and merge them, and is
+%[- MARK -] used by BuildApplication to combine all plugin modules to a single
+%[- MARK -] executable.
+%[- MARK -]
+%[- MARK -] +\deprecated{2.4}
+%[- MARK -]
+%[- MARK -] \section{\module{icopen} --- Internet Config replacement for \method{open()}}
+%[- MARK -] \declaremodule{standard}{icopen}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Internet Config replacement for \method{open()}.}
+%[- MARK -] END DIFF
plugin in un singolo eseguibile.
@@ -59,6 +98,21 @@
\declaremodule{standard}{macerrors}
\platform{Mac}
\modulesynopsis{Definizione delle costanti per molti codici di errore
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 57
+%[- MARK -] \section{\module{macerrors} --- Mac OS Errors}
+%[- MARK -] \declaremodule{standard}{macerrors}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Constant definitions for many Mac OS error codes.}
+%[- MARK -]
+%[- MARK -] -\module{macerrors} cotains constant definitions for many Mac OS error
+%[- MARK -] +\module{macerrors} contains constant definitions for many Mac OS error
+%[- MARK -] codes.
+%[- MARK -]
+%[- MARK -]
+%[- MARK -] \section{\module{macresource} --- Locate script resources}
+%[- MARK -] \declaremodule{standard}{macresource}
+%[- MARK -] END DIFF
di Mac OS.}
\module{macerrors} contiene la definizione delle costanti per molti
@@ -73,6 +127,96 @@
\module{macresource} aiuta gli script a trovare le loro risorse, come
finestre di dialogo e menu, senza richiedere codici speciali per
quando gli script verranno eseguiti sotto MacPython, applet di
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 71
+%[- MARK -] \module{macresource} helps scripts finding their resources, such as
+%[- MARK -] dialogs and menus, without requiring special case code for when the
+%[- MARK -] script is run under MacPython, as a MacPython applet or under OSX Python.
+%[- MARK -]
+%[- MARK -] \section{\module{Nav} --- NavServices calls}
+%[- MARK -] -\declaremodule{standard}{Nac}
+%[- MARK -] +\declaremodule{standard}{Nav}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Interface to Navigation Services.}
+%[- MARK -]
+%[- MARK -] A low-level interface to Navigation Services.
+%[- MARK -]
+%[- MARK -] -\section{\module{mkcwproject} --- Create CodeWarrior projects}
+%[- MARK -] -\declaremodule{standard}{mkcwproject}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Create CodeWarrior projects.}
+%[- MARK -] -
+%[- MARK -] -\refmodindex{distutils}
+%[- MARK -] -\module{mkcwproject} creates project files for the Metrowerks CodeWarrior
+%[- MARK -] -development environment. It is a helper module for
+%[- MARK -] -\module{distutils} but can be used separately for more
+%[- MARK -] -control.
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\section{\module{nsremote} --- Wrapper around Netscape OSA modules}
+%[- MARK -] -\declaremodule{standard}{nsremote}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Wrapper around Netscape OSA modules.}
+%[- MARK -] -
+%[- MARK -] -\module{nsremote} is a wrapper around the Netscape OSA modules that
+%[- MARK -] -allows you to easily send your browser to a given URL. A related
+%[- MARK -] -module that may be of interest is the \module{webbrowser} module,
+%[- MARK -] -documented in the \citetitle[../lib/lib.html]{Python Library
+%[- MARK -] -Reference}.
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] \section{\module{PixMapWrapper} --- Wrapper for PixMap objects}
+%[- MARK -] \declaremodule{standard}{PixMapWrapper}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Wrapper for PixMap objects.}
+%[- MARK -]
+%[- MARK -] \module{PixMapWrapper} wraps a PixMap object with a Python object that
+%[- MARK -] allows access to the fields by name. It also has methods to convert
+%[- MARK -] to and from \module{PIL} images.
+%[- MARK -]
+%[- MARK -] -
+%[- MARK -] -\section{\module{preferences} --- Application preferences manager}
+%[- MARK -] -\declaremodule{standard}{preferences}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Nice application preferences manager with support for
+%[- MARK -] - defaults.}
+%[- MARK -] -
+%[- MARK -] -The \module{preferences} module allows storage of user preferences in
+%[- MARK -] -the system-wide preferences folder, with defaults coming from the
+%[- MARK -] -application itself and the possibility to override preferences for
+%[- MARK -] -specific situations.
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\section{\module{pythonprefs} --- Preferences manager for Python}
+%[- MARK -] -\declaremodule{standard}{pythonprefs}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Specialized preferences manager for the Python
+%[- MARK -] - interpreter.}
+%[- MARK -] -
+%[- MARK -] -This module is a specialization of the \refmodule{preferences} module
+%[- MARK -] -that allows reading and writing of the preferences for the Python
+%[- MARK -] -interpreter.
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] -\section{\module{quietconsole} --- Non-visible standard output}
+%[- MARK -] -\declaremodule{standard}{quietconsole}
+%[- MARK -] - \platform{Mac}
+%[- MARK -] -\modulesynopsis{Buffered, non-visible standard output.}
+%[- MARK -] -
+%[- MARK -] -\module{quietconsole} allows you to keep stdio output in a buffer
+%[- MARK -] -without displaying it (or without displaying the stdout window
+%[- MARK -] -altogether, if set with \program{EditPythonPrefs}) until you try to read from
+%[- MARK -] -stdin or disable the buffering, at which point all the saved output is
+%[- MARK -] -sent to the window. Good for programs with graphical user interfaces
+%[- MARK -] -that do want to display their output at a crash.
+%[- MARK -] -
+%[- MARK -] -
+%[- MARK -] \section{\module{videoreader} --- Read QuickTime movies}
+%[- MARK -] \declaremodule{standard}{videoreader}
+%[- MARK -] \platform{Mac}
+%[- MARK -] \modulesynopsis{Read QuickTime movies frame by frame for further processing.}
+%[- MARK -]
+%[- MARK -] END DIFF
MacPython o sotto OSX Python.
\section{\module{Nav} --- Chiamate NavServices}
Modified: python/python/Doc/branches/2.4.3/ref/ref7.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/ref/ref7.tex (original)
+++ python/python/Doc/branches/2.4.3/ref/ref7.tex Fri Jun 2 12:52:55 2006
@@ -139,6 +139,25 @@
{"for" \token{target_list} "in" \token{expression_list}
":" \token{suite}}
\productioncont{["else" ":" \token{suite}]}
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 132
+%[- MARK -] {"for" \token{target_list} "in" \token{expression_list}
+%[- MARK -] ":" \token{suite}}
+%[- MARK -] \productioncont{["else" ":" \token{suite}]}
+%[- MARK -] \end{productionlist}
+%[- MARK -]
+%[- MARK -] -The expression list is evaluated once; it should yield a sequence. The
+%[- MARK -] -suite is then executed once for each item in the sequence, in the
+%[- MARK -] +The expression list is evaluated once; it should yield an iterable
+%[- MARK -] +object. An iterator is created for the result of the
+%[- MARK -] +{}\code{expression_list}. The suite is then executed once for each
+%[- MARK -] +item provided by the iterator, in the
+%[- MARK -] order of ascending indices. Each item in turn is assigned to the
+%[- MARK -] target list using the standard rules for assignments, and then the
+%[- MARK -] suite is executed. When the items are exhausted (which is immediately
+%[- MARK -] when the sequence is empty), the suite in the \keyword{else} clause, if
+%[- MARK -] present, is executed, and the loop terminates.
+%[- MARK -] END DIFF
\end{productionlist}
L'espressione list viene valutata una volta; dovrebbe produrre una
@@ -331,6 +350,37 @@
Una definizione di funzione definisce un oggetto funzione definito
dall'utente (vedere la sezione~\ref{types}):
\obindex{user-defined function}
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 313
+%[- MARK -] \obindex{user-defined function}
+%[- MARK -] \obindex{function}
+%[- MARK -]
+%[- MARK -] \begin{productionlist}
+%[- MARK -] \production{funcdef}
+%[- MARK -] - {"def" \token{funcname} "(" [\token{parameter_list}] ")"
+%[- MARK -] + {[\token{decorators}] "def" \token{funcname} "(" [\token{parameter_list}] ")"
+%[- MARK -] ":" \token{suite}}
+%[- MARK -] + \production{decorators}
+%[- MARK -] + {\token{decorator}+}
+%[- MARK -] + \production{decorator}
+%[- MARK -] + {"@" \token{dotted_name} ["(" [\token{argument_list} [","]] ")"] NEWLINE}
+%[- MARK -] + \production{dotted_name}
+%[- MARK -] + {\token{identifier} ("." \token{identifier})*}
+%[- MARK -] \production{parameter_list}
+%[- MARK -] - {(\token{defparameter} ",")*}
+%[- MARK -] - \productioncont{("*" \token{identifier} [, "**" \token{identifier}]}
+%[- MARK -] - \productioncont{| "**" \token{identifier}
+%[- MARK -] - | \token{defparameter} [","])}
+%[- MARK -] + {(\token{defparameter} ",")*}
+%[- MARK -] + \productioncont{(~~"*" \token{identifier} [, "**" \token{identifier}]}
+%[- MARK -] + \productioncont{ | "**" \token{identifier}}
+%[- MARK -] + \productioncont{ | \token{defparameter} [","] )}
+%[- MARK -] \production{defparameter}
+%[- MARK -] {\token{parameter} ["=" \token{expression}]}
+%[- MARK -] \production{sublist}
+%[- MARK -] {\token{parameter} ("," \token{parameter})* [","]}
+%[- MARK -] \production{parameter}
+%[- MARK -] END DIFF
\obindex{function}
\begin{productionlist}
@@ -362,6 +412,40 @@
\indexii{name}{binding}
La definizione della funzione non esegue il corpo della funzione;
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 341
+%[- MARK -] \indexii{name}{binding}
+%[- MARK -]
+%[- MARK -] The function definition does not execute the function body; this gets
+%[- MARK -] executed only when the function is called.
+%[- MARK -]
+%[- MARK -] +A function definition may be wrapped by one or more decorator expressions.
+%[- MARK -] +Decorator expressions are evaluated when the function is defined, in the scope
+%[- MARK -] +that contains the function definition. The result must be a callable,
+%[- MARK -] +which is invoked with the function object as the only argument.
+%[- MARK -] +The returned value is bound to the function name instead of the function
+%[- MARK -] +object. Multiple decorators are applied in nested fashion.
+%[- MARK -] +For example, the following code:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] + a f1(arg)
+%[- MARK -] + a f2
+%[- MARK -] +def func(): pass
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] +is equivalent to:
+%[- MARK -] +
+%[- MARK -] +\begin{verbatim}
+%[- MARK -] +def func(): pass
+%[- MARK -] +func = f1(arg)(f2(func))
+%[- MARK -] +\end{verbatim}
+%[- MARK -] +
+%[- MARK -] When one or more top-level parameters have the form \var{parameter}
+%[- MARK -] \code{=} \var{expression}, the function is said to have ``default
+%[- MARK -] parameter values.'' For a parameter with a
+%[- MARK -] default value, the corresponding argument may be omitted from a call,
+%[- MARK -] in which case the parameter's default value is substituted. If a
+%[- MARK -] END DIFF
questa viene eseguita solo quando viene chiamata la funzione.
Quando uno o più parametri di alto livello hanno la forma
@@ -433,6 +517,21 @@
Una definizione di classe definisce un oggetto classe (vedere la
sezione~\ref{types}):
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 410
+%[- MARK -] \begin{productionlist}
+%[- MARK -] \production{classdef}
+%[- MARK -] {"class" \token{classname} [\token{inheritance}] ":"
+%[- MARK -] \token{suite}}
+%[- MARK -] \production{inheritance}
+%[- MARK -] - {"(" [\token{expression_list}] ")"}
+%[- MARK -] + {"(" \token{expression_list} ")"}
+%[- MARK -] \production{classname}
+%[- MARK -] {\token{identifier}}
+%[- MARK -] \end{productionlist}
+%[- MARK -]
+%[- MARK -] A class definition is an executable statement. It first evaluates the
+%[- MARK -] END DIFF
\obindex{class}
\begin{productionlist}
Modified: python/python/Doc/branches/2.4.3/whatsnew/whatsnew20.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/whatsnew/whatsnew20.tex (original)
+++ python/python/Doc/branches/2.4.3/whatsnew/whatsnew20.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,15 @@
+%[- MARK -] BEGIN DIFF 001 of 4
+%[- MARK -] @@ 1
+%[- MARK -] \documentclass{howto}
+%[- MARK -]
+%[- MARK -] -% $Id: whatsnew20.tex,v 1.51 2004/01/02 06:57:49 fdrake Exp $
+%[- MARK -] +% $Id: whatsnew20.tex 38161 2005-01-01 00:34:56Z rhettinger $
+%[- MARK -]
+%[- MARK -] \title{What's New in Python 2.0}
+%[- MARK -] \release{1.02}
+%[- MARK -] \author{A.M. Kuchling and Moshe Zadka}
+%[- MARK -] \authoraddress{
+%[- MARK -] END DIFF
\documentclass{howto}
% $Id: whatsnew20.tex,v 1.49 2003/10/20 14:01:48 doerwalter Exp $
@@ -392,6 +404,24 @@
been added to Python 2.0. Augmented assignment operators include
\code{+=}, \code{-=}, \code{*=}, and so forth. For example, the
statement \code{a += 2} increments the value of the variable
+%[- MARK -] BEGIN DIFF 002 of 4
+%[- MARK -] @@ 395
+%[- MARK -] been added to Python 2.0. Augmented assignment operators include
+%[- MARK -] \code{+=}, \code{-=}, \code{*=}, and so forth. For example, the
+%[- MARK -] statement \code{a += 2} increments the value of the variable
+%[- MARK -] \code{a} by 2, equivalent to the slightly lengthier \code{a = a + 2}.
+%[- MARK -]
+%[- MARK -] +% The empty groups below prevent conversion to guillemets.
+%[- MARK -] The full list of supported assignment operators is \code{+=},
+%[- MARK -] \code{-=}, \code{*=}, \code{/=}, \code{\%=}, \code{**=}, \code{\&=},
+%[- MARK -] -\code{|=}, \verb|^=|, \code{>>=}, and \code{<<=}. Python classes can
+%[- MARK -] +\code{|=}, \verb|^=|, \code{>{}>=}, and \code{<{}<=}. Python classes can
+%[- MARK -] override the augmented assignment operators by defining methods named
+%[- MARK -] \method{__iadd__}, \method{__isub__}, etc. For example, the following
+%[- MARK -] \class{Number} class stores a number and supports using += to create a
+%[- MARK -] new instance with an incremented value.
+%[- MARK -]
+%[- MARK -] END DIFF
\code{a} by 2, equivalent to the slightly lengthier \code{a = a + 2}.
The full list of supported assignment operators is \code{+=},
@@ -636,6 +666,21 @@
that for ease of porting, MS Visual \Cpp{} treats code as 32 bit on Itanium.)
PythonWin also supports Windows CE; see the Python CE page at
\url{http://starship.python.net/crew/mhammond/ce/} for more
+%[- MARK -] BEGIN DIFF 003 of 4
+%[- MARK -] @@ 639
+%[- MARK -] that for ease of porting, MS Visual \Cpp{} treats code as 32 bit on Itanium.)
+%[- MARK -] PythonWin also supports Windows CE; see the Python CE page at
+%[- MARK -] \url{http://starship.python.net/crew/mhammond/ce/} for more
+%[- MARK -] information.
+%[- MARK -]
+%[- MARK -] -Another new platform is Darwin/MacOS X; inital support for it is in
+%[- MARK -] +Another new platform is Darwin/MacOS X; initial support for it is in
+%[- MARK -] Python 2.0. Dynamic loading works, if you specify ``configure
+%[- MARK -] --with-dyld --with-suffix=.x''. Consult the README in the Python
+%[- MARK -] source distribution for more instructions.
+%[- MARK -]
+%[- MARK -] An attempt has been made to alleviate one of Python's warts, the
+%[- MARK -] END DIFF
information.
Another new platform is Darwin/MacOS X; inital support for it is in
@@ -895,6 +940,23 @@
\function{PyOS_setsig()} will set a new handler.
% ======================================================================
+%[- MARK -] BEGIN DIFF 004 of 4
+%[- MARK -] @@ 905
+%[- MARK -] what compiler options to use for extension modules. Software authors
+%[- MARK -] had to go through an arduous ritual of editing Makefiles and
+%[- MARK -] configuration files, which only really work on Unix and leave Windows
+%[- MARK -] and MacOS unsupported. Python users faced wildly differing
+%[- MARK -] installation instructions which varied between different extension
+%[- MARK -] -packages, which made adminstering a Python installation something of a
+%[- MARK -] -chore.
+%[- MARK -] +packages, which made administering a Python installation something of
+%[- MARK -] +a chore.
+%[- MARK -]
+%[- MARK -] The SIG for distribution utilities, shepherded by Greg Ward, has
+%[- MARK -] created the Distutils, a system to make package installation much
+%[- MARK -] easier. They form the \module{distutils} package, a new part of
+%[- MARK -] Python's standard library. In the best case, installing a Python
+%[- MARK -] END DIFF
\section{Distutils: Making Modules Easy to Install}
Before Python 2.0, installing modules was a tedious affair -- there
Modified: python/python/Doc/branches/2.4.3/whatsnew/whatsnew21.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/whatsnew/whatsnew21.tex (original)
+++ python/python/Doc/branches/2.4.3/whatsnew/whatsnew21.tex Fri Jun 2 12:52:55 2006
@@ -1,5 +1,19 @@
\documentclass{howto}
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 1
+%[- MARK -] \documentclass{howto}
+%[- MARK -]
+%[- MARK -] \usepackage{distutils}
+%[- MARK -]
+%[- MARK -] -% $Id: whatsnew21.tex,v 1.32 2004/01/02 06:57:50 fdrake Exp $
+%[- MARK -] +% $Id: whatsnew21.tex 38161 2005-01-01 00:34:56Z rhettinger $
+%[- MARK -]
+%[- MARK -] \title{What's New in Python 2.1}
+%[- MARK -] \release{1.00}
+%[- MARK -] \author{A.M. Kuchling}
+%[- MARK -] \authoraddress{
+%[- MARK -] END DIFF
\usepackage{distutils}
% $Id: whatsnew21.tex,v 1.31 2003/07/22 00:52:42 fdrake Exp $
@@ -196,6 +210,21 @@
\lineii{<}{\method{__lt__}} \lineii{<=}{\method{__le__}}
\lineii{>}{\method{__gt__}} \lineii{>=}{\method{__ge__}}
\lineii{==}{\method{__eq__}} \lineii{!=}{\method{__ne__}}
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 201
+%[- MARK -] \lineii{==}{\method{__eq__}} \lineii{!=}{\method{__ne__}}
+%[- MARK -] \end{tableii}
+%[- MARK -]
+%[- MARK -] (The magic methods are named after the corresponding Fortran operators
+%[- MARK -] \code{.LT.}. \code{.LE.}, \&c. Numeric programmers are almost
+%[- MARK -] -certainly quite familar with these names and will find them easy to
+%[- MARK -] +certainly quite familiar with these names and will find them easy to
+%[- MARK -] remember.)
+%[- MARK -]
+%[- MARK -] Each of these magic methods is of the form \code{\var{method}(self,
+%[- MARK -] other)}, where \code{self} will be the object on the left-hand side of
+%[- MARK -] the operator, while \code{other} will be the object on the right-hand
+%[- MARK -] END DIFF
\end{tableii}
(The magic methods are named after the corresponding Fortran operators
@@ -599,6 +628,21 @@
be made for users of earlier Python versions. Version 1.0.2 of the
Distutils includes the changes described in PEP 241, as well as
various bugfixes and enhancements. It will be available from
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 602
+%[- MARK -] be made for users of earlier Python versions. Version 1.0.2 of the
+%[- MARK -] Distutils includes the changes described in PEP 241, as well as
+%[- MARK -] various bugfixes and enhancements. It will be available from
+%[- MARK -] the Distutils SIG at \url{http://www.python.org/sigs/distutils-sig/}.
+%[- MARK -]
+%[- MARK -] -% XXX update when I actually release 1.0.2
+%[- MARK -] -
+%[- MARK -] \begin{seealso}
+%[- MARK -]
+%[- MARK -] \seepep{241}{Metadata for Python Software Packages}{Written and
+%[- MARK -] implemented by A.M. Kuchling.}
+%[- MARK -]
+%[- MARK -] END DIFF
the Distutils SIG at \url{http://www.python.org/sigs/distutils-sig/}.
% XXX update when I actually release 1.0.2
Modified: python/python/Doc/branches/2.4.3/whatsnew/whatsnew22.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/whatsnew/whatsnew22.tex (original)
+++ python/python/Doc/branches/2.4.3/whatsnew/whatsnew22.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,15 @@
+%[- MARK -] BEGIN DIFF 001 of 2
+%[- MARK -] @@ 1
+%[- MARK -] \documentclass{howto}
+%[- MARK -]
+%[- MARK -] -% $Id: whatsnew22.tex,v 1.64 2004/01/02 06:57:50 fdrake Exp $
+%[- MARK -] +% $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $
+%[- MARK -]
+%[- MARK -] \title{What's New in Python 2.2}
+%[- MARK -] \release{1.02}
+%[- MARK -] \author{A.M. Kuchling}
+%[- MARK -] \authoraddress{
+%[- MARK -] END DIFF
\documentclass{howto}
% $Id: whatsnew22.tex,v 1.63 2003/08/29 17:49:26 akuchling Exp $
@@ -341,6 +353,21 @@
\function{super(\var{class}, \var{obj})}, which returns
a bound superclass object (not the actual class object). This form
will be used in methods to call a method in the superclass; for
+%[- MARK -] BEGIN DIFF 002 of 2
+%[- MARK -] @@ 345
+%[- MARK -] a bound superclass object (not the actual class object). This form
+%[- MARK -] will be used in methods to call a method in the superclass; for
+%[- MARK -] example, \class{D}'s \method{save()} method would look like this:
+%[- MARK -]
+%[- MARK -] \begin{verbatim}
+%[- MARK -] -class D:
+%[- MARK -] +class D (B,C):
+%[- MARK -] def save (self):
+%[- MARK -] # Call superclass .save()
+%[- MARK -] super(D, self).save()
+%[- MARK -] # Save D's private information here
+%[- MARK -] ...
+%[- MARK -] END DIFF
example, \class{D}'s \method{save()} method would look like this:
\begin{verbatim}
Modified: python/python/Doc/branches/2.4.3/whatsnew/whatsnew23.tex
==============================================================================
--- python/python/Doc/branches/2.4.3/whatsnew/whatsnew23.tex (original)
+++ python/python/Doc/branches/2.4.3/whatsnew/whatsnew23.tex Fri Jun 2 12:52:55 2006
@@ -1,3 +1,15 @@
+%[- MARK -] BEGIN DIFF 001 of 3
+%[- MARK -] @@ 1
+%[- MARK -] \documentclass{howto}
+%[- MARK -] \usepackage{distutils}
+%[- MARK -] -% $Id: whatsnew23.tex,v 1.165 2004/01/02 06:57:50 fdrake Exp $
+%[- MARK -] +% $Id: whatsnew23.tex 38161 2005-01-01 00:34:56Z rhettinger $
+%[- MARK -]
+%[- MARK -] \title{What's New in Python 2.3}
+%[- MARK -] \release{1.01}
+%[- MARK -] \author{A.M.\ Kuchling}
+%[- MARK -] \authoraddress{
+%[- MARK -] END DIFF
\documentclass{howto}
\usepackage{distutils}
% $Id: whatsnew23.tex,v 1.163 2003/10/23 18:08:03 akuchling Exp $
@@ -2216,6 +2228,21 @@
restricted by the limitations of the underlying emulation layer. The
standard OS/2 port, which uses IBM's Visual Age compiler, also gained
support for case-sensitive import semantics as part of the integration
+%[- MARK -] BEGIN DIFF 002 of 3
+%[- MARK -] @@ 2221
+%[- MARK -] support for case-sensitive import semantics as part of the integration
+%[- MARK -] of the EMX port into CVS. (Contributed by Andrew MacIntyre.)
+%[- MARK -]
+%[- MARK -] On MacOS, most toolbox modules have been weaklinked to improve
+%[- MARK -] backward compatibility. This means that modules will no longer fail
+%[- MARK -] -to load if a single routine is missing on the curent OS version.
+%[- MARK -] +to load if a single routine is missing on the current OS version.
+%[- MARK -] Instead calling the missing routine will raise an exception.
+%[- MARK -] (Contributed by Jack Jansen.)
+%[- MARK -]
+%[- MARK -] The RPM spec files, found in the \file{Misc/RPM/} directory in the
+%[- MARK -] Python source distribution, were updated for 2.3. (Contributed by
+%[- MARK -] END DIFF
of the EMX port into CVS. (Contributed by Andrew MacIntyre.)
On MacOS, most toolbox modules have been weaklinked to improve
@@ -2320,6 +2347,30 @@
\item Large octal and hex literals such as
\code{0xffffffff} now trigger a \exception{FutureWarning}. Currently
they're stored as 32-bit numbers and result in a negative value, but
+%[- MARK -] BEGIN DIFF 003 of 3
+%[- MARK -] @@ 2323
+%[- MARK -] \item Large octal and hex literals such as
+%[- MARK -] \code{0xffffffff} now trigger a \exception{FutureWarning}. Currently
+%[- MARK -] they're stored as 32-bit numbers and result in a negative value, but
+%[- MARK -] in Python 2.4 they'll become positive long integers.
+%[- MARK -]
+%[- MARK -] +% The empty groups below prevent conversion to guillemets.
+%[- MARK -] There are a few ways to fix this warning. If you really need a
+%[- MARK -] positive number, just add an \samp{L} to the end of the literal. If
+%[- MARK -] you're trying to get a 32-bit integer with low bits set and have
+%[- MARK -] -previously used an expression such as \code{~(1 << 31)}, it's probably
+%[- MARK -] +previously used an expression such as \code{\textasciitilde(1 <{}< 31)},
+%[- MARK -] +it's probably
+%[- MARK -] clearest to start with all bits set and clear the desired upper bits.
+%[- MARK -] For example, to clear just the top bit (bit 31), you could write
+%[- MARK -] -\code{0xffffffffL {\&}{\textasciitilde}(1L<<31)}.
+%[- MARK -] +\code{0xffffffffL {\&}{\textasciitilde}(1L<{}<31)}.
+%[- MARK -]
+%[- MARK -] \item You can no longer disable assertions by assigning to \code{__debug__}.
+%[- MARK -]
+%[- MARK -] \item The Distutils \function{setup()} function has gained various new
+%[- MARK -] keyword arguments such as \var{depends}. Old versions of the
+%[- MARK -] END DIFF
in Python 2.4 they'll become positive long integers.
There are a few ways to fix this warning. If you really need a
More information about the Commits
mailing list