4Suite API Documentation

Module Ft.Xml

Module providing utilities for processing XML files
Copyright 2006 Fourthought, Inc. (USA).
Detailed license and copyright information: http://4suite.org/COPYRIGHT
Project home, documentation, distributions: http://4suite.org/
Classes:
Functions:
Globals:

Modules

Classes and functions that help implement OASIS XML and TR9401 Catalogs. Resolution with Catalogs is handled via the Ft.Xml.InputSource module.
Abstraction module for Domlette usage. Domlette is a DOM-like library tailored for use in XPath/XSLT.
Classes providing a standard interface and encapsulation of metadata for document/entity streams intended for input to various XML processors.
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)
Localizable message strings
Abstraction module for Domlette SAX usage.
XInclude processing
XLink processing package
4XPath initialization and principal functions
Module for XPointer processing
XUpdate request processing
4XSLT initialization and XSLT pattern tools
XVIF integration for 4Suite. Includes basic RELAX NG support
cDomlette implementation: a very fast DOM-like library tailored for use in XPath/XSLT
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 0x401dd060>, **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

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

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'