diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/concrete.tex | 4 | ||||
| -rw-r--r-- | Doc/commontex/license.tex | 1 | ||||
| -rw-r--r-- | Doc/dist/dist.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libmailbox.tex | 82 | ||||
| -rw-r--r-- | Doc/lib/librandom.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libstruct.tex | 17 | ||||
| -rw-r--r-- | Doc/lib/libtime.tex | 6 | ||||
| -rw-r--r-- | Doc/ref/ref3.tex | 4 |
8 files changed, 85 insertions, 33 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 33b04d4..e2d3e52 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -2082,7 +2082,7 @@ format. \begin{verbatim} PyObject *key, *value; -int pos = 0; +Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { /* do something interesting with the values... */ @@ -2097,7 +2097,7 @@ while (PyDict_Next(self->dict, &pos, &key, &value)) { \begin{verbatim} PyObject *key, *value; -int pos = 0; +Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { int i = PyInt_AS_LONG(value) + 1; diff --git a/Doc/commontex/license.tex b/Doc/commontex/license.tex index d1554c2..c98a2c3 100644 --- a/Doc/commontex/license.tex +++ b/Doc/commontex/license.tex @@ -50,6 +50,7 @@ GPL-compatible; the table below summarizes the various releases. \linev{2.4.1}{2.4}{2005}{PSF}{yes} \linev{2.4.2}{2.4.1}{2005}{PSF}{yes} \linev{2.4.3}{2.4.2}{2006}{PSF}{yes} + \linev{2.4.4}{2.4.3}{2006}{PSF}{yes} \linev{2.5}{2.4}{2006}{PSF}{yes} \end{tablev} diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index ba90763..7a0f073 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -692,7 +692,7 @@ Some examples: \begin{tableii}{l|l}{code}{Provides Expression}{Explanation} \lineii{mypkg} {Provide \code{mypkg}, using the distribution version} - \lineii{mypkg (1.1} {Provide \code{mypkg} version 1.1, regardless of the + \lineii{mypkg (1.1)} {Provide \code{mypkg} version 1.1, regardless of the distribution version} \end{tableii} 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} diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index fb57eb0..4b9da9e 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -1997,8 +1997,8 @@ complicated). \methodline[numeric object]{__ixor__}{self, other} \methodline[numeric object]{__ior__}{self, other} These methods are called to implement the augmented arithmetic -operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=}, -\code{**=}, \code{<<=}, \code{>>=}, \code{\&=}, +operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{//=}, +\code{\%=}, \code{**=}, \code{<<=}, \code{>>=}, \code{\&=}, \code{\textasciicircum=}, \code{|=}). These methods should attempt to do the operation in-place (modifying \var{self}) and return the result (which could be, but does not have to be, \var{self}). If a specific method |