Package lxml :: Module objectify

[hide private]
[frames] | no frames]

# Module objectify

The `lxml.objectify` module implements a Python object API for XML. It is based on lxml.etree.

Version: 2.3.6

Classes | [hide private]

| BoolElement Boolean type base on string values: 'true' or 'false'.
| ElementMaker ElementMaker(self, namespace=None, nsmap=None, annotate=True, makeelement=None)
| FloatElement
| IntElement
| LongElement
| NoneElement
| NumberElement
| ObjectPath ObjectPath(path) Immutable object that represents a compiled object path.
| ObjectifiedDataElement This is the base class for all data type Elements. Subclasses should override the 'pyval' property and possibly the __str__ method.
| ObjectifiedElement Main XML Element class.
| ObjectifyElementClassLookup ObjectifyElementClassLookup(self, tree_class=None, empty_data_class=None) Element class lookup method that uses the objectify classes.
| PyType PyType(self, name, type_check, type_class, stringify=None) User defined type.
| StringElement String data class.

Functions | [hide private]

DataElement(_value, attrib=None, nsmap=None, _pytype=None, _xsi=None, **_attributes) Create a new element from a Python value and XML attributes taken from keyword arguments or a dictionary passed as second argument. |

Element(_tag, attrib=None, nsmap=None, _pytype=None, **_attributes) Objectify specific version of the lxml.etree Element() factory that always creates a structural (tree) element. |

SubElement(_parent, _tag, attrib=None, nsmap=None, **_extra) Subelement factory. This function creates an element instance, and appends it to an existing element. |

XML(xml, parser=None, base_url=None) Objectify specific version of the lxml.etree XML() literal factory that uses the objectify parser. |

__checkBool(...) |

__lower_bool(...) |

__parseBool(...) |

__unpickleElementTree(...) |

annotate(element_or_tree, ignore_old=True, ignore_xsi=False, empty_pytype=None, empty_type=None, annotate_xsi=0, annotate_pytype=1) Recursively annotates the elements of an XML tree with 'xsi:type' and/or 'py:pytype' attributes. |

deannotate(element_or_tree, pytype=True, xsi=True, xsi_nil=False, cleanup_namespaces=False) Recursively de-annotate the elements of an XML tree by removing 'py:pytype' and/or 'xsi:type' attributes and/or 'xsi:nil' attributes. |

dump(...) dump(_Element element not None) |

enable_recursive_str(on=True) Enable a recursively generated tree representation for str(element), based on objectify.dump(element). |

fromstring(xml, parser=None, base_url=None) Objectify specific version of the lxml.etree fromstring() function that uses the objectify parser. |

getRegisteredTypes() Returns a list of the currently registered PyType objects. |

makeparser(remove_blank_text=True, **kw) Create a new XML parser for objectify trees. |

parse(f, parser=None, base_url=None) Parse a file or file-like object with the objectify parser. |

pyannotate(element_or_tree, ignore_old=False, ignore_xsi=False, empty_pytype=None) Recursively annotates the elements of an XML tree with 'pytype' attributes. |

pytypename(obj) Find the name of the corresponding PyType for a Python object. |

set_default_parser(new_parser= None) Replace the default parser used by objectify's Element() and fromstring() functions. |

set_pytype_attribute_tag(attribute_tag=None) Change name and namespace of the XML attribute that holds Python type information. |

xsiannotate(element_or_tree, ignore_old=False, ignore_pytype=False, empty_type=None) Recursively annotates the elements of an XML tree with 'xsi:type' attributes. |

Variables | [hide private]

| E = `<lxml.objectify.ElementMaker object at 0x28de830>`
| PYTYPE_ATTRIBUTE = ``'``{http://codespeak.net/lxml/objectify/pytyp``...``
| __package__ = `None` hash(x)
| __test__ = ``{``}``

Function Details | [hide private]

### DataElement(_value, attrib=None, nsmap=None, _pytype=None, _xsi=None, **_attributes)

Create a new element from a Python value and XML attributes taken from keyword arguments or a dictionary passed as second argument.

Automatically adds a 'pytype' attribute for the Python type of the value, if the type can be identified. If '_pytype' or '_xsi' are among the keyword arguments, they will be used instead.

If the _value argument is an ObjectifiedDataElement instance, its py:pytype, xsi:type and other attributes and nsmap are reused unless they are redefined in attrib and/or keyword arguments.

### Element(_tag, attrib=None, nsmap=None, _pytype=None, **_attributes)

Objectify specific version of the lxml.etree Element() factory that always creates a structural (tree) element.

NOTE: requires parser based element class lookup activated in lxml.etree!

### XML(xml, parser=None, base_url=None)

Objectify specific version of the lxml.etree XML() literal factory that uses the objectify parser.

You can pass a different parser as second argument.

The `base_url` keyword argument allows to set the original base URL of the document to support relative Paths when looking up external entities (DTD, XInclude, ...).

### annotate(element_or_tree, ignore_old=True, ignore_xsi=False, empty_pytype=None, empty_type=None, annotate_xsi=0, annotate_pytype=1)

Recursively annotates the elements of an XML tree with 'xsi:type' and/or 'py:pytype' attributes.

If the 'ignore_old' keyword argument is True (the default), current 'py:pytype' attributes will be ignored for the type annotation. Set to False if you want reuse existing 'py:pytype' information (iff appropriate for the element text value).

If the 'ignore_xsi' keyword argument is False (the default), existing 'xsi:type' attributes will be used for the type annotation, if they fit the element text values.

Note that the mapping from Python types to XSI types is usually ambiguous. Currently, only the first XSI type name in the corresponding PyType definition will be used for annotation. Thus, you should consider naming the widest type first if you define additional types.

The default 'py:pytype' annotation of empty elements can be set with the `empty_pytype` keyword argument. Pass 'str', for example, to make string values the default.

The default 'xsi:type' annotation of empty elements can be set with the `empty_type` keyword argument. The default is not to annotate empty elements. Pass 'string', for example, to make string values the default.

The keyword arguments 'annotate_xsi' (default: 0) and 'annotate_pytype' (default: 1) control which kind(s) of annotation to use.

### deannotate(element_or_tree, pytype=True, xsi=True, xsi_nil=False, cleanup_namespaces=False)

Recursively de-annotate the elements of an XML tree by removing 'py:pytype' and/or 'xsi:type' attributes and/or 'xsi:nil' attributes.

If the 'pytype' keyword argument is True (the default), 'py:pytype' attributes will be removed. If the 'xsi' keyword argument is True (the default), 'xsi:type' attributes will be removed. If the 'xsi_nil' keyword argument is True (default: False), 'xsi:nil' attributes will be removed.

Note that this does not touch the namespace declarations by default. If you want to remove unused namespace declarations from the tree, pass the option `cleanup_namespaces=True`.

### dump(...)

dump(_Element element not None)

Return a recursively generated string representation of an element.

### fromstring(xml, parser=None, base_url=None)

Objectify specific version of the lxml.etree fromstring() function that uses the objectify parser.

You can pass a different parser as second argument.

The `base_url` keyword argument allows to set the original base URL of the document to support relative Paths when looking up external entities (DTD, XInclude, ...).

### getRegisteredTypes()

Returns a list of the currently registered PyType objects.

To add a new type, retrieve this list and call unregister() for all entries. Then add the new type at a suitable position (possibly replacing an existing one) and call register() for all entries.

This is necessary if the new type interferes with the type check functions of existing ones (normally only int/float/bool) and must the tried before other types. To add a type that is not yet parsable by the current type check functions, you can simply register() it, which will append it to the end of the type list.

### makeparser(remove_blank_text=True, **kw)

Create a new XML parser for objectify trees.

You can pass all keyword arguments that are supported by `etree.XMLParser()`. Note that this parser defaults to removing blank text. You can disable this by passing the `remove_blank_text` boolean keyword option yourself.

### parse(f, parser=None, base_url=None)

Parse a file or file-like object with the objectify parser.

You can pass a different parser as second argument.

The `base_url` keyword allows setting a URL for the document when parsing from a file-like object. This is needed when looking up external entities (DTD, XInclude, ...) with relative paths.

### pyannotate(element_or_tree, ignore_old=False, ignore_xsi=False, empty_pytype=None)

Recursively annotates the elements of an XML tree with 'pytype' attributes.

If the 'ignore_old' keyword argument is True (the default), current 'pytype' attributes will be ignored and replaced. Otherwise, they will be checked and only replaced if they no longer fit the current text value.

Setting the keyword argument `ignore_xsi` to True makes the function additionally ignore existing `xsi:type` annotations. The default is to use them as a type hint.

The default annotation of empty elements can be set with the `empty_pytype` keyword argument. The default is not to annotate empty elements. Pass 'str', for example, to make string values the default.

### set_default_parser(new_parser= None)

Replace the default parser used by objectify's Element() and fromstring() functions.

The new parser must be an etree.XMLParser.

Call without arguments to reset to the original parser.

### set_pytype_attribute_tag(attribute_tag=None)

Change name and namespace of the XML attribute that holds Python type information.

Do not use this unless you know what you are doing.

Reset by calling without argument.

Default: "{http://codespeak.net/lxml/objectify/pytype}pytype"

### xsiannotate(element_or_tree, ignore_old=False, ignore_pytype=False, empty_type=None)

Recursively annotates the elements of an XML tree with 'xsi:type' attributes.

If the 'ignore_old' keyword argument is True (the default), current 'xsi:type' attributes will be ignored and replaced. Otherwise, they will be checked and only replaced if they no longer fit the current text value.

Note that the mapping from Python types to XSI types is usually ambiguous. Currently, only the first XSI type name in the corresponding PyType definition will be used for annotation. Thus, you should consider naming the widest type first if you define additional types.

Setting the keyword argument `ignore_pytype` to True makes the function additionally ignore existing `pytype` annotations. The default is to use them as a type hint.

The default annotation of empty elements can be set with the `empty_type` keyword argument. The default is not to annotate empty elements. Pass 'string', for example, to make string values the default.

Variables Details | [hide private]

### PYTYPE_ATTRIBUTE

Value:

      '{http://codespeak.net/lxml/objectify/pytype}pytype'