summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorThomas Wouters <thomas@python.org>2007-02-01 18:02:27 (GMT)
committerThomas Wouters <thomas@python.org>2007-02-01 18:02:27 (GMT)
commitb213704f3cad4fc61c4117afe559454b02193e5b (patch)
tree770513db88d4f8ab5be603a54ad58882964afa1c /Doc/lib
parentec7027fc5b9d26175ad776bf7ee4798395e8dc48 (diff)
downloadcpython-b213704f3cad4fc61c4117afe559454b02193e5b.zip
cpython-b213704f3cad4fc61c4117afe559454b02193e5b.tar.gz
cpython-b213704f3cad4fc61c4117afe559454b02193e5b.tar.bz2
Merged revisions 53451-53537 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r53454 | brett.cannon | 2007-01-15 20:12:08 +0100 (Mon, 15 Jan 2007) | 3 lines Add a note for strptime that just because strftime supports some extra directive that is not documented that strptime will as well. ........ r53458 | vinay.sajip | 2007-01-16 10:50:07 +0100 (Tue, 16 Jan 2007) | 1 line Updated rotating file handlers to use _open(). ........ r53459 | marc-andre.lemburg | 2007-01-16 14:03:06 +0100 (Tue, 16 Jan 2007) | 2 lines Add news items for the recent pybench and platform changes. ........ r53460 | sjoerd.mullender | 2007-01-16 17:42:38 +0100 (Tue, 16 Jan 2007) | 4 lines Fixed ntpath.expandvars to not replace references to non-existing variables with nothing. Also added tests. This fixes bug #494589. ........ r53464 | neal.norwitz | 2007-01-17 07:23:51 +0100 (Wed, 17 Jan 2007) | 1 line Give Calvin Spealman access for python-dev summaries. ........ r53465 | neal.norwitz | 2007-01-17 09:37:26 +0100 (Wed, 17 Jan 2007) | 1 line Remove Calvin since he only has access to the website currently. ........ r53466 | thomas.heller | 2007-01-17 10:40:34 +0100 (Wed, 17 Jan 2007) | 2 lines Replace C++ comments with C comments. ........ r53472 | andrew.kuchling | 2007-01-17 20:55:06 +0100 (Wed, 17 Jan 2007) | 1 line [Part of bug #1599254] Add suggestion to Mailbox docs to use Maildir, and warn user to lock/unlock mailboxes when modifying them ........ r53475 | georg.brandl | 2007-01-17 22:09:04 +0100 (Wed, 17 Jan 2007) | 2 lines Bug #1637967: missing //= operator in list. ........ r53477 | georg.brandl | 2007-01-17 22:19:58 +0100 (Wed, 17 Jan 2007) | 2 lines Bug #1629125: fix wrong data type (int -> Py_ssize_t) in PyDict_Next docs. ........ r53481 | neal.norwitz | 2007-01-18 06:40:58 +0100 (Thu, 18 Jan 2007) | 1 line Try reverting part of r53145 that seems to cause the Windows buildbots to fail in test_uu.UUFileTest.test_encode ........ r53482 | fred.drake | 2007-01-18 06:42:30 +0100 (Thu, 18 Jan 2007) | 1 line add missing version entry ........ r53483 | neal.norwitz | 2007-01-18 07:20:55 +0100 (Thu, 18 Jan 2007) | 7 lines This test doesn't pass on Windows. The cause seems to be that chmod doesn't support the same funcationality as on Unix. I'm not sure if this fix is the best (or if it will even work)--it's a test to see if the buildbots start passing again. It might be better to not even run this test if it's windows (or non-posix). ........ r53488 | neal.norwitz | 2007-01-19 06:53:33 +0100 (Fri, 19 Jan 2007) | 1 line SF #1635217, Fix unbalanced paren ........ r53489 | martin.v.loewis | 2007-01-19 07:42:22 +0100 (Fri, 19 Jan 2007) | 3 lines Prefix AST symbols with _Py_. Fixes #1637022. Will backport. ........ r53497 | martin.v.loewis | 2007-01-19 19:01:38 +0100 (Fri, 19 Jan 2007) | 2 lines Add UUIDs for 2.5.1 and 2.5.2 ........ r53499 | raymond.hettinger | 2007-01-19 19:07:18 +0100 (Fri, 19 Jan 2007) | 1 line SF# 1635892: Fix docs for betavariate's input parameters . ........ r53503 | martin.v.loewis | 2007-01-20 15:05:39 +0100 (Sat, 20 Jan 2007) | 2 lines Merge 53501 and 53502 from 25 branch: Add /GS- for AMD64 and Itanium builds where missing. ........ r53504 | walter.doerwald | 2007-01-20 18:28:31 +0100 (Sat, 20 Jan 2007) | 2 lines Port test_resource.py to unittest. ........ r53505 | walter.doerwald | 2007-01-20 19:19:33 +0100 (Sat, 20 Jan 2007) | 2 lines Add argument tests an calls of resource.getrusage(). ........ r53506 | walter.doerwald | 2007-01-20 20:03:17 +0100 (Sat, 20 Jan 2007) | 2 lines resource.RUSAGE_BOTH might not exist. ........ r53507 | walter.doerwald | 2007-01-21 00:07:28 +0100 (Sun, 21 Jan 2007) | 2 lines Port test_new.py to unittest. ........ r53508 | martin.v.loewis | 2007-01-21 10:33:07 +0100 (Sun, 21 Jan 2007) | 2 lines Patch #1610575: Add support for _Bool to struct. ........ r53509 | georg.brandl | 2007-01-21 11:28:43 +0100 (Sun, 21 Jan 2007) | 3 lines Bug #1486663: don't reject keyword arguments for subclasses of builtin types. ........ r53511 | georg.brandl | 2007-01-21 11:35:10 +0100 (Sun, 21 Jan 2007) | 2 lines Patch #1627441: close sockets properly in urllib2. ........ r53517 | georg.brandl | 2007-01-22 20:40:21 +0100 (Mon, 22 Jan 2007) | 3 lines Use new email module names (#1637162, #1637159, #1637157). ........ r53518 | andrew.kuchling | 2007-01-22 21:26:40 +0100 (Mon, 22 Jan 2007) | 1 line Improve pattern used for mbox 'From' lines; add a simple test ........ r53519 | andrew.kuchling | 2007-01-22 21:27:50 +0100 (Mon, 22 Jan 2007) | 1 line Make comment match the code ........ r53522 | georg.brandl | 2007-01-22 22:10:33 +0100 (Mon, 22 Jan 2007) | 2 lines Bug #1249573: fix rfc822.parsedate not accepting a certain date format ........ r53524 | georg.brandl | 2007-01-22 22:23:41 +0100 (Mon, 22 Jan 2007) | 2 lines Bug #1627316: handle error in condition/ignore pdb commands more gracefully. ........ r53526 | lars.gustaebel | 2007-01-23 12:17:33 +0100 (Tue, 23 Jan 2007) | 4 lines Patch #1507247: tarfile.py: use current umask for intermediate directories. ........ r53527 | thomas.wouters | 2007-01-23 14:42:00 +0100 (Tue, 23 Jan 2007) | 13 lines SF patch #1630975: Fix crash when replacing sys.stdout in sitecustomize When running the interpreter in an environment that would cause it to set stdout/stderr/stdin's encoding, having a sitecustomize that would replace them with something other than PyFile objects would crash the interpreter. Fix it by simply ignoring the encoding-setting for non-files. This could do with a test, but I can think of no maintainable and portable way to test this bug, short of adding a sitecustomize.py to the buildsystem and have it always run with it (hmmm....) ........ r53528 | thomas.wouters | 2007-01-23 14:50:49 +0100 (Tue, 23 Jan 2007) | 4 lines Add news entry about last checkin (oops.) ........ r53531 | martin.v.loewis | 2007-01-23 22:11:47 +0100 (Tue, 23 Jan 2007) | 4 lines Make PyTraceBack_Here use the current thread, not the frame's thread state. Fixes #1579370. Will backport. ........ r53535 | brett.cannon | 2007-01-24 00:21:22 +0100 (Wed, 24 Jan 2007) | 5 lines Fix crasher for when an object's __del__ creates a new weakref to itself. Patch only fixes new-style classes; classic classes still buggy. Closes bug #1377858. Already backported. ........ r53536 | walter.doerwald | 2007-01-24 01:42:19 +0100 (Wed, 24 Jan 2007) | 2 lines Port test_popen.py to unittest. ........
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/libmailbox.tex82
-rw-r--r--Doc/lib/librandom.tex2
-rw-r--r--Doc/lib/libstruct.tex17
-rw-r--r--Doc/lib/libtime.tex6
4 files changed, 79 insertions, 28 deletions
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex
index 75ea7e1..961b050 100644
--- a/Doc/lib/libmailbox.tex
+++ b/Doc/lib/libmailbox.tex
@@ -25,22 +25,29 @@ Maildir, mbox, MH, Babyl, and MMDF.
A mailbox, which may be inspected and modified.
\end{classdesc*}
+The \class{Mailbox} class defines an interface and
+is not intended to be instantiated. Instead, format-specific
+subclasses should inherit from \class{Mailbox} and your code
+should instantiate a particular subclass.
+
The \class{Mailbox} interface is dictionary-like, with small keys
-corresponding to messages. Keys are issued by the \class{Mailbox} instance
-with which they will be used and are only meaningful to that \class{Mailbox}
-instance. A key continues to identify a message even if the corresponding
-message is modified, such as by replacing it with another message. Messages may
-be added to a \class{Mailbox} instance using the set-like method
-\method{add()} and removed using a \code{del} statement or the set-like methods
-\method{remove()} and \method{discard()}.
+corresponding to messages. Keys are issued by the \class{Mailbox}
+instance with which they will be used and are only meaningful to that
+\class{Mailbox} instance. A key continues to identify a message even
+if the corresponding message is modified, such as by replacing it with
+another message.
+
+Messages may be added to a \class{Mailbox} instance using the set-like
+method \method{add()} and removed using a \code{del} statement or the
+set-like methods \method{remove()} and \method{discard()}.
\class{Mailbox} interface semantics differ from dictionary semantics in some
-noteworthy ways. Each time a message is requested, a new representation
-(typically a \class{Message} instance) is generated, based upon the current
-state of the mailbox. Similarly, when a message is added to a \class{Mailbox}
-instance, the provided message representation's contents are copied. In neither
-case is a reference to the message representation kept by the \class{Mailbox}
-instance.
+noteworthy ways. Each time a message is requested, a new
+representation (typically a \class{Message} instance) is generated
+based upon the current state of the mailbox. Similarly, when a message
+is added to a \class{Mailbox} instance, the provided message
+representation's contents are copied. In neither case is a reference
+to the message representation kept by the \class{Mailbox} instance.
The default \class{Mailbox} iterator iterates over message representations, not
keys as the default dictionary iterator does. Moreover, modification of a
@@ -51,9 +58,14 @@ skipped, though using a key from an iterator may result in a
\exception{KeyError} exception if the corresponding message is subsequently
removed.
-\class{Mailbox} itself is intended to define an interface and to be inherited
-from by format-specific subclasses but is not intended to be instantiated.
-Instead, you should instantiate a subclass.
+Be very cautious when modifying mailboxes that might also be changed
+by some other process. The safest mailbox format to use for such
+tasks is Maildir; try to avoid using single-file formats such as mbox
+for concurrent writing. If you're modifying a mailbox, no matter what
+the format, you must lock it by calling the \method{lock()} and
+\method{unlock()} methods before making any changes. Failing to lock
+the mailbox runs the risk of losing data if some other process makes
+changes to the mailbox while your Python code is running.
\class{Mailbox} instances have the following methods:
@@ -202,15 +214,16 @@ general it is incorrect for \var{arg} to be a \class{Mailbox} instance.
\begin{methoddesc}{flush}{}
Write any pending changes to the filesystem. For some \class{Mailbox}
-subclasses, changes are always written immediately and this method does
-nothing.
+subclasses, changes are always written immediately and \method{flush()} does
+nothing, but you should still make a habit of calling this method.
\end{methoddesc}
\begin{methoddesc}{lock}{}
Acquire an exclusive advisory lock on the mailbox so that other processes know
not to modify it. An \exception{ExternalClashError} is raised if the lock is
not available. The particular locking mechanisms used depend upon the mailbox
-format.
+format. You should \emph{always} lock the mailbox before making any
+modifications to its contents.
\end{methoddesc}
\begin{methoddesc}{unlock}{}
@@ -1373,36 +1386,55 @@ of the format-specific information that can be converted:
\begin{verbatim}
import mailbox
destination = mailbox.MH('~/Mail')
+destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
destination.add(MHMessage(message))
+destination.flush()
+destination.unlock()
\end{verbatim}
-An example of sorting mail from numerous mailing lists, being careful to avoid
-mail corruption due to concurrent modification by other programs, mail loss due
-to interruption of the program, or premature termination due to malformed
-messages in the mailbox:
+This example sorts mail from several mailing lists into different
+mailboxes, being careful to avoid mail corruption due to concurrent
+modification by other programs, mail loss due to interruption of the
+program, or premature termination due to malformed messages in the
+mailbox:
\begin{verbatim}
import mailbox
import email.Errors
+
list_names = ('python-list', 'python-dev', 'python-bugs')
+
boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
-inbox = mailbox.Maildir('~/Maildir', None)
+inbox = mailbox.Maildir('~/Maildir', factory=None)
+
for key in inbox.iterkeys():
try:
message = inbox[key]
except email.Errors.MessageParseError:
continue # The message is malformed. Just leave it.
+
for name in list_names:
list_id = message['list-id']
if list_id and name in list_id:
+ # Get mailbox to use
box = boxes[name]
+
+ # Write copy to disk before removing original.
+ # If there's a crash, you might duplicate a message, but
+ # that's better than losing a message completely.
box.lock()
box.add(message)
- box.flush() # Write copy to disk before removing original.
+ box.flush()
box.unlock()
+
+ # Remove original message
+ inbox.lock()
inbox.discard(key)
+ inbox.flush()
+ inbox.unlock()
break # Found destination, so stop looking.
+
for box in boxes.itervalues():
box.close()
\end{verbatim}
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex
index c6b8846..78c536b 100644
--- a/Doc/lib/librandom.tex
+++ b/Doc/lib/librandom.tex
@@ -185,7 +185,7 @@ these equations can be found in any statistics text.
\begin{funcdesc}{betavariate}{alpha, beta}
Beta distribution. Conditions on the parameters are
- \code{\var{alpha} > -1} and \code{\var{beta} > -1}.
+ \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
Returned values range between 0 and 1.
\end{funcdesc}
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index 026968c..539e937 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -50,14 +50,15 @@ C and Python values should be obvious given their types:
\lineiv{c}{\ctype{char}}{string of length 1}{}
\lineiv{b}{\ctype{signed char}}{integer}{}
\lineiv{B}{\ctype{unsigned char}}{integer}{}
+ \lineiv{t}{\ctype{_Bool}}{bool}{(1)}
\lineiv{h}{\ctype{short}}{integer}{}
\lineiv{H}{\ctype{unsigned short}}{integer}{}
\lineiv{i}{\ctype{int}}{integer}{}
\lineiv{I}{\ctype{unsigned int}}{long}{}
\lineiv{l}{\ctype{long}}{integer}{}
\lineiv{L}{\ctype{unsigned long}}{long}{}
- \lineiv{q}{\ctype{long long}}{long}{(1)}
- \lineiv{Q}{\ctype{unsigned long long}}{long}{(1)}
+ \lineiv{q}{\ctype{long long}}{long}{(2)}
+ \lineiv{Q}{\ctype{unsigned long long}}{long}{(2)}
\lineiv{f}{\ctype{float}}{float}{}
\lineiv{d}{\ctype{double}}{float}{}
\lineiv{s}{\ctype{char[]}}{string}{}
@@ -70,6 +71,11 @@ Notes:
\begin{description}
\item[(1)]
+ The \character{t} conversion code corresponds to the \ctype{_Bool} type
+ defined by C99. If this type is not available, it is simulated using a
+ \ctype{char}. In standard mode, it is always represented by one byte.
+ \versionadded{2.6}
+\item[(2)]
The \character{q} and \character{Q} conversion codes are available in
native mode only if the platform C compiler supports C \ctype{long long},
or, on Windows, \ctype{__int64}. They are always available in standard
@@ -118,6 +124,12 @@ example, the Alpha and Merced processors use 64-bit pointer values,
meaning a Python long integer will be used to hold the pointer; other
platforms use 32-bit pointers and will use a Python integer.
+For the \character{t} format character, the return value is either
+\constant{True} or \constant{False}. When packing, the truth value
+of the argument object is used. Either 0 or 1 in the native or standard
+bool representation will be packed, and any non-zero value will be True
+when unpacking.
+
By default, C numbers are represented in the machine's native format
and byte order, and properly aligned by skipping pad bytes if
necessary (according to the rules used by the C compiler).
@@ -151,6 +163,7 @@ for any type (so you have to use pad bytes);
\ctype{long long} (\ctype{__int64} on Windows) is 8 bytes;
\ctype{float} and \ctype{double} are 32-bit and 64-bit
IEEE floating point numbers, respectively.
+\ctype{_Bool} is 1 byte.
Note the difference between \character{@} and \character{=}: both use
native byte order, but the size and alignment of the latter is
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index f40838a..e276045 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -324,6 +324,12 @@ Support for the \code{\%Z} directive is based on the values contained in
it is platform-specific except for recognizing UTC and GMT which are
always known (and are considered to be non-daylight savings
timezones).
+
+Only the directives specified in the documentation are supported. Because
+\code{strftime()} is implemented per platform it can sometimes offer more
+directives than those listed. But \code{strptime()} is independent of any
+platform and thus does not necessarily support all directives available that
+are not documented as supported.
\end{funcdesc}
\begin{datadesc}{struct_time}