home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 April / PCWorld_2001-04_cd.bin / Software / TemaCD / webclean / !!!python!!! / PyXML-0.6.3.win32-py2.0.exe / xmldoc / doc / xml-ref.txt < prev   
Text File  |  2000-10-07  |  23KB  |  555 lines
  1.  
  2.    Python/XML Reference Guide
  3.      _________________________________________________________________
  4.      _________________________________________________________________
  5.    
  6.                          Python/XML Reference Guide
  7.                                       
  8.                    The Python/XML Special Interest Group
  9.                                       
  10.                              xml-sig@python.org
  11.                        (edited by akuchling@acm.org)
  12.                                       
  13.   Abstract:
  14.   
  15.    XML is the eXtensible Markup Language, a subset of SGML, intended to
  16.    allow the creation and processing of application-specific markup
  17.    languages. Python makes an excellent language for processing XML data.
  18.    This document is the reference manual for the Python/XML package,
  19.    containing several XML modules.
  20.    
  21.    This is a draft document; 'XXX' in the text indicates that something
  22.    has to be filled in later, or rewritten, or verified, or something.
  23.  
  24.    THIS DOCUMENT IS SIGNIFICANTLY OUTDATED, DO NOT USE IT AS A BASIS OF
  25.    APPLICATION DEVELOPMENT.
  26.    
  27. Contents
  28.  
  29.      * Contents
  30.      * 1. xml.arch.xmlarch
  31.           + 1.1 ArchDocHandler methods
  32.           + 1.2 Architecture methods
  33.           + 1.3 ArchParseState methods
  34.           + 1.4 ArchException methods
  35.           + 1.5 AttributeParser methods
  36.           + 1.6 Normalizer methods
  37.      * 2. xml.parsers.xmllib
  38.      * 3. xml.sax.saxexts
  39.           + 3.1 ExtendedParser methods
  40.           + 3.2 ParserFactory methods
  41.      * 4. xml.sax.saxlib
  42.           + 4.1 AttributeList methods
  43.           + 4.2 DocumentHandler methods
  44.           + 4.3 DTDHandler methods
  45.           + 4.4 EntityResolver methods
  46.           + 4.5 ErrorHandler methods
  47.           + 4.6 Locator methods
  48.           + 4.7 Parser methods
  49.           + 4.8 SAXException methods
  50.           + 4.9 SAXParseException methods
  51.      * 5. xml.sax.saxutils
  52.           + 5.1 Location methods
  53.      * 6. xml.utils.iso8601 24 
  54.        
  55.                               1. xml.arch.xmlarch
  56.                                        
  57.    The xmlarch module contains an XML architectural forms processor
  58.    written in Python. It allows you to process XML architectural forms
  59.    using any parser that uses the SAX interfaces. The module allows you
  60.    to process several architectures in one parsing pass. Architectural
  61.    document events for an architecture can even be broadcasted to
  62.    multiple DocumentHandlers. (e.g. you can have 2 handlers for the RDF
  63.    architecture, 3 for the XLink architecture and perhaps one for the
  64.    HyTime architecture.) The architecture processor uses the SAX
  65.    DocumentHandler interface which means that you can register the
  66.    architecture handler (ArchDocHandler) with any SAX 1.0 compliant
  67.    parser. It currently does not process any meta document type
  68.    definition documents (meta-DTDs). When a DTD parser module is
  69.    available the code will be modified to use that in order to process
  70.    meta-DTD information. Please note that validating and well-formed
  71.    parsers may report different SAX events when parsing documents.
  72.    
  73.    The xmlarch module contains six classes: ArchDocHandler, Architecture,
  74.    ArchParseState, ArchException, AttributeParser and Normalizer.
  75.    
  76.      * ArchDocHandler is a subclass of the saxlib.DocumentHandler
  77.        interface. This is the class used for processing an architectural
  78.        document.
  79.      * Architecture contains information about an architecture.
  80.      * ArchParseState holds information about an architecture's parse
  81.        state when parsing a document.
  82.      * AttributeParser parses architecture use declaration PIs (attribute
  83.        strings).
  84.      * ArchException holds information about an architectural exception
  85.        thrown by an ArchDocHandler instance.
  86.      * Normalizer is a document handler that outputs "normalized" XML.
  87.        
  88. 1.1 ArchDocHandler methods
  89.  
  90.    Still undocumented.
  91.    
  92. 1.2 Architecture methods
  93.  
  94.    Still undocumented.
  95.    
  96. 1.3 ArchParseState methods
  97.  
  98.    Still undocumented.
  99.    
  100. 1.4 ArchException methods
  101.  
  102.    Still undocumented.
  103.    
  104. 1.5 AttributeParser methods
  105.  
  106.    Still undocumented.
  107.    
  108. 1.6 Normalizer methods
  109.  
  110.    Still undocumented.
  111.    
  112.                              2. xml.parsers.xmllib
  113.                                        
  114.    This is a version of the xmllib module from Python 1.5, modified to
  115.    use the _sgmlop C extension when it's available. This produces a
  116.    significant speedup, amounting to about a factor of 5. The interface
  117.    is unchanged from the original xmllib module; consult the Python
  118.    Library Reference documentation for that module.
  119.    
  120.                               3. xml.sax.saxexts
  121.                                        
  122.    make_parser ([parser])
  123.           A utility function that returns a Parser object for a
  124.           non-validating XML parser. If parser is specified, it must be a
  125.           parser name; otherwise, a list of available parsers is checked
  126.           and the fastest one chosen.
  127.           
  128.    HTMLParserFactory
  129.           An instance of the ParserFactory class that's already been
  130.           prepared with a list of HTML parsers. Simply call its
  131.           make_parser() method to get a Parser object.
  132.           
  133.    ParserFactory ()
  134.           A general class to be used by applications for creating parsers
  135.           on foreign systems where the list of installed parsers is
  136.           unknown.
  137.           
  138.    SGMLParserFactory
  139.           An instance of the ParserFactory class that's already been
  140.           prepared with a list of SGML parsers. Simply call its
  141.           make_parser() method to get a parser object.
  142.           
  143.    XMLParserFactory
  144.           An instance of the ParserFactory class that's already been
  145.           prepared with a list of nonvalidating XML parsers. Simply call
  146.           its make_parser() method to get a parser object.
  147.           
  148.    XMLValParserFactory
  149.           An instance of the ParserFactory class that's already been
  150.           prepared with a list of validating XML parsers. Simply call its
  151.           make_parser() method to get a parser object.
  152.           
  153.    ExtendedParser ()
  154.           This class is an experimental extended parser interface, that
  155.           offers additional functionality that may be useful. However,
  156.           it's not specified by the SAX specification.
  157.           
  158. 3.1 ExtendedParser methods
  159.  
  160.    close ()
  161.           Called after the last call to feed, when there are no more
  162.           data.
  163.           
  164.    feed (data)
  165.           Feeds data to the parser.
  166.           
  167.    get_parser_name ()
  168.           Returns a single-word parser name.
  169.           
  170.    get_parser_version ()
  171.           Returns the version of the imported parser, which may not be
  172.           the one the driver was implemented for.
  173.           
  174.    is_dtd_reading ()
  175.           True if the parser is non-validating, but conforms to the XML
  176.           specification by reading the DTD.
  177.           
  178.    is_validating ()
  179.           Returns true if the parser is validating, false otherwise.
  180.           
  181.    reset ()
  182.           Makes the parser start parsing afresh.
  183.           
  184. 3.2 ParserFactory methods
  185.  
  186.    get_parser_list ()
  187.           Returns the list of possible drivers. Currently this starts out
  188.           as ["xml.sax.drivers.drv_xmltok",
  189.           "xml.sax.drivers.drv_xmlproc",
  190.           "xml.sax.drivers.drv_xmltoolkit",
  191.           "xml.sax.drivers.drv_xmllib"].
  192.           
  193.    make_parser ([driver_name])
  194.           Returns a SAX driver for the first available parser of the
  195.           parsers in the list. Note that the list contains drivers, so it
  196.           first tries the driver and if that exists imports it to see if
  197.           the parser also exists. If no parsers are available a
  198.           SAXException is thrown.
  199.           
  200.           Optionally, driver_name can be a string containing the name of
  201.           the driver to be used; the stored parser list will then not be
  202.           used at all.
  203.           
  204.    set_parser_list (list)
  205.           Sets the driver list to list.
  206.           
  207.                                4. xml.sax.saxlib
  208.                                        
  209.    AttributeList ()
  210.           Interface for an attribute list. This interface provides
  211.           information about a list of attributes for an element (only
  212.           specified or defaulted attributes will be reported). Note that
  213.           the information returned by this object will be valid only
  214.           during the scope of the DocumentHandler.startElement callback,
  215.           and the attributes will not necessarily be provided in the
  216.           order declared or specified.
  217.           
  218.    DocumentHandler ()
  219.           Handle general document events. This is the main client
  220.           interface for SAX: it contains callbacks for the most important
  221.           document events, such as the start and end of elements. You
  222.           need to create an object that implements this interface, and
  223.           then register it with the Parser. If you do not want to
  224.           implement the entire interface, you can derive a class from
  225.           HandlerBase, which implements the default functionality. You
  226.           can find the location of any document event using the Locator
  227.           interface supplied by setDocumentLocator().
  228.           
  229.    DTDHandler ()
  230.           Handle DTD events. This interface specifies only those DTD
  231.           events required for basic parsing (unparsed entities and
  232.           attributes). If you do not want to implement the entire
  233.           interface, you can extend HandlerBase, which implements the
  234.           default behaviour.
  235.           
  236.    EntityResolver ()
  237.           This is the basic interface for resolving entities. If you
  238.           create an object implementing this interface, then register the
  239.           object with your Parser instance, the parser will call the
  240.           method in your object to resolve all external entities. Note
  241.           that HandlerBase implements this interface with the default
  242.           behaviour.
  243.           
  244.    ErrorHandler ()
  245.           This is the basic interface for SAX error handlers. If you
  246.           create an object that implements this interface, then register
  247.           the object with your Parser, the parser will call the methods
  248.           in your object to report all warnings and errors. There are
  249.           three levels of errors available: warnings, (possibly)
  250.           recoverable errors, and unrecoverable errors. All methods take
  251.           a SAXParseException as the only parameter.
  252.           
  253.    HandlerBase ()
  254.           Default base class for handlers. This class implements the
  255.           default behaviour for four SAX interfaces, inheriting from them
  256.           all: EntityResolver, DTDHandler, DocumentHandler, and
  257.           ErrorHandler. Rather than implementing those full interfaces,
  258.           you may simply extend this class and override the methods that
  259.           you need. Note that the use of this class is optional, since
  260.           you are free to implement the interfaces directly if you wish.
  261.           
  262.    Locator ()
  263.           Interface for associating a SAX event with a document location.
  264.           A locator object will return valid results only during calls to
  265.           methods of the SAXDocumentHandler class; at any other time, the
  266.           results are unpredictable.
  267.           
  268.    Parser ()
  269.           Basic interface for SAX parsers. All SAX parsers must implement
  270.           this basic interface: it allows users to register handlers for
  271.           different types of events and to initiate a parse from a URI, a
  272.           character stream, or a byte stream. SAX parsers should also
  273.           implement a zero-argument constructor.
  274.           
  275.    SAXException (msg, exception, locator)
  276.           Encapsulate an XML error or warning. This class can contain
  277.           basic error or warning information from either the XML parser
  278.           or the application: you can subclass it to provide additional
  279.           functionality, or to add localization. Note that although you
  280.           will receive a SAXException as the argument to the handlers in
  281.           the ErrorHandler interface, you are not actually required to
  282.           throw the exception; instead, you can simply read the
  283.           information in it.
  284.           
  285.    SAXParseException (msg, exception, locator)
  286.           Encapsulate an XML parse error or warning. This exception will
  287.           include information for locating the error in the original XML
  288.           document. Note that although the application will receive a
  289.           SAXParseException as the argument to the handlers in the
  290.           ErrorHandler interface, the application is not actually
  291.           required to throw the exception; instead, it can simply read
  292.           the information in it and take a different action.
  293.           
  294.           Since this exception is a subclass of SAXException, it inherits
  295.           the ability to wrap another exception.
  296.           
  297. 4.1 AttributeList methods
  298.  
  299.    The AttributeList class supports some of the behaviour of Python
  300.    dictionaries; the len(), has_key(), keys() methods are available, and
  301.    attr['href'] will retrieve the value of the href attribute. There are
  302.    also additional methods specific to AttributeList:
  303.    
  304.    getLength ()
  305.           Return the number of attributes in the list.
  306.           
  307.    getName (i)
  308.           Return the name of attribute i in the list.
  309.           
  310.    getType (i)
  311.           Return the type of an attribute in the list. i can be either
  312.           the integer index or the attribute name.
  313.           
  314.    getValue (i)
  315.           Return the value of an attribute in the list. i can be either
  316.           the integer index or the attribute name.
  317.           
  318. 4.2 DocumentHandler methods
  319.  
  320.    characters (ch, start, length)
  321.           Handle a character data event.
  322.           
  323.    endDocument ()
  324.           Handle an event for the end of a document.
  325.           
  326.    endElement (name)
  327.           Handle an event for the end of an element.
  328.           
  329.    ignorableWhitespace (ch, start, length)
  330.           Handle an event for ignorable whitespace in element content.
  331.           
  332.    processingInstruction (target, data)
  333.           Handle a processing instruction event.
  334.           
  335.    setDocumentLocator (locator)
  336.           Receive an object for locating the origin of SAX document
  337.           events. You'll probably want to store the value of locator as
  338.           an attribute of the handler instance.
  339.           
  340.    startDocument ()
  341.           Handle an event for the beginning of a document.
  342.           
  343.    startElement (name, attrs)
  344.           Handle an event for the beginning of an element.
  345.           
  346. 4.3 DTDHandler methods
  347.  
  348.    notationDecl (name, publicId, systemId)
  349.           Handle a notation declaration event.
  350.           
  351.    unparsedEntityDecl (publicId, systemId, notationName)
  352.           Handle an unparsed entity declaration event.
  353.           
  354. 4.4 EntityResolver methods
  355.  
  356.    resolveEntity (name, publicId, systemId)
  357.           Resolve the system identifier of an entity.
  358.           
  359. 4.5 ErrorHandler methods
  360.  
  361.    error (exception)
  362.           Handle a recoverable error.
  363.           
  364.    fatalError (exception)
  365.           Handle a non-recoverable error.
  366.           
  367.    warning (exception)
  368.           Handle a warning.
  369.           
  370. 4.6 Locator methods
  371.  
  372.    getColumnNumber ()
  373.           Return the column number where the current event ends.
  374.           
  375.    getLineNumber ()
  376.           Return the line number where the current event ends.
  377.           
  378.    getPublicId ()
  379.           Return the public identifier for the current event.
  380.           
  381.    getSystemId ()
  382.           Return the system identifier for the current event.
  383.           
  384. 4.7 Parser methods
  385.  
  386.    parse (systemId)
  387.           Parse an XML document from a system identifier.
  388.           
  389.    parseFile (fileobj)
  390.           Parse an XML document from a file-like object.
  391.           
  392.    setDocumentHandler (handler)
  393.           Register an object to receive basic document-related events.
  394.           
  395.    setDTDHandler (handler)
  396.           Register an object to receive basic DTD-related events.
  397.           
  398.    setEntityResolver (resolver)
  399.           Register an object to resolve external entities.
  400.           
  401.    setErrorHandler (handler)
  402.           Register an object to receive error-message events.
  403.           
  404.    setLocale (locale)
  405.           Allow an application to set the locale for errors and warnings.
  406.           SAX parsers are not required to provide localisation for errors
  407.           and warnings; if they cannot support the requested locale,
  408.           however, they must throw a SAX exception. Applications may
  409.           request a locale change in the middle of a parse.
  410.           
  411. 4.8 SAXException methods
  412.  
  413.    getException ()
  414.           Return the embedded exception, if any.
  415.           
  416.    getMessage ()
  417.           Return a message for this exception.
  418.           
  419. 4.9 SAXParseException methods
  420.  
  421.    The SAXParseException class has a locator attribute, containing an
  422.    instance of the Locator class, which represents the location in the
  423.    document where the parse error occurred. The following methods are
  424.    delegated to this instance.
  425.    
  426.    getColumnNumber ()
  427.           Return the column number of the end of the text where the
  428.           exception occurred.
  429.           
  430.    getLineNumber ()
  431.           Return the line number of the end of the text where the
  432.           exception occurred.
  433.           
  434.    getPublicId ()
  435.           Return the public identifier of the entity where the exception
  436.           occurred.
  437.           
  438.    getSystemId ()
  439.           Return the system identifier of the entity where the exception
  440.           occurred.
  441.           
  442.                               5. xml.sax.saxutils
  443.                                        
  444.    Canonizer (writer)
  445.           A SAX document handler that produces canonicalized XML output.
  446.           writer must support a write() method which accepts a single
  447.           string.
  448.           
  449.    ErrorPrinter ()
  450.           A simple class that just prints error messages to standard
  451.           error (sys.stderr).
  452.           
  453.    ESISDocHandler (writer)
  454.           A SAX document handler that produces naive ESIS output. writer
  455.           must support a write() method which accepts a single string.
  456.           
  457.    EventBroadcaster (list)
  458.           Takes a list of objects and forwards any method calls received
  459.           to all objects in the list. The attribute list holds the list
  460.           and can freely be modified by clients.
  461.           
  462.    Location (locator)
  463.           Represents a location in an XML entity. Initialized by being
  464.           passed a locator, from which it reads off the current location,
  465.           which is then stored internally.
  466.           
  467. 5.1 Location methods
  468.  
  469.    getColumnNumber ()
  470.           Return the column number of the location.
  471.           
  472.    getLineNumber ()
  473.           Return the line number of the location.
  474.           
  475.    getPublicId ()
  476.           Return the public identifier for the location.
  477.           
  478.    getSystemId ()
  479.           Return the system identifier for the location.
  480.           
  481.                              6. xml.utils.iso8601
  482.                                        
  483.    The xml.utils.iso8601 module provides conversion routines between the
  484.    ISO 8601 representations of date/time values and the floating point
  485.    values used elsewhere in Python. The floating point represtentation is
  486.    particularly useful in conjunction with the standard time module.
  487.    
  488.    Currently, this module supports a small superset of the ISO 8601
  489.    profile described by the World Wide Web Consortium (W3C). This is a
  490.    subset of ISO 8601, but covers the cases expected to be used most
  491.    often in the context of XML processing and Web applications. Future
  492.    versions of this module may support a larger subset of
  493.    ISO 8601-defined formats.
  494.    
  495.    parse (s)
  496.           Parse an ISO 8601 date representation (with an optional
  497.           time-of-day component) and return the date in seconds since the
  498.           epoch.
  499.           
  500.    parse_timezone (timezone)
  501.           Parse an ISO 8601 time zone designator and return the offset
  502.           relative to Universal Coordinated Time (UTC) in seconds. If
  503.           timezone is not valid, ValueError is raised.
  504.           
  505.    tostring (t[, timezone])
  506.           Return formatted date/time value according to the profile
  507.           described by the W3C. If timezone is provided, it must be the
  508.           offset from UTC in seconds specified as a number, or time zone
  509.           designator which can be parsed by parse_timezone(). If timezone
  510.           is specified as a string and cannot be parsed by
  511.           parse_timezone(), ValueError will be raised.
  512.           
  513.    ctime (t)
  514.           Return formatter date/time value using the local timezone. This
  515.           is equivalent to "tostring(t, time.timezone)".
  516.           
  517.    See Also:
  518.    
  519.    International Organization for Standardization. Data elements and
  520.    interchange formats -- Information interchange -- Representation of
  521.    dates and times. International Organization for Standardization, 1988.
  522.    
  523.    Gary Houston. ISO 8601 date/time representations. January 1993.
  524.    Available online as compressed PostScript:
  525.    ftp://ftp.informatik.uni-erlangen.de/pub/doc/ISO/ISO8601.ps.Z.
  526.    
  527.    Markus Kuhn. A Summary of the International Standard Dateand Time
  528.    Notation. Available online at
  529.    http://www.cl.cam.ac.uk/~mgk25/iso-time.html.
  530.    
  531.    Misha Wolf and Charles Wicksteed. Date and Time Formats. World Wide
  532.    Web Consortium Technical Note, September 1998. Available online at
  533.    http://www.w3.org/TR/NOTE-datetime.
  534.    
  535.                             About this document ...
  536.                                        
  537.    Python/XML Reference Guide
  538.    
  539.    This document was generated using the LaTeX2HTML translator.
  540.    
  541.    LaTeX2HTML is Copyright ⌐ 1993, 1994, 1995, 1996, 1997, Nikos Drakos,
  542.    Computer Based Learning Unit, University of Leeds, and Copyright ⌐
  543.    1997, 1998, Ross Moore, Mathematics Department, Macquarie University,
  544.    Sydney.
  545.    
  546.    The application of LaTeX2HTML to the Python documentation has been
  547.    heavily tailored by Fred L. Drake, Jr. (fdrake@acm.org). Original
  548.    navigation icons were contributed by Christopher Petrilli
  549.    (petrilli@dworkin.amber.org).
  550.      _________________________________________________________________
  551.    
  552.    Python/XML Reference Guide
  553.      _________________________________________________________________
  554.  
  555.