xsc – XIST core classes

This module contains all the central XML tree classes, exception and warning classes and a few helper classes and functions.

ll.xist.xsc.tonode(value)

Convert value to an XIST Node.

If value is a tuple or list, it will be (recursively) converted to a Frag. Integers, strings, etc. will be converted to a Text. If value is a Node already, it will be returned unchanged. In the case of None the XIST Null (ll.xist.xsc.Null) will be returned. If value is iterable, a Frag will be generated from the items. Anything else will raise an IllegalObjectError exception.

class ll.xist.xsc.build

Bases: object

A build object can be used as a context handler to create a new XIST tree:

with xsc.build():
   with html.ul() as e:
      +html.li("gurk")
      +html.li("hurz")

class ll.xist.xsc.addattr

Bases: object

An addattr object can be used as a context handler to modify an attribute of an element:

with xsc.build():
   with html.div() as e:
      with xsc.addattr("align"):
         +xsc.Text("right")

__init__(attrname)

Create an addattr object for adding to the attribute named attrname (which can be the Python name of an attribute or an attribute class).

ll.xist.xsc.add(*args, **kwargs)

add() appends items in args and sets attributes in kwargs in the currently active node in the with stack.

class ll.xist.xsc.Context

Bases: object

This is an empty class that can be used by the convert() method to hold element or namespace specific data during the convert() call. The method Converter.__getitem__() will return a unique instance of this class.

exception ll.xist.xsc.Error

Bases: Exception

Base class for all XIST exceptions

exception ll.xist.xsc.Warning

Bases: UserWarning

Base class for all warning exceptions (i.e. those that won’t result in a program termination.)

exception ll.xist.xsc.IllegalAttrValueWarning

Bases: Warning

Warning that is issued when an attribute has an illegal value.

exception ll.xist.xsc.RequiredAttrMissingWarning

Bases: Warning

Warning that is issued when a required attribute is missing.

exception ll.xist.xsc.UndeclaredAttrWarning

Bases: Warning

Warning that is issued when a local attribute is not declared.

exception ll.xist.xsc.UndeclaredNodeWarning

Bases: Warning

Warning that is issued when a node (i.e. element, entity or processing instruction) is not declared.

exception ll.xist.xsc.IllegalPrefixError

Bases: Error, LookupError

Exception that is raised when a namespace prefix is undefined.

exception ll.xist.xsc.FileNotFoundWarning

Bases: Warning

Warning that is issued when a file can’t be found.

exception ll.xist.xsc.IllegalObjectError

Bases: Error, TypeError

Exception that is raised when an XIST constructor gets passed an unconvertable object.

exception ll.xist.xsc.IllegalCommentContentWarning

Bases: Warning

Warning that is issued when there is an illegal comment, i.e. one containing -- or ending in -. (This can only happen when the comment was created by code, not when parsed from an XML file.)

exception ll.xist.xsc.IllegalProcInstFormatError

Bases: Error

Exception that is raised when there is an illegal processing instruction, i.e. one containing ?>. (This can only happen when the processing instruction was created by code, not when parsed from an XML file.)

class ll.xist.xsc.Converter

Bases: object

An instance of this class is passed around in calls to the convert() method. A Converter object can be used when some element needs to keep state across a nested convert() call. A typical example are nested chapter/subchapter elements with automatic numbering. For an example see the element ll.xist.ns.doc.section.

__init__(node=None, root=None, mode=None, stage=None, target=None, lang=None, makeaction=None, makeproject=None)

Create a Converter. Arguments are used to initialize the Converter properties of the same name.

__getitem__(key)

Return a context object for key. Two variants are supported:

• key may be a string, in which case it should be a hierarchical dot-separated name similar to Java package names (e.g. "org.example.project.handler"). This helps avoid name collisions. Context objects of this type must be explicitly created via __setitem__().

• key may be a ll.xist.xsc.Node instance or subclass. Each of these classes that defines its own Context class gets a unique instance of this class. This instance will be created on the first access and the element can store information there that needs to be available across calls to convert().

class ll.xist.xsc.Publisher

Bases: object

A Publisher object is used for serializing an XIST tree into a byte sequence.

__init__(encoding=None, xhtml=1, validate=False, prefixes={}, prefixdefault=False, hidexmlns=(), showxmlns=())

Create a publisher. Arguments have the following meaning:

encodingstring or None

Specifies the encoding to be used for the byte sequence. If None is used the encoding in the XML declaration will be used. If there is no XML declaration, UTF-8 will be used.

xhtmlint

With the parameter xhtml you can specify if you want HTML output:

HTML (xhtml==0)

Elements with a empty content model will be published as <foo>.

HTML browser compatible XML (xhtml==1)

Elements with an empty content model will be published as <foo /> and others that just happen to be empty as <foo></foo>. This is the default.

Pure XML (xhtml==2)

All empty elements will be published as <foo/>.

validatebool

Specifies whether validation should be done before publishing.

prefixesmapping

A dictionary that specifies which namespace prefixes should be used for publishing. Keys in the dictionary are either namespace names or objects that have an xmlns attribute which is the namespace name. Values can be:

False

Treat elements in this namespace as if they are not in any namespace (if global attributes from this namespace are encountered, a non-empty prefix will be used nonetheless).

None

Treat the namespace as the default namespaces (i.e. use unprefixed element names). Global attributes will again result in a non-empty prefix.

True

The publisher uses a unique non-empty prefix for this namespace.

A string

Use this prefix for the namespace.

prefixdefaultstring or None

If an element or attribute is encountered whose namespace name is not in prefixes prefixdefault is used as the fallback.

hidexmlnslist or set

hidexmlns can be a list or set that contains namespace names for which no xmlns attributes should be published. (This can be used to hide the namespace declarations for e.g. Java taglibs.)

showxmlnslist or set

showxmlns can be a list or set that contains namespace names for which xmlns attributes will be published, even if there are no elements from this namespace in the tree.

encode(text)

Encode text with the encoding and error handling currently active and return the resulting byte string.

encodetext(text)

Encode test as text data. text must be a str object. The publisher will apply the configured encoding, error handling and the current text filter (which escapes characters that can’t appear in text data (like < etc.)) and returns the resulting str object.

pushtextfilter(filter)

Pushes a new text filter function ontp the text filter stack. This function is responsible for escaping characters that can’t appear in text data (like <)). This is used to switch on escaping of " inside attribute values.

poptextfilter()

Pops the current text filter function from the stack.

pusherrors(errors)

Pushes a new error handling scheme onto the error handling stack.

poperrors()

Pop the current error handling scheme from the error handling stack.

getencoding()

Return the encoding currently in effect.

getnamespaceprefix(xmlns)

Return (and register) a namespace prefix for the namespace name xmlns. This honors the namespace configuration from self.prefixes and self.prefixdefault. Furthermore the same prefix will be returned from now on (except when the empty prefix becomes invalid once global attributes are encountered)

getobjectprefix(obj)

Get and register a namespace prefix for the namespace obj lives in (specified by the xmlns attribute of obj). Similar to getnamespaceprefix() this honors the namespace configuration from self.prefixes and self.prefixdefault (except when a global attribute requires a non-empty prefix).

iterbytes(node, base=None, allowschemerelurls=False)

Output the node node. This method is a generator that will yield the resulting XML byte sequence in fragments.

URLs in node will be published relative to the base URL base.

Setting allowschemerelurls to true allow schema-relative URLs (e.g. //www.example.org/about.html).

bytes(node, base=None, allowschemerelurls=False)

Return a bytes object in XML format for the XIST node node.

iterstring(node, base=None, allowschemerelurls=False)

A generator that will produce a serialized string of node.

string(node, base=None, allowschemerelurls=False)

Return a string for node.

write(stream, node, base=None, allowschemerelurls=False)

Write node to the file-like object stream (which must provide a write() method).

class ll.xist.xsc.Cursor

Bases: object

A Cursor object is used by the walk() method during tree traversal. It contains information about the state of the traversal and can be used to influence which parts of the tree are traversed and in which order.

Information about the state of the traversal is provided in the following attributes:

root

The node where traversal has been started (i.e. the object for which the walk() method has been called).

node

The current node being traversed.

path

A list of nodes that contains the path through the tree from the root to the current node (i.e. path[0] is root and path[-1] is node).

index

A path of indices (e.g. [0, 1] if the current node is the second child of the first child of the root). Inside attributes the index path will contain the name of the attribute (or a (attribute name, namespace name) tuple inside a global attribute).

event

A string that specifies which event is currently handled. Possible values are: "enterelementnode", "leaveelementnode", "enterattrnode", "leaveattrnode", "textnode", "commentnode", "doctypenode" "procinstnode", "entitynode" and "nullnode"

The following attributes specify which part of the tree should be traversed:

entercontent

Should the content of an element be entered?

enterattrs

Should the attributes of an element be entered? (Note that the attributes will always be entered before the content.)

enterattr

Should the content of the attributes of an element be entered? (This is only relevant if enterattrs is true.)

enterelementnode

Should the generator yield a "enterelementnode" event (i.e. return before entering the content or attributes of an element)?

leaveelementnode

Should the generator yield an "leaveelementnode" event (i.e. return after entering the content or attributes of an element)?

enterattrnode

Should the generator yield a "enterattrnode" event (i.e. return before entering the content of an attribute)? This is only relevant if enterattrs is true.

leaveattrnode

Should the generator yield an "leaveattrnode" event (i.e. return after entering the content of an attribute)? This is only relevant if enterattrs is true. Furthermore if enterattr is false, the behaviour is essentially the same as for enterattrnode.

Note that if any of these attributes is changed by the code consuming the generator, this new value will be used for the next traversal step once the generator is resumed and will be reset to its initial value (specified in the constructor) afterwards.

__init__(node, entercontent=True, enterattrs=False, enterattr=False, enterelementnode=True, leaveelementnode=False, enterattrnode=True, leaveattrnode=False)

Create a new Cursor object for a tree traversal rooted at the node node.

The arguments entercontent, enterattrs, enterattr, enterelementnode, leaveelementnode, enterattrnode and leaveattrnode are used as the initial values for the attributes of the same name. (see the class docstring for info about their use).

restore()

Restore the attributes entercontent, enterattrs, enterattr, enterelementnode, leaveelementnode, enterattrnode and leaveattrnode to their initial value.

class ll.xist.xsc.Node

Bases: object

Base class for nodes in the document tree. Derived classes may overwrite convert() or publish().

class Context

Bases: object

This is an empty class that can be used by the convert() method to hold element or namespace specific data during the convert() call. The method Converter.__getitem__() will return a unique instance of this class.

__truediv__(other)

Return a ChildCombinator with self as the left hand selector.

__floordiv__(other)

Return a DescendantCombinator with self as the left hand selector.

__mul__(other)

If other is an int, return a Frag with other times the node as an entry. Note that the node will not be copied, i.e. this is a “shallow __mul__()”.

If other is not an int, treat this a CSS combinator that creates an AdjacentSiblingCombinator with self as the left hand selector.

__rmul__(other)

Return a Frag with other times the node as an entry.

__pow__(other)

Return a GeneralSiblingCombinator with self as the left hand selector.

__and__(other)

Return an AndCombinator with self as the left hand selector.

__or__(other)

Return an OrCombinator with self as the left hand selector.

clone()

Return a clone of self. Compared to deepcopy() clone() will create multiple instances of objects that can be found in the tree more than once. clone() can’t clone trees that contain cycles.

copy()

Return a shallow copy of self.

deepcopy()

Return a deep copy of self.

present(presenter)

present() is used as a central dispatch method for the presenter classes. Normally it is not called by the user, but internally by the presenter. The user should use the appropriate presenter class directly.

conv(converter=None, root=None, mode=None, stage=None, target=None, lang=None, function=None, makeaction=None, makeproject=None)

Convenience method for calling convert().

conv() will automatically set converter.node to self to remember the “document root node” for which conv() has been called. This means that you should not call conv() in any of the recursive calls, as you would loose this information. Call convert() directly instead.

convert(converter)

Implementation of the conversion method. When you define your own element classes you have to overwrite this method and implement the desired conversion.

This method must return an instance of Node. It may not change self.

__str__()

Return the character content of self as a string. This means that comments and processing instructions will be filtered out. For elements you’ll get the element content.

__str__() can be used everywhere where a plain string representation of the node is required.

For example:

>>> from ll.xist.ns import html
>>> e = html.html(
...    html.head(
...       html.title("The page")
...    ),
...    html.body(
...       html.h1("The header"),
...       html.p("The content", class_="content")
...    )
... )
>>> print(e)
The pageThe headerThe content

__int__()

Convert the character content of self to an int.

asFloat(decimal='.', ignore='')

Convert the character content of self to an float. decimal specifies which decimal separator is used in the value (e.g. "." (the default) or ","). ignore specifies which characters will be ignored.

__float__()

Convert the character content of self to an float.

__complex__()

Convert the character content of self to an complex.

parsed(parser, event)

This method will be called by the parser parser once after self is created by the parser (This is used e.g. by URLAttr to incorporate the base URL into the attribute).

event is the parser event that initiated the call.

validate(recursive=True, path=None)

This method will be called when parsing or publishing to check whether self is valid.

If self is found to be invalid a warning should be issued through the Python warning framework.

publish(publisher)

Generate unicode strings for the node. publisher must be an instance of Publisher.

The encoding and xhtml specification are taken from the publisher.

iterbytes(base=None, allowschemerelurls=False, publisher=None, **publishargs)

A generator that will produce this node as a serialized byte string. (i.e. it will output what the method bytes() outputs, but incremetally).

For the possible parameters see the Publisher constructor and its iterbytes() method.

bytes(base=None, allowschemerelurls=False, publisher=None, **publishargs)

Return self as a serialized bytes object.

For the possible parameters see the Publisher constructor.

For example:

>>> from ll.xist.ns import html
>>> e = html.div(
...    html.h1("The header"),
...    html.p("The content", class_="content")
... )
>>> print(e.bytes())
b'<div><h1>The header</h1><p class="content">The content</p></div>'

iterstring(base=None, allowschemerelurls=False, publisher=None, **publishargs)

A generator that will produce a serialized string of self (i.e. it will output what the method string() outputs, but incremetally).

For the possible parameters see the Publisher constructor.

string(base=None, allowschemerelurls=False, publisher=None, **publishargs)

Return a serialized (unicode) string for self.

For the possible parameters see the Publisher constructor.

For example:

>>> from ll.xist.ns import html
>>> e = html.div(
...    html.h1("The header"),
...    html.p("The content", class_="content")
... )
>>> print(e.string())
<div><h1>The header</h1><p class="content">The content</p></div>

write(stream, base=None, allowschemerelurls=False, publisher=None, **publishargs)

Write self to the file-like object stream (which must provide a write() method).

For the rest of the parameters see the Publisher constructor.

walk(*selectors, entercontent=True, enterattrs=False, enterattr=False, enterelementnode=True, leaveelementnode=False, enterattrnode=True, leaveattrnode=False)

Return an iterator for traversing the tree rooted at self.

Each item produced by the iterator is a Cursor object. It contains information about the state of the traversal and can be used to influence which parts of the tree are traversed and in which order.

selectors is used for filtering which nodes to return from the iterator. The arguments entercontent, enterattrs, enterattr, enterelementnode, leaveelementnode, enterattrnode and leaveattrnode specify how the tree should be traversed. For more information see the Cursor class.

Note that the Cursor object is reused by walk(), so you can’t rely on any attributes remaining the same across calls to next().

The following example shows how to extract the text of an HTML label element for an input element with a specified HTML id:

from ll import misc
from ll.xist import xsc, xfind
from ll.xist.ns import html

def label(doc, id):
   label = misc.first(doc.walk(xfind.attrhasvalue("for", id)), None)
   if label is None:
      return None
   texts = []
   for c in label.node.walk(html.textarea, xsc.Text):
      if isinstance(c.node, html.textarea):
         c.entercontent = False
      else:
         texts.append(str(c.node))
   return " ".join("".join(texts).split()).strip()

doc = html.div(
   html.p(
      html.label(
         "Input your text here: ",
         html.textarea("Default value", rows=20, cols=80, id="foo"),
         " (just a test)",
         for_="foo",
      )
   )
)

print(repr(label(doc, "foo")))

This will output:

'Input your text here: (just a test)'

walknodes(*selectors, entercontent=True, enterattrs=False, enterattr=False, enterelementnode=True, leaveelementnode=False, enterattrnode=True, leaveattrnode=False)

Return an iterator for traversing the tree. The arguments have the same meaning as those for walk(). The items produced by the iterator are the nodes themselves.

walkpaths(*selectors, entercontent=True, enterattrs=False, enterattr=False, enterelementnode=True, leaveelementnode=False, enterattrnode=True, leaveattrnode=False)

Return an iterator for traversing the tree. The arguments have the same meaning as those for walk(). The items produced by the iterator are copies of the path.

compacted()

Return a version of self, where textnodes or character references that contain only linefeeds are removed, i.e. potentially useless whitespace is removed.

mapped(function, converter=None, **converterargs)

Return the node mapped through the function function. This call works recursively (for Frag and Element).

When you want an unmodified node you simply can return self. mapped() will make a copy of it and fill the content recursively. Note that element attributes will not be mapped. When you return a different node from function this node will be incorporated into the result as-is.

normalized()

Return a normalized version of self, which means that consecutive Text nodes are merged.

pretty(level=0, indent='\t')

Return a prettyfied version of self, i.e. one with properly nested and indented tags (as far as possible). If an element has mixed content (i.e. Text and non-Text nodes) the content will be returned as is.

Note that whitespace will prevent pretty printing too, so you might want to call normalized() and compacted() before calling pretty() to remove whitespace.

class ll.xist.xsc.CharacterData

Bases: Node

Base class for XML character data (Text, ProcInst, Comment and DocType).

(Provides nearly the same functionality as UserString, but omits a few methods.)

class ll.xist.xsc.Text

Bases: CharacterData

A text node. The characters <, >, & (and " inside attributes) will be “escaped” with the appropriate character entities when this node is published.

class ll.xist.xsc.Frag

Bases: Node, list

A fragment contains a list of nodes and can be used for dynamically constructing content. The attribute content of an Element is a Frag.

clear()

Make self empty.

__copy__()

helper for the copy module.

__deepcopy__(memo=None)

helper for the copy module.

__getitem__(index)

Return the index’th node of the content of the fragment. If index is a list __getitem__() will work recursively. If index is an empty list, self will be returned. __getitem__() also supports selectors (i.e. xfind.Selector objects).

__setitem__(index, value)

Allows you to replace the index’th content node of the fragment with the new value value (which will be converted to a node). If index is a list __setitem__() will be applied to the innermost index after traversing the rest of index recursively. If index is an empty list, an exception will be raised. __setitem__() also supports selectors (i.e. xfind.Selector objects).

__delitem__(index)

Remove the index’th content node from the fragment. If index is a list, the innermost index will be deleted, after traversing the rest of index recursively. If index is an empty list, an exception will be raised. Anything except list, int and slice objects will be turned into a selector (i.e. an xfind.Selector objects) and any child node matching this selector will be deleted from self.

__mul__(factor)

Return a Frag with factor times the content of self. Note that no copies of the content will be generated, so this is a “shallow __mul__()”.

__rmul__(factor)

Return a Frag with factor times the content of self. Note that no copies of the content will be generated, so this is a “shallow __mul__()”.

append(*others)

Append every item in others to self.

extend(items)

Append all items from the sequence items to self.

insert(index, *others)

Insert all items in others at the position index. (this is the same as self[index:index] = others)

withsep(separator, clone=False)

Return a version of self with a separator node between the nodes of self.

if clone is false, one node will be inserted several times, if clone is true, clones of this node will be used.

reversed()

Return a reversed version of the self.

filtered(function)

Return a filtered version of the self, i.e. a copy of self, where only content nodes for which function returns true will be copied.

shuffled()

Return a shuffled version of self, i.e. a copy of self where the content nodes are randomly reshuffled.

class ll.xist.xsc.Comment

Bases: CharacterData

An XML comment.

class ll.xist.xsc.DocType

Bases: CharacterData

An XML document type declaration.

class ll.xist.xsc.ProcInst

Bases: CharacterData

Base class for processing instructions.

Processing instructions for specific targets must be implemented as subclasses of ProcInst.

class ll.xist.xsc.Attr

Bases: Frag

Base class of all attribute classes.

The content of an attribute may be any other XIST node. This is different from a normal DOM, where only text and character references are allowed. The reason for this is to allow dynamic content (implemented as elements or processing instructions) to be put into attributes.

Of course, this dynamic content when finally converted to HTML should normally result in a fragment consisting only of text and character references. But note that it is allowed to have elements and processing instructions inside of attributes even when publishing. Processing instructions will be published as is and for elements their content will be published:

>>> from ll.xist.ns import html, php
>>> node = html.img(
...    src=php.php("echo 'eggs.gif'"),
...    alt=html.abbr(
...       "EGGS",
...       title="Extensible Graphics Generation System",
...       lang="en"
...    )
... )
>>> print(node.string())
<img alt="EGGS" src="<?php echo 'eggs.gif'?>" />

isfancy()

Return whether self contains nodes other than Text.

validate(recursive=True, path=None)

Check whether self has an allowed value, i.e. one that is specified in the class attribute values. If the value is not allowed a warning will be issued through the Python warning framework.

If self is “fancy” (i.e. contains non-Text nodes), no check will be done.

class ll.xist.xsc.TextAttr

Bases: Attr

Attribute class that is used for normal text attributes.

class ll.xist.xsc.IDAttr

Bases: Attr

Attribute used for ids.

class ll.xist.xsc.NumberAttr

Bases: Attr

Attribute class that is used for when the attribute value may be any kind of number.

class ll.xist.xsc.IntAttr

Bases: NumberAttr

Attribute class that is used when the attribute value may be an integer.

class ll.xist.xsc.FloatAttr

Bases: NumberAttr

Attribute class that is used when the attribute value may be a floating point value.

class ll.xist.xsc.BoolAttr

Bases: Attr

Attribute class that is used for boolean attributes. When publishing the value will always be the attribute name, regardless of the real value.

class ll.xist.xsc.ColorAttr

Bases: Attr

Attribute class that is used for a color attributes.

class ll.xist.xsc.StyleAttr

Bases: Attr

Attribute class that is used for CSS style attributes.

replaceurls(replacer)

Replace each URL in the style. Each URL will be passed to the callable replacer and replaced with the returned value.

urls(base=None)

Return a list of all the URLs (as URL objects) found in the style attribute.

class ll.xist.xsc.URLAttr

Bases: Attr

Attribute class that is used for URLs. See the module ll.url for more information about URL handling.

asURL()

Return self as a URL object (note that non-Text content will be filtered out).

forInput(root=None)

return a URL pointing to the real location of the referenced resource. root must be the root URL relative to which self will be interpreted and usually comes from the root attribute of the converter argument in convert().

imagesize(root=None)

Return the size of an image as a tuple.

contentlength(root=None)

Return the size of a file in bytes.

lastmodified(root=None)

returns the timestamp for the last modification to the file

openread(root=None)

Return a Resource for reading from the URL.

openwrite(root=None)

Return a Resource for writing to the URL.

class ll.xist.xsc.Attrs

Bases: Node, dict

An attribute map. Predefined attributes can be declared through nested subclasses of Attr.

__getitem__(name)

Return the attribute with the name name. name can be one of the following types:

A string

name will be treated as the XML name of a local attribute.

A two-item tuple

The first item is treated as the XML attribute name and the second item as the namespace name. If the namespace name is None this refers to a local attributes, otherwise to a global attribute.

An Attr subclass

__setitem__(name, value)

Set the attribute with the XML name to the value value. name may be a string or an attribute class or instance. The newly set attribute object will be returned.

__delitem__(name)

get(name, default=None)

Works like the dictionary method get(), it returns the attribute with the XML name name, or default if self has no such attribute. name may also be an attribute class (either from self.Attrs or a global attribute).

setdefault(name, default)

Works like the dictionary method setdefault(), it returns the attribute with the Python name name. If self has no such attribute, it will be set to default and default will be returned as the new attribute value.

update(*args, **kwargs)

Copies attributes over from all mappings in args and from kwargs. Keywords are treated as the Python names of attributes.

classmethod declaredattrs()

Return an iterator over all declared attribute classes.

filtered(function)

Return a filtered version of self.

withnames(*names)

Return a copy of self where only the attributes with XML names in names are kept, all others are removed.

withoutnames(*names)

Return a copy of self where all the attributes with XML names in names are removed.

class ll.xist.xsc.Element

Bases: Node

This class represents XML/XIST elements. All elements implemented by the user must be derived from this class.

Elements support the following class variables:

modelobject with validate() method

This is an object that is used for validating the content of the element. See the module ll.xist.sims for more info. If model is None validation will be skipped, otherwise it will be performed when parsing or publishing.

AttrsElement.Attrs subclass

This is a class derived from Element.Attrs and must define all attributes as classes nested inside this Attrs class.

xmlnsstring

This is the name of the namespace this element belong to.

registerbool

If register is false the element will never be registered in a Pool. The default is True.

xmlnamestring

If the class name has to be different from the XML name (e.g. because the XML name is not a valid Python identifier) xmlname can be used to specify the real XML name. Otherwise the XML name will be the Python name.

class Attrs

Bases: Node, dict

An attribute map. Predefined attributes can be declared through nested subclasses of Attr.

__delitem__(name)

__getitem__(name)

Return the attribute with the name name. name can be one of the following types:

A string

name will be treated as the XML name of a local attribute.

A two-item tuple

The first item is treated as the XML attribute name and the second item as the namespace name. If the namespace name is None this refers to a local attributes, otherwise to a global attribute.

An Attr subclass

__setitem__(name, value)

Set the attribute with the XML name to the value value. name may be a string or an attribute class or instance. The newly set attribute object will be returned.

classmethod declaredattrs()

Return an iterator over all declared attribute classes.

filtered(function)

Return a filtered version of self.

get(name, default=None)

Works like the dictionary method get(), it returns the attribute with the XML name name, or default if self has no such attribute. name may also be an attribute class (either from self.Attrs or a global attribute).

setdefault(name, default)

Works like the dictionary method setdefault(), it returns the attribute with the Python name name. If self has no such attribute, it will be set to default and default will be returned as the new attribute value.

update(*args, **kwargs)

Copies attributes over from all mappings in args and from kwargs. Keywords are treated as the Python names of attributes.

withnames(*names)

Return a copy of self where only the attributes with XML names in names are kept, all others are removed.

withoutnames(*names)

Return a copy of self where all the attributes with XML names in names are removed.

__init__(*content, **attrs)

Create a new Element instance.

Positional arguments are treated as content nodes. Keyword arguments and dictionaries are treated as attributes.

__enter__()

Element nodes can be used in with blocks to build XIST trees. Inside a with block + and add() can be used to append node to the currently active element in the with block:

with xsc.build():
   with html.ul() as node:
      +html.li("I hear and I forget.")
      +html.li("I see and I believe.")
      +html.li("I do and I understand.")
      xsc.add(class_="quote")
print(node.bytes())

__call__(*content, **attrs)

Calling an element add items in content to the element content and set attributes from attrs. The element itself will be returned.

append(*items)

Append every item in items to the elements content.

extend(items)

Append all items in items to the elements content.

insert(index, *items)

Insert every item in items at the position index.

__getitem__(index)

If index is a string, return the attribute with this (Python) name. If index is an attribute class, return the attribute that is an instance of this class. If index is a number or slice return the appropriate content node. index may also be a list, in with case __getitem__() will be applied recusively. __getitem__() also supports walk filters.

__setitem__(index, value)

Set an attribute or content node to the value value. For possible types for index see __getitem__().

__delitem__(index)

Remove an attribute or content node. For possible types for index see __getitem__().

__len__()

Return the number of children.

withsep(separator, clone=False)

Return a version of self with a separator node between the child nodes of self. For more info see Frag.withsep().

reversed()

Return a reversed version of self.

filtered(function)

Return a filtered version of the self.

shuffled()

Return a shuffled version of the self.

class ll.xist.xsc.AttrElement

Bases: Element

Special subclass of Element.

When an AttrElement node is the only node in an attribute, it takes over publishing of the attribute (via the methods publishattr() and publishboolattr()). In all other cases publishing is done in the normal way (and must be overwritten with the publish() method).

publish(publisher)

Publish self to the publisher publisher (outside of any attribute)

publishattr(publisher, attr)

Publish the attribute attr to the publisher publisher.

publishboolattr(publisher, attr)

Publish the boolean attribute attr to the publisher

class ll.xist.xsc.Entity

Bases: Node

Class for entities. Derive your own entities from it and overwrite convert().

class ll.xist.xsc.CharRef

Bases: Text, Entity

A simple named character reference, the code point is in the class attribute codepoint.

class ll.xist.xsc.Pool

Bases: Pool

A Pool stores a collection of XIST classes and can be passed to a parser. The parser will ask the pool which classes to use when elements, processing instructions etc. have to be instantiated.

__init__(*objects)

Create a Pool object. All items in objects will be registered in the pool.

register(object)

Register object in the pool. object can be:

• a Element, ProcInst or Entity class;

• an Attr class for a global attribute;

• an Attrs class containing global attributes;

• a dict (all values will be registered, this makes it possible to e.g. register all local variables by passing vars());

• a module (all attributes in the module will be registered).

clear()

Make self empty.

clone()

Return a copy of self.

elements()

Return an iterator for all registered element classes.

elementclass(xmlns, name)

Return the element class for the element with the XML name name and the namespace xmlns. If the element can’t be found an Element will be returned.

element(xmlns, name)

Return an element object for the element type with the XML name name and the namespace xmlns.

haselement(xmlns, name)

Is there a registered element class in self for the element type with the Python name name and the namespace xmlns?

procinsts()

Return an iterator for all registered processing instruction classes.

procinstclass(name)

Return the processing instruction class for the PI with the target name name. If the processing instruction can’t be found an return ProcInst.

procinst(name, content)

Return a processing instruction object for the PI type with the target name name.

hasprocinst(name)

Is there a registered processing instruction class in self for the PI with the target name name?

entities()

Return an iterator for all registered entity classes.

entityclass(name)

Return the entity class for the entity with the XML name name. If the entity can’t be found return Entity.

entity(name)

Return an entity object for the entity with the XML name name.

hasentity(name)

Is there a registered entity class in self for the entity with the XML name name?

attrkey(xmlns, name)

Return the key that can be used to set the attribute with the name name and the namespace xmlns. If self (or one of the base pools) has any global attribute registered for that name/namespace, the attribute class will be returned. Otherwise the tuple (name, xmlns) (or name itself for a local attribute) will be returned. With this key Attrs.__setitem__() will create the appropriate attribute class.

text(content)

Create a text node with the content content.

comment(content)

Create a comment node with the content content.

ll.xist.xsc.docpool()

Return a pool suitable for parsing XIST docstrings.

ll.xist.xsc.nsname(xmlns)

If xmlns is a module, return xmlns.xmlns, else return xmlns unchanged.

ll.xist.xsc.nsclark(obj)

Return a name in Clark notation. xmlns can be None, a string or a module to return a namespace name, or a Node instance to return a namespace name + node name combination:

>>> from ll.xist import xsc
>>> from ll.xist.ns import html
>>> xsc.nsclark(None)
'{}'
>>> xsc.nsclark(html)
'{http://www.w3.org/1999/xhtml}'
>>> xsc.nsclark(html.a)
'{http://www.w3.org/1999/xhtml}a'
>>> xsc.nsclark(html.a())
'{http://www.w3.org/1999/xhtml}a'

class ll.xist.xsc.quot

Bases: CharRef

quotation mark = APL quote, U+0022 ISOnum

class ll.xist.xsc.amp

Bases: CharRef

ampersand, U+0026 ISOnum

class ll.xist.xsc.lt

Bases: CharRef

less-than sign, U+003C ISOnum

class ll.xist.xsc.gt

Bases: CharRef

greater-than sign, U+003E ISOnum

class ll.xist.xsc.apos

Bases: CharRef

apostrophe mark, U+0027 ISOnum

ll.xist.xsc.element(xmlns, xmlname, *content, **attrs)

Create a plain element object with the namespace name xmlns and the element name xmlname. This object will be an instance of Element (not an instance of a subclass). content and attrs will be used to initialize the content and attributes of the element.

ll.xist.xsc.entity(xmlname)

Create a plain entity object with the entity name xmlname. This object will be an instance of Entity (not an instance of a subclass).

ll.xist.xsc.procinst(xmlname, *content)

Create a plain processing instruction object with the target name xmlname. This object will be an instance of ProcInst (not an instance of a subclass). content will be used to initialize the content of the processing instruction.

class ll.xist.xsc.Location

Bases: object

Represents a location in an XML entity.

__init__(url=None, line=None, col=None)

Create a new Location object using the arguments passed in. url is the URL/filename. line is the line number and col is the column number (both starting at 0).

offset(offset)

Return a location where the line number is incremented by offset (and the column number is reset to 0).