4Suite API Documentation: Ft.Xml

4Suite™ API Documentation

# ► Module Ft.Xml

Module providing utilities for processing XML files

    Copyright 2005 Fourthought, Inc. (USA).
    Detailed license and copyright information: http://4suite.org/COPYRIGHT
    Project home, documentation, distributions: http://4suite.org/

Classes: MarkupWriter, ReaderException, XIncludeException |  |  |  | Functions: ApplyXUpdate, Parse, ParsePath, SplitQName |  |  |  | Globals: EMPTY_NAMESPACE, EMPTY_PREFIX, HAS_PYEXPAT, READ_EXTERNAL_DTD, XHTML_NAMESPACE, XMLNS_NAMESPACE, XML_NAMESPACE

## Modules

Catalog | Classes and functions that help implement OASIS XML and TR9401 Catalogs. Resolution with Catalogs is handled via the Ft.Xml.InputSource module.
Domlette | Abstraction module for Domlette usage. Domlette is a DOM-like library tailored for use in XPath/XSLT.
InputSource | Classes providing a standard interface and encapsulation of metadata for document/entity streams intended for input to various XML processors.
Lib | Module providing XML support utilities (including serialization and tree comparison)
MarkupWriter | General-purpose utility class for generating XML (may eventually be expanded to produce more output types)
MessageSource | Localizable message strings
Sax | Abstraction module for Domlette SAX usage.
ThirdParty |
XInclude | XInclude processing
XLink | XLink processing package
XPath | 4XPath initialization and principal functions
XPointer | Module for XPointer processing
XUpdate | XUpdate request processing
Xslt | 4XSLT initialization and XSLT pattern tools
Xvif | XVIF integration for 4Suite. Includes basic RELAX NG support
cDomlette | cDomlette implementation: a very fast DOM-like library tailored for use in XPath/XSLT
cDomlettec | cDomlette implementation: a very fast DOM-like library tailored for use in XPath/XSLT

## Classes

class MarkupWriter(object)
  General-purpose utility class for generating XML (may eventually be expanded to produce more output types)

      Sample usage:

      from Ft.Xml import MarkupWriter
      writer = MarkupWriter(indent=u"yes")
      writer.startDocument()
      writer.startElement(u'xsa')
      writer.startElement(u'vendor')
      #Element with simple text (#PCDATA) content
      writer.simpleElement(u'name', content=u'Centigrade systems')
      #Note writer.text(content) still works
      writer.simpleElement(u'email', content=u"info@centigrade.bogus")
      writer.endElement(u'vendor')
      #Element with an attribute
      writer.startElement(u'product', attributes={u'id': u"100\u00B0"})
      #Note writer.attribute(name, value, namespace=None) still works
      writer.simpleElement(u'name', content=u"100\u00B0 Server")
      #XML fragment
      writer.xmlFragment('<version>1.0</version><last-release>20030401</last-release>')
      #Empty element
      writer.simpleElement(u'changes')
      writer.endElement(u'product')
      writer.endElement(u'xsa')
      writer.endDocument()

      Note on the difference between 4Suite writers and printers
      Writer  - module that exposes a broad public API for building output
                bit by bit
      Printer - module that simply takes a DOM and creates output from it
                as a whole, within one API invokation

  ### Methods

  __getattr__(self, value)
  __init__(self, stream=<open file '<stdout>', mode 'w' at 0xb7d5a068>, **wargs)
    Convenience factory function for Markup writers (based on xsl:output in XSLT)
    Overrides: __init__ from class object
  simpleElement(self, tagName, namespace=None, extraNss=None, attributes=None, content=u'')
    Create a simple tag with optional attributes and content. The complete element, start tag, optional text content, end tag, will all be generated by this one call. Must *not* be matched with an endElement call.

        Note: all "strings" in these parameters must be unicode objects
        tagName - qualified name of the element
        namespace - optional namespace URI
        attributes - optional dictionary mapping name to unicode value
                    the name can either be a unicode QName or a tuple
                    of (QName, namespace URI)
        content   - optional unicode object with the text body of the
                    simple element
        extraNss - optional dictionary (defaults to an empty one) that
                   creates additional namespace declarations that the
                   user wants to place on the specific element. Each key
                   is a ns prefix, and each value a ns name (URI).
                   You do not need to use extraNss if you will be using
                   a similar namespace parameter.  In fact, most people
                   will never need this parameter.

  startElement(self, tagName, namespace=None, extraNss=None, attributes=None)
    Create a start tag with optional attributes. Must eventually be matched with an endElement call

        Note: all "strings" in these parameters must be unicode objects
        tagName - qualified name of the element (must be unicode)
        namespace - optional namespace URI
        attributes - optional dictionary mapping name to unicode value
                    the name can either be a unicode QName or a tuple
                    of (QName, namespace URI)
        extraNss - optional dictionary (defaults to an empty one) that
                   creates additional namespace declarations that the
                   user wants to place on the specific element. Each key
                   is a ns prefix, and each value a ns name (URI).
                   You do not need to use extraNss if you will be using
                   a similar namespace parameter.  In fact, most people
                   will never need this parameter.

  xmlFragment(self, fragment)
    Incorporate a well-formed general entity into the output. fragment of fragment - string (must not be a Unicode object) to be incorporated verbatim into the output, after testing for wellp-formedness

  ### Methods inherited from class object

  __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

  ### Members

  __dict__ = <attribute '__dict__' of 'MarkupWriter' objects>
  __weakref__ = <attribute '__weakref__' of 'MarkupWriter' objects>

  ### Members inherited from class object

  __class__
class ReaderException(Ft.FtException)
  Exception class for errors specific to XML reading (at a level above standard, non-namespace-aware parsing)

  ### Methods

  __init__(self, errorCode, systemId, lineNumber, columnNumber, **kwords)
    Overrides: __init__ from class FtException
  __str__(self)
    Overrides: __str__ from class FtException

  ### Methods inherited from class Ft.FtException

  __getattr__, __repr__

  ### Methods inherited from class Exception

  __getitem__

  ### Members

  ASYNC_ENTITY = 13
  ATTRIBUTES_WITHOUT_ELEMENT = 2000
  ATTRIBUTE_DECLARED = 2001
  ATTRIBUTE_EXTERNAL_ENTITY_REF = 16
  ATTRIBUTE_UNDECLARED_NOTATION = 1023
  BAD_CHAR_REF = 14
  BINARY_ENTITY_REF = 15
  DUPLICATE_ATTRIBUTE = 8
  DUPLICATE_ELEMENT_DECL = 1013
  DUPLICATE_ID = 1007
  DUPLICATE_ID_DECL = 1014
  ENTITY_DECLARED = 2002
  ENTITY_DECLARED_IN_PE = 24
  ENTITY_UNDECLARED_NOTATION = 1024
  EXTERNAL_ENTITY_HANDLING = 21
  ID_ATTRIBUTE_DEFAULT = 1015
  ILLEGAL_PARAM_ENTITY_REF = 10
  INCOMPLETE_ELEMENT = 1004
  INCOMPLETE_PE = 29
  INCORRECT_ENCODING = 19
  INVALID_ELEMENT = 1001
  INVALID_ENTITY = 1009
  INVALID_ENUM_VALUE = 1022
  INVALID_NAME_SEQ_VALUE = 1019
  INVALID_NAME_VALUE = 1018
  INVALID_NMTOKEN_SEQ_VALUE = 1021
  INVALID_NMTOKEN_VALUE = 1020
  INVALID_PUBLICID = 32
  INVALID_TEXT = 1005
  INVALID_TEXT_DECL = 31
  INVALID_TOKEN = 4
  INVALID_XML_DECL = 30
  JUNK_AFTER_DOCUMENT_ELEMENT = 9
  MISPLACED_XML_PI = 17
  MISSING_ATTRIBUTE = 1011
  MISSING_DOCTYPE = 1000
  NOT_STANDALONE = 22
  NO_ELEMENTS = 3
  PARTIAL_CHAR = 6
  RECURSIVE_ENTITY_REF = 12
  RECURSIVE_PARSE_ERROR = 101
  RESERVED_NAMESPACE_URI = 40
  RESERVED_PREFIX_XML = 38
  RESERVED_PREFIX_XMLNS = 39
  ROOT_ELEMENT_MISMATCH = 1002
  SYNTAX_ERROR = 2
  TAG_MISMATCH = 7
  UNBOUND_PREFIX = 27
  UNCLOSED_CDATA_SECTION = 20
  UNCLOSED_TOKEN = 5
  UNDECLARED_ATTRIBUTE = 1006
  UNDECLARED_ELEMENT = 1003
  UNDECLARED_ENTITY = 1008
  UNDECLARED_NOTATION = 1010
  UNDECLARED_PREFIX = 28
  UNDEFINED_ENTITY = 11
  UNDEFINED_ID = 1012
  UNKNOWN_ENCODING = 18
  XML_PARSE_ERROR = 100
  XML_SPACE_DECL = 1016
  XML_SPACE_VALUES = 1017
class XIncludeException(Ft.FtException)
  Exception class for errors specific to XInclude processing

  ### Methods

  __init__(self, errorCode, *args)
    Overrides: __init__ from class FtException

  ### Methods inherited from class Ft.FtException

  __getattr__, __repr__, __str__

  ### Methods inherited from class Exception

  __getitem__

  ### Members

  FALLBACK_NOT_IN_INCLUDE = 16
  FRAGMENT_IDENTIFIER = 13
  INCLUDE_IN_INCLUDE = 15
  INVALID_PARSE_ATTR = 11
  MISSING_HREF = 10
  MULTIPLE_FALLBACKS = 17
  TEXT_XPOINTER = 12
  UNSUPPORTED_XPOINTER = 14

## Functions

ApplyXUpdate(*args, **kw_args)
  #Wrap this so that we can import it later
Parse(source)
  Convenience function for parsing XML. Use this function with a single argument, which must either be a string (not Unicode object), file-like object (stream), file path or URI.

      Returns a Domlette node.

      Only pass strings or streams to this function if the XML is self-contained
      XML (i.e. not requiring access to any other resource such as external
      entities or includes).  If you get URI resolution errors, do not use this
      function: use the lower-level APIs instead.  As an example, if you want
      such resolution to use the current working directory as a base, parse
      as follows for strings:

      from Ft.Xml.Domlette import NonvalidatingReader
      from Ft.Lib import Uri

      XML = "<!DOCTYPE a [ <!ENTITY b "b.xml"> ]><a>&b;</a>"

      base = Uri.OsPathToUri('')  #Turn CWD into a file: URL
      doc = NonvalidatingReader.parseString(XML, base)
      # during parsing, the replacement text for &b;
      # will be obtained from b.xml in the CWD

      For streams, use "parseStream" rather than "parseString" in the above.

ParsePath(source)
SplitQName(qualifiedName)
  SplitQName(qualifiedName) -> (prefix, localName)

      where 'qualifiedName' is a QName according to XML Namespaces 1.0
      <http://www.w3.org/TR/REC-xml-names>.
      returns the name parts according to the spec.

## Globals

EMPTY_NAMESPACE = None
EMPTY_PREFIX = None
HAS_PYEXPAT = True
READ_EXTERNAL_DTD = True
XHTML_NAMESPACE = u'http://www.w3.org/1999/xhtml'
XMLNS_NAMESPACE = u'http://www.w3.org/2000/xmlns/'
XML_NAMESPACE = u'http://www.w3.org/XML/1998/namespace'