the methods listed below.
\versionchanged[Added dictionary methods]{2.3.1}
-\begin{methoddesc}{close}{}
+\begin{methoddesc}[bsddbobject]{close}{}
Close the underlying file. The object can no longer be accessed. Since
there is no open \method{open} method for these objects, to open the file
again a new \module{bsddb} module open function must be called.
\end{methoddesc}
-\begin{methoddesc}{keys}{}
+\begin{methoddesc}[bsddbobject]{keys}{}
Return the list of keys contained in the DB file. The order of the list is
unspecified and should not be relied on. In particular, the order of the
list returned is different for different file formats.
\end{methoddesc}
-\begin{methoddesc}{has_key}{key}
+\begin{methoddesc}[bsddbobject]{has_key}{key}
Return \code{1} if the DB file contains the argument as a key.
\end{methoddesc}
-\begin{methoddesc}{set_location}{key}
+\begin{methoddesc}[bsddbobject]{set_location}{key}
Set the cursor to the item indicated by \var{key} and return a tuple
containing the key and its value. For binary tree databases (opened
using \function{btopen()}), if \var{key} does not actually exist in
database.
\end{methoddesc}
-\begin{methoddesc}{first}{}
+\begin{methoddesc}[bsddbobject]{first}{}
Set the cursor to the first item in the DB file and return it. The order of
keys in the file is unspecified, except in the case of B-Tree databases.
This method raises \exception{bsddb.error} if the database is empty.
\end{methoddesc}
-\begin{methoddesc}{next}{}
+\begin{methoddesc}[bsddbobject]{next}{}
Set the cursor to the next item in the DB file and return it. The order of
keys in the file is unspecified, except in the case of B-Tree databases.
\end{methoddesc}
-\begin{methoddesc}{previous}{}
+\begin{methoddesc}[bsddbobject]{previous}{}
Set the cursor to the previous item in the DB file and return it. The
order of keys in the file is unspecified, except in the case of B-Tree
databases. This is not supported on hashtable databases (those opened
with \function{hashopen()}).
\end{methoddesc}
-\begin{methoddesc}{last}{}
+\begin{methoddesc}[bsddbobject]{last}{}
Set the cursor to the last item in the DB file and return it. The
order of keys in the file is unspecified. This is not supported on
hashtable databases (those opened with \function{hashopen()}).
This method raises \exception{bsddb.error} if the database is empty.
\end{methoddesc}
-\begin{methoddesc}{sync}{}
+\begin{methoddesc}[bsddbobject]{sync}{}
Synchronize the database on disk.
\end{methoddesc}
context\optional{, format}}}}}
This function causes the \module{cgitb} module to take over the
interpreter's default handling for exceptions by setting the
- value of \code{\refmodule{sys}.excepthook}.
+ value of \member{\refmodule{sys}.excepthook}.
\withsubitem{(in module sys)}{\ttindex{excepthook()}}
The optional argument \var{display} defaults to \code{1} and can be set
report it using \module{cgitb}. The optional \var{info} argument
should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
- \code{\refmodule{sys}.exc_info()}. If the \var{info} argument
+ \function{\refmodule{sys}.exc_info()}. If the \var{info} argument
is not supplied, the current exception is obtained from
- \code{\refmodule{sys}.exc_info()}.
+ \function{\refmodule{sys}.exc_info()}.
\end{funcdesc}
The \class{Codec} class defines these methods which also define the
function interfaces of the stateless encoder and decoder:
-\begin{methoddesc}{encode}{input\optional{, errors}}
+\begin{methoddesc}[Codec]{encode}{input\optional{, errors}}
Encodes the object \var{input} and returns a tuple (output object,
length consumed). While codecs are not restricted to use with Unicode, in
a Unicode context, encoding converts a Unicode object to a plain string
empty object of the output object type in this situation.
\end{methoddesc}
-\begin{methoddesc}{decode}{input\optional{, errors}}
+\begin{methoddesc}[Codec]{decode}{input\optional{, errors}}
Decodes the object \var{input} and returns a tuple (output object,
length consumed). In a Unicode context, decoding converts a plain string
encoded using a particular character set encoding to a Unicode object.
\lineiv{idna}
{}
{Unicode string}
- {Implements \rfc{3490}.
- \versionadded{2.3}
- See also \refmodule{encodings.idna}}
+ {Implements \rfc{3490},
+ see also \refmodule{encodings.idna}}
\lineiv{mbcs}
{dbcs}
\lineiv{punycode}
{}
{Unicode string}
- {Implements \rfc{3492}.
- \versionadded{2.3}}
+ {Implements \rfc{3492}}
\lineiv{quopri_codec}
{quopri, quoted-printable, quotedprintable}
\end{tableiv}
+\versionadded[The \code{idna} and \code{punycode} encodings]{2.3}
+
\subsection{\module{encodings.idna} ---
Internationalized Domain Names in Applications}
\subsection{\class{deque} objects \label{deque-objects}}
-\begin{funcdesc}{deque}{\optional{iterable}}
+\begin{classdesc}{deque}{\optional{iterable}}
Returns a new deque object initialized left-to-right (using
\method{append()}) with data from \var{iterable}. If \var{iterable}
is not specified, the new deque is empty.
for \samp{pop(0)} and \samp{insert(0, v)} operations which change both the
size and position of the underlying data representation.
\versionadded{2.4}
-\end{funcdesc}
+\end{classdesc}
Deque objects support the following methods:
\end{datadesc}
\begin{datadesc}{None}
- The sole value of \code{\refmodule{types}.NoneType}. \code{None} is
+ The sole value of \member{\refmodule{types}.NoneType}. \code{None} is
frequently used to represent the absence of a value, as when default
arguments are not passed to a function.
\end{datadesc}
Panel objects have the following methods:
-\begin{methoddesc}{above}{}
+\begin{methoddesc}[Panel]{above}{}
Returns the panel above the current panel.
\end{methoddesc}
-\begin{methoddesc}{below}{}
+\begin{methoddesc}[Panel]{below}{}
Returns the panel below the current panel.
\end{methoddesc}
-\begin{methoddesc}{bottom}{}
+\begin{methoddesc}[Panel]{bottom}{}
Push the panel to the bottom of the stack.
\end{methoddesc}
-\begin{methoddesc}{hidden}{}
+\begin{methoddesc}[Panel]{hidden}{}
Returns true if the panel is hidden (not visible), false otherwise.
\end{methoddesc}
-\begin{methoddesc}{hide}{}
+\begin{methoddesc}[Panel]{hide}{}
Hide the panel. This does not delete the object, it just makes the
window on screen invisible.
\end{methoddesc}
-\begin{methoddesc}{move}{y, x}
+\begin{methoddesc}[Panel]{move}{y, x}
Move the panel to the screen coordinates \code{(\var{y}, \var{x})}.
\end{methoddesc}
-\begin{methoddesc}{replace}{win}
+\begin{methoddesc}[Panel]{replace}{win}
Change the window associated with the panel to the window \var{win}.
\end{methoddesc}
-\begin{methoddesc}{set_userptr}{obj}
+\begin{methoddesc}[Panel]{set_userptr}{obj}
Set the panel's user pointer to \var{obj}. This is used to associate an
arbitrary piece of data with the panel, and can be any Python object.
\end{methoddesc}
-\begin{methoddesc}{show}{}
+\begin{methoddesc}[Panel]{show}{}
Display the panel (which might have been hidden).
\end{methoddesc}
-\begin{methoddesc}{top}{}
+\begin{methoddesc}[Panel]{top}{}
Push panel to the top of the stack.
\end{methoddesc}
-\begin{methoddesc}{userptr}{}
+\begin{methoddesc}[Panel]{userptr}{}
Returns the user pointer for the panel. This might be any Python object.
\end{methoddesc}
-\begin{methoddesc}{window}{}
+\begin{methoddesc}[Panel]{window}{}
Returns the window object associated with the panel.
\end{methoddesc}
Dl objects, as returned by \function{open()} above, have the
following methods:
-\begin{methoddesc}{close}{}
+\begin{methoddesc}[dl]{close}{}
Free all resources, except the memory.
\end{methoddesc}
-\begin{methoddesc}{sym}{name}
+\begin{methoddesc}[dl]{sym}{name}
Return the pointer for the function named \var{name}, as a number, if
it exists in the referenced shared object, otherwise \code{None}. This
is useful in code like:
\NULL{} pointer)
\end{methoddesc}
-\begin{methoddesc}{call}{name\optional{, arg1\optional{, arg2\ldots}}}
+\begin{methoddesc}[dl]{call}{name\optional{, arg1\optional{, arg2\ldots}}}
Call the function named \var{name} in the referenced shared object.
The arguments must be either Python integers, which will be
passed as is, Python strings, to which a pointer will be passed,
>>>
\end{verbatim}
- \versionchanged[The ability to use \code{\refmodule{pdb}.set_trace()}
+ \versionchanged[The ability to use \function{\refmodule{pdb}.set_trace()}
usefully inside doctests was added]{2.4}
\end{itemize}
used. If \var{pm} has a true value, the script file is run directly, and
the debugger gets involved only if the script terminates via raising an
unhandled exception. If it does, then post-mortem debugging is invoked,
- via \code{\refmodule{pdb}.post_mortem()}, passing the traceback object
+ via \function{\refmodule{pdb}.post_mortem()}, passing the traceback object
from the unhandled exception. If \var{pm} is not specified, or is false,
the script is run under the debugger from the start, via passing an
- appropriate \function{execfile()} call to \code{\refmodule{pdb}.run()}.
+ appropriate \function{execfile()} call to \function{\refmodule{pdb}.run()}.
\versionadded{2.3}
In addition to the methods provided by the \class{UserDict.DictMixin} class,
\class{dumbdbm} objects provide the following methods.
-\begin{methoddesc}{sync}{}
+\begin{methoddesc}[dumbdbm]{sync}{}
Synchronize the on-disk directory and data files. This method is called by
the \method{sync} method of \class{Shelve} objects.
\end{methoddesc}
Element objects returned by Element or SubElement have the
following methods and attributes.
-\begin{memberdesc}{tag}
+\begin{memberdesc}[Element]{tag}
A string identifying what kind of data this element represents
(the element type, in other words).
\end{memberdesc}
-\begin{memberdesc}{text}
+\begin{memberdesc}[Element]{text}
The \var{text} attribute can be used to hold additional data
associated with the element.
As the name implies this attribute is usually a string but may be any
any text found between the element tags.
\end{memberdesc}
-\begin{memberdesc}{tail}
+\begin{memberdesc}[Element]{tail}
The \var{tail} attribute can be used to hold additional data
associated with the element.
This attribute is usually a string but may be any application-specific object.
any text found after the element's end tag and before the next tag.
\end{memberdesc}
-\begin{memberdesc}{attrib}
+\begin{memberdesc}[Element]{attrib}
A dictionary containing the element's attributes.
Note that while the \var{attrib} value is always a real mutable Python
dictionary, an ElementTree implementation may choose to use another
The following dictionary-like methods work on the element attributes.
-\begin{methoddesc}{clear}{}
+\begin{methoddesc}[Element]{clear}{}
Resets an element. This function removes all subelements, clears
all attributes, and sets the text and tail attributes to None.
\end{methoddesc}
-\begin{methoddesc}{get}{key\optional{, default=None}}
+\begin{methoddesc}[Element]{get}{key\optional{, default=None}}
Gets the element attribute named \var{key}.
Returns the attribute value, or \var{default} if the
attribute was not found.
\end{methoddesc}
-\begin{methoddesc}{items}{}
+\begin{methoddesc}[Element]{items}{}
Returns the element attributes as a sequence of (name, value) pairs.
The attributes are returned in an arbitrary order.
\end{methoddesc}
-\begin{methoddesc}{keys}{}
+\begin{methoddesc}[Element]{keys}{}
Returns the elements attribute names as a list.
The names are returned in an arbitrary order.
\end{methoddesc}
-\begin{methoddesc}{set}{key, value}
+\begin{methoddesc}[Element]{set}{key, value}
Set the attribute \var{key} on the element to \var{value}.
\end{methoddesc}
The following methods work on the element's children (subelements).
-\begin{methoddesc}{append}{subelement}
+\begin{methoddesc}[Element]{append}{subelement}
Adds the element \var{subelement} to the end of this elements internal list
of subelements.
\end{methoddesc}
-\begin{methoddesc}{find}{match}
+\begin{methoddesc}[Element]{find}{match}
Finds the first subelement matching \var{match}.
\var{match} may be a tag name or path.
Returns an element instance or \code{None}.
\end{methoddesc}
-\begin{methoddesc}{findall}{match}
+\begin{methoddesc}[Element]{findall}{match}
Finds all subelements matching \var{match}.
\var{match} may be a tag name or path.
Returns an iterable yielding all matching elements in document order.
\end{methoddesc}
-\begin{methoddesc}{findtext}{condition\optional{, default=None}}
+\begin{methoddesc}[Element]{findtext}{condition\optional{, default=None}}
Finds text for the first subelement matching \var{condition}.
\var{condition} may be a tag name or path.
Returns the text content of the first matching element, or
matching element has no text content an empty string is returned.
\end{methoddesc}
-\begin{methoddesc}{getchildren}{}
+\begin{methoddesc}[Element]{getchildren}{}
Returns all subelements. The elements are returned in document order.
\end{methoddesc}
-\begin{methoddesc}{getiterator}{\optional{tag=None}}
+\begin{methoddesc}[Element]{getiterator}{\optional{tag=None}}
Creates a tree iterator with the current element as the root.
The iterator iterates over this element and all elements below it
that match the given tag. If tag
order.
\end{methoddesc}
-\begin{methoddesc}{insert}{index, element}
+\begin{methoddesc}[Element]{insert}{index, element}
Inserts a subelement at the given position in this element.
\end{methoddesc}
-\begin{methoddesc}{makeelement}{tag, attrib}
+\begin{methoddesc}[Element]{makeelement}{tag, attrib}
Creates a new element object of the same type as this element.
Do not call this method, use the SubElement factory function instead.
\end{methoddesc}
-\begin{methoddesc}{remove}{subelement}
+\begin{methoddesc}[Element]{remove}{subelement}
Removes \var{subelement} from the element.
Unlike the findXXX methods this method compares elements based on
the instance identity, not on tag value or contents.
Return a new hmac object. If \var{msg} is present, the method call
\code{update(\var{msg})} is made. \var{digestmod} is the digest
constructor or module for the HMAC object to use. It defaults to
- the \code{\refmodule{hashlib}.md5} constructor. \note{The md5 hash
+ the \function{\refmodule{hashlib}.md5} constructor. \note{The md5 hash
has known weaknesses but remains the default for backwards compatibility.
Choose a better one for your application.}
\end{funcdesc}
never instantiated directly, but always through the module-level function
\function{logging.getLogger(name)}.
-\begin{datadesc}{propagate}
+\begin{memberdesc}[Logger]{propagate}
If this evaluates to false, logging messages are not passed by this
logger or by child loggers to higher level (ancestor) loggers. The
constructor sets this attribute to 1.
-\end{datadesc}
+\end{memberdesc}
-\begin{methoddesc}{setLevel}{lvl}
+\begin{methoddesc}[Logger]{setLevel}{lvl}
Sets the threshold for this logger to \var{lvl}. Logging messages
which are less severe than \var{lvl} will be ignored. When a logger is
created, the level is set to \constant{NOTSET} (which causes all messages
as the effective level.
\end{methoddesc}
-\begin{methoddesc}{isEnabledFor}{lvl}
+\begin{methoddesc}[Logger]{isEnabledFor}{lvl}
Indicates if a message of severity \var{lvl} would be processed by
this logger. This method checks first the module-level level set by
\function{logging.disable(lvl)} and then the logger's effective level as
determined by \method{getEffectiveLevel()}.
\end{methoddesc}
-\begin{methoddesc}{getEffectiveLevel}{}
+\begin{methoddesc}[Logger]{getEffectiveLevel}{}
Indicates the effective level for this logger. If a value other than
\constant{NOTSET} has been set using \method{setLevel()}, it is returned.
Otherwise, the hierarchy is traversed towards the root until a value
other than \constant{NOTSET} is found, and that value is returned.
\end{methoddesc}
-\begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{debug}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{DEBUG} on this logger.
The \var{msg} is the message format string, and the \var{args} are the
arguments which are merged into \var{msg} using the string formatting
\end{methoddesc}
-\begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{info}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{INFO} on this logger.
The arguments are interpreted as for \method{debug()}.
\end{methoddesc}
-\begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{warning}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{WARNING} on this logger.
The arguments are interpreted as for \method{debug()}.
\end{methoddesc}
-\begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{error}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{ERROR} on this logger.
The arguments are interpreted as for \method{debug()}.
\end{methoddesc}
-\begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{critical}{msg\optional{, *args\optional{, **kwargs}}}
Logs a message with level \constant{CRITICAL} on this logger.
The arguments are interpreted as for \method{debug()}.
\end{methoddesc}
-\begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
+\begin{methoddesc}[Logger]{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
Logs a message with integer level \var{lvl} on this logger.
The other arguments are interpreted as for \method{debug()}.
\end{methoddesc}
-\begin{methoddesc}{exception}{msg\optional{, *args}}
+\begin{methoddesc}[Logger]{exception}{msg\optional{, *args}}
Logs a message with level \constant{ERROR} on this logger.
The arguments are interpreted as for \method{debug()}. Exception info
is added to the logging message. This method should only be called
from an exception handler.
\end{methoddesc}
-\begin{methoddesc}{addFilter}{filt}
+\begin{methoddesc}[Logger]{addFilter}{filt}
Adds the specified filter \var{filt} to this logger.
\end{methoddesc}
-\begin{methoddesc}{removeFilter}{filt}
+\begin{methoddesc}[Logger]{removeFilter}{filt}
Removes the specified filter \var{filt} from this logger.
\end{methoddesc}
-\begin{methoddesc}{filter}{record}
+\begin{methoddesc}[Logger]{filter}{record}
Applies this logger's filters to the record and returns a true value if
the record is to be processed.
\end{methoddesc}
-\begin{methoddesc}{addHandler}{hdlr}
+\begin{methoddesc}[Logger]{addHandler}{hdlr}
Adds the specified handler \var{hdlr} to this logger.
\end{methoddesc}
-\begin{methoddesc}{removeHandler}{hdlr}
+\begin{methoddesc}[Logger]{removeHandler}{hdlr}
Removes the specified handler \var{hdlr} from this logger.
\end{methoddesc}
-\begin{methoddesc}{findCaller}{}
+\begin{methoddesc}[Logger]{findCaller}{}
Finds the caller's source filename and line number. Returns the filename,
line number and function name as a 3-element tuple.
\versionchanged[The function name was added. In earlier versions, the
filename and line number were returned as a 2-element tuple.]{2.5}
\end{methoddesc}
-\begin{methoddesc}{handle}{record}
+\begin{methoddesc}[Logger]{handle}{record}
Handles a record by passing it to all handlers associated with this logger
and its ancestors (until a false value of \var{propagate} is found).
This method is used for unpickled records received from a socket, as well
\method{filter()}.
\end{methoddesc}
-\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info
- \optional{, func, extra}}
+\begin{methoddesc}[Logger]{makeRecord}{name, lvl, fn, lno, msg, args, exc_info
+ \optional{, func, extra}}
This is a factory method which can be overridden in subclasses to create
specialized \class{LogRecord} instances.
\versionchanged[\var{func} and \var{extra} were added]{2.5}
base for more useful subclasses. However, the \method{__init__()}
method in subclasses needs to call \method{Handler.__init__()}.
-\begin{methoddesc}{__init__}{level=\constant{NOTSET}}
+\begin{methoddesc}[Handler]{__init__}{level=\constant{NOTSET}}
Initializes the \class{Handler} instance by setting its level, setting
the list of filters to the empty list and creating a lock (using
\method{createLock()}) for serializing access to an I/O mechanism.
\end{methoddesc}
-\begin{methoddesc}{createLock}{}
+\begin{methoddesc}[Handler]{createLock}{}
Initializes a thread lock which can be used to serialize access to
underlying I/O functionality which may not be threadsafe.
\end{methoddesc}
-\begin{methoddesc}{acquire}{}
+\begin{methoddesc}[Handler]{acquire}{}
Acquires the thread lock created with \method{createLock()}.
\end{methoddesc}
-\begin{methoddesc}{release}{}
+\begin{methoddesc}[Handler]{release}{}
Releases the thread lock acquired with \method{acquire()}.
\end{methoddesc}
-\begin{methoddesc}{setLevel}{lvl}
+\begin{methoddesc}[Handler]{setLevel}{lvl}
Sets the threshold for this handler to \var{lvl}. Logging messages which are
less severe than \var{lvl} will be ignored. When a handler is created, the
level is set to \constant{NOTSET} (which causes all messages to be processed).
\end{methoddesc}
-\begin{methoddesc}{setFormatter}{form}
+\begin{methoddesc}[Handler]{setFormatter}{form}
Sets the \class{Formatter} for this handler to \var{form}.
\end{methoddesc}
-\begin{methoddesc}{addFilter}{filt}
+\begin{methoddesc}[Handler]{addFilter}{filt}
Adds the specified filter \var{filt} to this handler.
\end{methoddesc}
-\begin{methoddesc}{removeFilter}{filt}
+\begin{methoddesc}[Handler]{removeFilter}{filt}
Removes the specified filter \var{filt} from this handler.
\end{methoddesc}
-\begin{methoddesc}{filter}{record}
+\begin{methoddesc}[Handler]{filter}{record}
Applies this handler's filters to the record and returns a true value if
the record is to be processed.
\end{methoddesc}
-\begin{methoddesc}{flush}{}
+\begin{methoddesc}[Handler]{flush}{}
Ensure all logging output has been flushed. This version does
nothing and is intended to be implemented by subclasses.
\end{methoddesc}
-\begin{methoddesc}{close}{}
+\begin{methoddesc}[Handler]{close}{}
Tidy up any resources used by the handler. This version does
nothing and is intended to be implemented by subclasses.
\end{methoddesc}
-\begin{methoddesc}{handle}{record}
+\begin{methoddesc}[Handler]{handle}{record}
Conditionally emits the specified logging record, depending on
filters which may have been added to the handler. Wraps the actual
emission of the record with acquisition/release of the I/O thread
lock.
\end{methoddesc}
-\begin{methoddesc}{handleError}{record}
+\begin{methoddesc}[Handler]{handleError}{record}
This method should be called from handlers when an exception is
encountered during an \method{emit()} call. By default it does nothing,
which means that exceptions get silently ignored. This is what is
processed when the exception occurred.
\end{methoddesc}
-\begin{methoddesc}{format}{record}
+\begin{methoddesc}[Handler]{format}{record}
Do formatting for a record - if a formatter is set, use it.
Otherwise, use the default formatter for the module.
\end{methoddesc}
-\begin{methoddesc}{emit}{record}
+\begin{methoddesc}[Handler]{emit}{record}
Do whatever it takes to actually log the specified logging record.
This version is intended to be implemented by subclasses and so
raises a \exception{NotImplementedError}.
Memory-mapped file objects support the following methods:
-\begin{methoddesc}{close}{}
+\begin{methoddesc}[mmap]{close}{}
Close the file. Subsequent calls to other methods of the object
will result in an exception being raised.
\end{methoddesc}
-\begin{methoddesc}{find}{string\optional{, start}}
+\begin{methoddesc}[mmap]{find}{string\optional{, start}}
Returns the lowest index in the object where the substring
\var{string} is found. Returns \code{-1} on failure. \var{start}
is the index at which the search begins, and defaults to zero.
\end{methoddesc}
-\begin{methoddesc}{flush}{\optional{offset, size}}
+\begin{methoddesc}[mmap]{flush}{\optional{offset, size}}
Flushes changes made to the in-memory copy of a file back to disk.
Without use of this call there is no guarantee that changes are
written back before the object is destroyed. If \var{offset} and
is flushed.
\end{methoddesc}
-\begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}}
+\begin{methoddesc}[mmap]{move}{\var{dest}, \var{src}, \var{count}}
Copy the \var{count} bytes starting at offset \var{src} to the
destination index \var{dest}. If the mmap was created with
\constant{ACCESS_READ}, then calls to move will throw a
\exception{TypeError} exception.
\end{methoddesc}
-\begin{methoddesc}{read}{\var{num}}
+\begin{methoddesc}[mmap]{read}{\var{num}}
Return a string containing up to \var{num} bytes starting from the
current file position; the file position is updated to point after the
bytes that were returned.
\end{methoddesc}
-\begin{methoddesc}{read_byte}{}
+\begin{methoddesc}[mmap]{read_byte}{}
Returns a string of length 1 containing the character at the current
file position, and advances the file position by 1.
\end{methoddesc}
-\begin{methoddesc}{readline}{}
+\begin{methoddesc}[mmap]{readline}{}
Returns a single line, starting at the current file position and up to
the next newline.
\end{methoddesc}
-\begin{methoddesc}{resize}{\var{newsize}}
+\begin{methoddesc}[mmap]{resize}{\var{newsize}}
Resizes the map and the underlying file, if any.
If the mmap was created with \constant{ACCESS_READ} or
\constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
\end{methoddesc}
-\begin{methoddesc}{seek}{pos\optional{, whence}}
+\begin{methoddesc}[mmap]{seek}{pos\optional{, whence}}
Set the file's current position. \var{whence} argument is optional
and defaults to \code{os.SEEK_SET} or \code{0} (absolute file
positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek
(seek relative to the file's end).
\end{methoddesc}
-\begin{methoddesc}{size}{}
+\begin{methoddesc}[mmap]{size}{}
Return the length of the file, which can be larger than the size of
the memory-mapped area.
\end{methoddesc}
-\begin{methoddesc}{tell}{}
+\begin{methoddesc}[mmap]{tell}{}
Returns the current position of the file pointer.
\end{methoddesc}
-\begin{methoddesc}{write}{\var{string}}
+\begin{methoddesc}[mmap]{write}{\var{string}}
Write the bytes in \var{string} into memory at the current position
of the file pointer; the file position is updated to point after the
bytes that were written. If the mmap was created with
\exception{TypeError} exception.
\end{methoddesc}
-\begin{methoddesc}{write_byte}{\var{byte}}
+\begin{methoddesc}[mmap]{write_byte}{\var{byte}}
Write the single-character string \var{byte} into memory at the
current position of the file pointer; the file position is advanced
by \code{1}. If the mmap was created with \constant{ACCESS_READ},
Note that POP3, though widely supported, is obsolescent. The
implementation quality of POP3 servers varies widely, and too many are
quite poor. If your mailserver supports IMAP, you would be better off
-using the \code{\refmodule{imaplib}.\class{IMAP4}} class, as IMAP
+using the \class{\refmodule{imaplib}.IMAP4} class, as IMAP
servers tend to be better implemented.
A single class is provided by the \module{poplib} module:
\cfunction{select()} is O(highest file descriptor), while
\cfunction{poll()} is O(number of file descriptors).
-\begin{methoddesc}{register}{fd\optional{, eventmask}}
+\begin{methoddesc}[poll]{register}{fd\optional{, eventmask}}
Register a file descriptor with the polling object. Future calls to
the \method{poll()} method will then check whether the file descriptor
has any pending I/O events. \var{fd} can be either an integer, or an
once.
\end{methoddesc}
-\begin{methoddesc}{unregister}{fd}
+\begin{methoddesc}[poll]{unregister}{fd}
Remove a file descriptor being tracked by a polling object. Just like
the \method{register()} method, \var{fd} can be an integer or an
object with a \method{fileno()} method that returns an integer.
causes a \exception{KeyError} exception to be raised.
\end{methoddesc}
-\begin{methoddesc}{poll}{\optional{timeout}}
+\begin{methoddesc}[poll]{poll}{\optional{timeout}}
Polls the set of registered file descriptors, and returns a
possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
for the descriptors that have events or errors to report.
papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
-both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1}
+both in the \citetitle{UNIX Programmer's Manual, Supplementary Documents 1}
(sections PS1:7 and PS1:8). The platform-specific reference material
for the various socket-related system calls are also a valuable source
of information on the details of socket semantics. For \UNIX, refer
SSL objects have the following methods.
-\begin{methoddesc}{write}{s}
+\begin{methoddesc}[SSL]{write}{s}
Writes the string \var{s} to the on the object's SSL connection.
The return value is the number of bytes written.
\end{methoddesc}
-\begin{methoddesc}{read}{\optional{n}}
+\begin{methoddesc}[SSL]{read}{\optional{n}}
If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
read until EOF. The return value is a string of the bytes read.
\end{methoddesc}
-\begin{methoddesc}{server}{}
+\begin{methoddesc}[SSL]{server}{}
Returns a string describing the server's certificate.
Useful for debugging purposes; do not parse the content of this string
because its format can't be parsed unambiguously.
\end{methoddesc}
-\begin{methoddesc}{issuer}{}
+\begin{methoddesc}[SSL]{issuer}{}
Returns a string describing the issuer of the server's certificate.
Useful for debugging purposes; do not parse the content of this string
because its format can't be parsed unambiguously.
A \class{Connection} instance has the following attributes and methods:
\label{sqlite3-Connection-IsolationLevel}
-\begin{memberdesc}{isolation_level}
+\begin{memberdesc}[Connection]{isolation_level}
Get or set the current isolation level. None for autocommit mode or one of
"DEFERRED", "IMMEDIATE" or "EXLUSIVE". See ``Controlling Transactions'',
section~\ref{sqlite3-Controlling-Transactions}, for a more detailed explanation.
\end{memberdesc}
-\begin{methoddesc}{cursor}{\optional{cursorClass}}
+\begin{methoddesc}[Connection]{cursor}{\optional{cursorClass}}
The cursor method accepts a single optional parameter \var{cursorClass}.
If supplied, this must be a custom cursor class that extends
\class{sqlite3.Cursor}.
\end{methoddesc}
-\begin{methoddesc}{execute}{sql, \optional{parameters}}
+\begin{methoddesc}[Connection]{execute}{sql, \optional{parameters}}
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's \method{execute} method with the
parameters given.
\end{methoddesc}
-\begin{methoddesc}{executemany}{sql, \optional{parameters}}
+\begin{methoddesc}[Connection]{executemany}{sql, \optional{parameters}}
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's \method{executemany} method with the
parameters given.
\end{methoddesc}
-\begin{methoddesc}{executescript}{sql_script}
+\begin{methoddesc}[Connection]{executescript}{sql_script}
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's \method{executescript} method with the
parameters given.
\end{methoddesc}
-\begin{methoddesc}{create_function}{name, num_params, func}
+\begin{methoddesc}[Connection]{create_function}{name, num_params, func}
Creates a user-defined function that you can later use from within SQL
statements under the function name \var{name}. \var{num_params} is the number
\verbatiminput{sqlite3/md5func.py}
\end{methoddesc}
-\begin{methoddesc}{create_aggregate}{name, num_params, aggregate_class}
+\begin{methoddesc}[Connection]{create_aggregate}{name, num_params, aggregate_class}
Creates a user-defined aggregate function.
\verbatiminput{sqlite3/mysumaggr.py}
\end{methoddesc}
-\begin{methoddesc}{create_collation}{name, callable}
+\begin{methoddesc}[Connection]{create_collation}{name, callable}
Creates a collation with the specified \var{name} and \var{callable}. The
callable will be passed two string arguments. It should return -1 if the first
\end{verbatim}
\end{methoddesc}
-\begin{methoddesc}{interrupt}{}
+\begin{methoddesc}[Connection]{interrupt}{}
You can call this method from a different thread to abort any queries that
might be executing on the connection. The query will then abort and the caller
will get an exception.
\end{methoddesc}
-\begin{methoddesc}{set_authorizer}{authorizer_callback}
+\begin{methoddesc}[Connection]{set_authorizer}{authorizer_callback}
This routine registers a callback. The callback is invoked for each attempt to
access a column of a table in the database. The callback should return
module.
\end{methoddesc}
-\begin{memberdesc}{row_factory}
+\begin{memberdesc}[Connection]{row_factory}
You can change this attribute to a callable that accepts the cursor and
the original row as a tuple and will return the real result row. This
way, you can implement more advanced ways of returning results, such
% XXX what's a db_row-based solution?
\end{memberdesc}
-\begin{memberdesc}{text_factory}
+\begin{memberdesc}[Connection]{text_factory}
Using this attribute you can control what objects are returned for the
TEXT data type. By default, this attribute is set to \class{unicode} and
the \module{sqlite3} module will return Unicode objects for TEXT. If you want to return
\verbatiminput{sqlite3/text_factory.py}
\end{memberdesc}
-\begin{memberdesc}{total_changes}
+\begin{memberdesc}[Connection]{total_changes}
Returns the total number of database rows that have been modified, inserted,
or deleted since the database connection was opened.
\end{memberdesc}
A \class{Cursor} instance has the following attributes and methods:
-\begin{methoddesc}{execute}{sql, \optional{parameters}}
+\begin{methoddesc}[Cursor]{execute}{sql, \optional{parameters}}
Executes a SQL statement. The SQL statement may be parametrized (i. e.
placeholders instead of SQL literals). The \module{sqlite3} module supports two kinds of
\end{methoddesc}
-\begin{methoddesc}{executemany}{sql, seq_of_parameters}
+\begin{methoddesc}[Cursor]{executemany}{sql, seq_of_parameters}
Executes a SQL command against all parameter sequences or mappings found in the
sequence \var{sql}. The \module{sqlite3} module also allows
using an iterator yielding parameters instead of a sequence.
\verbatiminput{sqlite3/executemany_2.py}
\end{methoddesc}
-\begin{methoddesc}{executescript}{sql_script}
+\begin{methoddesc}[Cursor]{executescript}{sql_script}
This is a nonstandard convenience method for executing multiple SQL statements
at once. It issues a COMMIT statement first, then executes the SQL script it
\verbatiminput{sqlite3/executescript.py}
\end{methoddesc}
-\begin{memberdesc}{rowcount}
+\begin{memberdesc}[Cursor]{rowcount}
Although the \class{Cursor} class of the \module{sqlite3} module implements this
attribute, the database engine's own support for the determination of "rows
affected"/"rows selected" is quirky.
Browser controllers provide two methods which parallel two of the
module-level convenience functions:
-\begin{methoddesc}{open}{url\optional{, new\optional{, autoraise=1}}}
+\begin{methoddesc}[controller]{open}{url\optional{, new\optional{, autoraise=1}}}
Display \var{url} using the browser handled by this controller.
If \var{new} is 1, a new browser window is opened if possible.
If \var{new} is 2, a new browser page ("tab") is opened if possible.
\end{methoddesc}
-\begin{methoddesc}{open_new}{url}
+\begin{methoddesc}[controller]{open_new}{url}
Open \var{url} in a new window of the browser handled by this
controller, if possible, otherwise, open \var{url} in the only
browser window. Alias \function{open_new}.
\end{methoddesc}
-\begin{methoddesc}{open_new_tab}{url}
+\begin{methoddesc}[controller]{open_new_tab}{url}
Open \var{url} in a new page ("tab") of the browser handled by this
controller, if possible, otherwise equivalent to \function{open_new}.
\versionadded{2.5}
\method{Detach()} method to return the integer handle, and
also disconnect the Windows handle from the handle object.
-\begin{methoddesc}{Close}{}
+\begin{methoddesc}[PyHKEY]{Close}{}
Closes the underlying Windows handle.
If the handle is already closed, no error is raised.
\end{methoddesc}
-\begin{methoddesc}{Detach}{}
+\begin{methoddesc}[PyHKEY]{Detach}{}
Detaches the Windows handle from the handle object.
The result is an integer (or long on 64 bit Windows) that holds
Decompression objects support the following methods, and two attributes:
-\begin{memberdesc}{unused_data}
+\begin{memberdesc}[Decompress]{unused_data}
A string which contains any bytes past the end of the compressed data.
That is, this remains \code{""} until the last byte that contains
compression data is available. If the whole string turned out to
\member{unused_data} attribute is no longer the empty string.
\end{memberdesc}
-\begin{memberdesc}{unconsumed_tail}
+\begin{memberdesc}[Decompress]{unconsumed_tail}
A string that contains any data that was not consumed by the last
\method{decompress} call because it exceeded the limit for the
uncompressed data buffer. This data has not yet been seen by the zlib
An update event for the window was received. Redraw the window.
\end{methoddesc}
-\begin{methoddesc}{do_activate}{activate, event}
+\begin{methoddesc}[Window]{do_activate}{activate, event}
The window was activated (\code{\var{activate} == 1}) or deactivated
(\code{\var{activate} == 0}). Handle things like focus highlighting,
etc.
projects / python / commitdiff