Documentation: xmlproc DTD APIs

Working with DTDs

Accessing DTD information

DTD information is only available from the validating parser, which implements a get_dtd method, which can be used to get an object conforming to the DTD interface, containing all information about the DTD.

Parsing a DTD without parsing a document

This functionality is not yet supported. In a future version of xmlproc the DTD parser will be made a separate module and possibly even distributed separately. If you want to do this now you should read the source code.

List of interfaces

These are the interfaces used to discover information about the DTD of the parsed document:

• The DTD interface.
• The ElementType interface.
• The Attribute interface.
• The Entity interface.
• The DTDConsumer interface.

The DTD interface

This is the interface of the object that holds information about the DTD of the current document. This object can be queried to discover information about the DTD.

def resolve_pe(self,name):

Returns the entity object (either InternalEntity or ExternalEntity) of the parameter entity with the given name. If no parameter entity with this name has been declared a KeyError is thrown.

def resolve_ge(self,name):

Returns the entity object (either InternalEntity or ExternalEntity) of the general entity with the given name. If no general entity with this name has been declared a KeyError is thrown.

def get_elem(self,name):

Returns the element object of the element with the given name. Throws a KeyError if no such element has been declared.

def get_root_elem(self):

Returns the name of the element declared as the root element (as a string).

def get_notation(self,name):

Returns the notation object of the given notation. If no such notation has been declared a KeyError is thrown.

The ElementType interface

This class encapsulates information about an element type.

def get_name(self):

Returns the name of the element type.

def get_attr_list(self):

Returns a list of the names of the declared attributes for this element (as strings).

def get_attr(self,name):

Returns the attribute object of the given attribute or throws a KeyError if none has been declared.

def get_start_state(self):

Returns the start state of the content model of the element. (No guarantees is made as to the type of this value.)

def final_state(self,state):

Returns true if the given state (as returned by get_start_state or next_state) is a final state, ie: one in which the element is allowed to end.

def next_state(self,state,elem_name):

Returns the next state of the element when the an element with the given name is encountered in the given state. Character data is represented as the element name '#PCDATA'.

The Attribute interface

This class encapsulates information about an attribute.

def validate(self,value,err):

Takes an attribute value ('value') and an ErrorHandler ('err') and validates the attribute value for correctness, reporting errors to 'err'.

def get_name(self):

Returns the name of the attribute.

def get_type(self):

Returns the declared type of the attribute. (ID, CDATA etc.)

def get_decl(self):

Returns the default declaration of the attribute. (#IMPLIED, #REQUIRED, #FIXED or #DEFAULT.)

def get_default(self):

Return the default value of the attribute, or None if none has been declared.

The Entity interface

This class encapsulates information about entities. It is implemented by two classes: InternalEntity and ExternalEntity. InternalEntity only implements a subset of the interface.

def is_internal(self):

True if the entity is internal, false otherwise.

def is_parsed(self):

True if the entity is parsed, false otherwise. (Not implemented by InternalEntity.)

def get_pubid(self):

Returns the public identifier of the entity. (Not implemented by InternalEntity.)

def get_sysid(self):

Returns the system identifier of the entity. (Not implemented by InternalEntity.)

The DTDConsumer interface

This interface is used to receive parse events from the DTD parser.

def set_error_handler(self,err):

Sets the error handler of the DTDConsumer. The error handler does not have to be used, but the DTDConsumer must accept this method call.

def dtd_start(self):

Called before any DTD events arrive. (Note: This will be called once for the internal DTD subset (if any) and once for the external DTD subset (if parsed).)

def dtd_end(self):

Called when the DTD is completely parsed. (Note: This will be called once for the internal DTD subset (if any) and once for the external DTD subset (if parsed).)

def new_comment(self,contents):

Called when a comment is encountered in the DTD.

def new_pi(self,target,rem):

Called when a processing instruction is encountered in the DTD.

def new_general_entity(self,name,val):

Called when an internal general entity declaration is encountered. 'val' contains the entity replacement text.

def new_external_entity(self,ent_name,pub_id,sys_id,ndata):

Called when an external general entity declaration is encountered. 'ndata' is the name of the associated notation, or None if none was associated.

def new_parameter_entity(self,name,val):

Called when an internal parameter entity declaration is encountered. 'val' contains the entity replacement text.

def new_external_pe(self,name,pubid,sysid):

Called when an external parameter entity declaration is encountered.

def new_notation(self,name,pubid,sysid):

Called when a notation declaration is encountered.

def new_element_type(self,elem_name,elem_cont):

Called when an element type declaration is encountered. 'elem_cont' is a ContentModel object. (Email me if you want more information about how to deal with content models.)

def new_attribute(self,elem,attr,a_type,a_decl,a_def):

Called when an attribute declaration is encountered. 'elem' is the name of the element, 'attr' the name of the attribute, 'a_type' the name of the attribute type (ID, CDATA...), 'a_decl' the name of the declared default type (#REQUIRED, #IMPLIED...) and 'a_def' the declared default value (or None if none were declared).

def handle_comment(self,contents):

Called when a comment is encountered inside the DTD.

def handle_pi(self,target,data):

Called when a processing instruction is encountered inside the DTD.