diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/newtypes.tex | 16 | ||||
| -rw-r--r-- | Doc/dist/dist.tex | 4 | ||||
| -rw-r--r-- | Doc/lib/libdoctest.tex | 15 | ||||
| -rw-r--r-- | Doc/lib/libfunctools.tex | 46 | ||||
| -rw-r--r-- | Doc/lib/libsgmllib.tex | 5 | ||||
| -rw-r--r-- | Doc/lib/libsocket.tex | 4 | ||||
| -rw-r--r-- | Doc/lib/libsqlite3.tex | 101 | ||||
| -rw-r--r-- | Doc/lib/liburllib2.tex | 12 | ||||
| -rw-r--r-- | Doc/mac/undoc.tex | 11 | ||||
| -rw-r--r-- | Doc/whatsnew/whatsnew25.tex | 22 |
10 files changed, 189 insertions, 47 deletions
diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex index 28f77f7..04f6795 100644 --- a/Doc/api/newtypes.tex +++ b/Doc/api/newtypes.tex @@ -1549,7 +1549,9 @@ to be able to test for its presence before using it.} Before using this slot, the caller should test whether it is present by using the \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} - function. If present, it may be \NULL, indicating that the object's + function. If the flag is present, \member{bf_getcharbuffer} may be + \NULL, + indicating that the object's contents cannot be used as \emph{8-bit characters}. The slot function may also raise an error if the object's contents cannot be interpreted as 8-bit characters. For example, if the @@ -1574,12 +1576,13 @@ to be able to test for its presence before using it.} \begin{ctypedesc}[getreadbufferproc]{Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)} - Return a pointer to a readable segment of the buffer. This function + Return a pointer to a readable segment of the buffer in + \code{*\var{ptrptr}}. This function is allowed to raise an exception, in which case it must return - \code{-1}. The \var{segment} which is passed must be zero or + \code{-1}. The \var{segment} which is specified must be zero or positive, and strictly less than the number of segments returned by the \member{bf_getsegcount} slot function. On success, it returns - the length of the buffer memory, and sets \code{*\var{ptrptr}} to a + the length of the segment, and sets \code{*\var{ptrptr}} to a pointer to that memory. \end{ctypedesc} @@ -1608,8 +1611,9 @@ to be able to test for its presence before using it.} \begin{ctypedesc}[getcharbufferproc]{Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr)} - Return the size of the memory buffer in \var{ptrptr} for segment - \var{segment}. \code{*\var{ptrptr}} is set to the memory buffer. + Return the size of the segment \var{segment} that \var{ptrptr} + is set to. \code{*\var{ptrptr}} is set to the memory buffer. + Returns \code{-1} on error. \end{ctypedesc} diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index 9970ec2..e95c0d3 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -849,7 +849,7 @@ version. This information includes: {long string}{} \lineiv{download_url}{location where the package may be downloaded} {URL}{(4)} - \lineiv{classifiers}{a list of Trove classifiers} + \lineiv{classifiers}{a list of classifiers} {list of strings}{(4)} \end{tableiv} @@ -2251,7 +2251,7 @@ are laid out in the following table. \lineiii{scripts}{A list of standalone script files to be built and installed}{a list of strings} \lineiii{ext_modules}{A list of Python extensions to be built}{A list of instances of \class{distutils.core.Extension}} -\lineiii{classifiers}{A list of Trove categories for the package}{XXX link to better definition} +\lineiii{classifiers}{A list of categories for the package}{The list of available categorizations is at \url{http://cheeseshop.python.org/pypi?:action=list_classifiers}.} \lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}} % What on earth is the use case for script_name? \lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string} diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index f9a97fa..957ecf4 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -952,7 +952,7 @@ sections \ref{doctest-simple-testmod} and \begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{, globs}\optional{, verbose}\optional{, - isprivate}\optional{, report}\optional{, + report}\optional{, optionflags}\optional{, extraglobs}\optional{, raise_on_error}\optional{, exclude_empty}} @@ -990,19 +990,14 @@ sections \ref{doctest-simple-testmod} and for function \function{testfile()} above, except that \var{globs} defaults to \code{\var{m}.__dict__}. - Optional argument \var{isprivate} specifies a function used to - determine whether a name is private. The default function treats - all names as public. \var{isprivate} can be set to - \code{doctest.is_private} to skip over names that are - private according to Python's underscore naming convention. - \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it. - If you need to skip tests based on name, filter the list returned by - \code{DocTestFinder.find()} instead.} - \versionchanged[The parameter \var{optionflags} was added]{2.3} \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error} and \var{exclude_empty} were added]{2.4} + + \versionchanged[The optional argument \var{isprivate}, deprecated + in 2.4, was removed]{2.5} + \end{funcdesc} There's also a function to run the doctests associated with a single object. diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex index a25a23a..33a6f52 100644 --- a/Doc/lib/libfunctools.tex +++ b/Doc/lib/libfunctools.tex @@ -5,6 +5,7 @@ \moduleauthor{Peter Harris}{scav@blueyonder.co.uk} \moduleauthor{Raymond Hettinger}{python@rcn.com} +\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com} \sectionauthor{Peter Harris}{scav@blueyonder.co.uk} \modulesynopsis{Higher-order functions and operations on callable objects.} @@ -50,6 +51,51 @@ two: \end{verbatim} \end{funcdesc} +\begin{funcdesc}{update_wrapper} +{wrapper, wrapped\optional{, assigned}\optional{, updated}} +Update a wrapper function to look like the wrapped function. The optional +arguments are tuples to specify which attributes of the original +function are assigned directly to the matching attributes on the wrapper +function and which attributes of the wrapper function are updated with +the corresponding attributes from the original function. The default +values for these arguments are the module level constants +\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's name, +module and documentation string) and \var{WRAPPER_UPDATES} (which +updates the wrapper function's instance dictionary). + +The main intended use for this function is in decorator functions +which wrap the decorated function and return the wrapper. If the +wrapper function is not updated, the metadata of the returned function +will reflect the wrapper definition rather than the original function +definition, which is typically less than helpful. +\end{funcdesc} + +\begin{funcdesc}{wraps} +{wrapped\optional{, assigned}\optional{, updated}} +This is a convenience function for invoking +\code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)} +as a function decorator when defining a wrapper function. For example: + \begin{verbatim} + >>> def my_decorator(f): + ... @wraps(f) + ... def wrapper(*args, **kwds): + ... print 'Calling decorated function' + ... return f(*args, **kwds) + ... return wrapper + ... + >>> @my_decorator + ... def example(): + ... print 'Called example function' + ... + >>> example() + Calling decorated function + Called example function + >>> example.__name__ + 'example' + \end{verbatim} +Without the use of this decorator factory, the name of the example +function would have been \code{'wrapper'}. +\end{funcdesc} \subsection{\class{partial} Objects \label{partial-objects}} diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex index 1578313..3ec1018 100644 --- a/Doc/lib/libsgmllib.tex +++ b/Doc/lib/libsgmllib.tex @@ -218,8 +218,9 @@ preference over \method{do_\var{tag}()}. The \end{methoddescni} \begin{methoddescni}{do_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag} that does -not come with a matching closing tag. The \var{attributes} argument +This method is called to process an opening tag \var{tag} +for which no \method{start_\var{tag}} method is defined. +The \var{attributes} argument has the same meaning as described for \method{handle_starttag()} above. \end{methoddescni} diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index c7b656d..8066528 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -548,7 +548,7 @@ are described in \ref{bltin-file-objects}, ``File Objects.'') The file object references a \cfunction{dup()}ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently. -The socket should be in blocking mode. +The socket must be in blocking mode. \index{I/O control!buffering}The optional \var{mode} and \var{bufsize} arguments are interpreted the same way as by the built-in \function{file()} function; see ``Built-in Functions'' @@ -647,7 +647,7 @@ Timeout mode internally sets the socket in non-blocking mode. The blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. A consequence of this is that file objects returned by the \method{makefile()} -method should only be used when the socket is in blocking mode; in +method must only be used when the socket is in blocking mode; in timeout or non-blocking mode file operations that cannot be completed immediately will fail. diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex index 8c80eb6..db15c00 100644 --- a/Doc/lib/libsqlite3.tex +++ b/Doc/lib/libsqlite3.tex @@ -6,6 +6,105 @@ \sectionauthor{Gerhard Häring}{gh@ghaering.de} \versionadded{2.5} +SQLite is a C library that provides a SQL-language database that +stores data in disk files without requiring a separate server process. +pysqlite was written by Gerhard H\"aring and provides a SQL interface +compliant with the DB-API 2.0 specification described by +\pep{249}. This means that it should be possible to write the first +version of your applications using SQLite for data storage. If +switching to a larger database such as PostgreSQL or Oracle is +later necessary, the switch should be relatively easy. + +To use the module, you must first create a \class{Connection} object +that represents the database. Here the data will be stored in the +\file{/tmp/example} file: + +\begin{verbatim} +conn = sqlite3.connect('/tmp/example') +\end{verbatim} + +You can also supply the special name \samp{:memory:} to create +a database in RAM. + +Once you have a \class{Connection}, you can create a \class{Cursor} +object and call its \method{execute()} method to perform SQL commands: + +\begin{verbatim} +c = conn.cursor() + +# Create table +c.execute('''create table stocks +(date timestamp, trans varchar, symbol varchar, + qty decimal, price decimal)''') + +# Insert a row of data +c.execute("""insert into stocks + values ('2006-01-05','BUY','RHAT',100,35.14)""") +\end{verbatim} + +Usually your SQL operations will need to use values from Python +variables. You shouldn't assemble your query using Python's string +operations because doing so is insecure; it makes your program +vulnerable to an SQL injection attack. + +Instead, use the DB-API's parameter substitution. Put \samp{?} as a +placeholder wherever you want to use a value, and then provide a tuple +of values as the second argument to the cursor's \method{execute()} +method. (Other database modules may use a different placeholder, +such as \samp{\%s} or \samp{:1}.) For example: + +\begin{verbatim} +# Never do this -- insecure! +symbol = 'IBM' +c.execute("... where symbol = '%s'" % symbol) + +# Do this instead +t = (symbol,) +c.execute('select * from stocks where symbol=?', t) + +# Larger example +for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00), + ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00), + ('2006-04-06', 'SELL', 'IBM', 500, 53.00), + ): + c.execute('insert into stocks values (?,?,?,?,?)', t) +\end{verbatim} + +To retrieve data after executing a SELECT statement, you can either +treat the cursor as an iterator, call the cursor's \method{fetchone()} +method to retrieve a single matching row, +or call \method{fetchall()} to get a list of the matching rows. + +This example uses the iterator form: + +\begin{verbatim} +>>> c = conn.cursor() +>>> c.execute('select * from stocks order by price') +>>> for row in c: +... print row +... +(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001) +(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0) +(u'2006-04-06', u'SELL', u'IBM', 500, 53.0) +(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0) +>>> +\end{verbatim} + +\begin{seealso} + +\seeurl{http://www.pysqlite.org} +{The pysqlite web page.} + +\seeurl{http://www.sqlite.org} +{The SQLite web page; the documentation describes the syntax and the +available data types for the supported SQL dialect.} + +\seepep{249}{Database API Specification 2.0}{PEP written by +Marc-Andr\'e Lemburg.} + +\end{seealso} + + \subsection{Module functions and constants\label{sqlite3-Module-Contents}} \begin{datadesc}{PARSE_DECLTYPES} @@ -467,7 +566,7 @@ connections. If you want \strong{autocommit mode}, then set \member{isolation_level} to None. -Otherwise leave it at it's default, which will result in a plain "BEGIN" +Otherwise leave it at its default, which will result in a plain "BEGIN" statement, or set it to one of SQLite's supported isolation levels: DEFERRED, IMMEDIATE or EXCLUSIVE. diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex index f77ed25..f4351c3 100644 --- a/Doc/lib/liburllib2.tex +++ b/Doc/lib/liburllib2.tex @@ -18,11 +18,13 @@ The \module{urllib2} module defines the following functions: Open the URL \var{url}, which can be either a string or a \class{Request} object. -\var{data} should be a string, which specifies additional data to -send to the server. In HTTP requests, which are the only ones that -support \var{data}, it should be a buffer in the format of -\mimetype{application/x-www-form-urlencoded}, for example one returned -from \function{urllib.urlencode()}. +\var{data} may be a string specifying additional data to send to the +server. Currently HTTP requests are the only ones that use \var{data}; +the HTTP request will be a POST instead of a GET when the \var{data} +parameter is provided. \var{data} should be a buffer in the standard +\mimetype{application/x-www-form-urlencoded} format. The +\function{urllib.urlencode()} function takes a mapping or sequence of +2-tuples and returns a string in this format. This function returns a file-like object with two additional methods: diff --git a/Doc/mac/undoc.tex b/Doc/mac/undoc.tex index 63a4dbd..72abadf 100644 --- a/Doc/mac/undoc.tex +++ b/Doc/mac/undoc.tex @@ -95,14 +95,3 @@ audio tracks. The \module{W} widgets are used extensively in the \program{IDE}. -\section{\module{waste} --- non-Apple \program{TextEdit} replacement} -\declaremodule{standard}{waste} - \platform{Mac} -\modulesynopsis{Interface to the ``WorldScript-Aware Styled Text Engine.''} - -\begin{seealso} - \seetitle[http://www.merzwaren.com/waste/]{About WASTE}{Information - about the WASTE widget and library, including - documentation and downloads.} -\end{seealso} - diff --git a/Doc/whatsnew/whatsnew25.tex b/Doc/whatsnew/whatsnew25.tex index 5bee789..4015d98 100644 --- a/Doc/whatsnew/whatsnew25.tex +++ b/Doc/whatsnew/whatsnew25.tex @@ -1166,12 +1166,13 @@ In 2.5 the internal data structure has been customized for implementing sets, and as a result sets will use a third less memory and are somewhat faster. (Implemented by Raymond Hettinger.) -\item The speed of some Unicode operations, such as -finding substrings, string splitting, and character map decoding, has -been improved. (Substring search and splitting improvements were +\item The speed of some Unicode operations, such as finding +substrings, string splitting, and character map encoding and decoding, +has been improved. (Substring search and splitting improvements were added by Fredrik Lundh and Andrew Dalke at the NeedForSpeed -sprint. Character map decoding was improved by Walter D\"orwald.) -% Patch 1313939 +sprint. Character maps were improved by Walter D\"orwald and +Martin von~L\"owis.) +% Patch 1313939, 1359618 \item The \function{long(\var{str}, \var{base})} function is now faster on long digit strings because fewer intermediate results are @@ -1185,6 +1186,11 @@ strings into an internal representation and caches this representation, yielding a 20\% speedup. (Contributed by Bob Ippolito at the NeedForSpeed sprint.) +\item The \module{re} module got a 1 or 2\% speedup by switching to +Python's allocator functions instead of the system's +\cfunction{malloc()} and \cfunction{free()}. +(Contributed by Jack Diederich at the NeedForSpeed sprint.) + \item The code generator's peephole optimizer now performs simple constant folding in expressions. If you write something like \code{a = 2+3}, the code generator will do the arithmetic and produce @@ -1358,7 +1364,6 @@ to specify which generation to collect. now support a \code{key} keyword parameter similar to the one provided by the \function{min()}/\function{max()} functions and the \method{sort()} methods. For example: -Example: \begin{verbatim} >>> import heapq @@ -1923,10 +1928,11 @@ variables. You shouldn't assemble your query using Python's string operations because doing so is insecure; it makes your program vulnerable to an SQL injection attack. -Instead, use SQLite's parameter substitution. Put \samp{?} as a +Instead, use the DB-API's parameter substitution. Put \samp{?} as a placeholder wherever you want to use a value, and then provide a tuple of values as the second argument to the cursor's \method{execute()} -method. For example: +method. (Other database modules may use a different placeholder, +such as \samp{\%s} or \samp{:1}.) For example: \begin{verbatim} # Never do this -- insecure! |