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)[source]
Convert
value
to an XISTNode
.If
value
is a tuple or list, it will be (recursively) converted to aFrag
. Integers, strings, etc. will be converted to aText
. Ifvalue
is aNode
already, it will be returned unchanged. In the case ofNone
the XIST Null (ll.xist.xsc.Null
) will be returned. Ifvalue
is iterable, aFrag
will be generated from the items. Anything else will raise anIllegalObjectError
exception.
- class ll.xist.xsc.build[source]
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[source]
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")
- ll.xist.xsc.add(*args, **kwargs)[source]
add()
appends items inargs
and sets attributes inkwargs
in the currently active node in thewith
stack.
- class ll.xist.xsc.Context[source]
Bases:
object
This is an empty class that can be used by the
convert()
method to hold element or namespace specific data during theconvert()
call. The methodConverter.__getitem__()
will return a unique instance of this class.
- exception ll.xist.xsc.Warning[source]
Bases:
UserWarning
Base class for all warning exceptions (i.e. those that won’t result in a program termination.)
- exception ll.xist.xsc.IllegalAttrValueWarning[source]
Bases:
Warning
Warning that is issued when an attribute has an illegal value.
- exception ll.xist.xsc.RequiredAttrMissingWarning[source]
Bases:
Warning
Warning that is issued when a required attribute is missing.
- exception ll.xist.xsc.UndeclaredAttrWarning[source]
Bases:
Warning
Warning that is issued when a local attribute is not declared.
- exception ll.xist.xsc.UndeclaredNodeWarning[source]
Bases:
Warning
Warning that is issued when a node (i.e. element, entity or processing instruction) is not declared.
- exception ll.xist.xsc.IllegalPrefixError[source]
Bases:
Error
,LookupError
Exception that is raised when a namespace prefix is undefined.
- exception ll.xist.xsc.FileNotFoundWarning[source]
Bases:
Warning
Warning that is issued when a file can’t be found.
- exception ll.xist.xsc.IllegalObjectError[source]
-
Exception that is raised when an XIST constructor gets passed an unconvertable object.
- exception ll.xist.xsc.IllegalCommentContentWarning[source]
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[source]
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[source]
Bases:
object
An instance of this class is passed around in calls to the
convert()
method. AConverter
object can be used when some element needs to keep state across a nestedconvert()
call. A typical example are nested chapter/subchapter elements with automatic numbering. For an example see the elementll.xist.ns.doc.section
.- __init__(node=None, root=None, mode=None, stage=None, target=None, lang=None, makeaction=None, makeproject=None)[source]
Create a
Converter
. Arguments are used to initialize theConverter
properties of the same name.
- __getitem__(key)[source]
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 all.xist.xsc.Node
instance or subclass. Each of these classes that defines its ownContext
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 toconvert()
.
- class ll.xist.xsc.Publisher[source]
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=())[source]
Create a publisher. Arguments have the following meaning:
encoding
string orNone
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.xhtml
intWith 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/>
.
- HTML (
validate
boolSpecifies whether validation should be done before publishing.
prefixes
mappingA 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.
prefixdefault
string orNone
If an element or attribute is encountered whose namespace name is not in
prefixes
prefixdefault
is used as the fallback.hidexmlns
list or sethidexmlns
can be a list or set that contains namespace names for which noxmlns
attributes should be published. (This can be used to hide the namespace declarations for e.g. Java taglibs.)showxmlns
list or setshowxmlns
can be a list or set that contains namespace names for whichxmlns
attributes will be published, even if there are no elements from this namespace in the tree.
- encode(text)[source]
Encode
text
with the encoding and error handling currently active and return the resulting byte string.
- encodetext(text)[source]
Encode
test
as text data.text
must be astr
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 resultingstr
object.
- pushtextfilter(filter)[source]
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()[source]
Pops the current text filter function from the stack.
- pusherrors(errors)[source]
Pushes a new error handling scheme onto the error handling stack.
- poperrors()[source]
Pop the current error handling scheme from the error handling stack.
- getencoding()[source]
Return the encoding currently in effect.
- getnamespaceprefix(xmlns)[source]
Return (and register) a namespace prefix for the namespace name
xmlns
. This honors the namespace configuration fromself.prefixes
andself.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)[source]
Get and register a namespace prefix for the namespace
obj
lives in (specified by thexmlns
attribute ofobj
). Similar togetnamespaceprefix()
this honors the namespace configuration fromself.prefixes
andself.prefixdefault
(except when a global attribute requires a non-empty prefix).
- iterbytes(node, base=None, allowschemerelurls=False)[source]
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 URLbase
.Setting
allowschemerelurls
to true allow schema-relative URLs (e.g.//www.example.org/about.html
).
- bytes(node, base=None, allowschemerelurls=False)[source]
Return a
bytes
object in XML format for the XIST nodenode
.
- iterstring(node, base=None, allowschemerelurls=False)[source]
A generator that will produce a serialized string of
node
.
- string(node, base=None, allowschemerelurls=False)[source]
Return a string for
node
.
- write(stream, node, base=None, allowschemerelurls=False)[source]
Write
node
to the file-like objectstream
(which must provide awrite()
method).
- class ll.xist.xsc.Cursor[source]
Bases:
object
A
Cursor
object is used by thewalk()
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).
- 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
andpath[-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:
- 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 ifenterattrs
is true.
- leaveattrnode
Should the generator yield an
"leaveattrnode"
event (i.e. return after entering the content of an attribute)? This is only relevant ifenterattrs
is true. Furthermore ifenterattr
is false, the behaviour is essentially the same as forenterattrnode
.
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)[source]
Create a new
Cursor
object for a tree traversal rooted at the nodenode
.The arguments
entercontent
,enterattrs
,enterattr
,enterelementnode
,leaveelementnode
,enterattrnode
andleaveattrnode
are used as the initial values for the attributes of the same name. (see the class docstring for info about their use).
- restore()[source]
Restore the attributes
entercontent
,enterattrs
,enterattr
,enterelementnode
,leaveelementnode
,enterattrnode
andleaveattrnode
to their initial value.
- class ll.xist.xsc.Node[source]
Bases:
object
Base class for nodes in the document tree. Derived classes may overwrite
convert()
orpublish()
.- 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 theconvert()
call. The methodConverter.__getitem__()
will return a unique instance of this class.
- __truediv__(other)[source]
Return a
ChildCombinator
withself
as the left hand selector.
- __floordiv__(other)[source]
Return a
DescendantCombinator
withself
as the left hand selector.
- __mul__(other)[source]
If
other
is anint
, return aFrag
withother
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 anint
, treat this a CSS combinator that creates anAdjacentSiblingCombinator
withself
as the left hand selector.
- __pow__(other)[source]
Return a
GeneralSiblingCombinator
withself
as the left hand selector.
- __and__(other)[source]
Return an
AndCombinator
withself
as the left hand selector.
- __or__(other)[source]
Return an
OrCombinator
withself
as the left hand selector.
- clone()[source]
Return a clone of
self
. Compared todeepcopy()
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()[source]
Return a shallow copy of
self
.
- deepcopy()[source]
Return a deep copy of
self
.
- present(presenter)[source]
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)[source]
Convenience method for calling
convert()
.conv()
will automatically setconverter.node
toself
to remember the “document root node” for whichconv()
has been called. This means that you should not callconv()
in any of the recursive calls, as you would loose this information. Callconvert()
directly instead.
- convert(converter)[source]
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 changeself
.
- __str__()[source]
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
- asFloat(decimal='.', ignore='')[source]
Convert the character content of
self
to anfloat
.decimal
specifies which decimal separator is used in the value (e.g."."
(the default) or","
).ignore
specifies which characters will be ignored.
- parsed(parser, event)[source]
This method will be called by the parser
parser
once afterself
is created by the parser (This is used e.g. byURLAttr
to incorporate the base URL into the attribute).event
is the parser event that initiated the call.
- validate(recursive=True, path=None)[source]
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)[source]
Generate unicode strings for the node.
publisher
must be an instance ofPublisher
.The encoding and xhtml specification are taken from the
publisher
.
- iterbytes(base=None, allowschemerelurls=False, publisher=None, **publishargs)[source]
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 itsiterbytes()
method.
- bytes(base=None, allowschemerelurls=False, publisher=None, **publishargs)[source]
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)[source]
A generator that will produce a serialized string of
self
(i.e. it will output what the methodstring()
outputs, but incremetally).For the possible parameters see the
Publisher
constructor.
- string(base=None, allowschemerelurls=False, publisher=None, **publishargs)[source]
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)[source]
Write
self
to the file-like objectstream
(which must provide awrite()
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)[source]
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 argumentsentercontent
,enterattrs
,enterattr
,enterelementnode
,leaveelementnode
,enterattrnode
andleaveattrnode
specify how the tree should be traversed. For more information see theCursor
class.Note that the
Cursor
object is reused bywalk()
, so you can’t rely on any attributes remaining the same across calls tonext()
.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)[source]
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)[source]
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()[source]
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)[source]
Return the node mapped through the function
function
. This call works recursively (forFrag
andElement
).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 fromfunction
this node will be incorporated into the result as-is.
- normalized()[source]
Return a normalized version of
self
, which means that consecutiveText
nodes are merged.
- pretty(level=0, indent='\t')[source]
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()
andcompacted()
before callingpretty()
to remove whitespace.
- class ll.xist.xsc.CharacterData[source]
Bases:
Node
Base class for XML character data (
Text
,ProcInst
,Comment
andDocType
).(Provides nearly the same functionality as
UserString
, but omits a few methods.)
- class ll.xist.xsc.Text[source]
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[source]
-
A fragment contains a list of nodes and can be used for dynamically constructing content. The attribute
content
of anElement
is aFrag
.- clear()[source]
Make
self
empty.
- __getitem__(index)[source]
Return the
index
’th node of the content of the fragment. Ifindex
is a list__getitem__()
will work recursively. Ifindex
is an empty list,self
will be returned.__getitem__()
also supports selectors (i.e.xfind.Selector
objects).
- __setitem__(index, value)[source]
Allows you to replace the
index
’th content node of the fragment with the new valuevalue
(which will be converted to a node). Ifindex
is a list__setitem__()
will be applied to the innermost index after traversing the rest ofindex
recursively. Ifindex
is an empty list, an exception will be raised.__setitem__()
also supports selectors (i.e.xfind.Selector
objects).
- __delitem__(index)[source]
Remove the
index
’th content node from the fragment. Ifindex
is a list, the innermost index will be deleted, after traversing the rest ofindex
recursively. Ifindex
is an empty list, an exception will be raised. Anything exceptlist
,int
andslice
objects will be turned into a selector (i.e. anxfind.Selector
objects) and any child node matching this selector will be deleted fromself
.
- __mul__(factor)[source]
Return a
Frag
withfactor
times the content ofself
. Note that no copies of the content will be generated, so this is a “shallow__mul__()
”.
- __rmul__(factor)
Return a
Frag
withfactor
times the content ofself
. Note that no copies of the content will be generated, so this is a “shallow__mul__()
”.
- append(*others)[source]
Append every item in
others
toself
.
- extend(items)[source]
Append all items from the sequence
items
toself
.
- insert(index, *others)[source]
Insert all items in
others
at the positionindex
. (this is the same asself[index:index] = others
)
- withsep(separator, clone=False)[source]
Return a version of
self
with a separator node between the nodes ofself
.if
clone
is false, one node will be inserted several times, ifclone
is true, clones of this node will be used.
- reversed()[source]
Return a reversed version of the
self
.
- filtered(function)[source]
Return a filtered version of the
self
, i.e. a copy ofself
, where only content nodes for whichfunction
returns true will be copied.
- shuffled()[source]
Return a shuffled version of
self
, i.e. a copy ofself
where the content nodes are randomly reshuffled.
- class ll.xist.xsc.Comment[source]
Bases:
CharacterData
An XML comment.
- class ll.xist.xsc.DocType[source]
Bases:
CharacterData
An XML document type declaration.
- class ll.xist.xsc.ProcInst[source]
Bases:
CharacterData
Base class for processing instructions.
Processing instructions for specific targets must be implemented as subclasses of
ProcInst
.
- class ll.xist.xsc.Attr[source]
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'?>" />
- validate(recursive=True, path=None)[source]
Check whether
self
has an allowed value, i.e. one that is specified in the class attributevalues
. 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[source]
Bases:
Attr
Attribute class that is used for normal text attributes.
- class ll.xist.xsc.NumberAttr[source]
Bases:
Attr
Attribute class that is used for when the attribute value may be any kind of number.
- class ll.xist.xsc.IntAttr[source]
Bases:
NumberAttr
Attribute class that is used when the attribute value may be an integer.
- class ll.xist.xsc.FloatAttr[source]
Bases:
NumberAttr
Attribute class that is used when the attribute value may be a floating point value.
- class ll.xist.xsc.BoolAttr[source]
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[source]
Bases:
Attr
Attribute class that is used for a color attributes.
- class ll.xist.xsc.StyleAttr[source]
Bases:
Attr
Attribute class that is used for CSS style attributes.
- replaceurls(replacer)[source]
Replace each URL in the style. Each URL will be passed to the callable
replacer
and replaced with the returned value.
- urls(base=None)[source]
Return a list of all the URLs (as
URL
objects) found in the style attribute.
- class ll.xist.xsc.URLAttr[source]
Bases:
Attr
Attribute class that is used for URLs. See the module
ll.url
for more information about URL handling.- forInput(root=None)[source]
return a
URL
pointing to the real location of the referenced resource.root
must be the root URL relative to whichself
will be interpreted and usually comes from theroot
attribute of theconverter
argument inconvert()
.
- imagesize(root=None)[source]
Return the size of an image as a tuple.
- contentlength(root=None)[source]
Return the size of a file in bytes.
- lastmodified(root=None)[source]
returns the timestamp for the last modification to the file
- openread(root=None)[source]
Return a
Resource
for reading from the URL.
- openwrite(root=None)[source]
Return a
Resource
for writing to the URL.
- class ll.xist.xsc.Attrs[source]
-
An attribute map. Predefined attributes can be declared through nested subclasses of
Attr
.- __getitem__(name)[source]
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)[source]
Set the attribute with the XML
name
to the valuevalue
.name
may be a string or an attribute class or instance. The newly set attribute object will be returned.
- __delitem__(name)[source]
- get(name, default=None)[source]
Works like the dictionary method
get()
, it returns the attribute with the XML namename
, ordefault
ifself
has no such attribute.name
may also be an attribute class (either fromself.Attrs
or a global attribute).
- setdefault(name, default)[source]
Works like the dictionary method
setdefault()
, it returns the attribute with the Python namename
. Ifself
has no such attribute, it will be set todefault
anddefault
will be returned as the new attribute value.
- update(*args, **kwargs)[source]
Copies attributes over from all mappings in
args
and fromkwargs
. Keywords are treated as the Python names of attributes.
- classmethod declaredattrs()[source]
Return an iterator over all declared attribute classes.
- filtered(function)[source]
Return a filtered version of
self
.
- withnames(*names)[source]
Return a copy of
self
where only the attributes with XML names innames
are kept, all others are removed.
- withoutnames(*names)[source]
Return a copy of
self
where all the attributes with XML names innames
are removed.
- class ll.xist.xsc.Element[source]
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:
model
object withvalidate()
methodThis is an object that is used for validating the content of the element. See the module
ll.xist.sims
for more info. Ifmodel
isNone
validation will be skipped, otherwise it will be performed when parsing or publishing.Attrs
Element.Attrs
subclassThis is a class derived from
Element.Attrs
and must define all attributes as classes nested inside thisAttrs
class.xmlns
stringThis is the name of the namespace this element belong to.
register
boolIf
register
is false the element will never be registered in aPool
. The default isTrue
.xmlname
stringIf 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
-
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 valuevalue
.name
may be a string or an attribute class or instance. The newly set attribute object will be returned.
- get(name, default=None)
Works like the dictionary method
get()
, it returns the attribute with the XML namename
, ordefault
ifself
has no such attribute.name
may also be an attribute class (either fromself.Attrs
or a global attribute).
- setdefault(name, default)
Works like the dictionary method
setdefault()
, it returns the attribute with the Python namename
. Ifself
has no such attribute, it will be set todefault
anddefault
will be returned as the new attribute value.
- update(*args, **kwargs)
Copies attributes over from all mappings in
args
and fromkwargs
. Keywords are treated as the Python names of attributes.
- __init__(*content, **attrs)[source]
Create a new
Element
instance.Positional arguments are treated as content nodes. Keyword arguments and dictionaries are treated as attributes.
- __enter__()[source]
Element
nodes can be used inwith
blocks to build XIST trees. Inside awith
block+
andadd()
can be used to append node to the currently active element in thewith
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)[source]
Calling an element add items in
content
to the element content and set attributes fromattrs
. The element itself will be returned.
- append(*items)[source]
Append every item in
items
to the elements content.
- extend(items)[source]
Append all items in
items
to the elements content.
- insert(index, *items)[source]
Insert every item in
items
at the positionindex
.
- __getitem__(index)[source]
If
index
is a string, return the attribute with this (Python) name. Ifindex
is an attribute class, return the attribute that is an instance of this class. Ifindex
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)[source]
Set an attribute or content node to the value
value
. For possible types forindex
see__getitem__()
.
- __delitem__(index)[source]
Remove an attribute or content node. For possible types for
index
see__getitem__()
.
- __len__()[source]
Return the number of children.
- withsep(separator, clone=False)[source]
Return a version of
self
with a separator node between the child nodes ofself
. For more info seeFrag.withsep()
.
- reversed()[source]
Return a reversed version of
self
.
- filtered(function)[source]
Return a filtered version of the
self
.
- shuffled()[source]
Return a shuffled version of the
self
.
- class ll.xist.xsc.AttrElement[source]
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 methodspublishattr()
andpublishboolattr()
). In all other cases publishing is done in the normal way (and must be overwritten with thepublish()
method).- publish(publisher)[source]
Publish
self
to the publisherpublisher
(outside of any attribute)
- publishattr(publisher, attr)[source]
Publish the attribute
attr
to the publisherpublisher
.
- publishboolattr(publisher, attr)[source]
Publish the boolean attribute
attr
to the publisher
- class ll.xist.xsc.Entity[source]
Bases:
Node
Class for entities. Derive your own entities from it and overwrite
convert()
.
- class ll.xist.xsc.CharRef[source]
-
A simple named character reference, the code point is in the class attribute
codepoint
.
- class ll.xist.xsc.Pool[source]
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)[source]
Create a
Pool
object. All items inobjects
will be registered in the pool.
- register(object)[source]
Register
object
in the pool.object
can be:
- clear()[source]
Make
self
empty.
- clone()[source]
Return a copy of
self
.
- elements()[source]
Return an iterator for all registered element classes.
- elementclass(xmlns, name)[source]
Return the element class for the element with the XML name
name
and the namespacexmlns
. If the element can’t be found anElement
will be returned.
- element(xmlns, name)[source]
Return an element object for the element type with the XML name
name
and the namespacexmlns
.
- haselement(xmlns, name)[source]
Is there a registered element class in
self
for the element type with the Python namename
and the namespacexmlns
?
- procinsts()[source]
Return an iterator for all registered processing instruction classes.
- procinstclass(name)[source]
Return the processing instruction class for the PI with the target name
name
. If the processing instruction can’t be found an returnProcInst
.
- procinst(name, content)[source]
Return a processing instruction object for the PI type with the target name
name
.
- hasprocinst(name)[source]
Is there a registered processing instruction class in
self
for the PI with the target namename
?
- entities()[source]
Return an iterator for all registered entity classes.
- entityclass(name)[source]
Return the entity class for the entity with the XML name
name
. If the entity can’t be found returnEntity
.
- entity(name)[source]
Return an entity object for the entity with the XML name
name
.
- hasentity(name)[source]
Is there a registered entity class in
self
for the entity with the XML namename
?
- attrkey(xmlns, name)[source]
Return the key that can be used to set the attribute with the name
name
and the namespacexmlns
. Ifself
(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)
(orname
itself for a local attribute) will be returned. With this keyAttrs.__setitem__()
will create the appropriate attribute class.
- text(content)[source]
Create a text node with the content
content
.
- comment(content)[source]
Create a comment node with the content
content
.
- ll.xist.xsc.docpool()[source]
Return a pool suitable for parsing XIST docstrings.
- ll.xist.xsc.nsname(xmlns)[source]
If
xmlns
is a module, returnxmlns.xmlns
, else returnxmlns
unchanged.
- ll.xist.xsc.nsclark(obj)[source]
Return a name in Clark notation.
xmlns
can beNone
, a string or a module to return a namespace name, or aNode
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'
- ll.xist.xsc.element(xmlns, xmlname, *content, **attrs)[source]
Create a plain element object with the namespace name
xmlns
and the element namexmlname
. This object will be an instance ofElement
(not an instance of a subclass).content
andattrs
will be used to initialize the content and attributes of the element.
- ll.xist.xsc.entity(xmlname)[source]
Create a plain entity object with the entity name
xmlname
. This object will be an instance ofEntity
(not an instance of a subclass).
- ll.xist.xsc.procinst(xmlname, *content)[source]
Create a plain processing instruction object with the target name
xmlname
. This object will be an instance ofProcInst
(not an instance of a subclass).content
will be used to initialize the content of the processing instruction.
- class ll.xist.xsc.Location[source]
Bases:
object
Represents a location in an XML entity.
- __init__(url=None, line=None, col=None)[source]
Create a new
Location
object using the arguments passed in.url
is the URL/filename.line
is the line number andcol
is the column number (both starting at 0).
- offset(offset)[source]
Return a location where the line number is incremented by offset (and the column number is reset to 0).