traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Many small markup revisions to be more consistent with markup elsewhere, 

and to provide more consistent indexing.

Added an index entry.

Added documentation for the error and XMLParserType objects.
This commit is contained in:
Fred Drake 2000-10-29 05:10:30 +00:00
parent 4ba298c325
commit efffe8e317
1 changed files with 61 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
Doc/lib/libpyexpat.tex
View File

@ -1,5 +1,5 @@
\section{\module{xml.parsers.expat} --- \section{\module{xml.parsers.expat} ---
Fast XML parsing using the Expat library} Fast XML parsing using Expat}
\declaremodule{standard}{xml.parsers.expat} \declaremodule{standard}{xml.parsers.expat}
\modulesynopsis{An interface to the Expat non-validating XML parser.} \modulesynopsis{An interface to the Expat non-validating XML parser.}
@ -8,8 +8,8 @@
\versionadded{2.0} \versionadded{2.0}
The \module{xml.parsers.expat} module is a Python interface to the Expat The \module{xml.parsers.expat} module is a Python interface to the
non-validating XML parser. Expat\index{Expat} non-validating XML parser.
The module provides a single extension type, \class{xmlparser}, that The module provides a single extension type, \class{xmlparser}, that
represents the current state of an XML parser. After an represents the current state of an XML parser. After an
\class{xmlparser} object has been created, various attributes of the object \class{xmlparser} object has been created, various attributes of the object
@ -20,35 +20,48 @@ and markup in the XML document.
This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to
provide access to the Expat parser. Direct use of the provide access to the Expat parser. Direct use of the
\module{pyexpat} module is deprecated. \module{pyexpat} module is deprecated.
This module provides one exception and one type object:
\begin{excdesc}{error}
The exception raised when Expat reports an error.
\end{excdesc}
\begin{datadesc}{XMLParserType}
The type of the return values from the \function{ParserCreate()}
function.
\end{datadesc}
The \module{xml.parsers.expat} module contains two functions: The \module{xml.parsers.expat} module contains two functions:
\begin{funcdesc}{ErrorString}{errno} \begin{funcdesc}{ErrorString}{errno}
Returns an explanatory string for a given error number \var{errno}. Returns an explanatory string for a given error number \var{errno}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{ParserCreate}{\optional{encoding, namespace_separator}} \begin{funcdesc}{ParserCreate}{\optional{encoding\optional{,
namespace_separator}}}
Creates and returns a new \class{xmlparser} object. Creates and returns a new \class{xmlparser} object.
\var{encoding}, if specified, must be a string naming the encoding \var{encoding}, if specified, must be a string naming the encoding
used by the XML data. Expat doesn't support as many encodings as used by the XML data. Expat doesn't support as many encodings as
Python does, and its repertoire of encodings can't be extended; it Python does, and its repertoire of encodings can't be extended; it
supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.
% XXX pyexpat.c should only allow a 1-char string for this parameter
Expat can optionally do XML namespace processing for you, enabled by Expat can optionally do XML namespace processing for you, enabled by
providing a value for \var{namespace_separator}. When namespace providing a value for \var{namespace_separator}. The value must be a
processing is enabled, element type names and attribute names that one-character string; a \exception{ValueError} will be raised if the
belong to a namespace will be expanded. The element name string has an illegal length (\code{None} is considered the same as
passed to the element handlers omission). When namespace processing is enabled, element type names
and attribute names that belong to a namespace will be expanded. The
element name passed to the element handlers
\function{StartElementHandler()} and \function{EndElementHandler()} \function{StartElementHandler()} and \function{EndElementHandler()}
will be the concatenation of the namespace URI, the namespace will be the concatenation of the namespace URI, the namespace
separator character, and the local part of the name. If the namespace separator character, and the local part of the name. If the namespace
separator is a zero byte (\code{chr(0)}) separator is a zero byte (\code{chr(0)}) then the namespace URI and
then the namespace URI and the local part will be the local part will be concatenated without any separator.
concatenated without any separator.
For example, if \var{namespace_separator} is set to For example, if \var{namespace_separator} is set to
\samp{ }, and the following document is parsed: \character{ }, and the following document is parsed:
\begin{verbatim} \begin{verbatim}
<?xml version="1.0"?> <?xml version="1.0"?>
@ -72,20 +85,20 @@ elem2
\class{xmlparser} objects have the following methods: \class{xmlparser} objects have the following methods:
\begin{methoddesc}{Parse}{data \optional{, isfinal}} \begin{methoddesc}[xmlparser]{Parse}{data \optional{, isfinal}}
Parses the contents of the string \var{data}, calling the appropriate Parses the contents of the string \var{data}, calling the appropriate
handler functions to process the parsed data. \var{isfinal} must be handler functions to process the parsed data. \var{isfinal} must be
true on the final call to this method. \var{data} can be the empty true on the final call to this method. \var{data} can be the empty
string at any time. string at any time.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{ParseFile}{file} \begin{methoddesc}[xmlparser]{ParseFile}{file}
Parse XML data reading from the object \var{file}. \var{file} only Parse XML data reading from the object \var{file}. \var{file} only
needs to provide the \method{read(\var{nbytes})} method, returning the needs to provide the \method{read(\var{nbytes})} method, returning the
empty string when there's no more data. empty string when there's no more data.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{SetBase}{base} \begin{methoddesc}[xmlparser]{SetBase}{base}
Sets the base to be used for resolving relative URIs in system identifiers in Sets the base to be used for resolving relative URIs in system identifiers in
declarations. Resolving relative identifiers is left to the application: declarations. Resolving relative identifiers is left to the application:
this value will be passed through as the base argument to the this value will be passed through as the base argument to the
@ -93,42 +106,43 @@ this value will be passed through as the base argument to the
and \function{UnparsedEntityDeclHandler} functions. and \function{UnparsedEntityDeclHandler} functions.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{GetBase}{} \begin{methoddesc}[xmlparser]{GetBase}{}
Returns a string containing the base set by a previous call to Returns a string containing the base set by a previous call to
\method{SetBase()}, or \code{None} if \method{SetBase()}, or \code{None} if
\method{SetBase()} hasn't been called. \method{SetBase()} hasn't been called.
\end{methoddesc} \end{methoddesc}
\class{xmlparser} objects have the following attributes: \class{xmlparser} objects have the following attributes:
\begin{datadesc}{returns_unicode} \begin{memberdesc}[xmlparser]{returns_unicode}
If this attribute is set to 1, the handler functions will be passed If this attribute is set to 1, the handler functions will be passed
Unicode strings. If \member{returns_unicode} is 0, 8-bit strings Unicode strings. If \member{returns_unicode} is 0, 8-bit strings
containing UTF-8 encoded data will be passed to the handlers. containing UTF-8 encoded data will be passed to the handlers.
\end{datadesc} \end{memberdesc}
The following attributes contain values relating to the most recent The following attributes contain values relating to the most recent
error encountered by an \class{xmlparser} object, and will only have error encountered by an \class{xmlparser} object, and will only have
correct values once a call to \method{Parse()} or \method{ParseFile()} correct values once a call to \method{Parse()} or \method{ParseFile()}
has raised a \exception{xml.parsers.expat.error} exception. has raised a \exception{xml.parsers.expat.error} exception.
\begin{datadesc}{ErrorByteIndex} \begin{memberdesc}[xmlparser]{ErrorByteIndex}
Byte index at which an error occurred. Byte index at which an error occurred.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{ErrorCode} \begin{memberdesc}[xmlparser]{ErrorCode}
Numeric code specifying the problem. This value can be passed to the Numeric code specifying the problem. This value can be passed to the
\function{ErrorString()} function, or compared to one of the constants \function{ErrorString()} function, or compared to one of the constants
defined in the \module{errors} object. defined in the \module{errors} object.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{ErrorColumnNumber} \begin{memberdesc}[xmlparser]{ErrorColumnNumber}
Column number at which an error occurred. Column number at which an error occurred.
\end{datadesc} \end{memberdesc}
\begin{datadesc}{ErrorLineNumber} \begin{memberdesc}[xmlparser]{ErrorLineNumber}
Line number at which an error occurred. Line number at which an error occurred.
\end{datadesc} \end{memberdesc}
Here is the list of handlers that can be set. To set a handler on an Here is the list of handlers that can be set. To set a handler on an
\class{xmlparser} object \var{o}, use \class{xmlparser} object \var{o}, use
@ -137,76 +151,76 @@ be taken from the following list, and \var{func} must be a callable
object accepting the correct number of arguments. The arguments are object accepting the correct number of arguments. The arguments are
all strings, unless otherwise stated. all strings, unless otherwise stated.
\begin{methoddesc}{StartElementHandler}{name, attributes} \begin{methoddesc}[xmlparser]{StartElementHandler}{name, attributes}
Called for the start of every element. \var{name} is a string Called for the start of every element. \var{name} is a string
containing the element name, and \var{attributes} is a dictionary containing the element name, and \var{attributes} is a dictionary
mapping attribute names to their values. mapping attribute names to their values.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{EndElementHandler}{name} \begin{methoddesc}[xmlparser]{EndElementHandler}{name}
Called for the end of every element. Called for the end of every element.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{ProcessingInstructionHandler}{target, data} \begin{methoddesc}[xmlparser]{ProcessingInstructionHandler}{target, data}
Called for every processing instruction. Called for every processing instruction.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{CharacterDataHandler}{\var{data}} \begin{methoddesc}[xmlparser]{CharacterDataHandler}{data}
Called for character data. Called for character data.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{UnparsedEntityDeclHandler}{entityName, base, \begin{methoddesc}[xmlparser]{UnparsedEntityDeclHandler}{entityName, base,
systemId, publicId, systemId, publicId,
notationName} notationName}
Called for unparsed (NDATA) entity declarations. Called for unparsed (NDATA) entity declarations.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{NotationDeclHandler}{notationName, base, systemId, \begin{methoddesc}[xmlparser]{NotationDeclHandler}{notationName, base,
publicId} systemId, publicId}
Called for notation declarations. Called for notation declarations.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{StartNamespaceDeclHandler}{prefix, uri} \begin{methoddesc}[xmlparser]{StartNamespaceDeclHandler}{prefix, uri}
Called when an element contains a namespace declaration. Called when an element contains a namespace declaration.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{EndNamespaceDeclHandler}{prefix} \begin{methoddesc}[xmlparser]{EndNamespaceDeclHandler}{prefix}
Called when the closing tag is reached for an element Called when the closing tag is reached for an element
that contained a namespace declaration. that contained a namespace declaration.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{CommentHandler}{data} \begin{methoddesc}[xmlparser]{CommentHandler}{data}
Called for comments. Called for comments.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{StartCdataSectionHandler}{} \begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{}
Called at the start of a CDATA section. Called at the start of a CDATA section.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{EndCdataSectionHandler}{} \begin{methoddesc}[xmlparser]{EndCdataSectionHandler}{}
Called at the end of a CDATA section. Called at the end of a CDATA section.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{DefaultHandler}{data} \begin{methoddesc}[xmlparser]{DefaultHandler}{data}
Called for any characters in the XML document for Called for any characters in the XML document for
which no applicable handler has been specified. This means which no applicable handler has been specified. This means
characters that are part of a construct which could be reported, but characters that are part of a construct which could be reported, but
for which no handler has been supplied. for which no handler has been supplied.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{DefaultHandlerExpand}{data} \begin{methoddesc}[xmlparser]{DefaultHandlerExpand}{data}
This is the same as the \function{DefaultHandler}, This is the same as the \function{DefaultHandler},
but doesn't inhibit expansion of internal entities. but doesn't inhibit expansion of internal entities.
The entity reference will not be passed to the default handler. The entity reference will not be passed to the default handler.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{NotStandaloneHandler}{} \begin{methoddesc}[xmlparser]{NotStandaloneHandler}{}
Called if the XML document hasn't been declared as being a standalone Called if the XML document hasn't been declared as being a standalone
document. document.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{ExternalEntityRefHandler}{context, base, systemId, \begin{methoddesc}[xmlparser]{ExternalEntityRefHandler}{context, base,
publicId} systemId, publicId}
Called for references to external entities. Called for references to external entities.
\end{methoddesc} \end{methoddesc}