diff options
Diffstat (limited to 'Doc/lib')
| -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 |
6 files changed, 163 insertions, 20 deletions
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: |