Documentation: the xmlproc APIs

Using the API

Ordinary XML parsing

An application that uses the xmlproc API has to import the xmlproc module (non-validating parsing) or the xmlval module (validating parsing). A parser object is created by instantiating an object of the XMLProcessor class (non-validating) or XMLValidator (validating). Both classes have the same interface.

If you want to receive information about the document being parsed you must implement an object conforming to the Application interface, and tell the parser about it with the set_application method.

If you want to receive error events and react to them you must implement an object conforming to the ErrorHandler interface, and tell the parser to use your error handler with the set_error_handler method.

It is also possible to control the way the parser interprets system identifiers, by implementing an object conforming to the InputSourceFactory interface and giving it to the parser with the set_inputsource_factory method.

Working with DTDs and catalog files

See the DTD API documentation and the catalog file documentation.

List of interfaces

These are the classes of interest to xmlproc application writers:

The Parser interface

This is the interface implemented by the two XML parser objects and is used to control parsing.

def __init__(self):
Instantiates a parser.
def set_application(self,app):
Tells the parser where to send data events.
def set_error_handler(self,err):
Tells the parser where to send error events.
def set_inputsource_factory(self,isf):
Tells the parser which object to use to map system identifiers to file-like objects.
def set_pubid_resolver(self,pubres):
Tells the parser which object to use to map public identifiers to system identifiers.
def set_dtd_listener(self, dtd_listener):
Tells the parser where to send DTD parse events. The dtd_listener object must implement the DTDConsumer interface.
def parse_resource(self,sysID,bufsize=16384):
Makes the parser parse the XML document with the given system identifier.
def reset(self):
Resets the parser to process another file, losing all unparsed data.
def feed(self,new_data):
Makes the parser parse a chunk of data.
def close(self):
Closes the parser, making it process all remaining data. The effects of calling feed after close and before the first reset are undefined.
def get_current_sysid(self):
Returns the system identifier of the current entity being parsed.
def get_offset(self):
Returns the current offset (in characters) from the start of the entity.
def get_line(self):
Returns the current line number.
def get_column(self):
Returns the current column position.
def get_dtd(self):
Returns the object holding information about the DTD of the document. This object conforms to the DTD interface. (Note that the DTD object returned by XMLProcessor will have much less information, since the XMLProcessor does not keep as much DTD information.)
def set_error_language(self,language):
Tells the parser which language to report errors in. 'language' must be an ISO 3166 language code (case does not matter). A KeyError will be thrown if the language is not supported.
def set_data_after_wf_error(self,stop_on_error):
Tells the parser whether to report data events to the application after a well-formedness error (0) or whether to stop reporting data (which is the default, 1).
def set_read_external_subset(self, read):
Tells the parser whether to read the external DTD subset of documents (including external parameter entities). Note that XMLValidator will ignore this method and always read the external subset.
def deref(self):
The parser creates circular data structures during parsing. When the parser object is no longer to be used and you wish to free the memory it has allocated, call this method. The parser object will be non-functional afterwards.
def get_elem_stack(self):
This method returns the list that holds the stack of open elements. Note that this list is live and must not be modified by the application.
def get_raw_construct(self):
Returns the raw XML string that triggered the current callback event.
def get_current_ent_stack(self):
Returns a snapshot of the current stack of open entities as a list of (entity name, entity sysid) tuples.

Application

This is the interface of the objects that data events from the parsed document.

def set_locator(self,locator):
Called by the parser to give the application an object to query for the current location. The object conforms to the parser interface.
def doc_start(self):
Called at the start of the document, first of all method calls, except set_locator.
def doc_end(self):
Called at the end of the document, last of all method calls.
def handle_comment(self,data):
Notifies the application of comments. (Note that it is improper for applications to let information in comments affect their operation.)
def handle_start_tag(self,name,attrs):
Called by the parser for each start tag. 'name' is the name of the element, 'attrs' a attribute name to attribute value hash.
def handle_end_tag(self,name):
Called by the parser for each end tag. 'name' is the name of the element.
def handle_data(self,data,start,end):
Called by the parser whenever it encounters textual data. (This callback does not distinguish between character entity references, entity references, CDATA marked sections or plain text.)
def handle_ignorable_data(self,data,start,end):
The validating parser calls this method instead of handle_data for whitespace that does not appear in elements which allow mixed content (ie: #PCDATA content).
def handle_pi(self,target,data):
Called to notify the application of processing instructions.
def handle_doctype(self,root,pubID,sysID):
Called to notify the application of the contents of the DOCTYPE declaration.
def set_entity_info(self,xmlver,enc,sddecl):
Called to notify the application of the contents of the XML declaration (and also for text declarations in external parsed entities). The values of the parameters will be None if the PI attributes were not present in the document.

The ErrorHandler interface

This interface is used to receive information about errors encountered during the parsing of the document.

def __init__(self,locator):
Creates a new error handler, and gives it the locator to use to locate error events.
def set_locator(self,loc):
Tells the error handler where to find location information for the error events. The object given in the 'loc' parameter conforms to the Parser interface.
def get_locator(self):
Returns the locator of this error handler.
def warning(self,msg):
Called to handle a warning message.
def error(self,msg):
Called to handle a non-fatal error.
def fatal(self,msg):
Called to handle a fatal error.

The PubIdResolver interface

This interface is used by the parser to resolve any public identifiers used in the document to their corresponding system identifiers. The default implementation always returns the given system identifier, but the interface has been included mainly to allow support for catalog files.

def resolve_pe_pubid(self,pubid,sysid):
Called to resolve the system identifier at which this external parameter entity can be found.
def resolve_doctype_pubid(self,pubid,sysid):
Called to resolve the system identifier at which this document type definition can be found. (Called from the DOCTYPE declaration.)
def resolve_entity_pubid(self,pubid,sysid):
Called to resolve the system identifier of an external entity.

The InputSourceFactory interface

This interface is used to allow users to control the way in which the parser interprets system identifiers. This is especially useful for embedding the parser in a larger document system, which may want to use system identifiers to refer to other documents inside the document system and not just to be ordinary URLs. It is also useful to allow the application to interpret system identifiers that are URIs, but not URLs, such as URNs.

The default implementation interprets system identifiers as URLs.

def create_input_source(self,sysid):
This method returns a file-like object from which the document referred to by the system identifier can be read.
Last update 2000-05-11 14:20, by Lars Marius Garshol.